diff-diff 3.4.1__tar.gz → 3.5.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: diff-diff
-Version: 3.4.1
+Version: 3.5.0
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Science/Research
 Classifier: Operating System :: OS Independent
@@ -159,8 +159,9 @@ Full guide: `diff_diff.get_llm_guide("practitioner")`.
 - [SunAbraham](https://diff-diff.readthedocs.io/en/stable/api/staggered.html) - Sun & Abraham (2021) interaction-weighted estimator for heterogeneity-robust event studies
 - [ImputationDiD](https://diff-diff.readthedocs.io/en/stable/api/imputation.html) - Borusyak, Jaravel & Spiess (2024) imputation estimator, most efficient under homogeneous effects
 - [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>`)
+- [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()`)
 - [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`.

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

@@ -106,8 +106,9 @@ Full guide: `diff_diff.get_llm_guide("practitioner")`.
 - [SunAbraham](https://diff-diff.readthedocs.io/en/stable/api/staggered.html) - Sun & Abraham (2021) interaction-weighted estimator for heterogeneity-robust event studies
 - [ImputationDiD](https://diff-diff.readthedocs.io/en/stable/api/imputation.html) - Borusyak, Jaravel & Spiess (2024) imputation estimator, most efficient under homogeneous effects
 - [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>`)
+- [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()`)
 - [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`.

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

@@ -222,6 +222,11 @@ from diff_diff.trop import (
     TROPResults,
     trop,
 )
+from diff_diff.synthetic_control import (
+    SyntheticControl,
+    synthetic_control,
+)
+from diff_diff.synthetic_control_results import SyntheticControlResults
 from diff_diff.wooldridge import WooldridgeDiD
 from diff_diff.wooldridge_results import WooldridgeDiDResults
 from diff_diff.utils import (
@@ -293,7 +298,7 @@ ETWFE = WooldridgeDiD
 DCDH = ChaisemartinDHaultfoeuille
 HAD = HeterogeneousAdoptionDiD
 
-__version__ = "3.4.1"
+__version__ = "3.5.0"
 __all__ = [
     # Estimators
     "DifferenceInDifferences",
@@ -309,6 +314,7 @@ __all__ = [
     "SpilloverDiD",
     "TripleDifference",
     "TROP",
+    "SyntheticControl",
     "StackedDiD",
     # Estimator aliases (short names)
     "DiD",
@@ -355,6 +361,8 @@ __all__ = [
     "StaggeredTripleDiffResults",
     "TROPResults",
     "trop",
+    "SyntheticControlResults",
+    "synthetic_control",
     "StackedDiDResults",
     "stacked_did",
     # EfficientDiD

{diff_diff-3.4.1 → diff_diff-3.5.0}/diff_diff/_reporting_helpers.py

@@ -618,6 +618,23 @@ def describe_target_parameter(results: Any) -> Dict[str, Any]:
             "reference": "REGISTRY.md Sec. TROP",
         }
 
+    if name == "SyntheticControlResults":
+        return {
+            "name": "SCM ATT (mean post-treatment gap for the single treated unit)",
+            "definition": (
+                "The average over the post-treatment periods of the gap "
+                "``alpha_hat_{1t} = Y_{1t} - sum_j w_j Y_{jt}`` between the single "
+                "treated unit and its donor-weighted synthetic control (Abadie, "
+                "Diamond & Hainmueller 2010). There is no population-averaging or "
+                "sampling estimand — it is the effect on the one treated unit; "
+                "significance is assessed by in-space placebo permutation inference "
+                "(no analytical standard error)."
+            ),
+            "aggregation": "single_unit_gap",
+            "headline_attribute": "att",
+            "reference": "REGISTRY.md Sec. SyntheticControl",
+        }
+
     # Default: unrecognized result class. Fall through with a neutral
     # block — agents / downstream consumers can still dispatch on
     # ``aggregation="unknown"`` and fall back to generic ATT narration.

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

@@ -203,6 +203,7 @@ class BusinessReport:
         if honest_did_results is not None and type(results).__name__ in {
             "SyntheticDiDResults",
             "TROPResults",
+            "SyntheticControlResults",
         }:
             raise ValueError(
                 f"{type(results).__name__} routes robustness to "
@@ -213,8 +214,9 @@ class BusinessReport:
                 "object's native diagnostics "
                 "(SDiD: ``in_time_placebo()``, ``sensitivity_to_zeta_omega()``, "
                 "``pre_treatment_fit``; TROP: ``effective_rank``, "
-                "``loocv_score``) — BusinessReport surfaces these "
-                "automatically under ``estimator_native_diagnostics``."
+                "``loocv_score``; SyntheticControl: ``in_space_placebo()``, "
+                "``pre_rmspe``, ``get_placebo_df()``) — BusinessReport surfaces "
+                "these automatically under ``estimator_native_diagnostics``."
             )
 
         # Round-44 P1 CI review on PR #318: mirror the SDiD/TROP
@@ -646,10 +648,13 @@ class BusinessReport:
         if att is None or not np.isfinite(att):
             sign = "undefined"
         ci_level = int(round((1.0 - display_alpha) * 100))
-        is_significant = (
+        # bool(...) coerces away numpy bool_ — when ``p`` is a numpy NaN (e.g.
+        # SyntheticControl, whose analytical p_value is always NaN), ``np.isfinite``
+        # yields a numpy bool that is NOT JSON-serializable in the schema.
+        is_significant = bool(
             p is not None and np.isfinite(p) and p < phrasing_alpha if p is not None else False
         )
-        near_threshold = (
+        near_threshold = bool(
             p is not None
             and np.isfinite(p)
             and (phrasing_alpha - 0.01) < p < (phrasing_alpha + 0.001)
@@ -1002,16 +1007,25 @@ def _lift_robustness(dr: Optional[Dict[str, Any]]) -> Dict[str, Any]:
         return {"status": "skipped", "reason": "auto_diagnostics=False"}
     bacon = dr.get("bacon") or {}
     native = dr.get("estimator_native_diagnostics") or {}
+    native_block = {
+        "status": native.get("status"),
+        "estimator": native.get("estimator"),
+        "pre_treatment_fit": native.get("pre_treatment_fit"),
+    }
+    # Classic SCM exposes pre_rmspe + donor-weight concentration + the (opt-in)
+    # in-space placebo rather than SDiD's pre_treatment_fit; surface those so the
+    # top-level robustness block is not empty for SyntheticControl.
+    if native.get("estimator") == "SyntheticControl":
+        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")
     return {
         "bacon": {
             "status": bacon.get("status"),
             "forbidden_weight": bacon.get("forbidden_weight"),
             "verdict": bacon.get("verdict"),
         },
-        "estimator_native": {
-            "status": native.get("status"),
-            "pre_treatment_fit": native.get("pre_treatment_fit"),
-        },
+        "estimator_native": native_block,
     }
 
 
@@ -1153,6 +1167,20 @@ def _describe_assumption(estimator_name: str, results: Any = None) -> Dict[str,
                 "captured through latent factor loadings."
             ),
         }
+    if estimator_name in {"SyntheticControlResults"}:
+        return {
+            # Distinct from SDiD's "synthetic_fit" weighted-PT analogue: classic
+            # SCM is a donor-weighted level match (matches the DR "scm_fit" method).
+            "parallel_trends_variant": "scm_fit",
+            "no_anticipation": True,
+            "description": (
+                "Classic synthetic control identifies the single treated unit's "
+                "counterfactual via a donor-weighted match to its pre-treatment "
+                "trajectory (a design-enforced fit, not a parallel-trends test); "
+                "significance comes from in-space placebo permutation inference "
+                "rather than an analytical standard error."
+            ),
+        }
     if estimator_name == "ContinuousDiDResults":
         # Callaway, Goodman-Bacon & Sant'Anna (2024), two-level PT:
         # REGISTRY.md §ContinuousDiD > Identification.
@@ -1780,6 +1808,8 @@ def _pt_method_subject(method: Optional[str]) -> str:
         return "Pre-treatment event-study coefficients"
     if method == "synthetic_fit":
         return "The synthetic-control pre-treatment fit"
+    if method == "scm_fit":
+        return "The synthetic-control donor-weighted pre-treatment fit"
     if method == "factor":
         return "The factor-model pre-treatment fit"
     return "Pre-treatment data"
@@ -1806,7 +1836,9 @@ def _pt_method_stat_label(method: Optional[str]) -> Optional[str]:
         return "joint p"
     if method in {"slope_difference", "hausman"}:
         return "p"
-    if method in {"synthetic_fit", "factor"}:
+    if method in {"synthetic_fit", "scm_fit", "factor"}:
+        # Design-enforced fit-based paths have no p-value label (SCM's significance
+        # is the in-space placebo, not a PT joint test).
         return None
     return "joint p"
 
@@ -1846,6 +1878,13 @@ def _references_for(estimator_name: str) -> List[Dict[str, str]]:
                 "& Wager, S. (2021). Synthetic Difference in Differences."
             ),
         },
+        "SyntheticControlResults": {
+            "role": "estimator",
+            "citation": (
+                "Abadie, A., Diamond, A., & Hainmueller, J. (2010). Synthetic "
+                "Control Methods for Comparative Case Studies. JASA, 105(490)."
+            ),
+        },
         "SunAbrahamResults": {
             "role": "estimator",
             "citation": (
@@ -2181,11 +2220,20 @@ def _render_summary(schema: Dict[str, Any]) -> str:
                     "assumption." + sens_tail_see_reliable
                 )
         elif verdict == "design_enforced_pt":
-            sentences.append(
-                "The synthetic control is designed to match the treated "
-                "group's pre-period trajectory (SDiD's weighted-parallel-"
-                "trends analogue)."
-            )
+            if method == "scm_fit":
+                sentences.append(
+                    "The synthetic control is designed to reproduce the treated "
+                    "unit's pre-period trajectory via donor weights (classic SCM's "
+                    "design-enforced analogue of parallel trends); significance "
+                    "comes from in-space placebo permutation inference, not a "
+                    "parallel-trends test."
+                )
+            else:
+                sentences.append(
+                    "The synthetic control is designed to match the treated "
+                    "group's pre-period trajectory (SDiD's weighted-parallel-"
+                    "trends analogue)."
+                )
         elif verdict == "inconclusive":
             # Round-35 P1 CI review on PR #318: a ``verdict=="inconclusive"``
             # state means one or more pre-period coefficients had

{diff_diff-3.4.1 → diff_diff-3.5.0}/diff_diff/chaisemartin_dhaultfoeuille.py

@@ -19,7 +19,7 @@ References
 - de Chaisemartin, C. & D'Haultfoeuille, X. (2020). Two-Way Fixed Effects
   Estimators with Heterogeneous Treatment Effects. *American Economic
   Review*, 110(9), 2964-2996.
-- de Chaisemartin, C. & D'Haultfoeuille, X. (2022, revised 2023).
+- de Chaisemartin, C. & D'Haultfoeuille, X. (2022, revised July 2023).
   Difference-in-Differences Estimators of Intertemporal Treatment Effects.
   NBER Working Paper 29873. Web Appendix Section 3.7.3 contains the
   cohort-recentered plug-in variance formula implemented here.
@@ -4506,11 +4506,15 @@ def _compute_per_period_dids(
         leaver_mask = (d_prev == 1) & (d_curr == 0) & present
         stable1_mask = (d_prev == 1) & (d_curr == 1) & present
 
-        # AER 2020 Theorem 3 N_{a,b,t} weights are CELL counts, not
-        # within-cell observation sums. Each (g, t) cell contributes once
+        # Library equal-cell weighting: N_{a,b,t} here counts (g, t)
+        # cells in each transition state. Each cell contributes once
         # regardless of how many original observations fed into the
-        # y_gt cell mean. See REGISTRY.md ChaisemartinDHaultfoeuille
-        # estimator equations.
+        # y_gt cell mean. This is a documented library deviation from
+        # AER 2020 Equation 3 (which defines N_{d,d',t} = sum N_{g,t},
+        # i.e., observation-sum weighting) and from R DIDmultiplegtDYN
+        # (individual-row weighting on unbalanced inputs). See
+        # REGISTRY.md ## ChaisemartinDHaultfoeuille L517 "Note (deviation
+        # from R DIDmultiplegtDYN ...)" for the full text.
         n_10 = int(joiner_mask.sum())
         n_00 = int(stable0_mask.sum())
         n_01 = int(leaver_mask.sum())
@@ -4635,7 +4639,8 @@ def _compute_placebo(
         leaver_mask = (d_pre_prev == 1) & (d_prev == 1) & (d_curr == 0) & present
         stable1_mask = (d_pre_prev == 1) & (d_prev == 1) & (d_curr == 1) & present
 
-        # Placebo weights are CELL counts (matching Theorem 3 convention)
+        # Placebo weights: library equal-cell counts (same documented
+        # deviation as the main DID_M path; see REGISTRY.md L517).
         n_10 = int(joiner_mask.sum())
         n_00 = int(stable0_mask.sum())
         n_01 = int(leaver_mask.sum())

{diff_diff-3.4.1 → diff_diff-3.5.0}/diff_diff/chaisemartin_dhaultfoeuille_results.py

@@ -13,7 +13,7 @@ References
 - de Chaisemartin, C. & D'Haultfoeuille, X. (2020). Two-Way Fixed Effects
   Estimators with Heterogeneous Treatment Effects. *American Economic
   Review*, 110(9), 2964-2996.
-- de Chaisemartin, C. & D'Haultfoeuille, X. (2022, revised 2023).
+- de Chaisemartin, C. & D'Haultfoeuille, X. (2022, revised July 2023).
   Difference-in-Differences Estimators of Intertemporal Treatment Effects.
   NBER Working Paper 29873.
 """
@@ -335,8 +335,13 @@ class ChaisemartinDHaultfoeuilleResults:
         ``L_max >= 1`` it was repurposed to hold the per-group count
         that matches the ``DID_1`` estimand. Originally equals
         once regardless of how many original observations fed into it.
-        This is the ``N_S`` denominator of ``DID_M`` per AER 2020
-        Theorem 3 — cell counts, not within-cell observation counts.
+        This is the ``N_S`` denominator of ``DID_M`` under the library's
+        equal-cell weighting convention (cell counts, not within-cell
+        observation sums). The AER 2020 paper's Equation 3 defines
+        ``N_{d,d',t} = sum_g N_{g,t}`` (observation sums); the
+        library's choice is a documented deviation - see
+        ``docs/methodology/REGISTRY.md`` ``## ChaisemartinDHaultfoeuille``
+        L517 for the full Note.
     n_cohorts : int
         Distinct cohorts ``(D_{g,1}, F_g, S_g)`` after filtering.
     n_groups_dropped_crossers : int

{diff_diff-3.4.1 → diff_diff-3.5.0}/diff_diff/conley.py

@@ -212,7 +212,7 @@ def _validate_conley_estimator_inputs(
 ) -> None:
     """Shared front-door validation for ``vcov_type='conley'`` on the
     estimator entry points (``DifferenceInDifferences``, ``MultiPeriodDiD``,
-    ``TwoWayFixedEffects``).
+    ``TwoWayFixedEffects``, ``SunAbraham``, and ``WooldridgeDiD``-OLS).
 
     Each estimator's ``fit()`` calls this BEFORE building Conley arrays or
     threading them into the variance computation. The eight checks below
@@ -296,10 +296,14 @@ def _validate_conley_estimator_inputs(
         raise ValueError(f"Cluster column '{cluster}' not found in data")
     if survey_design is not None:
         raise NotImplementedError(
-            f"{estimator_name}(vcov_type='conley') + survey_design is a "
-            "follow-up (Bertanha-Imbens 2014 weighted-Conley). Drop "
-            "survey_design for cross-sectional Conley, or use vcov_type='hc1' "
-            "for survey-aware cluster-robust without spatial HAC."
+            f"{estimator_name}(vcov_type='conley') + survey_design is "
+            "deferred — weighted spatial-HAC under probability sampling "
+            "is an open methodological question; no canonical extension "
+            "of Conley (1999) exists for the combination. Drop "
+            "survey_design for unweighted Conley (cross-sectional or panel "
+            "block-decomposed via conley_lag_cutoff > 0), or use "
+            "vcov_type='hc1' for survey-aware cluster-robust without "
+            "spatial HAC."
         )
     if inference == "wild_bootstrap":
         raise NotImplementedError(
@@ -365,6 +369,61 @@ def _uniform_kernel(u: np.ndarray) -> np.ndarray:
     return (np.abs(u) <= 1.0).astype(np.float64)
 
 
+def _serial_bartlett_kernel_matrix(t_codes: np.ndarray, L: int) -> np.ndarray:
+    """Within-unit Newey-West (1987) Bartlett HAC kernel matrix for serial
+    correlation in panel data, indexed by panel-wide dense time codes.
+
+    Returns the K matrix with ``K[i, j] = 1 - |t_i - t_j| / (L + 1)`` for
+    ``0 < |t_i - t_j| <= L``, else 0. The lag-0 diagonal is excluded so
+    callers can add this to a spatial within-period meat without
+    double-counting the diagonal.
+
+    Uses the 1-D radial pairwise form (matches conleyreg::time_dist), NOT
+    Conley 1999 Eq 3.14's 2-D separable product window — see the methodology
+    lock at :func:`_compute_conley_meat` for context.
+    """
+    t = t_codes.astype(np.float64, copy=False)
+    lag_mat = np.abs(t[:, None] - t[None, :])
+    return ((lag_mat <= L) & (lag_mat != 0)).astype(np.float64) * (1.0 - lag_mat / (L + 1.0))
+
+
+def _validate_meat_psd(
+    M: np.ndarray,
+    *,
+    error_msg: str,
+    warning_template: str,
+    stacklevel: int = 3,
+) -> None:
+    """Finite + PSD guard for sandwich meat matrices. Raises ``ValueError``
+    on non-finite entries; warns ``UserWarning`` when ``min(eigvalsh(M)) <
+    -1e-12``.
+
+    Parameters
+    ----------
+    error_msg
+        Message passed to ``ValueError`` on non-finite entries.
+    warning_template
+        Format string for the negative-eigenvalue warning. May contain an
+        ``{eigval}`` placeholder; the caller embeds ``{eigval:.2e}`` directly
+        in the template so the helper formats the minimum eigenvalue with
+        scientific notation.
+    stacklevel
+        Frame count from inside ``_validate_meat_psd``: ``stacklevel=N``
+        attributes the warning to the Nth caller above the helper itself.
+        Default 3 covers a single intermediate frame (the helper's direct
+        caller's caller); pass an explicit value matching call-site depth.
+    """
+    if not np.all(np.isfinite(M)):
+        raise ValueError(error_msg)
+    eigvals = np.linalg.eigvalsh(M)
+    if eigvals.size and eigvals.min() < -1e-12:
+        warnings.warn(
+            warning_template.format(eigval=eigvals.min()),
+            UserWarning,
+            stacklevel=stacklevel,
+        )
+
+
 def _compute_spatial_bartlett_meat_sparse(
     S: np.ndarray,
     coords: np.ndarray,
@@ -957,37 +1016,33 @@ def _compute_conley_meat(
                     mask_u = unit_arr == u_val
                     scores_u = scores[mask_u]
                     # Use dense panel-period codes (NOT raw labels) for lag math.
-                    t_u = time_codes[mask_u].astype(np.float64)
-                    lag_mat = np.abs(t_u[:, None] - t_u[None, :])
-                    K_u = ((lag_mat <= L) & (lag_mat != 0)).astype(np.float64) * (
-                        1.0 - lag_mat / (L + 1.0)
-                    )
+                    K_u = _serial_bartlett_kernel_matrix(time_codes[mask_u], L)
                     meat += scores_u.T @ K_u @ scores_u
-    if not np.all(np.isfinite(meat)):
-        raise ValueError(
-            "Conley meat contains non-finite values; check residuals and "
-            "score matrix for NaN/Inf."
-        )
-
     # PSD guard. Neither the uniform kernel (Conley 1999 fn 11) nor the
     # radial 1-D Bartlett specialization is formally PSD-guaranteed —
     # Conley's explicit PSD Bartlett formula (Eq 3.14) is the 2-D separable
     # product window, not the 1-D radial pairwise form that R `conleyreg`,
     # Stata `acreg`, and this implementation use. Check both kernels.
-    eigvals = np.linalg.eigvalsh(meat)
-    if eigvals.size and eigvals.min() < -1e-12:
-        warnings.warn(
+    # ``{eigval:.2e}`` is a literal placeholder for ``_validate_meat_psd``;
+    # only ``{kernel!r}`` is interpolated by the f-string here.
+    _validate_meat_psd(
+        meat,
+        error_msg=(
+            "Conley meat contains non-finite values; check residuals and "
+            "score matrix for NaN/Inf."
+        ),
+        warning_template=(
             f"Conley meat with conley_kernel={kernel!r} has a materially "
-            f"negative eigenvalue ({eigvals.min():.2e}); the variance "
+            "negative eigenvalue ({eigval:.2e}); the variance "
             "estimator is not guaranteed PSD on this design. Both "
             "supported kernels (radial bartlett and uniform) are "
             "practitioner specializations of Conley 1999 and are not "
             "formally PSD-guaranteed; consider varying conley_cutoff_km "
             "or reviewing the design for collinearity / degenerate "
-            "residual structure.",
-            UserWarning,
-            stacklevel=3,
-        )
+            "residual structure."
+        ),
+        stacklevel=4,
+    )
 
     return meat