diff-diff 3.5.0__tar.gz → 3.5.2__tar.gz

{diff_diff-3.5.0 → diff_diff-3.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: diff-diff
-Version: 3.5.0
+Version: 3.5.2
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Science/Research
 Classifier: Operating System :: OS Independent
@@ -161,11 +161,11 @@ Full guide: `diff_diff.get_llm_guide("practitioner")`.
 - [TwoStageDiD](https://diff-diff.readthedocs.io/en/stable/api/two_stage.html) - Gardner (2022) two-stage estimator with GMM sandwich variance
 - [SpilloverDiD](https://diff-diff.readthedocs.io/en/stable/api/spillover.html) - Butts (2021) ring-indicator spillover-aware DiD identifying direct effect on treated + per-ring spillover on near-control units; handles non-staggered and staggered timing; supports survey-design variance under `survey_design=` for HC1 / CR1 (Wave E.1 Binder TSL) and Conley (Wave E.2 panel-aware stratified-Conley sandwich on per-period PSU totals; extended in Wave E.2 follow-up to `conley_lag_cutoff > 0` via panel-block composition with within-PSU serial Bartlett HAC — `lag>0` requires an effective PSU via explicit `survey_design.psu` or injected `cluster=<col>`); `SurveyDesign.subpopulation()` preserves full-design `n_psu` / `df_survey` via zero-padded scores (Wave E.3, R `svyrecvar(subset())` form)
 - [SyntheticDiD](https://diff-diff.readthedocs.io/en/stable/api/estimators.html) - Synthetic DiD combining standard DiD and synthetic control for few treated units
-- [SyntheticControl](https://diff-diff.readthedocs.io/en/stable/api/synthetic_control.html) - Abadie, Diamond & Hainmueller (2010) classic synthetic control for a single treated unit (donor-weight counterfactual, nested/custom V; in-space placebo permutation inference via `in_space_placebo()`)
+- [SyntheticControl](https://diff-diff.readthedocs.io/en/stable/api/synthetic_control.html) - Abadie, Diamond & Hainmueller (2010) classic synthetic control for a single treated unit (donor-weight counterfactual, nested/cv/inverse-variance/custom V; in-space placebo permutation inference via `in_space_placebo()`, plus ADH-2015 `leave_one_out()` + `in_time_placebo()` robustness, Firpo-Possebom (2018) test-inversion confidence sets, and Chernozhukov-Wüthrich-Zhu (2021) conformal inference)
 - [TripleDifference](https://diff-diff.readthedocs.io/en/stable/api/triple_diff.html) - triple difference (DDD) estimator for designs requiring two criteria for treatment eligibility
 - [ContinuousDiD](https://diff-diff.readthedocs.io/en/stable/api/continuous_did.html) - Callaway, Goodman-Bacon & Sant'Anna (2024) continuous treatment DiD with dose-response curves
 - [HeterogeneousAdoptionDiD](https://diff-diff.readthedocs.io/en/stable/api/had.html) - de Chaisemartin, Ciccia, D'Haultfœuille & Knau (2026) for designs where **no unit remains untreated**; local-linear estimator at the dose support boundary returning Weighted Average Slope (WAS) on Design 1' (`d̲ = 0` / QUG) or `WAS_{d̲}` on Design 1 (`d̲ > 0`, continuous-near-d̲ or mass-point), with a multi-period event-study extension (last-treatment cohort, pointwise CIs). **Panel-only** in this release - repeated cross-sections rejected by the validator. Alias `HAD`.
-- [StackedDiD](https://diff-diff.readthedocs.io/en/stable/api/stacked_did.html) - Wing, Freedman & Hollingsworth (2024) stacked DiD with Q-weights and sub-experiments
+- [StackedDiD](https://diff-diff.readthedocs.io/en/stable/api/stacked_did.html) - Wing, Freedman & Hollingsworth (2024) stacked DiD with Q-weights and sub-experiments; optional covariate balancing (Ustyuzhanin 2026)
 - [EfficientDiD](https://diff-diff.readthedocs.io/en/stable/api/efficient_did.html) - Chen, Sant'Anna & Xie (2025) efficient DiD with optimal weighting for tighter SEs
 - [TROP](https://diff-diff.readthedocs.io/en/stable/api/trop.html) - Triply Robust Panel estimator (Athey et al. 2025) with nuclear norm factor adjustment
 - [StaggeredTripleDifference](https://diff-diff.readthedocs.io/en/stable/api/staggered.html#staggeredtripledifference) - Ortiz-Villavicencio & Sant'Anna (2025) staggered DDD with group-time ATT

{diff_diff-3.5.0 → diff_diff-3.5.2}/README.md

@@ -108,11 +108,11 @@ Full guide: `diff_diff.get_llm_guide("practitioner")`.
 - [TwoStageDiD](https://diff-diff.readthedocs.io/en/stable/api/two_stage.html) - Gardner (2022) two-stage estimator with GMM sandwich variance
 - [SpilloverDiD](https://diff-diff.readthedocs.io/en/stable/api/spillover.html) - Butts (2021) ring-indicator spillover-aware DiD identifying direct effect on treated + per-ring spillover on near-control units; handles non-staggered and staggered timing; supports survey-design variance under `survey_design=` for HC1 / CR1 (Wave E.1 Binder TSL) and Conley (Wave E.2 panel-aware stratified-Conley sandwich on per-period PSU totals; extended in Wave E.2 follow-up to `conley_lag_cutoff > 0` via panel-block composition with within-PSU serial Bartlett HAC — `lag>0` requires an effective PSU via explicit `survey_design.psu` or injected `cluster=<col>`); `SurveyDesign.subpopulation()` preserves full-design `n_psu` / `df_survey` via zero-padded scores (Wave E.3, R `svyrecvar(subset())` form)
 - [SyntheticDiD](https://diff-diff.readthedocs.io/en/stable/api/estimators.html) - Synthetic DiD combining standard DiD and synthetic control for few treated units
-- [SyntheticControl](https://diff-diff.readthedocs.io/en/stable/api/synthetic_control.html) - Abadie, Diamond & Hainmueller (2010) classic synthetic control for a single treated unit (donor-weight counterfactual, nested/custom V; in-space placebo permutation inference via `in_space_placebo()`)
+- [SyntheticControl](https://diff-diff.readthedocs.io/en/stable/api/synthetic_control.html) - Abadie, Diamond & Hainmueller (2010) classic synthetic control for a single treated unit (donor-weight counterfactual, nested/cv/inverse-variance/custom V; in-space placebo permutation inference via `in_space_placebo()`, plus ADH-2015 `leave_one_out()` + `in_time_placebo()` robustness, Firpo-Possebom (2018) test-inversion confidence sets, and Chernozhukov-Wüthrich-Zhu (2021) conformal inference)
 - [TripleDifference](https://diff-diff.readthedocs.io/en/stable/api/triple_diff.html) - triple difference (DDD) estimator for designs requiring two criteria for treatment eligibility
 - [ContinuousDiD](https://diff-diff.readthedocs.io/en/stable/api/continuous_did.html) - Callaway, Goodman-Bacon & Sant'Anna (2024) continuous treatment DiD with dose-response curves
 - [HeterogeneousAdoptionDiD](https://diff-diff.readthedocs.io/en/stable/api/had.html) - de Chaisemartin, Ciccia, D'Haultfœuille & Knau (2026) for designs where **no unit remains untreated**; local-linear estimator at the dose support boundary returning Weighted Average Slope (WAS) on Design 1' (`d̲ = 0` / QUG) or `WAS_{d̲}` on Design 1 (`d̲ > 0`, continuous-near-d̲ or mass-point), with a multi-period event-study extension (last-treatment cohort, pointwise CIs). **Panel-only** in this release - repeated cross-sections rejected by the validator. Alias `HAD`.
-- [StackedDiD](https://diff-diff.readthedocs.io/en/stable/api/stacked_did.html) - Wing, Freedman & Hollingsworth (2024) stacked DiD with Q-weights and sub-experiments
+- [StackedDiD](https://diff-diff.readthedocs.io/en/stable/api/stacked_did.html) - Wing, Freedman & Hollingsworth (2024) stacked DiD with Q-weights and sub-experiments; optional covariate balancing (Ustyuzhanin 2026)
 - [EfficientDiD](https://diff-diff.readthedocs.io/en/stable/api/efficient_did.html) - Chen, Sant'Anna & Xie (2025) efficient DiD with optimal weighting for tighter SEs
 - [TROP](https://diff-diff.readthedocs.io/en/stable/api/trop.html) - Triply Robust Panel estimator (Athey et al. 2025) with nuclear norm factor adjustment
 - [StaggeredTripleDifference](https://diff-diff.readthedocs.io/en/stable/api/staggered.html#staggeredtripledifference) - Ortiz-Villavicencio & Sant'Anna (2025) staggered DDD with group-time ATT

{diff_diff-3.5.0 → diff_diff-3.5.2}/diff_diff/__init__.py

@@ -298,7 +298,7 @@ ETWFE = WooldridgeDiD
 DCDH = ChaisemartinDHaultfoeuille
 HAD = HeterogeneousAdoptionDiD
 
-__version__ = "3.5.0"
+__version__ = "3.5.2"
 __all__ = [
     # Estimators
     "DifferenceInDifferences",

diff_diff-3.5.2/diff_diff/balancing.py

@@ -0,0 +1,209 @@
+"""Covariate balancing weights (entropy balancing).
+
+Implements **entropy balancing** (Hainmueller, J. (2012). "Entropy Balancing for
+Causal Effects: A Multivariate Reweighting Method to Produce Balanced Samples in
+Observational Studies." *Political Analysis*, 20(1), 25-46.
+https://doi.org/10.1093/pan/mpr025).
+
+Entropy balancing finds nonnegative control weights ``w_i`` that exactly match a set
+of target covariate moments (here: the treated-group covariate means) while staying as
+close as possible — in the Kullback-Leibler sense — to a set of base weights (uniform by
+default). The solution is obtained from the convex dual
+
+    minimize over λ:  L(λ) = log( Σ_i q_i exp(Z_iᵀ λ) ),   Z_i = X_i − target,
+
+whose stationary point ``∇L = Σ_i w_i Z_i = 0`` is exactly first-moment balance, with
+``w_i = q_i exp(Z_iᵀ λ) / Σ_j q_j exp(Z_jᵀ λ)``. ``L`` is convex (log-sum-exp), so a
+damped Newton iteration (gradient = weighted mean of the centered moments, Hessian =
+weighted covariance) converges to the balancing weights whenever the target lies in the
+interior of the control covariate convex hull; otherwise no finite λ balances the
+moments and the problem is **infeasible**.
+
+This module is dependency-light (numpy, with an optional scipy L-BFGS fallback) and is
+used by ``StackedDiD`` to construct the within-sub-experiment design weights ``b_{sa}``
+for Covariate-Balanced Weighted Stacked DID (Ustyuzhanin 2026).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional, Tuple
+
+import numpy as np
+
+__all__ = ["entropy_balance", "BalanceError"]
+
+
+class BalanceError(ValueError):
+    """Raised when entropy balancing fails to achieve first-moment balance.
+
+    Carries the achieved ``max_residual`` and the per-covariate residual vector so
+    callers (e.g. ``StackedDiD``) can attach cohort context and report the worst-
+    balanced covariate.
+    """
+
+    def __init__(self, message: str, *, max_residual: float, residuals: np.ndarray):
+        super().__init__(message)
+        self.max_residual = max_residual
+        self.residuals = residuals
+
+
+def entropy_balance(
+    X: np.ndarray,
+    target_means: np.ndarray,
+    base_weights: Optional[np.ndarray] = None,
+    *,
+    max_iter: int = 200,
+    tol: float = 1e-8,
+) -> Tuple[np.ndarray, Dict[str, Any]]:
+    """Solve entropy balancing for control weights matching ``target_means``.
+
+    Parameters
+    ----------
+    X : np.ndarray, shape (n, k)
+        Covariate matrix for the ``n`` control units (``k`` covariates).
+    target_means : np.ndarray, shape (k,)
+        Target first moments to match — for CBWSDID these are the treated-group
+        covariate means.
+    base_weights : np.ndarray, shape (n,), optional
+        Nonnegative base weights ``q_i`` (the KL reference). Defaults to uniform.
+        Internally renormalized to sum to one.
+    max_iter : int
+        Maximum damped-Newton iterations (then a scipy L-BFGS fallback is attempted).
+    tol : float
+        Convergence tolerance on the maximum absolute (raw-scale) moment residual
+        ``max_r |Σ_i w_i X_{i,r} − target_r|``.
+
+    Returns
+    -------
+    weights : np.ndarray, shape (n,)
+        Nonnegative weights summing to one with ``Σ_i w_i X_i ≈ target_means``.
+    info : dict
+        ``converged`` (bool), ``max_residual`` (float), ``n_iter`` (int),
+        ``ess`` (effective sample size ``1 / Σ_i w_i²``), ``solver`` (str).
+
+    Raises
+    ------
+    BalanceError
+        If neither the damped-Newton nor the L-BFGS fallback drives the maximum moment
+        residual below ``tol`` (the target is outside the control covariate hull, i.e.
+        infeasible).
+    ValueError
+        On malformed inputs (shape mismatch, non-finite, negative base weights).
+    """
+    X = np.asarray(X, dtype=np.float64)
+    if X.ndim != 2:
+        raise ValueError(f"X must be 2-D (n, k); got shape {X.shape}")
+    n, k = X.shape
+    target = np.asarray(target_means, dtype=np.float64).reshape(-1)
+    if target.shape[0] != k:
+        raise ValueError(f"target_means length {target.shape[0]} != n_covariates {k}")
+    if not np.all(np.isfinite(X)) or not np.all(np.isfinite(target)):
+        raise ValueError("X and target_means must be finite")
+    if n == 0:
+        raise ValueError("X has no control rows")
+
+    if base_weights is None:
+        q = np.full(n, 1.0 / n)
+    else:
+        q = np.asarray(base_weights, dtype=np.float64).reshape(-1)
+        if q.shape[0] != n:
+            raise ValueError(f"base_weights length {q.shape[0]} != n_control {n}")
+        if np.any(q < 0) or not np.all(np.isfinite(q)):
+            raise ValueError("base_weights must be nonnegative and finite")
+        s = q.sum()
+        if s <= 0:
+            raise ValueError("base_weights sum to zero")
+        q = q / s
+
+    # Centered moments; standardize columns for conditioning (balance set is invariant
+    # to the linear rescaling — it is absorbed into the dual variable λ).
+    Z = X - target
+    scale = Z.std(axis=0)
+    scale[scale < 1e-12] = 1.0
+    Zs = Z / scale
+
+    def weights_at(lam: np.ndarray) -> np.ndarray:
+        logits = Zs @ lam
+        logits -= logits.max()
+        ew = q * np.exp(logits)
+        return ew / ew.sum()
+
+    def dual_loss(lam: np.ndarray) -> float:
+        logits = Zs @ lam
+        m = logits.max()
+        return float(m + np.log(np.sum(q * np.exp(logits - m))))
+
+    def raw_residual(w: np.ndarray) -> np.ndarray:
+        return w @ X - target
+
+    lam = np.zeros(k)
+    solver = "newton"
+    n_iter = 0
+    for n_iter in range(1, max_iter + 1):
+        w = weights_at(lam)
+        if np.max(np.abs(raw_residual(w))) < tol:
+            break
+        g = w @ Zs  # gradient of the dual loss (standardized scale)
+        Zc = Zs - g
+        H = (w[:, None] * Zc).T @ Zc  # weighted covariance (PSD)
+        ridge = 1e-10 * (np.trace(H) / k + 1e-12)
+        try:
+            direction = -np.linalg.solve(H + ridge * np.eye(k), g)
+        except np.linalg.LinAlgError:
+            direction = -np.linalg.lstsq(H, g, rcond=None)[0]
+        # Backtracking (Armijo) line search on the convex dual loss.
+        base = dual_loss(lam)
+        slope = float(g @ direction)  # < 0 (descent)
+        step = 1.0
+        for _ in range(40):
+            if dual_loss(lam + step * direction) <= base + 1e-4 * step * slope:
+                break
+            step *= 0.5
+        lam = lam + step * direction
+    else:
+        w = weights_at(lam)
+
+    w = weights_at(lam)
+    resid = raw_residual(w)
+    max_resid = float(np.max(np.abs(resid)))
+
+    if max_resid >= tol:
+        # Fallback: scipy L-BFGS-B on the convex dual (robust to poor Newton scaling).
+        try:
+            from scipy.optimize import minimize
+
+            res = minimize(
+                dual_loss,
+                lam,
+                jac=lambda L: weights_at(L) @ Zs,
+                method="L-BFGS-B",
+                options={"maxiter": 500, "gtol": 1e-12},
+            )
+            w_lbfgs = weights_at(res.x)
+            resid_lbfgs = raw_residual(w_lbfgs)
+            if np.max(np.abs(resid_lbfgs)) < max_resid:
+                lam, w, resid = res.x, w_lbfgs, resid_lbfgs
+                max_resid = float(np.max(np.abs(resid)))
+                solver = "lbfgs"
+        except Exception:  # pragma: no cover - scipy always present, defensive
+            pass
+
+    converged = max_resid < tol
+    info: Dict[str, Any] = {
+        "converged": converged,
+        "max_residual": max_resid,
+        "n_iter": n_iter,
+        "ess": float(1.0 / np.sum(w**2)),
+        "solver": solver,
+    }
+    if not converged:
+        worst = int(np.argmax(np.abs(resid)))
+        raise BalanceError(
+            "entropy balancing did not converge to first-moment balance "
+            f"(max moment residual {max_resid:.3e} >= tol {tol:.1e}; worst covariate "
+            f"index {worst}). The target mean is likely outside the convex hull of the "
+            "control covariates (infeasible).",
+            max_residual=max_resid,
+            residuals=resid,
+        )
+    return w, info

{diff_diff-3.5.0 → diff_diff-3.5.2}/diff_diff/business_report.py

@@ -1019,6 +1019,9 @@ def _lift_robustness(dr: Optional[Dict[str, Any]]) -> Dict[str, Any]:
         native_block["pre_rmspe"] = native.get("pre_rmspe")
         native_block["weight_concentration"] = native.get("weight_concentration")
         native_block["in_space_placebo"] = native.get("in_space_placebo")
+        # ADH-2015 robustness diagnostics (opt-in; "not_run" stub until run).
+        native_block["leave_one_out"] = native.get("leave_one_out")
+        native_block["in_time_placebo"] = native.get("in_time_placebo")
     return {
         "bacon": {
             "status": bacon.get("status"),

diff_diff-3.5.2/diff_diff/conformal.py

@@ -0,0 +1,399 @@
+"""Conformal inference for counterfactual / synthetic controls (Chernozhukov,
+Wüthrich & Zhu 2021, *JASA* 116(536):1849–1864).
+
+Pure, numpy-only building blocks for the conformal-inference layer surfaced as
+opt-in methods on :class:`SyntheticControlResults`
+(:meth:`~diff_diff.synthetic_control_results.SyntheticControlResults.conformal_test`,
+``conformal_confidence_intervals``, ``conformal_average_effect``). See
+``docs/methodology/papers/chernozhukov-wuthrich-zhu-2021-review.md`` and the
+``## SyntheticControl`` section of ``docs/methodology/REGISTRY.md``.
+
+**Method (CWZ §2.2).** Under a sharp null ``H0: θ = θ0`` over the post period,
+impute the counterfactual treated outcomes (``Y^N_{1t} = Y_{1t} − θ0_t`` for
+``t > T0``; pre-period unchanged), fit a *time-permutation-invariant* proxy on
+**all** periods under that null, take residuals ``û_t = Y^N_{1t} − P̂^N_t``, form
+the statistic ``S_q(û) = ((1/√T*)·Σ_{t>T0}|û_t|^q)^{1/q}`` (high → reject), and
+compute a permutation p-value (eq 2) ``p̂ = (1/|Π|)·#{π∈Π : S(û_π) ≥ S(û)}`` by
+reshuffling residuals over time. ``Π`` contains the identity, so ``p̂ ≥ 1/|Π|``
+automatically (there is NO extra ``+1`` — distinct from the cross-unit placebo
+``(1+n)/(n+1)``). Inverting the test over a grid of ``θ0`` gives confidence sets.
+
+**Proxy.** The proxy is the canonical CWZ constrained-LS synthetic control
+(eqs 3–4): simplex weights minimising ``Σ_{t}(Y^N_{1t} − Σ_j w_j Y^N_{jt})²``
+over **all** periods under the null, ``w ≥ 0, Σ w = 1``, **no V-matrix, no
+intercept, outcomes-only** (footnote 9: "we estimate w under the null based on
+all the data"). This is DISTINCT from the headline ADH V-matrix weights — CWZ's
+exactness theory (Lemma 1, Appendix D exchangeability) requires a time-symmetric
+proxy, which the ADH pre-period V-fit is not. Reuses the Frank-Wolfe simplex
+solver :func:`diff_diff.utils._sc_weight_fw`.
+"""
+
+import math
+import warnings
+from typing import Any, Dict, List, Optional, Tuple
+
+import numpy as np
+
+from diff_diff.utils import _sc_weight_fw
+
+__all__: List[str] = []
+
+_INF = float("inf")
+
+
+# =============================================================================
+# Proxy fit (CWZ §2.3, eqs 3-4) — canonical constrained-LS synthetic control
+# =============================================================================
+
+
+def _cwz_proxy_fit(
+    y1: np.ndarray,
+    Y0: np.ndarray,
+    *,
+    max_iter: int,
+    min_decrease: float,
+    init_weights: Optional[np.ndarray] = None,
+) -> Tuple[np.ndarray, np.ndarray, bool]:
+    """Fit the canonical CWZ constrained-LS SC proxy over ALL given periods (eq 4).
+
+    Minimises ``Σ_t (y1_t − Σ_j w_j Y0_{tj})²`` s.t. ``w ≥ 0, Σ w = 1`` (no
+    intercept, no V-matrix). ``y1`` is the (already null-imputed) treated outcome
+    vector ``(T,)``; ``Y0`` the donor outcomes ``(T, J)``. Reuses
+    :func:`_sc_weight_fw` packed ``(T, J+1)`` (donor columns first, target last),
+    ``zeta=0, intercept=False`` — the solver projects onto the unit simplex, so the
+    ``w ≥ 0, Σ w = 1`` constraint is delivered with no extra normalization.
+
+    ``min_decrease`` is the ALREADY-SCALED absolute convergence tolerance; the
+    caller must pass a θ0-invariant scale (e.g. the pre-window outcome norm) so CI
+    membership does not drift with the grid value via the tolerance.
+
+    Returns ``(w (J,), resid = y1 − Y0 @ w (T,), converged)``. ``J == 1`` is the
+    degenerate single-donor case ``w = [1]`` (no optimisation).
+    """
+    y1 = np.asarray(y1, dtype=float)
+    Y0 = np.asarray(Y0, dtype=float)
+    _, J = Y0.shape
+    if J == 1:
+        w = np.array([1.0], dtype=float)
+        return w, y1 - Y0 @ w, True
+    packed = np.column_stack([Y0, y1])  # (T, J+1); last column is the target
+    with warnings.catch_warnings():
+        warnings.filterwarnings("ignore", message=r".*did not converge.*", category=UserWarning)
+        w, converged = _sc_weight_fw(
+            packed,
+            zeta=0.0,
+            intercept=False,
+            init_weights=init_weights,
+            min_decrease=float(min_decrease),
+            max_iter=int(max_iter),
+            return_convergence=True,
+        )
+    w = np.asarray(w, dtype=float)
+    return w, y1 - Y0 @ w, bool(converged)
+
+
+# =============================================================================
+# Test statistic (CWZ §2.2) and permutation sets
+# =============================================================================
+
+
+def _cwz_statistic(u: np.ndarray, post_mask: np.ndarray, q: Any) -> float:
+    """``S_q(û) = ((1/√T*)·Σ_{t>T0}|û_t|^q)^{1/q}`` (CWZ §2.2).
+
+    ``q=∞`` → ``max_{t>T0}|û_t|`` (the ``√T*`` factor vanishes in the sup limit).
+    ``post_mask`` is a boolean over the (calendar-ordered) periods selecting the
+    post window. Returns NaN if the post window is empty.
+    """
+    post = np.abs(u[post_mask])
+    n_star = post.size
+    if n_star == 0:
+        return float("nan")
+    if q == _INF:
+        return float(np.max(post))
+    s = float(np.sum(post**q))
+    return float((s / np.sqrt(n_star)) ** (1.0 / q))
+
+
+def _moving_block_perms(m: int) -> np.ndarray:
+    """Moving-block permutations ``Π_→`` — ``m`` cyclic shifts (CWZ §2.2).
+
+    Row ``j`` (``j = 0,…,m−1``) is the index array of ``π_j(i) = (i + j) mod m``
+    (the paper's 1-based ``i+j`` wrapped at ``m``); ``û_π = û[row]``. Row 0 is the
+    identity. Shape ``(m, m)``. Valid under stationary, weakly-dependent errors
+    (Assumption 2.2).
+    """
+    base = np.arange(m)
+    return (base[None, :] + base[:, None]) % m
+
+
+def _iid_perms(m: int, n_draws: int, rng: np.random.Generator) -> np.ndarray:
+    """i.i.d. permutations ``Π_all`` (CWZ §2.2).
+
+    Exact ``m!`` enumeration ONLY when genuinely small (``m ≤ 12`` and
+    ``m! ≤ n_draws``); otherwise ``n_draws`` random draws with the identity
+    prepended (the identity must be in ``Π``). Valid under i.i.d. errors
+    (Assumption 2.1). p-values below ``1/n_draws`` are unattainable.
+    """
+    if m <= 12 and math.factorial(m) <= n_draws:
+        from itertools import permutations
+
+        return np.array(list(permutations(range(m))), dtype=int)
+    ident = np.arange(m)[None, :]
+    if n_draws <= 1:
+        return ident
+    draws = np.stack([rng.permutation(m) for _ in range(n_draws - 1)])
+    return np.vstack([ident, draws]).astype(int)
+
+
+def _make_perms(m: int, scheme: str, n_iid: int, rng: np.random.Generator) -> np.ndarray:
+    """Dispatch to the requested permutation set (both include the identity)."""
+    if scheme == "moving_block":
+        return _moving_block_perms(m)
+    if scheme == "iid":
+        return _iid_perms(m, n_iid, rng)
+    raise ValueError(f"scheme must be 'moving_block' or 'iid', got {scheme!r}")
+
+
+# =============================================================================
+# Permutation p-value (CWZ eq 2)
+# =============================================================================
+
+
+def _cwz_pvalue(
+    u: np.ndarray, post_mask: np.ndarray, perms: np.ndarray, q: Any
+) -> Tuple[float, float, int]:
+    """CWZ eq (2) permutation p-value for residuals ``u``.
+
+    ``p̂ = (1/|Π|)·#{π ∈ Π : S(û_π) ≥ S(û)}``. The residual vector is permuted and
+    the statistic always reads the FIXED post-window slots (``post_mask``); the
+    identity ``π`` is in ``perms`` so ``p̂ ≥ 1/|Π|`` automatically (no extra ``+1``).
+    Ties (``≥``) are counted conservatively. ``perms`` is the ``(|Π|, len(u))``
+    integer index array from :func:`_make_perms`. Returns ``(p, S_observed, |Π|)``.
+    """
+    s_obs = _cwz_statistic(u, post_mask, q)
+    post_perm = np.abs(u[perms][:, post_mask])  # (|Π|, T*)
+    n_star = post_perm.shape[1]
+    if q == _INF:
+        s_perm = post_perm.max(axis=1)
+    else:
+        s_perm = (post_perm**q).sum(axis=1) / np.sqrt(n_star)
+        s_perm = s_perm ** (1.0 / q)
+    n = perms.shape[0]
+    tol = 1e-12 * max(abs(s_obs), 1.0)
+    n_ge = int(np.sum(s_perm >= s_obs - tol))
+    return n_ge / n, float(s_obs), n
+
+
+# =============================================================================
+# Single-null evaluation (joint sharp-null test) and grid inversion (CIs)
+# =============================================================================
+
+
+def _single_null_pvalue(
+    y1_obs: np.ndarray,
+    Y0: np.ndarray,
+    post_mask: np.ndarray,
+    effect_on_post: np.ndarray,
+    perms: np.ndarray,
+    q: Any,
+    *,
+    max_iter: int,
+    min_decrease: float,
+    init_weights: Optional[np.ndarray] = None,
+) -> Dict[str, Any]:
+    """Build ``Z(θ0)``, fit the proxy under the null, and return the p-value.
+
+    ``effect_on_post`` (length = ``post_mask.sum()``, calendar order) is subtracted
+    from the observed treated outcomes in the post window. The proxy is fit ONCE on
+    the null-imputed data and residuals are permuted (CWZ footnote 7 — the proxy is
+    time-permutation-invariant, so permuting residuals ≡ permuting data).
+    """
+    y1n = np.asarray(y1_obs, dtype=float).copy()
+    y1n[post_mask] = y1n[post_mask] - np.asarray(effect_on_post, dtype=float)
+    w, resid, conv = _cwz_proxy_fit(
+        y1n, Y0, max_iter=max_iter, min_decrease=min_decrease, init_weights=init_weights
+    )
+    p, s_obs, n = _cwz_pvalue(resid, post_mask, perms, q)
+    return {"p_value": p, "s_observed": s_obs, "n_perms": n, "converged": conv, "weights": w}
+
+
+def _auto_grid(center: float, spread: float, n_grid: int) -> np.ndarray:
+    """Symmetric inversion grid centred on the point estimate.
+
+    Half-width is a generous multiple of the pre-period residual scale (so a valid
+    CI lies inside the grid for well-behaved fits); membership outside the grid is
+    NOT certified (grid-limited — flagged via ``status`` when the accepted set
+    touches an edge).
+    """
+    half = max(8.0 * spread, 0.5 * abs(center) + 1e-6)
+    return np.linspace(center - half, center + half, n_grid)
+
+
+def _assemble_single_ci(
+    thetas: np.ndarray,
+    pvals: np.ndarray,
+    converged: np.ndarray,
+    alpha: float,
+    point_estimate: float,
+) -> Dict[str, Any]:
+    """Assemble a confidence interval from a single-post-slot inversion grid.
+
+    A grid point is **rejected** ONLY when it converged AND ``p ≤ alpha``; a
+    non-converged point is **indeterminate** (its p is unreliable) and is therefore
+    NOT rejected — keeping it in the set is the conservative choice for an interval
+    (excluding tail non-convergence would understate the width, the opposite of
+    fail-closed). The confidence set is the complement of the rejections; ``in_set``
+    (returned for the grid table) is ``~rejected``. The hull is ``[min, max]`` of the
+    in-set ``θ`` with a ``contiguous`` flag (a *rejected* point strictly inside the
+    hull ⇒ non-contiguous). ``n_nonconverged`` is surfaced so an interval widened by
+    indeterminacy is detectable. ``status`` is one of ``{"ran", "grid_limited",
+    "empty"}`` (the granularity-``unbounded`` case is handled by the caller).
+    """
+    rejected = converged & (pvals <= alpha)
+    in_set = ~rejected
+    n_nonconv = int(np.sum(~converged))
+    acc = thetas[in_set]
+    if acc.size == 0:
+        return {
+            "lower": float("nan"),
+            "upper": float("nan"),
+            "status": "empty",
+            "contiguous": True,
+            "point_estimate": float(point_estimate),
+            "n_in_set": 0,
+            "n_nonconverged": n_nonconv,
+            "_in_set": in_set,
+        }
+    lower, upper = float(acc.min()), float(acc.max())
+    inside = (thetas > lower) & (thetas < upper)
+    contiguous = bool(not np.any(rejected[inside]))
+    touches_edge = bool(in_set[0] or in_set[-1])
+    status = "grid_limited" if touches_edge else "ran"
+    return {
+        "lower": lower,
+        "upper": upper,
+        "status": status,
+        "contiguous": contiguous,
+        "point_estimate": float(point_estimate),
+        "n_in_set": int(acc.size),
+        "n_nonconverged": n_nonconv,
+        "_in_set": in_set,
+    }
+
+
+def _invert_single_post(
+    y1_obs: np.ndarray,
+    Y0: np.ndarray,
+    post_idx: int,
+    alpha: float,
+    perms: np.ndarray,
+    *,
+    max_iter: int,
+    min_decrease: float,
+    grid: Optional[np.ndarray] = None,
+    n_grid: int = 100,
+) -> Dict[str, Any]:
+    """Invert a single-post-slot conformal test over a grid (CWZ Algorithm 1).
+
+    The series ``y1_obs`` ``(m,)`` / ``Y0`` ``(m, J)`` has exactly one post slot at
+    ``post_idx`` (a per-period CI sub-series ``(pre ∪ {t})`` or a block-collapsed
+    average series). For each candidate effect ``θ`` the post outcome is imputed
+    (``y1[post_idx] − θ``), the proxy refit (warm-started across the grid — FW is
+    convex so warm-starting only affects speed, not the optimum), and the
+    permutation p-value recomputed. With one post slot ``S_q`` reduces to
+    ``|û_post|`` for every ``q``, so ``q`` is inert here (fixed to 1). Returns the CI
+    summary plus the ``grid`` table of ``(θ, p, in_set, converged)`` rows.
+
+    When ``alpha < 1/|Π|`` every candidate has ``p ≥ 1/|Π| > alpha`` (the identity is
+    in ``Π``), so NO value is ever rejected and the confidence set is the whole line:
+    this short-circuits to ``status="unbounded"`` with ``(-inf, +inf)`` endpoints and
+    an empty grid (the per-point table is uninformative when nothing can be rejected).
+    """
+    y1_obs = np.asarray(y1_obs, dtype=float)
+    Y0 = np.asarray(Y0, dtype=float)
+    m = y1_obs.shape[0]
+    post_mask = np.zeros(m, dtype=bool)
+    post_mask[post_idx] = True
+    n_perms = int(perms.shape[0])
+
+    # Un-absorbed point estimate + grid center from a PRE-ONLY proxy fit: predict the
+    # post slot from a proxy fit on the other (pre) slots only. The θ=0 full-series fit
+    # would let the proxy soak the effect into the weights, biasing the naive residual
+    # toward 0 and mis-centring the auto-grid (CWZ inverts the test precisely to avoid
+    # relying on that naive residual). ``spread`` is the pre-fit residual noise scale.
+    pre_sel = ~post_mask
+    w_pre, resid_pre, _ = _cwz_proxy_fit(
+        y1_obs[pre_sel], Y0[pre_sel], max_iter=max_iter, min_decrease=min_decrease
+    )
+    point_est = float(y1_obs[post_idx] - Y0[post_idx] @ w_pre)
+    spread = float(np.std(resid_pre)) if resid_pre.size else 1.0
+
+    if alpha < 1.0 / n_perms:
+        # Granularity-unbounded: every null is accepted (p >= 1/|Π| > alpha).
+        return {
+            "lower": -float("inf"),
+            "upper": float("inf"),
+            "status": "unbounded",
+            "contiguous": True,
+            "point_estimate": point_est,
+            "n_in_set": 0,
+            "n_nonconverged": 0,
+            "grid": [],
+            "n_perms": n_perms,
+        }
+
+    if grid is None:
+        grid = _auto_grid(point_est, spread, n_grid)
+    else:
+        grid = np.asarray(grid, dtype=float)
+
+    pvals = np.empty(grid.shape[0], dtype=float)
+    converged = np.empty(grid.shape[0], dtype=bool)
+    w_prev = w_pre
+    for i, theta in enumerate(grid):
+        y1n = y1_obs.copy()
+        y1n[post_idx] = y1n[post_idx] - float(theta)
+        w, resid, conv = _cwz_proxy_fit(
+            y1n, Y0, max_iter=max_iter, min_decrease=min_decrease, init_weights=w_prev
+        )
+        w_prev = w
+        p, _, _ = _cwz_pvalue(resid, post_mask, perms, 1)
+        pvals[i] = p
+        converged[i] = conv
+
+    out = _assemble_single_ci(grid, pvals, converged, alpha, point_est)
+    in_set = out.pop("_in_set")
+    out["grid"] = list(zip(grid.tolist(), pvals.tolist(), in_set.tolist(), converged.tolist()))
+    out["n_perms"] = n_perms
+    return out
+
+
+# =============================================================================
+# Block collapse for the average-effect test (CWZ Appendix A.1)
+# =============================================================================
+
+
+def _block_collapse(
+    y1: np.ndarray, Y0: np.ndarray, n_pre: int, n_post: int
+) -> Tuple[np.ndarray, np.ndarray, int]:
+    """Collapse the calendar-ordered panel into non-overlapping ``T*``-blocks (A.1).
+
+    The post block is the last ``n_post`` periods; pre blocks tile the pre-period
+    backwards from ``T0``, so the earliest ``n_pre % n_post`` pre-periods are
+    DROPPED to make the pre-block count integral (the paper assumes ``T/T*``
+    integer). Each block is the per-unit average over its ``n_post`` periods.
+    Returns ``(y1_blocks, Y0_blocks, n_dropped)`` with the post block last. Requires
+    at least one full pre-block after the drop (``n_pre ≥ n_post``).
+    """
+    y1 = np.asarray(y1, dtype=float)
+    Y0 = np.asarray(Y0, dtype=float)
+    t_star = n_post
+    drop = n_pre % t_star
+    n_pre_blocks = (n_pre - drop) // t_star
+    pre_y1 = y1[drop:n_pre].reshape(n_pre_blocks, t_star).mean(axis=1)
+    pre_Y0 = Y0[drop:n_pre].reshape(n_pre_blocks, t_star, Y0.shape[1]).mean(axis=1)
+    post_y1 = y1[n_pre:].mean()
+    post_Y0 = Y0[n_pre:].mean(axis=0)
+    y1_blocks = np.concatenate([pre_y1, [post_y1]])
+    Y0_blocks = np.vstack([pre_Y0, post_Y0[None, :]])
+    return y1_blocks, Y0_blocks, drop