# Numerical contracts: what safe mode checks

The library's ambient **safety mode** (see the user guide's "Safe and unsafe mode") checks genuine
numerical **preconditions** and skips them under `safety.unsafe()` or a jax trace. This page is the
op-by-op reference: which operations check what, which properties are only *caveats*, and the
settled answer to "which operations need minimal ranks" (none — a reference result that does not
exist in the literature).

## The classification rule

- **Precondition** — the operation is *undefined or numerically wrong* without the property.
  **Safe mode checks it** and raises; unsafe mode / under-jit skips the check.
- **Caveat** — the operation is *valid and correct as computed*; the property only governs *what
  the result means* (e.g. "this coordinate inner product equals Hilbert–Schmidt"). **Never
  enforced** — enforcing it would reject legitimate use.

The classic example: orthogonality/gaugedness is a **caveat** for a raw coordinate inner product
(it is valid on any frame; the properties only make it *equal HS*) — which is why the semantic
`inner`/`norm` live on the `MANIFOLD` geometry (where the properties are preconditions) while
`T3Tangent.corewise_inner`/`corewise_norm` are the raw coordinate ops (no HS claim, no check).

## The numerical properties and their checkers

| property | meaning | checker |
|---|---|---|
| **same-frame** (`SF`) | two tangents share one tangent space — their frames are *numerically equal* (`safety.frames_equal`, with an object-identity fast path; a jit round-trip of the same frame passes) | built into the checked ops |
| **orthogonal** (`ORTH`) | the frame is orthonormal (U/O/L/R conditions) | `T3Frame.is_orthogonal(atol)` |
| **gauged** (`GAUGE`) | the variations satisfy the gauge conditions (48)–(49) | `T3Tangent.is_gauged(atol)` |
| **minimal rank** | no stored rank is redundant | `has_minimal_ranks` (structural) / `has_numerically_minimal_ranks` (numerical) — **diagnostic only, never enforced** (see the verdict below) |

Checkers are **per stack element** (they return a verdict of shape `stack_shape`); a safe-mode
precondition requires **all** elements to pass. The checks are cheap in loops: the underlying
residuals (`T3Frame.orthogonality_residual`, `T3Tangent.gauge_residual`) are cached on the frozen
objects, so a fixed frame or tangent reused across an inner loop is contracted once. The tolerance
is jax-aware (`rtol_jax`, looser, when any operand is a jax array — jax defaults to float32 — else
`rtol_numpy`).

## What each surface checks in safe mode

`—` = no numerical precondition (structural checks — shapes, ranks, pair consistency — still apply
always, in both modes).

### `T3Tangent`

| op | precondition | caveat (never checked) |
|---|---|---|
| `+`, `−` | **SF** | |
| `* scalar`, `__neg__`, `normalized()` | — | |
| `allclose(other)` | **SF** | |
| `corewise_inner(other)` | **SF** | "= HS iff orthogonal + gauged" (that claim belongs to `MANIFOLD.inner`) |
| `corewise_norm()` | — (unary) | "= HS iff orthogonal + gauged" |
| `to_dense`, `to_t3` | — | realization is gauge-invariant, valid on any frame |
| `probe`/`apply`/`entries` (+ transposes), `*_derivatives` (+ transposes) | — | bare `𝒥`/`𝒥ᵀ` — gauge-invariant on any frame; the Riemannian projector `Π` is the geometry's, applied separately |
| `to_vector`/`from_vector`, `zeros`/`unit`/`zeros_like`, `reverse`, `sum_tangents` | — | |
| `stack_tangents` | **SF** (all leaves) | |
| `stack_frame`, `unstack_*` | — | `stack_frame` deliberately stacks *different* bases |
| the checkers (`is_orthogonal`, `is_gauged`, `has_minimal_ranks`, …) | — | they *are* the checks; non-enforcing by design |

### The geometries (the semantic `inner`/`norm` live here)

