feat: v0.9.12 — probit-scale MTE (Heckman frame) + statspai CLI + sp.help introspection

- bayes_mte gains selection='uniform'|'normal' kwarg; 'normal' fits the
  MTE polynomial on V = Φ⁻¹(U_D) so (poly_u=1, hv_latent, normal)
  exactly recovers the linear Heckman MTE slope on a bivariate-normal DGP.
- Shared PROBIT_CLIP in bayes/_base keeps fit / ATT-ATU integrator /
  policy_effect on the same numerical footing; BayesianMTEResult carries
  the selection tag so policy_effect transforms the grid to V scale.
- mte_curve adds a 'v' column under selection='normal'.
- Round-C review fixed 2 BLOCKERs (ATT/ATU + policy_effect had been
  raising U-scale powers against a V-scale posterior) and added
  tests/test_bayes_mte_selection.py (12 tests, 78 focused MTE tests green).
- New `statspai` console_scripts entry → statspai.cli:main, plus
  statspai.help module providing sp.help / sp.list_functions /
  sp.search_functions backed by registry auto-registration from
  statspai.__all__.
- Author email updated to brycew6m@stanford.edu across pyproject,
  __init__, and Cargo.toml.

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

Author: brycewang-stanford

CHANGELOG.md

@@ -2,6 +2,82 @@
 
 All notable changes to StatsPAI will be documented in this file.
 
+## [0.9.12] - 2026-04-20 — Probit-scale MTE (Heckman selection frame)
+
+Adds the third orthogonal axis to `sp.bayes_mte`: the MTE polynomial
+can now be fit on either the uniform scale `U_D ∈ [0, 1]`
+(v0.9.11 default) or the probit / V scale
+`V = Φ^{-1}(U_D) ∈ ℝ` — the conventional Heckman (1979) / HV 2005
+frame. All `(first_stage, mte_method, selection)` combinations fit.
+
+### Added (0.9.12)
+
+- **`sp.bayes_mte(..., selection='uniform' | 'normal')`** — new kwarg.
+  - `'uniform'` (default) preserves v0.9.11 behaviour: polynomial
+    in `U_D ∈ [0, 1]`.
+  - `'normal'` reinterprets the abscissa as `V = Φ^{-1}(U_D)` via
+    `pt.sqrt(2) * pt.erfinv(2a-1)` on the tensor side and
+    `scipy.stats.norm.ppf` on numpy side. Under strict HV + bivariate-
+    normal, `poly_u=1 + selection='normal' + mte_method='hv_latent'`
+    exactly recovers the linear Heckman MTE slope.
+
+- **`mte_curve` exposes `v` column** under `selection='normal'`
+  (empty otherwise) so users can plot on the scale their model
+  was fit on.
+
+- **Shared `PROBIT_CLIP` constant** in `statspai.bayes._base` —
+  fit-time, ATT/ATU integrator, and `policy_effect` all read the
+  same clip so the three paths stay numerically consistent.
+
+### Empirical recovery on Heckman DGP (true `(b_0, b_1) = (0.5, 1.5)`)
+
+| combo | `b_0` | `b_1` |
+|---|---|---|
+| plugin × polynomial × V | -0.73 | 0.82 |
+| plugin × hv_latent × V | 0.42 | 1.37 ✓ |
+| joint × polynomial × V | -0.73 | 0.81 |
+| joint × hv_latent × V | 0.46 | 1.40 ✓ |
+
+Same story as earlier releases: `hv_latent` recovers truth;
+`polynomial` fits `g(v)` not `MTE(v)` and is biased.
+
+### Round-B review found 2 BLOCKERS + 2 HIGHs; Round-C fixed all
+
+1. **BLOCKER-1**: `_integrated_effect` (ATT/ATU) was raising `U_population`
+   to polynomial powers directly, even under `'normal'` where the
+   posterior is on V scale. **Fixed** — transforms to
+   `Φ^{-1}(U_population)` first.
+2. **BLOCKER-2**: `BayesianMTEResult.policy_effect` computed
+   `u_pow = [u^k ...]` instead of `[v^k ...]` under `'normal'`,
+   silently integrating a V-scale polynomial against u-scale powers.
+   **Fixed** — `BayesianMTEResult` now carries a `selection` field,
+   and `policy_effect` transforms the grid to V scale when needed.
+   Regression test asserts `policy_effect(policy_weight_ate())`
+   matches `.ate` to 1e-8 under `'normal'`.
+3. **HIGH-1**: `mte_curve` lacked a `v` column — **added**.
+4. **Round-C follow-up**: extracted `PROBIT_CLIP = 1e-6` to a shared
+   module constant consumed by both `mte.py` and `_base.py` so the
+   three-site fit/summary/policy paths cannot drift.
+
+### Tests (0.9.12)
+
+- `tests/test_bayes_mte_selection.py` (NEW, 12 tests) — back-compat,
+  method-label, Heckman DGP recovery, all-8-combo orthogonality,
+  input validation, `v` column presence/absence, ATT/ATU V-scale
+  correctness (Round-C regression), `policy_effect` V-scale
+  parity with `.ate` (Round-C regression), uniform-vs-normal
+  non-trivial disagreement.
+- 78 focused MTE tests green.
+
+### Non-goals (0.9.12)
+
+- Full bivariate-normal error covariance `(U_0, U_1, V) ~ N(0, Σ)`
+  with free `ρ_{0V}`, `ρ_{1V}` — convergence-intensive MvNormal
+  mixture, queued for 0.9.13+.
+- Rust Phase 2 — separate branch.
+
+---
+
 ## [0.9.11] - 2026-04-20 — Multi-instrument MTE + true CHV-2011 PRTE weights
 
 Closes two long-standing API gaps plus an empirical math debt.

