fix(graphical): EP statistics completion — F6 truncated KL + F7(b) evidence recording

[Jammy2211]

Summary

Closes out the #1332 audit's statistical findings (tracker #1353). F6: TruncatedNormalMessage.kl now computes the exact same-support KL from truncated moments — the old untruncated approximation distorted the EPHistory convergence metric as posterior mass approached the bounds (live in HowToFit ch3 via af.TruncatedGaussianPrior); the new expression reduces to the Gaussian formula as bounds recede and is Monte-Carlo-verified at interior, near-bounds and half-bounded geometries. F7(b): the search-driven factor projection now records the sampler's log-evidence on the projected mean field's log_norm (AbstractSearch.optimise → MeanField.from_priors(log_norm=…)) — implementing the design README §5 already documented. With F7(a) (#1351) and F7(c) (#1345), all three legs of "evidence bookkeeping broken" are now fixed: EPMeanField.log_evidence is trustworthy for model comparison when factor searches are nested samplers (MCMC/MLE factors contribute 0 — documented).

Also carries the #1336 Recommendation-A decision into README §6 (keep all three deterministic-composition mechanisms; tighter-vs-modular trade-off documented; compound pattern is the declarative surface) and replaces §5's stale audit warning.

API Changes

Behaviour fixes + one optional argument. TruncatedNormalMessage.kl returns the exact truncated KL (convergence-metric values change for truncated-prior EP fits — correctly). MeanField.from_priors gains log_norm=0.0. EPMeanField.log_evidence becomes meaningful in sampler-driven fits (previously silently missing all sampler evidence).
See full details below.

Test Plan

• Full suite: 1474 passed / 14 skipped / 1 pre-existing failure — test_full_hierachical, now triaged on test_full_hierachical flaky — hierarchical EP lands at wrong mu_logt #1352 as deterministic test-order dependence (0/6 standalone with bit-identical value, 3/3 whole-file; id-counter → EP-update-order hypothesis posted); unrelated to this diff
• New test_ep_statistics_completion.py — 7 tests: MC-vs-analytic truncated KL at 3 geometries, wide-bounds reduction to the Gaussian formula, near-bounds divergence from the old formula, support-mismatch raise, from_priors log_norm plumbing (incl. through the fix(graphical): EP statistics fix batch — F1/F2/F4/F8 from #1332 #1351 operator algebra)
• EP integration smoke 3/3 PASS (ep_parity initially failed on a stale resume cache — degenerate reloaded samples, joint sigma=0; fresh run passes; noted for the cache-hygiene file)
• test_static regression caught in-suite and fixed (two-level getattr: StaticResult has no samples)

Validation checklist (--auto run — plan on the issue)

• Effective level: supervised (--auto chain; human directed all five follow-ups 2026-07-10, research: EP review phase 5 — reconcile the three deterministic-variable mechanisms #1336 Rec-A decision human-made)
• Gate: tests 1474/14 + documented test_full_hierachical flaky — hierarchical EP lands at wrong mu_logt #1352 order-dependence · smoke 3/3 fresh · review CLEAN · Heart YELLOW, identical 6-reason acked set
• Human: merge, amend, or reject — then log the outcome

Full API Changes (for automation & release notes)

Added

• MeanField.from_priors(priors, log_norm=0.0) — optional evidence carried by the projected mean field (the per-factor Ẑₐ of README §5 Eq. 14)

Changed Behaviour

• TruncatedNormalMessage.kl(dist) — exact same-support truncated KL via truncated moments (scipy.truncnorm.stats); previously the untruncated Gaussian formula. Different-support case still raises. EP convergence-metric values on truncated-prior graphs change (correctly)
• AbstractSearch.optimise (EP factor updates) — the projected mean field's log_norm is the sampler's log-evidence of the tilted fit (0.0 for searches without an evidence estimate, and for results with no samples, e.g. StaticResult)
• autofit/graphical/README.md — §5 audit warning replaced (F7 fixed; nested-sampler requirement stated); §6 records the research: EP review phase 5 — reconcile the three deterministic-variable mechanisms #1336 Recommendation-A decision

Migration

• None. Code that compared EPMeanField.log_evidence values across versions should note they were previously missing all sampler evidence.

🤖 Generated with Claude Code