# `PtcRunner.Kernel.ProviderError`
[🔗](https://github.com/andreasronge/ptc_runner/blob/main/lib/ptc_runner/kernel/provider_error.ex#L1)

A bounded host-constructed failure returned by a capability provider.

Providers return `{:error, %ProviderError{}}` for expected failures. The
dispatcher converts it into the uniform Lisp capability error envelope.
`details` is truncated to 1,024 characters and must not contain credentials,
BEAM exceptions, stack traces, or other host-private data.
Adapters that translate dependency errors must select bounded diagnostic
fields explicitly; inspecting an entire error value may retain request
bodies, response bodies, headers, causes, or credentials and is forbidden.

`mutation_state: :indeterminate` is orthogonal to the diagnostic `kind`: it
means a non-successful call may already have changed external state and is
therefore never retryable. `dispatch_provenance` is trusted, internal
evidence for the mission dispatcher. Providers may set it to
`:not_dispatched` only when no invocation could have reached the underlying
transport, `:dispatched` when the callee returned a complete answer, or
`:possibly_dispatched` when a call may have been sent and the outcome is
unknown. It is never copied into the public Lisp envelope. A replay
provider may attach its validated `:replay_request_hash`; the dispatcher
records that host-owned evidence separately from the Lisp envelope. Missing
provenance is treated conservatively after callback entry.

# `dispatch_provenance`

```elixir
@type dispatch_provenance() :: :not_dispatched | :dispatched | :possibly_dispatched
```

# `kind`

```elixir
@type kind() :: PtcRunner.Kernel.LLMFailureCatalog.provider_kind()
```

# `mutation_state`

```elixir
@type mutation_state() :: :indeterminate
```

# `t`

```elixir
@type t() :: %PtcRunner.Kernel.ProviderError{
  details: binary() | nil,
  dispatch_provenance: dispatch_provenance() | nil,
  kind: kind(),
  mutation_state: mutation_state() | nil,
  replay_request_hash: binary() | nil,
  retryable?: boolean()
}
```

# `new`

```elixir
@spec new(kind(), binary() | nil, keyword()) :: t()
```

Constructs a provider failure with optional bounded details and
`:retryable?`, `:mutation_state`, internal `:dispatch_provenance`, and
internal `:replay_request_hash` metadata.

Mutation state accepts only `:indeterminate`, and dispatch provenance accepts
`:not_dispatched`, `:dispatched`, or `:possibly_dispatched`. A replay request hash is
valid only for a non-retryable `:not_found` error whose details are the exact
replay-miss message for that hash. An indeterminate failure is always
constructed as non-retryable.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
