Module laplace_sampler_contract 

Laplace-correction / mode-posterior sampler contract (trait-inversion #1521).

gam-solve’s REML inner loop (#784 block-local quadrature correction) and the custom-family never-fail covariance path call into the gam-inference-tier NUTS / importance-sampling engine (inference::hmc_io, ~8k lines) — an UP-edge that keeps gam-solve in the inference SCC.

The COMPUTATION (NUTS, importance sampling, the directional-cubic eigen diagnostic) is irreducibly above gam-solve and STAYS UP in hmc_io. Only the neutral surface is contract-downed here, mirroring the rho_posterior data-down (#1521):

• the plain-DATA result carriers gam-solve reads (BlockQuadratureMarginal, BlockQuadratureMoments, LaplaceTrustworthiness);
• the caller-supplied BlockExcessTarget evaluator gam-solve IMPLEMENTS (its Gam784BlockTarget), so the trait must live below both;
• the CORRECTOR TRAIT LaplaceMarginalCorrector gam-solve calls THROUGH; the monolith / gam-inference implements it over hmc_io and injects the impl via the process-level registry below.

The pure threshold math (laplace_skewness_threshold, laplace_trustworthiness_from_skewness) has no sampler dependency, so it is moved down outright (gam-solve calls it directly).

When no impl is registered (e.g. a build that never links the sampler tier) the sampler getters return None and gam-solve degrades to its existing decline paths — the #784 correction returns zero (already a frequent decline outcome) and the never-fail covariance path keeps the optimizer-conditional covariance (already the Err(reason) fallback). The contract therefore introduces no behavioral cliff and no stub.

Structs

BlockQuadratureMarginal

Block-local deterministic quadrature correction (issue #784).

BlockQuadratureMoments

Quadrature-weighted moments of the per-node gradient channels — the integration-side half of the #784 exact-gradient seam. All expectations are under p ∝ q·e^{−ΔF} over the SAME deterministic nodes that produced the value, so the spliced value and its assembled gradient cannot desync (#901).

LaplaceTrustworthiness

Adaptive, block-local Laplace-trustworthiness verdict (issue #784): which curvature directions are too non-Gaussian for the plain Laplace summary.

Constants

BLOCK_GH_MAX_DIM

Maximum curvature-heavy block dimension for deterministic product Gauss–Hermite quadrature. The fine rule has five nodes per axis, so the cap follows from the 4096-node work ceiling: 5^5 = 3125, while 5^6 = 15625.

Traits

BlockExcessTarget

Caller-supplied evaluator for the non-Gaussian remainder ΔF(t) of the local log-posterior, restricted to the curvature-heavy block subspace (issue #784).

LaplaceMarginalCorrector

The gam-inference-tier sampler for the #784 block-local Laplace correction.

Functions

laplace_marginal_corrector

The registered #784 block-local Laplace corrector, or None when the embedding has not initialized the inference tier.

laplace_skewness_threshold

Auto-derive the per-direction skewness threshold τ(n) separating Laplace-trustworthy directions from those that need the higher-order correction / sampling fallback. Derived purely from the effective sample size, no tunable flag: (5/24)γ_r² > 1/n_eff ⇔ |γ_r| > sqrt((24/5)/n_eff).

laplace_trustworthiness_from_skewness

Adaptive, block-local Laplace-trustworthiness verdict (issue #784): flag the directions whose standardized skewness exceeds laplace_skewness_threshold. No linear algebra of its own — consumes the directional cubic diagnostic.

set_laplace_marginal_corrector

Register the #784 block-local Laplace corrector. First writer wins; a later call is ignored so a re-init can never swap a live criterion mid-run.