feat: find a message by request id or idempotency key

A caller that lost its `MessageReference` had no way to rebuild one, so
a web request that timed out, a process that restarted, or a retry that
arrived on another node could not read what the first attempt produced.
The enqueue path already deduplicates by idempotency key, so the row
could be found. Nothing public could find it.

`find_by` is shaped like `ActiveRecord::Base.find_by`, and the receiver
carries the scope the key needs:

    SolidObjects.client.find_by(request_id: id)
    CartActor.ref("alice").find_by(idempotency_key: key)

A request id is unique across the table, so the client answers it. An
idempotency key is unique per instance, so a reference answers it. A
caller cannot write a lookup the indexes cannot serve.

Every lookup runs the same authorization hook the original call ran,
against the stored operation and arguments, because a request id is not
a capability. An absent row, an actor this process no longer registers,
and a caller the policy refuses all return `nil`, so the lookup cannot
be used to ask whether a request id exists.

`MessageReference#outcome` reports the status, the result, the
persisted error, the rejection, and the attempt count, so a terminal
failure answers as well as a success.

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

Author: cardmagic

lib/solid_objects.rb

@@ -26,6 +26,7 @@
 require "solid_objects/application_write_guard"
 require "solid_objects/actor"
 require "solid_objects/reference"
+require "solid_objects/outcome"
 require "solid_objects/message_reference"
 require "solid_objects/administration_audit"
 require "solid_objects/redrive_task"

lib/solid_objects/client.rb

@@ -94,6 +94,21 @@ def wait(message_reference, timeout:, authorization_context: nil)
       raise SyncDiagnostics.new.database_contention_for(message_reference, timeout:)
     end
 
+    # @rbs (?reference: Reference?, ?request_id: String?, ?idempotency_key: String?, ?authorization_context: untyped) -> MessageReference?
+    def find_by(reference: nil, request_id: nil, idempotency_key: nil, authorization_context: nil)
+      unless [ request_id, idempotency_key ].compact.one?
+        raise ArgumentError, "find_by expects exactly one of request_id: or idempotency_key:"
+      end
+      if idempotency_key && reference.nil?
+        raise ArgumentError, "find_by with idempotency_key: requires reference:"
+      end
+
+      readable_message(
+        looked_up_message(reference:, request_id:, idempotency_key:),
+        authorization_context:
+      )
+    end
+
     # @rbs (Reference, ?authorization_context: untyped) -> StateSnapshot
     def snapshot(reference, authorization_context: nil)
       SolidObjects.registry.fetch(reference.actor_type)
@@ -164,6 +179,50 @@ def enqueue_sync(reference:, operation:, arguments:, idempotency_key:, timeout:)
       )
     end
 
+    # @rbs (reference: Reference?, request_id: String?, idempotency_key: String?) -> Message?
+    def looked_up_message(reference:, request_id:, idempotency_key:)
+      return Message.uncached { Message.find_by(request_id:) } if request_id
+
+      instance = Instance.find_by(
+        actor_type: reference.actor_type,
+        actor_id: reference.actor_id
+      )
+      return nil unless instance
+
+      Message.uncached { Message.find_by(instance_id: instance.id, idempotency_key:) }
+    end
+
+    # @rbs (Message?, authorization_context: untyped) -> MessageReference?
+    def readable_message(message, authorization_context:)
+      return nil unless message
+      return nil unless authorized_to_read?(message, authorization_context:)
+
+      MessageReference.from_message(message)
+    end
+
+    # @rbs (Message, authorization_context: untyped) -> bool
+    def authorized_to_read?(message, authorization_context:)
+      actor_class = SolidObjects.registry.fetch(message.actor_type)
+      operation = message.operation.to_sym
+      query = actor_class.definition.queries.key?(operation)
+      return false unless query || actor_class.definition.messages.key?(operation)
+
+      hook = if query
+        SolidObjects.configuration.authorize_query
+      else
+        SolidObjects.configuration.authorize_message
+      end
+      hook.call(
+        actor_type: message.actor_type,
+        actor_id: message.actor_id,
+        operation: message.operation.to_s,
+        arguments: message.arguments,
+        authorization_context:
+      )
+    rescue UnknownActor
+      false
+    end
+
     # @rbs (MessageReference, Message) -> void
     def validate_message_reference!(message_reference, message)
       valid = message_reference.request_id == message.request_id &&

lib/solid_objects/message_reference.rb

@@ -52,6 +52,20 @@ def result
       Message.uncached { Message.find(id).result }
     end
 
