Release 3.4.0: SpilloverDiD (Butts 2021), Bacon R-parity goldens, agent-discoverability surface, PreTrendsPower R-parity audit

[igerber]

Summary

Minor release. Bumps version 3.3.3 -> 3.4.0 across pyproject.toml, rust/Cargo.toml, diff_diff/__init__.py, diff_diff/guides/llms-full.txt, CITATION.cff (with date-released: 2026-05-19), and splits the CHANGELOG.md [Unreleased] section into a new empty [Unreleased] + [3.4.0] - 2026-05-19 block with comparison link.

Per the project SemVer convention (minor reserved for new estimator classes; additive extensions, new variance methods, new kwargs are patch-level), this is a minor bump because [Unreleased] adds a new top-level estimator (SpilloverDiD).

What landed since 3.3.3 (full detail in CHANGELOG [3.4.0]):

• SpilloverDiD - ring-indicator spillover-aware DiD (Butts 2021). New standalone estimator at diff_diff/spillover.py. Waves A-D: base estimator + Conley spatial-HAC SE + event-study (per-event-time x ring) decomposition + GMM df correction. Full docs surface (docs/api/spillover.rst, REGISTRY, references, methodology paper review).
• BaconDecomposition: Goodman-Bacon (2021) methodology audit (PR-B) closing the METHODOLOGY_REVIEW.md row. R-parity goldens at benchmarks/data/r_bacondecomp_golden.json. Behavior change: default weights flipped from "approximate" to "exact" per the methodology audit; pre-PR behavior reproducible via weights="approximate".
• DifferenceInDifferences(absorb=..., vcov_type in {\"hc2\", \"hc2_bm\"}) now supported via internal auto-route promoting absorb= to fixed_effects= so the full hat-matrix-dependent HC2 leverage correction and CR2 Bell-McCaffrey DOF are computed correctly. R-parity vs sandwich::vcovHC and clubSandwich::vcovCR at ~1e-10.
• MultiPeriodDiD(cluster=..., vcov_type=\"hc2_bm\") now supported via new _compute_cr2_bm_contrast_dof helper generalizing the per-coefficient Pustejovsky-Tipton 2018 algebra to arbitrary (k, m) contrast matrices for the post-period-average ATT DOF; cluster-aware Satterthwaite DOF R-verified against clubSandwich::Wald_test(test=\"HTZ\").
• PreTrendsPower implementation audit (PR-B) - major pretrends.py rewrite (+964 lines), 14+ CI rounds of methodology polish, R-parity golden generator at benchmarks/R/generate_pretrends_golden.R, comprehensive tests/test_methodology_pretrends.py (1,164 lines).
• Agent-discoverability surface (Issues Surface get_llm_guide / profile_panel / practitioner_next_steps more prominently for agent discovery #460, Add cold-start agent regression test to CI #461): new top-level agent_workflow(df, unit=..., time=..., treatment=..., outcome=...) stateless orchestrator, dir(diff_diff) agent-facing-first ordering via _OrderedName(str) subclass, top-level __doc__ rewritten to lead with the agent workflow recommendation, contract test at tests/test_agent_discoverability.py.
• ChaisemartinDHaultfoeuille.predict_het x placebo R-parity on both global and per-path surfaces; t-distribution DF threading in _compute_heterogeneity_test (closes TODO pilot-412).
• generate_ddd_panel_data - new panel-structured DGP helper for Triple-Difference power analysis.
• Roth (2022) paper review under docs/methodology/papers/roth-2022-review.md.

Methodology references (required if estimator / math changes)

• Method name(s): N/A for this release-bump PR - methodology changes landed in the underlying PRs (SpilloverDiD: event_study=True per-event-time × ring decomposition (Wave C) #456, BaconDecomposition R parity goldens #457, DiD-absorb HC2/HC2-BM: auto-route to fixed_effects internally #458, Lift MultiPeriodDiD-absorb HC2/HC2-BM gate via auto-route #459, SpilloverDiD: Gardner GMM first-stage correction (Wave D) #462, PreTrendsPower: Roth (2022) paper review + silent-failure guard #463, Surface agent_workflow() + curated dir() for LLM discoverability (#460) #464, PreTrendsPower implementation audit (Roth 2022 — PR-B) #466, Add agent-discoverability contract test (#461) #467). All deviations and citations are documented in docs/methodology/REGISTRY.md (## SpilloverDiD, ## BaconDecomposition, ## PreTrendsPower, ## DifferenceInDifferences, ## MultiPeriodDiD, ## ChaisemartinDHaultfoeuille).
• Paper / source link(s): see CHANGELOG [3.4.0] bullets - each cites its papers inline.
• Any intentional deviations from the source (and why): documented per-method in REGISTRY.md (SpilloverDiD ring overlap handling; BaconDecomposition default weights flip with backward-compat opt-in; PreTrendsPower constant-violation pattern as level shift; MultiPeriodDiD CR2-BM contrast-DOF refactor preserving per-coefficient parity at atol=1e-10).

Validation

• Tests added/updated: none in this PR (release-bump only). Test additions and R-parity validation landed with the underlying PRs.
• Backtest / simulation / notebook evidence (if applicable): none in this PR.

Security / privacy

• Confirm no secrets/PII in this PR: confirmed

[github-actions]

Overall Assessment

✅ Looks good

This is a release-cut / metadata-only PR. I found no unmitigated P0 or P1 issues in the reviewed diff.

Executive Summary

• No in-scope methodology change: the diff only bumps version/date surfaces and cuts the 3.4.0 changelog section (CHANGELOG.md:L8-L10, CHANGELOG.md:L1482-L1482, pyproject.toml:L5-L8, diff_diff/__init__.py:L296-L297, rust/Cargo.toml:L1-L4, CITATION.cff:L10-L11, diff_diff/guides/llms-full.txt:L5-L5).
• Versioning is internally consistent at 3.4.0 across Python packaging, runtime __version__, Rust crate metadata, citation metadata, and the LLM guide.
• Release dating is internally consistent at 2026-05-19 between CHANGELOG.md:L10-L10 and CITATION.cff:L11-L11.
• I found no new code-quality, performance, maintainability, tech-debt, or security issues in the changed lines.
• I did not run import/tests locally because the review environment is missing runtime dependencies (numpy).

Methodology

• Severity: none. Impact: none in scope; I checked docs/methodology/REGISTRY.md, and the reviewed diff does not touch estimator logic, assumptions, weighting, variance/SE, or defaults. Concrete fix: none.

Code Quality

• Severity: none. Impact: none; the version bump is synchronized across pyproject.toml:L5-L8, diff_diff/__init__.py:L296-L297, rust/Cargo.toml:L1-L4, CITATION.cff:L10-L11, and diff_diff/guides/llms-full.txt:L5-L5. Concrete fix: none.

Performance

• Severity: none. Impact: none; no executable runtime path changed. Concrete fix: none.

Maintainability

• Severity: none. Impact: none; the release cut in CHANGELOG.md:L8-L10 is paired with the new comparison link at CHANGELOG.md:L1482-L1482. Concrete fix: none.

Tech Debt

• Severity: none. Impact: none; this PR does not introduce new deferred work that needs tracking in TODO.md. Concrete fix: none.

Security

• Severity: none. Impact: none; the diff is metadata/docs only and does not add secrets, workflow execution changes, or new IO/network surfaces. Concrete fix: none.

Documentation/Tests

• Severity: none. Impact: none; the release version/date documentation is internally consistent across CHANGELOG.md:L10-L10 and CITATION.cff:L10-L11. Concrete fix: none.
• Verification note: I could not run a Python import smoke test locally because numpy is not installed in this review environment.