fix(resolver): include req_type in resolution cache key

[rd4398]

The session-level cache in BootstrapRequirementResolver used (requirement_string, pre_built) as its cache key, ignoring req_type. When a package was first resolved as a transitive dependency with cooldown enforced, the cached result was incorrectly reused for a subsequent top-level resolution that should have bypassed cooldown.

Add req_type to the cache key so transitive and top-level resolutions are cached separately.

Closes: #1187

[coderabbitai]

Warning

Review limit reached

@rd4398, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 32 minutes and 15 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: c7629a64-36cb-43c5-a2e6-a458cf2ea3fa

📥 Commits

Reviewing files that changed from the base of the PR and between 8cd195f and 2805c3e.

📒 Files selected for processing (3)

• src/fromager/bootstrap_requirement_resolver.py
• src/fromager/bootstrapper.py
• tests/test_bootstrap_requirement_resolver.py

📝 Walkthrough

Walkthrough

BootstrapRequirementResolver now includes RequirementType in its session-level cache key. The internal _resolved_requirements dict keys changed from (requirement_string, pre_built) to (requirement_string, pre_built, req_type). Public helper methods get_cached_resolution() and cache_resolution() accept the new req_type parameter. The resolve() method and git+ URL path in Bootstrapper.resolve_versions() pass req_type to these cache methods. Tests verify cache separation between transitive (INSTALL) and top-level (TOP_LEVEL) resolutions and confirm tuple immutability.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly and accurately describes the main change: adding req_type to the resolution cache key in the resolver.
Description check	✅ Passed	The description clearly explains the bug (cache key missing req_type), its impact (cooldown bypass ignored), and the solution (add req_type to cache key).
Linked Issues check	✅ Passed	The PR implementation fully addresses issue #1187 by adding req_type to the cache key in BootstrapRequirementResolver, ensuring transitive and top-level resolutions are cached separately.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to fixing the cache key bug: cache key modifications, method signature updates, and related test coverage for cache separation.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[LalatenduMohanty]

@dhellmann This alone might not fix the issue A>=1.0 blocking A==2.0.0 top-level. We need #1157 as well. But we should merge this first then merge #1157

[tiran]

IMO the suggestion from 1187 is not the best solution. Breadth-first resolution of top-level requirements should solve the issue, too.

[rd4398]

IMO the suggestion from 1187 is not the best solution. Breadth-first resolution of top-level requirements should solve the issue, too.

@tiran I agree that 1187 is not the best solution however, I think the BFS approach will make things more complicated. I see the following challenges:

1. Build dependency ordering constraint

DFS exists for a reason: to build packages in dependency order. Before you can
build package B, you need B's build dependencies (setuptools, wheel, etc.) to
be available as wheels. The DFS loop ensures that when `_phase_prepare_build`
installs build deps into the build environment, those wheels have already been
built.

A pure BFS approach would try to build all top-level packages simultaneously,
but their build dependencies might not be ready yet. This is the fundamental
constraint.

Impact: A naive BFS would require a two-pass approach:
- Pass 1: Resolve all top-level versions (already done)
- Pass 2: Build in topological order based on dependency graph

This is essentially what `bootstrap_parallel` already does (sdist-only serial
pass, then parallel wheel build).

2. Scope of changes

Changing from DFS to BFS in the iterative bootstrap loop would be a
significant refactor:

- The `WorkItem` phase machine and LIFO stack are designed for DFS
- Changing to a FIFO queue (BFS) would break build ordering guarantees
- The `_track_why` dependency chain tracking assumes DFS order
- The `_seen_requirements` deduplication assumes DFS order
- Progress tracking and logging assume DFS order

I wonder this will complicate the already existing bootstrap logic. A more targeted approach would be to add a resolution-only BFS pass before the DFS build pass, but this is essentially what pre-resolution already does.

3. BFS doesn't fully solve the problem

Even with BFS for top-level resolution, transitive dependencies of B can
still conflict with transitive dependencies of C. If B depends on `X>=1.0`
and C depends on `X>=2.0`, whichever is resolved first sets the cache. This
is a broader issue than just top-level vs transitive.

4. Multiple version mode

In `--multiple-versions` mode, the resolver returns ALL matching versions, not
just the highest. BFS resolution would need to handle this correctly — all
versions of all top-level deps resolved before any transitive deps.

This is already handled by pre-resolution (`resolve_and_add_top_level` with
`return_all_versions=self.multiple_versions`)

Some points to consider:

