Module encode 

Kantorovich-certified encode atlas (issue #1010).

Encoding a row x ∈ ℝᵖ against a FROZEN SAE dictionary is, per atom k, the coordinate-only Newton problem

min_t  f_k(t) = ½‖x − z_k · B_kᵀ Φ_k(t)‖² + prior_k(t),

with the amplitude z_k and decoder block B_k held fixed (the encode freezes the dictionary; only the latent coordinate t moves). Newton on F(t) = ∇f_k(t) converges quadratically from a start t₀ into the unique root in a certified ball whenever the Newton–Kantorovich quantity

h = β · η · L ≤ ½,    β = ‖F'(t₀)⁻¹‖,   η = ‖F'(t₀)⁻¹ F(t₀)‖,

where L is a Lipschitz constant of F' (the Hessian of f_k) on a region containing the Newton iterates. h is CHECKABLE per row in O(q³) (q = latent_dim, tiny), so each fast-path encode carries its own exactness certificate.

The closed-form Hessian-Lipschitz constant L

Write m(t) = z·BᵀΦ(t) ∈ ℝᵖ (the reconstruction) and r(t) = m(t) − x. Then f = ½‖r‖² + prior and, differentiating three times,

∇³f = 3·sym(J_mᵀ : ∇²m) + ⟨r, ∇³m⟩ + ∇³prior,

so an operator-norm bound on the chart is

L ≤ 3·‖J_m‖·‖∇²m‖ + ‖r‖·‖∇³m‖ + L_prior,

with ‖∂^g m‖ ≤ |z|·(Σ_m ‖B_{m,:}‖)·B_g, where B_g = sup_chart max_m ‖∂^g Φ_m‖ is the per-column jet sup of the basis family — closed form per family (BasisHessianLipschitz). ‖r‖ is bounded by ‖x‖ + |z|·(Σ_m‖B_{m,:}‖)·B_0. The ARD/von-Mises prior L_prior is a closed-form constant from the prior strength. Every bound is conservative (an over-estimate of L only SHRINKS the certified radius — it can never certify a row that does not converge).

Pipeline

1. Offline, per atom (EncodeAtlas::build): chart centers t_c on the atom’s coordinate grid (the SHAPE_BAND grid idiom), each with a certified Newton radius R_c solved from the Kantorovich inequality at the worst-case in-chart start.
2. Online, per row (EncodeAtlas::certified_encode_row): route to the nearest chart, start from its distilled IFT predictor, take one or two Newton steps, then the h ≤ ½ check AT the start point is the per-row certificate.
3. Uncertified tail: rows whose start fails h ≤ ½ are FLAGGED (counted in EncodeResult::encode_uncertified_count) and must be routed by the caller to the existing exact multi-start solve. No approximation enters silently.

Structs

AtlasConfig

Configuration for EncodeAtlas construction and online encode. All fields are explicit; the atlas never reads global state and adds no CLI flags.

AtomEncodeAtlas

The per-atom encode atlas: a set of certified charts covering the atom’s coordinate domain, plus the decoder/amplitude scaling needed to recompute a per-row certificate online.

CertifiedChart

One offline-certified chart: a center, its Kantorovich constants, and the certified Newton-convergence radius R_c solved from h = β·η·L ≤ ½ at the worst-case in-chart start.

ChartRegion

A chart region on an atom’s latent coordinate: a center t_c plus a certified in-chart radius. Over the ball ‖t − t_c‖ ≤ radius the jet sup bounds returned by BasisHessianLipschitz hold, so the Kantorovich constant L computed from them is valid for any start in the ball.

EncodeAtlas

The encode atlas: per-atom certified charts plus the online certified-encode driver (issue #1010).

EncodeResult

Result of a certified encode over a batch of rows, carrying the honesty flag: how many rows could NOT be certified and were flagged for the exact multi-start fallback (issue #1010 — no approximation enters silently).

RowCertificate

Per-row Kantorovich certificate at a start t₀ for one atom encode.

Constants

KANTOROVICH_THRESHOLD

The Kantorovich convergence threshold h ≤ ½. Below this the Newton iteration is guaranteed to converge quadratically into the unique root in the certified ball; at or above it the start is uncertified.

Traits

BasisHessianLipschitz

Per-column sup-norm bounds on the first three coordinate jets of a basis family Φ(t), valid over a stated ChartRegion (issue #1010). These are the analytic ingredients of the Hessian-Lipschitz constant L — see the module docs for the assembly. value_sup bounds max_m |Φ_m|, jacobian_sup/hessian_sup/third_sup bound max_m ‖∂^g Φ_m‖.

Functions

row_certificate

Compute the per-row Kantorovich certificate for encoding target row x against atom atom at start coordinate t₀, with fixed amplitude z and the chart’s closed-form Lipschitz constant lipschitz. Returns the certificate AND the Newton step δ = −H⁻¹ g so the caller can advance.