Learn the SCM, phase 2: count and posterior mechanisms, a lean pass, and the RL audit

[raphaelrrcoelho]

Phase 2 of the learn-the-SCM program, on top of the fit_scm core merged in #34. Two new mechanism families, a lean pass, and an audit that answers a direct question about this library's identity.

What this adds

PoissonGLMFit — a log-linear count mechanism fitted by IRLS, for binned point-process data. Requested by a downstream causalrl.neuro consumer: lag-unrolled spike nodes routinely carry 6–12 lagged parents, and at ~3 levels each TabularCPT needs 729 to 531,441 rows, nearly all unobserved and dominated by the Laplace prior. A GLM is linear in the parents where the table is exponential in them, and it keeps the point-process structure a table discards. invertible=False is correct rather than a limitation — a Poisson draw is not recoverable from (parents, count), so counterfactuals at this node are genuinely unidentified and the L3 guard refuses them. Opt-in via families={...}; the dtype heuristic still routes counts to TabularCPT.

BayesianLinearFit — posterior structural coefficients via NUTS, behind the existing causalrl[numpyro] extra. Where fit_scm returns one point-estimated mechanism and fit_scm_mec represents the SCM belief as a discrete list of equivalence-class members, this is the continuous version: the posterior-mean mechanism plus the draws behind it as mechanism.posterior, so mechanism uncertainty can be carried into an estimand instead of discarded. Every invariant its siblings satisfy still holds — invertible=True, residual attached, exact round-trip, scored by R².

A fitted SCM is now a reinforcement-learning environment you can act in. fit_scm returns the library's ordinary StructuralCausalModel, and envs/base.py already accepts one — so this composition worked by construction and is now executed rather than assumed: tests/test_learned_scm_as_env.py fits a world model from a confounded log, runs it as a Gymnasium bandit, and pins that sampled rewards follow the interventional order where the logged conditional reverses.

A lean pass removing dead surface, sharing duplicated logic, and replacing one vacuous test with a discriminating one.

The audit, and its honest answer

The library is called causalrl, and this sub-project added six ways to fit a mechanism from a static table. Fitting a Poisson GLM is supervised learning; E[Y | do(A=1)] is an estimand, not a value function. So the question was asked directly: is any of this reinforcement learning?

The answer recorded in docs/learned_scm/PROGRESS.md is partly, and the confirming evidence is a zero: git grep "fit_scm\|FitReport\|provenance=\"fitted\"" -- src/causalrl/envs src/causalrl/agents returned no matches. Nothing in the library's RL half had ever heard of the learned model. This sub-project grew beside the RL spine rather than into it.

• No, on its own terms. No policy, no reward, no exploration, no regret inside fit_scm.
• Yes, for what it produces. A learned SCM is what model-based RL calls a world model, and it now reaches the environment surface with no adapter.
• Not yet, where it would matter most. CausalMBRLAgent has no scm= parameter — all six of its planners build a per-action adjusted-value table from columnar arrays — so "model-based" is currently true in the causal-identification sense, not the model-based-RL sense. The one SCM-consuming agent, CounterfactualOptimalPolicy, is correctly refused on a default fitted model by the L3 provenance guard. That seam is specified in four items and deliberately left unbuilt: it is sub-project 4.

examples/learned_scm_policy.py closes the loop end to end — learn from confounded logs, plan in the model with Thompson sampling, score the resulting policy in the true world. Mean regret 0.000 (causal structure) vs 0.100 (confounder-blind) across 5 seeds, with both world models fitting E[Y|A] to within 0.008 of each other, so the difference is structure rather than fit quality. A randomized-log control in the same run shows the causal machinery buying nothing (0.000 vs 0.000) when the log was not confounded. That control is the point: the edge is the decision in the confounded regime, not accuracy in general. It is a synthetic world with exact ground truth, not a benchmark result, and the example says so in its own output.

What review caught that tests did not

Every defect below passed a green test suite.

• A mechanism that ignored its own noise. PoissonGLMFit's tests passed against an implementation that discarded the noise argument and returned the fitted mean — the only test calling the mechanism asserted mean(drawn) ≈ e^0.8, which a mean predictor satisfies exactly. The entire inverse-CDF construction was pinned by nothing. Now pinned by integer-valuedness and Poisson dispersion, mutation-verified.
• A prior on the wrong scale. BayesianLinearFit standardised X but not y, leaving sigma ~ HalfNormal(1) on the child's raw scale. The MAP condition σ⁴ + nσ² − SSR = 0 gives posterior sigma ≈ 668 for a true residual sd of 10 000 — a 15× underestimate that would make every downstream rollout and counterfactual band silently overconfident.
• A guard that bounded the wrong quantity. The Poisson support table is (n, cap+1), rebuilt per call, so capping columns alone still permitted ~2.4 GB. Now one budget on n * (cap + 1), checked before the first allocation.
• A class that did not ship. BayesianLinearFit was absent from both export tables and from _FAMILY_NAMES, so it was reachable only by full module path and FitReport.summary() printed family=BayesianLinearFit beside family=poisson_glm. Its author worked in a worktree cut before PoissonGLMFit existed and never saw the pattern.
• A documentation snippet that demonstrated nothing. docs/tour.md advertised a persistent intervention as "a lever no arm exposes", then pinned the mediator with the chosen arm — d-separating the outcome from the lever. Measured: 0.9020 under both do(X=0) and do(X=1).
• A headline number with no test. The example's regret claim could be inverted by scoring each policy inside the model that chose it, and the smoke test stayed green.

Verification

Full CI gate locally: ruff clean, 335 files formatted, pyright src 0 errors / 0 warnings / 0 informations, pytest --cov-fail-under=90 exit 0 — 900 passed, 4 skipped, coverage 96.75%. examples/learned_scm_policy.py run end to end and its numbers reproduced independently.

One thing this machine cannot verify. numpyro and JAX are not installed here, so tests/test_bayesian_fit.py skips entirely and its assertions have never executed locally — CI's [numpyro] lane is their first real run and the sole executor of bayesian_fit.py, which is coverage-omitted like its nuts.py sibling. That lane is the gate for this PR.

Backward compatibility

No existing behaviour changes. _is_discrete still routes counts to TabularCPT; both new families are opt-in per node. causalrl.BayesianLinearFit resolves on a core install with no numpyro present — verified — because the export is lazy and numpyro is imported inside fit().