Module laplace_sampler_contract 

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

gam-solve’s REML inner loop (#784 block-local sampled marginal 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 (BlockSampledMarginal, BlockSampledMoments, GaussianModePosterior, LaplaceTrustworthiness);
• the caller-supplied BlockExcessTarget evaluator gam-solve IMPLEMENTS (its Gam784BlockTarget), so the trait must live below both;
• the two SAMPLER TRAITS (LaplaceMarginalSampler, GaussianModePosteriorSampler) gam-solve calls THROUGH; the monolith / gam-inference implements them 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

BlockSampledMarginal

Block-local sampled marginal correction (issue #784).

BlockSampledMoments

Self-normalized importance-weighted moments of the per-draw gradient channels — the sampler-side half of the #784 exact-gradient seam. All expectations are under p ∝ q·e^{−ΔF} over the SAME fixed-seed draws that produced the value, so the spliced value and its assembled gradient can never desync (#901).

GaussianModePosterior

Honest posterior summary from sampling the proper Gaussian posterior N(mode, H⁻¹) — the terminal never-fail rung of the custom-family covariance escalation. Field-for-field the monolith hmc_io type.

LaplaceTrustworthiness

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

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).

GaussianModePosteriorSampler

The gam-inference-tier sampler for the never-fail Gaussian mode posterior (custom-family covariance escalation). Implemented UP over hmc_io::sample_gaussian_mode_posterior (which auto-derives its NutsConfig::for_dimension(mode.len()) internally — that NUTS config never crosses the contract) and injected DOWN via set_gaussian_mode_posterior_sampler.

LaplaceMarginalSampler

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

Functions

gaussian_mode_posterior_sampler

The registered never-fail Gaussian-mode-posterior sampler, or None when the sampler tier is not linked (the custom-family path then retains the optimizer-conditional covariance — its existing fallback).

laplace_marginal_sampler

The registered #784 Laplace-correction sampler, or None when the sampler tier is not linked / not yet initialized (gam-solve then declines the correction, returning the zero contribution — a safe no-op).

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_gaussian_mode_posterior_sampler

Register the monolith’s hmc_io-backed never-fail Gaussian-mode-posterior sampler. First writer wins (see set_laplace_marginal_sampler).

set_laplace_marginal_sampler

Register the monolith’s hmc_io-backed #784 Laplace-correction sampler. Called once at process init by the gam-inference tier. First writer wins; a later call is ignored (returns Err with the boxed value) so a re-init can never swap a live sampler mid-run.