feat(resolver): exempt top-level == pins from release cooldown

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

Author: LalatenduMohanty

docs/how-tos/release-age-cooldown.rst

@@ -130,3 +130,13 @@ Valid values:
 This is useful when a specific package is trusted enough to allow recent
 versions, or when a package's release cadence makes the global cooldown
 impractical.
+
+Top-Level ``==`` Pin Exemption
+------------------------------
+
+Top-level requirements that use ``==`` (e.g. ``torch==2.5.1``) bypass the
+cooldown automatically — the operator has explicitly chosen that version.
+
+``==`` specifiers in transitive dependencies are **not** exempt; without
+this distinction a malicious package could pin its own dependencies to
+bypass cooldown.

docs/proposals/release-cooldown.md

@@ -55,17 +55,12 @@ References:
   global default plus per-package overrides.
 - **SSH transport** for git timestamp retrieval.
 
-### Future consideration: `==` pin exemptions
-
-Whether `==` pins in top-level requirements or constraints files
-should automatically bypass cooldown is deferred. The per-package
-`resolver_dist.min_release_age: 0` override already provides an
-explicit, auditable escape hatch for packages that need to use
-recently-published versions. Adding automatic `==` exemptions
-would introduce a special case that weakens the security model
-and requires users to understand the distinction. This can be
-revisited if the per-package override proves too cumbersome in
-practice.
+### `==` pin exemptions (implemented)
+
+Top-level `==` pins bypass cooldown automatically. Transitive `==` pins
+remain subject to cooldown for security. See
+[the how-to guide](../how-tos/release-age-cooldown.rst) for details.
+Tracked in [#1123](https://github.com/python-wheel-build/fromager/issues/1123).
 
 ## How
 

src/fromager/resolver.py

@@ -103,7 +103,7 @@ def resolve(
         req_type=req_type,
         ignore_platform=ignore_platform,
     )
-    provider.cooldown = resolve_package_cooldown(ctx, req)
+    provider.cooldown = resolve_package_cooldown(ctx, req, req_type=req_type)
     max_age_cutoff = _compute_max_age_cutoff(ctx)
     results = find_all_matching_from_provider(
         provider, req, max_age_cutoff=max_age_cutoff
@@ -137,19 +137,35 @@ def default_resolver_provider(
     )
 
 
+def _has_equality_pin(req: Requirement) -> bool:
+    """Return True if the requirement has a single exact ``==`` pin.
+
+    Rejects wildcard pins (``==1.*``) and compound specifiers (``==1,>2``)
+    which are not true exact version pins.
+    """
+    specs = list(req.specifier)
+    return len(specs) == 1 and specs[0].operator == "==" and "*" not in specs[0].version
+
+
 def resolve_package_cooldown(
     ctx: context.WorkContext,
     req: Requirement,
+    req_type: RequirementType | None = None,
 ) -> Cooldown | None:
     """Compute the effective cooldown for a single package.
 
     Args:
         ctx: The current work context (provides the global cooldown).
         req: The package requirement being resolved.
+        req_type: The requirement type (top-level, install, etc.).
 
     Returns:
         The cooldown to pass to the provider, or ``None`` if disabled.
     """
+    if req_type == RequirementType.TOP_LEVEL and _has_equality_pin(req):
+        logger.info("cooldown bypassed -- top-level requirement uses == pin")
+        return None
+
     per_package_days = ctx.package_build_info(req).resolver_min_release_age
     global_cooldown = ctx.cooldown
     if per_package_days is None:

src/fromager/sources.py

@@ -153,7 +153,7 @@ def get_source_provider(
             ignore_platform=pbi.resolver_ignore_platform,
         ),
     )
-    provider.cooldown = resolver.resolve_package_cooldown(ctx, req)
+    provider.cooldown = resolver.resolve_package_cooldown(ctx, req, req_type=req_type)
     return provider
 
 

src/fromager/wheels.py

@@ -549,7 +549,9 @@ def resolve_all_prebuilt_wheels(
             provider = get_prebuilt_wheel_provider(
                 ctx=ctx, req=req, wheel_server_url=url, req_type=req_type
             )
-            provider.cooldown = resolver.resolve_package_cooldown(ctx, req)
+            provider.cooldown = resolver.resolve_package_cooldown(
+                ctx, req, req_type=req_type
+            )
             # The local fromager wheel server is PEP 503-only and serves
             # packages that were already resolved and vetted earlier in the
             # same run. Don't fail-closed on missing upload_time there.

tests/test_cooldown.py

@@ -20,6 +20,7 @@
 from packaging.version import Version
 
 from fromager import candidate, context, packagesettings, resolver, sources, wheels
+from fromager.requirements_file import RequirementType
 
 _BOOTSTRAP_TIME = datetime.datetime(2026, 3, 26, 0, 0, 0, tzinfo=datetime.UTC)
 _COOLDOWN_7_DAYS = datetime.timedelta(days=7)
@@ -860,3 +861,69 @@ def test_compute_max_age_cutoff_disabled(
     """_compute_max_age_cutoff returns None when max_release_age is not set."""
     cutoff = resolver._compute_max_age_cutoff(tmp_context)
     assert cutoff is None
+
+
+def test_resolve_package_cooldown_exempt_toplevel_equality_pin(
+    tmp_path: pathlib.Path,
+) -> None:
+    """Top-level == pin bypasses cooldown."""
+    ctx = _make_ctx(tmp_path, cooldown=_COOLDOWN)
+    result = resolver.resolve_package_cooldown(
+        ctx, Requirement("test-pkg==1.3.2"), req_type=RequirementType.TOP_LEVEL
+    )
+    assert result is None
+
+
+def test_resolve_package_cooldown_enforced_transitive_equality_pin(
+    tmp_path: pathlib.Path,
+) -> None:
+    """Transitive == pin does NOT bypass cooldown."""
+    ctx = _make_ctx(tmp_path, cooldown=_COOLDOWN)
+    result = resolver.resolve_package_cooldown(
+        ctx, Requirement("test-pkg==1.3.2"), req_type=RequirementType.INSTALL
+    )
+    assert result is _COOLDOWN
+
+
+def test_resolve_package_cooldown_enforced_toplevel_no_pin(
+    tmp_path: pathlib.Path,
+) -> None:
+    """Top-level requirement without == still gets cooldown."""
+    ctx = _make_ctx(tmp_path, cooldown=_COOLDOWN)
+    result = resolver.resolve_package_cooldown(
+        ctx, Requirement("test-pkg>=1.0"), req_type=RequirementType.TOP_LEVEL
+    )
+    assert result is _COOLDOWN
+
+
+def test_resolve_package_cooldown_none_req_type_not_exempt(
+    tmp_path: pathlib.Path,
+) -> None:
+    """Unknown req_type (None) with == does NOT bypass cooldown."""
+    ctx = _make_ctx(tmp_path, cooldown=_COOLDOWN)
+    result = resolver.resolve_package_cooldown(
+        ctx, Requirement("test-pkg==1.3.2"), req_type=None
+    )
+    assert result is _COOLDOWN
+
+
+def test_resolve_package_cooldown_toplevel_wildcard_equality_not_exempt(
+    tmp_path: pathlib.Path,
+) -> None:
+    """Top-level wildcard equality (==1.*) is not an exact pin — cooldown applies."""
+    ctx = _make_ctx(tmp_path, cooldown=_COOLDOWN)
+    result = resolver.resolve_package_cooldown(
+        ctx, Requirement("test-pkg==1.*"), req_type=RequirementType.TOP_LEVEL
+    )
+    assert result is _COOLDOWN
+
+
+def test_resolve_package_cooldown_toplevel_compound_specifier_not_exempt(
+    tmp_path: pathlib.Path,
+) -> None:
+    """Top-level compound specifier (==1.0,>0.9) is not a single exact pin."""
+    ctx = _make_ctx(tmp_path, cooldown=_COOLDOWN)
+    result = resolver.resolve_package_cooldown(
+        ctx, Requirement("test-pkg==1.0,>0.9"), req_type=RequirementType.TOP_LEVEL
+    )
+    assert result is _COOLDOWN