refactor(elreal): consolidate exact-dyadic oracle helpers into one shared header (#1035) (#1056)

The exact-dyadic oracle helpers (exact_real / exact_block / exact_blocks /
exact_value / exact_series_sum / approx / check_zero_overlap), built on
dyadic_exact.hpp (the #1022 oracle work), had been copy-pasted into FIVE places
that had already drifted apart: addition.cpp and add_renormalization.cpp
(inline), exact_value_oracle.cpp (as exact_zbcl), summation/summation_oracle.hpp
(z.take(32)), and arithmetic/arithmetic_oracle.hpp (z.take(64), added after the
issue with a "consolidation tracked by #1035" note). Keeping the subtle
digits<=53 vs wide-cfloat bit path in sync by hand was error-prone, and the
32-vs-64 window split was exactly the drift #1035 warned about.

Promote them to a single source of truth:

  include/sw/universal/verification/elreal_oracle.hpp
  namespace sw::universal::elreal_oracle

All helpers are templates (implicitly inline), so multi-TU inclusion is ODR-safe.
The window is unified to ZBCL_EXACT_WINDOW = 32 (the #1022 value). This is
behaviour-preserving: a ZBCL<double> near 1.0 saturates at ~19-20 non-overlapping
components against the 2^-1022 floor, so take(32) == take(64) for every test
value; the arithmetic suite's former 64-window captured nothing extra.

- New: verification/elreal_oracle.hpp (superset of all five copies).
- Deleted: summation/summation_oracle.hpp, arithmetic/arithmetic_oracle.hpp.
- 17 elreal test TUs now include the shared header; the `namespace est = ...`
  aliases retarget to elreal_oracle (call sites unchanged). addition.cpp,
  add_renormalization.cpp, and exact_value_oracle.cpp drop their inline copies
  for a using-directive; exact_value_oracle.cpp's exact_zbcl call sites become
  exact_value. exact_value_oracle.cpp keeps its EFT-specific oracle code
  (dval / block_ulp / EFT checks) local.

Pure refactor, no behaviour change. Verified: el_arith_*, el_sum_*, el_math_*
(20 targets) build and pass with BOTH gcc and clang. ASCII clean.

Resolves #1035

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: Ravenwater

elastic/elreal/arithmetic/add_renormalization.cpp

@@ -20,13 +20,15 @@
 #include <vector>
 
 #include <universal/number/elreal/elreal.hpp>
-#include <universal/verification/dyadic_exact.hpp>
+#include <universal/verification/elreal_oracle.hpp>
 #include <universal/verification/test_suite.hpp>
 
 namespace {
 
 using sw::universal::block;
 using sw::universal::ZBCL;
+// exact_block / exact_value: the shared exact-dyadic oracle (#1035).
+using namespace sw::universal::elreal_oracle;
 
 // 0-overlap check + descending-exponent sanity over the first n blocks.
 template <typename FpType>
@@ -44,25 +46,6 @@ int check_canonical(const ZBCL<FpType>& z, std::size_t n, const std::string& tag
     return fails;
 }
 
-// Compare the exact value of an add() result to a dyadic reference.
-template <typename FpType>
-sw::universal::dyadic exact_block(const block<FpType>& b) {
-    using namespace sw::universal;
-    if (b.is_zero_block()) return dyadic();
-    // FpType here is double in this test; <=53 bits -> exact via from_double.
-    dyadic d = dyadic::from_double(static_cast<double>(b.v));
-    d.scale += b.exp;
-    return d;
-}
-
-template <typename FpType>
-sw::universal::dyadic exact_value(const ZBCL<FpType>& z) {
-    using namespace sw::universal;
-    dyadic acc;
-    for (const auto& blk : z.take(32)) acc = acc + exact_block(blk);
-    return acc;
-}
-
 // pow2 singleton ZBCL.
 ZBCL<double> p2(int e) {
     using namespace sw::universal;

elastic/elreal/arithmetic/addition.cpp

@@ -18,62 +18,13 @@
 #include <iostream>
 
 #include <universal/number/elreal/elreal.hpp>
-#include <universal/verification/dyadic_exact.hpp>
+#include <universal/verification/elreal_oracle.hpp>
 #include <universal/verification/test_suite.hpp>
 
 namespace {
 
-// Exact value of a binary float v as a dyadic, with no precision loss at any
-// significand width (shared with the #1022 oracle; see its exact_real for the
-// full rationale). p <= 53: double is exact. p > 53 with the Universal FP API
-// (cfloat quad and up): read the encoding directly -- sign, scale, and the fbits
-// stored fraction bits -- giving (-1)^sign * (2^fbits + F) * 2^(scale - fbits).
-// This avoids cfloat's wide-precision frexp/floor (filed separately).
-template <typename T>
-sw::universal::dyadic exact_real(T v) {
-    using namespace sw::universal;
-    if (v == T(0)) return dyadic();
-    if constexpr (std::numeric_limits<T>::digits <= 53) {
-        return dyadic::from_double(static_cast<double>(v));
-    } else if constexpr (has_universal_fp_api_v<T>) {
-        constexpr int fbits = std::numeric_limits<T>::digits - 1;
-        assert(v.isnormal() && "exact_real bit path expects a normal value");
-        dyadic::bigint F(0);
-        for (int i = 0; i < fbits; ++i) {
-            if (v.test(static_cast<unsigned>(i))) {
-                dyadic::bigint bit(1); bit <<= i; F = F + bit;
-            }
-        }
-        dyadic::bigint M(1); M <<= fbits; M = M + F;     // hidden bit + fraction
-        return dyadic(v.sign() ? -M : M, v.scale() - fbits);
-    } else {
-        static_assert(has_universal_fp_api_v<T>,
-            "exact_real: wide native hosts not supported yet (add std::frexp path).");
-        return dyadic();
-    }
-}
-
-// Exact value of a block as a dyadic rational (value(b) = v * 2^exp), shared
-// with the #1022 oracle.
-template <typename FpType>
-sw::universal::dyadic exact_block(const sw::universal::block<FpType>& b) {
-    using namespace sw::universal;
-    if (b.is_zero_block()) return dyadic();
-    dyadic d = exact_real(b.v);
-    d.scale += b.exp;
-    return d;
-}
-
-template <typename FpType>
-sw::universal::dyadic exact_value(const sw::universal::ZBCL<FpType>& z) {
-    using namespace sw::universal;
-    dyadic acc;
-    // 32-block window, matching the #1022 oracle's ZBCL_EXACT_WINDOW so both
-    // files agree on the exact value of the same stream; finite test sums settle
-    // well within it.
-    for (const auto& blk : z.take(32)) acc = acc + exact_block(blk);
-    return acc;
-}
+// exact_real / exact_block / exact_value: the shared exact-dyadic oracle (#1035).
+using namespace sw::universal::elreal_oracle;
 
 // Value preservation, validated against an INDEPENDENT exact dyadic oracle
 // (not long double -- see #1022). double and float are round-to-nearest, so

elastic/elreal/arithmetic/arithmetic_oracle.hpp

@@ -22,11 +22,11 @@
 #include <universal/verification/dyadic_exact.hpp>
 #include <universal/verification/test_suite.hpp>
 
-#include "arithmetic_oracle.hpp"
+#include <universal/verification/elreal_oracle.hpp>
 
 namespace {
 
-namespace est = sw::universal::elreal_arith_test;
+namespace est = sw::universal::elreal_oracle;
 
 template <typename FpType>
 int verify_all(const std::string& host) {

elastic/elreal/arithmetic/division.cpp

@@ -67,85 +67,21 @@
 #include <universal/number/cfloat/cfloat.hpp>
 #include <universal/number/bfloat16/bfloat16.hpp>
 #include <universal/number/elreal/elreal.hpp>
-#include <universal/verification/dyadic_exact.hpp>
+#include <universal/verification/elreal_oracle.hpp>
 #include <universal/verification/test_suite.hpp>
 
 namespace {
 
 using namespace sw::universal;
+// exact_real / exact_block / exact_blocks / exact_value + ZBCL_EXACT_WINDOW: the
+// shared exact-dyadic oracle this file pioneered (#1022), now consolidated (#1035).
+using namespace sw::universal::elreal_oracle;
 
-// Exact value of a binary floating-point value v as a dyadic rational, with NO
-// precision loss at any significand width.
-//
-// Two regimes, chosen at compile time:
-//
-//   * p = digits <= 53: double represents v exactly, so from_double is exact and
-//     cheap. Covers float(24), double(53), half(11), bfloat16(8), cfloat<24,5>(19),
-//     cfloat<32,8>(24) -- every <= 53-bit host.
-//
-//   * p > 53 with the Universal FP API (cfloat quad and up): read the encoding
-//     DIRECTLY -- sign, scale, and the fbits stored fraction bits -- and assemble
-//         value = (-1)^sign * (2^fbits + F) * 2^(scale - fbits),  fbits = p - 1.
-//     Reading the encoding directly keeps this oracle self-contained: it depends
-//     on no cfloat math function, only on the bit layout. (Historically it also
-//     side-stepped two wide-precision cfloat bugs that an earlier frexp/floor
-//     extraction tripped over -- cfloat floor mis-handling large integers, #1026,
-//     and cfloat frexp's non-std [1,2) fraction, #1027; both now fixed. That
-//     earlier extraction had passed #1023's quad sweeps only because they fed
-//     double-derived <= 53-bit q128 values, silently mis-extracting genuine
-//     113-bit ones.) The bit-based path is verified consistent across widths and
-//     against an independent 2x-wider cfloat product.
-template <typename T>
-dyadic exact_real(T v) {
-    if (v == T(0)) return dyadic();
-    if constexpr (std::numeric_limits<T>::digits <= 53) {
-        return dyadic::from_double(static_cast<double>(v));
-    } else if constexpr (has_universal_fp_api_v<T>) {
-        constexpr int fbits = std::numeric_limits<T>::digits - 1;
-        assert(v.isnormal() && "exact_real bit path expects a normal value");
-        dyadic::bigint F(0);
-        for (int i = 0; i < fbits; ++i) {
-            if (v.test(static_cast<unsigned>(i))) {
-                dyadic::bigint bit(1); bit <<= i; F = F + bit;
-            }
-        }
-        dyadic::bigint M(1); M <<= fbits; M = M + F;     // hidden bit + fraction
-        return dyadic(v.sign() ? -M : M, v.scale() - fbits);
-    } else {
-        static_assert(has_universal_fp_api_v<T>,
-            "exact_real: wide (>53-bit) native hosts are not supported yet; add a "
-            "std::frexp-based extraction (std frexp is correct for native types) "
-            "when such a host is introduced.");
-        return dyadic();
-    }
-}
-
-// exact value of a single block as a dyadic rational (value(b) = v * 2^exp).
-// Shares no code with the block/EFT/threeAdd/add algorithms under test.
-template <typename FpType>
-dyadic exact_block(const block<FpType>& b) {
-    if (b.is_zero_block()) return dyadic();
-    dyadic d = exact_real(b.v);
-    d.scale += b.exp;          // multiply by 2^exp exactly (value = v * 2^exp)
-    return d;
-}
-
-template <typename FpType>
-dyadic exact_blocks(const std::vector<block<FpType>>& bs) {
-    dyadic acc;                // 0
-    for (const auto& b : bs) acc = acc + exact_block(b);
-    return acc;
-}
-
-// Number of ZBCL blocks forced when computing an exact value. Finite sums of the
-// test inputs settle well within this; kept identical to addition.cpp's window
-// so the two files agree on the "exact value" of the same stream.
-constexpr std::size_t ZBCL_EXACT_WINDOW = 32;
-
-template <typename FpType>
-dyadic exact_zbcl(const ZBCL<FpType>& z) {
-    return exact_blocks(z.take(ZBCL_EXACT_WINDOW));
-}
+// The exact-dyadic helpers (exact_real / exact_block / exact_blocks / exact_value)
+// and ZBCL_EXACT_WINDOW that this oracle pioneered (#1022) now live in the shared
+// header <universal/verification/elreal_oracle.hpp> (#1035) and are brought into
+// scope by the using-directive above. The EFT/threeAdd/add reference checks below
+// build on them but share no code with the algorithms under test.
 
 // value of a block in double, and its ulp -- used only for the bfloat16
 // truncation bound (double has ~45 bits of headroom over bfloat16's 8).
@@ -225,7 +161,7 @@ int check_add_exact(double a, double b, const std::string& tag) {
     auto za = from_native<FpType>(a);
     auto zb = from_native<FpType>(b);
     auto z  = add(za, zb);
-    if ((exact_zbcl(za) + exact_zbcl(zb)) != exact_zbcl(z)) {
+    if ((exact_value(za) + exact_value(zb)) != exact_value(z)) {
         std::cout << tag << " add value WRONG: a=" << a << " b=" << b << "\n";
         return 1;
     }

elastic/elreal/arithmetic/exact_value_oracle.cpp

@@ -18,11 +18,11 @@
 #include <universal/verification/dyadic_exact.hpp>
 #include <universal/verification/test_suite.hpp>
 
-#include "arithmetic_oracle.hpp"
+#include <universal/verification/elreal_oracle.hpp>
 
 namespace {
 
-namespace est = sw::universal::elreal_arith_test;
+namespace est = sw::universal::elreal_oracle;
 
 // exact_value(mul(x,y)) == exact(x) * exact(y), plus 0-overlap.
 template <typename FpType>

elastic/elreal/arithmetic/multiplication.cpp

@@ -18,11 +18,11 @@
 #include <universal/verification/dyadic_exact.hpp>
 #include <universal/verification/test_suite.hpp>
 
-#include "arithmetic_oracle.hpp"
+#include <universal/verification/elreal_oracle.hpp>
 
 namespace {
 
-namespace est = sw::universal::elreal_arith_test;
+namespace est = sw::universal::elreal_oracle;
 
 template <typename FpType>
 int verify_one(double v, const std::string& tag) {

elastic/elreal/arithmetic/negation.cpp

@@ -36,11 +36,11 @@
 #include <universal/verification/dyadic_exact.hpp>
 #include <universal/verification/test_suite.hpp>
 
-#include "../arithmetic/arithmetic_oracle.hpp"
+#include <universal/verification/elreal_oracle.hpp>
 
 namespace {
 
-namespace est = sw::universal::elreal_arith_test;
+namespace est = sw::universal::elreal_oracle;
 
 template <typename FpType>
 int check_value(const sw::universal::ZBCL<FpType>& z, double ref, double tol, const std::string& tag) {

elastic/elreal/math/constants.cpp

@@ -26,11 +26,11 @@
 #include <universal/verification/dyadic_exact.hpp>
 #include <universal/verification/test_suite.hpp>
 
-#include "../arithmetic/arithmetic_oracle.hpp"
+#include <universal/verification/elreal_oracle.hpp>
 
 namespace {
 
-namespace est = sw::universal::elreal_arith_test;
+namespace est = sw::universal::elreal_oracle;
 
 template <typename FpType>
 int near(const sw::universal::ZBCL<FpType>& z, double ref, double tol, const std::string& tag) {

elastic/elreal/math/exponent.cpp

@@ -20,11 +20,11 @@
 #include <universal/verification/dyadic_exact.hpp>
 #include <universal/verification/test_suite.hpp>
 
-#include "../arithmetic/arithmetic_oracle.hpp"
+#include <universal/verification/elreal_oracle.hpp>
 
 namespace {
 
-namespace est = sw::universal::elreal_arith_test;
+namespace est = sw::universal::elreal_oracle;
 
 template <typename FpType>
 int near(const sw::universal::ZBCL<FpType>& z, double ref, double tol, const std::string& tag) {