1. Is building two versions actually wrong? -- In single-version mode, both
   versions will be built, but downstream packages will use whichever version
   the dependency graph and constraints file specify. If A==2.0.0 satisfies
   A>=1.0, the constraints file should pick 2.0.0

2. The pre-resolution gap -- re-resolution caches ("A==2.0.0", False).
   The transitive dep is ("A>=1.0", False) — a different cache key. These
   don't collide. The bug requires identical requirement strings. How often we will hit this scenario?

3. To avoid redundant builds, I think the fix could be at the
   _phase_start level: when a transitive resolution produces version X,
   check if a top-level resolution for the same package already produced
   version Y > X that satisfies the transitive specifier, and use Y instead.
   This is version reconciliation, not resolution order change.

4. If we all still want to do a BFS approach, the lowest refactor and less risky solution will be: resolve all top-level deps in pre-resolution (already done), then in the DFS build
   loop, have _phase_resolve check if the package was already resolved as top-level in pre-resolution and reuse that version when compatible. This avoids changing DFS→BFS entirely

Let me know what you think / whether I am missing anything. cc @LalatenduMohanty @dhellmann

[rd4398]

IMO the suggestion from 1187 is not the best solution. Breadth-first resolution of top-level requirements should solve the issue, too.

@tiran I agree that 1187 is not the best solution however, I think the BFS approach will make things more complicated. I see the following challenges:

1. Build dependency ordering constraint

DFS exists for a reason: to build packages in dependency order. Before you can
build package B, you need B's build dependencies (setuptools, wheel, etc.) to
be available as wheels. The DFS loop ensures that when `_phase_prepare_build`
installs build deps into the build environment, those wheels have already been
built.

A pure BFS approach would try to build all top-level packages simultaneously,
but their build dependencies might not be ready yet. This is the fundamental
constraint.

Impact: A naive BFS would require a two-pass approach:
- Pass 1: Resolve all top-level versions (already done)
- Pass 2: Build in topological order based on dependency graph

This is essentially what `bootstrap_parallel` already does (sdist-only serial
pass, then parallel wheel build).

2. Scope of changes

Changing from DFS to BFS in the iterative bootstrap loop would be a
significant refactor:

- The `WorkItem` phase machine and LIFO stack are designed for DFS
- Changing to a FIFO queue (BFS) would break build ordering guarantees
- The `_track_why` dependency chain tracking assumes DFS order
- The `_seen_requirements` deduplication assumes DFS order
- Progress tracking and logging assume DFS order

I wonder this will complicate the already existing bootstrap logic. A more targeted approach would be to add a resolution-only BFS pass before the DFS build pass, but this is essentially what pre-resolution already does.

3. BFS doesn't fully solve the problem

Even with BFS for top-level resolution, transitive dependencies of B can
still conflict with transitive dependencies of C. If B depends on `X>=1.0`
and C depends on `X>=2.0`, whichever is resolved first sets the cache. This
is a broader issue than just top-level vs transitive.

4. Multiple version mode

In `--multiple-versions` mode, the resolver returns ALL matching versions, not
just the highest. BFS resolution would need to handle this correctly — all
versions of all top-level deps resolved before any transitive deps.

This is already handled by pre-resolution (`resolve_and_add_top_level` with
`return_all_versions=self.multiple_versions`)

Some points to consider:

1. Is building two versions actually wrong? -- In single-version mode, both
   versions will be built, but downstream packages will use whichever version
   the dependency graph and constraints file specify. If A==2.0.0 satisfies
   A>=1.0, the constraints file should pick 2.0.0
2. The pre-resolution gap -- re-resolution caches ("A==2.0.0", False).
   The transitive dep is ("A>=1.0", False) — a different cache key. These
   don't collide. The bug requires identical requirement strings. How often we will hit this scenario?
3. To avoid redundant builds, I think the fix could be at the
   _phase_start level: when a transitive resolution produces version X,
   check if a top-level resolution for the same package already produced
   version Y > X that satisfies the transitive specifier, and use Y instead.
   This is version reconciliation, not resolution order change.
4. If we all still want to do a BFS approach, the lowest refactor and less risky solution will be: resolve all top-level deps in pre-resolution (already done), then in the DFS build
   loop, have _phase_resolve check if the package was already resolved as top-level in pre-resolution and reuse that version when compatible. This avoids changing DFS→BFS entirely

Let me know what you think / whether I am missing anything. cc @LalatenduMohanty @dhellmann

UPDATE: I posted this before reading Doug's comment here: #1187 (comment)
I am okay with implementing what he suggested and will make changes to this PR