@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.

@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.

@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.

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

@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.

@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.

@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.