docs: note high-precision requirement for Phase 9c/10 uniformization

The Java uniformization classes (FundamentalPolygonUtility, CanonicalFormUtility)
rely on the *Big arbitrary-precision geometry (MathContext(50)) because products
of hyperbolic isometry generators grow exponentially and double fails to verify
the group relation ∏gᵢ = Id. Record this planning-relevant prerequisite and
resolve the contradiction in java-parity.md, which previously listed *Big as
permanently out of scope.

- CLAUDE.md: † note on the Phase-9 not-yet-ported table
- java-parity.md: *Big exception (localized high-precision substrate for 9c/10)
- phases.md: precision prerequisite as 9c sub-task + effort estimate
- design-decisions.md: new "Scalar type: double, with one localized exception"

Core flattening (Newton/energy/Eigen solver) stays double; the substrate
(cpp_dec_float_50 / mpreal) is localized to the uniformization module only.

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

CLAUDE.md

@@ -191,13 +191,15 @@ The Java library under `de.varylab.discreteconformal` contains these items not y
 |---|---|---|
 | `InversiveDistanceFunctional` | `inversive_distance_functional.hpp` | 9a |
 | Analytic HyperIdeal Hessian | `hyper_ideal_hessian.hpp` (replace FD) | 9b |
-| 4g-polygon boundary walk in `FundamentalDomainUtility` | `fundamental_domain.hpp` (extend) | 9c |
+| 4g-polygon boundary walk in `FundamentalDomainUtility` | `fundamental_domain.hpp` (extend) | 9c † |
 | `DiscreteHarmonicFormUtility` | Phase 10a prerequisite | 10 |
 | `DiscreteHolomorphicFormUtility` | Phase 10a | 10 |
-| `HomologyUtility`, `CanonicalBasisUtility` | Phase 10 | 10 |
+| `HomologyUtility`, `CanonicalBasisUtility` | Phase 10 † | 10 |
 
 When porting a Java class, locate the original in `de.varylab.discreteconformal.*` at [github.com/varylab/conformallab](https://github.com/varylab/conformallab) and use it as the reference implementation.
 
+**† High-precision requirement (Phase 9c / 10):** The Java uniformization classes (`FundamentalPolygon`, `CanonicalFormUtility`) use `RnBig`/`PnBig`/`P2Big` with `MathContext(50)` — 50 significant decimal digits. Reason: products of hyperbolic isometry generators grow exponentially, so `double` fails when verifying the group relation ∏gᵢ = Id. When porting, replicate this **locally** with `boost::multiprecision::cpp_dec_float_50` (or MPFR `mpreal`) — only inside the uniformization module, NOT globally and NOT in the Eigen solver. The core flattening (Newton/energy) stays `double` (see `conformal_mesh.hpp:45`).
+
 ## Test design patterns
 
 ### "Natural theta" — constructing a known equilibrium at x* = 0

doc/architecture/design-decisions.md

@@ -46,6 +46,26 @@ and linear system infrastructure to serve all three without branching.
 
 ---
 
+## Scalar type: `double`, with one localized exception
+
+The kernel is `CGAL::Simple_cartesian<double>` and the whole numerical core
+(functionals, Hessians, Newton, Eigen sparse solvers) is `double`. Conformal
+flattening minimises a smooth energy over transcendental (floating-point) lengths
+and angles, so exact/extended arithmetic buys nothing there — the Java original is
+`double` here too. The CGAL wrapper (`include/CGAL/*.h`) is templated on `FT` for
+API genericity, but delegates to the `double` core.
+
+**The one exception (deferred, Phase 9c/10):** hyperbolic uniformization
+(`FundamentalPolygonUtility`, `CanonicalFormUtility`) composes products of isometry
+generators whose entries grow exponentially; `double` then fails to verify the group
+relation ∏gᵢ = Id. The Java original handles this with `RnBig`/`PnBig`/`P2Big` at
+`MathContext(50)`. When ported, this needs a **localized** high-precision substrate
+(`boost::multiprecision::cpp_dec_float_50` or MPFR `mpreal`) **inside the
+uniformization module only** — never the core or the Eigen solver. See `CLAUDE.md`
+Phase-9 note and `doc/roadmap/java-parity.md` (`*Big` exception).
+
+---
+
 ## Priority-BFS layout
 
 A naive BFS layout places faces in arbitrary order; trilateration errors accumulate

doc/roadmap/java-parity.md

@@ -89,7 +89,16 @@ items were unrecorded and have now been added above:
 Everything else unmentioned is intentionally out of scope: the `plugin/*` jReality
 Swing GUI, the `MTJ*`/`Tao*`/`*PETSc` solver bindings (replaced by Eigen), the
 convergence/`*Series` test harness, and the `*Big` arbitrary-precision geometry
-(`P2Big`/`PnBig`/`RnBig` — deliberately dropped in favour of `Simple_cartesian<double>`).
+(`P2Big`/`PnBig`/`RnBig` — deliberately dropped from the core in favour of `Simple_cartesian<double>`).
+
+> **Exception — `*Big` is NOT permanently out of scope.** The Phase 9c/10 uniformization
+> classes (`FundamentalPolygonUtility`, `CanonicalFormUtility`, rows 55–56 above) build on
+> the `*Big` classes in Java for a reason: products of hyperbolic isometry generators grow
+> exponentially, so `double` fails when verifying the group relation ∏gᵢ = Id (`MathContext(50)`
+> = 50 significant digits in Java). When those classes are ported, a localized high-precision
+> substrate (`boost::multiprecision::cpp_dec_float_50` or MPFR `mpreal`) must be reintroduced —
+> **only inside the uniformization module**, not in the core flattening or the Eigen solver.
+> See the Phase-9 note in `CLAUDE.md`.
 
 ---
 

doc/roadmap/phases.md

@@ -131,8 +131,15 @@ mesh type.
          Mathematical source: Poincaré 1882 + Sechelmann 2016 §5
          Research component: bridging to conformallab++ cut_graph.hpp
                              + holonomy infrastructure.
+         † PRECISION PREREQUISITE: the canonicalisation composes products of
+           hyperbolic isometry generators, whose entries grow exponentially.
+           double fails to verify the group relation ∏gᵢ = Id; Java uses
+           MathContext(50) (RnBig/PnBig/P2Big). Port a LOCALIZED high-precision
+           substrate (boost::multiprecision::cpp_dec_float_50 or MPFR mpreal)
+           inside the uniformization module only — NOT the core or the Eigen
+           solver. See CLAUDE.md Phase-9 note + java-parity.md exception.
          Effort: ~2 weeks for fundamental polygon, +2 weeks for surgery
-                 layer, +1 week integration.
+                 layer, +1 week integration, +~3 days high-precision substrate.
 ```
 
 9d — Cone metrics + sphere utilities  (Java port + research extension)