dCDH by_path Wave 3 #8+#9: non-binary treatment + paths_of_interest

Bundles two adjacent extensions to ChaisemartinDHaultfoeuille.by_path:

1. Non-binary integer treatment (Wave 3 #8): replace the
   `NotImplementedError` gate at chaisemartin_dhaultfoeuille.py:1870
   with a `ValueError` for continuous D (e.g. 1.5) per the no-silent-
   failures contract; integer-coded D in Z (e.g. ordinal {0, 1, 2})
   is now supported and produces integer-state path tuples
   (e.g. (0, 2, 2, 2)). Validated against R `did_multiplegt_dyn(...,
   by_path)` for D in {0, 1, 2} via the new
   `multi_path_reversible_by_path_non_binary` golden-value scenario:
   per-path point estimates match R bit-exactly (rtol ~1e-9 events,
   rtol+atol envelope for placebo near-zero values), per-path SE
   inherits the documented cross-path cohort-sharing deviation
   (~5% rtol; SE_RTOL=0.15 envelope).

2. paths_of_interest kwarg (Wave 3 #9): new estimator parameter
   accepting a list of int tuples for explicit user-specified path
   selection. Mutually exclusive with by_path=k (raises ValueError
   at __init__ and set_params time). Each tuple length validated at
   __init__ for uniformity, vs L_max+1 at fit-time. Bool / np.bool_
   rejected; np.integer accepted and canonicalized to Python int.
   Duplicates emit a UserWarning and dedupe; unobserved paths emit
   a UserWarning and are omitted from path_effects. Composes with
   non-binary D and all downstream by_path surfaces (bootstrap,
   placebos, sup-t bands, controls, trends_linear, trends_nonparam).
   Python-only API (R has no list-based selection in by_path).

Threading: paths_of_interest added to 6 path-enumeration helper
signatures (`_enumerate_treatment_paths`, `_compute_path_effects`,
`_compute_path_cumulated_event_study`, `_collect_path_bootstrap_inputs`,
`_compute_path_placebos`, `_collect_path_placebo_bootstrap_inputs`).
The `:1118` preconditions gate (drop_larger_lower / L_max / mutex
with heterogeneity / design2 / honest_did / survey_design) and the
11 `self.by_path is not None` activation branches in fit() rerouted
to fire under either selector.

For D >= 10, R's `did_multiplegt_by_path` derives the per-path
baseline via `substr(path_index$path, 1, 1)` which captures only
the first character of the comma-separated path string (e.g.
captures "1" instead of "12" for path = "12,12,..."), mis-allocating
R's per-path control-pool subset. Python's tuple-key matching is
correct; the parity scenario stays in D in {0, 1, 2} to avoid the R
bug.

Adds:
- `_validate_paths_of_interest` module-level helper for canonicalization
- `TestByPathNonBinary` (10 tests, 3 slow)
- `TestPathsOfInterest` (27 tests, 7 slow)
- `TestDCDHDynRParityByPathNonBinary` (1 parity test)
- R script Scenario 19 + regenerated dcdh_dynr_golden_values.json
- REGISTRY.md sub-paragraphs for non-binary + paths_of_interest
- CHANGELOG.md Unreleased > Added entry
- llms-full.txt kwarg listing for paths_of_interest

Removes: the now-stale `test_forbids_non_binary_treatment` gate-
firing test from TestByPathCoverageFitGates.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: igerber

CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+- **`ChaisemartinDHaultfoeuille.by_path` + non-binary integer treatment** — `by_path=k` now accepts integer-coded discrete treatment (D in Z, e.g. ordinal `{0, 1, 2}`); path tuples become integer-state tuples like `(0, 2, 2, 2)`. The previous `NotImplementedError` gate at `chaisemartin_dhaultfoeuille.py:1870` is replaced by a `ValueError` for continuous D (e.g. `D=1.5`) at fit-time per the no-silent-failures contract — the existing `int(round(float(v)))` cast in `_enumerate_treatment_paths` is now defensive (no-op for integer-coded D). Validated against R `did_multiplegt_dyn(..., by_path)` for D in `{0, 1, 2}` via the new `multi_path_reversible_by_path_non_binary` golden-value scenario (78 switchers, 3 paths, single-baseline custom DGP, F_g >= 4): per-path point estimates match R bit-exactly (rtol ~1e-9 on event horizons; rtol+atol envelope for placebo near-zero values), per-path SE inherits the documented cross-path cohort-sharing deviation (~5% rtol observed; SE_RTOL=0.15 envelope). **Deviation from R for D >= 10:** R's `did_multiplegt_by_path` derives the per-path baseline via `path_index$baseline_XX <- substr(path_index$path, 1, 1)`, which captures only the first character of the comma-separated path string (e.g. for `path = "12,12,..."` it captures `"1"` instead of `"12"`); this mis-allocates R's per-path control-pool subset for D >= 10. Python's tuple-key matching is correct in this regime — the per-path point estimates we compute are correct; R's per-path subset for the same path is buggy. The shipped parity scenario stays in `D in {0, 1, 2}` to avoid the R bug. R-parity test at `tests/test_chaisemartin_dhaultfoeuille_parity.py::TestDCDHDynRParityByPathNonBinary`; cross-surface invariants regression-tested at `tests/test_chaisemartin_dhaultfoeuille.py::TestByPathNonBinary`.
+- **New `paths_of_interest` kwarg on `ChaisemartinDHaultfoeuille`** for user-specified treatment-path subsets, alternative to `by_path=k`'s top-k automatic ranking. Mutually exclusive with `by_path`; setting both raises `ValueError` at `__init__` and `set_params` time. Each path tuple must be a list/tuple of `int` of length `L_max + 1` (uniformity validated at `__init__`; length match against `L_max + 1` validated at fit-time); `bool` and `np.bool_` are explicitly rejected, `np.integer` accepted and canonicalized to Python `int` for tuple-key consistency. Duplicates emit a `UserWarning` and are deduplicated; paths not observed in the panel emit a `UserWarning` and are omitted from `path_effects`. Paths appear in `results.path_effects` in the user-specified order, modulo deduplication and unobserved-path filtering. Composes with non-binary D and all downstream `by_path` surfaces (bootstrap, per-path placebos, per-path joint sup-t bands, `controls`, `trends_linear`, `trends_nonparam`) — mechanical filter on observed paths via the same `_enumerate_treatment_paths` call site, no methodology change. **Python-only API extension; no R equivalent** — R's `did_multiplegt_dyn(..., by_path=k)` only accepts a positive int (top-k) or `-1` (all paths). The `by_path` precondition gate at `chaisemartin_dhaultfoeuille.py:1118` (drop_larger_lower / L_max / `heterogeneity` / `design2` / `honest_did` / `survey_design` mutex) and the 11 `self.by_path is not None` activation branches in `fit()` were rerouted to fire under either selector. Validation + behavior + cross-feature regressions at `tests/test_chaisemartin_dhaultfoeuille.py::TestPathsOfInterest`.
+
 ## [3.3.2] - 2026-04-26
 
 ### Added

benchmarks/R/generate_dcdh_dynr_test_values.R

@@ -927,6 +927,97 @@ scenarios$multi_path_reversible_by_path_trends_nonparam <- list(
   results = extract_dcdh_by_path(res18, n_effects = 3, n_placebos = 1)
 )
 
+# Scenario 19: by_path + non-binary integer treatment (D in {0, 1, 2}).
+# Phase 3 Wave 3 #8 lift. Custom inline DGP (mirror Scenario 17 structure)
+# with 3 single-baseline non-binary paths: low-dose sustained
+# (0, 1, 1, 1), high-dose sustained (0, 2, 2, 2), and ramp-up
+# (0, 1, 2, 2). All F_g >= 4 (defensive: avoids any pre-window boundary
+# edge cases under future trends_lin combinations and matches Scenario 17).
+# 78 switchers + 20 never-treated (D=0) + 20 always-treated (D=2) controls.
+# n_periods=13, L_max=3.
+#
+# R's substr(path, 1, 1) baseline-derivation in did_multiplegt_by_path
+# is correct for D in {0..9} (single-digit decimal); we stay in {0, 1, 2}
+# so no R bug interferes. Python's tuple-key matching is correct
+# regardless of D range.
+cat("  Scenario 19: multi_path_reversible_by_path_non_binary\n")
+{
+  set.seed(119)
+  n_periods19 <- 13
+  L_max19 <- 3
+  target_paths19 <- list(
+    c(0L, 1L, 1L, 1L),  # path 1, low-dose sustained (rank 1)
+    c(0L, 2L, 2L, 2L),  # path 2, high-dose sustained (rank 2)
+    c(0L, 1L, 2L, 2L)   # path 3, ramp-up            (rank 3)
+  )
+  fg_path_counts19 <- list(
+    list(F_g = 4L, path_idx = 1L, count = 18L),
+    list(F_g = 5L, path_idx = 1L, count = 14L),
+    list(F_g = 6L, path_idx = 2L, count = 14L),
+    list(F_g = 7L, path_idx = 2L, count = 12L),
+    list(F_g = 8L, path_idx = 3L, count = 12L),
+    list(F_g = 9L, path_idx = 3L, count = 8L)
+  )
+  n_switchers19 <- sum(sapply(fg_path_counts19, function(x) x$count))
+  stopifnot(n_switchers19 == 78L)
+  D19 <- matrix(0L, nrow = n_switchers19, ncol = n_periods19)
+  g19 <- 1L
+  for (entry in fg_path_counts19) {
+    F_g <- entry$F_g
+    target <- target_paths19[[entry$path_idx]]
+    n_here <- entry$count
+    for (k in seq_len(n_here)) {
+      if (F_g >= 3L) D19[g19, 1:(F_g - 2L)] <- 0L
+      for (j in 0:L_max19) D19[g19, F_g - 1L + j] <- target[j + 1L]
+      if (F_g + L_max19 <= n_periods19) {
+        D19[g19, (F_g + L_max19):n_periods19] <- target[L_max19 + 1L]
+      }
+      g19 <- g19 + 1L
+    }
+  }
+  # Append 20 never-treated (D=0) and 20 always-treated (D=2) controls
+  D19 <- rbind(
+    D19,
+    matrix(0L, nrow = 20L, ncol = n_periods19),
+    matrix(2L, nrow = 20L, ncol = n_periods19)
+  )
+  n_total19 <- nrow(D19)
+  set.seed(119L)
+  group_fe19 <- rnorm(n_total19, 0, 2.0)
+  noise19 <- matrix(rnorm(n_total19 * n_periods19, 0, 0.5),
+                    nrow = n_total19, ncol = n_periods19)
+  period_arr19 <- 0:(n_periods19 - 1L)
+  Y19 <- 10.0 +
+    matrix(group_fe19, nrow = n_total19, ncol = n_periods19) +
+    matrix(0.1 * period_arr19, nrow = n_total19, ncol = n_periods19, byrow = TRUE) +
+    1.5 * D19 +
+    noise19
+  d19 <- data.frame(
+    group = rep(seq_len(n_total19) - 1L, each = n_periods19),
+    period = rep(period_arr19, n_total19),
+    treatment = as.vector(t(D19)),
+    outcome = as.vector(t(Y19))
+  )
+  res19 <- did_multiplegt_dyn(
+    df = d19, outcome = "outcome", group = "group", time = "period",
+    treatment = "treatment", effects = 3, placebo = 1, by_path = 3,
+    ci_level = 95
+  )
+  scenarios$multi_path_reversible_by_path_non_binary <- list(
+    data = list(
+      group = as.numeric(d19$group),
+      period = as.numeric(d19$period),
+      treatment = as.numeric(d19$treatment),
+      outcome = as.numeric(d19$outcome)
+    ),
+    params = list(pattern = "single_baseline_multi_path_non_binary",
+                  n_switcher_groups = 78L, n_realized_groups = 118L,
+                  n_periods = 13L, seed = 119L, effects = 3, placebo = 1,
+                  by_path = 3, ci_level = 95),
+    results = extract_dcdh_by_path(res19, n_effects = 3, n_placebos = 1)
+  )
+}
+
 # ---------------------------------------------------------------------------
 # Write output
 # ---------------------------------------------------------------------------