feat: find a message by request id or idempotency key

[cardmagic]

Works on #74.

Why

A caller reads a result through a MessageReference, and Client#wait refuses
anything less than the whole reference. The check is right; the problem is that
a caller who loses the reference cannot rebuild one. A web request that timed
out, a process that restarted, or a retry that arrived on another node knows its
own request id or its own idempotency key, and neither was enough.

The enqueue path already deduplicates by idempotency key, so the row could be
found. Nothing public could find it.

The receiver carries the scope

SolidObjects.client.find_by(request_id: "b1a1c0de-...", authorization_context: current_user)
CartActor.ref("alice").find_by(idempotency_key: "checkout-7f3a", authorization_context: current_user)
SolidObjects.client.find_by(reference: CartActor.ref("alice"), idempotency_key: "checkout-7f3a")

Lookup	Uniqueness	Receiver
request_id	unique across the table	SolidObjects.client
idempotency_key	unique per instance	Reference

A caller cannot express a lookup the indexes cannot serve, because the receiver
supplies the scope the key needs. Naming neither key, naming both, or naming an
idempotency key without a reference each raise ArgumentError. An unknown
keyword raises from Ruby itself.

Authorization

A request id is not a capability, so every lookup runs the same
authorize_message or authorize_query hook the original call ran, against the
stored operation and arguments.

An absent row, an actor this process no longer registers, and a caller the
policy refuses all return nil. That is deliberate: a lookup that raised where
it was refused and returned nil where it was absent would be a way to ask
whether a request id exists.

Outcome

reference.outcome
# => #<data SolidObjects::Outcome status: "dead",
#      result: nil,
#      error: #<data SolidObjects::ErrorRecord class_name: "Payments::Declined", ...>,
#      rejection: nil,
#      attempts: 5>

A lookup that only answered for successes would not be usable for recovery, so
outcome carries the persisted error for a dead message and the rejection for a
rejected one, beside the status and the attempt count.

Two things the issue assumes that the code does not

The request_id index already exists. The issue asks for a migration adding
idx_so_messages_request_id. db/migrate/20260805000000 line 122 already
declares index :request_id, unique: true, name: "idx_so_messages_request". The
lookup is an index hit today and this branch adds no migration.

An async enqueue stores no result. Executor#complete serializes the result
only when delivery_mode == "sync"; an async message stores nil on purpose.
So the recovery example in the issue finds its message and reports completed,
and reads nil for the result. That is already true of MessageReference#result
and is not introduced here. find_by answers status, error, rejection, and
attempts for any message, and a result for one enqueued with sync. A test
pins both halves, so the boundary is recorded rather than discovered later.

Making async results durable is a separate decision about storage and retention,
and it belongs in its own change.

Tests

test/integration/result_lookup_test.rb, 24 tests, each watched failing first
with undefined method 'find_by':

lookup by request id and by idempotency key, the client and the reference
agreeing, a message that has not run, a dead message with its error and attempt
count, a rejected message with its rejection, a completed outcome with its
result, an async message reporting no result, an unknown key and an unknown
request id, all three ArgumentError cases, an unknown keyword, an unauthorized
caller receiving nil that absence cannot be told from, authorization against
the stored operation and arguments, the query hook for a query, a key scoped to
its own instance, and a rebuilt reference that waits and sees the commit.

The pruned tests: a pruned key raising for a completed, a rejected, and a dead
message, the error naming its key, a refused caller reading nil, the bound
holding at three keys, and a keyless message remembering nothing. Without the
raise they failed with SolidObjects::MessagePruned expected but nothing was raised; without the gate the refused caller received MessagePruned; without
the bound key-0 was still remembered.

Validation

bundle exec rake passes: 781 runs, 0 failures, 39 skips, with Standard,
RuboCop, RBS, Steep, and Brakeman clean.

Every backend runs the whole suite: SQLite, PostgreSQL 16, MySQL through
mysql2, and MySQL through trilogy, each 780 runs with 0 failures.

A pruned message and one that never existed

The issue also asks that the two be told apart. Orleans answers this in grain
state: a grain keeps its deduplication history with the grain, not in a separate
tombstone store. An actor now does the same, so neither shape the earlier draft
weighed is needed.

The executor already writes the instance row in the transaction that completes,
rejects, or kills a turn, so the remembered keys ride on a write that happens
anyway. No second store, no second write, and no separate retention.

reference.find_by(idempotency_key: "checkout-7f3a")
# SolidObjects::MessagePruned: the message for idempotency key
# "checkout-7f3a" was pruned

reference.find_by(idempotency_key: "never-sent")
# => nil

retained_idempotency_keys bounds the memory and defaults to 64 keys for each
actor. A key the actor already remembers moves to the end rather than repeating,
and a message that carried no key remembers nothing.

Each remembered key retains the original operation and arguments. Pruned
lookups apply the same message or query authorization policy as live lookups.
Arguments count toward the existing serialized byte limit. Older entries
without arguments return absence because authorization cannot be reproduced.
A denied caller cannot distinguish a pruned key from an unused key.

Only a key lookup can make the distinction. The runtime generates a request id,
so no actor remembers one, and find_by(request_id:) answers nil in both
cases. A caller that must tell them apart sends its own idempotency key.

db/migrate/20260923000000_add_solid_objects_completed_idempotency_keys.rb adds
the column as jsonb on PostgreSQL and json elsewhere.

Seven hand-copied migration lists

Three of them ran migrations against a full schema, and all three broke on the
new column:

undefined method `completed_idempotency_keys' for an instance of
SolidObjects::Instance

SolidObjects::SchemaBootstrap reads db/migrate instead, and
test/unit/migration_bootstrap_test.rb fails if any script names a migration
class again. load_contract_test.rb records why the new file is not loaded by
requiring the gem.

Review fixes and regression evidence

Argument-dependent authorization is covered by a regression that first failed
with MessagePruned: the message for idempotency key "protected" was pruned
for a denied caller. The fixed test verifies absence for that caller and
MessagePruned for an authorized caller. Legacy history without arguments
also returns absence. Serialized size tests account for the retained arguments.

The single-use bounded, remembered_message, and dead_row helpers are
inlined and generated RBS signatures updated. bundle exec rake passes:
796 runs, 0 failures, 0 errors, 39 skips; Standard, RuboCop, RBS validation,
Steep, and Brakeman pass. The focused suite including the additional legacy
regression passes 36 tests with 0 skips.

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge; the latest revision resolves the remaining conditional-structure concern without changing behavior.

Summary

The latest revision replaces the remaining nested optional history update with a Standard-compatible single-line conditional modifier.

• Preserves idempotency-key history only when the terminal message has a key.
• Removes the nested if identified by the previous review.
• Introduces no new behavioral changes or outstanding findings.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Failure[Terminal message failure] --> HasKey{Idempotency key?}
  HasKey -->|Yes| Remember[Update retained key history]
  HasKey -->|No| Skip[Skip history update]
  Remember --> Dead[Mark message dead]
  Skip --> Dead

Loading

_{Reviews (6) · Last reviewed commit: "refactor: simplify optional key persiste..."}

[cardmagic]

@greptileai Please review the latest commit b60dec5. All outstanding findings are addressed; single-use helpers are inlined and pruned lookups now retain original authorization arguments within the byte bound.

[cardmagic]

@greptileai Please review 32cba11. Both remaining single-use wrappers are inlined and their generated signatures removed. Focused tests, formatting, lint, RBS validation, and Steep pass.

[cardmagic]

@greptileai Please review 4314869. The optional history update now uses a single-line conditional modifier, satisfying both the remaining finding and Standard Ruby. Lookup tests and both style checks pass.