Add prepared Schur gravity reduction and contract tests

experiments/GRAVITY_REDUCTION_IMPLEMENTATION_2026-09-17.md

@@ -0,0 +1,93 @@
+# Reduced gravity linearization
+
+This branch supplies the linear algebra for the gravity-reduced nonlinear
+formulation. It does not change the physics equations, normalization, default
+Newton strategy, or model specification API. Gravity completion and accepted/trial
+state ownership belong to the nonlinear context; the reduced operator has no
+preparation or state-mutation entry point.
+
+## Contract
+
+Write the full normalized root equations as `F(u,z)=0`, `G(u,z)=0`, where `z`
+contains the gravity gradient and potential. The typed gravity partition selects
+those physical blocks from the compiled form. All other root coordinates and
+rows, including optional specification borders, stay in the retained system.
+Row and column orderings need not agree.
+
+At a prepared state, `GravityReducedOperator` applies
+
+```
+S p = F_u p - F_z (G_z^{-1} G_u p).
+```
+
+`TryLiftTangent` returns `[p, -G_z^{-1} G_u p]`. On the gravity manifold this
+is the derivative of the completed state with respect to retained coordinates.
+`TryCondenseRightHandSide` and `TryLiftCorrection` also support a nonzero gravity
+right-hand side:
+
+```
+b_reduced = b_F - F_z G_z^{-1} b_G,
+delta_z = G_z^{-1} (b_G - G_u delta_u).
+```
+
+Consequently a small remaining gravity defect is retained in the Newton
+equations rather than silently dropped. These formulas require an invertible
+gravity block; they do not regularize a singular full stellar problem or remove
+the n=3 homology.
+
+The production gravity subsystem owns its inner backend and restricted full
+inverse. The reduced operator borrows it, allocates workspaces once, and checks
+its preparation generation through `IsCurrent()` before and after actions. Each
+inner solve starts from zero to avoid importing a previous Krylov direction into
+the next action. A successful backend report is checked against the requested
+true-residual threshold. The `Try` APIs return numerical failures without
+replacing the caller's output; the MFEM `Mult` adapter throws the typed
+`GravityReductionFailure` because a void action cannot return failure data.
+The outer owner must translate this into a failed numerical attempt.
+
+`GravityReducedPreconditioner` injects a retained residual into the full root,
+applies the supplied full inverse, and extracts retained coordinates. The
+retained block of the exact full inverse is exactly `S^{-1}`. For an approximate
+inverse this provides an interchangeable preconditioner without assembling a
+second approximate physics operator. Its stationary/flexible application
+contract is propagated at compile time. It never rebinds the full inverse to a
+reduced matrix.
+
+## Accuracy and cost
+
+The Schur formula is exact; an iterative inner solve evaluates it approximately.
+Tolerance-stopped inner Krylov is not necessarily a linear map of its right-hand
+side. FGMRES permits varying preconditioners, not arbitrary errors in its
+operator. The nonlinear owner must choose sufficiently tight inner tolerances,
+verify the lifted correction against the full Jacobian and full right-hand side,
+and refuse an inaccurate correction. This gate is also necessary when the state
+has only approximately completed gravity.
+
+An action costs one gravity solve and two full Jacobian applications outside the
+inner solve. Projection preconditioning costs one full inverse application.
+This first implementation deliberately reuses existing operators and inverses;
+its cost should be measured before replacing them with specialized gravity
+kernels. All scratch vectors persist across applications. Objects borrow stable
+addresses, are not reentrant, and must not outlive their prepared subsystem or
+full inverse.
+
+## Verification
+
+The focused test source `tests/solver/gravity_reduction.cpp` covers:
+
+- Central finite differences of a genuinely curved, analytically completed
+  gravity manifold; freezing gravity produces a detectably different derivative.
+- Tangent lifting and vanishing gravity action.
+- Schur condensation/lifting versus a direct monolithic solve, including a
+  nonzero gravity right-hand side and a coupled optional border.
+- The exact inverse projection identity and compile-time propagation of both
+  stationary and flexible inverse contracts.
+- Reduced and monolithic Newton convergence to the same known equilibrium.
+- Numerical failure propagation without partially published results, true-defect
+  gate enforcement, stale preparation rejection, and dimension checks.
+- Linearity, repeatability, and input/output alias safety with an exact inner
+  solve.
+
+These algebraic tests establish the reduction contract. They do not establish
+FEM convergence, a faster implementation, or an additional virial-qualified
+stellar equilibrium; those require the integrated runtime experiments.