Clarify completed AIPW normalization TODO (#552)

Summary: Pull Request resolved: #552

Differential Revision: D114694029

Pulled By: talgalili

fbshipit-source-id: 35b0ef28f474a615a3a1dcca9d4e01dda2061516

Author: neuralsorcerer

docs/architecture/architecture_0_23_0.md

@@ -29,7 +29,7 @@
 | 2026-07-16 | **`summary()` reports the fit-weights and *scopes* any DR statement to them — never a blanket "doubly robust".** For a linear WLS fit with non-uniform weights it states e.g. "g-computation; doubly robust w.r.t. weights `<col>`"; uniform-weight or non-linear fits are reported as plain g-computation. | The DR guarantee is relative to the specific weight set used in the fit; reporting it (not a bare flag) is honest and avoids false-DR claims. DR *for the target estimand* still requires those weights to be the target-reweighting/IPW weights. |
 | 2026-07-16 | **`outcomes_hat` columns follow a `<outcome>_hat` naming convention** (e.g. `happiness_hat`) — self-describing in `.df`, discernible from covariates/outcomes; `from_frame` **warns** if an unclaimed `_hat`-suffixed column would be inferred as a covariate. | Makes predicted columns recognizable end-to-end and prevents a reloaded target's `_hat` column from silently corrupting the next `adjust()`'s propensity model (the round-trip covariate leak). |
 | 2026-07-16 | **`outcomes_hat().mean_with_ci()` defaults to `ci_method="bootstrap"`** on a BalanceFrame+target-backed view; a lone/target-less view **raises** (never silently returns the analytic CI, which under-covers `μ̂_OM` by treating `ŷ_T` as fixed). `mean()` stays the O(1) point estimate. | The analytic `ci_of_weighted_mean` ignores model-fitting uncertainty; bootstrap is the honest default. |
-| 2026-07-16 | **AIPW normalization contract: deferred to phase 2 but DOCUMENTED now.** The augmentation is valid only when `w_R` and `w_T` are on the same population scale (both from `adjust()`); Hájek self-normalization gives *asymptotic* DR (ratio bias `O(1/n)`). Phase-2 `aipw()` should require `adjust()`-calibrated weights + assert `|Σw_R−Σw_T|/Σw_T < tol`. | Records the correctness precondition so the deferred AIPW isn't built on an unstated assumption. (update 2026-07-18: `aipw()` shipped but does NOT yet enforce this contract — it uses the present balance weights with no `adjust()` requirement and no `|Σw_R−Σw_T|/Σw_T < tol` assertion, only a warning on constant responder weights; the contract remains a TODO.) |
+| 2026-07-16 | **AIPW normalization contract: was deferred to phase 2 but documented at the time.** The augmentation is valid only when `w_R` and `w_T` are on the same population scale (both from `adjust()`); Hájek self-normalization gives *asymptotic* DR (ratio bias `O(1/n)`). Phase-2 `aipw()` should require `adjust()`-calibrated weights + assert `|Σw_R−Σw_T|/Σw_T < rtol`. | Records the correctness precondition so AIPW was not built on an unstated assumption. **Superseded by the 2026-08-01 decision above:** `aipw()` now enforces this contract with `rtol = 1e-6`. |
 | 2026-07-15 | **Default estimator = sklearn `HistGradientBoosting{Regressor,Classifier}`** (dispatched by outcome type via `_is_discrete_series`); pluggable via **`model=`** — a single sklearn estimator (cloned per outcome; one type only for mixed outcomes), a `{"_discrete": clf, "_continuous": reg}` **type map** (a missing type falls back to `"auto"`), or a `{outcome_column: estimator}` **column map**. | One robust default for continuous **and** binary outcomes, mixed/categorical features, and non-linearity, with **no new dependency** (IPW already uses `HistGradientBoostingClassifier` for custom models). True XGBoost/LightGBM stay optional plug-ins (balance keeps deps light — copilot §7). **Caveat:** a non-linear default makes phase-1 `μ̂_OM` a pure g-computation estimate (not auto-DR); a *linear* estimator **fit by WLS with the adjusted IPW weights (after `adjust()`)** recovers the exact DR identity only as a special case, and the AIPW phase restores DR for any estimator. |
 | 2026-07-16 | **`fit_outcome_model` API finalized:** the estimator argument is **`model=`** (renamed from `learner=`), carrying the `"auto"` / estimator / type-map / column-map dispatch above; a new **`variables=`** restricts the model inputs `X` to a validated subset of the covariate columns (default `None` = all covars); the per-outcome estimator choice is logged at **INFO**. | sklearn-like naming (`model=`) with a single argument covering every dispatch mode; `variables=` gives the outcome axis the same covariate-subset control the weighting axis has, without touching the frame's covariate role. |
 | 2026-07-15 | **New `outcome_models/` package** (parallel to `weighting_methods/`). | Distinct axis from `BALANCE_WEIGHTING_METHODS`; room for multiple learners + AIPW helpers. |