fix(resolver): use two-step resolution for age filter fallback in multi-version mode

When --max-release-age filters out all candidates, the resolver's safety
fallback kept every candidate, causing multi-version bootstrap to attempt
building all versions. Now the bootstrapper checks the wheel cache first:
if a cached wheel exists the package is skipped; otherwise it re-resolves
without the age filter as a last resort.

Co-Authored-By: Claude <claude@anthropic.com>
Signed-off-by: Rohan Devasthale <rdevasth@redhat.com>

Author: rd4398

src/fromager/bootstrap_requirement_resolver.py

@@ -40,15 +40,20 @@ def __init__(
         self,
         ctx: context.WorkContext,
         prev_graph: DependencyGraph | None = None,
+        multiple_versions: bool = False,
     ) -> None:
         """Initialize requirement resolver.
 
         Args:
             ctx: Work context with constraints and settings
             prev_graph: Optional previous dependency graph for caching
+            multiple_versions: If ``True``, age filtering returns an empty
+                list instead of falling back to all candidates, letting the
+                caller decide how to handle the case.
         """
         self.ctx = ctx
         self.prev_graph = prev_graph
+        self.multiple_versions = multiple_versions
         # Session-level resolution cache to avoid re-resolving same requirements
         # Key: (requirement_string, pre_built) to distinguish source vs prebuilt
         # Value: tuple of (url, version) tuples sorted by version (highest first)
@@ -65,6 +70,7 @@ def resolve(
         parent_req: Requirement | None = None,
         pre_built: bool | None = None,
         return_all_versions: bool = False,
+        skip_age_filter: bool = False,
     ) -> list[tuple[str, Version]]:
         """Resolve package requirement to matching version(s).
 
@@ -81,6 +87,9 @@ def resolve(
                 If None (default), uses package build info to determine.
             return_all_versions: If True, return all matching versions. If False,
                 return only the highest matching version.
+            skip_age_filter: If ``True``, resolve without applying
+                ``max_release_age`` filtering.  Used for fallback resolution
+                when the initial age-filtered attempt returned no candidates.
 
         Returns:
             List of (url, version) tuples sorted by version (highest first).
@@ -104,25 +113,38 @@ def resolve(
                 f"Git URL requirements must be handled by Bootstrapper: {req}"
             )
 
-        # Check session cache (keyed by requirement + pre_built)
-        cached_result = self.get_cached_resolution(req, pre_built)
-        if cached_result is not None:
-            logger.debug(f"resolved {req} from cache")
-            return list(cached_result) if return_all_versions else [cached_result[0]]
+        # Skip session cache when age filter is overridden to avoid
+        # mixing filtered and unfiltered results.
+        if not skip_age_filter:
+            cached_result = self.get_cached_resolution(req, pre_built)
+            if cached_result is not None:
+                logger.debug(f"resolved {req} from cache")
+                return (
+                    list(cached_result) if return_all_versions else [cached_result[0]]
+                )
 
         # Resolve using strategies
-        results = self._resolve(req, req_type, parent_req, pre_built)
+        results = self._resolve(
+            req, req_type, parent_req, pre_built, skip_age_filter=skip_age_filter
+        )
 
-        # Cache the result
-        self.cache_resolution(req, pre_built, results)
-        return results if return_all_versions else [results[0]]
+        # Cache non-empty results from normal (age-filtered) resolution only.
+        if results and not skip_age_filter:
+            self.cache_resolution(req, pre_built, results)
+
+        if return_all_versions:
+            return results
+        if not results:
+            raise RuntimeError(f"No versions found for {req}")
+        return [results[0]]
 
     def _resolve(
         self,
         req: Requirement,
         req_type: RequirementType,
         parent_req: Requirement | None,
         pre_built: bool,
+        skip_age_filter: bool = False,
     ) -> list[tuple[str, Version]]:
         """Internal resolution logic without caching.
 
