Filter cooldown-excluded versions and surface a hint in errors

Adds a per-version filter to `Resolver#filter_specs` that drops specs
whose `created_at` falls within the effective cooldown window. The
filter only runs over `@all_specs`, so lockfile-pinned versions in
`@base` survive even if a newer release would now be excluded. Specs
without `created_at` are kept so historical versions and indexes that
do not yet expose timestamps remain usable.

A shared `cooldown_now` memoization ensures every comparison within
one resolve sees the same timestamp, stabilizing tests near a
threshold boundary. When the resolver fails because every matching
version is in cooldown, both `raise_not_found!` and
`no_versions_incompatibility_for` surface a hint suggesting
`--cooldown 0` to bypass; a small `cooldown_hint` helper keeps the
wording in sync between the two error paths and is locked down with
unit specs.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: hsbt

bundler/lib/bundler/resolver.rb

@@ -203,6 +203,9 @@ def no_versions_incompatibility_for(package, unsatisfied_term)
 
         platforms_explanation = specs_matching_other_platforms.any? ? " for any resolution platforms (#{package.platforms.join(", ")})" : ""
         custom_explanation = "#{constraint} could not be found in #{repository_for(package)}#{platforms_explanation}"
+        if hint = cooldown_hint(specs_matching_other_platforms)
+          custom_explanation += " (#{hint})"
+        end
 
         label = "#{name} (#{constraint_string})"
         extended_explanation = other_specs_matching_message(specs_matching_other_platforms, label) if specs_matching_other_platforms.any?
@@ -372,6 +375,10 @@ def raise_not_found!(package)
         message << "\n#{other_specs_matching_message(specs, matching_part)}"
       end
 
+      if hint = cooldown_hint(specs_matching_requirement)
+        message << "\n\n#{hint}."
+      end
+
       if specs_matching_requirement.any? && (hint = platform_mismatch_hint)
         message << "\n\n#{hint}"
       end
@@ -415,7 +422,7 @@ def filter_matching_specs(specs, requirements)
     end
 
     def filter_specs(specs, package)
-      filter_remote_specs(filter_prereleases(specs, package), package)
+      filter_cooldown(filter_remote_specs(filter_prereleases(specs, package), package))
     end
 
     def filter_prereleases(specs, package)
@@ -424,6 +431,35 @@ def filter_prereleases(specs, package)
       specs.reject {|s| s.version.prerelease? }
     end
 
+    def filter_cooldown(specs)
+      return specs if specs.empty?
+      excluded = cooldown_excluded_specs(specs)
+      return specs if excluded.empty?
+      specs - excluded
+    end
+
+    def cooldown_excluded_specs(specs)
+      specs.select {|spec| cooldown_excluded?(spec) }
+    end
+
+    def cooldown_hint(specs)
+      excluded = cooldown_excluded_specs(specs)
+      return nil if excluded.empty?
+      "#{excluded.size} version#{"s" if excluded.size > 1} excluded by the cooldown setting; pass `--cooldown 0` to bypass"
+    end
+
+    def cooldown_excluded?(spec)
+      return false unless spec.respond_to?(:created_at) && spec.created_at
+      return false unless spec.respond_to?(:remote) && spec.remote
+      days = spec.remote.effective_cooldown
+      return false if days.nil? || days <= 0
+      (cooldown_now - spec.created_at) < (days * 86_400)
+    end
+
+    def cooldown_now
+      @cooldown_now ||= Time.now
+    end
+
     def filter_remote_specs(specs, package)
       if package.prefer_local?
         local_specs = specs.select {|s| s.is_a?(StubSpecification) }

