Spectre.Operation.Spec (Spectre v0.3.0)

Immutable registry entry for one operation available to an operational loop.

Executors and validators are stable module/function references. They are resolved from code after restart and are never embedded in checkpoints.

Summary

Types

executor()

t()

validator()

Functions

new(spec)

Builds a validated spec from a struct, map or keyword list.

validate(spec)

Checks every invariant of the spec, including that its portable contract fields survive checkpoint serialization.

validate!(spec)

Same as validate/1 but returns the spec on success and raises ArgumentError on failure.

Types

executor()

@type executor() :: nil | module() | {module(), atom()}

t()

@type t() :: %Spectre.Operation.Spec{
  catalog: [atom() | String.t()],
  description: String.t() | nil,
  domain: [term()] | nil,
  executor: executor() | term(),
  fallback: executor(),
  id: atom() | String.t(),
  input: validator(),
  kind: :function | :action | :effect | :cognitive | :planner,
  metadata: map(),
  output: validator(),
  policy: :registered | executor(),
  reconcile: executor(),
  remember: false | true | map(),
  retry: Spectre.Operation.Retry.t(),
  risk: atom() | nil,
  side_effect: :none | :idempotent | :reconcilable | :non_idempotent,
  timeout: pos_integer()
}

validator()

@type validator() :: nil | atom() | module() | {module(), atom()}

Functions

new(spec)

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

Builds a validated spec from a struct, map or keyword list.

Missing fields fall back to defaults (kind: :function, timeout: 30_000, a kind-dependent side_effect). Raises ArgumentError when the resulting spec is invalid.

validate(spec)

@spec validate(t()) :: :ok | {:error, term()}

Checks every invariant of the spec, including that its portable contract fields survive checkpoint serialization.

Returns :ok or {:error, reason} with a tagged tuple naming the first violated invariant.

validate!(spec)

@spec validate!(t()) :: t()

Same as validate/1 but returns the spec on success and raises ArgumentError on failure.