Module encode 

Kantorovich-certified encode atlas (issue #1010).

Encoding a row x ∈ ℝᵖ against a frozen multi-atom dictionary is the joint coordinate problem

min_{t_1,…,t_K}  ½‖x − Σ_k z_k B_kᵀΦ_k(t_k)‖² + Σ_k prior_k(t_k).

[joint_encode_refine_row] solves that objective with the shared residual. The per-atom atlas below is an initializer and a standalone single-atom projection facility; composing its independent optima is not a multi-atom encode. With the amplitude z_k and decoder block B_k held fixed, Newton on a single-atom field F(t) = ∇f_k(t) converges 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).

EncodeObjective

The TRUE per-row encode objective’s non-Euclidean ingredients (F3), so the Kantorovich certificate certifies the SAME functional the fit optimized t against — not a bare Euclidean stand-in.

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

FallbackTelemetry

The honest cost breakdown of the encode tax (reviewer condition #3). Every (row, atom) encode lands in exactly one of three tiers, in ascending cost:

JointEncodeResult

Result of solving the frozen dictionary’s joint coordinate objective over a batch. converged[row] is a numerical first-order stationarity verdict for the shared-residual objective, not a Newton–Kantorovich certificate.

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

encode_grad_hess

Evaluate one atom’s encode objective gradient F(t) = ∇f_k(t) and the FULL Hessian F'(t) = ∇²f_k(t) at a single coordinate t, for a single target row x and fixed amplitude z. With m(t) = z·BᵀΦ(t), r = m − x, J_m = z·Bᵀ J_Φ:

encode_reconstruction_error

Reconstruction error ‖x − z·m(t)‖ of an encoded coordinate t — the criterion the certified encode minimizes over its candidate charts to pick the GLOBAL basin. m(t) = Bᵀ Φ(t) is the amplitude-1 reconstruction; z is the amplitude. A non-finite reconstruction returns +∞ so it never wins.

joint_encode_fallback_fraction

The JOINT (multi-atom) encode-fallback fraction: the share of rows whose per-row joint reconstruction problem across CO-ACTIVE atoms is NOT covered by the composition of the per-atom certificates, so the row genuinely needs the exact multi-start solve (reviewer condition #3 — the honest encode-tax cost multiplier at scale).

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.