spec/bundler/resolver/cooldown_spec.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+RSpec.describe Bundler::Resolver do
+  let(:resolver) { described_class.allocate }
+
+  def remote(cooldown:)
+    instance_double(Bundler::Source::Rubygems::Remote, effective_cooldown: cooldown)
+  end
+
+  def spec(created_at:, remote:)
+    Struct.new(:created_at, :remote).new(created_at, remote)
+  end
+
+  describe "#filter_cooldown" do
+    let(:now) { Time.now }
+
+    context "with a 7-day cooldown" do
+      let(:r) { remote(cooldown: 7) }
+
+      it "rejects versions published within the window" do
+        recent = spec(created_at: now - (2 * 86_400), remote: r)
+        old = spec(created_at: now - (30 * 86_400), remote: r)
+
+        expect(resolver.send(:filter_cooldown, [recent, old])).to eq([old])
+      end
+
+      it "keeps versions published exactly at the threshold" do
+        boundary = spec(created_at: now - (7 * 86_400), remote: r)
+
+        expect(resolver.send(:filter_cooldown, [boundary])).to eq([boundary])
+      end
+
+      it "leaves rolling-delay history intact" do
+        # 7-day cooldown with frequent releases must still expose an older candidate.
+        in_cooldown = spec(created_at: now - 86_400, remote: r)
+        also_in_cooldown = spec(created_at: now - (3 * 86_400), remote: r)
+        eligible = spec(created_at: now - (10 * 86_400), remote: r)
+
+        result = resolver.send(:filter_cooldown, [in_cooldown, also_in_cooldown, eligible])
+
+        expect(result).to eq([eligible])
+      end
+    end
+
+    context "when created_at is missing (blank metadata)" do
+      it "keeps the spec regardless of cooldown" do
+        s = spec(created_at: nil, remote: remote(cooldown: 7))
+
+        expect(resolver.send(:filter_cooldown, [s])).to eq([s])
+      end
+    end
+
+    context "when the remote has no cooldown" do
+      it "keeps every spec" do
+        s = spec(created_at: now - 3600, remote: remote(cooldown: nil))
+
+        expect(resolver.send(:filter_cooldown, [s])).to eq([s])
+      end
+    end
+
+    context "when cooldown is 0" do
+      it "keeps every spec (escape hatch)" do
+        s = spec(created_at: now - 3600, remote: remote(cooldown: 0))
+
+        expect(resolver.send(:filter_cooldown, [s])).to eq([s])
+      end
+    end
+
+    context "when the spec does not respond to created_at" do
+      it "keeps the spec" do
+        bare = Struct.new(:version).new("1.0.0")
+
+        expect(resolver.send(:filter_cooldown, [bare])).to eq([bare])
+      end
+    end
+
+    context "when the spec has no remote" do
+      it "keeps the spec" do
+        s = spec(created_at: now - 86_400, remote: nil)
+
+        expect(resolver.send(:filter_cooldown, [s])).to eq([s])
+      end
+    end
+
+    it "returns the same array when input is empty" do
+      expect(resolver.send(:filter_cooldown, [])).to eq([])
+    end
+  end
+
+  describe "#cooldown_hint" do
+    let(:now) { Time.now }
+    let(:r) { remote(cooldown: 7) }
+
+    it "returns nil when no spec is excluded" do
+      expect(resolver.send(:cooldown_hint, [])).to be_nil
+    end
+
+    it "returns nil when every spec is outside the cooldown window" do
+      eligible = [spec(created_at: now - (30 * 86_400), remote: r)]
+
+      expect(resolver.send(:cooldown_hint, eligible)).to be_nil
+    end
+
+    it "mentions the count and the bypass flag for one excluded version" do
+      excluded = [spec(created_at: now - 86_400, remote: r)]
+
+      hint = resolver.send(:cooldown_hint, excluded)
+
+      expect(hint).to match(/1 version excluded by the cooldown setting/)
+      expect(hint).to match(/--cooldown 0/)
+    end
+
+    it "uses plural wording when multiple versions are excluded" do
+      excluded = Array.new(3) { spec(created_at: now - 86_400, remote: r) }
+
+      expect(resolver.send(:cooldown_hint, excluded)).to match(/3 versions excluded/)
+    end
+  end
+end

spec/support/shards.rb

@@ -143,6 +143,7 @@ module Shards
         "spec/bundler/ci_detector_spec.rb",
       ],
       shard_d: [
+        "spec/bundler/resolver/cooldown_spec.rb",
         "spec/commands/outdated_spec.rb",
         "spec/commands/update_spec.rb",
         "spec/lock/lockfile_spec.rb",