fix: report a missing migration in the doctor

A parity audit against the TypeScript branch found three gaps.

The doctor passed on an instance table without
`completed_idempotency_keys`, so an operator who installed the gem and
skipped the migration learned about it from a worker crash rather than
from `solid_objects doctor`. The TypeScript doctor verifies its whole
migration list, so it already caught the equivalent. Without the column
in `EXPECTED_COLUMNS` the new test fails with `Expected true to not be
truthy`.

The dead path wrote the instance row for every dead message, including
one that carried no key. `remember_key` now returns first, which matches
what the TypeScript repository does and removes a write per dead
message. The complete and reject paths fold the column into an update
they already perform.

The changelog described neither the migration an application must run
nor `SolidObjects::SchemaBootstrap`.

A test proves two keyed messages in one activation pass are both
remembered, because the executor reads the locked instance row rather
than a claim-time copy.

Validation: bundle exec rake, plus the full suite on PostgreSQL 16,
mysql2, and trilogy. 783 runs, 0 failures on each.

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

Author: cardmagic

CHANGELOG.md

@@ -28,6 +28,16 @@
   `retained_idempotency_keys` bounds the memory and defaults to 64 keys for
   each actor. A lookup by request id cannot make the distinction, because the
   runtime, not the caller, generates a request id and no actor remembers one.
+- Add `db/migrate/20260923000000_add_solid_objects_completed_idempotency_keys.rb`,
+  which adds `instances.completed_idempotency_keys` as `jsonb` on PostgreSQL and
+  `json` elsewhere. An application installs it with
+  `bin/rails solid_objects:install:migrations` and runs it before it upgrades a
+  worker, because the executor writes the column on every finished turn. The
+  doctor now reports the column as missing when it is not installed.
+- Apply migrations through `SolidObjects::SchemaBootstrap`, which reads
+  `db/migrate`. Seven scripts each carried a hand-copied migration list, and
+  three of them applied an incomplete schema. A test fails if any script names a
+  migration class again.
 
 - Retry a dead effect or broadcast. `SolidObjects.dead_letters` keeps its
   message meaning and answers `effects` and `broadcasts`, so the kind rides on

lib/solid_objects/doctor.rb

@@ -65,7 +65,7 @@ def to_s
       instances: %w[
         id actor_type actor_id state state_version next_message_sequence
         activation_owner_id activation_token activation_expires_at
-        activation_generation
+        activation_generation completed_idempotency_keys
       ],
       messages: %w[
         id instance_id delivery_mode arguments sequence attempt_count request_id

lib/solid_objects/executor.rb

@@ -405,7 +405,7 @@ def fail_message(error)
         if error.is_a?(NonRetryableError) ||
             locked_message.attempt_count >= locked_message.max_attempts
           create_dead_letter(message: locked_message, error_details:, now:)
-          instance.update!(completed_idempotency_keys: remembered_keys(instance, locked_message))
+          remember_key(instance, locked_message)
           dead = true
         else
           ReadyMessage.create!(
@@ -475,6 +475,13 @@ def matching_claim!
       raise LostActivation, "message claim changed"
     end
 
+    # @rbs (Instance, Message) -> void
+    def remember_key(instance, message)
+      return unless message.idempotency_key
+
+      instance.update!(completed_idempotency_keys: remembered_keys(instance, message))
+    end
+
     # @rbs (Instance, Message) -> Array[String]
     def remembered_keys(instance, message)
       remembered = Array(instance.completed_idempotency_keys)

sig/generated/lib/solid_objects/executor.rbs

@@ -94,6 +94,9 @@ module SolidObjects
     # @rbs () -> ClaimedMessage
     def matching_claim!: () -> ClaimedMessage
 
+    # @rbs (Instance, Message) -> void
+    def remember_key: (Instance, Message) -> void
+
     # @rbs (Instance, Message) -> Array[String]
     def remembered_keys: (Instance, Message) -> Array[String]
 

test/integration/doctor_test.rb

@@ -113,6 +113,25 @@ class DoctorTest < ActiveSupport::TestCase
     assert_equal :skip, report.check(:sync_round_trip).status
   end
 
+  test "fails when a migration that a runtime path needs is missing" do
+    installed = SolidObjects::Record.connection
+    instances = SolidObjects.table_name(:instances)
+    connection = Object.new
+    connection.define_singleton_method(:data_sources) { installed.data_sources }
+    connection.define_singleton_method(:columns) do |table|
+      columns = installed.columns(table)
+      next columns unless table == instances
+
+      columns.reject { |column| column.name == "completed_idempotency_keys" }
+    end
+
+    report = SolidObjects::Doctor.new(connection:).call
+
+    refute report.healthy?
+    assert_equal :fail, report.check(:schema).status
+    assert_match(/completed_idempotency_keys/, report.check(:schema).message)
+  end
+
   test "reports live runtime roles" do
     now = SolidObjects.database_adapter.database_now
     SolidObjects::Process.create!(

test/integration/result_lookup_test.rb

@@ -283,6 +283,17 @@ def reject_checkout
     assert_equal 3, SolidObjects::Instance.sole.completed_idempotency_keys.size
   end
 
+  test "remembers every key of one activation pass" do
+    reference = CartActor.ref("alice")
+    reference.async(idempotency_key: "first").checkout(order_id: 1)
+    reference.async(idempotency_key: "second").checkout(order_id: 2)
+    run_actors
+    SolidObjects::Message.delete_all
+
+    assert_raises(SolidObjects::MessagePruned) { reference.find_by(idempotency_key: "first") }
+    assert_raises(SolidObjects::MessagePruned) { reference.find_by(idempotency_key: "second") }
+  end
+
   test "remembers nothing for a message that carried no key" do
     reference = CartActor.ref("alice")
     reference.async.checkout(order_id: 1)