diff-diff 3.11.1__tar.gz → 3.12.0__tar.gz

{diff_diff-3.11.1 → diff_diff-3.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: diff-diff
-Version: 3.11.1
+Version: 3.12.0
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Science/Research
 Classifier: Operating System :: OS Independent
@@ -21,7 +21,7 @@ Requires-Dist: pytest>=7.0 ; extra == 'dev'
 Requires-Dist: pytest-xdist>=3.0 ; extra == 'dev'
 Requires-Dist: pytest-cov>=4.0 ; extra == 'dev'
 Requires-Dist: black==26.5.1 ; extra == 'dev'
-Requires-Dist: ruff==0.16.4 ; extra == 'dev'
+Requires-Dist: ruff==0.16.5 ; extra == 'dev'
 Requires-Dist: mypy==2.3.1 ; extra == 'dev'
 Requires-Dist: maturin>=1.4,<2.0 ; extra == 'dev'
 Requires-Dist: matplotlib>=3.5 ; extra == 'dev'
@@ -134,7 +134,7 @@ Measuring campaign lift? Evaluating a product launch? Rolling out a policy in wa
 - [Brand awareness survey tutorial](https://diff-diff.readthedocs.io/en/stable/tutorials/17_brand_awareness_survey.html) - full example with complex survey design, brand funnel analysis, and staggered rollouts
 - Have BRFSS/ACS/CPS individual records? Use [`aggregate_survey()`](https://diff-diff.readthedocs.io/en/stable/api/prep.html) to roll respondent-level microdata into a geographic-period panel with inverse-variance precision weights for second-stage DiD
 
-`BusinessReport` and `DiagnosticReport` are experimental preview classes that produce plain-English output and a structured `to_dict()` schema from any fitted result - wording and schema will evolve. See [docs/methodology/REPORTING.md](https://github.com/igerber/diff-diff/blob/main/docs/methodology/REPORTING.md) for usage and stability notes.
+`BusinessReport` and `DiagnosticReport` are experimental preview classes that produce plain-English output and a structured `to_dict()` schema from any fitted estimator result except the two rejected by type (`EventStudyResults` surfaces and `DurationDiDResults`) - wording and schema will evolve. See [docs/methodology/REPORTING.md](https://github.com/igerber/diff-diff/blob/main/docs/methodology/REPORTING.md) for usage and stability notes.
 
 ## Practitioner Workflow (Baker et al. 2025)
 
@@ -176,11 +176,13 @@ Full guide: `diff_diff.get_llm_guide("practitioner")`.
 - [LPDiD](https://diff-diff.readthedocs.io/en/stable/api/lpdid.html) - Dube, Girardi, Jorda & Taylor (2025) Local Projections DiD: per-horizon long-difference event study on clean controls (no negative weighting), variance- or equally-weighted ATT, for absorbing or non-absorbing (reversible) treatment
 - [ChangesInChanges](https://diff-diff.readthedocs.io/en/stable/api/changes_in_changes.html) - Athey & Imbens (2006) nonlinear/distributional DiD for the 2x2 design: full counterfactual distribution and quantile treatment effects via CDF transformation, plus the QDiD comparison estimator via `method="qdid"`; bootstrap inference; R qte parity. Alias `CiC`
 - [LWDiD](https://diff-diff.readthedocs.io/en/stable/api/lwdid.html) - Lee & Wooldridge (2025, 2026) rolling-transformation DiD: unit-specific demean/detrend converts panel to cross-section, staggered adoption, `estimation_method` in `reg`/`ipw`/`dr`/`psm` (the papers' RA/IPW/IPWRA plus propensity-score matching), exact small-N inference on the classical collapsed regression
-- [DMLDiD](https://diff-diff.readthedocs.io/en/stable/api/dml_did.html) - Chang (2020) double/debiased machine learning DiD: staggered ATT(g,t) with cross-fitted ML nuisance learners (DML2) and Neyman-orthogonal scores, for flexible/high-dimensional covariate adjustment under conditional parallel trends; panel or declared repeated cross sections (`panel=False`); survey/cluster support on both lanes
+- [DMLDiD](https://diff-diff.readthedocs.io/en/stable/api/dml_did.html) - Chang (2020) double/debiased machine learning DiD: staggered ATT(g,t) with cross-fitted ML nuisance learners (DML2) and Neyman-orthogonal scores, for flexible/high-dimensional covariate adjustment under conditional parallel trends; panel or declared repeated cross sections (`panel=False`); survey/cluster support on both lanes (bad-control lane: panel only, `cluster=` only); Caetano, Callaway, Payne & Sant'Anna (2026) bad-control score via `fit(bad_control=, bad_control_covariates=)`
+- [DurationDiD](https://diff-diff.readthedocs.io/en/stable/api/duration_did.html) - Deaner & Ku (2026) causal duration DiD for a binary absorbing outcome (spell ended) in a two-group common-timing design: restricts the groups' untreated hazards (`method="cd"` additive gap or `method="ph"` ratio) instead of outcome levels, imputes the treated counterfactual survival, reports the per-date absorption ATT with whole-individual bootstrap pointwise and simultaneous bands plus a fixed-anchor pre-treatment specification test
 - [BaconDecomposition](https://diff-diff.readthedocs.io/en/stable/api/bacon.html) - Goodman-Bacon (2021) decomposition for diagnosing TWFE bias in staggered settings
 
 ## Diagnostics & Sensitivity
 
+- [Bad-control pre-test](https://diff-diff.readthedocs.io/en/stable/api/dml_did.html) - Caetano, Callaway, Payne & Sant'Anna (2026) Remark 6 `ATT_X(g,t)`: the effect of treatment on a suspected bad control itself, per (g,t) cell (`DMLDiDResults.bad_control_summary()`; analytical SE; pre-period rows pre-test the identifying assumptions MP-5 / MP-8 and should be zero, post-period rows are the Condition-2 check that treatment affects the covariate)
 - [RD Plots](https://diff-diff.readthedocs.io/en/stable/api/regression_discontinuity.html) - Calonico, Cattaneo & Titiunik (2015) optimal data-driven RD plots (`RDPlot`): all 8 rdrobust `binselect` bin selectors, implied-scale/WIMSE-weight reporting, optional matplotlib rendering
 - [Manipulation Testing](https://diff-diff.readthedocs.io/en/stable/api/regression_discontinuity.html) - Cattaneo, Jansson & Ma (2020) density-discontinuity test (`RDDensityTest`): rddensity 3.0 parity, robust bias-corrected inference, unrestricted/restricted models, mass-point adjustment
 - [Parallel Trends Testing](https://diff-diff.readthedocs.io/en/stable/api/diagnostics.html) - simple and Wasserstein-robust parallel trends tests, equivalence testing (TOST)

{diff_diff-3.11.1 → diff_diff-3.12.0}/README.md

@@ -79,7 +79,7 @@ Measuring campaign lift? Evaluating a product launch? Rolling out a policy in wa
 - [Brand awareness survey tutorial](https://diff-diff.readthedocs.io/en/stable/tutorials/17_brand_awareness_survey.html) - full example with complex survey design, brand funnel analysis, and staggered rollouts
 - Have BRFSS/ACS/CPS individual records? Use [`aggregate_survey()`](https://diff-diff.readthedocs.io/en/stable/api/prep.html) to roll respondent-level microdata into a geographic-period panel with inverse-variance precision weights for second-stage DiD
 
-`BusinessReport` and `DiagnosticReport` are experimental preview classes that produce plain-English output and a structured `to_dict()` schema from any fitted result - wording and schema will evolve. See [docs/methodology/REPORTING.md](https://github.com/igerber/diff-diff/blob/main/docs/methodology/REPORTING.md) for usage and stability notes.
+`BusinessReport` and `DiagnosticReport` are experimental preview classes that produce plain-English output and a structured `to_dict()` schema from any fitted estimator result except the two rejected by type (`EventStudyResults` surfaces and `DurationDiDResults`) - wording and schema will evolve. See [docs/methodology/REPORTING.md](https://github.com/igerber/diff-diff/blob/main/docs/methodology/REPORTING.md) for usage and stability notes.
 
 ## Practitioner Workflow (Baker et al. 2025)
 
@@ -121,11 +121,13 @@ Full guide: `diff_diff.get_llm_guide("practitioner")`.
 - [LPDiD](https://diff-diff.readthedocs.io/en/stable/api/lpdid.html) - Dube, Girardi, Jorda & Taylor (2025) Local Projections DiD: per-horizon long-difference event study on clean controls (no negative weighting), variance- or equally-weighted ATT, for absorbing or non-absorbing (reversible) treatment
 - [ChangesInChanges](https://diff-diff.readthedocs.io/en/stable/api/changes_in_changes.html) - Athey & Imbens (2006) nonlinear/distributional DiD for the 2x2 design: full counterfactual distribution and quantile treatment effects via CDF transformation, plus the QDiD comparison estimator via `method="qdid"`; bootstrap inference; R qte parity. Alias `CiC`
 - [LWDiD](https://diff-diff.readthedocs.io/en/stable/api/lwdid.html) - Lee & Wooldridge (2025, 2026) rolling-transformation DiD: unit-specific demean/detrend converts panel to cross-section, staggered adoption, `estimation_method` in `reg`/`ipw`/`dr`/`psm` (the papers' RA/IPW/IPWRA plus propensity-score matching), exact small-N inference on the classical collapsed regression
-- [DMLDiD](https://diff-diff.readthedocs.io/en/stable/api/dml_did.html) - Chang (2020) double/debiased machine learning DiD: staggered ATT(g,t) with cross-fitted ML nuisance learners (DML2) and Neyman-orthogonal scores, for flexible/high-dimensional covariate adjustment under conditional parallel trends; panel or declared repeated cross sections (`panel=False`); survey/cluster support on both lanes
+- [DMLDiD](https://diff-diff.readthedocs.io/en/stable/api/dml_did.html) - Chang (2020) double/debiased machine learning DiD: staggered ATT(g,t) with cross-fitted ML nuisance learners (DML2) and Neyman-orthogonal scores, for flexible/high-dimensional covariate adjustment under conditional parallel trends; panel or declared repeated cross sections (`panel=False`); survey/cluster support on both lanes (bad-control lane: panel only, `cluster=` only); Caetano, Callaway, Payne & Sant'Anna (2026) bad-control score via `fit(bad_control=, bad_control_covariates=)`
+- [DurationDiD](https://diff-diff.readthedocs.io/en/stable/api/duration_did.html) - Deaner & Ku (2026) causal duration DiD for a binary absorbing outcome (spell ended) in a two-group common-timing design: restricts the groups' untreated hazards (`method="cd"` additive gap or `method="ph"` ratio) instead of outcome levels, imputes the treated counterfactual survival, reports the per-date absorption ATT with whole-individual bootstrap pointwise and simultaneous bands plus a fixed-anchor pre-treatment specification test
 - [BaconDecomposition](https://diff-diff.readthedocs.io/en/stable/api/bacon.html) - Goodman-Bacon (2021) decomposition for diagnosing TWFE bias in staggered settings
 
 ## Diagnostics & Sensitivity
 
+- [Bad-control pre-test](https://diff-diff.readthedocs.io/en/stable/api/dml_did.html) - Caetano, Callaway, Payne & Sant'Anna (2026) Remark 6 `ATT_X(g,t)`: the effect of treatment on a suspected bad control itself, per (g,t) cell (`DMLDiDResults.bad_control_summary()`; analytical SE; pre-period rows pre-test the identifying assumptions MP-5 / MP-8 and should be zero, post-period rows are the Condition-2 check that treatment affects the covariate)
 - [RD Plots](https://diff-diff.readthedocs.io/en/stable/api/regression_discontinuity.html) - Calonico, Cattaneo & Titiunik (2015) optimal data-driven RD plots (`RDPlot`): all 8 rdrobust `binselect` bin selectors, implied-scale/WIMSE-weight reporting, optional matplotlib rendering
 - [Manipulation Testing](https://diff-diff.readthedocs.io/en/stable/api/regression_discontinuity.html) - Cattaneo, Jansson & Ma (2020) density-discontinuity test (`RDDensityTest`): rddensity 3.0 parity, robust bias-corrected inference, unrestricted/restricted models, mass-point adjustment
 - [Parallel Trends Testing](https://diff-diff.readthedocs.io/en/stable/api/diagnostics.html) - simple and Wasserstein-robust parallel trends tests, equivalence testing (TOST)

{diff_diff-3.11.1 → diff_diff-3.12.0}/diff_diff/__init__.py

@@ -98,6 +98,8 @@ from diff_diff.diagnostics import (
 )
 from diff_diff.dml_did import DMLDiD
 from diff_diff.dml_did_results import DMLDiDResults
+from diff_diff.duration_did import DurationDiD
+from diff_diff.duration_did_results import DurationDiDPretestResults, DurationDiDResults
 from diff_diff.efficient_did import (
     EDiDBootstrapResults,
     EfficientDiD,
@@ -371,7 +373,7 @@ def __getattr__(name: str) -> _Any:
     raise AttributeError(f"module 'diff_diff' has no attribute {name!r}")
 
 
-__version__ = "3.11.1"
+__version__ = "3.12.0"
 __all__ = [
     # Estimators
     "DifferenceInDifferences",
@@ -471,6 +473,10 @@ __all__ = [
     "DMLDiD",
     "DMLDiDResults",
     "SieveLearner",
+    # DurationDiD (Deaner & Ku 2026 causal duration DiD)
+    "DurationDiD",
+    "DurationDiDResults",
+    "DurationDiDPretestResults",
     # Visualization
     "plot_bacon",
     "plot_event_study",

{diff_diff-3.11.1 → diff_diff-3.12.0}/diff_diff/_backend.py

@@ -114,13 +114,13 @@ try:
 except ImportError:
     _rust_batched_ridge_chol_solve = None
 
-# HC2 (leverage-corrected) robust vcov: imported independently for the same
-# mixed-version reason as demean_map (a stale extension missing only this
-# newer symbol degrades HC2 to the NumPy path without disabling the older
-# Rust accelerations).
+# HC2 requires the v2 fail-closed leverage contract. An older extension can
+# export the original symbol yet return finite covariance at unit leverage,
+# so symbol presence alone is insufficient. Import v2 independently: legacy
+# extensions use NumPy HC2 while retaining every other Rust acceleration.
 try:
     from diff_diff._rust_backend import (
-        compute_robust_vcov_hc2 as _rust_compute_robust_vcov_hc2,
+        compute_robust_vcov_hc2_v2 as _rust_compute_robust_vcov_hc2,
     )
 except ImportError:
     _rust_compute_robust_vcov_hc2 = None

{diff_diff-3.11.1 → diff_diff-3.12.0}/diff_diff/_crossfit.py

@@ -35,7 +35,7 @@ import copy
 import pickle
 import warnings
 from dataclasses import dataclass, field
-from typing import Any, Dict, Iterator, Literal, Optional, Tuple, cast, overload
+from typing import Any, Dict, Iterator, Literal, NamedTuple, Optional, Tuple, cast, overload
 
 import numpy as np
 import pandas as pd
@@ -53,12 +53,14 @@ __all__ = [
     "CrossFitResult",
     "assign_folds",
     "cross_fit_predict",
+    "FoldFit",
+    "iter_fold_fits",
 ]
 
 _LOG_LOSS_CLIP = 1e-15
 
 
-def _fresh_learner(learner: Any) -> Any:
+def _fresh_learner(learner: Any, *, stacklevel: int) -> Any:
     """Per-fold learner isolation: a deep copy of the (never-fit) template.
 
     ``copy.deepcopy`` of the user's template gives every fold a fully
@@ -70,7 +72,10 @@ def _fresh_learner(learner: Any) -> Any:
     a container parameter). The template itself is never fit. A copy FAILURE
     is never silent: the instance is reused with a loud ``UserWarning`` naming
     the learner and the fit-reset assumption now being relied on
-    (no-silent-failures rule).
+    (no-silent-failures rule). ``stacklevel`` is supplied by the caller so the
+    warning is attributed to the entry point's own caller (``cross_fit_predict``
+    passes the level that lands on the user's call site; internal consumers
+    of ``iter_fold_fits`` pass the level that lands on themselves).
     """
     try:
         return copy.deepcopy(learner)
@@ -80,14 +85,14 @@ def _fresh_learner(learner: Any) -> Any:
         # and this warning lands in notebook/CI logs (the same boundary as
         # DMLDiD's persisted-diagnostics sanitization).
         warnings.warn(
-            f"cross_fit_predict: could not deep-copy the "
+            f"_crossfit: could not deep-copy the "
             f"{type(learner).__name__} template for this fold "
             f"({type(exc).__name__}); "
             "REUSING the same instance and relying on its fit-reset behavior. "
             "A warm-start/stateful learner in this situation can leak data "
             "across folds.",
             UserWarning,
-            stacklevel=3,
+            stacklevel=stacklevel,
         )
         return learner
 
@@ -404,55 +409,45 @@ def assign_folds(
     )
 
 
-@overload
-def cross_fit_predict(
-    learner: RegressorLearner,
-    X: np.ndarray,
-    y: np.ndarray,
-    folds: FoldAssignment,
-    *,
-    fit_mask: Optional[np.ndarray] = ...,
-    predict_method: Literal["predict"] = ...,
-    sample_weight: Optional[np.ndarray] = ...,
-    context_label: str = ...,
-) -> CrossFitResult: ...
-
-
-@overload
-def cross_fit_predict(
-    learner: ClassifierLearner,
-    X: np.ndarray,
-    y: np.ndarray,
-    folds: FoldAssignment,
-    *,
-    fit_mask: Optional[np.ndarray] = ...,
-    predict_method: Literal["predict_proba"],
-    sample_weight: Optional[np.ndarray] = ...,
-    context_label: str = ...,
-) -> CrossFitResult: ...
+class FoldFit(NamedTuple):
+    """One fold's fitted learner plus the index sets it was built from.
 
+    Yielded by :func:`iter_fold_fits`. ``X`` / ``y`` / ``sample_weight`` are the
+    validated, float64-coerced arrays (so consumers index them positionally
+    exactly as :func:`cross_fit_predict` does); ``learner`` is the per-fold
+    deep copy already fit on ``fit_idx``; ``train_idx`` is fold ``k``'s full
+    training complement and ``test_idx`` the held-out fold.
+    """
 
-def cross_fit_predict(
+    k: int
+    learner: Any
+    fit_idx: np.ndarray
+    train_idx: np.ndarray
+    test_idx: np.ndarray
+    n_fit: int
+    w_fit: Optional[np.ndarray]
+    kind: str
+    label: str
+    X: np.ndarray
+    y: np.ndarray
+    sample_weight: Optional[np.ndarray]
+
+
+def _prepare_cross_fit_inputs(
     learner: object,
     X: np.ndarray,
     y: np.ndarray,
     folds: FoldAssignment,
     *,
-    fit_mask: Optional[np.ndarray] = None,
-    predict_method: str = "predict",
-    sample_weight: Optional[np.ndarray] = None,
-    context_label: str = "",
-) -> CrossFitResult:
-    """Out-of-fold predictions for every unit.
+    fit_mask: Optional[np.ndarray],
+    predict_method: str,
+    sample_weight: Optional[np.ndarray],
+) -> Tuple[np.ndarray, np.ndarray, np.ndarray, Optional[np.ndarray], str]:
+    """Argument validation shared by every cross-fit entry point.
 
-    Per fold k: fit the learner on ``train_mask(k) & fit_mask`` (e.g. the
-    untreated units), predict ALL units in fold k. ``context_label``
-    (e.g. the nuisance name or (g,t) cell) is prefixed into every
-    ``DegenerateFoldError`` message to identify WHICH cross-fit failed.
+    Own-argument failures raise plain ``ValueError`` (the module contract).
     """
     n_units = folds.n_units
-    label = f"{context_label}: " if context_label else ""
-
     if predict_method not in ("predict", "predict_proba"):
         raise ValueError(
             f"predict_method must be 'predict' or 'predict_proba', got {predict_method!r}"
@@ -491,20 +486,19 @@ def cross_fit_predict(
             )
         fit_mask_arr = raw_mask
 
+    sw: Optional[np.ndarray] = None
     if sample_weight is not None:
-        sample_weight = np.asarray(sample_weight, dtype=np.float64)
-        if sample_weight.ndim != 1:
+        sw = np.asarray(sample_weight, dtype=np.float64)
+        if sw.ndim != 1:
             raise ValueError(
-                f"sample_weight must be 1-dimensional, got ndim={sample_weight.ndim} "
+                f"sample_weight must be 1-dimensional, got ndim={sw.ndim} "
                 "(a column vector like (n, 1) is not accepted)"
             )
-        if sample_weight.shape[0] != n_units:
-            raise ValueError(
-                f"sample_weight has length {sample_weight.shape[0]}, expected {n_units}"
-            )
-        if not np.isfinite(sample_weight).all():
+        if sw.shape[0] != n_units:
+            raise ValueError(f"sample_weight has length {sw.shape[0]}, expected {n_units}")
+        if not np.isfinite(sw).all():
             raise ValueError("sample_weight contains NaN or Inf values")
-        if np.any(sample_weight < 0):
+        if np.any(sw < 0):
             raise ValueError("sample_weight must be non-negative")
 
     if predict_method == "predict_proba" and not np.all((y == 0.0) | (y == 1.0)):
@@ -512,91 +506,294 @@ def cross_fit_predict(
             "y must be strictly binary 0/1 for predict_method='predict_proba' "
             "(the logit solver silently saturates on other encodings)"
         )
+    return X, y, fit_mask_arr, sw, kind
 
-    oof = np.empty(n_units, dtype=np.float64)
-    fold_losses = np.empty(folds.n_folds, dtype=np.float64)
-    n_fit_per_fold = np.empty(folds.n_folds, dtype=np.int64)
 
-    for k, train_idx, test_idx in folds.iter_folds():
-        fit_idx = train_idx[fit_mask_arr[train_idx]]
-        n_fit = fit_idx.shape[0]
-        n_fit_per_fold[k] = n_fit
-        w_fit = None if sample_weight is None else sample_weight[fit_idx]
+def _learner_error(
+    exc: ValueError, *, k: int, label: str, n_fit: int, w_fit: Optional[np.ndarray]
+) -> DegenerateFoldError:
+    return DegenerateFoldError(
+        f"{label}learner error in fold {k}: {exc}; the fold's fit subset "
+        f"has n={n_fit}"
+        + (f", n_pos_weight={int(np.sum(w_fit > 0))}" if w_fit is not None else "")
+        + ". Reduce n_folds, widen fit_mask, or check the fold's data."
+    )
 
-        # (a) Universal cheap pre-checks -> DegenerateFoldError directly.
-        if n_fit == 0:
-            raise DegenerateFoldError(
-                f"{label}fold {k}: the fit subset is empty (train size "
-                f"{train_idx.shape[0]}, fit_mask keeps 0). Reduce n_folds, widen "
-                "fit_mask, or check the stratify labels."
-            )
-        if w_fit is not None and not np.any(w_fit > 0):
+
+def _fit_subset(
+    learner: object,
+    X: np.ndarray,
+    y: np.ndarray,
+    fit_idx: np.ndarray,
+    *,
+    n_train: int,
+    kind: str,
+    sample_weight: Optional[np.ndarray],
+    k: int,
+    label: str,
+    warn_stacklevel: int,
+) -> Tuple[Any, int, Optional[np.ndarray]]:
+    """Fit a fresh deep copy of ``learner`` on ``fit_idx`` (fold ``k``).
+
+    Universal degeneracy pre-checks raise ``DegenerateFoldError`` directly; a
+    learner ``ValueError`` is re-raised as ``DegenerateFoldError`` chained via
+    ``raise ... from exc``; a learner-raised ``DegenerateFoldError`` passes
+    through unwrapped. Returns ``(fitted_learner, n_fit, w_fit)``.
+    """
+    n_fit = int(fit_idx.shape[0])
+    w_fit = None if sample_weight is None else sample_weight[fit_idx]
+
+    # (a) Universal cheap pre-checks -> DegenerateFoldError directly.
+    if n_fit == 0:
+        raise DegenerateFoldError(
+            f"{label}fold {k}: the fit subset is empty (train size "
+            f"{n_train}, fit_mask keeps 0). Reduce n_folds, widen "
+            "fit_mask, or check the stratify labels."
+        )
+    if w_fit is not None and not np.any(w_fit > 0):
+        raise DegenerateFoldError(
+            f"{label}fold {k}: all {n_fit} fit rows have zero sample_weight. "
+            "Reduce n_folds or check the weights."
+        )
+    if kind == "classifier":
+        labels = y[fit_idx] if w_fit is None else y[fit_idx][w_fit > 0]
+        if np.unique(labels).shape[0] < 2:
             raise DegenerateFoldError(
-                f"{label}fold {k}: all {n_fit} fit rows have zero sample_weight. "
-                "Reduce n_folds or check the weights."
+                f"{label}fold {k}: the fit subset has a single "
+                f"{'positive-weight ' if w_fit is not None else ''}class "
+                f"(n_fit={n_fit}). A classifier needs both classes in every "
+                "fold's complement; reduce n_folds or stratify by the label."
             )
-        if predict_method == "predict_proba":
-            labels = y[fit_idx] if w_fit is None else y[fit_idx][w_fit > 0]
-            if np.unique(labels).shape[0] < 2:
-                raise DegenerateFoldError(
-                    f"{label}fold {k}: the fit subset has a single "
-                    f"{'positive-weight ' if w_fit is not None else ''}class "
-                    f"(n_fit={n_fit}). A classifier needs both classes in every "
-                    "fold's complement; reduce n_folds or stratify by the label."
-                )
 
-        # (b) Learner errors during the fold -> DegenerateFoldError, chained.
-        try:
-            fold_learner = _fresh_learner(learner)
-            # Unweighted path calls fit(X, y) WITHOUT the keyword: the
-            # advertised duck-typed contract is fit/predict(_proba), so a
-            # learner whose fit signature is only (X, y) must work when no
-            # weights are in play. sample_weight= is passed only on
-            # genuinely weighted paths, where an unsupported signature
-            # raises TypeError — a caller protocol violation that PROPAGATES
-            # (the DegenerateFoldError wrapper below catches ValueError
-            # only; fold-data degeneracy, not signature bugs).
-            fit_kwargs = {} if w_fit is None else {"sample_weight": w_fit}
-            if kind == "regressor":
-                reg = cast(RegressorLearner, fold_learner)
-                reg.fit(X[fit_idx], y[fit_idx], **fit_kwargs)
-                raw_pred = reg.predict(X[test_idx])
-            else:
-                clf = cast(ClassifierLearner, fold_learner)
-                clf.fit(X[fit_idx], y[fit_idx], **fit_kwargs)
-                raw_pred = clf.predict_proba(X[test_idx])
-            pred = _validate_predictions(
-                raw_pred,
-                test_idx.shape[0],
-                kind=kind,
-                context=f"{label}fold {k}",
-                classes=(getattr(fold_learner, "classes_", None) if kind == "classifier" else None),
-            )
-        except DegenerateFoldError:
-            raise
-        except ValueError as exc:
-            raise DegenerateFoldError(
-                f"{label}learner error in fold {k}: {exc}; the fold's fit subset "
-                f"has n={n_fit}"
-                + (f", n_pos_weight={int(np.sum(w_fit > 0))}" if w_fit is not None else "")
-                + ". Reduce n_folds, widen fit_mask, or check the fold's data."
-            ) from exc
-
-        oof[test_idx] = pred
-
-        # Out-of-fold loss (diagnostic; NaN sentinel for zero-weight folds).
-        w_test = None if sample_weight is None else sample_weight[test_idx]
-        if predict_method == "predict":
-            errs = (y[test_idx] - pred) ** 2
+    # (b) Learner errors during the fold -> DegenerateFoldError, chained.
+    try:
+        fold_learner = _fresh_learner(learner, stacklevel=warn_stacklevel)
+        # Unweighted path calls fit(X, y) WITHOUT the keyword: the
+        # advertised duck-typed contract is fit/predict(_proba), so a
+        # learner whose fit signature is only (X, y) must work when no
+        # weights are in play. sample_weight= is passed only on
+        # genuinely weighted paths, where an unsupported signature
+        # raises TypeError — a caller protocol violation that PROPAGATES
+        # (the DegenerateFoldError wrapper below catches ValueError
+        # only; fold-data degeneracy, not signature bugs).
+        fit_kwargs = {} if w_fit is None else {"sample_weight": w_fit}
+        if kind == "regressor":
+            cast(RegressorLearner, fold_learner).fit(X[fit_idx], y[fit_idx], **fit_kwargs)
         else:
-            p_clip = np.clip(pred, _LOG_LOSS_CLIP, 1.0 - _LOG_LOSS_CLIP)
-            errs = -(y[test_idx] * np.log(p_clip) + (1.0 - y[test_idx]) * np.log(1.0 - p_clip))
-        if w_test is None:
-            fold_losses[k] = float(np.mean(errs))
-        elif np.sum(w_test) > 0:
-            fold_losses[k] = float(np.sum(w_test * errs) / np.sum(w_test))
+            cast(ClassifierLearner, fold_learner).fit(X[fit_idx], y[fit_idx], **fit_kwargs)
+    except DegenerateFoldError:
+        raise
+    except ValueError as exc:
+        raise _learner_error(exc, k=k, label=label, n_fit=n_fit, w_fit=w_fit) from exc
+    return fold_learner, n_fit, w_fit
+
+
+def _predict_subset(
+    fold_learner: Any,
+    X_rows: np.ndarray,
+    *,
+    kind: str,
+    k: int,
+    label: str,
+    n_fit: int,
+    w_fit: Optional[np.ndarray],
+) -> np.ndarray:
+    """Predict ``X_rows`` with a fitted fold learner and validate the output.
+
+    Same exception contract as :func:`_fit_subset` (chained
+    ``DegenerateFoldError`` on a learner ``ValueError``; pass-through of a
+    learner-raised ``DegenerateFoldError``).
+    """
+    try:
+        if kind == "regressor":
+            raw_pred = cast(RegressorLearner, fold_learner).predict(X_rows)
         else:
-            fold_losses[k] = np.nan
+            raw_pred = cast(ClassifierLearner, fold_learner).predict_proba(X_rows)
+        return _validate_predictions(
+            raw_pred,
+            X_rows.shape[0],
+            kind=kind,
+            context=f"{label}fold {k}",
+            classes=(getattr(fold_learner, "classes_", None) if kind == "classifier" else None),
+        )
+    except DegenerateFoldError:
+        raise
+    except ValueError as exc:
+        raise _learner_error(exc, k=k, label=label, n_fit=n_fit, w_fit=w_fit) from exc
+
+
+def _fold_loss(
+    kind: str, y_test: np.ndarray, pred: np.ndarray, w_test: Optional[np.ndarray]
+) -> float:
+    """Out-of-fold MSE (regressor) or log-loss (classifier); NaN for a zero-weight fold."""
+    if kind == "regressor":
+        errs = (y_test - pred) ** 2
+    else:
+        p_clip = np.clip(pred, _LOG_LOSS_CLIP, 1.0 - _LOG_LOSS_CLIP)
+        errs = -(y_test * np.log(p_clip) + (1.0 - y_test) * np.log(1.0 - p_clip))
+    if w_test is None:
+        return float(np.mean(errs))
+    if np.sum(w_test) > 0:
+        return float(np.sum(w_test * errs) / np.sum(w_test))
+    return float(np.nan)
+
+
+def _iter_fold_fits_impl(
+    learner: object,
+    X: np.ndarray,
+    y: np.ndarray,
+    folds: FoldAssignment,
+    fit_mask_arr: np.ndarray,
+    sample_weight: Optional[np.ndarray],
+    kind: str,
+    label: str,
+    warn_stacklevel: int,
+) -> Iterator[FoldFit]:
+    for k, train_idx, test_idx in folds.iter_folds():
+        fit_idx = train_idx[fit_mask_arr[train_idx]]
+        fitted, n_fit, w_fit = _fit_subset(
+            learner,
+            X,
+            y,
+            fit_idx,
+            n_train=int(train_idx.shape[0]),
+            kind=kind,
+            sample_weight=sample_weight,
+            k=k,
+            label=label,
+            warn_stacklevel=warn_stacklevel,
+        )
+        yield FoldFit(
+            k=k,
+            learner=fitted,
+            fit_idx=fit_idx,
+            train_idx=train_idx,
+            test_idx=test_idx,
+            n_fit=n_fit,
+            w_fit=w_fit,
+            kind=kind,
+            label=label,
+            X=X,
+            y=y,
+            sample_weight=sample_weight,
+        )
+
+
+def iter_fold_fits(
+    learner: object,
+    X: np.ndarray,
+    y: np.ndarray,
+    folds: FoldAssignment,
+    *,
+    fit_mask: Optional[np.ndarray] = None,
+    predict_method: str = "predict",
+    sample_weight: Optional[np.ndarray] = None,
+    context_label: str = "",
+    warn_stacklevel: int = 4,
+) -> Iterator[FoldFit]:
+    """Per-fold fitted learners (the building block under ``cross_fit_predict``).
+
+    Validation runs EAGERLY at the call (not at the first ``__next__``), then
+    the returned iterator yields one :class:`FoldFit` per fold in ascending
+    ``k``, each holding a fresh deep copy of ``learner`` fit on
+    ``train_mask(k) & fit_mask``. Predictions are the caller's job via
+    ``_predict_subset``; this is what lets a consumer fit a NESTED nuisance on
+    fold ``k``'s own training units. ``warn_stacklevel`` is the frame the
+    deep-copy-failure warning is attributed to (default: the frame advancing
+    the iterator).
+    """
+    X64, y64, fit_mask_arr, sw, kind = _prepare_cross_fit_inputs(
+        learner,
+        X,
+        y,
+        folds,
+        fit_mask=fit_mask,
+        predict_method=predict_method,
+        sample_weight=sample_weight,
+    )
+    label = f"{context_label}: " if context_label else ""
+    return _iter_fold_fits_impl(
+        learner, X64, y64, folds, fit_mask_arr, sw, kind, label, warn_stacklevel
+    )
+
+
+@overload
+def cross_fit_predict(
+    learner: RegressorLearner,
+    X: np.ndarray,
+    y: np.ndarray,
+    folds: FoldAssignment,
+    *,
+    fit_mask: Optional[np.ndarray] = ...,
+    predict_method: Literal["predict"] = ...,
+    sample_weight: Optional[np.ndarray] = ...,
+    context_label: str = ...,
+) -> CrossFitResult: ...
+
+
+@overload
+def cross_fit_predict(
+    learner: ClassifierLearner,
+    X: np.ndarray,
+    y: np.ndarray,
+    folds: FoldAssignment,
+    *,
+    fit_mask: Optional[np.ndarray] = ...,
+    predict_method: Literal["predict_proba"],
+    sample_weight: Optional[np.ndarray] = ...,
+    context_label: str = ...,
+) -> CrossFitResult: ...
+
+
+def cross_fit_predict(
+    learner: object,
+    X: np.ndarray,
+    y: np.ndarray,
+    folds: FoldAssignment,
+    *,
+    fit_mask: Optional[np.ndarray] = None,
+    predict_method: str = "predict",
+    sample_weight: Optional[np.ndarray] = None,
+    context_label: str = "",
+) -> CrossFitResult:
+    """Out-of-fold predictions for every unit.
+
+    Per fold k: fit the learner on ``train_mask(k) & fit_mask`` (e.g. the
+    untreated units), predict ALL units in fold k. ``context_label``
+    (e.g. the nuisance name or (g,t) cell) is prefixed into every
+    ``DegenerateFoldError`` message to identify WHICH cross-fit failed.
+    """
+    n_units = folds.n_units
+    oof = np.empty(n_units, dtype=np.float64)
+    fold_losses = np.empty(folds.n_folds, dtype=np.float64)
+    n_fit_per_fold = np.empty(folds.n_folds, dtype=np.int64)
+
+    # stacklevel 5: _fresh_learner -> _fit_subset -> generator frame ->
+    # cross_fit_predict -> the user's call site.
+    for ff in iter_fold_fits(
+        learner,
+        X,
+        y,
+        folds,
+        fit_mask=fit_mask,
+        predict_method=predict_method,
+        sample_weight=sample_weight,
+        context_label=context_label,
+        warn_stacklevel=5,
+    ):
+        n_fit_per_fold[ff.k] = ff.n_fit
+        pred = _predict_subset(
+            ff.learner,
+            ff.X[ff.test_idx],
+            kind=ff.kind,
+            k=ff.k,
+            label=ff.label,
+            n_fit=ff.n_fit,
+            w_fit=ff.w_fit,
+        )
+        oof[ff.test_idx] = pred
+        w_test = None if ff.sample_weight is None else ff.sample_weight[ff.test_idx]
+        fold_losses[ff.k] = _fold_loss(ff.kind, ff.y[ff.test_idx], pred, w_test)
 
     return CrossFitResult(
         oof_predictions=oof,