# `Nous.CodeRuntime.Failure`
[🔗](https://github.com/nyo16/nous/blob/v0.17.1/lib/nous/code_runtime/result.ex#L1)

Why a program did not produce a value.

A failure is **data**, never an exception. A program that throws, loops forever,
floods stdout, or dies with its substrate is a normal outcome of running
model-authored code: the model gets told what happened and writes a better
program. Raising would make the tool call an error and lose that loop.

The `kind`s are distinct because the model — and the operator reading a log —
can act differently on each:

  * `:exception` — the program raised. Its own bug; the message is the guest's.
  * `:timeout` — the wall-clock budget expired. Possibly an infinite loop,
    possibly just slow; the program ran and may have had side effects.
  * `:abort` — cancelled from outside (`c:Nous.CodeRuntime.cancel/2`), e.g. the
    agent run was cancelled. Not the program's fault.
  * `:substrate_exit` — the runtime died underneath us. Ours to fix, not the
    model's, and the one kind that should page somebody.
  * `:invalid_output` — the program returned something unrepresentable.
  * `:output_limit` — it produced more output than the ledger allows. The
    retained prefix is still in `Result.logs`, because truncated evidence beats
    none.

# `kind`

```elixir
@type kind() ::
  :exception
  | :timeout
  | :abort
  | :substrate_exit
  | :invalid_output
  | :output_limit
```

# `t`

```elixir
@type t() :: %Nous.CodeRuntime.Failure{kind: kind(), message: String.t()}
```

# `kinds`

```elixir
@spec kinds() :: [kind()]
```

Every failure kind.

# `new`

```elixir
@spec new(kind(), String.t()) :: t()
```

Build a failure. Unknown kinds are rejected at construction, where the bug is,
rather than surfacing as an unmatched clause somewhere downstream.

---

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