fix(cci,correl,willr): divide by the value the guard tests, and make %R's range a guarantee (#395)

The three remaining functions carrying #390's shape: a guard that establishes one
expression while the arithmetic below it divides by another. All three are
reachable through the shipped batch API and all three return a wrong answer under
TA_SUCCESS.

CCI guards `tempReal2` and divided by `0.015*tempReal2`. The band is RELATIVE and
the underflow is ABSOLUTE, so they cross: below |average| ~ 1.6e-308 the guard
still answers "not flat" while the scaled copy is exactly 0.0. Dividing by the
deviation and scaling after removes the mismatch structurally. It also fixes the
silent half, which is larger than the loud one -- the pre-scaled form loses
precision long before it reaches Inf, measured relative error 7.7e-08 at price
scale 1e-314 rising to 4.8e-01 at 1e-321, against 2e-16 for the new form at every
one of those magnitudes.

CORREL guards ssX and ssY separately -- correctly, and correl.c explains why -- and
divided by `sqrt(ssX*ssY)`. The product carries the fourth power of the window
spread, so it leaves the double range at both ends while both factors are still
ordinary normals with all 53 bits, and no test of the factors can see it. Where
spXY is zero the result is NaN, which the [-1,1] clamp does not catch (`NaN > 1.0`
is false); where it is not, the +-Inf is rewritten to exactly +-1.0, a perfect
correlation reported from a degenerate window. A root of each factor cannot do
either: sqrt maps any finite positive double into [2.3e-162, 1.4e154], so their
product is representable at both ends. That also deletes the comment block arguing
for the one-root form, whose overflow reasoning the tree's own oracle
(ta_test_reference.c) already contradicted.

WILLR is two defects, and the maintainer's ruling on the second is on #395. It
still carried the exact `diff != 0.0` that #107 replaced in STOCH, so a
machine-flat window divided sub-epsilon residue into full-scale noise, and a
denormal range underflowed `diff` to 0.0 and answered 0 -- the value meaning a
close at the period HIGH -- for a close sitting on the period LOW. Separately, the
pre-scaled divisor cost the endpoint exactness that keeps %R in its documented
range: the shipped library returns -100.00000000000001 on the reference series at
periods 2, 3 and 4. Dividing by the range and scaling after makes the bound a
theorem for well-formed input (fl(h-c) <= fl(h-l) by monotonicity, so the quotient
is in [0,1] under every rounding mode); the clamp extends it to input TA-Lib does
not validate, a close outside its own bar. `diff` leaves the body and the
streaming handle of all four backends.

Not scoped here, and checked rather than assumed: an exhaustive scan of every
division in ta_codegen/input finds no fourth instance of the shape. The Hilbert
family matches it lexically and is cleared -- `atan(Im/Re)*rad2Deg` can only reach
+-Inf, which the `[0.67*prev, 1.5*prev]` then `[6,50]` clamp absorbs on the next
statement -- so #396's seven rows are rewritten from "reachability unproven" to
that clearance.

The sweep from #396 now has no live instance to point at, so its self-test
reconstructs CCI's pre-#395 divisor instead of reading a shipped defect, and pins
the third half the other arms pin: silent when nothing bounds an operand.
Two soundness fixes on the arm: its whole-divisor test accepted any operator, and
its equality arm lacked the exclusivity its siblings carry. CORREL's fixed divisor
is annotated rather than special-cased, which makes reverting correl.c:236 fail
twice -- the key goes stale and the new divisor arrives unannotated.

Measured, not assumed. LEGACY_TOL instrumented to record every function in one
run: CCI 1.42e-14 and WILLR 7.11e-15 are new rows at 5e-14 and 3e-14; CORREL's
3.15e-13 is unchanged, so its #242 row stands. --fuzz-064 gives WILLR its own
5e-14 absolute bound rather than leaving it in the FMA bucket, whose 1e-9 is five
orders looser than it needs -- the reason #338 gives for naming ATR. Absolute
because %R is a bounded dimensionless oscillator: its floor is a ULP of 100 at any
input magnitude.

