Fix #401 holistic audit residuals: two stale docstrings around dCDH by_path / paths_of_interest support

Holistic re-audit of merged #401 (dCDH by_path non-binary integer treatment + `paths_of_interest` Python-only selector) + #419 (cleanup PR broadening R-parser caveat). Per-PR CI review on #419 couldn't see the combined post-PR holistic state. Local agentic codex review against the combined diff (3 rounds) surfaced 2 P2 docstring fixes:

- `_validate_and_aggregate_to_cells` (`chaisemartin_dhaultfoeuille.py` aggregator helper): the `Raises` block still said the helper raises on "non-binary raw treatment values", but the shipped implementation now accepts continuous `d_gt` cell means and defers integer-only enforcement to `fit()` time (the `by_path` / `paths_of_interest` contract). Updated the Raises section to enumerate the actual failure modes (missing columns, NaN, non-coercible, within-cell-varying) and explain where the integer-only check actually lives.
- `path_sup_t_bands` dataclass field-adjacent comment (`chaisemartin_dhaultfoeuille_results.py`): comment still said the field is populated when `by_path` is a positive int AND `n_bootstrap > 0`, but `paths_of_interest` also activates the field. Updated to match the public docstring above (EITHER `by_path` OR `paths_of_interest` AND `n_bootstrap > 0`).

No methodology changes, no behavior changes to fit() outputs — both are documentation-only edits on dataclass field comments and a helper Raises block. The methodology contract has been correct on the public docstrings + REGISTRY all along; only the source-adjacent comments lagged.

Empirical observation: pilot-401 converged in 3 codex rounds (vs 11 for the #402 pilot). #401's cleanup PR #419 was a narrow R-parser caveat broadening, so the holistic state didn't have many cross-surface drift opportunities — consistent with the holistic-pilot pattern's expected return-on-investment scaling with cleanup-PR scope.

Author: igerber

diff_diff/chaisemartin_dhaultfoeuille.py

@@ -143,9 +143,16 @@ def _validate_and_aggregate_to_cells(
     Raises
     ------
     ValueError
-        On missing columns, NaN treatment / outcome values, non-numeric
-        treatment / outcome that cannot be coerced, or non-binary raw
-        treatment values.
+        On missing columns; NaN values in the treatment / outcome columns;
+        non-numeric treatment / outcome that cannot be coerced via
+        ``pd.to_numeric``; or within-cell-varying treatment (any
+        ``(group, time)`` cell where ``d_min != d_max``, since fuzzy DiD
+        is out of scope and deferred to a separate dCdH 2018 paper).
+        Integer-coded non-binary treatment (the ``by_path`` /
+        ``paths_of_interest`` requirement) is enforced separately at
+        ``fit()`` time, not here at aggregation time — this helper
+        accepts continuous ``d_gt`` cell means and lets ``fit()`` decide
+        whether the integer-only contract applies.
     """
     # 1. Required columns
     missing = [c for c in (outcome, group, time, treatment) if c not in data.columns]

diff_diff/chaisemartin_dhaultfoeuille_results.py

@@ -625,16 +625,16 @@ class ChaisemartinDHaultfoeuilleResults:
     )
     # Per-path joint sup-t simultaneous-band metadata. Keyed by path
     # tuple; each entry holds `{"crit_value", "alpha", "n_bootstrap",
-    # "method", "n_valid_horizons"}`. Populated when `by_path` is a
-    # positive int AND `n_bootstrap > 0`. The joint band itself is
-    # written per-horizon as `cband_conf_int` on
-    # `path_effects[path]["horizons"][l]` (mirrors the OVERALL
-    # `event_study_effects[l]["cband_conf_int"]` pattern at
+    # "method", "n_valid_horizons"}`. Populated when EITHER `by_path` is
+    # a positive int OR `paths_of_interest` is non-empty AND
+    # `n_bootstrap > 0`. The joint band itself is written per-horizon as
+    # `cband_conf_int` on `path_effects[path]["horizons"][l]` (mirrors
+    # the OVERALL `event_study_effects[l]["cband_conf_int"]` pattern at
     # `chaisemartin_dhaultfoeuille.py:2865-2875`). Empty-state contract:
-    # `None` when not requested (no bootstrap or `by_path is None`); `{}`
-    # when requested but no path passed both gates (>=2 valid horizons
-    # AND a strict majority — more than 50% — of finite sup-t draws).
-    # The bands cover joint inference
+    # `None` when not requested (no bootstrap, or both `by_path` and
+    # `paths_of_interest` are `None`); `{}` when requested but no path
+    # passed both gates (>=2 valid horizons AND a strict majority — more
+    # than 50% — of finite sup-t draws). The bands cover joint inference
     # WITHIN a single path across horizons; they do NOT provide
     # simultaneous coverage across paths.
     path_sup_t_bands: Optional[Dict[Tuple[int, ...], Dict[str, Any]]] = field(