corrscore 0.1.0__tar.gz

corrscore-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,36 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install build backend
+        run: pip install build
+      - name: Build sdist and wheel
+        run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

corrscore-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,23 @@
+name: test
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install package with dev dependencies
+        run: pip install -e ".[dev]"
+      - name: Run tests
+        run: pytest -q
+      - name: Type-check
+        run: mypy src/corrscore

corrscore-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+.hypothesis/
+.mypy_cache/
+*.egg-info/
+dist/
+build/
+.venv*/

corrscore-0.1.0/CITATION.cff

@@ -0,0 +1,22 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite the accompanying paper below."
+title: "corrscore: Matrix-Aware Proper Scoring Rules and Significance Testing for Correlation and Covariance Forecasts in Python"
+type: software
+authors:
+  - family-names: Nguyen
+    given-names: Vinh
+    # orcid: "https://orcid.org/XXXX-XXXX-XXXX-XXXX"  # fill in
+url: "https://github.com/vinhnguyen3455/corrscore"
+license: MIT
+version: 0.1.0
+date-released: 2026-08-27
+preferred-citation:
+  type: unpublished
+  title: "corrscore: Matrix-Aware Proper Scoring Rules and Significance Testing for Correlation and Covariance Forecasts in Python"
+  authors:
+    - family-names: Nguyen
+      given-names: Vinh
+      # orcid: "https://orcid.org/XXXX-XXXX-XXXX-XXXX"  # fill in
+  year: 2026
+  url: "https://papers.ssrn.com/sol3/papers.cfm?abstract_id=7358478"
+  notes: "Working paper, SSRN. Also pending submission to arXiv (q-fin.CP) -- update this record with the arXiv identifier once endorsement clears."

corrscore-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vinh Nguyen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

