feat: find a message by request id or idempotency key

[cardmagic]

Ports cardmagic/solid-objects-ruby#79, which works on #74 there.

Why

A caller reads a result through a MessageReference, and a caller who loses
that 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

await runtime.findBy({ requestId, authorizationContext })
await reference.findBy({ idempotencyKey: "checkout-7f3a", authorizationContext })
await runtime.findBy({ reference, idempotencyKey: "checkout-7f3a" })

Lookup	Uniqueness	Receiver
requestId	unique across the table	runtime
idempotencyKey	unique per actor	a reference

Naming neither key, naming both, or naming an idempotency key without a
reference each throw a TypeError.

Authorization

A request id is not a capability, so every lookup runs the same message or 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 undefined. A lookup that threw where it was refused
and returned undefined where it was absent would be a way to ask whether a
request id exists.

Outcome

await found.outcome()
// { status: "dead", result: undefined,
//   error: { name: "Error", message: "payment declined" },
//   rejection: undefined, attempts: 1 }

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.

Schema version 12

This runtime needed the index the issue asks for. messages constrained only
UNIQUE (actor_type, actor_id, request_id), which cannot serve a lookup that
names the request id alone. Version 12 adds a unique index on request_id.
Every value is a fresh randomUUID(), so existing rows cannot collide.

Ruby needed no equivalent: its first migration has always carried
index :request_id, unique: true.

Two differences from the Ruby port, both recorded in docs/parity.md

This runtime stores a result for every completed message, so a lookup
answers one for asynchronous work. Ruby serializes a result only when
delivery_mode == "sync", so a lookup there answers the status, the error, and
the rejection, but not the result of async work. A test pins the behaviour on
each side rather than leaving it to be discovered.

The index above, which Ruby did not need.

Tests

test/result-lookup.test.ts, 25 tests, each watched failing first:

lookup by request id and by idempotency key, the runtime 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 its result, an unknown request id and an
unknown key, all three TypeError cases, a refusing runtime receiving
undefined that absence cannot be told from, authorization against the stored
operation and arguments, the query hook for a getter, a key scoped to its own
actor, 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 undefined, the
bound holding at three keys, and a keyless message remembering nothing. Without
the raise they failed with expected promise to reject; without the gate the
refused caller received MessagePruned; without the bound the memory held
[ 'key-0', 'key-1', 'key-2', …(2) ].

test/cloudflare/recovery.test.ts repeats the pruned case, the bound, and the
unsupported request id lookup against a real Durable Object.

Validation

Gate	Result
vitest run	515 passed, 32 skipped
PostgreSQL 18	52 passed
MySQL 8.4	39 passed, 7 skipped
Cloudflare Workers	56 passed
Prettier, 3 check scripts, tsc	clean
pnpm run build	clean

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.

The repository 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.

await reference.findBy({ idempotencyKey: "checkout-7f3a" })
// MessagePruned: the message for idempotency key "checkout-7f3a" was pruned

await reference.findBy({ idempotencyKey: "never-sent" })
// undefined

retainedIdempotencyKeys 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 findBy({ requestId }) answers undefined in
both cases.

Schema version 13 adds instances.completed_idempotency_keys.

The Durable Objects backend was left red

The previous commit added messageOutcome and findBy to ActorRuntime and
implemented neither on CloudflareRuntime, so three CI jobs failed on one
error:

Class 'CloudflareRuntime' incorrectly implements interface 'ActorRuntime'.
  Type 'CloudflareRuntime' is missing the following properties from type
  'ActorRuntime': messageOutcome, findBy

Both now work there, including the remembered keys, which live in the same
instance record. A Durable Object indexes only its own messages, so
findBy({ requestId }) without a reference raises UnsupportedCapability;
every other form works. The portable runtime contract now covers findBy and
outcome(), so both backends answer the same test.

The parity row that still called result lookup Planned now reads Native.

Four hand-copied schema version lists

The doctor and three tests each carried 1, 2, ... 12 by hand, and all four
broke on version 13. They read SCHEMA_VERSIONS from src/schema.ts instead.

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.

Validation: JavaScript suite 525 passed / 32 skipped, then the focused suite
34 passed after adding the legacy regression; Cloudflare suite 59 passed.
Main, examples, Cloudflare, and all build TypeScript configurations pass;
parameter, documentation, browser-import, and changed-file formatting checks pass.

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge; the latest conditional refactor preserves lookup behavior and no outstanding findings remain.

Summary

This PR adds authorized message recovery by request ID or actor-scoped idempotency key across the SQL and Cloudflare runtimes.

• Adds findBy() and atomic outcome() APIs.
• Preserves authorization using the stored operation and original arguments.
• Distinguishes retained-but-pruned idempotency keys from keys that never existed.
• Bounds retained key history by count and serialized size.
• Adds schema support for globally unique request IDs and remembered idempotency keys.
• Implements the portable contract for Durable Objects, with documented capability differences.
• The latest change cleanly flattens the remaining nested lookup conditional without changing its behavior.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[findBy request] --> B{Lookup key}
  B -->|Request ID| C[Find globally or within named Durable Object]
  B -->|Idempotency key| D[Find within actor scope]
  C --> E{Live message found?}
  D --> E
  E -->|Yes| F[Authorize stored operation and arguments]
  E -->|No, remembered key| G[Authorize remembered operation and arguments]
  E -->|No history| H[Return undefined]
  F -->|Allowed| I[Return MessageReference]
  F -->|Denied| H
  G -->|Allowed| J[Throw MessagePruned]
  G -->|Denied or legacy arguments absent| H
  I --> K[outcome reads one stored snapshot]

Loading

_{Reviews (5) · Last reviewed commit: "refactor: flatten Cloudflare lookup guar..."}

[cardmagic]

@greptileai Please review the latest commit 3293548. All outstanding findings have been addressed, including original-argument authorization for pruned lookups on both backends.

[cardmagic]

@greptileai The remaining nested lookup conditional is flattened in 0fbdec6. All 59 Cloudflare tests and the Cloudflare TypeScript check pass. Please review the latest commit.