{
  "pack_id": "leakage-safe-regime-backtesting",
  "title": "Leakage-safe regime backtesting",
  "version": "0.1.0",
  "summary": "A collection of nouns and verbs for synthetic and historical statistical validation hygiene using purged and embargoed expanding-window walk-forward splits, volatility-regime Rank IC and ICIR, turnover cost accounting and multiple-testing deflation, strictly never as financial, investment or trading advice.",
  "dependencies": [
    "checked-data-analysis",
    "evaluation-design",
    "measured-claims"
  ],
  "boundaries": [
    "Strictly statistical validation hygiene on synthetic or historical panel series: never financial, investment or trading advice.",
    "No orders, trades, position recommendations or brokerage connections exist anywhere in this pack.",
    "Training folds must purge forward-label horizon overlaps before test windows and enforce embargo buffers.",
    "Importing the pack writes nothing, enqueues nothing and installs no code."
  ],
  "nouns": [
    {
      "slug": "pack",
      "category": "noun.skill_pack",
      "role": "pack",
      "title": "A collection of nouns and verbs for purged walk-forward statistical validation hygiene, regime Rank IC, turnover drag and multiple-testing deflation, never as financial advice",
      "value": {
        "lets_workers": "Audit time-series model evaluations strictly for statistical validation hygiene (never as financial or trading advice): build purged and embargoed expanding-window walk-forward splits, compute tie-aware Spearman Rank IC and ICIR across causal volatility regimes, deduct L1 turnover drag, and deflate Sharpe statistics for the number of tested configurations.",
        "not_for": "Financial advice, investment recommendations, order generation, live trading or brokerage interaction.",
        "flow": [
          {
            "verb": {
              "$verb": "leakage-safe-regime-backtesting.build-purged-splits"
            },
            "when": "Construct and audit expanding-window walk-forward folds with horizon purging and embargo bars."
          },
          {
            "verb": {
              "$verb": "leakage-safe-regime-backtesting.score-regime-ic-and-turnover"
            },
            "when": "Stratify Spearman Rank IC and ICIR across causal volatility regimes and deduct turnover drag."
          },
          {
            "verb": {
              "$verb": "leakage-safe-regime-backtesting.deflate-multiple-testing"
            },
            "when": "Apply skewness/kurtosis-adjusted multiple-testing deflation across all evaluated trials."
          }
        ],
        "guardrails": [
          {
            "$pin": "guardrail.statistical-hygiene-never-advice"
          },
          {
            "$pin": "guardrail.purge-label-horizons"
          },
          {
            "$pin": "guardrail.deflate-trial-multiplicity"
          }
        ],
        "tool": {
          "$pin": "tool.regime-backtest"
        },
        "worked_example": "Synthetic 4-unit fictional panel (SERIES_A.X..SERIES_D.X) recomputed in test_regime_backtest.py: verifies 3 leakage-free purged walk-forward folds, stratifies Rank IC across low/mid/high volatility regimes, accounts for 10 bps turnover drag and evaluates 12-trial Deflated Sharpe probability."
      },
      "relations": [
        [
          "requires_noun",
          "guardrail.statistical-hygiene-never-advice"
        ],
        [
          "requires_noun",
          "guardrail.purge-label-horizons"
        ],
        [
          "requires_noun",
          "guardrail.deflate-trial-multiplicity"
        ],
        [
          "requires_noun",
          "spec.walk-forward-hygiene"
        ],
        [
          "requires_noun",
          "rules.regime-and-turnover"
        ],
        [
          "requires_noun",
          "tool.regime-backtest"
        ],
        [
          "requires_noun",
          "template.validation-receipt"
        ]
      ]
    },
    {
      "slug": "guardrail.statistical-hygiene-never-advice",
      "category": "noun.skill_pack",
      "role": "guardrail",
      "title": "Guardrail: strictly statistical validation hygiene, never financial or trading advice",
      "category_reason": "Establishes the non-advisory statistical hygiene boundary across every task and artifact.",
      "value": {
        "rule": "Outputs measure statistical out-of-sample hygiene on synthetic or historical panels only; no task recommends securities, sizes live capital, or connects to any broker or exchange.",
        "how_it_is_checked": "Pack boundaries, schema fields and CLI help enforce diagnostic-only statistical hygiene outputs."
      }
    },
    {
      "slug": "guardrail.purge-label-horizons",
      "category": "noun.skill_pack",
      "role": "guardrail",
      "title": "Guardrail: purge training observations whose forward target horizon overlaps the test fold",
      "category_reason": "Prevents multi-bar forward target overlap from leaking test realizations into training.",
      "value": {
        "rule": "Every training index t satisfies t + label_horizon_bars <= test_start in walk-forward splits and obeys embargo_bars after any validation block.",
        "how_it_is_checked": "verify_split_hygiene audits every fold and blocks evaluation when leakage_free is false."
      }
    },
    {
      "slug": "guardrail.deflate-trial-multiplicity",
      "category": "noun.skill_pack",
      "role": "guardrail",
      "title": "Guardrail: penalize selection bias across all tested hyperparameter and feature trials",
      "category_reason": "Prevents data-mined configurations from passing on raw single-test Sharpe ratios.",
      "value": {
        "rule": "deflated_sharpe_ratio raises the null benchmark SR_0 with num_trials and adjusts variance for sample skewness and kurtosis.",
        "how_it_is_checked": "run_validation_audit requires deflated_sharpe_prob >= min_dsr_prob alongside positive net cumulative score."
      }
    },
    {
      "slug": "spec.walk-forward-hygiene",
      "category": "noun.benchmark_suite",
      "role": "spec",
      "title": "Specification: purged walk-forward splits, causal volatility regimes, turnover drag and DSR gate",
      "category_reason": "Defines deterministic split, regime, cost and multiple-testing validation parameters.",
      "value": {
        "splits": {
          "mode": "expanding_purged_walk_forward",
          "default_label_horizon_bars": 3,
          "default_embargo_bars": 2
        },
        "regimes": {
          "low_vol_ceiling": 0.012,
          "high_vol_floor": 0.025,
          "causal_feature_required": true
        },
        "hygiene_gates": {
          "default_cost_bps": 10.0,
          "min_dsr_prob": 0.9
        }
      }
    },
    {
      "slug": "rules.regime-and-turnover",
      "category": "noun.reflex_procedure",
      "role": "rules",
      "title": "Evaluation rules: tie-aware Spearman Rank IC, L1 turnover drag and Euler-Mascheroni trial deflation",
      "category_reason": "Zero-call statistical computation formulas.",
      "value": {
        "rank_correlation": "average_rank_spearman",
        "turnover_formula": "sum_j |w_{t,j} - w_{t-1,j}| * cost_bps * 1e-4",
        "multiple_testing": "euler_mascheroni_extreme_value_dsr",
        "model_calls": 0
      }
    },
    {
      "slug": "tool.regime-backtest",
      "category": "noun.code_node",
      "role": "tool_card",
      "title": "Tool card: purged walk-forward split auditor, regime IC calculator and multiple-testing deflator",
      "category_reason": "Tested standard-library Python package pinned by path, file count and digest.",
      "value": {
        "name": "Leakage-safe regime backtesting",
        "code": {
          "$code": "leakage-safe-regime-backtesting"
        },
        "runtime": "Python 3.10 or later, standard library only.",
        "commands": [
          "python -m regime_backtest splits --input PANEL_BUNDLE.json",
          "python -m regime_backtest audit --input PANEL_BUNDLE.json"
        ],
        "does": [
          "Generates expanding-window walk-forward and blocked K-fold splits with horizon purging and embargo checks.",
          "Computes Spearman Rank IC and ICIR across causal low, mid and high volatility regimes plus linear turnover cost drag.",
          "Computes skewness/kurtosis-adjusted Deflated Sharpe probability across num_trials."
        ],
        "does_not": [
          "Provide financial, investment or trading advice, generate orders or connect to any brokerage or market venue."
        ],
        "code_license": "MIT"
      },
      "relations": [
        [
          "verifies",
          "spec.walk-forward-hygiene"
        ]
      ]
    },
    {
      "slug": "template.validation-receipt",
      "category": "noun.scene_recipe",
      "role": "template",
      "title": "Template: statistical split-hygiene, regime IC, turnover and multiple-testing receipt",
      "value": {
        "describes": "a non-advisory statistical validation receipt reporting split leakage status, regime Rank IC, turnover drag and Deflated Sharpe probability",
        "schema": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "leakage_free",
            "num_folds",
            "overall_mean_rank_ic",
            "overall_rank_icir",
            "regime_mean_ic",
            "mean_turnover",
            "net_cumulative",
            "deflated_sharpe_prob",
            "passes_hygiene_gate"
          ],
          "properties": {
            "leakage_free": {
              "type": "boolean"
            },
            "num_folds": {
              "type": "integer",
              "minimum": 1
            },
            "overall_mean_rank_ic": {
              "type": "number",
              "minimum": -1,
              "maximum": 1
            },
            "overall_rank_icir": {
              "type": "number"
            },
            "regime_mean_ic": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "low_vol",
                "mid_vol",
                "high_vol"
              ],
              "properties": {
                "low_vol": {
                  "type": "number"
                },
                "mid_vol": {
                  "type": "number"
                },
                "high_vol": {
                  "type": "number"
                }
              }
            },
            "mean_turnover": {
              "type": "number",
              "minimum": 0
            },
            "net_cumulative": {
              "type": "number"
            },
            "deflated_sharpe_prob": {
              "type": "number",
              "minimum": 0,
              "maximum": 1
            },
            "passes_hygiene_gate": {
              "type": "boolean"
            }
          }
        },
        "example": {
          "leakage_free": true,
          "num_folds": 3,
          "overall_mean_rank_ic": 0.733333,
          "overall_rank_icir": 1.615489,
          "regime_mean_ic": {
            "low_vol": 0.9,
            "mid_vol": 0.6,
            "high_vol": 0.7
          },
          "mean_turnover": 0.116667,
          "net_cumulative": 0.04165,
          "deflated_sharpe_prob": 0.97584,
          "passes_hygiene_gate": true
        }
      }
    },
    {
      "slug": "example.synthetic-panel",
      "category": "noun.eval_run",
      "role": "example",
      "synthetic": true,
      "title": "Worked example input: synthetic 4-series fictional panel (SERIES_A.X..SERIES_D.X) for hygiene checks",
      "category_reason": "Purely synthetic statistical fixture recomputed by test_regime_backtest.py.",
      "value": {
        "synthetic_series_ids": [
          "SERIES_A.X",
          "SERIES_B.X",
          "SERIES_C.X",
          "SERIES_D.X"
        ],
        "split_config": {
          "n_bars": 60,
          "min_train_bars": 20,
          "test_bars": 10,
          "step_bars": 12,
          "label_horizon_bars": 3,
          "embargo_bars": 2
        },
        "low_vol_ceiling": 0.012,
        "high_vol_floor": 0.025,
        "cost_bps": 10.0,
        "num_trials": 12,
        "cross_trial_sr_std": 0.25,
        "min_dsr_prob": 0.9,
        "out_of_sample_bars": [
          {
            "causal_realized_vol": 0.009,
            "predictions": [
              0.1,
              0.25,
              0.4,
              0.7
            ],
            "weights": [
              -0.25,
              -0.1,
              0.1,
              0.25
            ],
            "realized_outcomes": [
              -0.01,
              0.002,
              -0.001,
              0.014
            ]
          },
          {
            "causal_realized_vol": 0.011,
            "predictions": [
              0.15,
              0.3,
              0.45,
              0.65
            ],
            "weights": [
              -0.25,
              -0.1,
              0.1,
              0.25
            ],
            "realized_outcomes": [
              -0.006,
              -0.002,
              0.005,
              0.011
            ]
          },
          {
            "causal_realized_vol": 0.01,
            "predictions": [
              0.2,
              0.35,
              0.55,
              0.8
            ],
            "weights": [
              -0.2,
              -0.15,
              0.15,
              0.2
            ],
            "realized_outcomes": [
              0.003,
              -0.004,
              0.006,
              0.008
            ]
          },
          {
            "causal_realized_vol": 0.011,
            "predictions": [
              0.12,
              0.28,
              0.5,
              0.75
            ],
            "weights": [
              -0.2,
              -0.15,
              0.15,
              0.2
            ],
            "realized_outcomes": [
              -0.007,
              -0.001,
              0.004,
              0.01
            ]
          },
          {
            "causal_realized_vol": 0.016,
            "predictions": [
              0.12,
              0.32,
              0.52,
              0.75
            ],
            "weights": [
              -0.2,
              -0.15,
              0.15,
              0.2
            ],
            "realized_outcomes": [
              -0.005,
              0.003,
              0.001,
              0.012
            ]
          },
          {
            "causal_realized_vol": 0.018,
            "predictions": [
              0.05,
              0.4,
              0.5,
              0.85
            ],
            "weights": [
              -0.25,
              -0.05,
              0.05,
              0.25
            ],
            "realized_outcomes": [
              0.004,
              -0.003,
              0.002,
              -0.001
            ]
          },
          {
            "causal_realized_vol": 0.02,
            "predictions": [
              0.18,
              0.28,
              0.6,
              0.72
            ],
            "weights": [
              -0.25,
              -0.05,
              0.05,
              0.25
            ],
            "realized_outcomes": [
              -0.008,
              -0.002,
              0.007,
              0.009
            ]
          },
          {
            "causal_realized_vol": 0.019,
            "predictions": [
              0.1,
              0.35,
              0.58,
              0.8
            ],
            "weights": [
              -0.25,
              -0.05,
              0.05,
              0.25
            ],
            "realized_outcomes": [
              -0.006,
              0.001,
              0.005,
              0.011
            ]
          },
          {
            "causal_realized_vol": 0.028,
            "predictions": [
              0.22,
              0.38,
              0.58,
              0.9
            ],
            "weights": [
              -0.2,
              -0.1,
              0.1,
              0.2
            ],
            "realized_outcomes": [
              -0.012,
              0.004,
              0.002,
              0.015
            ]
          },
          {
            "causal_realized_vol": 0.031,
            "predictions": [
              0.08,
              0.33,
              0.48,
              0.78
            ],
            "weights": [
              -0.2,
              -0.1,
              0.1,
              0.2
            ],
            "realized_outcomes": [
              0.005,
              -0.006,
              0.008,
              -0.002
            ]
          },
          {
            "causal_realized_vol": 0.027,
            "predictions": [
              0.14,
              0.29,
              0.62,
              0.82
            ],
            "weights": [
              -0.2,
              -0.1,
              0.1,
              0.2
            ],
            "realized_outcomes": [
              -0.009,
              0.001,
              0.004,
              0.013
            ]
          },
          {
            "causal_realized_vol": 0.029,
            "predictions": [
              0.16,
              0.31,
              0.6,
              0.84
            ],
            "weights": [
              -0.2,
              -0.1,
              0.1,
              0.2
            ],
            "realized_outcomes": [
              -0.007,
              -0.002,
              0.006,
              0.012
            ]
          }
        ]
      }
    },
    {
      "slug": "example.validation-receipt",
      "category": "noun.eval_run",
      "role": "example",
      "synthetic": true,
      "title": "Worked example output: recomputed non-advisory statistical validation hygiene receipt",
      "category_reason": "Deterministic output conforming to template.validation-receipt.",
      "value": {
        "conforms_to": {
          "$pin": "template.validation-receipt"
        },
        "instance": {
          "leakage_free": true,
          "num_folds": 3,
          "overall_mean_rank_ic": 0.733333,
          "overall_rank_icir": 1.615489,
          "regime_mean_ic": {
            "low_vol": 0.9,
            "mid_vol": 0.6,
            "high_vol": 0.7
          },
          "mean_turnover": 0.116667,
          "net_cumulative": 0.04165,
          "deflated_sharpe_prob": 0.97584,
          "passes_hygiene_gate": true
        }
      },
      "relations": [
        [
          "derives_from",
          "example.synthetic-panel"
        ],
        [
          "verifies",
          "template.validation-receipt"
        ]
      ]
    }
  ],
  "verbs": [
    {
      "slug": "build-purged-splits",
      "kind": "verb.compile_dag",
      "title": "Construct and audit purged and embargoed expanding-window walk-forward splits",
      "claimant": "agent",
      "model_use": "none",
      "summary": "Generate expanding-window walk-forward folds that purge forward-label horizons before each test window, enforce after-test embargo buffers, and audit zero index or horizon leakage.",
      "outcome": "Verified walk-forward fold indices and zero-leakage audit report.",
      "ready_outcome": "purged_splits_verified",
      "pinned": [
        "spec.walk-forward-hygiene",
        "tool.regime-backtest",
        "guardrail.purge-label-horizons"
      ],
      "slots": [
        {
          "name": "split_config",
          "category": "noun.benchmark_suite",
          "description": "Pin of n_bars, min_train_bars, test_bars, label_horizon_bars and embargo_bars."
        }
      ],
      "produces": [
        {
          "name": "split_audit",
          "template": "template.validation-receipt"
        }
      ],
      "steps": [
        "Run generate_purged_walk_forward_splits on the panel length and horizon config.",
        "Run verify_split_hygiene and confirm leakage_free == true."
      ],
      "acceptance": [
        {
          "id": "zero-horizon-leakage",
          "check": "verify_split_hygiene returns leakage_free == true with empty violations.",
          "method": "deterministic"
        }
      ]
    },
    {
      "slug": "score-regime-ic-and-turnover",
      "kind": "verb.benchmark_harness",
      "title": "Compute regime-stratified Rank IC/ICIR and turnover cost drag",
      "claimant": "agent",
      "model_use": "none",
      "summary": "Evaluate tie-aware Spearman Rank IC and ICIR across causal low, mid and high volatility regimes and deduct linear L1 turnover drag from synthetic periodic scores.",
      "outcome": "Regime-stratified Rank IC/ICIR table and net-of-turnover periodic series.",
      "ready_outcome": "regime_ic_and_costs_scored",
      "pinned": [
        "rules.regime-and-turnover",
        "tool.regime-backtest",
        "guardrail.statistical-hygiene-never-advice"
      ],
      "slots": [
        {
          "name": "out_of_sample_panel",
          "category": "noun.eval_run",
          "description": "Pin of out-of-sample causal volatility, predictions, weights and realized outcomes."
        }
      ],
      "produces": [
        {
          "name": "regime_and_cost_summary",
          "template": "template.validation-receipt"
        }
      ],
      "steps": [
        "Compute Rank IC and ICIR per causal volatility bucket with compute_regime_ic_summary.",
        "Deduct turnover costs with account_turnover_costs."
      ],
      "acceptance": [
        {
          "id": "regime-and-turnover-recomputed",
          "check": "compute_regime_ic_summary and account_turnover_costs reproduce regime ICs and net_cumulative.",
          "method": "deterministic"
        }
      ],
      "follows": [
        "leakage-safe-regime-backtesting.build-purged-splits"
      ]
    },
    {
      "slug": "deflate-multiple-testing",
      "kind": "verb.verify_gate",
      "title": "Evaluate multiple-testing Deflated Sharpe hygiene gate",
      "claimant": "agent",
      "model_use": "none",
      "summary": "Adjust the net out-of-sample Sharpe statistic for skewness, kurtosis and the expected maximum across num_trials to emit a non-advisory statistical hygiene receipt.",
      "outcome": "A conforming validation-receipt recording split hygiene, regime ICs, turnover drag and Deflated Sharpe probability.",
      "ready_outcome": "validation_hygiene_gated",
      "pinned": [
        "spec.walk-forward-hygiene",
        "tool.regime-backtest",
        "template.validation-receipt",
        "guardrail.deflate-trial-multiplicity",
        "guardrail.statistical-hygiene-never-advice"
      ],
      "slots": [
        {
          "name": "regime_and_cost_summary",
          "category": "noun.eval_run",
          "description": "Pin of net periodic series and total trial count."
        }
      ],
      "produces": [
        {
          "name": "validation_receipt",
          "template": "template.validation-receipt"
        }
      ],
      "steps": [
        "Run deflated_sharpe_ratio with the exact total num_trials evaluated.",
        "Validate the full output against template.validation-receipt."
      ],
      "acceptance": [
        {
          "id": "matches-validation-receipt-schema",
          "check": "Output passes schema validation against template.validation-receipt.",
          "method": "deterministic"
        }
      ],
      "follows": [
        "leakage-safe-regime-backtesting.score-regime-ic-and-turnover"
      ]
    }
  ]
}