corrscore-0.1.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.5
+Name: corrscore
+Version: 0.1.0
+Summary: Matrix-aware proper-scoring-rule backtesting for correlation and covariance forecasts: zero-overlap walk-forward evaluation, energy/variogram scoring, and significance testing (block bootstrap, Diebold-Mariano, Model Confidence Set).
+Author-email: Vinh Nguyen <vinhnguyen3455@gmail.com>
+License: MIT
+License-File: LICENSE
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.10
+Requires-Dist: arch>=6.3
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Provides-Extra: dev
+Requires-Dist: hypothesis>=6.100; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# corrscore
+
+Matrix-aware proper-scoring-rule backtesting for correlation and covariance forecasts, in Python.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+## Why this exists
+
+Forecasting a correlation or covariance matrix is common in risk management and portfolio
+construction — but evaluating that forecast correctly is not routine. Two mistakes are easy to
+make and hard to notice:
+
+1. **Naive matrix-comparison metrics aren't proper scoring rules.** A metric that isn't a proper
+   scoring rule can reward a forecaster for hedging toward a "safe" answer instead of reporting
+   their honest best guess — the evaluation itself creates bad incentives.
+2. **Walk-forward evaluation windows are easy to overlap with the estimation window**, silently
+   leaking future information into a backtest and inflating apparent skill.
+
+`corrscore` evaluates a forecast; it never produces one. It doesn't fit a model, doesn't implement
+any particular correlation-dynamics model, and doesn't fetch or clean data — it's a focused
+evaluation layer you drop on top of whatever you're already forecasting with.
+
+## What it offers
+
+- **Matrix-aware energy and variogram scores.** The two standard proper scoring rules from the
+  forecast-verification literature, generalized from their usual vector-valued form to score a
+  full `K x K` correlation/covariance matrix directly.
+- **A geometric variant of the variogram score**, aware of the fact that correlation matrices live
+  on a curved space rather than flat Euclidean space — sharper at detecting forecast danger as a
+  matrix approaches the boundary of validity (near-singular, highly correlated regimes).
+- **Four forecast representations**, not just point forecasts: a single deterministic matrix, a
+  discrete mixture of any number of atoms, an isotropic-Gaussian mixture, or a general Monte Carlo
+  ensemble — with closed-form scoring wherever one exists, Monte Carlo estimation only where it
+  doesn't.
+- **A backtesting harness (`backtest_zero_overlap`)** that makes the specific, easy-to-make
+  lookahead bug — ground truth computed from a window that overlaps the forecast origin —
+  structurally impossible to reproduce, rather than something you have to remember to get right.
+- **Significance testing**, not just point comparisons: a circular block bootstrap for
+  serially-dependent score differentials, the Diebold-Mariano test, and the Model Confidence Set
+  — so "is model A really better than model B" has an actual answer.
+
+```python
+from corrscore import matrix_energy_score, backtest_zero_overlap
+from corrscore import circular_block_bootstrap, diebold_mariano, model_confidence_set
+
+result = backtest_zero_overlap(
+    forecast_fns={"naive": naive_forecast, "filter": my_model.forecast},
+    ground_truth_fn=realized_correlation,   # (start, end) -> K x K matrix
+    origins=origins,
+    horizon=10,
+)
+sig = circular_block_bootstrap(result.scores["filter"], result.scores["naive"], block_lengths=[1, 3, 6, 10])
+mcs = model_confidence_set(result.scores, alpha=0.10)
+```
+
+## Install
+
+```bash
+pip install corrscore
+```
+
+Requires Python 3.10-3.12. Runtime dependencies are `numpy`, `scipy`, and `arch` (for the circular
+block bootstrap) — nothing else.
+
+## Validation
+
+Every scoring rule and test in this package is checked against an independent source of truth, not
+just its own self-consistency: `diebold_mariano` and `model_confidence_set` are cross-checked
+against live-generated R oracles (`forecast::dm.test` byte-exact, `MCS::MCSprocedure`
+verdict-matched), and every closed-form scoring formula is checked against brute-force Monte Carlo
+simulation of the object it claims to score. Fully type-hinted and `mypy`-clean. See `tests/` for
+the full suite.
+
+## Related work
+
+No existing package (Python or R) treats a correlation/covariance matrix as the forecast object
+with purge-aware walk-forward splitting and a proper scoring rule built in — see
+[`docs/survey/`](docs/survey/) for the full landscape survey and the specific reuse-vs.-vendor
+decision behind each dependency.
+
+## Citation
+
+A companion paper describing the package's design and methodology is available as a working
+paper on SSRN: [Nguyen (2026), "corrscore: Matrix-Aware Proper Scoring Rules and Significance
+Testing for Correlation and Covariance Forecasts in
+Python"](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=7358478). See
+[`CITATION.cff`](CITATION.cff) for a machine-readable citation.
+
+## Development
+
+```bash
+git clone https://github.com/vinhnguyen3455/corrscore
+cd corrscore
+pip install -e ".[dev]"
+pytest -q
+mypy src/corrscore
+```
+
+Issues and pull requests welcome.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

corrscore-0.1.0/README.md

@@ -0,0 +1,103 @@
+# corrscore
+
+Matrix-aware proper-scoring-rule backtesting for correlation and covariance forecasts, in Python.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+## Why this exists
+
+Forecasting a correlation or covariance matrix is common in risk management and portfolio
+construction — but evaluating that forecast correctly is not routine. Two mistakes are easy to
+make and hard to notice:
+
+1. **Naive matrix-comparison metrics aren't proper scoring rules.** A metric that isn't a proper
+   scoring rule can reward a forecaster for hedging toward a "safe" answer instead of reporting
+   their honest best guess — the evaluation itself creates bad incentives.
+2. **Walk-forward evaluation windows are easy to overlap with the estimation window**, silently
+   leaking future information into a backtest and inflating apparent skill.
+
+`corrscore` evaluates a forecast; it never produces one. It doesn't fit a model, doesn't implement
+any particular correlation-dynamics model, and doesn't fetch or clean data — it's a focused
+evaluation layer you drop on top of whatever you're already forecasting with.
+
+## What it offers
+
+- **Matrix-aware energy and variogram scores.** The two standard proper scoring rules from the
+  forecast-verification literature, generalized from their usual vector-valued form to score a
+  full `K x K` correlation/covariance matrix directly.
+- **A geometric variant of the variogram score**, aware of the fact that correlation matrices live
+  on a curved space rather than flat Euclidean space — sharper at detecting forecast danger as a
+  matrix approaches the boundary of validity (near-singular, highly correlated regimes).
+- **Four forecast representations**, not just point forecasts: a single deterministic matrix, a
+  discrete mixture of any number of atoms, an isotropic-Gaussian mixture, or a general Monte Carlo
+  ensemble — with closed-form scoring wherever one exists, Monte Carlo estimation only where it
+  doesn't.
+- **A backtesting harness (`backtest_zero_overlap`)** that makes the specific, easy-to-make
+  lookahead bug — ground truth computed from a window that overlaps the forecast origin —
+  structurally impossible to reproduce, rather than something you have to remember to get right.
+- **Significance testing**, not just point comparisons: a circular block bootstrap for
+  serially-dependent score differentials, the Diebold-Mariano test, and the Model Confidence Set
+  — so "is model A really better than model B" has an actual answer.
+
+```python
+from corrscore import matrix_energy_score, backtest_zero_overlap
+from corrscore import circular_block_bootstrap, diebold_mariano, model_confidence_set
+
+result = backtest_zero_overlap(
+    forecast_fns={"naive": naive_forecast, "filter": my_model.forecast},
+    ground_truth_fn=realized_correlation,   # (start, end) -> K x K matrix
+    origins=origins,
+    horizon=10,
+)
+sig = circular_block_bootstrap(result.scores["filter"], result.scores["naive"], block_lengths=[1, 3, 6, 10])
+mcs = model_confidence_set(result.scores, alpha=0.10)
+```
+
+## Install
+
+```bash
+pip install corrscore
+```
+
+Requires Python 3.10-3.12. Runtime dependencies are `numpy`, `scipy`, and `arch` (for the circular
+block bootstrap) — nothing else.
+
+## Validation
+
+Every scoring rule and test in this package is checked against an independent source of truth, not
+just its own self-consistency: `diebold_mariano` and `model_confidence_set` are cross-checked
+against live-generated R oracles (`forecast::dm.test` byte-exact, `MCS::MCSprocedure`
+verdict-matched), and every closed-form scoring formula is checked against brute-force Monte Carlo
+simulation of the object it claims to score. Fully type-hinted and `mypy`-clean. See `tests/` for
+the full suite.
+
+## Related work
+
+No existing package (Python or R) treats a correlation/covariance matrix as the forecast object
+with purge-aware walk-forward splitting and a proper scoring rule built in — see
+[`docs/survey/`](docs/survey/) for the full landscape survey and the specific reuse-vs.-vendor
+decision behind each dependency.
+
+## Citation
+
+A companion paper describing the package's design and methodology is available as a working
+paper on SSRN: [Nguyen (2026), "corrscore: Matrix-Aware Proper Scoring Rules and Significance
+Testing for Correlation and Covariance Forecasts in
+Python"](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=7358478). See
+[`CITATION.cff`](CITATION.cff) for a machine-readable citation.
+
+## Development
+
+```bash
+git clone https://github.com/vinhnguyen3455/corrscore
+cd corrscore
+pip install -e ".[dev]"
+pytest -q
+mypy src/corrscore
+```
+
+Issues and pull requests welcome.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

corrscore-0.1.0/docs/survey/README.md

@@ -0,0 +1,56 @@
+# Related-software survey — findings (complete 2026-08-25)
+
+This package's scope rests on one survey, run live against PyPI/CRAN/GitHub
+(license, last-activity, and — the actual point of the exercise — an
+adversarial search trying to falsify the claimed gap) rather than assumed
+from general familiarity. See
+[`related-software-survey.md`](related-software-survey.md) in this same
+directory for the full package-by-package table.
+
+## What this settles, concretely
+
+1. **The gap is real and survives an adversarial search.** No package, in
+   either Python or R, treats a correlation/covariance matrix as the
+   forecast object with purge-aware walk-forward splitting and a proper
+   scoring rule built in — every existing tool operates one layer down (a
+   scalar loss, a vector observation, or a generic index-based CV
+   splitter). Confirmed by targeted searches for the specific claim
+   ("correlation matrix forecast evaluation package," GitHub topic search
+   on `covariance-matrix`), not just an absence of a name that happened to
+   come to mind.
+
+2. **`arch` (Sheppard) is the one dependency that clears this package's own
+   bar** (widely used, actively maintained, field-standard) — kept
+   directly for `CircularBlockBootstrap` rather than reimplemented.
+   Everything else found in the survey either isn't clearly established
+   enough (`scoringrules`: 98★, and its own PyPI/GitHub release metadata
+   disagreed on dates during this check — an unresolved integrity flag)
+   or isn't installable at all as a real dependency (`model-confidence-set`:
+   GitHub-only, no PyPI release, 21★; `mlfinlab`: gone commercial).
+
+3. **R is comparatively well-served; Python is the real gap.** R's
+   `scoringRules` (CRAN, 2024-09-18), `MCS` (Catania, CRAN, **2026-03-19** —
+   genuinely current), `multDM`, and base `forecast::dm.test` together
+   cover almost everything this package implements — just not assembled
+   into one matrix-aware, zero-overlap pipeline. That absence of assembly,
+   not absence of building blocks, is why an R companion package remains a
+   plausible but non-urgent future extension, not a v1 requirement.
+
+4. **Dependency policy, applied concretely per package**: `README.md`'s
+   own "Dependency policy" table and `src/corrscore/`'s module docstrings
+   (`scoring.py`, `diebold_mariano.py`, `mcs.py`) each state the specific
+   reuse-vs.-vendor decision and why, rather than leaving it implicit.
+   `model_confidence_set` in particular is checked against R's
+   `MCS::MCSprocedure` verdict on a fixed synthetic case
+   (`tests/_reference/mcs_oracle_case.py`) rather than claimed correct by
+   construction — it was the clearest case in the survey for vendoring
+   over depending, and also the implementation with the most room for a
+   subtle bug, so the highest-value place to have an external check.
+
+## What this survey did not cover
+
+Whether `matrix_variogram_score`'s specific entry-indexing convention
+matches any convention a reader coming from the meteorology/
+forecast-verification literature would expect by default — there is no
+existing matrix-valued precedent to check against, which is the whole
+reason a convention had to be chosen rather than adopted.

corrscore-0.1.0/docs/survey/related-software-survey.md

@@ -0,0 +1,36 @@
+# Related-software survey
+
+Live-verified 2026-08-25 against PyPI/CRAN package pages, GitHub license/activity
+checks, and source inspection where relevant.
+
+| Package | Ecosystem | License | Last verified activity | Relevant to this harness |
+|---|---|---|---|---|
+| `scoringrules` | Python/PyPI | Apache-2.0 | v0.11.0; GitHub and PyPI release-date metadata disagree — unresolved | Energy + variogram score, vector-valued only, no matrix awareness |
+| `properscoring` | Python/PyPI | Apache-2.0 | v0.1, 2015 — dead | Superseded by `scoringrules` |
+| `arch` (Sheppard) | Python/PyPI | NCSA | v8.0.0, actively maintained | `arch.bootstrap.CircularBlockBootstrap` — the canonical Python implementation this package reuses directly |
+| `tscv` / `timeseriescv` | Python/PyPI | BSD-3 / MIT | 2023 / 2018, stale | Gap-based CV splitters, not matrix-aware; `backtest_zero_overlap`'s own mechanics are thin enough not to depend on either |
+| `mlfinlab` (Hudson & Thames) | Python/PyPI | closed-source, paid | confirmed live | López de Prado's own purged/embargoed K-fold code — no longer usable as a free dependency |
+| `dieboldmariano` | Python/PyPI | MIT | v1.1.0, Jan 2025 | Standalone DM test, scalar loss series — vendored instead (see below) |
+| `model-confidence-set` (JLDC) | Python/GitHub only | MIT | 21★, no PyPI release | Only maintained Python MCS port found — also the flimsiest dependency in the whole survey; vendored instead |
+| `scoringRules` | R/CRAN | GPL-2/3 | v1.1.3, 2024-09-18 | Vector-valued energy score only, same matrix gap as the Python side |
+| `MCS` (Catania) | R/CRAN | GPL-2 | v0.2.0, **2026-03-19** | Canonical Hansen et al. (2011) MCS — the best-maintained MCS implementation in either language; used as a development-time oracle |
+| `multDM` | R/CRAN | GPL-3 | v1.1.5, 2025-03-08 | Multivariate DM test |
+| `forecast::dm.test` | R (base ecosystem) | — | long-established | Canonical scalar DM test in R; used as this package's `diebold_mariano` development-time oracle |
+
+**The gap check, adversarially searched, not falsified.** Targeted searches
+("correlation matrix forecast evaluation package," "covariance forecast
+backtesting python," "regime-switching correlation model validation
+software," GitHub topic search on `covariance-matrix`) turned up no
+package, in either language, that treats a correlation or covariance
+matrix as the forecast object with purge-aware walk-forward splitting and
+a proper scoring rule built in.
+
+## Dependency decisions (mirrors `README.md`'s own table)
+
+| Package | Role in `corrscore` | Decision |
+|---|---|---|
+| `numpy`, `scipy` | array math, `hyp1f1`/`gammaln`, `pdist` | dependency |
+| `arch` | `CircularBlockBootstrap` | dependency |
+| `scoringrules` | energy/variogram score math | vendored (`scoring.py`) |
+| `dieboldmariano` | DM test | vendored (`diebold_mariano.py`), oracle-checked against `forecast::dm.test` |
+| `model-confidence-set` | Model Confidence Set | vendored (`mcs.py`), verdict-checked against `MCS::MCSprocedure` |

corrscore-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "corrscore"
+version = "0.1.0"
+description = "Matrix-aware proper-scoring-rule backtesting for correlation and covariance forecasts: zero-overlap walk-forward evaluation, energy/variogram scoring, and significance testing (block bootstrap, Diebold-Mariano, Model Confidence Set)."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "Vinh Nguyen", email = "vinhnguyen3455@gmail.com" },
+]
+requires-python = ">=3.10"
+dependencies = [
+    "numpy>=1.24",
+    "scipy>=1.10",
+    "arch>=6.3",
+]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Intended Audience :: Financial and Insurance Industry",
+    "Intended Audience :: Science/Research",
+    "Topic :: Office/Business :: Financial :: Investment",
+    "Topic :: Scientific/Engineering :: Mathematics",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "hypothesis>=6.100",
+    "mypy>=1.10",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/corrscore"]
+
+[tool.mypy]
+warn_unused_configs = true
+ignore_missing_imports = true