| op | precondition | caveat |
|---|---|---|
| `MANIFOLD.inner(t1, t2)` | **SF + ORTH + GAUGE** (both operands) | minimal (for *strict* HS exactness — see the verdict: not needed) |
| `MANIFOLD.norm(t)` | **ORTH + GAUGE** (unary — no SF) | minimal |
| `COREWISE.inner(t1, t2)` | **SF** | — (Euclidean by design; no ORTH/GAUGE) |
| `COREWISE.norm(t)` | — | |
| `MANIFOLD.project` (`Π`), `project_oblique` | **ORTH** | minimal (for oblique's HS-matching purpose) |
| `MANIFOLD.retract(p)` | **ORTH** (gauge-invariant, so ORTH only) | minimal (strict rank preservation — without it, retract drops numerically-redundant rank) |
| `MANIFOLD.project_ambient(frame, grad)` | **ORTH** | — |
| `MANIFOLD.transport(v, new_frame)` | **ORTH** (the new frame) | — |
| `MANIFOLD.randn`/`random_orthogonal`/`randn_like` | **ORTH** (via the projection) | minimal (for a *true* Gaussian on `T_xM`) |
| `MANIFOLD.frame`, `COREWISE.frame`, `COREWISE.{randn, project, retract, randn_like}` | — | `frame` *produces* the orthonormal frame; corewise ops are gauge-free by design |

### `GaussNewtonModel` / `UniformGaussNewtonModel`

| op | precondition |
|---|---|
| `gradient`, `gn_hessian(p)`, `jacobian(p)`, `gn_quadratic(p)`, `evaluate(p)` | **SF** — `p` must live at the model's frame (checked numerically, identity fast path). The frame's orthogonality is a construction invariant (`geometry.frame(x)` produces it), not a per-op check. |

### Precondition-free surfaces

| surface | why |
|---|---|
| `TuckerTensorTrain.inner`/`norm` | **exact HS for any cores** (`use_orthogonalization` is a stability option, not a correctness requirement) |
| `TuckerTensorTrain` arithmetic, sampling, `t3svd`, `t3m`, conversions, constructors | exact for any cores; only structural checks |
| `corewise.*` | the raw coordinate layer; structural shape-match only |
| the backend sampling machinery (`probing`/`apply`/`entries` sweeps and transposes) | bare `𝒥`/`𝒥ᵀ` contractions, frame/gauge-agnostic |
| `t3_orthogonal_representations`, the `T3Frame`/`T3Variations` constructors | structural validation always (both modes); the orthogonal representation *produces* an orthonormal frame |

## Minimal ranks: the settled verdict

Minimal rank splits into **structural** (`has_minimal_ranks` — ranks equal the structural minimum;
cheap integer arithmetic) and **numerical** (`has_numerically_minimal_ranks` — no stored rank
numerically redundant). Which operations actually *need* minimal ranks was settled empirically
(each op compared on a minimal vs a non-minimal *orthogonal* frame against the dense oracle):

| op | needs minimal? | evidence |
|---|---|---|
| `MANIFOLD.inner`/`norm` | **NO** | the gauged coordinate inner product equals the dense HS value *exactly* on a non-minimal orthonormal frame — **orthogonal + gauged suffices** |
| `manifold_dim` / `tangent_space_dimension` | **NO** | the formula matches the true tangent-space dimension for any ranks |
| `MANIFOLD.retract` | **caveat only** | still a valid first-order retraction on a non-minimal frame; it just *drops* the numerically-redundant rank (desirable cleanup) — minimal buys only strict rank preservation |
| `MANIFOLD.randn` / `project_oblique` | **NO** | correct on any orthonormal frame |
| `MANIFOLD.project` / `project_ambient` / `transport`, the gauge projections | **NO** | orthogonality suffices |

**Verdict: minimal rank is not a correctness precondition for any verified operation**, so it is
never checked — a minimal-rank gate would reject legitimate rank-redundant frames for no
correctness reason. It survives as the `retract` rank-preservation caveat and as the diagnostic
checkers. (Related fact: `t3_orthogonal_representations` does *not* guarantee structural
minimality — build from a minimal-rank point if you need rank preservation.) Naming rule: bare
`minimal_ranks` means the structural notion; `numerically_minimal` means the SVD-grade notion.

---

*The decision record behind this page — the op-by-op sweep, the experiments, and the sign-off —
is preserved as [`contributor/numerical_contract_catalog.md`](contributor/numerical_contract_catalog.md).*