Scale prepared gravity consistency by uncancelled field contributions

experiments/GRAVITY_PREPARED_ROUNDOFF_2026-09-17.md

@@ -0,0 +1,45 @@
+# Gravity prepared-residual arithmetic experiment
+
+This hypothesis branch changes only the arithmetic assessment used after a
+gravity correction has passed its inner true-residual gate. It does not change
+that inner tolerance, the full-system lifted Newton gate, nonlinear merit
+acceptance, physical equations, or virial validation.
+
+For fixed retained state, write the normalized gravity residual as
+`G = A_q q + A_phi phi + b`. Its norm can be tiny while the separate terms are
+large. Estimating arithmetic from `||G||` and the combined correction action
+therefore misses cancellation and the floating-point addition of corrected
+gravity coefficients.
+
+Before changing the candidate, the workspace now measures the normalized
+gradient and potential actions separately, for both the old state and its
+correction. It infers the fixed source as `b = G_old - A_q q - A_phi phi`.
+Selection uses the compiled field block types, and applications reuse the
+prepared gravity operator. Scratch vectors are allocated with the workspace.
+
+The assessment uses `256 epsilon` times the sum of those five contribution
+norms and the norms of the old, desired, and freshly prepared gravity residuals.
+This is an explicit arithmetic estimate, **not a rigorous forward-error bound**:
+it does not bound cancellation inside each individual field action. The factor
+does not create an absolute residual floor, so a common scaling of the gravity
+equations scales the assessment equally.
+
+Two separate requirements remain:
+
+1. The discrepancy between the affine prediction and freshly prepared gravity
+   residual must fit the arithmetic estimate.
+2. The prepared residual's distance from its target must not exceed the
+   **measured** inner true residual plus that estimate.
+
+Diagnostics retain the raw affine discrepancy, raw target defect, arithmetic
+estimate, and resulting target threshold separately. Nonfinite or negative
+norm inputs fail the assessment. A failed preparation leaves these measurements
+unavailable rather than reusing the preceding trial's values. Diagnostics also
+report whether compact gravity operator and inverse applications were selected.
+
+Three focused tests, appended to `tests/solver/gravity_reduction.cpp`, cover
+large cancelling contributions, rejection of defects beyond either gate,
+nonfinite measurements, and scaling over twenty-four orders of magnitude.
+The real stellar rejection must still be reproduced and reassessed; passing a
+synthetic arithmetic test alone establishes neither the hypothesis nor stellar
+convergence.