Spectre.Action (Spectre v0.3.0)

Provider-neutral description of one action.

An action says what should happen and which provider owns the operation. It does not execute work and it does not carry lifecycle state. Spectre turns it into an Spectre.Effect before policy evaluation, persistence, and execution.

:via is deliberately data rather than a module name. Libraries such as Kinetic, Lens, or an MCP adapter can therefore select a registered provider without teaching the core how that provider works.

Summary

Types

name()

provider_ref()

ref()

t()

Functions

from_effect(effect)

Restores the provider-neutral action carried by an effect.

matches_ref?(expected, effect)

Returns true when a DSL protection/hook reference selects the action.

new(action)

Builds an action from a name/reference and options.

new(action, opts)

ref(effect)

Returns the canonical {provider, operation} reference.

split_ref(name)

Splits compact references such as {:lens, :navigate} and {:mcp, :github, :create_issue}.

to_effect_attrs(action)

Converts an action into attributes accepted by Spectre.Effect.stage_action/3.

valid_ref?(reference)

Returns whether a value is a supported compact action reference.

Types

name()

@type name() :: atom() | String.t()

provider_ref()

@type provider_ref() :: atom() | String.t() | tuple()

ref()

@type ref() :: name() | {provider_ref(), name()} | tuple()

t()

@type t() :: %Spectre.Action{
  args: map(),
  metadata: map(),
  mode: :read | :write | :destructive | nil,
  name: name(),
  planned_by: module() | atom() | nil,
  schema_hash: String.t() | nil,
  via: provider_ref()
}

Functions

from_effect(effect)

@spec from_effect(Spectre.Effect.t()) :: t()

Restores the provider-neutral action carried by an effect.

matches_ref?(expected, effect)

@spec matches_ref?(term(), t() | Spectre.Effect.t()) :: boolean()

Returns true when a DSL protection/hook reference selects the action.

A bare action name remains provider-agnostic for backwards compatibility. A tuple is namespaced and must match both provider and operation.

new(action)

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

Builds an action from a name/reference and options.

Spectre.Action.new(:list_projects)
Spectre.Action.new(:navigate, via: :lens, args: %{url: "https://example.com"})
Spectre.Action.new({:mcp, :github, :create_issue}, args: %{title: "Bug"})

new(action, opts)

@spec new(
  ref() | t(),
  keyword()
) :: t()

ref(effect)

@spec ref(t() | Spectre.Effect.t() | ref()) :: {provider_ref(), name()}

Returns the canonical {provider, operation} reference.

split_ref(name)

@spec split_ref(ref()) :: {:ok, {provider_ref(), name()}} | :error

Splits compact references such as {:lens, :navigate} and {:mcp, :github, :create_issue}.

to_effect_attrs(action)

@spec to_effect_attrs(t()) :: map()

Converts an action into attributes accepted by Spectre.Effect.stage_action/3.

valid_ref?(reference)

@spec valid_ref?(term()) :: boolean()

Returns whether a value is a supported compact action reference.