+    # @rbs () -> Outcome
+    def outcome
+      Message.uncached do
+        message = Message.find(id)
+        Outcome.new(
+          status: status,
+          result: message.result,
+          error: ErrorRecord.from(message.error),
+          rejection: RejectionRecord.from(message.rejection),
+          attempts: message.attempt_count
+        )
+      end
+    end
+
     # @rbs (?timeout: Numeric, ?authorization_context: untyped) -> untyped
     def wait(timeout: 5.seconds, authorization_context: nil)
       SolidObjects.client.wait(

lib/solid_objects/outcome.rb

@@ -0,0 +1,31 @@
+# rbs_inline: enabled
+
+module SolidObjects
+  ErrorRecord = Data.define(:class_name, :message, :backtrace) do
+    # @rbs (Hash[String, untyped]?) -> ErrorRecord?
+    def self.from(error)
+      return nil if error.blank?
+
+      new(
+        class_name: error["class"],
+        message: error["message"],
+        backtrace: Array(error["backtrace"]).freeze
+      )
+    end
+  end
+
+  RejectionRecord = Data.define(:code, :message, :details) do
+    # @rbs (Hash[String, untyped]?) -> RejectionRecord?
+    def self.from(rejection)
+      return nil if rejection.blank?
+
+      new(
+        code: rejection["code"],
+        message: rejection["message"],
+        details: Serialization.readonly_copy(rejection["details"])
+      )
+    end
+  end
+
+  Outcome = Data.define(:status, :result, :error, :rejection, :attempts)
+end

lib/solid_objects/reference.rb

@@ -67,6 +67,11 @@ def destroy(authorization_context: nil)
       SolidObjects.client.destroy(self, authorization_context:)
     end
 
+    # @rbs (idempotency_key: String, ?authorization_context: untyped) -> MessageReference?
+    def find_by(idempotency_key:, authorization_context: nil)
+      SolidObjects.client.find_by(reference: self, idempotency_key:, authorization_context:)
+    end
+
     # @rbs (?authorization_context: untyped) -> StateSnapshot
     def snapshot(authorization_context: nil)
       SolidObjects.client.snapshot(self, authorization_context:)

sig/generated/lib/solid_objects/client.rbs

@@ -16,6 +16,9 @@ module SolidObjects
     # @rbs (MessageReference, timeout: Numeric, ?authorization_context: untyped) -> untyped
     def wait: (MessageReference, timeout: Numeric, ?authorization_context: untyped) -> untyped
 
+    # @rbs (?reference: Reference?, ?request_id: String?, ?idempotency_key: String?, ?authorization_context: untyped) -> MessageReference?
+    def find_by: (?reference: Reference?, ?request_id: String?, ?idempotency_key: String?, ?authorization_context: untyped) -> MessageReference?
+
     # @rbs (Reference, ?authorization_context: untyped) -> StateSnapshot
     def snapshot: (Reference, ?authorization_context: untyped) -> StateSnapshot
 
@@ -29,6 +32,15 @@ module SolidObjects
     # @rbs (reference: Reference, operation: Symbol | String, arguments: Hash[Symbol | String, untyped], idempotency_key: String?, timeout: Numeric) -> MessageReference
     def enqueue_sync: (reference: Reference, operation: Symbol | String, arguments: Hash[Symbol | String, untyped], idempotency_key: String?, timeout: Numeric) -> MessageReference
 
+    # @rbs (reference: Reference?, request_id: String?, idempotency_key: String?) -> Message?
+    def looked_up_message: (reference: Reference?, request_id: String?, idempotency_key: String?) -> Message?
+
+    # @rbs (Message?, authorization_context: untyped) -> MessageReference?
+    def readable_message: (Message?, authorization_context: untyped) -> MessageReference?
+
+    # @rbs (Message, authorization_context: untyped) -> bool
+    def authorized_to_read?: (Message, authorization_context: untyped) -> bool
+
     # @rbs (MessageReference, Message) -> void
     def validate_message_reference!: (MessageReference, Message) -> void
 

sig/generated/lib/solid_objects/message_reference.rbs

@@ -34,6 +34,9 @@ module SolidObjects
     # @rbs () -> untyped
     def result: () -> untyped
 
+    # @rbs () -> Outcome
+    def outcome: () -> Outcome
+
     # @rbs (?timeout: Numeric, ?authorization_context: untyped) -> untyped
     def wait: (?timeout: Numeric, ?authorization_context: untyped) -> untyped
   end

sig/generated/lib/solid_objects/outcome.rbs

@@ -0,0 +1,52 @@
+# Generated from lib/solid_objects/outcome.rb with RBS::Inline
+
+module SolidObjects
+  class ErrorRecord < Data
+    attr_reader class_name(): untyped
+
+    attr_reader message(): untyped
+
+    attr_reader backtrace(): untyped
+
+    def self.new: (untyped class_name, untyped message, untyped backtrace) -> instance
+                | (class_name: untyped, message: untyped, backtrace: untyped) -> instance
+
+    def self.members: () -> [ :class_name, :message, :backtrace ]
+
+    def members: () -> [ :class_name, :message, :backtrace ]
+  end
+
+  class RejectionRecord < Data
+    attr_reader code(): untyped
+
+    attr_reader message(): untyped
+
+    attr_reader details(): untyped
+
+    def self.new: (untyped code, untyped message, untyped details) -> instance
+                | (code: untyped, message: untyped, details: untyped) -> instance
+
+    def self.members: () -> [ :code, :message, :details ]
+
+    def members: () -> [ :code, :message, :details ]
+  end
+
+  class Outcome < Data
+    attr_reader status(): untyped
+
+    attr_reader result(): untyped
+
+    attr_reader error(): untyped
+
+    attr_reader rejection(): untyped
+
+    attr_reader attempts(): untyped
+
+    def self.new: (untyped status, untyped result, untyped error, untyped rejection, untyped attempts) -> instance
+                | (status: untyped, result: untyped, error: untyped, rejection: untyped, attempts: untyped) -> instance
+
+    def self.members: () -> [ :status, :result, :error, :rejection, :attempts ]
+
+    def members: () -> [ :status, :result, :error, :rejection, :attempts ]
+  end
+end

sig/generated/lib/solid_objects/reference.rbs

@@ -2,10 +2,10 @@
 
 module SolidObjects
   class Reference
-    @actor_type: String
-
     @actor_id: String
 
+    @actor_type: String
+
     attr_reader actor_type: untyped
 
     attr_reader actor_id: untyped
@@ -22,6 +22,9 @@ module SolidObjects
     # @rbs (?authorization_context: untyped) -> bool
     def destroy: (?authorization_context: untyped) -> bool
 
+    # @rbs (idempotency_key: String, ?authorization_context: untyped) -> MessageReference?
+    def find_by: (idempotency_key: String, ?authorization_context: untyped) -> MessageReference?
+
     # @rbs (?authorization_context: untyped) -> StateSnapshot
     def snapshot: (?authorization_context: untyped) -> StateSnapshot