Add prepared gravity subsystem and second-order trial correction

experiments/GRAVITY_SUBSYSTEM_IMPLEMENTATION_2026-09-17.md

@@ -0,0 +1,85 @@
+# Prepared gravity subsystem and curvature correction
+
+This branch introduces solver components; the complete equilibrium equations,
+normalization, and model specification remain the source of truth.
+
+## Block and lifetime contracts
+
+`MakeGravityBlockPartition<Form>(layout)` selects the gravity-gradient and
+gravity-potential blocks by their compiled value and residual types. Its
+constraints reject forms lacking those blocks. The complement is retained in
+root order, including any generated angular-momentum or central-density border.
+There are no string identifiers or fixed root offsets in this selection.
+
+`GravityBlockPartition` also has a checked explicit-index constructor for
+algebraic tests and other compiled adapters. Local partitions may be empty;
+gravity and retained local systems must be square. A globally empty gravity
+system is rejected by the prepared linear backend. Gather/injection require
+preallocated, nonoverlapping storage.
+
+`PreparedGravitySubsystem` owns restricted operator/inverse workspaces and the
+existing prepared linear backend. It borrows the full normalized operator,
+inverse, and communicator at stable addresses. It is neither movable nor
+copyable. Preparation records the root preparation generation. After candidate
+preparation the caller must refresh its physical inverse and explicitly refresh
+the subsystem; stale applications and solves fail. The subsystem does not
+prepare a candidate, change an accepted state, or commit a step.
+
+The exact gravity action is the principal restriction of the root Jacobian.
+The preconditioner is the corresponding restriction of the supplied root
+inverse. This reuses existing normalization, gravity boundary conditions, and
+preconditioning recipes, but does not assert that the restricted inverse is an
+exact gravity inverse. Every solve retains the backend's independently checked
+true-defect gate. Both wrappers preallocate full-vector workspaces; applications
+perform gather/scatter and the existing root actions without allocating their
+own vectors. Full root actions may do unnecessary non-gravity work; a specialized
+gravity action/inverse adapter remains a future optimization requiring equality
+tests against this reference restriction.
+
+Attempted solves, completed inner iterations, failed calls, completed solve time,
+and the last completed solve report are available without history allocation.
+Contract exceptions count as failed calls but do not trigger new collectives to
+measure elapsed time during unwinding.
+
+The existing FGMRES backend now admits ranks with zero local equations while
+requiring a nonempty global system. `GetConfiguration()` returns its immutable
+prescription so another prepared operator can reuse the same backend options.
+
+## Curvature correction
+
+`PreparedGravityCurvatureCorrection` captures `G(x)` and `J_G(x) p` before any
+candidate preparation. For a prepared candidate `x + alpha p` it solves
+
+```
+G_z(x + alpha p) delta_z = G(x) + alpha J_G(x) p - G(x + alpha p).
+```
+
+Only the compact gravity correction is returned. The caller may inject it only
+after a converged inner report, then must prepare and evaluate the complete
+candidate again before applying its usual acceptance rules. In particular,
+improving gravity does not certify the hydrostatic, material, or shape residual.
+
+For smooth equations with uniformly bounded inverse gravity block, the right
+side and correction are second order in `alpha`. This preserves the base and
+Newton tangent even when the base does not lie on the gravity solution manifold.
+It differs from projecting the candidate to `G=0`, which can introduce a finite
+correction at zero step when the base gravity residual is nonzero. Inexact inner
+tolerances control cancellation of the remainder; they cannot replace the outer
+equilibrium and virial checks.
+
+The owner captures a new base for each new Newton direction and invalidates the
+cache when that direction is discarded. The stored base generation is exposed
+for diagnostics; preparing trials intentionally does not invalidate the captured
+base arrays. Reusing those arrays after replacing the base or direction violates
+the caller's explicit lifecycle contract.
+
+## Test coverage
+
+`tests/solver/gravity_subsystem.cpp` covers typed forms with/without a central
+border, noncontiguous and differently ordered row/value maps, invalid maps and
+overlapping storage, exact restricted solves, true-defect failure, nonfinite
+inputs, stale operator/inverse preparation, locally empty MPI partitions,
+globally empty rejection, preserved backend options, zero affine curvature at
+an off-manifold base, and the second-order correction at curved trial geometry.
+The root integration campaign compiles these components and tests real stellar
+states; this branch does not claim a new validated stellar equilibrium.