From 94323c2e8c89f9e82cbeeeff65ac79a755a39203 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marek=20Lema=C5=84czyk?= <marek@lemanczyk.eu>
Date: Mon, 20 Oct 2025 11:48:07 +0200
Subject: [PATCH] Document unreachable MulMod guards

---
 PerfectNumbers.Core/UInt128Extensions.cs | 25 ++++++++++------------
 PerfectNumbers.Core/ULongExtensions.cs   | 27 +++++++++++++-----------
 2 files changed, 26 insertions(+), 26 deletions(-)

diff --git a/PerfectNumbers.Core/UInt128Extensions.cs b/PerfectNumbers.Core/UInt128Extensions.cs
index bc4a36d..bfc18d7 100644
--- a/PerfectNumbers.Core/UInt128Extensions.cs
+++ b/PerfectNumbers.Core/UInt128Extensions.cs
@@ -671,10 +671,11 @@ public static class UInt128Extensions
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     public static UInt128 AddMod(this UInt128 value, UInt128 addend, UInt128 modulus)
     {
-        if (modulus <= UInt128.One)
-        {
-            return UInt128.Zero;
-        }
+        // The by-divisor CPU path never supplies moduli below 2, so this guard stays disabled.
+        // if (modulus <= UInt128.One)
+        // {
+        //     return UInt128.Zero;
+        // }
 
         value %= modulus;
         addend %= modulus;
@@ -684,21 +685,17 @@ public static class UInt128Extensions
         }
 
         UInt128 threshold = modulus - addend;
-        if (value >= threshold)
-        {
-            return value - threshold;
-        }
-
-        return value + addend;
+        return value >= threshold ? value - threshold : value + addend;
     }
 
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     public static UInt128 SubtractOneMod(this UInt128 value, UInt128 modulus)
     {
-        if (modulus <= UInt128.One)
-        {
-            return UInt128.Zero;
-        }
+        // The divisor scan never observes moduli below 2, so leave this guard documented but inactive.
+        // if (modulus <= UInt128.One)
+        // {
+        //     return UInt128.Zero;
+        // }
 
         if (value == UInt128.Zero)
         {
diff --git a/PerfectNumbers.Core/ULongExtensions.cs b/PerfectNumbers.Core/ULongExtensions.cs
index 41507f3..dd8e040 100644
--- a/PerfectNumbers.Core/ULongExtensions.cs
+++ b/PerfectNumbers.Core/ULongExtensions.cs
@@ -458,10 +458,11 @@ public static partial class ULongExtensions
 	[MethodImpl(MethodImplOptions.AggressiveInlining)]
 	public static ulong AddMod64(this ulong value, ulong addend, ulong modulus)
 	{
-		if (modulus <= 1UL)
-		{
-			return 0UL;
-		}
+		// The CPU factoring path never presents moduli below 2, so leave this guard documented but disabled.
+		// if (modulus <= 1UL)
+		// {
+		// 	return 0UL;
+		// }
 
 		UInt128 sum = (UInt128)value + addend;
 		UInt128 mod = modulus;
@@ -480,10 +481,11 @@ public static partial class ULongExtensions
 	[MethodImpl(MethodImplOptions.AggressiveInlining)]
 	private static ulong FoldMontgomery(ulong value, ulong modulus)
 	{
-		if (modulus <= 1UL)
-		{
-			return 0UL;
-		}
+		// Moduli in the divisor scan always exceed 1, so retain the documentation and skip the runtime guard.
+		// if (modulus <= 1UL)
+		// {
+		// 	return 0UL;
+		// }
 
 		if (value < modulus)
 		{
@@ -508,10 +510,11 @@ public static partial class ULongExtensions
 	[MethodImpl(MethodImplOptions.AggressiveInlining)]
 	public static ulong ModPow64(this ulong value, ulong exponent, ulong modulus)
 	{
-		if (modulus <= 1UL)
-		{
-			return 0UL;
-		}
+		// Moduli below 2 do not occur in the even-perfect divisor scans, so keep the guard commented for clarity.
+		// if (modulus <= 1UL)
+		// {
+		// 	return 0UL;
+		// }
 
 		ulong result = 1UL;
 		value = FoldMontgomery(value, modulus);