docs: describe the result lookup

The branch added an API and documented none of it. The changelog, the
architecture guide, the pruning note, and the roadmap entry the issue
quotes now say what exists, including that a result is stored for sync
delivery only and that a pruned message still answers nil.

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

Author: cardmagic

CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## Unreleased
 
+- Find a message whose reference a caller lost.
+  `SolidObjects.client.find_by(request_id:)` answers a request id, which is
+  unique across the table, and `reference.find_by(idempotency_key:)` answers a
+  key, which is unique per instance, so the receiver supplies the scope the key
+  needs. Naming neither key, naming both, or naming an idempotency key without a
+  reference raises `ArgumentError`.
+- Authorize every lookup with the 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 a lookup cannot be used to ask whether a request
+  id exists.
+- Add `MessageReference#outcome`, which reports the status, the result, the
+  persisted error, the rejection, and the attempt count, so a terminal failure
+  answers as well as a success. A result is stored for `sync` delivery only, so
+  an asynchronous message reports its status and error and no result.
+
 - 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/architecture.md

@@ -424,6 +424,16 @@ outer commit, and callers timing out on work they indirectly block.
 waiting and immediately returns a `MessageReference`. Runtime workers process
 it normally.
 
+A caller that loses that reference rebuilds one. `SolidObjects.client.find_by`
+answers a request id, which is unique across the table, and
+`reference.find_by` answers an idempotency key, which is unique per instance.
+Each lookup runs the authorization hook the original call ran, against the
+stored operation and arguments, and answers `nil` for an absent row, an
+unregistered actor, and a refused caller alike, so it 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. A result is
+stored for `sync` delivery only.
+
 An executing caller receives an inline after-commit callback error even though
 the turn committed. An independently waiting caller observes the durable
 result and may return before that callback raises in the worker. Completed
@@ -867,7 +877,7 @@ All backends use unique identity and sequence constraints, short transactions, a
 12. **How are leases renewed?** Conditional database update by instance, owner, generation, and unexpired lease.
 13. **How does graceful shutdown work?** Stop claims, finish current turn within timeout, release cached leases, stop heartbeat, mark process stopped.
 14. **How does synchronous invocation work across processes?** The caller first tries to claim and execute the actor locally. If another process owns it, a wake-up adapter prompts a durable result query and bounded polling remains the fallback.
-15. **What happens after caller timeout?** A committed message continues and its eventual result can be recovered with the timeout's authorized message reference. An enqueue timeout leaves no message. Running Ruby code is not preempted.
+15. **What happens after caller timeout?** A committed message continues and its eventual result can be recovered with the timeout's authorized message reference, or with `find_by` from the request id or the idempotency key when that reference is gone. An enqueue timeout leaves no message. Running Ruby code is not preempted.
 16. **How are results cleaned up?** `prune_messages` deletes eligible terminal history in bounded batches after global or per-actor retention. It previews by default and preserves live work, dead letters, retry links, and unfinished outboxes.
 17. **How are large mailboxes managed?** The implemented controls are the per-actor mailbox cap, payload caps, and fair activation yields; rate and global admission controls remain roadmap work.
 18. **How are completed messages pruned?** Operators schedule the dry-run-reviewed `prune_messages --execute` command. Solid Objects does not run deletion automatically.

docs/operations.md

@@ -543,6 +543,11 @@ broadcasts, and other message-owned rows. Choose a cutoff longer than every
 `sync` timeout because a caller whose result row disappears can no longer
 observe it.
 
+`find_by` reads the same rows, so a lookup answers only while the message it
+names survives retention. A pruned message and one that never existed both
+answer `nil` today, which is why a cutoff longer than the window in which a
+caller may retry matters.
+
 Actor expiration is disabled by default. `prune_instances` considers only
 actor types listed in `instance_retention_by_actor_type`, excludes active or
 paused actors, and preserves ready/claimed mailbox work, scheduled reminders,

docs/roadmap.md

@@ -197,7 +197,9 @@
 
 ## Next milestones
 
-1. Add result lookup by request ID and broader deadlock retry classification.
+1. Broaden deadlock retry classification. Result lookup by request ID and by
+   idempotency key is implemented; what remains is telling a pruned message
+   from one that never existed.
 2. Add Turbo append intents.
 3. Add distributed rate limits, global admission hooks, and cache-capacity
    eviction.