API idempotency

Send caller-owned mutation identity in the HTTP header:

Idempotency-Key: reservation:res_42:confirmation-email

The request JSON does not accept idempotencyKey. A reservation is scoped by project, canonical tool, user, caller-supplied connection (or the default sentinel), catalog major, and key. Repeating the same key and request within that complete scope replays the associated execution; changing the key creates a distinct mutation attempt.

After the executor accepts an identical replay, subsequent execution GET and list records expose replayed: true. The replay reuses the original execution ID. The field is absent until an actual replay is observed; absence does not mean the original request lacked an idempotency key.

Good keys identify the business action, not a transport attempt:

order:<order-id>:refund:<refund-revision>
reservation:<reservation-id>:confirmation-email
model-turn:<turn-id>:tool:<tool-call-id>

Keep the key stable when retrying a transport interruption or timeout whose execution outcome is unknown. Fetch the original execution first because the provider may have completed the side effect. A terminal failed execution is also retained and replayed under its key, even when its normalized error is retryable; starting a new provider attempt requires a new key.

Idempotency-Key is request-header-only. Public execution records never expose its raw value, prefix, hash, canonical-request hash, or scope tuple.

MCP derives mcp:<session-id>:<json-rpc-id> unless _meta["dev.eyeball/idempotencyKey"] overrides it.