chore(types): mypy triage to enforceable zero + blocking CI job (3/3)

[igerber]

Summary

Final part of the lint/type-hygiene program (#677/#679 normalization, #681 Lint workflow). mypy diff_diff goes from 184 errors to an enforced zero, and the Lint workflow gains a blocking Mypy job.

Error-class disposition (184 baseline, mid-triage peak 193 from annotation exposure):

Class	Count	Disposition
[index] 79	~55 real fixes (float-keyed dict annotations, Optional narrowing, list-vs-array rebinds masked by the disabled assignment code)	14 -> prep_dgp per-module override (seeded-RNG-stream-load-bearing Optional arrays); rest fixed
[attr-defined] 51	Root cause: 19 survey_design/resolved_survey: object params across 13 files -> properly typed via TYPE_CHECKING imports; one attribute inferred as type None from unannotated = None init; one missing mixin stub	all fixed
[union-attr] 21 (+conversions)	assert ... is not None narrowings at flag-guarded blocks, each documenting a real invariant (incl. a 5-estimator copy-pasted twin block)	all fixed
[misc] 11	Stale return-arity annotations + flag-dependent returns -> Literal overloads (_compute_aggregated_se_with_wif, _compute_overall_att); a variable reused for two types renamed; mypy's union-explosion give-up -> 2 reasoned inline ignores	fixed / 2 ignores
[call-overload] 6-8	solve_ols overload chain unbroken (helper moved out from between @overload block and implementation); sentinel str key in int-keyed dCDH dicts -> scoped documented ignores	fixed / 4 ignores
[no-redef] 4, [operator] 8, rest	Duplicate conflicting annotations dropped; Optional comparisons narrowed	all fixed

Net: ~170 of 184 resolved by real fixes; suppressions are one module override + matplotlib/plotly stub-parity skips + a handful of reasoned inline ignores. warn_unused_ignores = true added — it immediately surfaced 23 stale pre-existing ignores, now removed.

CI: lint.yml gains the Mypy job (pinned mypy==2.1.0 + pinned numpy/pandas/scipy so stubs cannot drift CI-vs-local; the package is NOT installed — no maturin/Rust). Lint Gate needs extended — no branch-protection change needed (the gate name is unchanged by design). TestLintWorkflowPinSync now covers the mypy pin, and a new test_mypy_job_stub_deps_exact_pinned locks the stub pins.

Docs: TODO.md "Type Annotations" note rewritten to the honest enforced-zero-with-listed-suppressions state; "Large Module Files" table regenerated from live counts (dated 2026-07-13); suppression-tightening filed as an Actionable Backlog row. CONTRIBUTING/CLAUDE.md updated to the all-three-tools-mirrored state.

Local review: 3 codex rounds (force-fresh), converged to zero actionable findings; round findings (stub-pin guard test, workflow header comment) folded in.

Methodology references (required if estimator / math changes)

• Method name(s): N/A - no estimator equations, weights, control groups, inference families, or defaults changed (typing, narrowing asserts on documented invariants, and CI only). Local codex review cross-checked the touched estimator files against the registry.
• Paper / source link(s): N/A
• Any intentional deviations from the source (and why): None

Validation

• Tests added/updated: 2 new workflow-guard tests (mypy pin sync, stub-dep pins); tests/test_openai_review.py -m '' green (254). Targeted estimator batteries across every touched file: 3,434 tests passed, zero narrowing-assert fires (survey, linalg, estimators, staggered, sun_abraham, imputation, two_stage, cdh, efficient_did, spillover, diagnostics, prep, bootstrap_chunking, survey_phase6, had_pretests, wooldridge, triple_diff, staggered_triple_diff, continuous_did, pretrends, bootstrap_utils, methodology_synthetic_control).
• Backtest / simulation / notebook evidence (if applicable): N/A - mypy error count was verified byte-stable (184) across the pure-formatting stages, and mypy diff_diff now reports zero.

Security / privacy

• Confirm no secrets/PII in this PR: Yes

---

Generated with Claude Code

🤖 Generated with Claude Code

https://claude.ai/code/session_01Lbd6nqWmg4snvvBmegwqiw

[github-actions]

Overall Assessment

✅ Looks good — no unmitigated P0 or P1 findings.

Executive Summary

• No estimator equations, weighting formulas, variance/SE formulas, identification defaults, or public defaults appear to change in the provided diff.
• Methodology-adjacent edits are type annotations, narrowing asserts, overloads, and documented invariant guards.
• No new inline inference anti-patterns or partial NaN guards were found in the changed estimator files.
• The remaining mypy suppressions are explicitly documented and tracked in TODO.md, so they are P3 informational.
• The new Mypy job is wired into Lint Gate, and guard tests cover tool/stub pins.

Methodology

• Severity: P3 informational
  Impact: Affected methods include survey-aware and inference-adjacent paths across dCDH, Callaway-Sant’Anna, EfficientDiD, SunAbraham, ImputationDiD, TwoStageDiD, SpilloverDiD, TWFE/DiD, and shared survey/linalg helpers. The changed lines do not alter the documented formulas; relevant survey bootstrap, replicate-weight, dCDH allocator, and Spillover Conley+survey choices are already documented in docs/methodology/REGISTRY.md:L998-L1040, docs/methodology/REGISTRY.md:L4912-L5068, and TODO.md:L77.
  Concrete fix: None required.

Code Quality

• Severity: None
  Impact: The new assert ... is not None statements are invariant narrowings around already-gated branches, not replacement validation for user inputs. No new inline t_stat = effect / se pattern was introduced outside the existing safe_inference() implementation.
  Concrete fix: None.

Performance

• Severity: None
  Impact: The PR adds a CI typecheck job but does not introduce material runtime changes in estimator code.
  Concrete fix: None.

Maintainability

• Severity: None
  Impact: The overloads and TYPE_CHECKING imports improve static contracts without changing runtime APIs. The workflow pin-sync tests reduce future CI/local drift risk.
  Concrete fix: None.

Tech Debt

• Severity: P3 informational
  Impact: Enforced-zero mypy still relies on global disabled codes and a prep_dgp per-module [index] override in pyproject.toml:L152-L182. This is explicitly tracked in TODO.md:L51 and summarized in TODO.md:L244-L256, so it is not a blocker under the deferred-work policy.
  Concrete fix: No action required for this PR; burn down the TODO row later.

Security

• Severity: None
  Impact: No new secrets or credential material were found in the changed diff. Existing secret-like strings are test fixtures in tests/test_openai_review.py, not live credentials.
  Concrete fix: None.

Documentation/Tests

• Severity: P3 informational
  Impact: The new Mypy workflow is included in the stable gate at .github/workflows/lint.yml:L48-L82, and tests cover tool pin sync plus exact stub dependency pins at tests/test_openai_review.py:L4682-L4724. I also verified the pinned package versions are resolvable on PyPI for mypy, numpy, pandas, scipy, black, and ruff. (pypi.org)
  Concrete fix: None.

I did not run the full test suite in this review environment; this was a static diff and methodology review.