docs/superpowers/specs/2026-04-20-v0912-probit-scale-mte.md

@@ -0,0 +1,111 @@
+# StatsPAI v0.9.12 — Probit-scale MTE (Heckman selection frame)
+
+**Author:** Bryce Wang · **Date:** 2026-04-20 · **Status:** design → implementation
+
+## 1. Motivation
+
+v0.9.11 handled multi-IV MTE and the true CHV-2011 PRTE weight. The one remaining thread in the Bayesian MTE frontier is the **Heckman (1979) selection model** with Gaussian/probit-scale errors, which is the conventional parametric frame underlying HV 2005:
+
+```
+V_i ~ N(0, 1)
+D_i = 1{ logit(p_i) + V_i > 0 }   (probit / normal-tail selection)
+MTE(v) = μ_1(X) - μ_0(X) + (ρ_{1V}σ_1 - ρ_{0V}σ_0) · v  (linear in V)
+```
+
+Under the strict bivariate-normal HV assumption, MTE is linear on the V scale. Our existing polynomial-in-U_D model (U_D ∈ [0,1]) is richer but parametrised on the uniform scale; a user who wants the conventional Heckman interpretation needs the V-scale formulation.
+
+v0.9.12 adds a third orthogonal axis to `sp.bayes_mte`:
+
+| axis | options |
+|---|---|
+| `first_stage` | `'plugin'` / `'joint'` |
+| `mte_method` | `'polynomial'` / `'hv_latent'` |
+| **`selection`** (new) | `'uniform'` (default) / `'normal'` |
+
+Together these describe the 8-combo grid of Bayesian MTE specifications. All 8 are expected to fit without error; recovery characteristics differ by DGP.
+
+## 2. Scope
+
+### In scope (v0.9.12)
+
+- **`sp.bayes_mte(..., selection='uniform' | 'normal')`** — new kwarg. `'uniform'` (default) preserves v0.9.11 behaviour. `'normal'` reinterprets the polynomial abscissa as `V_i = Φ^(-1)(U_D_i)` (probit scale, V ∈ ℝ). All combinations with existing `first_stage` / `mte_method` flags supported.
+- **Mathematical identity guarantee**: `'normal'` mode fits the MTE polynomial in V. Under `poly_u=1` + `selection='normal'` + `mte_method='hv_latent'` the model exactly matches the linear Heckman-HV MTE.
+- **Method label** reflects the selection scale: `"Bayesian MTE on V scale (...)"` vs `"Bayesian MTE on U_D scale (...)"`.
+
+### Out of scope (deferred to 0.9.13+)
+
+- **Full bivariate-normal error covariance** `(U_0, U_1, V) ~ N(0, Σ)` with free correlations `ρ_{0V}`, `ρ_{1V}`. Requires explicit mixture modelling and MvNormal over `(Y, D)` that has known convergence pathologies in PyMC. Tracked as a separate release.
+- Selection-on-levels (`μ_0` ≠ `μ_1`) as a free parameter: currently absorbed into `alpha + beta_X·X`. Disentangling requires the full mixture model.
+- Rust Phase 2, VI backends for MTE.
+
+## 3. API
+
+```python
+def bayes_mte(
+    data, y, treat, instrument, covariates=None,
+    *,
+    first_stage: str = 'plugin',
+    mte_method: str = 'polynomial',
+    selection: str = 'uniform',        # NEW
+    u_grid: np.ndarray | None = None,
+    poly_u: int = 2,
+    ...
+)
+```
+
+### Semantics
+
+Under `selection='uniform'` (v0.9.11 default):
+```
+Abscissa a ∈ [0, 1]  (either p_i in polynomial mode or U_D_i in hv_latent)
+MTE-curve: τ(a) = Σ_k b_k · a^k,  a ∈ u_grid ⊂ [0, 1]
+```
+
+Under `selection='normal'`:
+```
+Abscissa v ∈ ℝ  with v = Φ^{-1}(a)
+MTE-curve: τ(v) = Σ_k b_k · v^k,  v ∈ Φ^{-1}(u_grid) ⊂ ℝ
+```
+
+The returned `mte_curve` DataFrame still has a `u` column (in [0,1]) for user convenience — this is the natural propensity scale. The `v` column is added when `selection='normal'` so users can see the probit coordinate.
+
+ATE / ATT / ATU integrals: on the V scale, we integrate against the Gaussian density `φ(v) dv` rather than uniform `du`. This matches the HV identified-integrand under bivariate-normal.
+
+### Defaults justification
+
+`'uniform'` stays the default because:
+1. No breaking change to v0.9.11 users.
+2. The `[0,1]` propensity scale is the agent-native abstraction most users want.
+3. `'normal'` is a purer "I'm doing Heckman textbook work" mode — users who need it will reach for it.
+
+## 4. File plan
+
+| File | Change |
+|---|---|
+| `src/statspai/bayes/mte.py` | Add `selection` kwarg; transform abscissa via `Φ^{-1}` when `'normal'`; adjust ATE integration to Gaussian measure when `'normal'`; update method label + `model_info`. |
+| `src/statspai/bayes/_base.py` | `mte_curve` DataFrame adds a `v` column when fit was on V scale (empty otherwise). |
+| `tests/test_bayes_mte_selection.py` | NEW — `selection='normal'` recovery + orthogonality. |
+| `pyproject.toml` | `version = "0.9.12"` |
+| `CHANGELOG.md` | 0.9.12 entry |
+
+## 5. Test plan
+
+- `test_selection_uniform_back_compat` — scalar call with default `selection` returns v0.9.11 behaviour.
+- `test_selection_normal_api_surface` — new kwarg flows to `model_info['selection']`; method label mentions V scale.
+- `test_selection_normal_recovers_linear_heckman` — DGP with Gaussian V and MTE linear in V; `poly_u=1 + selection='normal' + hv_latent` recovers the slope.
+- `test_selection_normal_all_orthogonal_combos_run` — 4 combos (plugin/joint × polynomial/hv_latent) × selection='normal'.
+- `test_selection_invalid_value_raises`.
+- `test_selection_normal_mte_curve_has_v_column`.
+
+## 6. Success criteria
+
+1. `selection='normal'` runs on all 4 `(first_stage, mte_method)` combos.
+2. On a DGP with `MTE(V) = 0.5 + 1.5·V` (Gaussian latent V), `poly_u=1 + selection='normal' + hv_latent` recovers `(0.5, 1.5)` within HDI.
+3. Full suite stays green (zero-new-failures rule).
+4. Two rounds of code review, zero ship-blockers.
+
+## 7. Non-goals (explicit)
+
+- Free cross-correlation parameters `(ρ_{0V}, ρ_{1V})` — the bivariate-normal mixture is its own release.
+- Policy weights on V scale — current `policy_weight_*` builders still operate on the `[0,1]` grid; users on `selection='normal'` get `u_grid` transformed via `Φ` so policy integrals remain well-defined on the propensity scale.
+- Changing the sign / direction of `V = Φ^{-1}(p)` (we use the standard convention).