@@ -135,6 +157,7 @@ def _resolve(
             req_type: Type of requirement
             parent_req: Parent requirement from dependency chain
             pre_built: Whether to resolve prebuilt (True) or source (False)
+            skip_age_filter: If ``True``, skip ``max_release_age`` filtering.
 
         Returns:
             List of (url, version) tuples sorted by version (highest first)
@@ -175,9 +198,14 @@ def _resolve(
                 sdist_server_url=resolver.PYPI_SERVER_URL,
                 req_type=req_type,
             )
-            max_age_cutoff = resolver._compute_max_age_cutoff(self.ctx)
+            max_age_cutoff = (
+                None if skip_age_filter else resolver._compute_max_age_cutoff(self.ctx)
+            )
             return resolver.find_all_matching_from_provider(
-                provider, req, max_age_cutoff=max_age_cutoff
+                provider,
+                req,
+                max_age_cutoff=max_age_cutoff,
+                fallback_on_empty_age_filter=not self.multiple_versions,
             )
 
     def get_cached_resolution(

src/fromager/bootstrapper.py

@@ -173,6 +173,7 @@ def __init__(
         self._resolver = bootstrap_requirement_resolver.BootstrapRequirementResolver(
             ctx=ctx,
             prev_graph=prev_graph,
+            multiple_versions=multiple_versions,
         )
         # Push items onto the stack as we start to resolve their
         # dependencies so at the end we have a list of items that need to
@@ -258,6 +259,7 @@ def resolve_versions(
         req: Requirement,
         req_type: RequirementType,
         return_all_versions: bool = False,
+        skip_age_filter: bool = False,
     ) -> list[tuple[str, Version]]:
         """Resolve version(s) of a requirement.
 
@@ -272,6 +274,8 @@ def resolve_versions(
             req_type: Type of requirement
             return_all_versions: If True, return all matching versions.
                 If False, return only highest version.
+            skip_age_filter: If ``True``, resolve without applying
+                ``max_release_age`` filtering.
 
         Returns:
             List of (url, version) tuples. Contains one item when
@@ -307,6 +311,7 @@ def resolve_versions(
             req_type=req_type,
             parent_req=parent_req,
             return_all_versions=return_all_versions,
+            skip_age_filter=skip_age_filter,
         )
 
     def _processing_build_requirement(self, current_req_type: RequirementType) -> bool:
@@ -669,6 +674,26 @@ def _find_cached_wheel(
 
         return None, None
 
+    def _has_any_cached_wheel(self, req: Requirement) -> bool:
+        """Check if ANY version of a package has a cached wheel locally.
+
+        Scans local wheel directories for any ``.whl`` file matching the
+        package name.  Used to determine whether a package can be safely
+        skipped when all versions are filtered by ``max-release-age``.
+        """
+        prefix = finders._dist_name_to_filename(req.name).lower() + "-"
+        for search_dir in (
+            self.ctx.wheels_build,
+            self.ctx.wheels_downloads,
+            self.ctx.wheels_prebuilt,
+        ):
+            if not search_dir.exists():
+                continue
+            for whl in search_dir.glob("*.whl"):
+                if whl.name.lower().startswith(prefix):
+                    return True
+        return False
+
     def _get_install_dependencies(
         self,
         req: Requirement,
@@ -1341,17 +1366,49 @@ def _phase_resolve(self, item: WorkItem) -> list[WorkItem]:
         wheels are already cached to avoid redundant builds and
         transitive dependency processing.
 
+        When ``max-release-age`` filtering yields no candidates in
+        multiple-version mode, checks the local wheel cache:
+
+        - Cached wheel exists: skip the package (return empty list).
+        - No cached wheel: re-resolve without the age filter so the
+          package can still be built for the first time.
+
         Returns:
             One START-phase item per resolved version that needs building.
-            Empty list if all versions are already cached.
+            Empty list if all versions are already cached or skipped.
         """
         resolved_versions = self.resolve_versions(
             item.req,
             item.req_type,
             return_all_versions=self.multiple_versions,
         )
+
         if not resolved_versions:
-            raise RuntimeError(f"Could not resolve any versions for {item.req}")
+            if not self.multiple_versions:
+                raise RuntimeError(f"Could not resolve any versions for {item.req}")
+
+            if self._has_any_cached_wheel(item.req):
+                logger.info(
+                    "%s: all versions filtered by max-release-age, "
+                    "cached wheel exists; skipping",
+                    item.req.name,
+                )
+                return []
+
+            # No cached wheel — fall back to unfiltered resolution
+            logger.warning(
+                "%s: all versions filtered by max-release-age and no "
+                "cached wheel exists; falling back to unfiltered resolution",
+                item.req.name,
+            )
+            resolved_versions = self.resolve_versions(
+                item.req,
+                item.req_type,
+                return_all_versions=True,
+                skip_age_filter=True,
+            )
+            if not resolved_versions:
+                raise RuntimeError(f"Could not resolve any versions for {item.req}")
 
         if self.multiple_versions:
             logger.info(f"resolved {len(resolved_versions)} version(s) for {item.req}")

src/fromager/resolver.py

@@ -243,6 +243,7 @@ def find_all_matching_from_provider(
     provider: BaseProvider,
     req: Requirement,
     max_age_cutoff: datetime.datetime | None = None,
+    fallback_on_empty_age_filter: bool = True,
 ) -> list[tuple[str, Version]]:
     """Find all matching candidates from provider without full dependency resolution.
 
@@ -255,6 +256,10 @@ def find_all_matching_from_provider(
         max_age_cutoff: If set, reject candidates published before this time.
             If all candidates are older than the cutoff, all are kept and
             a warning is emitted to avoid empty resolution.
+        fallback_on_empty_age_filter: If ``True`` (default), keep all
+            candidates when age filtering would produce an empty result.
+            If ``False``, return an empty list instead, allowing the
+            caller to implement its own fallback strategy.
 
     Returns list of (url, version) tuples sorted by version (highest first).
 
@@ -315,7 +320,7 @@ def find_all_matching_from_provider(
             )
         if filtered:
             candidates_list = filtered
-        else:
+        elif fallback_on_empty_age_filter:
             logger.warning(
                 "%s: all %d candidate(s) of %s are older than %d days, "
                 "keeping all to avoid empty resolution",
@@ -324,6 +329,15 @@ def find_all_matching_from_provider(
                 req,
                 max_age_days,
             )
+        else:
+            logger.info(
+                "%s: all %d candidate(s) of %s are older than %d days",
+                req.name,
+                len(candidates_list),
+                req,
+                max_age_days,
+            )
+            candidates_list = []
 
     # Convert candidates to list of (url, version) tuples
     # Candidates are sorted by version (highest first) by BaseProvider.find_matches()

tests/test_bootstrapper_iterative.py

@@ -353,6 +353,100 @@ def test_no_filtering_in_single_version_mode(
         assert len(result) == 1
         mock_cache.assert_not_called()
 
+    def test_age_filtered_all_with_cache_skips_package(
+        self, tmp_context: WorkContext
+    ) -> None:
+        """When all versions are age-filtered and a cached wheel exists, skip entirely."""
+        bt = bootstrapper.Bootstrapper(tmp_context, multiple_versions=True)
+        item = _make_resolve_item()
+
+        with (
+            patch.object(bt, "resolve_versions", return_value=[]),
+            patch.object(bt, "_has_any_cached_wheel", return_value=True),
+        ):
+            result = bt._phase_resolve(item)
+
+        assert result == []
+
+    def test_age_filtered_all_without_cache_falls_back(
+        self, tmp_context: WorkContext
+    ) -> None:
+        """When all versions are age-filtered and no cached wheel, re-resolve without filter."""
+        bt = bootstrapper.Bootstrapper(tmp_context, multiple_versions=True)
+        item = _make_resolve_item()
+
+        call_count = 0
+
+        def mock_resolve(
+            req: Requirement,
+            req_type: RequirementType,
+            return_all_versions: bool = False,
+            skip_age_filter: bool = False,
+        ) -> list:
+            nonlocal call_count
+            call_count += 1
+            if call_count == 1:
+                return []
+            return [("url-1.0", Version("1.0"))]
+
+        with (
+            patch.object(bt, "resolve_versions", side_effect=mock_resolve),
+            patch.object(bt, "_has_any_cached_wheel", return_value=False),
+        ):
+            result = bt._phase_resolve(item)
+
+        assert len(result) == 1
+        assert result[0].resolved_version == Version("1.0")
+        assert call_count == 2
+
+    def test_empty_resolution_raises_in_single_version_mode(
+        self, tmp_context: WorkContext
+    ) -> None:
+        """In single-version mode, empty resolution raises RuntimeError."""
+        bt = bootstrapper.Bootstrapper(tmp_context, multiple_versions=False)
+        item = _make_resolve_item()
+
+        with (
+            patch.object(bt, "resolve_versions", return_value=[]),
+            pytest.raises(RuntimeError, match="Could not resolve"),
+        ):
+            bt._phase_resolve(item)
+
+
+class TestHasAnyCachedWheel:
+    def test_finds_wheel_in_build_dir(self, tmp_context: WorkContext) -> None:
+        """Detects wheel in build directory."""
+        bt = bootstrapper.Bootstrapper(tmp_context)
+        tmp_context.wheels_build.mkdir(parents=True, exist_ok=True)
+        (tmp_context.wheels_build / "testpkg-1.0-py3-none-any.whl").touch()
+        assert bt._has_any_cached_wheel(Requirement("testpkg")) is True
+
+    def test_finds_wheel_in_downloads_dir(self, tmp_context: WorkContext) -> None:
+        """Detects wheel in downloads directory."""
+        bt = bootstrapper.Bootstrapper(tmp_context)
+        tmp_context.wheels_downloads.mkdir(parents=True, exist_ok=True)
+        (tmp_context.wheels_downloads / "testpkg-2.0-py3-none-any.whl").touch()
+        assert bt._has_any_cached_wheel(Requirement("testpkg")) is True
+
+    def test_finds_wheel_in_prebuilt_dir(self, tmp_context: WorkContext) -> None:
+        """Detects wheel in prebuilt directory."""
+        bt = bootstrapper.Bootstrapper(tmp_context)
+        tmp_context.wheels_prebuilt.mkdir(parents=True, exist_ok=True)
+        (tmp_context.wheels_prebuilt / "testpkg-3.0-py3-none-any.whl").touch()
+        assert bt._has_any_cached_wheel(Requirement("testpkg")) is True
+
+    def test_no_wheel_returns_false(self, tmp_context: WorkContext) -> None:
+        """Returns False when no cached wheel exists."""
+        bt = bootstrapper.Bootstrapper(tmp_context)
+        assert bt._has_any_cached_wheel(Requirement("nonexistent")) is False
+
+    def test_different_package_not_matched(self, tmp_context: WorkContext) -> None:
+        """Wheels for other packages are not matched."""
+        bt = bootstrapper.Bootstrapper(tmp_context)
+        tmp_context.wheels_downloads.mkdir(parents=True, exist_ok=True)
+        (tmp_context.wheels_downloads / "otherpkg-1.0-py3-none-any.whl").touch()
+        assert bt._has_any_cached_wheel(Requirement("testpkg")) is False
+
 
 class TestPhaseStart:
     def test_new_item_advances_to_prepare_source(

tests/test_cooldown.py

@@ -796,6 +796,30 @@ def test_max_release_age_all_too_old_keeps_all(
     assert "keeping all to avoid empty resolution" in caplog.text
 
 
+def test_max_release_age_all_too_old_returns_empty_when_fallback_disabled(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """When fallback is disabled and all versions are too old, return empty list."""
+    max_age_cutoff = _BOOTSTRAP_TIME + datetime.timedelta(days=1)
+    with requests_mock.Mocker() as r:
+        r.get(
+            "https://pypi.org/simple/test-pkg/",
+            json=_cooldown_json_response,
+            headers={"Content-Type": _PYPI_SIMPLE_JSON_CONTENT_TYPE},
+        )
+        provider = resolver.PyPIProvider(include_sdists=True)
+        with caplog.at_level(logging.INFO, logger="fromager.resolver"):
+            results = resolver.find_all_matching_from_provider(
+                provider,
+                Requirement("test-pkg"),
+                max_age_cutoff=max_age_cutoff,
+                fallback_on_empty_age_filter=False,
+            )
+    assert results == []
+    assert "all 3 candidate(s)" in caplog.text
+    assert "keeping all to avoid empty resolution" not in caplog.text
+
+
 def test_max_release_age_candidates_without_upload_time_pass_through() -> None:
     """Candidates without upload_time are not filtered out by max-release-age."""
     no_timestamp_response = {