fix: list a dead row by the id retry accepts

Two host applications in /tmp/testruby and /tmp/testnode exercised every
unreleased feature as a consumer, and Ruby failed a call TypeScript
answers.

`dead_letters.effects.all` returned Active Record rows, so `row.id` was
the primary key while `retry` reads `effect_id`:

    row.id                 # => 3
    row.effect_id          # => "b6d51a55-…"
    retry(row.id)          # => ActiveRecord::RecordNotFound
    retry(row.effect_id)   # => ok

TypeScript returns `DeadRow` values whose `id` is what `retry` takes, so
`retry(row.id)` has always worked there and the obvious Ruby call
raised. `SolidObjects::DeadRow` now carries the identifier, the kind, the
actor, the status, the attempt count, and the error, and `dead` still
answers the relation for a caller that wants to scope it further.

Wake-up selection rescued every exception, so a `NameError` from an
unloaded model read as "the database could not be reached to select an
adapter" and silently downgraded the process to in-process signalling.
It now rescues database, system call, and IO errors only, and the new
test fails without that with `NameError expected but nothing was
raised`.

`json` 3.0.2 breaks `ActiveSupport::JSON.decode`, and with it every JSON
column this gem writes. The defect is in Active Support and a new Rails
8.1 application resolves that version today, so operations.md names the
combination and the pin.

Validation: bundle exec rake (789 runs, 0 failures), plus a Rails 8.1
host application where all 24 consumer checks pass.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: cardmagic

CHANGELOG.md

@@ -49,6 +49,20 @@
   healthy and found out from a worker crash. A test fails when the list does not
   name a column that a migration after the first adds.
 
+- List a dead effect or broadcast as a `SolidObjects::DeadRow` rather than as
+  an Active Record row. `all` returned rows whose `id` was the primary key while
+  `retry` reads `effect_id` or `broadcast_id`, so the obvious
+  `scope.retry(scope.all.first.id)` raised `ActiveRecord::RecordNotFound`.
+  `DeadRow#id` is now the value `retry` accepts, which is what the TypeScript
+  runtime has always returned. `dead` still answers the relation for a caller
+  that wants to scope it further.
+- Raise a load error rather than report an unreachable database. Wake-up
+  selection rescued every exception, so a `NameError` from an unloaded model
+  read as "the database could not be reached" and downgraded the process to
+  in-process signalling. It now rescues database, system call, and IO errors
+  only.
+- Note that `json` 3.0.2 breaks `ActiveSupport::JSON.decode`, and therefore
+  every JSON column, in [docs/operations.md](docs/operations.md).
 - Retry a dead effect or broadcast. `SolidObjects.dead_letters` keeps its
   message meaning and answers `effects` and `broadcasts`, so the kind rides on
   the receiver. `retry` returns a dead row to pending with a zero attempt count

docs/operations.md

@@ -25,6 +25,22 @@ reports a failed or warned check rather than raising out of the command.
 
 ## Installing and upgrading
 
+Solid Objects keeps actor state, message arguments, results, and the remembered
+idempotency keys in JSON columns. Active Support decodes every one of them, and
+`ActiveSupport::JSON.decode` raises with the `json` gem at 3.0.2:
+
+```
+ArgumentError: wrong number of arguments (given 2, expected 1)
+```
+
+The failure is in Active Support rather than in Solid Objects, and it reaches
+every JSON column in a Rails application. A new Rails 8.1 application resolves
+`json` 3.0.2 today, so pin the 2.x series until Rails ships a fix:
+
+```ruby
+gem "json", "~> 2"
+```
+
 Review [CHANGELOG.md](CHANGELOG.md) for compatibility and deployment-order
 notes, then update the gem:
 

lib/solid_objects.rb

@@ -32,6 +32,7 @@
 require "solid_objects/redrive_task"
 require "solid_objects/redrive_manager"
 require "solid_objects/redrive_runner"
+require "solid_objects/dead_row"
 require "solid_objects/dead_letter_scope"
 require "solid_objects/dead_letter_manager"
 require "solid_objects/message_pruner"
@@ -229,7 +230,7 @@ def resolve_wake_up
       WakeUpAdapters.build(configuration.wake_up_adapter)
     rescue ArgumentError
       raise
-    rescue => error
+    rescue ActiveRecord::ActiveRecordError, SystemCallError, IOError => error
       unreachable_wake_up(error)
     end
 

lib/solid_objects/dead_letter_scope.rb

@@ -27,10 +27,25 @@ def self.for_kind(kind)
       raise ArgumentError, "unknown dead letter kind #{kind.inspect}"
     end
 
-    # @rbs (?authorization_context: untyped) -> ActiveRecord::Relation[untyped]
+    # @rbs (?authorization_context: untyped) -> Array[DeadRow]
     def all(authorization_context: nil)
       authorize!(:inspect, authorization_context:)
-      dead.order(updated_at: :desc, id: :desc)
+      dead.includes(:instance).order(updated_at: :desc, id: :desc).map { |row| dead_row(row) }
+    end
+
+    # @rbs (untyped) -> DeadRow
+    def dead_row(row)
+      DeadRow.new(
+        id: row.public_send(identifier),
+        kind:,
+        actor_type: row.instance.actor_type,
+        actor_id: row.instance.actor_id,
+        status: row.status,
+        attempt_count: row.attempt_count,
+        available_at: row.available_at,
+        failed_at: row.updated_at,
+        error: row.error
+      )
     end
 
     # @rbs (String, ?authorization_context: untyped) -> untyped