Six new legs, each sabotage-proven against a build of the pre-fix arithmetic:
CCI subnormal (was +-Inf, now exactly +-1/0.015 -- period 2 makes the mean
deviation equal the numerator, so the expectation is an equality); CORREL at
2^-283 (was NaN, -1, +1; now 0 and +-1/sqrt(15)); and WILLR's endpoint, range,
denormal window, clamp domain (was +-10000) and machine-flat window.

Green: full C suite, generator cargo test and clippy -D warnings, Rust
clippy/doc/doctests/tests, --codegen against the frozen oracle (161 passed 0 failed
in each of the four backends, CCI and WILLR both value-compared), --xlang-hash
(338,957 golden cases, four backends bit-identical), --fuzz-064 (0 failures),
regen-check, and the four source/lock/retcode/candle checks.

Shipped-build A/B on a Zen 4 laptop, min of 12 alternating rounds x 200 reps,
20k bars, four untouched controls inside +-2%: WILLR batch 0.917 (the batch tier
LOSES a division), WILLR streaming 1.054, CCI 1.115, CORREL 1.142. The streaming
+5% is the ALT1 tier paying per bar for a hoist it used to amortise, the same
order as KAMA's clamp in #390. CCI's and CORREL's costs are one extra divide and
one extra sqrt per bar; both were checked for a cheaper correct form and neither
has one that does not reintroduce an overflow band or retighten a guard #253
deliberately widened. CORREL's is well under the ~25% the deleted comment claimed.

Closes #395.

Claude-Session: https://claude.ai/code/session_01GesMuivQUwX4xHr4hEtnS8

Author: mario4tier

CHANGELOG.md