corrscore-0.1.0/src/corrscore/__init__.py

@@ -0,0 +1,21 @@
+from .backtest import BacktestResult, backtest_zero_overlap
+from .bootstrap import BootstrapResult, circular_block_bootstrap
+from .diebold_mariano import DieboldMarianoResult, diebold_mariano
+from .mcs import MCSResult, model_confidence_set
+from .scoring import matrix_energy_score, matrix_geodesic_variogram_score, matrix_variogram_score
+from .utils import asymmetric_weighted_mean
+
+__all__ = [
+    "matrix_energy_score",
+    "matrix_variogram_score",
+    "matrix_geodesic_variogram_score",
+    "backtest_zero_overlap",
+    "BacktestResult",
+    "circular_block_bootstrap",
+    "BootstrapResult",
+    "diebold_mariano",
+    "DieboldMarianoResult",
+    "model_confidence_set",
+    "MCSResult",
+    "asymmetric_weighted_mean",
+]

corrscore-0.1.0/src/corrscore/backtest.py

@@ -0,0 +1,148 @@
+"""The zero-overlap walk-forward backtest driver.
+
+Design note: an earlier sketch of this API had a `window` parameter
+defaulting to `horizon`. Working through the actual mechanics precisely
+during implementation surfaced a cleaner, more honestly-scoped contract,
+documented here rather than silently substituted. This harness does not,
+and cannot, police how much history a caller's `forecast_fn` consults
+internally -- that model is opaque to the harness (it might be a
+full-history discounted filter, a short trailing window, or anything
+else), exactly the same responsibility boundary scikit-learn's
+`TimeSeriesSplit` leaves to the caller. What the harness genuinely *can*
+and does enforce, unconditionally, is that `ground_truth_fn` is always
+called with a start point strictly after the origin
+(`origin + 1 + purge_gap`), never a window that reaches back before or
+across it. That guards against a real class of bug this package exists
+to prevent: computing "ground truth" as a window *ending* near the
+origin rather than a window *starting* strictly after it, which silently
+leaks estimation-window information into the evaluation. This API makes
+that specific mistake structurally impossible to reproduce, since the
+caller never controls the start point passed to `ground_truth_fn`.
+"""
+from __future__ import annotations
+
+from typing import Any, Callable, Mapping, NamedTuple, Sequence
+
+import numpy as np
+import numpy.typing as npt
+
+from .scoring import matrix_energy_score
+
+ForecastFn = Callable[[int], Mapping[str, Any]]
+GroundTruthFn = Callable[[int, int], npt.ArrayLike]
+ScoreFn = Callable[[Mapping[str, Any], npt.ArrayLike], float]
+SeverityFn = Callable[[npt.NDArray[np.float64]], float]
+
+__all__ = ["BacktestResult", "backtest_zero_overlap"]
+
+
+class BacktestResult(NamedTuple):
+    """Result of `backtest_zero_overlap`.
+
+    Attributes
+    ----------
+    origins : list of int
+        The origins actually scored, in order.
+    scores : dict of str -> ndarray
+        Per-model, per-origin scores, one array per key of the
+        `forecast_fns` mapping passed in, aligned with `origins`.
+    severity : ndarray or None
+        Per-origin realized-severity values (`severity_fn(y)` at each
+        origin), or None if `severity_fn` was not supplied. Intended for
+        `corrscore.asymmetric_weighted_mean`.
+    horizon : int
+    purge_gap : int
+    """
+
+    origins: list[int]
+    scores: dict[str, npt.NDArray[np.float64]]
+    severity: npt.NDArray[np.float64] | None
+    horizon: int
+    purge_gap: int
+
+
+def backtest_zero_overlap(
+    forecast_fns: Mapping[str, ForecastFn] | ForecastFn,
+    ground_truth_fn: GroundTruthFn,
+    origins: Sequence[int],
+    horizon: int,
+    purge_gap: int = 0,
+    score_fn: ScoreFn = matrix_energy_score,
+    severity_fn: SeverityFn | None = None,
+) -> BacktestResult:
+    """Score one or more forecasting methods against a proper,
+    zero-overlap-by-construction ground truth.
+
+    For each `origin` in `origins`: computes
+    `y = ground_truth_fn(origin + 1 + purge_gap, origin + 1 + purge_gap
+    + horizon)`, then scores each `forecast_fns[name](origin)` against
+    `y` via `score_fn`. `purge_gap=0` (the default) gives zero shared
+    days between the forecast origin and the ground-truth window by
+    construction; a larger `purge_gap` is a deliberate relaxation the
+    caller must opt into explicitly -- never a silent default.
+
+    Parameters
+    ----------
+    forecast_fns : callable, or dict of str -> callable
+        Each callable maps an origin (int) to a forecast dict in the
+        shape `matrix_energy_score`/`matrix_variogram_score` expect
+        (see `corrscore.scoring`). A single callable is treated as
+        `{"model": forecast_fns}`. Sharing one `ground_truth_fn` call
+        per origin across every model is deliberate: ground truth is
+        model-independent and often the more expensive computation, and
+        this shape is exactly what `corrscore.circular_block_bootstrap`,
+        `corrscore.diebold_mariano`, and `corrscore.model_confidence_set`
+        expect as input (`result.scores[name]`).
+    ground_truth_fn : callable
+        `(start, end) -> K x K matrix`. Called only with
+        `start = origin + 1 + purge_gap`, `end = start + horizon` --
+        never anything else. It is the caller's responsibility that
+        this function computes a genuinely forward-looking realized
+        estimate from `[start, end)`, not a trailing one -- the timing
+        guard above prevents overlap, but not a `ground_truth_fn` that
+        is itself defined as a trailing window.
+    origins : sequence of int
+    horizon : int
+    purge_gap : int, default=0
+    score_fn : callable, default=matrix_energy_score
+    severity_fn : callable, optional
+        `y -> float`, a per-origin realized-severity summary (e.g. mean
+        absolute off-diagonal correlation) for later use with
+        `corrscore.asymmetric_weighted_mean`.
+
+    Returns
+    -------
+    BacktestResult
+    """
+    if callable(forecast_fns):
+        forecast_fns = {"model": forecast_fns}
+    if purge_gap < 0:
+        raise ValueError(f"purge_gap must be >= 0, got {purge_gap}")
+    if horizon < 1:
+        raise ValueError(f"horizon must be >= 1, got {horizon}")
+
+    names = list(forecast_fns.keys())
+    scores: dict[str, list[float]] = {name: [] for name in names}
+    severities: list[float] = []
+    used_origins: list[int] = []
+
+    for origin in origins:
+        start = origin + 1 + purge_gap
+        end = start + horizon
+        y = np.asarray(ground_truth_fn(start, end), dtype=float)
+        for name in names:
+            forecast = forecast_fns[name](origin)
+            scores[name].append(score_fn(forecast, y))
+        if severity_fn is not None:
+            severities.append(severity_fn(y))
+        used_origins.append(origin)
+
+    scores_arr = {name: np.array(values) for name, values in scores.items()}
+    severity_arr = np.array(severities) if severity_fn is not None else None
+    return BacktestResult(
+        origins=used_origins,
+        scores=scores_arr,
+        severity=severity_arr,
+        horizon=horizon,
+        purge_gap=purge_gap,
+    )