# `Rulestead.Runtime`
[🔗](https://github.com/szTheory/rulestead/blob/v1.0.0/lib/rulestead/runtime.ex#L2)

Cached, keyed flag lookup for running Phoenix and Plug applications.

Where `Rulestead.evaluate/3` is the pure evaluator over an authored flag
*payload* you already hold, `Rulestead.Runtime` resolves a flag by
`environment_key` and `flag_key` against the local snapshot cache and then
evaluates it. Use it in request and job paths where you do not want to fetch and
pass payloads yourself.

```elixir
{:ok, true} =
  Rulestead.Runtime.enabled?("production", "checkout_v2", context)
```

## Payload-first vs cached lookup

| You have… | Use |
|-----------|-----|
| an authored flag payload | `Rulestead.evaluate/3` |
| an environment + flag key, snapshot cache running | `Rulestead.Runtime` |

Both share the same deterministic evaluator and the same `%Rulestead.Result{}`.

## Supported surface

This facade is a closed catalog: `evaluate/3`, `enabled?/3`, `get_value/4`,
`get_variant/3`, `explain/3`, and `diagnostics/1`. Modules under
`Rulestead.Runtime.*` (cache, snapshot, refresh) are **implementation detail and
not public API** — see [API Stability](api_stability.md).

# `diagnostics`

```elixir
@spec diagnostics(keyword()) :: map()
```

Returns a map of current runtime cache state for all known environments.

`opts` is a keyword list, currently unused and reserved for future filtering
options. Pass `[]` or omit the argument entirely.

The returned map is keyed by environment name and includes cache freshness,
refresh status, flag counts, and snapshot timestamps. Useful for health checks,
operator dashboards, and debugging cache state without querying the store
directly.

# `enabled?`

```elixir
@spec enabled?(
  String.t() | atom(),
  String.t() | atom(),
  Rulestead.Context.t() | keyword() | map()
) ::
  {:ok, boolean()} | {:error, Rulestead.Error.t()}
```

Evaluates a flag and returns whether it is enabled for the given context.

Derives the result from `evaluate/3`. Returns `{:ok, boolean()}` on success,
or `{:error, %Rulestead.Error{}}` when evaluation fails.

# `evaluate`

```elixir
@spec evaluate(
  String.t() | atom(),
  String.t() | atom(),
  Rulestead.Context.t() | keyword() | map()
) ::
  {:ok, Rulestead.Result.t()} | {:error, Rulestead.Error.t()}
```

Resolves a flag from the snapshot cache and evaluates it against the given
context.

Arguments:

- `environment_key` — the environment to look up (e.g. `"production"`)
- `flag_key` — the flag identifier (e.g. `"checkout_v2"`)
- `context` — a `%Rulestead.Context{}`, keyword list, or map describing the
  requesting actor and environment

Returns `{:ok, %Rulestead.Result{}}` on success, or
`{:error, %Rulestead.Error{}}` when the cache is unavailable or the flag is
not found.

```elixir
context = Rulestead.Context.new(environment: "production", targeting_key: "u1")
{:ok, result} = Rulestead.Runtime.evaluate("production", "checkout_v2", context)
result.enabled?
```

# `explain`

```elixir
@spec explain(
  String.t() | atom(),
  String.t() | atom(),
  Rulestead.Context.t() | keyword() | map()
) ::
  {:ok, String.t()} | {:error, Rulestead.Error.t()}
```

Evaluates a flag and returns a human-readable explanation of the evaluation
decision.

Requires a running cache with available runtime metadata for the given
`environment_key`. The returned string describes which rule matched, what the
bucketing outcome was, and why — useful for support tools, operator dashboards,
and debugging.

Returns `{:ok, String.t()}` on success, or `{:error, %Rulestead.Error{}}` when
evaluation or metadata retrieval fails.

# `get_value`

```elixir
@spec get_value(
  String.t() | atom(),
  String.t() | atom(),
  Rulestead.Context.t() | keyword() | map(),
  term()
) :: {:ok, term()} | {:error, Rulestead.Error.t()}
```

Evaluates a flag and returns its configured value, falling back to `default`.

The fourth argument, `default`, is returned when the result's `:value` is `nil`
or the evaluation reason is `:default`. This covers degraded-cache scenarios
where the flag is not found and a safe fallback is needed.

Returns `{:ok, term()}` on success, or `{:error, %Rulestead.Error{}}` when
evaluation fails.

# `get_variant`

```elixir
@spec get_variant(
  String.t() | atom(),
  String.t() | atom(),
  Rulestead.Context.t() | keyword() | map()
) ::
  {:ok, String.t() | nil} | {:error, Rulestead.Error.t()}
```

Evaluates a flag and returns the matched variant key, or `nil` when no variant
applies.

Returns `{:ok, String.t() | nil}` on success, or `{:error, %Rulestead.Error{}}`
when evaluation fails.

---

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