pyproject.toml

@@ -4,15 +4,15 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "StatsPAI"
-version = "0.9.11"
+version = "0.9.12"
 description = "The Agent-Native Causal Inference & Econometrics Toolkit for Python"
 readme = "README.md"
 license = {text = "MIT"}
 authors = [
-    {name = "Biaoyue Wang", email = "bryce@copaper.ai"}
+    {name = "Biaoyue Wang", email = "brycew6m@stanford.edu"}
 ]
 maintainers = [
-    {name = "Biaoyue Wang", email = "bryce@copaper.ai"}
+    {name = "Biaoyue Wang", email = "brycew6m@stanford.edu"}
 ]
 classifiers = [
     "Development Status :: 3 - Alpha",
@@ -89,6 +89,9 @@ tune = [
     "optuna>=3.0",
 ]
 
+[project.scripts]
+statspai = "statspai.cli:main"
+
 [project.urls]
 Homepage = "https://github.com/brycewang-stanford/statspai"
 Documentation = "https://github.com/brycewang-stanford/statspai#quick-example"

rust/statspai_hdfe/Cargo.toml

@@ -2,7 +2,7 @@
 name = "statspai_hdfe"
 version = "0.1.0-alpha.1"
 edition = "2021"
-authors = ["Bryce Wang <bryce@copaper.ai>"]
+authors = ["Bryce Wang <brycew6m@stanford.edu>"]
 description = "PyO3 + Rayon HDFE group-demean kernel for StatsPAI"
 license = "MIT"
 readme = "README.md"

src/statspai/__init__.py

@@ -22,9 +22,9 @@
 >>> sp.outreg2(result, filename="results.xlsx")
 """
 
-__version__ = "0.9.11"
+__version__ = "0.9.12"
 __author__ = "Biaoyue Wang"
-__email__ = "bryce@copaper.ai"
+__email__ = "brycew6m@stanford.edu"
 
 from .core.results import EconometricResults, CausalResult
 from .regression.ols import regress

src/statspai/bayes/_base.py

@@ -26,6 +26,16 @@
 )
 
 
+# Shared clip constant for the probit-scale (``selection='normal'``)
+# transform. Any site computing ``Φ^{-1}(a)`` — the fit-time
+# polynomial powers, the post-hoc ATT/ATU integrator, and
+# ``policy_effect`` — MUST use this constant so the three paths stay
+# numerically consistent (cf. v0.9.12 round-C review HIGH on clip
+# drift between fit and policy_effect). Tightening requires
+# one-line change here; all callers pick it up automatically.
+PROBIT_CLIP: float = 1e-6
+
+
 def _require_pymc():
     """Import PyMC and ArviZ, or raise a clear ImportError."""
     try:
@@ -381,6 +391,11 @@ class BayesianMTEResult(BayesianCausalResult):
     ate: float = float('nan')
     att: float = float('nan')
     atu: float = float('nan')
+    # v0.9.12: `'uniform'` (default) fits MTE polynomial in U_D on
+    # [0,1]; `'normal'` fits in V = Φ^{-1}(U_D) on ℝ. The result
+    # remembers this so `policy_effect` can transform the abscissa
+    # before integrating against the user's weight_fn.
+    selection: str = 'uniform'
 
     def policy_effect(
         self,
@@ -422,7 +437,18 @@ def policy_effect(
         poly_u = b_mte_post.shape[-1] - 1
         flat = b_mte_post.reshape(-1, poly_u + 1)
         u = np.asarray(self.u_grid, dtype=float)
-        u_pow = np.column_stack([u ** k for k in range(poly_u + 1)])
+
+        # v0.9.12: respect the selection scale. Under
+        # ``selection='normal'`` the polynomial is in ``v = Φ^{-1}(u)``
+        # so the abscissa-powers must be built on v, not u. The
+        # weight_fn is still passed u (the natural scale for users)
+        # but we transform internally before dotting with b_mte.
+        if self.selection == 'normal':
+            from scipy.stats import norm as _norm_dist
+            abscissa = _norm_dist.ppf(np.clip(u, PROBIT_CLIP, 1 - PROBIT_CLIP))
+        else:
+            abscissa = u
+        u_pow = np.column_stack([abscissa ** k for k in range(poly_u + 1)])
         mte_samples = flat @ u_pow.T         # (S, n_grid)
         weights = np.asarray(weight_fn(u), dtype=float)
         if weights.shape != u.shape: