# `Dsxir.Program`

Runtime state container for a user program.

Carries a reference to the user module, a per-predictor `State` map, and an
open metadata map populated by optimizers. Flows explicitly through `forward/2`
and `Dsxir.Module.Runtime.call/4` — never held as ambient state.

# `t`

```elixir
@type t() :: %Dsxir.Program{
  metadata: map(),
  module: module(),
  predictors: %{required(atom()) => Dsxir.Program.State.t()}
}
```

# `get_state`

```elixir
@spec get_state(t(), atom()) :: Dsxir.Program.State.t()
```

Fetch the per-predictor `State` slot, raising if `name` is unknown.

# `new`

```elixir
@spec new(module()) :: t()
```

Build a fresh program for `user_module`. Raises
`Dsxir.Errors.Invalid.Module` when the module is not a `Dsxir.Module`.

# `new`

```elixir
@spec new(module(), [atom()]) :: t()
```

Build a program with explicit predictor names (used internally by load).

# `put_state`

```elixir
@spec put_state(t(), atom(), Dsxir.Program.State.t()) :: t()
```

Replace the `State` for `name` in `prog`, returning the updated program.

---

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