Spectre.Policy (Spectre v0.3.0)

Copy Markdown View Source

Policy gate evaluator for pending effects.

A policy is a temporary deterministic router for one pending effect. While a policy is active, Spectre ignores normal flow routing and interprets the next user turn as approval, rejection, or retry.

Summary

Types

decision()
resolution()
t()

Functions

awaiting?(state)

Returns true when the state is waiting on a policy response.

decide(policy, text)

Decides whether policy text accepts, rejects, or misses all policy branches.

new(attrs)

Builds a policy struct from compiled DSL metadata.

resolve(resolution, input, ctx)

Resolves the active policy from a trusted host decision without matching synthetic user text.

resume(input, ctx)

Resumes the active policy with the user's latest input.

Types

decision()

@type decision() :: {:accept, atom()} | {:reject, atom()} | :no_match

resolution()

@type resolution() ::
  {:accept, atom()} | {:reject, atom()} | Spectre.Policy.Resolution.t()

t()

@type t() :: %Spectre.Policy{
  accepts: [map()],
  max_attempts: pos_integer() | nil,
  name: atom(),
  otherwise: {:ask, atom() | String.t()} | nil,
  owner: module() | nil,
  reference: term(),
  rejects: [map()],
  request: atom() | String.t() | nil,
  scope: Spectre.Definition.scope(),
  then: atom() | nil
}

Functions

awaiting?(state)

@spec awaiting?(Spectre.State.t()) :: boolean()

Returns true when the state is waiting on a policy response.

decide(policy, text)

@spec decide(t(), String.t()) :: decision()

Decides whether policy text accepts, rejects, or misses all policy branches.

new(attrs)

@spec new(map()) :: t()

Builds a policy struct from compiled DSL metadata.

resolve(resolution, input, ctx)

@spec resolve(resolution(), Spectre.Input.t(), Spectre.Context.t() | map()) ::
  {:ok, Spectre.Result.t()} | {:error, term()}

Resolves the active policy from a trusted host decision without matching synthetic user text.

The label must exist in the policy's corresponding accept/reject branches. This is useful when an application already has durable proof that a policy is satisfied. Callers should use Spectre.resolve_policy/4 so the resulting state is persisted before execution.

resume(input, ctx)

@spec resume(Spectre.Input.t(), Spectre.Context.t()) ::
  {:ok, Spectre.Result.t()} | {:error, term()}

Resumes the active policy with the user's latest input.