Idempotency

This page explains how a Client retries an uncertain execution without duplicating effects.

Idempotency makes repeated execute requests with the same key, runnable, and input behave as one Run.

The difficult retry case is a timeout. The Client does not know whether execution started, completed, or never reached the server. Retrying a side-effecting program without a protocol guarantee can repeat its effects.

When execute.idempotency is declared, the Client may send an idempotency_key. The server stores the runnable, input, and recorded response. The same key with the same runnable and input replays the first result without executing again. The same key with a different runnable or input produces the request-error kind idempotency_conflict.

Harborview declares the capability in its real manifest:

{
  "execute": {
    "test_run": true,
    "idempotency": true
  }
}

Refused Runs are not recorded for replay because no effect occurred. This matters after catalog_drift: an unchanged request with the same key may proceed after the catalog is repaired, while a corrected program or changed input requires a fresh key.

Server implementations must claim a key atomically before execution so concurrent requests cannot both run. The deduplication window is at least the declared retention period. Client implementations should reuse the same key only when retrying the same uncertain request.

When idempotency is not declared, a Client must not assume automatic retry is safe. For side-effecting work, the Host should surface the retry decision instead.

Formal rules: Part II §6.5.6, Effects, idempotency, and partial failure and Part IV §8, Idempotency in practice.

Next: Drift and recovery · Outcomes