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

Closed catalog of admitted LLM provider, model-alias protocol, and
whole-request timeout failures.

`PtcRunner.Kernel.ProviderError` and `PtcRunner.Kernel.SafeMetadata` consume
this module. `mix ptc.gen_docs` projects the same rows into the generated
`agent.failure` component. The classifier inspects the existing bounded LLM
envelope and does not add a field to `tool/llm-request`, `llm/request`,
inspection, or `run-outcome` maps.

Authenticated fail-fast consumption stays the provider kinds, Kernel-generated
provider failures, and whole-request timeout aliases. Model-alias protocol
reasons are recoverable to `run-outcome` but remain unauthenticated at
`kernel-llm-provider-failure`.

# `provider_failure_kind`

```elixir
@type provider_failure_kind() :: provider_kind() | :reservation_bound_exceeded
```

# `provider_kind`

```elixir
@type provider_kind() ::
  :denied
  | :not_found
  | :unavailable
  | :invalid_request
  | :internal
  | :domain_error
  | :invalid_result
  | :authentication_failed
  | :payment_required
  | :rate_limited
  | :tool_calling_unsupported
  | :usage_unavailable
  | :timeout
  | :transport_error
```

# `authenticated_kebabs`

```elixir
@spec authenticated_kebabs() :: [String.t()]
```

Kebab names SafeMetadata may authenticate as `llm_provider_failure`.

Includes provider kinds, Kernel-generated provider failures, and whole-request
timeout aliases. Omits model-alias protocol reasons, which stay unauthenticated
at fail-fast.

# `consume_kind`

```elixir
@spec consume_kind(String.t()) :: provider_failure_kind() | nil
```

Maps a normalized kebab failure name to the closed consume atom, or `nil`.

# `lisp_source`

```elixir
@spec lisp_source() :: String.t()
```

PTC-Lisp source for the generated `agent.failure` component.

# `provider_kinds`

```elixir
@spec provider_kinds() :: [provider_kind()]
```

---

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