refactor(resolver): make Cooldown always present, never None

Replace None-as-disabled with a zero min_age Cooldown so callers
never need None checks. Adds Cooldown.disabled() factory and
simplifies resolve_package_cooldown to always return a value.

Co-Authored-By: Claude <claude@anthropic.com>
Signed-off-by: Lalatendu Mohanty <lmohanty@redhat.com>

Author: LalatenduMohanty

src/fromager/__main__.py

@@ -283,11 +283,7 @@ def main(
         network_isolation=network_isolation,
         max_jobs=jobs,
         settings_dir=settings_dir,
-        cooldown=(
-            candidate.Cooldown(min_age=datetime.timedelta(days=min_release_age))
-            if min_release_age > 0
-            else None
-        ),
+        cooldown=candidate.Cooldown(min_age=datetime.timedelta(days=min_release_age)),
     )
     wkctx.setup()
     ctx.obj = wkctx

src/fromager/candidate.py

@@ -22,6 +22,10 @@ class Cooldown:
     Frozen so that cooldown policy cannot be accidentally weakened after
     construction — all parameters are set once and shared read-only.
 
+    A cooldown with ``min_age`` of zero (or negative) is effectively disabled —
+    every package age exceeds the threshold.  Use :meth:`disabled` as a
+    convenient factory instead of ``None``.
+
     bootstrap_time is fixed at construction so all resolutions in a single run
     share the same cutoff.
 
@@ -35,6 +39,11 @@ class Cooldown:
     )
     exempt_versions: frozenset[Version] = dataclasses.field(default_factory=frozenset)
 
+    @classmethod
+    def disabled(cls) -> "Cooldown":
+        """Return a cooldown that never filters any candidate."""
+        return cls(min_age=datetime.timedelta(0))
+
 
 @dataclasses.dataclass(frozen=True, order=True, slots=True, repr=False, kw_only=True)
 class Candidate:

src/fromager/context.py

@@ -20,9 +20,10 @@
     external_commands,
     packagesettings,
 )
+from .candidate import Cooldown
 
 if typing.TYPE_CHECKING:
-    from . import build_environment, candidate
+    from . import build_environment
 
 logger = logging.getLogger(__name__)
 
@@ -47,7 +48,7 @@ def __init__(
         max_jobs: int | None = None,
         settings_dir: pathlib.Path | None = None,
         wheel_server_url: str = "",
-        cooldown: candidate.Cooldown | None = None,
+        cooldown: Cooldown | None = None,
         max_release_age: datetime.timedelta | None = None,
     ):
         if active_settings is None:
