Unify the error for jobs whose class no longer resolves

Both a worker picking up a job whose class is gone and the concurrency
maintenance releasing a blocked one now fail the job with
SolidQueue::Job::ClassMissingError. Before, the first case surfaced as
whatever NameError Active Job's deserialization raised, and the second
one, just added, had its own BlockedExecution::JobClassMissingError, so
the same user mistake read differently in failed jobs depending on
where it was caught. The error subclasses NameError, which is what
resolving the class raises, so anything matching on NameError still
matches.

Also surface the new failed: key in the release_blocked log line,
document the behaviour in the README's concurrency controls section,
and add the magic comment to the new test file.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CACej2M9mLVDwpE3Bk8V41

Author: rosa

README.md

@@ -555,6 +555,8 @@ It's important to note that after one or more candidate jobs are unblocked (eith
 
 When using `discard` as the behaviour to handle conflicts, you might have jobs discarded for until the `duration` interval if something happens and a running job fails to release the semaphore.
 
+If a job's class no longer exists by the time its concurrency controls are checked—say it was renamed or removed in a deploy while jobs referencing it were still in the queue—the job is marked as failed with a `SolidQueue::Job::ClassMissingError`, so it shows up in [failed jobs](#failed-jobs-and-retries), where it can be retried once the class is back, or discarded. Jobs with a missing class picked up by a worker fail with the same error.
+
 
 For example:
 ```ruby

app/models/solid_queue/blocked_execution.rb

@@ -2,8 +2,6 @@
 
 module SolidQueue
   class BlockedExecution < Execution
-    class JobClassMissingError < RuntimeError; end
-
     assumes_attributes_from_job :concurrency_key
     before_create :set_expires_at
 
@@ -49,12 +47,9 @@ def release
       SolidQueue.instrument(:release_blocked, job_id: job.id, concurrency_key: concurrency_key, released: false) do |payload|
         transaction do
           if job.job_class.nil?
-            # The job's class no longer resolves (renamed/removed between deploys).
-            # Mark the job as failed so it surfaces in Mission Control (where it can
-            # be retried once the class is restored, or discarded), and destroy the
-            # orphan row so the dispatcher stops retrying it forever.
-            job.failed_with(JobClassMissingError.new("Job class #{job.class_name.inspect} could not be resolved"))
+            job.failed_with(Job::ClassMissingError.for(job))
             destroy!
+
             payload[:failed] = true
           elsif acquire_concurrency_lock
             promote_to_ready

app/models/solid_queue/claimed_execution.rb

@@ -115,6 +115,8 @@ def finalizing
       end
 
       def execute
+        raise Job::ClassMissingError.for(job) if job.job_class.nil?
+
         ActiveJob::Base.execute(job.arguments.merge("provider_job_id" => job.id))
         Result.new(true, nil)
       rescue Exception => e

app/models/solid_queue/job.rb

@@ -4,6 +4,15 @@ module SolidQueue
   class Job < Record
     class EnqueueError < StandardError; end
 
+    # Raised when a job's class can't be resolved anymore, typically because it
+    # was renamed or removed in a deploy while jobs referencing it were in
+    # flight. It subclasses NameError, which is what resolving the class raises.
+    class ClassMissingError < NameError
+      def self.for(job)
+        new("Job class #{job.class_name.inspect} could not be resolved")
+      end
+    end
+
     include Executable, Clearable, Recurrable, Batchable
 
     serialize :arguments, coder: JSON

lib/solid_queue/log_subscriber.rb

@@ -59,7 +59,7 @@ def release_many_blocked(event)
   end
 
   def release_blocked(event)
-    debug formatted_event(event, action: "Release blocked job", **event.payload.slice(:job_id, :concurrency_key, :released))
+    debug formatted_event(event, action: "Release blocked job", **event.payload.slice(:job_id, :concurrency_key, :released, :failed))
   end
 
   def enqueue_recurring_task(event)

test/models/solid_queue/blocked_execution_test.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "test_helper"
 
 class SolidQueue::BlockedExecutionTest < ActiveSupport::TestCase
@@ -44,7 +46,7 @@ def perform(job_result)
 
     failed = SolidQueue::FailedExecution.find_by(job_id: blocked_job.id)
     assert failed, "expected a failed execution to be created for the orphan"
-    assert_equal "SolidQueue::BlockedExecution::JobClassMissingError", failed.exception_class
+    assert_equal "SolidQueue::Job::ClassMissingError", failed.exception_class
     assert_match "GoneJob", failed.message
   end
 end

test/models/solid_queue/claimed_execution_test.rb

@@ -146,7 +146,7 @@ class SolidQueue::ClaimedExecutionTest < ActiveSupport::TestCase
     claimed_execution = claim_job(job)
 
     assert_difference -> { SolidQueue::ClaimedExecution.count } => -1, -> { SolidQueue::FailedExecution.count } => 1 do
-      assert_raises NameError do
+      assert_raises SolidQueue::Job::ClassMissingError do
         claimed_execution.perform
       end
     end
@@ -159,7 +159,7 @@ class SolidQueue::ClaimedExecutionTest < ActiveSupport::TestCase
     claimed_execution = claim_job(job)
 
     assert_difference -> { SolidQueue::ClaimedExecution.count } => -1, -> { SolidQueue::FailedExecution.count } => 1 do
-      assert_raises NameError do
+      assert_raises SolidQueue::Job::ClassMissingError do
         claimed_execution.perform
       end
     end