Durable operation reference
Checkpoint states, storage requirements, and reconciliation errors for resumable remote work.
On this page
Options
| Field | Contract |
|---|---|
key | Checkpoint key, 1–200 letters/digits/underscore/dot/colon/hyphen. |
operation | Static operation identity, 1–128 allowed identifier characters. |
inputFingerprint | Caller-owned opaque input/account binding; never a credential. |
store | CheckpointStore with load and atomic compareAndSet. |
submit({ signal }) | One explicit submission returning { remoteId }. |
poll(remoteId, { signal }) | Read-only status; pending, completed with value, or failed. |
timeoutMs, pollIntervalMs, maxPolls | Positive integer invocation limits; 30,000 / 1,000 / 100 defaults. |
signal | Optional caller cancellation. |
Checkpoint states
submitting: intent persisted; an unknown outcome requires reconciliation.submitted: saved remote ID; safe to resume read-only polling.completed: JSON result stored and returned on resume.failed: remote failure retained; no automatic resubmission.
A checkpoint has version 1, a monotonically advancing revision, operation/input binding, and an updatedAt timestamp. Remote IDs are present after submission. Results are present only when completed.
Explicit remote-ID reconciliation
Import attachDurableRemoteId from @belweave/search-sdk/durable. Supply store, key, operation, inputFingerprint, and a verified remoteId. The helper accepts only a matching submitting checkpoint, atomically advances its revision to submitted, and returns that checkpoint. Missing, mismatched, or concurrently changed state returns checkpoint_conflict.
DurableOperationError
| Code | Action |
|---|---|
configuration | Correct invalid options, identifiers, or checkpoint values. |
storage_failure | Reconcile persisted state before continuing. |
checkpoint_conflict | Another writer or a different input binding owns the checkpoint. |
ambiguous_submission | Remote work may exist; do not automatically submit again. |
poll_failed | Read failed; resume using the saved remote identifier. |
remote_failed | Provider reported a terminal failure. |
poll_limit | Resume the saved job in a later bounded invocation. |
aborted, timeout | Persisted state remains; these do not cancel the remote job. |
A remoteId can be exposed on the durable error when submission returned an ID but checkpoint persistence failed. Preserve it for reconciliation. Error messages omit raw storage and provider error details.