> For the complete documentation index, see [llms.txt](https://docs.sedona.fun/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sedona.fun/safety-semantics.md).

# Safety semantics

[← Back to dashboard](https://www.sedona.fun/dashboard/api-keys)

The SDK preserves uncertainty instead of converting it into success.

## Mutation ambiguity

Mutations are single-attempt. A timeout, cancellation, network reset, or body read failure after dispatch may leave the provider outcome unknown. The SDK raises `outcome_unknown` and may attach a reconciliation hint. It never retries the mutation automatically.

Read retries are opt-in and apply only when the provider descriptor declares a read transient:

```ts
const client = createClient(provider, {
  readRetry: { maxAttempts: 3, maxElapsedMs: 2_000 },
});
```

Cancellation and per-call timeout budgets cover lazy provider startup, the operation, and retry backoff. Invalid budgets fail before provider I/O.

## Typed errors

Use `isOpenblueError` across package boundaries:

```ts
try {
  await operation();
} catch (error) {
  if (isOpenblueError(error)) {
    console.error({
      code: error.code,
      operation: error.operation,
      httpStatus: error.httpStatus,
      providerCode: error.providerCode,
      retryable: error.retryable,
      retryAfter: error.retryAfter,
      requestId: error.requestId,
    });
  }
}
```

Do not log `raw` or `cause`; they may contain provider data. Fleet preserves HTTP status and provider error code when available. The production Fleet API does not currently expose a stable request or correlation ID, so `requestId` is normally absent.

Important codes include:

| Code                     | Meaning                                          |
| ------------------------ | ------------------------------------------------ |
| `authentication`         | bearer key was rejected                          |
| `authorization`          | key is valid but lacks route or line access      |
| `validation`             | request was refused as malformed                 |
| `capability_unavailable` | adapter or provider cannot perform the operation |
| `rate_limited`           | provider throttled the request                   |
| `timeout`                | no result was observed before the budget         |
| `cancelled`              | caller cancelled before a result                 |
| `outcome_unknown`        | a mutation may have dispatched                   |

## Cursors and event checkpoints

List cursors are bound to the provider, operation, and query that issued them. Do not move a cursor between methods or change filters while resuming.

An opened event stream exposes a live checkpoint:

```ts
const stream = client.events.stream({ after: savedCheckpoint });
await stream.open();
for await (const event of stream) {
  await processEvent(event);
  await persistCheckpoint(stream.checkpoint());
}
```

Persist the checkpoint only after the event's application work commits.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.sedona.fun/safety-semantics.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.