docs(proposals): add unified CacheManager design proposal

[Xaenalt]

Summary

• Splits out the design proposal document for the unified CacheManager from the implementation PR (Add unified CacheManager with prioritized multi-backend lookup #1216)
• Covers motivation, architecture decisions, backend protocol, CLI surface, and integration points

Implementation: #1216

Test plan

• Docs build passes (hatch run docs:build)
• RST renders correctly in Sphinx output

Made with Cursor

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR adds a proposal for a unified cache manager. It defines prioritized local and remote cache lookup, centralized storage, integrity verification, observability commands, cached-wheel bootstrap short-circuiting, opt-in configuration, security safeguards, verification coverage, and future extensions.

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 clearly identifies the addition of the unified CacheManager design proposal.
Description check	✅ Passed	The description accurately summarizes the standalone CacheManager proposal and its documentation test plan.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

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.}

[coderabbitai]

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/proposals/unified-cache-manager.rst`:
- Line 66: Update the PrepareSource.run() reference in the CacheManager
documentation text to use RST’s required double-backtick markup, preserving the
surrounding wording.
- Around line 106-115: The heading "Files added or modified:" in the
unified-cache-manager proposal document is ambiguous and implies these files are
being changed by the current PR, when they actually represent planned changes
for a future implementation. Rename this heading to something like "Planned
implementation touchpoints" or add introductory text that clarifies the list
describes the proposed implementation work rather than current modifications.
- Around line 130-141: The proposal contains conflicting hash-mismatch behavior:
the remote-download rules say mismatches raise errors, while the fetch-failure
rules treat them as cache misses. Choose one contract, update both the
hash-verification and fetch-failure bullets consistently, and if fallback
remains enabled, preserve hash failures as distinct from ordinary cache misses.
- Around line 41-45: Update WheelCacheKey and the local cache lookup to include
and enforce wheel compatibility tags—interpreter, ABI, and platform—when
identifying or matching artifacts. Ensure local lookup filters candidates by all
tags before returning a hit, keeping local and RemotePEP503Backend behavior
consistent and preventing incompatible wheels from being selected.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 59d3394f-685f-4441-90b7-ff7e8607e3ef

📥 Commits

Reviewing files that changed from the base of the PR and between e979af8 and 7e642c5.

📒 Files selected for processing (1)

• docs/proposals/unified-cache-manager.rst

[coderabbitai]

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/proposals/unified-cache-manager.rst`:
- Around line 154-157: Update the verification section in the unified cache
manager proposal to describe tests, linting, type checking, and formatting as
planned or future work rather than completed results. Rename the section to
“Planned verification” and use future-tense wording unless concrete CI or test
evidence is available to link.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: fa3f9e6c-75e5-43e7-a766-a7d0007a23ea

📥 Commits

Reviewing files that changed from the base of the PR and between e979af8 and 5ce43e1.

📒 Files selected for processing (1)

• docs/proposals/unified-cache-manager.rst

[coderabbitai]

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Mark these checks as planned unless results are available.

This PR contains a standalone proposal. The document lists implementation files as planned touchpoints, but these lines state that new tests and quality checks already pass. Rename the section to Planned verification, use future tense, or link the exact CI and test evidence.

Suggested wording

- Verification
+ Planned verification
- New tests cover cache components, short-circuit logic, concurrency safety,
- CLI commands, and error handling.
+ New tests will cover cache components, short-circuit logic, concurrency
+ safety, CLI commands, and error handling.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/proposals/unified-cache-manager.rst` around lines 154 - 157, Update the
verification section in the unified cache manager proposal to describe tests,
linting, type checking, and formatting as planned or future work rather than
completed results. Rename the section to “Planned verification” and use
future-tense wording unless concrete CI or test evidence is available to link.

[rd4398]

Clarification questions:

1. What happens to server.update_wheel_mirror()?: Currently, when a wheel is found or built, it's registered in the local PEP 503 mirror via server.update_wheel_mirror() so subsequent builds can find it. Does the CacheManager's store operation replace this? Do they coexist?

2. WorkContext.wheels_build returns thread-specific paths during parallel builds (context.py line 115). The proposal says the CacheManager is thread-safe with internal locking, but doesn't discuss:

• Do parallel build threads share a CacheManager instance or get their own?
• How does the LocalDirectoryBackend handle concurrent writes to the same directory?
• What happens if two threads try to store the same wheel simultaneously?

3. Cache staleness and invalidation semantics: cache gc keeps "the N most recent per package+version," but what determines "most recent" — file mtime? Build tag number? And what makes a cached wheel stale in the first place? The existing system uses build-tag comparison to detect stale wheels. Does the CacheManager preserve this, or introduce a new staleness model?

4. The opt-in flag --use-cache-manager is mentioned, but: when the CacheManager is active, does it replace the existing cache checks (in find_cached_wheel and _is_wheel_built), or layer on top of them? Can both run simultaneously? What happens to the --cache-wheel-server-url CLI option — is it consumed by the
   CacheManager or does it continue to feed the old path?

[rd4398]

I think the key should include the full build tag (number + suffix string) from day one, even if the hook isn't wired up yet. We already have a PR (#1273) adds string suffixes to build tags