@@ -95,7 +96,9 @@ def __init__(
 
         self._parallel_builds = False
 
-        self.cooldown: candidate.Cooldown | None = cooldown
+        self.cooldown: Cooldown = (
+            cooldown if cooldown is not None else Cooldown.disabled()
+        )
         self._max_release_age: datetime.timedelta | None = max_release_age
 
     @property

src/fromager/finders.py

@@ -61,7 +61,6 @@ def __init__(
             ignore_platform=False,
             use_resolver_cache=use_resolver_cache,
             override_download_url=None,
-            cooldown=None,
             supports_upload_time=False,
         )
 

src/fromager/resolver.py

@@ -164,68 +164,57 @@ def _get_toplevel_pinned_versions(
 def _resolve_cooldown_params(
     ctx: context.WorkContext,
     req: Requirement,
-) -> tuple[datetime.timedelta, datetime.datetime] | None:
+) -> tuple[datetime.timedelta, datetime.datetime]:
     """Resolve min_age and bootstrap_time for a package's cooldown.
 
-    Returns ``None`` when cooldown is disabled (no global/per-package
-    configuration, or a per-package override of 0).  Otherwise returns
-    the effective ``(min_age, bootstrap_time)`` pair.
+    Always returns a ``(min_age, bootstrap_time)`` pair.  When cooldown is
+    disabled (per-package override of 0, or no global/per-package config),
+    ``min_age`` will be zero — every package age exceeds that threshold.
     """
     min_age_override = ctx.package_build_info(req).resolver_min_release_age
 
-    if ctx.cooldown is None and min_age_override is None:
-        return None
     if min_age_override == 0:
-        return None
-
-    if min_age_override is not None:
+        min_age = datetime.timedelta(0)
+    elif min_age_override is not None:
         min_age = datetime.timedelta(days=min_age_override)
-    elif ctx.cooldown is not None:
-        min_age = ctx.cooldown.min_age
     else:
-        return None
+        min_age = ctx.cooldown.min_age
 
-    bootstrap_time = (
-        ctx.cooldown.bootstrap_time
-        if ctx.cooldown is not None
-        else datetime.datetime.now(datetime.UTC)
-    )
-    return min_age, bootstrap_time
+    return min_age, ctx.cooldown.bootstrap_time
 
 
 def resolve_package_cooldown(
     ctx: context.WorkContext,
     req: Requirement,
     req_type: RequirementType | None = None,
-) -> Cooldown | None:
+) -> Cooldown:
     """Compute the effective cooldown for a single package.
 
-    Returns ``None`` (cooldown disabled) when:
+    Always returns a ``Cooldown`` instance.  A ``min_age`` of zero means
+    cooldown is effectively disabled — every package age exceeds zero.
+
+    Returns a *disabled* cooldown (min_age=0) when:
 
     * The requirement is a top-level exact ``==`` pin — the user explicitly
       approved that version.
     * A per-package ``min_release_age=0`` override disables cooldown.
     * No global cooldown is configured and no per-package override enables one.
 
-    Otherwise a ``Cooldown`` is returned with:
+    Otherwise returns an *active* cooldown with:
 
     * *min_age* from the per-package override (if set) or the global cooldown.
     * *bootstrap_time* inherited from the global cooldown (for a consistent
-      cutoff across the entire run) or the current time.
+      cutoff across the entire run).
     * *exempt_versions* populated from top-level exact-pinned entries in the
       dependency graph, so transitive resolutions of the same package honour
       the user's explicit pin.
     """
     if req_type == RequirementType.TOP_LEVEL and _has_equality_pin(req):
-        if ctx.cooldown is not None:
+        if ctx.cooldown.min_age:
             logger.info("cooldown bypassed as the top-level requirement uses == pin")
-        return None
-
-    params = _resolve_cooldown_params(ctx, req)
-    if params is None:
-        return None
+        return Cooldown.disabled()
 
-    min_age, bootstrap_time = params
+    min_age, bootstrap_time = _resolve_cooldown_params(ctx, req)
     return Cooldown(
         min_age=min_age,
         bootstrap_time=bootstrap_time,
@@ -243,12 +232,7 @@ def _compute_max_age_cutoff(
     """
     if ctx.max_release_age is None:
         return None
-    bootstrap_time = (
-        ctx.cooldown.bootstrap_time
-        if ctx.cooldown is not None
-        else datetime.datetime.now(datetime.UTC)
-    )
-    return bootstrap_time - ctx.max_release_age
+    return ctx.cooldown.bootstrap_time - ctx.max_release_age
 
 
 def extract_filename_from_url(url: str) -> str:
@@ -609,8 +593,9 @@ def __init__(
         self.req_type = req_type
         self.use_cache_candidates = use_resolver_cache
 
-        # cooldown specific settings
-        self.cooldown = cooldown
+        self.cooldown: Cooldown = (
+            cooldown if cooldown is not None else Cooldown.disabled()
+        )
         # Does this provider supply upload timestamps for candidates?
         # Defaults to False (safe/unknown). Subclasses that reliably populate
         # upload_time on every candidate should set this to True in their __init__.
@@ -732,7 +717,7 @@ def is_satisfied_by(self, requirement: Requirement, candidate: Candidate) -> boo
     def is_blocked_by_cooldown(self, candidate: Candidate) -> bool:
         """Return True if the candidate is rejected by the release-age cooldown."""
 
-        if self.cooldown is None:
+        if not self.cooldown.min_age:
             return False
 
         if candidate.version in self.cooldown.exempt_versions:
@@ -981,7 +966,7 @@ def _get_no_match_error_message(
 
         # If a cooldown is active, check whether it's responsible for the
         # failure so we can give a more actionable error message.
-        if self.cooldown is not None:
+        if self.cooldown.min_age:
             cutoff = self.cooldown.bootstrap_time - self.cooldown.min_age
             all_candidates = list(self._find_cached_candidates(identifier))
             missing_time = [c for c in all_candidates if c.upload_time is None]