@@ -116,6 +116,8 @@ See [github commits](https://github.com/TA-Lib/ta-lib/commits) for complete list
 - (#253) Fix many TA_IS_ZERO vs TA_IS_ZERO_SCALED choices. Numerically better for edge cases, like very small inputs (<10e-8) or mostly flat input prices.
 - (#390) STOCH and STOCHF returned `inf` or `NaN` while reporting success, for prices near the bottom of the double range. A close sitting on the window high now comes out as exactly 100.
 - (#390) KAMA could return values outside the range of the prices it was smoothing, and ER values above 1. Both come from the same efficiency ratio exceeding its own maximum when floating-point drift left the running sum of price movement below the net move it bounds. The ratio is now clamped, making ER a hard 0..1.
+- (#395) CCI returned `+/-Inf` while reporting success, and CORREL returned `NaN` or a perfect +/-1 correlation from a window that had none, for prices near the bottom of the double range. Both now divide by the value their guard actually tests, so they stay accurate to the last bits at every price scale.
+- (#395) WILLR could return values outside its documented [-100, 0] range, and answered 0 - the value meaning a close at the period high - for a close sitting on the period low whenever the window's high-low range was very small. A close on the period low now comes out as exactly -100, the range is guaranteed even for a close outside its own bar, and a window flat to within rounding of its own prices answers 0, as STOCH and STOCHF already did.
 
 ## [0.7.1] 2026-07-03
 ### Added

src/ta_func/ta_CCI.c

@@ -67,6 +67,9 @@
  *  082326 MF,CC  Fix #253. Scale that flatness test to the window's own price
  *                level: the fixed band zeroed the whole output for any
  *                instrument quoted small enough to fall under it.
+ *  090626 MF,CC  Fix #395. Divide by the mean deviation, scale after: the
+ *                pre-scaled `0.015*tempReal2` underflowed to 0.0 on a
+ *                denormal price that the guard still called "not flat".
  */
 
 TA_LIB_API int TA_CCI_Lookback( int optInTimePeriod )
@@ -203,7 +206,13 @@ TA_LIB_API TA_RetCode TA_CCI( int    startIdx,
       tempReal2 /= optInTimePeriod;
       /* And finally, the CCI... */
       tempReal = lastValue - theAverage;
-      /* Both tests are relative to the window's own price level (issue #253).
+      /* Divide by the mean deviation itself and scale after: the guard has to
+       * test the very expression the division uses, or a scaling step can
+       * carry a guarded-non-zero into a zero divisor. The band is relative and
+       * the underflow of the 0.015 product is absolute, so no band on the
+       * deviation can cover the product.
+       *
+       * Both tests are relative to the window's own price level (issue #253).
        * They ask "is this window flat?", and flatness is a property of the
        * prices relative to each other -- but a deviation carries the quote
        * unit, so the fixed TA_IS_ZERO band these used to be answered "flat" for
@@ -215,7 +224,7 @@ TA_LIB_API TA_RetCode TA_CCI( int    startIdx,
       tempReal3 = fabs(theAverage);
       if( !TA_IS_ZERO_SCALED(tempReal, tempReal3) && !TA_IS_ZERO_SCALED(tempReal2, tempReal3) )
       {
-         outReal[outIdx++] = tempReal / (0.015 * tempReal2);
+         outReal[outIdx++] = tempReal / tempReal2 / 0.015;
       } else 
       {
          outReal[outIdx++] = 0.0;
@@ -335,7 +344,7 @@ TA_RetCode TA_S_CCI( int    startIdx,
       tempReal3 = fabs(theAverage);
       if( !TA_IS_ZERO_SCALED(tempReal, tempReal3) && !TA_IS_ZERO_SCALED(tempReal2, tempReal3) )
       {
-         outReal[outIdx++] = tempReal / (0.015 * tempReal2);
+         outReal[outIdx++] = tempReal / tempReal2 / 0.015;
       } else 
       {
          outReal[outIdx++] = 0.0;
@@ -403,7 +412,13 @@ static void TA_CCI_StepImpl( struct TA_CCI_Stream *sp, double inHigh, double inL
    tempReal2 /= sp->optInTimePeriod;
    /* And finally, the CCI... */
    tempReal = lastValue - theAverage;
-   /* Both tests are relative to the window's own price level (issue #253).
+   /* Divide by the mean deviation itself and scale after: the guard has to
+    * test the very expression the division uses, or a scaling step can
+    * carry a guarded-non-zero into a zero divisor. The band is relative and
+    * the underflow of the 0.015 product is absolute, so no band on the
+    * deviation can cover the product.
+    *
+    * Both tests are relative to the window's own price level (issue #253).
     * They ask "is this window flat?", and flatness is a property of the
     * prices relative to each other -- but a deviation carries the quote
     * unit, so the fixed TA_IS_ZERO band these used to be answered "flat" for
@@ -415,7 +430,7 @@ static void TA_CCI_StepImpl( struct TA_CCI_Stream *sp, double inHigh, double inL
    tempReal3 = fabs(theAverage);
    if( !TA_IS_ZERO_SCALED(tempReal, tempReal3) && !TA_IS_ZERO_SCALED(tempReal2, tempReal3) )
    {
-      *outReal= tempReal / (0.015 * tempReal2);
+      *outReal= tempReal / tempReal2 / 0.015;
    } else 
    {
       *outReal= 0.0;
@@ -547,7 +562,13 @@ static TA_RetCode TA_CCI_OpenImpl( struct TA_CCI_Stream **stream, const double i
          tempReal2 /= optInTimePeriod;
          /* And finally, the CCI... */
          tempReal = lastValue - theAverage;
-         /* Both tests are relative to the window's own price level (issue #253).
+         /* Divide by the mean deviation itself and scale after: the guard has to
+          * test the very expression the division uses, or a scaling step can
+          * carry a guarded-non-zero into a zero divisor. The band is relative and
+          * the underflow of the 0.015 product is absolute, so no band on the
+          * deviation can cover the product.
+          *
+          * Both tests are relative to the window's own price level (issue #253).
           * They ask "is this window flat?", and flatness is a property of the
           * prices relative to each other -- but a deviation carries the quote
           * unit, so the fixed TA_IS_ZERO band these used to be answered "flat" for
@@ -559,7 +580,7 @@ static TA_RetCode TA_CCI_OpenImpl( struct TA_CCI_Stream **stream, const double i
          tempReal3 = fabs(theAverage);
          if( !TA_IS_ZERO_SCALED(tempReal, tempReal3) && !TA_IS_ZERO_SCALED(tempReal2, tempReal3) )
          {
-            outReal[outIdx++ * outStride] = tempReal / (0.015 * tempReal2);
+            outReal[outIdx++ * outStride] = tempReal / tempReal2 / 0.015;
          } else 
          {
             outReal[outIdx++ * outStride] = 0.0;
@@ -683,7 +704,13 @@ TA_LIB_API TA_RetCode TA_CCI_Peek( const TA_CCI_Stream *stream, double inHigh, d
    tempReal2 /= sp->optInTimePeriod;
    /* And finally, the CCI... */
    tempReal = lastValue - theAverage;
-   /* Both tests are relative to the window's own price level (issue #253).
+   /* Divide by the mean deviation itself and scale after: the guard has to
+    * test the very expression the division uses, or a scaling step can
+    * carry a guarded-non-zero into a zero divisor. The band is relative and
+    * the underflow of the 0.015 product is absolute, so no band on the
+    * deviation can cover the product.
+    *
+    * Both tests are relative to the window's own price level (issue #253).
     * They ask "is this window flat?", and flatness is a property of the
     * prices relative to each other -- but a deviation carries the quote
     * unit, so the fixed TA_IS_ZERO band these used to be answered "flat" for
@@ -695,7 +722,7 @@ TA_LIB_API TA_RetCode TA_CCI_Peek( const TA_CCI_Stream *stream, double inHigh, d
    tempReal3 = fabs(theAverage);
    if( !TA_IS_ZERO_SCALED(tempReal, tempReal3) && !TA_IS_ZERO_SCALED(tempReal2, tempReal3) )
    {
-      *outReal= tempReal / (0.015 * tempReal2);
+      *outReal= tempReal / tempReal2 / 0.015;
    } else 
    {
       *outReal= 0.0;

src/ta_func/ta_CORREL.c

@@ -47,18 +47,24 @@
  *  Initial  Name/description
  *  -------------------------------------------------------------------
  *  MF       Mario Fortier
+ *  CC       Claude Code (AI assistant)
  *
  *
  * Change history:
  *
- *  MMDDYY BY   Description
+ *  MMDDYY BY    Description
  *  -------------------------------------------------------------------
- *  120802 MF   Template creation.
- *  101003 MF   Initial Coding
- *  062804 MF   Resolve div by zero bug on limit case.
- *  082326 MF   Fix #242. Cancellation-free sums (shifted data + reseed, as
- *              TA_VAR does since #118), per-factor degeneracy test and a
- *              range clamp.
+ *  120802 MF    Template creation.
+ *  101003 MF    Initial Coding
+ *  062804 MF    Resolve div by zero bug on limit case.
+ *  082326 MF    Fix #242. Cancellation-free sums (shifted data + reseed, as
+ *               TA_VAR does since #118), per-factor degeneracy test and a
+ *               range clamp.
+ *  090626 MF,CC Fix #395. A root of each guarded factor, not a root of their
+ *               product: sqrt(ssX*ssY) left the double range at both ends
+ *               while ssX and ssY were still ordinary normals, returning NaN
+ *               under TA_SUCCESS and a perfect correlation from a degenerate
+ *               window.
  */
 
 TA_LIB_API int TA_CORREL_Lookback( int optInTimePeriod )
@@ -295,25 +301,13 @@ TA_LIB_API TA_RetCode TA_CORREL( int    startIdx,
        * is also the cheaper test: the two fabs() cost ~7% of this function's
        * runtime, and buy a wrong answer.
        *
-       * sqrt(ssX*ssY) rather than sqrt(ssX)*sqrt(ssY): the guard has already
-       * established both are positive, so the product needs no protection from
-       * a negative operand, and the second square root is worth ~25% of the
-       * runtime.
-       *
-       * The product CAN overflow to +Inf, and the one-root form is chosen with
-       * that known. TA_REAL_MAX bounds optional PARAMETERS; a batch call's input
-       * arrays are not range-checked, so ssX and ssY are bounded only by the
-       * double range and their product exceeds it once |x| passes ~1e154. The
-       * two-root form would not overflow there -- but the form this replaces
-       * built exactly the same product (it tested ssX*ssY against TA_EPSILON), so
-       * the exposure is unchanged, and an Inf here yields 0.0 rather than a wrong
-       * correlation. Trading a quarter of the runtime for a case that already
-       * behaved this way, on inputs 117 orders past any price, is not a trade
-       * worth making. Revisit only if input range-checking is ever added.
+       * A root of each guarded factor, never a root of their product: that
+       * product leaves the double range at BOTH ends while ssX and ssY are
+       * still ordinary normals, which no test of the factors can see (#395).
        */
       if( ssX > 0.00000000000001 * sumX2 && ssY > 0.00000000000001 * sumY2 )
       {
-         tempReal = spXY / sqrt(ssX * ssY);
+         tempReal = spXY / (sqrt(ssX) * sqrt(ssY));
          /* A correlation coefficient cannot leave [-1,1]; rounding in the
           * three sums can still put it a few ulp outside.
           */
@@ -490,7 +484,7 @@ TA_RetCode TA_S_CORREL( int    startIdx,
       trailingIdx += 1;
       if( ssX > 0.00000000000001 * sumX2 && ssY > 0.00000000000001 * sumY2 )
       {
-         tempReal = spXY / sqrt(ssX * ssY);
+         tempReal = spXY / (sqrt(ssX) * sqrt(ssY));
          if( tempReal > 1.0 )
          {
             tempReal = 1.0;
@@ -701,25 +695,13 @@ static void TA_CORREL_StepImpl( struct TA_CORREL_Stream *sp, double inReal0, dou
     * is also the cheaper test: the two fabs() cost ~7% of this function's
     * runtime, and buy a wrong answer.
     *
-    * sqrt(ssX*ssY) rather than sqrt(ssX)*sqrt(ssY): the guard has already
-    * established both are positive, so the product needs no protection from
-    * a negative operand, and the second square root is worth ~25% of the
-    * runtime.
-    *
-    * The product CAN overflow to +Inf, and the one-root form is chosen with
-    * that known. TA_REAL_MAX bounds optional PARAMETERS; a batch call's input
-    * arrays are not range-checked, so ssX and ssY are bounded only by the
-    * double range and their product exceeds it once |x| passes ~1e154. The
-    * two-root form would not overflow there -- but the form this replaces
-    * built exactly the same product (it tested ssX*ssY against TA_EPSILON), so
-    * the exposure is unchanged, and an Inf here yields 0.0 rather than a wrong
-    * correlation. Trading a quarter of the runtime for a case that already
-    * behaved this way, on inputs 117 orders past any price, is not a trade
-    * worth making. Revisit only if input range-checking is ever added.
+    * A root of each guarded factor, never a root of their product: that
+    * product leaves the double range at BOTH ends while ssX and ssY are
+    * still ordinary normals, which no test of the factors can see (#395).
     */
    if( ssX > 0.00000000000001 * sumX2 && ssY > 0.00000000000001 * sumY2 )
    {
-      tempReal = spXY / sqrt(ssX * ssY);
+      tempReal = spXY / (sqrt(ssX) * sqrt(ssY));
       /* A correlation coefficient cannot leave [-1,1]; rounding in the
        * three sums can still put it a few ulp outside.
        */
@@ -973,25 +955,13 @@ static TA_RetCode TA_CORREL_OpenImpl( struct TA_CORREL_Stream **stream, const do
           * is also the cheaper test: the two fabs() cost ~7% of this function's
           * runtime, and buy a wrong answer.
           *
-          * sqrt(ssX*ssY) rather than sqrt(ssX)*sqrt(ssY): the guard has already
-          * established both are positive, so the product needs no protection from
-          * a negative operand, and the second square root is worth ~25% of the
-          * runtime.
-          *
-          * The product CAN overflow to +Inf, and the one-root form is chosen with
-          * that known. TA_REAL_MAX bounds optional PARAMETERS; a batch call's input
-          * arrays are not range-checked, so ssX and ssY are bounded only by the
-          * double range and their product exceeds it once |x| passes ~1e154. The
-          * two-root form would not overflow there -- but the form this replaces
-          * built exactly the same product (it tested ssX*ssY against TA_EPSILON), so
-          * the exposure is unchanged, and an Inf here yields 0.0 rather than a wrong
-          * correlation. Trading a quarter of the runtime for a case that already
-          * behaved this way, on inputs 117 orders past any price, is not a trade
-          * worth making. Revisit only if input range-checking is ever added.
+          * A root of each guarded factor, never a root of their product: that
+          * product leaves the double range at BOTH ends while ssX and ssY are
+          * still ordinary normals, which no test of the factors can see (#395).
           */
          if( ssX > 0.00000000000001 * sumX2 && ssY > 0.00000000000001 * sumY2 )
          {
-            tempReal = spXY / sqrt(ssX * ssY);
+            tempReal = spXY / (sqrt(ssX) * sqrt(ssY));
             /* A correlation coefficient cannot leave [-1,1]; rounding in the
              * three sums can still put it a few ulp outside.
              */
@@ -1276,25 +1246,13 @@ TA_LIB_API TA_RetCode TA_CORREL_Peek( const TA_CORREL_Stream *stream, double inR
     * is also the cheaper test: the two fabs() cost ~7% of this function's
     * runtime, and buy a wrong answer.
     *
-    * sqrt(ssX*ssY) rather than sqrt(ssX)*sqrt(ssY): the guard has already
-    * established both are positive, so the product needs no protection from
-    * a negative operand, and the second square root is worth ~25% of the
-    * runtime.
-    *
-    * The product CAN overflow to +Inf, and the one-root form is chosen with
-    * that known. TA_REAL_MAX bounds optional PARAMETERS; a batch call's input
-    * arrays are not range-checked, so ssX and ssY are bounded only by the
-    * double range and their product exceeds it once |x| passes ~1e154. The
-    * two-root form would not overflow there -- but the form this replaces
-    * built exactly the same product (it tested ssX*ssY against TA_EPSILON), so
-    * the exposure is unchanged, and an Inf here yields 0.0 rather than a wrong
-    * correlation. Trading a quarter of the runtime for a case that already
-    * behaved this way, on inputs 117 orders past any price, is not a trade
-    * worth making. Revisit only if input range-checking is ever added.
+    * A root of each guarded factor, never a root of their product: that
+    * product leaves the double range at BOTH ends while ssX and ssY are
+    * still ordinary normals, which no test of the factors can see (#395).
     */
    if( ssX > 0.00000000000001 * sumX2 && ssY > 0.00000000000001 * sumY2 )
    {
-      tempReal = spXY / sqrt(ssX * ssY);
+      tempReal = spXY / (sqrt(ssX) * sqrt(ssY));
       /* A correlation coefficient cannot leave [-1,1]; rounding in the
        * three sums can still put it a few ulp outside.
        */