# `duron.errors` module

Application failures are recorded as outcomes and delivered as `ApplicationError`. Runtime failures describe problems with definitions, history, ownership, or scheduling. Cancellation is handled separately; let `asyncio.CancelledError` propagate so the runtime can complete cleanup.

## Application failures

Effects record ordinary exceptions as outcomes. Every persisted application failure is delivered as `ApplicationError`, both during the first execution and on replay. Uncaught workflow failures observed through `run.result()` use the same type. Cancellation remains separate.

`ApplicationError` exposes `type_name`, `message`, optional JSON `details`, and `cause` (also available as Python's `__cause__`). For ordinary exceptions, `type_name` is the module-qualified class name, such as `builtins:ValueError`. Duron stores a bounded explicit cause chain; it does not reconstruct exception classes, constructor arguments, or arbitrary attributes.

Raise `ApplicationError` directly to supply a stable application error code and structured details. Re-raising it preserves its type name and details across further durable boundaries:

```python
from duron.errors import ApplicationError

# Inside an effect:
raise ApplicationError(
    "payment_rejected", "Payment was declined", details={"code": 409}
)
```

For richer details, explicitly call an application codec's `encode_json` before raising and `decode_json` with a known schema when catching the error. Duron persists details as finite JSON; it never sends exception objects to the codec.

## Runtime failures

### Submission and run lifecycle

| Error | Meaning and response |
| --- | --- |
| `SubmissionConflictError` | A run ID identifies a different immutable invocation. |
| `ContractMismatchError` | A reference differs from the persisted or registered contract. |
| `RunCancelledError` | The workflow acknowledged durable cancellation. |
| `RunFailedError` | No workflow outcome is available because the run is blocked or scheduling failed. `kind` is a `FailureKind`, including `INTERRUPTED_EFFECT` for an effect without an outcome. |
| `RunNotFoundError` | An operation selected an absent run. |

### Definitions and history

| Error | Meaning and response |
| --- | --- |
| `HistoryMismatchError` | The selected definition, inputs, or operation sequence disagrees with history. Use compatible code for that run, or start a new run. |
| `InterruptedEffectError` | Replay found an effect call without a final outcome. The scheduler marks the run `BLOCKED` and will not invoke the effect again. |
| `WorkflowDefinitionError` | The definition or port interface is invalid, or input consumers overlap with an interruptible scope. |
| `CorruptLogError` | A persisted record cannot be decoded or validated. Inspect the underlying history and its reported offset. |

### Ports and messages

| Error | Meaning and response |
| --- | --- |
| `PortClosedError` | A workflow input is closed and drained, or an effect output is closed. Host sends to closed inputs or terminal runs are discarded asynchronously. |
| `Interrupted` | An interruptible scope consumed one input; `value` contains its payload. |
| `ChannelClosedError` | A scoped effect channel is closed. An uncaught instance in an effect becomes an application failure. |
| `PostConflictError` | A delivery ID or posting key conflicts with existing content, or an append batch mixes existing and new IDs. |

### Storage and execution ownership

| Error | Meaning and response |
| --- | --- |
| `StorageError` | A storage operation failed, or another scheduler or store owns the database file. |
| `ClaimLostError` | The write claim no longer belongs to this owner. Stop using the stale owner. |
| `ClaimBusyError` | Another owner holds the claim. Wait for release. |
| `RunUnavailableError` | The effect's run owner is no longer accepting operations. |
| `InvalidHandleError` | An endpoint has an invalid identity, direction, type, or owner. |
| `InvalidExecutionRequestError` | An executor request does not match the registered call. |
| `InvalidPostError` | A posting key, action, or payload is invalid. |
| `ExecutionCompletedError` | A mutation was attempted after the effect completed. |

`DuronError` groups Duron-specific conditions. Invalid arguments may also raise standard `TypeError` or `ValueError`; cancellation uses `asyncio.CancelledError`. Ownership and history errors propagate as runtime failures.

Public error hierarchy for Duron.

Duron-specific conditions have dedicated classes for type-based handling. The intermediate `WorkflowError` and `StorageError` bases group related conditions. Invalid arguments can also raise standard Python exceptions.

## JSONValue

```python
JSONValue: TypeAlias
```

Recursive type representing any valid JSON value.

## \_\_all\_\_

```python
__all__
```

## ApplicationError

```python
ApplicationError(
    type_name: str,
    message: str,
    *,
    details: JSONValue = None,
    cause: ApplicationError | None = None,
)
```

A persisted application failure from an effect or workflow.

`details` contains optional JSON data. Use an application codec explicitly to encode and decode richer details with a known schema. Original exception classes and constructor arguments are never reconstructed.

### cause

```python
cause: BaseException | None
```

The explicit cause, also available through Python's `__cause__`.

### details

```python
details: JSONValue
```

### message

```python
message
```

### type\_name

```python
type_name
```

## ChannelClosedError

An explicit effect stream or signal channel is permanently closed.

## ClaimBusyError

Another owner holds the history claim.

## ClaimLostError

The storage claim was lost while appending to the run.

## ContractMismatchError

A workflow reference does not match the persisted or registered contract.

## CorruptLogError

```python
CorruptLogError(offset: int, message: str)
```

Persisted log data cannot be decoded or validated.

### offset

```python
offset
```

## DefaultCodec

Encode finite JSON values and return decoded values unchanged.

Supports `None`, booleans, numbers, strings, lists, and dictionaries with string keys. Annotations do not trigger type validation or reconstruction. Use a custom Codec for other Python types.

### decode\_json

```python
decode_json(
    encoded: JSONValue, _expected_type: TypeHint[_T]
) -> _T
```

### encode\_json

```python
encode_json(
    result: object, _annotated_type: TypeHint[object]
) -> JSONValue
```

## DuronError

Base class for Duron-specific errors.

## ExecutionCompletedError

A new mutation was attempted after final execution completion.

## FailureKind

Why the scheduler stopped running a job without a workflow outcome.

### CONTRACT\_MISMATCH

```python
CONTRACT_MISMATCH
```

### CORRUPT\_HISTORY

```python
CORRUPT_HISTORY
```

### HISTORY\_MISMATCH

```python
HISTORY_MISMATCH
```

### INFRASTRUCTURE

```python
INFRASTRUCTURE
```

### INTERRUPTED\_EFFECT

```python
INTERRUPTED_EFFECT
```

### INVALID

```python
INVALID
```

### UNAVAILABLE

```python
UNAVAILABLE
```

## HistoryMismatchError

```python
HistoryMismatchError(
    message: str,
    *,
    expected: object | None = None,
    actual: object | None = None,
)
```

A replay diverged from the recorded history.

The structured `expected` and `actual` fields name what diverged.

### actual

```python
actual
```

### expected

```python
expected
```

## Interrupted

```python
Interrupted(value: object)
```

A signal interrupted an interruptible block.

Attributes:

- **`value`** –

  The payload sent with the signal that caused the interrupt.

### value

```python
value
```

## InterruptedEffectError

```python
InterruptedEffectError(operation_id: str)
```

A committed effect call has no final outcome and cannot be dispatched again.

### operation\_id

```python
operation_id
```

## InvalidExecutionRequestError

A worker request does not match its registered execution schema.

## InvalidHandleError

A handle's identity, direction, type, or ownership is invalid.

## InvalidPostError

A posting key, action, or payload is malformed.

## PortClosedError

An input is closed for delivery, or closed and drained for receiving.

## PostConflictError

A delivery ID, append batch, or posting key was reused with new content.

## RunCancelledError

The durable workflow acknowledged cancellation.

## RunFailedError

```python
RunFailedError(message: str, kind: FailureKind)
```

No workflow outcome is available because the run is blocked or failed.

`kind` classifies the failure. `INFRASTRUCTURE` means the retry budget was exhausted; `INVALID` means a deterministic input or codec failure. A blocked run may resume when its implementation becomes available, but an interrupted effect is never invoked again.

### kind

```python
kind
```

## RunNotFoundError

The selected persisted run does not exist.

## RunUnavailableError

The run has no active owner accepting executor operations.

## StorageError

Category base for storage and ownership failures.

## SubmissionConflictError

A run ID already identifies a different immutable invocation.

## WorkflowDefinitionError

A workflow or effect was declared or invoked incorrectly.

## WorkflowError

Category base for workflow lifecycle and definition errors.
