# Durable operation reference

Checkpoint states, storage requirements, and reconciliation errors for resumable remote work.

Canonical: https://searchsdk.dev/docs/api/durable
Markdown: https://searchsdk.dev/docs/api/durable.md

<a id="options"></a>

## Options

> **TypeScript reference**
> The API names, code and policy behavior in this article describe the TypeScript SDK. See [your language guide](https://searchsdk.dev/docs/sdks) for its supported surface and limits.

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

<a id="states"></a>

## 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.

<a id="attach"></a>

## 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.

> **Caller verification is required**
> Confirm the remote job belongs to this exact operation, account, and input before attaching it. This helper provides local checkpoint consistency; it does not verify remote identity or guarantee exactly-once execution.

<a id="errors"></a>

## 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.