falsealpha 0.1.0__tar.gz → 0.2.1__tar.gz

{falsealpha-0.1.0 → falsealpha-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: falsealpha
-Version: 0.1.0
+Version: 0.2.1
 Summary: A C++ alpha-mining engine that searches formulaic trading signals, then tells you which of its discoveries are fake.
 Keywords: quant,alpha,genetic-programming,backtesting,overfitting,deflated-sharpe
 Author: Owen Alderson
@@ -22,6 +22,7 @@ Description-Content-Type: text/markdown
 # falsealpha
 
 [![CI](https://github.com/owen-alderson/falsealpha/actions/workflows/ci.yml/badge.svg)](https://github.com/owen-alderson/falsealpha/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/falsealpha.svg)](https://pypi.org/project/falsealpha/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
 **A C++ engine that searches thousands of formulaic trading signals, then tells you which of its own discoveries are fake.**
@@ -35,6 +36,7 @@ $ falsealpha data noise --out noise.npz          # 2,500 days x 60 assets of pur
 $ falsealpha mine noise.npz runs/noise
 6002 formulas tried -> 50 finalists -> 0 survivors
   luck bar (train): best of 6002 unskilled strategies ~ Sharpe +1.84 /yr
+  trial clusters: ~709 independent bets -> luck bar +1.56 /yr (reported; the gate counts every formula)
   Reality Check p 0.942 (gate)   SPA p 0.800
   PBO 0.95  (share of splits where the in-sample best finalist lands in the bottom half)
 
@@ -42,6 +44,7 @@ $ falsealpha data planted --out planted.npz      # same, plus one hidden alpha
 $ falsealpha mine planted.npz runs/planted
 6397 formulas tried -> 50 finalists -> 3 survivors
   luck bar (train): best of 6397 unskilled strategies ~ Sharpe +1.85 /yr
+  trial clusters: ~667 independent bets -> luck bar +1.55 /yr (reported; the gate counts every formula)
   Reality Check p 0.000 (gate)   SPA p 0.000
   PBO 0.00  (share of splits where the in-sample best finalist lands in the bottom half)
   [PASS] train +5.87 (DSR 1.00)  val +4.94 (DSR 1.00)  (decay_linear(ts_sum(volume, 3), 5) * ts_sum(volume, 5))
@@ -49,7 +52,7 @@ $ falsealpha unseal runs/planted
 combined: holdout Sharpe +4.08 /yr, P(true Sharpe > 0) 1.00, 498 days
 ```
 
-Across 30 independent noise panels (1,500 days × 60 assets, population 200 × 6 generations; [`scripts/noise_calibration.py`](scripts/noise_calibration.py)), the firewall let through **0** formulas. The Reality Check gate never opened (0 of 30); the Deflated Sharpe alone would also have caught everything. Mean PBO was 0.49, a coin flip, which is what overfitting to noise looks like.
+Across 30 independent noise panels (1,500 days × 60 assets, population 200 × 6 generations; [`scripts/noise_calibration.py`](scripts/noise_calibration.py)), the firewall let through **0** formulas. The Reality Check gate never opened (0 of 30); the Deflated Sharpe alone would also have caught everything, even counting only the trial clusters as independent bets (0 of 30 runs had a finalist reach a train DSR of 0.95 either way). Mean PBO was 0.49, a coin flip, which is what overfitting to noise looks like.
 
 ## On real data: six years of crypto
 
@@ -60,6 +63,7 @@ $ falsealpha data binance --out data/binance-top100.npz
 $ falsealpha mine data/binance-top100.npz runs/crypto        # 45 s on an M3 Pro
 7376 formulas tried -> 50 finalists -> 0 survivors
   luck bar (train): best of 7376 unskilled strategies ~ Sharpe +1.88 /yr
+  trial clusters: ~1197 independent bets -> luck bar +1.64 /yr (reported; the gate counts every formula)
   Reality Check p 0.475 (gate)   SPA p 0.185
   PBO 0.73  (share of splits where the in-sample best finalist lands in the bottom half)
   [fail] train +2.06 (DSR 0.64)  val -1.08 (DSR 0.00)  min(((quote_volume / ts_mean(ts_delta(open, 20), 5)) - high), -ts_sum(trades, 10))
@@ -67,7 +71,7 @@ $ falsealpha mine data/binance-top100.npz runs/crypto        # 45 s on an M3 Pro
   [fail] train +1.86 (DSR 0.48)  val +1.02 (DSR 0.14)  ts_sum((-trades * ts_cov(close, quote_volume, 10)), 40)
 ```
 
-The best formula the search found earns a Sharpe of +2.06 a year over four years of training data, after costs. Shown alone, that is a backtest people trade. The firewall rejects it on the training data already: 7,376 tries at nothing would be expected to produce about +1.88 by luck, so its Deflated Sharpe is only 0.64. On the next 16 months, which the search never saw, it loses money (−1.08 a year), and so does the runner-up (−1.79). The few finalists that stay positive out of sample (+1.02 at best) are well within what luck explains over 493 days (Reality Check p = 0.48), and PBO is 0.73: picking the in-sample best finalist usually picks a below-median one.
+The best formula the search found earns a Sharpe of +2.06 a year over four years of training data, after costs. Shown alone, that is a backtest people trade. The firewall rejects it on the training data already: 7,376 tries at nothing would be expected to produce about +1.88 by luck, so its Deflated Sharpe is only 0.64. Many of those tries are near-copies of each other; grouping them (|corr| > 0.7) leaves about 1,197 independent bets, a luck bar of +1.64, and a Deflated Sharpe of 0.80: still a fail, so the verdict does not rest on the conservative count. On the next 16 months, which the search never saw, it loses money (−1.08 a year), and so does the runner-up (−1.79). The few finalists that stay positive out of sample (+1.02 at best) are well within what luck explains over 493 days (Reality Check p = 0.48), and PBO is 0.73: picking the in-sample best finalist usually picks a below-median one.
 
 So the honest result of this run is **no tradable alpha**, and the holdout (May 2025 to September 2026) stays sealed for a better search. That is the tool working: it is built to say "no" when the evidence is not there.
 
@@ -88,7 +92,7 @@ So the honest result of this run is **no tradable alpha**, and the holdout (May
 ```
 
 1. **Search.** Genetic programming over an Alpha101-style formula language: ramped half-and-half initialisation, subtree crossover, point / subtree / hoist mutation, tournament selection, a parsimony penalty, and a novelty penalty against a hall of fame so it keeps finding *different* signals rather than near-copies (|corr| ≤ 0.7 between finalists). Fitness is the net long-short Sharpe on the train period only.
-2. **Ledger.** Every distinct formula the search scores is written to `ledger.csv.gz` (formulas are canonicalised, so `a + b` and `b + a` count once). This is the *N* in the multiple-testing correction, not just the winners.
+2. **Ledger.** Every distinct formula the search scores is written to `ledger.csv.gz` (formulas are canonicalised, so `a + b` and `b + a` count once). This is the *N* in the multiple-testing correction, not just the winners. Each formula is also assigned to a **trial cluster**: it joins the first cluster whose leader's train returns it matches with |corr| > 0.7, or leads a new one. The number of clusters estimates how many *independent* bets the search made.
 3. **Firewall.** A finalist survives only if it passes all of:
    - **Train Deflated Sharpe ≥ 0.95** ([Bailey & López de Prado 2014](https://papers.ssrn.com/abstract=2460551)): the train Sharpe must beat the expected maximum of *N* unskilled strategies, where *N* is the whole ledger.
    - **Validation Sharpe > 0 with Deflated Sharpe ≥ 0.95**, deflated for the number of finalists scored on the unseen validation days.
@@ -96,7 +100,7 @@ So the honest result of this run is **no tradable alpha**, and the holdout (May
    - **PBO** ([Bailey, Borwein, López de Prado & Zhu 2017](https://papers.ssrn.com/abstract=2326253)) is reported, computed over the finalists' train + validation returns: combinatorially symmetric cross-validation over 16 blocks (12,870 splits), the share where the in-sample best finalist lands in the bottom half out of sample.
 4. **Holdout.** The search and validation never receive the holdout days: the panel is physically truncated before they run. `falsealpha unseal` scores the survivors and their equal-risk combination on the holdout once; a second look needs `--force`, and the report shows every look.
 
-**One deliberate deviation from the DSR paper.** The paper sets the luck bar from the variance of Sharpe ratios *across* trials. In a search that finds something real, dozens of variants of that signal inflate that variance and the test ends up punishing the discovery (on the planted data it rejects a true signal with a Sharpe of 9). falsealpha uses the null variance, 1/(T−1): the expected best of *N* strategies with no skill. Counting every distinct formula as a trial overstates the number of independent trials, so the bar is conservative. The paper's version is still computed and stored (`sr0_train_paper`).
+**One deliberate deviation from the DSR paper.** The paper sets the luck bar from the variance of Sharpe ratios *across* trials. In a search that finds something real, dozens of variants of that signal inflate that variance and the test ends up punishing the discovery (on the planted data it rejects a true signal with a Sharpe of 9). falsealpha uses the null variance, 1/(T−1): the expected best of *N* strategies with no skill. Counting every distinct formula as a trial overstates the number of independent trials, so the bar is conservative; the run reports how much by also deflating against the trial clusters (`n_effective`, `dsr_effective`, the "DSR vs clusters" column in the report), and the gate keeps the conservative count. The paper's version is still computed and stored (`sr0_train_paper`).
 
 ## Quick start
 
@@ -225,4 +229,12 @@ cmake -S . -B build -DFALSEALPHA_BUILD_TESTS=ON && cmake --build build -j && ./b
 - C. R. Harvey, Y. Liu, H. Zhu (2016). …and the Cross-Section of Expected Returns. *Review of Financial Studies* 29(1).
 - Z. Kakushadze (2016). 101 Formulaic Alphas. *Wilmott* 2016(84). [arXiv:1601.00991](https://arxiv.org/abs/1601.00991)
 
-MIT licence.
+## Disclaimer
+
+Research software, not investment advice. Backtested results do not predict future returns. falsealpha is not affiliated with or endorsed by Binance.
+
+## Data and licences
+
+`falsealpha data binance` downloads Binance's public historical data from [Binance Vision](https://data.binance.vision) to your own machine. Binance licenses that data under [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/) with its own [dataset terms](https://data.binance.vision/Binance_Vision-Terms_of_Use.pdf): non-commercial use only, and anything you publish from it must credit Binance Vision and carry the same licence.
+
+The results in this README and `docs/report.png` are derived from Binance Vision data, so they are licensed CC BY-NC-SA 4.0, with credit to Binance Vision. The code is MIT.

{falsealpha-0.1.0 → falsealpha-0.2.1}/README.md

@@ -1,6 +1,7 @@
 # falsealpha
 
 [![CI](https://github.com/owen-alderson/falsealpha/actions/workflows/ci.yml/badge.svg)](https://github.com/owen-alderson/falsealpha/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/falsealpha.svg)](https://pypi.org/project/falsealpha/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
 **A C++ engine that searches thousands of formulaic trading signals, then tells you which of its own discoveries are fake.**
@@ -14,6 +15,7 @@ $ falsealpha data noise --out noise.npz          # 2,500 days x 60 assets of pur
 $ falsealpha mine noise.npz runs/noise
 6002 formulas tried -> 50 finalists -> 0 survivors
   luck bar (train): best of 6002 unskilled strategies ~ Sharpe +1.84 /yr
+  trial clusters: ~709 independent bets -> luck bar +1.56 /yr (reported; the gate counts every formula)
   Reality Check p 0.942 (gate)   SPA p 0.800
   PBO 0.95  (share of splits where the in-sample best finalist lands in the bottom half)
 
@@ -21,6 +23,7 @@ $ falsealpha data planted --out planted.npz      # same, plus one hidden alpha
 $ falsealpha mine planted.npz runs/planted
 6397 formulas tried -> 50 finalists -> 3 survivors
   luck bar (train): best of 6397 unskilled strategies ~ Sharpe +1.85 /yr
+  trial clusters: ~667 independent bets -> luck bar +1.55 /yr (reported; the gate counts every formula)
   Reality Check p 0.000 (gate)   SPA p 0.000
   PBO 0.00  (share of splits where the in-sample best finalist lands in the bottom half)
   [PASS] train +5.87 (DSR 1.00)  val +4.94 (DSR 1.00)  (decay_linear(ts_sum(volume, 3), 5) * ts_sum(volume, 5))
@@ -28,7 +31,7 @@ $ falsealpha unseal runs/planted
 combined: holdout Sharpe +4.08 /yr, P(true Sharpe > 0) 1.00, 498 days
 ```
 
-Across 30 independent noise panels (1,500 days × 60 assets, population 200 × 6 generations; [`scripts/noise_calibration.py`](scripts/noise_calibration.py)), the firewall let through **0** formulas. The Reality Check gate never opened (0 of 30); the Deflated Sharpe alone would also have caught everything. Mean PBO was 0.49, a coin flip, which is what overfitting to noise looks like.
+Across 30 independent noise panels (1,500 days × 60 assets, population 200 × 6 generations; [`scripts/noise_calibration.py`](scripts/noise_calibration.py)), the firewall let through **0** formulas. The Reality Check gate never opened (0 of 30); the Deflated Sharpe alone would also have caught everything, even counting only the trial clusters as independent bets (0 of 30 runs had a finalist reach a train DSR of 0.95 either way). Mean PBO was 0.49, a coin flip, which is what overfitting to noise looks like.
 
 ## On real data: six years of crypto
 
@@ -39,6 +42,7 @@ $ falsealpha data binance --out data/binance-top100.npz
 $ falsealpha mine data/binance-top100.npz runs/crypto        # 45 s on an M3 Pro
 7376 formulas tried -> 50 finalists -> 0 survivors
   luck bar (train): best of 7376 unskilled strategies ~ Sharpe +1.88 /yr
+  trial clusters: ~1197 independent bets -> luck bar +1.64 /yr (reported; the gate counts every formula)
   Reality Check p 0.475 (gate)   SPA p 0.185
   PBO 0.73  (share of splits where the in-sample best finalist lands in the bottom half)
   [fail] train +2.06 (DSR 0.64)  val -1.08 (DSR 0.00)  min(((quote_volume / ts_mean(ts_delta(open, 20), 5)) - high), -ts_sum(trades, 10))
@@ -46,7 +50,7 @@ $ falsealpha mine data/binance-top100.npz runs/crypto        # 45 s on an M3 Pro
   [fail] train +1.86 (DSR 0.48)  val +1.02 (DSR 0.14)  ts_sum((-trades * ts_cov(close, quote_volume, 10)), 40)
 ```
 
-The best formula the search found earns a Sharpe of +2.06 a year over four years of training data, after costs. Shown alone, that is a backtest people trade. The firewall rejects it on the training data already: 7,376 tries at nothing would be expected to produce about +1.88 by luck, so its Deflated Sharpe is only 0.64. On the next 16 months, which the search never saw, it loses money (−1.08 a year), and so does the runner-up (−1.79). The few finalists that stay positive out of sample (+1.02 at best) are well within what luck explains over 493 days (Reality Check p = 0.48), and PBO is 0.73: picking the in-sample best finalist usually picks a below-median one.
+The best formula the search found earns a Sharpe of +2.06 a year over four years of training data, after costs. Shown alone, that is a backtest people trade. The firewall rejects it on the training data already: 7,376 tries at nothing would be expected to produce about +1.88 by luck, so its Deflated Sharpe is only 0.64. Many of those tries are near-copies of each other; grouping them (|corr| > 0.7) leaves about 1,197 independent bets, a luck bar of +1.64, and a Deflated Sharpe of 0.80: still a fail, so the verdict does not rest on the conservative count. On the next 16 months, which the search never saw, it loses money (−1.08 a year), and so does the runner-up (−1.79). The few finalists that stay positive out of sample (+1.02 at best) are well within what luck explains over 493 days (Reality Check p = 0.48), and PBO is 0.73: picking the in-sample best finalist usually picks a below-median one.
 
 So the honest result of this run is **no tradable alpha**, and the holdout (May 2025 to September 2026) stays sealed for a better search. That is the tool working: it is built to say "no" when the evidence is not there.
 
@@ -67,7 +71,7 @@ So the honest result of this run is **no tradable alpha**, and the holdout (May
 ```
 
 1. **Search.** Genetic programming over an Alpha101-style formula language: ramped half-and-half initialisation, subtree crossover, point / subtree / hoist mutation, tournament selection, a parsimony penalty, and a novelty penalty against a hall of fame so it keeps finding *different* signals rather than near-copies (|corr| ≤ 0.7 between finalists). Fitness is the net long-short Sharpe on the train period only.
-2. **Ledger.** Every distinct formula the search scores is written to `ledger.csv.gz` (formulas are canonicalised, so `a + b` and `b + a` count once). This is the *N* in the multiple-testing correction, not just the winners.
+2. **Ledger.** Every distinct formula the search scores is written to `ledger.csv.gz` (formulas are canonicalised, so `a + b` and `b + a` count once). This is the *N* in the multiple-testing correction, not just the winners. Each formula is also assigned to a **trial cluster**: it joins the first cluster whose leader's train returns it matches with |corr| > 0.7, or leads a new one. The number of clusters estimates how many *independent* bets the search made.
 3. **Firewall.** A finalist survives only if it passes all of:
    - **Train Deflated Sharpe ≥ 0.95** ([Bailey & López de Prado 2014](https://papers.ssrn.com/abstract=2460551)): the train Sharpe must beat the expected maximum of *N* unskilled strategies, where *N* is the whole ledger.
    - **Validation Sharpe > 0 with Deflated Sharpe ≥ 0.95**, deflated for the number of finalists scored on the unseen validation days.
@@ -75,7 +79,7 @@ So the honest result of this run is **no tradable alpha**, and the holdout (May
    - **PBO** ([Bailey, Borwein, López de Prado & Zhu 2017](https://papers.ssrn.com/abstract=2326253)) is reported, computed over the finalists' train + validation returns: combinatorially symmetric cross-validation over 16 blocks (12,870 splits), the share where the in-sample best finalist lands in the bottom half out of sample.
 4. **Holdout.** The search and validation never receive the holdout days: the panel is physically truncated before they run. `falsealpha unseal` scores the survivors and their equal-risk combination on the holdout once; a second look needs `--force`, and the report shows every look.
 
-**One deliberate deviation from the DSR paper.** The paper sets the luck bar from the variance of Sharpe ratios *across* trials. In a search that finds something real, dozens of variants of that signal inflate that variance and the test ends up punishing the discovery (on the planted data it rejects a true signal with a Sharpe of 9). falsealpha uses the null variance, 1/(T−1): the expected best of *N* strategies with no skill. Counting every distinct formula as a trial overstates the number of independent trials, so the bar is conservative. The paper's version is still computed and stored (`sr0_train_paper`).
+**One deliberate deviation from the DSR paper.** The paper sets the luck bar from the variance of Sharpe ratios *across* trials. In a search that finds something real, dozens of variants of that signal inflate that variance and the test ends up punishing the discovery (on the planted data it rejects a true signal with a Sharpe of 9). falsealpha uses the null variance, 1/(T−1): the expected best of *N* strategies with no skill. Counting every distinct formula as a trial overstates the number of independent trials, so the bar is conservative; the run reports how much by also deflating against the trial clusters (`n_effective`, `dsr_effective`, the "DSR vs clusters" column in the report), and the gate keeps the conservative count. The paper's version is still computed and stored (`sr0_train_paper`).
 
 ## Quick start
 
@@ -204,4 +208,12 @@ cmake -S . -B build -DFALSEALPHA_BUILD_TESTS=ON && cmake --build build -j && ./b
 - C. R. Harvey, Y. Liu, H. Zhu (2016). …and the Cross-Section of Expected Returns. *Review of Financial Studies* 29(1).
 - Z. Kakushadze (2016). 101 Formulaic Alphas. *Wilmott* 2016(84). [arXiv:1601.00991](https://arxiv.org/abs/1601.00991)
 
-MIT licence.
+## Disclaimer
+
+Research software, not investment advice. Backtested results do not predict future returns. falsealpha is not affiliated with or endorsed by Binance.
+
+## Data and licences
+
+`falsealpha data binance` downloads Binance's public historical data from [Binance Vision](https://data.binance.vision) to your own machine. Binance licenses that data under [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/) with its own [dataset terms](https://data.binance.vision/Binance_Vision-Terms_of_Use.pdf): non-commercial use only, and anything you publish from it must credit Binance Vision and carry the same licence.
+
+The results in this README and `docs/report.png` are derived from Binance Vision data, so they are licensed CC BY-NC-SA 4.0, with credit to Binance Vision. The code is MIT.

{falsealpha-0.1.0 → falsealpha-0.2.1}/cpp/include/falsealpha/gp.hpp

@@ -25,7 +25,7 @@ struct SearchConfig {
     std::size_t train_begin = 0, train_end = 0;  // fitness is measured on days [begin, end)
     ScoreConfig score;
     double parsimony = 0.0005;  // per node, in per-period Sharpe units
-    double max_corr = 0.7;      // above this |corr| with a better hall member a formula is a near-copy
+    double max_corr = 0.7;      // above this |corr| a formula is a near-copy (hall of fame, trial clusters)
     int hall_size = 50;
     std::uint64_t seed = 1;
     int threads = 0;            // 0 = all cores
@@ -33,10 +33,15 @@ struct SearchConfig {
 
 // One row of the trial ledger: every distinct formula the search ever scored.
 // The Deflated Sharpe Ratio needs all of them, not just the winners.
+// Near-copies are not independent trials, so trials are also clustered by
+// their train returns: a trial joins the first cluster whose leader it
+// matches with |corr| > max_corr, or leads a new one. The number of clusters
+// estimates the number of independent trials.
 struct Trial {
     std::string formula;
     double sharpe = 0, mean_ic = 0, turnover = 0;  // train window, per period; NaN if degenerate
     int size = 0, generation = 0;
+    int cluster = -1;  // -1 if degenerate
 };
 
 struct Finalist {

{falsealpha-0.1.0 → falsealpha-0.2.1}/cpp/src/bindings.cpp

@@ -171,13 +171,15 @@ PYBIND11_MODULE(_core, m) {
         py::dict ledger;
         std::vector<std::string> formula;
         std::vector<double> sharpe, ic, turnover;
-        std::vector<int> size, gen;
+        std::vector<int> size, gen, cluster;
         for (const auto& t : r.ledger) {
             formula.push_back(t.formula); sharpe.push_back(t.sharpe); ic.push_back(t.mean_ic);
             turnover.push_back(t.turnover); size.push_back(t.size); gen.push_back(t.generation);
+            cluster.push_back(t.cluster);
         }
         ledger["formula"] = formula; ledger["sharpe"] = to_array(sharpe); ledger["mean_ic"] = to_array(ic);
         ledger["turnover"] = to_array(turnover); ledger["size"] = size; ledger["generation"] = gen;
+        ledger["cluster"] = cluster;
         py::list hall;
         for (const auto& f : r.hall)
             hall.append(py::dict(py::arg("formula") = f.formula, py::arg("fitness") = f.fitness,

{falsealpha-0.1.0 → falsealpha-0.2.1}/cpp/src/gp.cpp

@@ -117,8 +117,47 @@ struct Scored {
     Summary train;
     std::vector<double> net;
     std::vector<double> hall_corr;  // |corr| with each hall member as of the start of this generation
+    std::vector<float> unit;        // train returns, demeaned, unit length (NaN days = mean)
+    int cluster = -1;
 };
 
+// Train returns as a demeaned unit vector, so a dot product is a correlation
+// (with NaN days at the mean). Empty if the series is constant.
+std::vector<float> unit_returns(const std::vector<double>& net, std::size_t begin, std::size_t end) {
+    double sum = 0, n = 0;
+    for (std::size_t t = begin; t < end; ++t)
+        if (std::isfinite(net[t])) { sum += net[t]; n += 1; }
+    if (n < 2) return {};
+    double mean = sum / n, ss = 0;
+    for (std::size_t t = begin; t < end; ++t)
+        if (std::isfinite(net[t])) ss += (net[t] - mean) * (net[t] - mean);
+    if (!(ss > 0)) return {};
+    double scale = 1 / std::sqrt(ss);
+    std::vector<float> u(end - begin, 0.0f);
+    for (std::size_t t = begin; t < end; ++t)
+        if (std::isfinite(net[t])) u[t - begin] = static_cast<float>((net[t] - mean) * scale);
+    return u;
+}
+
+float dot(const std::vector<float>& a, const std::vector<float>& b) {
+    // Eight running sums, so the compiler can vectorise without reassociating.
+    float acc[8] = {};
+    std::size_t n = a.size(), i = 0;
+    for (; i + 8 <= n; i += 8)
+        for (int j = 0; j < 8; ++j) acc[j] += a[i + j] * b[i + j];
+    float s = ((acc[0] + acc[1]) + (acc[2] + acc[3])) + ((acc[4] + acc[5]) + (acc[6] + acc[7]));
+    for (; i < n; ++i) s += a[i] * b[i];
+    return s;
+}
+
+// First leader in [from, to) that u matches with |corr| > threshold, or -1.
+int find_cluster(const std::vector<float>& u, const std::vector<std::vector<float>>& leaders, std::size_t from,
+                 std::size_t to, double threshold) {
+    for (std::size_t i = from; i < to; ++i)
+        if (std::fabs(dot(u, leaders[i])) > threshold) return static_cast<int>(i);
+    return -1;
+}
+
 }  // namespace
 
 double series_corr(const std::vector<double>& a, const std::vector<double>& b, std::size_t begin, std::size_t end) {
@@ -156,6 +195,7 @@ SearchResult search(const Data& d, const Mat& returns, const SearchConfig& c, co
     Builder build(c, rng);
     SearchResult result;
     std::unordered_map<std::string, double> fitness_cache;  // formula -> penalised fitness
+    std::vector<std::vector<float>> leaders;                 // one per trial cluster
 
     auto fits = [&](const Node& n) {
         return n.size() <= static_cast<std::size_t>(c.max_size) && n.depth() <= static_cast<std::size_t>(c.max_depth);
@@ -183,6 +223,7 @@ SearchResult search(const Data& d, const Mat& returns, const SearchConfig& c, co
         }
         std::vector<Scored> scored(todo.size());
         const auto& hall = result.hall;
+        std::size_t known_leaders = leaders.size();  // read-only while the workers run
         parallel_for(todo.size(), c.threads, [&](std::size_t j) {
             const Node& n = pop[todo[j]];
             Scored& s = scored[j];
@@ -191,6 +232,8 @@ SearchResult search(const Data& d, const Mat& returns, const SearchConfig& c, co
             s.train = summarize(b, c.train_begin, c.train_end);
             if (s.train.n < 2 || s.train.sd <= 0) return;  // degenerate: never trades
             s.raw = s.train.sharpe - c.parsimony * static_cast<double>(n.size());
+            s.unit = unit_returns(b.net, c.train_begin, c.train_end);
+            if (!s.unit.empty()) s.cluster = find_cluster(s.unit, leaders, 0, known_leaders, c.max_corr);
             s.fitness = s.raw;
             double worst = 0;
             s.hall_corr.resize(hall.size());
@@ -217,6 +260,14 @@ SearchResult search(const Data& d, const Mat& returns, const SearchConfig& c, co
             tr.sharpe = ok ? s.train.sharpe : NaN;
             tr.mean_ic = ok ? s.train.mean_ic : NaN;
             tr.turnover = ok ? s.train.turnover : NaN;
+            if (ok && !s.unit.empty()) {
+                if (s.cluster < 0) s.cluster = find_cluster(s.unit, leaders, known_leaders, leaders.size(), c.max_corr);
+                if (s.cluster < 0) {
+                    s.cluster = static_cast<int>(leaders.size());
+                    leaders.push_back(std::move(s.unit));
+                }
+                tr.cluster = s.cluster;
+            }
             result.ledger.push_back(tr);
             fitness_cache[s.formula] = s.fitness;
             if (!ok) continue;

{falsealpha-0.1.0 → falsealpha-0.2.1}/cpp/src/ops.cpp

@@ -246,32 +246,46 @@ Mat apply_series(Op op, const Mat& a, const Mat* b, int d) {
     }
     if (op == Op::TsMax || op == Op::TsMin) return sliding_extreme(a, d, op == Op::TsMax);
 
-    if (op == Op::TsArgmax || op == Op::TsArgmin || op == Op::TsRank) {
-        // O(d) per cell; windows are short and these ops are rare in the search.
+    if (op == Op::TsArgmax || op == Op::TsArgmin) {
+        // Days since the extreme (0 = today); ties go to the most recent.
+        // O(d) per cell, a whole row per step (vectorised across assets).
+        Rolling nan_count(a, d);
+        std::vector<double> best(N), lag(N);
+        bool want_max = op == Op::TsArgmax;
+        for (std::size_t t = 0; t < T; ++t) {
+            nan_count.step(t);
+            if (t + 1 < D) continue;
+            std::copy(a.row(t), a.row(t) + N, best.begin());
+            std::fill(lag.begin(), lag.end(), 0.0);
+            for (std::size_t k = 1; k < D; ++k) {
+                const double* v = a.row(t - k);
+                for (std::size_t n = 0; n < N; ++n) {
+                    bool better = want_max ? v[n] > best[n] : v[n] < best[n];
+                    best[n] = better ? v[n] : best[n];
+                    lag[n] = better ? static_cast<double>(k) : lag[n];
+                }
+            }
+            for (std::size_t n = 0; n < N; ++n)
+                if (!nan_count.bad[n]) out(t, n) = lag[n];
+        }
+        return out;
+    }
+
+    if (op == Op::TsRank) {
+        // O(d) per cell; windows are short.
         Rolling nan_count(a, d);
         for (std::size_t t = 0; t < T; ++t) {
             nan_count.step(t);
             if (t + 1 < D) continue;
             for (std::size_t n = 0; n < N; ++n) {
                 if (nan_count.bad[n]) continue;
-                double cur = a(t, n);
-                if (op == Op::TsRank) {
-                    double below = 0, equal = 0;
-                    for (std::size_t k = 0; k < D; ++k) {
-                        double v = a(t - k, n);
-                        below += v < cur;
-                        equal += v == cur;
-                    }
-                    out(t, n) = (below + 0.5 * (equal - 1)) / (d - 1);
-                } else {
-                    // Days since the extreme (0 = today); ties go to the most recent.
-                    std::size_t best = 0;
-                    for (std::size_t k = 1; k < D; ++k) {
-                        double v = a(t - k, n), bv = a(t - best, n);
-                        if (op == Op::TsArgmax ? v > bv : v < bv) best = k;
-                    }
-                    out(t, n) = static_cast<double>(best);
+                double cur = a(t, n), below = 0, equal = 0;
+                for (std::size_t k = 0; k < D; ++k) {
+                    double v = a(t - k, n);
+                    below += v < cur;
+                    equal += v == cur;
                 }
+                out(t, n) = (below + 0.5 * (equal - 1)) / (d - 1);
             }
         }
         return out;

{falsealpha-0.1.0 → falsealpha-0.2.1}/cpp/src/score.cpp

@@ -46,7 +46,7 @@ Backtest backtest(const Mat& signal, const Mat& returns, const Data& d, const Sc
         if (members.size() >= static_cast<std::size_t>(c.min_assets)) {
             sig.clear();
             for (auto n : members) sig.push_back(s[n]);
-            std::vector<double> rk = average_ranks(sig);
+            std::vector<double> rk = average_ranks(sig), sig_rk = rk;
             double mean = std::accumulate(rk.begin(), rk.end(), 0.0) / rk.size();
             double gross = 0;
             for (auto& x : rk) { x -= mean; gross += std::fabs(x); }
@@ -56,7 +56,9 @@ Backtest backtest(const Mat& signal, const Mat& returns, const Data& d, const Sc
             sig.clear(); tgt.clear();
             for (auto n : members)
                 if (std::isfinite(r[n])) { sig.push_back(s[n]); tgt.push_back(r[n]); }
-            if (sig.size() >= static_cast<std::size_t>(c.min_assets)) b.ic[t] = pearson(average_ranks(sig), average_ranks(tgt));
+            // Usually every member has a target, and the signal ranks are the ones just computed.
+            if (sig.size() < members.size()) sig_rk = average_ranks(sig);
+            if (sig.size() >= static_cast<std::size_t>(c.min_assets)) b.ic[t] = pearson(sig_rk, average_ranks(tgt));
         }
 
         double pnl = 0, turn = 0;

{falsealpha-0.1.0 → falsealpha-0.2.1}/cpp/tests/test_ops.cpp

@@ -117,6 +117,39 @@ TEST_CASE("rolling state survives long series (drift refresh)") {
     }
 }
 
+TEST_CASE("moments stay exact in a quiet window after a volatile history") {
+    // The rolling sums behind the window means carry rounding drift from the
+    // huge earlier values; the corrected two-pass step must cancel it.
+    const std::size_t T = 400, N = 2, quiet = 300;
+    Data d;
+    d.T = T; d.N = N;
+    d.universe.assign(T * N, 1);
+    Mat c(T, N), v(T, N);
+    std::mt19937 rng(5);
+    std::normal_distribution<double> g(0.0, 1.0);
+    for (std::size_t t = 0; t < T; ++t) {
+        bool calm = t >= quiet;
+        c(t, 0) = calm ? 1.0 : 1e9 * (1 + 0.3 * g(rng));                    // then constant (a redenomination)
+        c(t, 1) = calm ? 1.0 + 1e-7 * g(rng) : 1e9 * (1 + 0.3 * g(rng));     // then barely moving
+        v(t, 0) = v(t, 1) = 1 + g(rng);
+    }
+    d.fields["close"] = c;
+    d.fields["volume"] = v;
+    Mat sd = evaluate(parse("ts_std(close, 20)"), d);
+    Mat z = evaluate(parse("ts_zscore(close, 20)"), d);
+    Mat cr = evaluate(parse("ts_corr(close, volume, 20)"), d);
+    for (std::size_t t = quiet + 19; t < T; ++t) {
+        REQUIRE(sd(t, 0) == 0.0);
+        REQUIRE(std::isnan(z(t, 0)));
+        REQUIRE(std::isnan(cr(t, 0)));
+        double m = 0, ss = 0;
+        for (std::size_t k = 0; k < 20; ++k) m += c(t - k, 1);
+        m /= 20;
+        for (std::size_t k = 0; k < 20; ++k) ss += (c(t - k, 1) - m) * (c(t - k, 1) - m);
+        REQUIRE(sd(t, 1) == Approx(std::sqrt(ss / 19)).epsilon(1e-9));
+    }
+}
+
 TEST_CASE("unknown fields are reported") {
     Data d = test::random_data(10, 3, 1);
     REQUIRE_THROWS_AS(evaluate(parse("rank(vwap)"), d), std::invalid_argument);

{falsealpha-0.1.0 → falsealpha-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "scikit_build_core.build"
 
 [project]
 name = "falsealpha"
-version = "0.1.0"
+version = "0.2.1"
 description = "A C++ alpha-mining engine that searches formulaic trading signals, then tells you which of its discoveries are fake."
 readme = "README.md"
 requires-python = ">=3.10"

{falsealpha-0.1.0 → falsealpha-0.2.1}/scripts/noise_calibration.py

@@ -1,8 +1,9 @@
 """How often does the firewall pass something on pure noise?
 
 Mines 30 independent noise panels (1,500 days x 60 assets, population 200 x 6
-generations, 10 bps costs) and counts survivors and SPA / Reality Check
-rejections. Usage: python scripts/noise_calibration.py [workdir]
+generations, 10 bps costs) and counts survivors, SPA / Reality Check
+rejections, and runs where a finalist passes the train Deflated Sharpe when
+trials are counted as every formula or as clusters. Usage: python scripts/noise_calibration.py [workdir]
 """
 
 import sys
@@ -15,6 +16,7 @@ from falsealpha import run, synthetic
 
 work = Path(sys.argv[1] if len(sys.argv) > 1 else tempfile.mkdtemp())
 spa, rc, pbo, survivors = [], [], [], 0
+dsr_all, dsr_eff, share = 0, 0, []
 for s in range(30):
     synthetic.noise(T=1500, N=60, seed=100 + s).save(work / f"noise{s}.npz")
     v = run.mine(work / f"noise{s}.npz", work / f"run{s}", run.MineConfig(population=200, generations=6, seed=s))
@@ -22,6 +24,11 @@ for s in range(30):
     rc.append(v["snoop"]["reality_check_p"])
     pbo.append(v["pbo"]["pbo"])
     survivors += len(v["survivors"])
+    dsr_all += any(f["train"]["dsr"] >= 0.95 for f in v["finalists"])
+    dsr_eff += any(f["train"]["dsr_effective"] >= 0.95 for f in v["finalists"])
+    share.append(v["n_effective"] / v["n_trials"])
 print(f"survivors: {survivors}")
 print(f"SPA p < 0.05: {sum(p < 0.05 for p in spa)}/30   Reality Check p < 0.05: {sum(p < 0.05 for p in rc)}/30")
 print(f"mean PBO: {np.mean(pbo):.2f}")
+print(f"train DSR >= 0.95 on some finalist: {dsr_all}/30 counting every formula, {dsr_eff}/30 counting clusters "
+      f"(clusters = {np.mean(share):.0%} of formulas)")

{falsealpha-0.1.0 → falsealpha-0.2.1}/src/falsealpha/cli.py

@@ -89,6 +89,9 @@ def cmd_mine(a: argparse.Namespace) -> None:
 def _print_verdict(v: dict, ppy: float) -> None:
     print(f"\n{v['n_trials']} formulas tried -> {v['n_finalists']} finalists -> {len(v['survivors'])} survivors")
     print(f"  luck bar (train): best of {v['n_trials']} unskilled strategies ~ Sharpe {_ann(v['sr0_train'], ppy)} /yr")
+    if "n_effective" in v:
+        print(f"  trial clusters: ~{v['n_effective']} independent bets -> luck bar {_ann(v['sr0_train_effective'], ppy)} /yr"
+              " (reported; the gate counts every formula)")
     if v["snoop"]:
         print(f"  Reality Check p {v['snoop']['reality_check_p']:.3f} (gate)   SPA p {v['snoop']['spa_p']:.3f}")
     if v["pbo"]:

{falsealpha-0.1.0 → falsealpha-0.2.1}/src/falsealpha/firewall.py

@@ -12,6 +12,10 @@ and validation and holdout are scored after the fact. Tests, in order:
    and the test ends up punishing the discovery. We report it as a diagnostic.
    Counting every distinct formula as a trial overstates the number of
    independent trials (near-copies are correlated), so the test is conservative.
+   The search also clusters its trials by train returns (|corr| above the
+   near-copy threshold joins a cluster); the cluster count estimates the
+   effective number of independent trials, and the DSR against it is reported
+   next to the gate, to show how much the conservative count matters.
 2. Validation Deflated Sharpe. The finalists are fresh trials on unseen days,
    deflated for the number of finalists.
 3. White's Reality Check on validation: is the best finalist better than flat
@@ -56,15 +60,22 @@ def deflated(net: np.ndarray, n_trials: float) -> dict:
     return {"sharpe": sr, "sr0": sr0, "dsr": dsr, "n": m["n"], "skew": m["skew"], "kurt": m["kurt"]}
 
 
-def run(ledger_sharpe: np.ndarray, nets: np.ndarray, train: slice, val: slice, t: Thresholds) -> dict:
-    """nets: finalists x days (pre-holdout panel), NaN where a day has no position or target."""
-    trials = ledger_sharpe[np.isfinite(ledger_sharpe)]
+def run(ledger_sharpe: np.ndarray, ledger_cluster: np.ndarray, nets: np.ndarray, train: slice, val: slice,
+        t: Thresholds) -> dict:
+    """nets: finalists x days (pre-holdout panel), NaN where a day has no position or target.
+    ledger_cluster: each trial's cluster id (-1 if degenerate)."""
+    ok = np.isfinite(ledger_sharpe)
+    trials = ledger_sharpe[ok]
     n_trials = len(trials)
+    n_effective = len(np.unique(ledger_cluster[ok & (ledger_cluster >= 0)]))
     var_trials = float(np.var(trials, ddof=1)) if n_trials > 1 else 0.0
     K = len(nets)
 
-    rows = [{"train": deflated(nets[k, train], n_trials), "validation": deflated(nets[k, val], K)}
-            for k in range(K)]
+    rows = []
+    for k in range(K):
+        tr = deflated(nets[k, train], n_trials)
+        tr["dsr_effective"] = deflated(nets[k, train], n_effective)["dsr"]
+        rows.append({"train": tr, "validation": deflated(nets[k, val], K)})
     T_train = train.stop - train.start
 
     out = {
@@ -73,6 +84,8 @@ def run(ledger_sharpe: np.ndarray, nets: np.ndarray, train: slice, val: slice, t
         "null_sharpe_sd": 1 / math.sqrt(T_train - 1),
         "sr0_train": _core.expected_max_sharpe(1 / (T_train - 1), n_trials),
         "sr0_train_paper": _core.expected_max_sharpe(var_trials, n_trials),
+        "n_effective": n_effective,
+        "sr0_train_effective": _core.expected_max_sharpe(1 / (T_train - 1), n_effective),
         "n_finalists": K,
         "finalists": rows,
         "snoop": None,

{falsealpha-0.1.0 → falsealpha-0.2.1}/src/falsealpha/report.py

@@ -92,7 +92,8 @@ def build(run_dir: str | Path) -> str:
         "split": {"val": cfg["index"]["val_start"], "hold": hold_start},
         "curves": [{"name": c["name"], "values": c["values"]} for c in curves],
         "hist": {"counts": hist_counts.tolist(), "edges": edges.tolist(),
-                 "luck": _finite(yearly(v["sr0_train"]))},
+                 "luck": _finite(yearly(v["sr0_train"])),
+                 "luck_effective": _finite(yearly(v["sr0_train_effective"])) if "n_effective" in v else None},
         "pbo": v["pbo"]["logits"] if v["pbo"] else [],
         "progress": progress,
     }
@@ -100,6 +101,11 @@ def build(run_dir: str | Path) -> str:
     looks = holdout["looks"]
     tiles = [
         (f"{v['n_trials']:,}", "formulas tried", "every distinct formula counts against the winners"),
+    ]
+    if "n_effective" in v:
+        tiles.append((f"≈{v['n_effective']:,}", "independent bets", "trial clusters (|corr| > "
+                      f"{cfg['search']['max_corr']}); shown for scale, the tests count every formula"))
+    tiles += [
         (str(v["n_finalists"]), "finalists", "diverse best of the search (|corr| ≤ "
          f"{cfg['search']['max_corr']})"),
         (str(len(survivors)), "survivors", "passed every test below"),
@@ -119,6 +125,7 @@ def build(run_dir: str | Path) -> str:
                   else f'<span class="st bad" title="{html.escape("; ".join(f["reasons"]))}">✕ fail</span>')
         return (f"<tr><td class=num>{i + 1}</td><td class=formula><code>{html.escape(f['formula'])}</code></td>"
                 f"<td class=num>{_fmt(yearly(tr['sharpe']), '+.2f')}</td><td class=num>{_fmt(tr['dsr'], '.2f')}</td>"
+                f"<td class=num>{_fmt(tr.get('dsr_effective'), '.2f')}</td>"
                 f"<td class=num>{_fmt(yearly(va['sharpe']), '+.2f')}</td><td class=num>{_fmt(va['dsr'], '.2f')}</td>"
                 f"<td>{status}</td><td class=why>{html.escape('; '.join(f['reasons']))}</td></tr>")
 
@@ -153,6 +160,8 @@ def build(run_dir: str | Path) -> str:
             .replace("%LOOKS%", look_html)
             .replace("%LUCK%", _fmt(yearly(v["sr0_train"]), "+.2f"))
             .replace("%NTRIALS%", f"{v['n_trials']:,}")
+            .replace("%LUCKEFF%", f"; counting only the ≈{v['n_effective']:,} trial clusters it is "
+                     f"{_fmt(yearly(v['sr0_train_effective']), '+.2f')}/yr" if "n_effective" in v else "")
             .replace("%DATA%", json.dumps(payload, allow_nan=False, default=_finite)
                      .replace("</", "<\\/")))
 
@@ -213,7 +222,7 @@ details{margin-top:8px;color:var(--ink2);font-size:13.5px}
 <div class=grid2>
 <div><h2>Trial Sharpe ratios vs the luck bar</h2>
 <p class=muted>Train Sharpe of all %NTRIALS% trials, annualised. The line is the best Sharpe expected from that many
-<em>unskilled</em> strategies (%LUCK%/yr).</p><div class=card id=hist></div></div>
+<em>unskilled</em> strategies (%LUCK%/yr)%LUCKEFF%.</p><div class=card id=hist></div></div>
 <div><h2>PBO: in-sample winner's out-of-sample rank</h2>
 <p class=muted>One logit per train/validation split (CSCV). Left of 0 the in-sample winner lands in the bottom half
 out of sample; the share there is the PBO.</p><div class=card id=pbo></div></div>
@@ -227,7 +236,7 @@ out of sample; the share there is the PBO.</p><div class=card id=pbo></div></div
 <p class=muted>Pass = train DSR ≥ 0.95 against all trials, validation Sharpe &gt; 0 with DSR ≥ 0.95 against the
 finalists, and the Reality Check gate open. Sharpe ratios annualised.</p>
 <div class="card tablewrap"><table><thead><tr><th class=num>#</th><th>formula</th><th class=num>train Sharpe</th>
-<th class=num>train DSR</th><th class=num>val Sharpe</th><th class=num>val DSR</th><th>verdict</th><th>why</th></tr>
+<th class=num>train DSR</th><th class=num title="train DSR against the number of trial clusters instead of every formula">DSR vs clusters</th><th class=num>val Sharpe</th><th class=num>val DSR</th><th>verdict</th><th>why</th></tr>
 </thead><tbody>%TABLE%</tbody></table></div>
 
 <h2>Holdout</h2>
@@ -272,9 +281,9 @@ function bars(id,counts,edges,refs,fmt){const host=document.getElementById(id);
     hit.addEventListener("pointerleave",()=>f.tip.style.display="none")});
   el("line",{x1:f.m.l,x2:f.W-f.m.r,y1:y(0),y2:y(0),stroke:css("--axis")},f.svg);
   for(const v of ticks(lo,hi,6)){const t=el("text",{x:x(v),y:f.H-6,"text-anchor":"middle"},f.svg);t.textContent=fmt(v)}
-  for(const r of refs){if(r.at==null||r.at<lo||r.at>hi)continue;
-    el("line",{x1:x(r.at),x2:x(r.at),y1:f.m.t,y2:y(0),stroke:css("--ink"),"stroke-width":1.5,"stroke-dasharray":"4 3"},f.svg);
-    const t=el("text",{x:x(r.at)+5,y:f.m.t+10},f.svg);t.textContent=r.label;t.style.fill=css("--ink2")}}
+  refs.forEach((r,i)=>{if(r.at==null||r.at<lo||r.at>hi)return;
+    el("line",{x1:x(r.at),x2:x(r.at),y1:f.m.t,y2:y(0),stroke:css(i?"--ink2":"--ink"),"stroke-width":1.5,"stroke-dasharray":i?"2 3":"4 3"},f.svg);
+    const t=el("text",{x:x(r.at)+5,y:f.m.t+10+14*i},f.svg);t.textContent=r.label;t.style.fill=css("--ink2")})}
 
 function lines(id,xs,series,opts){const host=document.getElementById(id);
   if(!series.length){host.textContent="No finalists.";return}
@@ -308,7 +317,7 @@ function draw(){for(const id of ["eq","hist","pbo","prog"])document.getElementBy
   const pct=v=>(v*100).toFixed(0)+"%";
   lines("eq",D.dates,D.curves,{fmt:pct,xfmt:s=>s.slice(0,7),zero:true,
     bands:[{from:D.split.val,to:D.split.hold,label:"validation"},{from:D.split.hold,to:D.dates.length-1,label:"holdout"}]});
-  bars("hist",D.hist.counts,D.hist.edges,[{at:D.hist.luck,label:"luck bar"}],v=>v.toFixed(1));
+  bars("hist",D.hist.counts,D.hist.edges,[{at:D.hist.luck,label:"luck bar"},{at:D.hist.luck_effective,label:"clusters"}],v=>v.toFixed(1));
   if(D.pbo.length){const lo=Math.min(...D.pbo,-0.5),hi=Math.max(...D.pbo,0.5),k=24,e=[...Array(k+1)].map((_,i)=>lo+(hi-lo)*i/k),
     c=Array(k).fill(0);for(const v of D.pbo)c[Math.min(k-1,Math.floor((v-lo)/(hi-lo)*k))]++;
     bars("pbo",c,e,[{at:0,label:"0"}],v=>v.toFixed(1))}else document.getElementById("pbo").textContent="Not enough finalists.";

{falsealpha-0.1.0 → falsealpha-0.2.1}/src/falsealpha/run.py

@@ -99,7 +99,8 @@ def mine(panel_path: str | Path, run_dir: str | Path, cfg: MineConfig, splits: S
 
     hall = result["hall"]
     nets = np.array([h["net"] for h in hall]) if hall else np.zeros((0, hold_start))
-    verdict = firewall.run(result["ledger"]["sharpe"], nets, train, val, thresholds)
+    verdict = firewall.run(result["ledger"]["sharpe"], np.asarray(result["ledger"]["cluster"]), nets, train, val,
+                           thresholds)
 
     run_dir.mkdir(parents=True, exist_ok=True)
     config = {
@@ -127,9 +128,9 @@ def mine(panel_path: str | Path, run_dir: str | Path, cfg: MineConfig, splits: S
     ledger = result["ledger"]
     with gzip.open(run_dir / "ledger.csv.gz", "wt", newline="") as f:
         w = csv.writer(f)
-        w.writerow(["formula", "train_sharpe", "train_mean_ic", "train_turnover", "size", "generation"])
+        w.writerow(["formula", "train_sharpe", "train_mean_ic", "train_turnover", "size", "generation", "cluster"])
         for row in zip(ledger["formula"], ledger["sharpe"], ledger["mean_ic"], ledger["turnover"],
-                       ledger["size"], ledger["generation"]):
+                       ledger["size"], ledger["generation"], ledger["cluster"]):
             w.writerow(row)
 
     finalists = []

{falsealpha-0.1.0 → falsealpha-0.2.1}/tests/test_firewall.py

@@ -105,3 +105,47 @@ def test_report_uses_the_panels_own_dates(tmp_path):
     run.mine(tmp_path / "b.npz", tmp_path / "run", run.MineConfig(population=40, generations=2, threads=2))
     html = report.build(tmp_path / "run")
     assert str(bdays[-1]) in html and str(np.datetime64("2015-01-01") + 899) not in html
+
+
+def _unit(net: np.ndarray) -> np.ndarray:
+    """Train returns as the search clusters them: demeaned, NaN days at the mean, unit length."""
+    z = np.where(np.isfinite(net), net - np.nanmean(net), 0.0)
+    return z / np.linalg.norm(z)
+
+
+def test_trials_are_clustered_into_independent_bets(planted_run):
+    import csv
+    import gzip
+
+    from falsealpha import _core
+    from falsealpha.panel import Panel
+
+    d, v = planted_run
+    with gzip.open(d / "run" / "ledger.csv.gz", "rt") as f:
+        rows = list(csv.DictReader(f))
+    ok = [r for r in rows if r["train_sharpe"] not in ("nan", "")]
+    clusters = [int(r["cluster"]) for r in ok]
+    assert sorted(set(clusters)) == list(range(len(set(clusters))))  # ids 0..K-1, in order of discovery
+    assert all(int(r["cluster"]) == -1 for r in rows if r not in ok)
+    assert v["n_effective"] == len(set(clusters)) < v["n_trials"] == len(ok)
+    assert v["sr0_train_effective"] < v["sr0_train"]
+    for f in v["finalists"]:
+        assert f["train"]["dsr_effective"] >= f["train"]["dsr"]
+
+    # Every member matches its leader (the cluster's first trial); leaders don't match each other.
+    cfg = json.loads((d / "run" / "config.json").read_text())
+    train = slice(*cfg["index"]["train"])
+    panel = Panel.load(d / "p.npz").head(cfg["index"]["hold_start"])
+    leader = {}
+    for r in ok:
+        leader.setdefault(int(r["cluster"]), r["formula"])
+    members = [r["formula"] for r in ok if leader[int(r["cluster"])] != r["formula"]][:40]
+    firsts = list(leader.values())[:40]
+    nets = {b_f: _unit(np.asarray(b["net"])[train]) for b_f, b in zip(
+        members + firsts, _core.backtest_many(members + firsts, "returns", panel.core(), delay=1, cost_bps=0))}
+    by_formula = {r["formula"]: int(r["cluster"]) for r in ok}
+    for m in members:
+        assert abs(nets[m] @ nets[leader[by_formula[m]]]) > 0.7 - 1e-4
+    for i, a in enumerate(firsts):
+        for b in firsts[:i]:
+            assert abs(nets[a] @ nets[b]) <= 0.7 + 1e-4