test: Java golden-value oracles for the five DCE math cores + P1-2/P1-3 fixes

Add bit-for-bit (1e-12) golden-value oracle tests pinning the C++ pure-math
and functional cores against the compiled upstream Java library (openjdk 17):

- HyperIdealGoldenJava: Clausen/Л/ImLi2, ζ13/14/15/ζ, both tetrahedron-volume
  formulas (real de.varylab…Clausen / HyperIdealUtility).
- EuclideanGoldenJava / SphericalGoldenJava: angle formulas + β relations + Л
  energy terms, plus FULL-MESH oracles driving the real EuclideanCyclicFunctional
  / SphericalFunctional on a shared tetrahedron — per-vertex gradient (Θ−Σα) and
  ΔE = E(x)−E(0) (C++ Gauss-Legendre path integral vs Java closed form).
- SphericalGoldenJava.FullMeshEdgeDofGradient: edge-DOF gradient (vertex + edge
  components, α_opp⁺+α_opp⁻−θ_e) vs raw conformalEnergyAndGradient — locks
  Finding 3 at the solution level (audit items 4 & 5).
- PeriodMatrix.NormalizeModulus_GoldenJava: τ-reduction fold convention vs the
  real DiscreteEllipticUtility.normalizeModulus (audit items 7 & 8).

Subtlety documented: the spherical oracles call Java's raw
conformalEnergyAndGradient, not evaluate() (which pre-runs a Brent gauge
maximization that C++ factors into the Newton solver's spherical_gauge_shift).

Also:
- P1-2 (layout.hpp): Euclidean holonomy now uses a per-cut-edge rigid-motion fit
  g(z)=a·z+b, exposing residual_rotation = |arg(a)| as a diagnostic; non-
  regressive (flat case a=1 reduces to the old midpoint formula).
- P1-3 (period_matrix.hpp): is_in_fundamental_domain fixed to the correct
  half-open SL(2,ℤ) domain (−½ ≤ Re < ½). Updated the now-exposed
  ComputePeriodMatrix_ReducedTau_InFD to assert the normalizeModulus domain
  (closed +½ edge) instead.

Test counts (single source of truth = doc/api/tests.md): 272/272 pass, 0
skipped (26 non-CGAL + 246 CGAL).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

code/tests/test_hyper_ideal_utility.cpp

@@ -4,10 +4,12 @@
 // Port of de.varylab.discreteconformal.functional.HyperIdealUtilityTest (Java/JUnit).
 
 #include "hyper_ideal_utility.hpp"
+#include "hyper_ideal_geometry.hpp"
 #include "clausen.hpp"
 
 #include <gtest/gtest.h>
 #include <cmath>
+#include <complex>
 
 using conformallab::calculateTetrahedronVolume;
 using conformallab::calculateTetrahedronVolumeWithIdealVertexAtGamma;
@@ -93,3 +95,43 @@ TEST(HyperIdealUtilityTest, CompareGeneralAndIdealFormulaCase2) {
     double V  = calculateTetrahedronVolume(bi, bj, bk, ai, aj, ak);
     EXPECT_NEAR(Ve, V, 1e-12);
 }
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Golden-value oracle tests — pin the C++ pure-math core bit-for-bit against the
+// upstream Java reference (de.varylab.discreteconformal.functional.{Clausen,
+// HyperIdealUtility}), captured by running the compiled Java library (openjdk 17)
+// on these exact inputs.  Unlike the FD gradient checks (which only verify
+// curl-freeness, since the C++ energy is the path-integral of its own gradient),
+// these lock the absolute values of the math-critical helpers against an
+// independent implementation, catching any silent convention/formula drift.
+//
+// To regenerate: see doc/reviewer/java-port-audit.md (oracle harness recipe).
+// Values are Java's Double.toString output (shortest round-trip).  Tolerance is
+// 1e-12 (well above the ~1e-15 inter-platform libm divergence for these ranges).
+// ─────────────────────────────────────────────────────────────────────────────
+TEST(HyperIdealGoldenJava, ClausenLobachevskyImLi2) {
+    EXPECT_NEAR(conformallab::clausen2(0.7),  0.954448086482735,  1e-12);
+    EXPECT_NEAR(conformallab::clausen2(2.5),  0.4335982032355327, 1e-12);
+    EXPECT_NEAR(conformallab::clausen2(-1.3), -0.9897032532295984, 1e-12);
+    EXPECT_NEAR(Lobachevsky(0.9),             0.4121734067662043, 1e-12);
+    EXPECT_NEAR(conformallab::ImLi2(std::complex<double>(0.3, 0.4)),
+                                              0.46136289181910894, 1e-12);
+}
+
+TEST(HyperIdealGoldenJava, ZetaFamily) {
+    EXPECT_NEAR(conformallab::zeta13(0.5, 0.7, 0.9), 2.663195966482385,  1e-12);
+    EXPECT_NEAR(conformallab::zeta14(0.4, 0.8),      1.8262295633065202, 1e-12);
+    EXPECT_NEAR(conformallab::zeta15(0.6),           2.216976794676588,  1e-12);
+    EXPECT_NEAR(conformallab::zeta(0.5, 0.7, 0.9),   1.6156519307269948, 1e-12);
+}
+
+TEST(HyperIdealGoldenJava, TetrahedronVolumes) {
+    // Generic non-degenerate generalized hyperbolic tetrahedron.
+    EXPECT_NEAR(calculateTetrahedronVolume(0.6, 0.7, 0.8, 0.5, 0.9, 0.4),
+                2.9074633382516435, 1e-12);
+    // One ideal vertex at gamma, non-symmetric angles (Java test2 inputs).
+    EXPECT_NEAR(calculateTetrahedronVolumeWithIdealVertexAtGamma(
+                    0.6623267054958116, 1.437248992086214, 1.0420169560077686,
+                    0.6896178197389236, 0.5195634857410114, 0.6304500578493993),
+                2.0459750326926214, 1e-12);
+}