Proposal: centralize release-age cooldown in `CooldownPolicy` on `Settings`

[LalatenduMohanty]

Summary

Proposal from @tiran to refactor release-age cooldown management around a single CooldownPolicy object owned by Settings, replacing today's split between WorkContext.cooldown, per-request resolve_package_cooldown(), and post-construction provider.cooldown mutation.

POC branch: https://github.com/tiran/fromager/tree/cooldown-policy
POC commit: tiran@aa7666d

Problem

Release-age cooldown (#877) works, but policy state and enforcement are scattered:

Layer	Role today
WorkContext.cooldown	Global Cooldown from --min-release-age
resolve_package_cooldown()	Per-request effective cooldown (per-package override, top-level == bypass)
provider.cooldown	Post-construction mutation at 3 call sites (#1081)
BaseProvider.is_blocked_by_cooldown()	Per-candidate enforcement with provider-specific timestamp semantics

This makes cooldown hard to inspect, test in isolation, and easy to mis-wire (forgetting provider.cooldown = … silently disables enforcement).

Proposed architecture

Move cooldown configuration and filtering into one policy object on Settings:

CLI --min-release-age
        │
        ▼
Settings.cooldown (CooldownPolicy)
  ├── min_release_age          # global default
  ├── package_cooldowns        # pre-loaded from resolver_dist.min_release_age
  ├── cooldown_exempt_versions # from top-level == pins (see #1123)
  └── bootstrap_time           # fixed reference time for the run
        │
        ▼
filter_candidates(candidates)  # single enforcement point after find_candidates

CooldownPolicy responsibilities

1. Configuration — hold global min_release_age, indexed per-package overrides, and version exemptions.
2. Initialization — set_package_cooldowns() pre-loads overrides from package settings once at startup (via Settings._reset()).
3. Exemptions — add_cooldown_exempt_versions() registers (name, version) pairs from exact == pins.
4. Enforcement — filter_candidates() returns only candidates that satisfy the effective minimum age.

Integration points

• --min-release-age passed to Settings.from_files() instead of constructing Cooldown on WorkContext.
• Providers call ctx.settings.cooldown.filter_candidates() after find_candidates(), eliminating provider.cooldown mutation.
• resolve_package_cooldown() and per-provider is_blocked_by_cooldown() logic retired once parity is verified.

Benefits

• Single inspectable object — dump settings.cooldown to see global default, all overrides, and exemptions.
• No post-construction mutation — addresses the fragility described in Avoid post-construction mutation of provider cooldown settings #1081 without adding provider wrapper indirection.
• Pure filter function — filter_candidates() is testable without network or resolvelib.
• Co-located with resolver config — cooldown overrides already live in resolver_dist; policy belongs on Settings.

Related

• add cooldown period when resolving version numbers during bootstrapping #877 — release-age cooldown feature
• Avoid post-construction mutation of provider cooldown settings #1081 — avoid post-construction mutation of provider cooldown
• Exempt == version pins from release cooldown enforcement #1123 — top-level == pin exemptions
• disable cooldown for local and cache wheel server #1140 — disable cooldown for local/cache wheel server
• Cooldown check blocks transitive dependency that matches top-level exact pin #1153 — cooldown edge case with transitive deps matching top-level pin

[LalatenduMohanty]

Design decisions to resolve

The POC does not address these yet:

1. Request context — Today, top-level == bypass uses req_type per request. The POC batch-loads exempt versions instead. Confirm this still matches Exempt == version pins from release cooldown enforcement #1123 (transitive == pins remain subject to cooldown).

2. Provider semantics — Current enforcement is provider-aware (supports_upload_time, GitHub warn-and-skip, local wheel server exception in disable cooldown for local and cache wheel server #1140). A centralized filter must preserve this behavior or document intentional changes.

3. bootstrap_time lifecycle — Same reference time is used for cooldown and --max-release-age; it must stay fixed for the whole run.

4. Observability — filter_candidates() should log structured rejection reasons so centralized filtering is at least as debuggable as today's provider-level logs.

5. Plugin contract — Authors implementing get_resolver_provider should not handle cooldown themselves. Fromager applies cooldown filtering after the provider returns candidates.