lib/solid_objects/dead_row.rb

@@ -0,0 +1,15 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  DeadRow = Data.define(
+    :id,
+    :kind,
+    :actor_type,
+    :actor_id,
+    :status,
+    :attempt_count,
+    :available_at,
+    :failed_at,
+    :error
+  )
+end

sig/generated/lib/solid_objects/dead_letter_scope.rbs

@@ -22,8 +22,11 @@ module SolidObjects
     # @rbs (String) -> DeadLetterScope
     def self.for_kind: (String) -> DeadLetterScope
 
-    # @rbs (?authorization_context: untyped) -> ActiveRecord::Relation[untyped]
-    def all: (?authorization_context: untyped) -> ActiveRecord::Relation[untyped]
+    # @rbs (?authorization_context: untyped) -> Array[DeadRow]
+    def all: (?authorization_context: untyped) -> Array[DeadRow]
+
+    # @rbs (untyped) -> DeadRow
+    def dead_row: (untyped) -> DeadRow
 
     # @rbs (String, ?authorization_context: untyped) -> untyped
     def retry: (String, ?authorization_context: untyped) -> untyped

sig/generated/lib/solid_objects/dead_row.rbs

@@ -0,0 +1,30 @@
+# Generated from lib/solid_objects/dead_row.rb with RBS::Inline
+
+module SolidObjects
+  class DeadRow < Data
+    attr_reader id(): untyped
+
+    attr_reader kind(): untyped
+
+    attr_reader actor_type(): untyped
+
+    attr_reader actor_id(): untyped
+
+    attr_reader status(): untyped
+
+    attr_reader attempt_count(): untyped
+
+    attr_reader available_at(): untyped
+
+    attr_reader failed_at(): untyped
+
+    attr_reader error(): untyped
+
+    def self.new: (untyped id, untyped kind, untyped actor_type, untyped actor_id, untyped status, untyped attempt_count, untyped available_at, untyped failed_at, untyped error) -> instance
+                | (id: untyped, kind: untyped, actor_type: untyped, actor_id: untyped, status: untyped, attempt_count: untyped, available_at: untyped, failed_at: untyped, error: untyped) -> instance
+
+    def self.members: () -> [ :id, :kind, :actor_type, :actor_id, :status, :attempt_count, :available_at, :failed_at, :error ]
+
+    def members: () -> [ :id, :kind, :actor_type, :actor_id, :status, :attempt_count, :available_at, :failed_at, :error ]
+  end
+end

test/integration/dead_letter_scopes_test.rb

@@ -144,11 +144,26 @@ def run
     broadcasts = SolidObjects.dead_letters.broadcasts.all(authorization_context: "operator")
     messages = SolidObjects.dead_letters.all(authorization_context: "operator")
 
-    assert_equal [ effect.effect_id ], effects.map(&:effect_id)
-    assert_equal [ broadcast.broadcast_id ], broadcasts.map(&:broadcast_id)
+    assert_equal [ effect.effect_id ], effects.map(&:id)
+    assert_equal [ broadcast.broadcast_id ], broadcasts.map(&:id)
     assert_equal 1, messages.count
   end
 
+  test "lists a dead row whose id retry accepts" do
+    effect = dead_effect
+
+    row = SolidObjects.dead_letters.effects.all(authorization_context: "operator").sole
+
+    assert_equal effect.effect_id, row.id
+    assert_equal "effect", row.kind
+    assert_equal "dead", row.status
+    assert_equal "scoped-dead-letter-orders", row.actor_type
+    assert_equal "one", row.actor_id
+    SolidObjects.dead_letters.effects.retry(row.id, authorization_context: "operator")
+
+    assert_equal "pending", effect.reload.status
+  end
+
   test "reads only dead rows, not pending ones" do
     dead = dead_effect
     OrderActor.ref("two").async.place
@@ -157,7 +172,7 @@ def run
     effects = SolidObjects.dead_letters.effects.all(authorization_context: "operator")
 
     assert_equal 2, SolidObjects::Effect.count
-    assert_equal [ dead.effect_id ], effects.map(&:effect_id)
+    assert_equal [ dead.effect_id ], effects.map(&:id)
   end
 
   test "refuses an unauthorized caller" do

test/integration/wake_up_selection_test.rb

@@ -260,6 +260,17 @@ def wait(timeout:) = false
     end
   end
 
+  test "a load error is not reported as an unreachable database" do
+    SolidObjects::WakeUpAdapters.singleton_class.alias_method(:built, :build)
+    SolidObjects::WakeUpAdapters.define_singleton_method(:build) do |_name|
+      raise NameError, "uninitialized constant SolidObjects::Record"
+    end
+
+    assert_raises(NameError) { SolidObjects.wake_up }
+  ensure
+    SolidObjects::WakeUpAdapters.singleton_class.alias_method(:build, :built)
+  end
+
   test "the doctor reports the selected adapter" do
     SolidObjects.configuration.authorize_administration = ->(**) { true }
     check = SolidObjects::Doctor.new.call.check(:wake_up)