Spectre.Run (Spectre v0.3.0)

Serializable continuation for one unit of Spectre work.

A Run owns logical execution state only. Provider clients, processes, callbacks, memory values, and runtime options are deliberately re-resolved for every Spectre.Runtime.advance/2 or Spectre.Runtime.resume/3.

Hosts normally consume the public Spectre.Turn projection. Actor/runtime integrations can checkpoint a Run with checkpoint/2 and restore it with restore/2.

Summary

Types

cursor()

status()

t()

Functions

checkpoint(run, opts \\ [])

Serializes a continuation after stripping transport-only envelope details.

ref(run, kind, boundary_id, subject_id \\ nil)

Builds the revision-fenced public reference for a Run boundary.

restore(binary, opts \\ [])

Restores and validates a Run checkpoint.

Types

cursor()

@type cursor() :: :turn | :policy | :effect | :complete

status()

@type status() :: :ready | :boundary | :awaiting | :complete | :failed

t()

@type t() :: %Spectre.Run{
  activation_generation: non_neg_integer(),
  agent: module(),
  authority_epoch: non_neg_integer(),
  causation_id: String.t() | nil,
  closure_digest: String.t(),
  correlation_id: String.t() | nil,
  cursor: cursor(),
  definition_ref: Spectre.Definition.Ref.t(),
  deployment_requirement: term() | nil,
  id: String.t(),
  input: Spectre.Input.t(),
  last_error: term(),
  metadata: map(),
  result: Spectre.Result.t() | nil,
  revision: non_neg_integer(),
  run_version: pos_integer(),
  state: Spectre.State.t(),
  status: status(),
  step_id: String.t() | nil,
  trace_id: String.t(),
  waiting: Spectre.Run.Boundary.t() | Spectre.Invocation.t() | nil
}

Functions

checkpoint(run, opts \\ [])

@spec checkpoint(
  t(),
  keyword()
) :: {:ok, binary()} | {:error, term()}

Serializes a continuation after stripping transport-only envelope details.

The codec rejects non-portable values in authoritative State or Result data rather than silently checkpointing process-local handles.

ref(run, kind, boundary_id, subject_id \\ nil)

@spec ref(t(), Spectre.Run.Ref.kind(), String.t(), term()) :: Spectre.Run.Ref.t()

Builds the revision-fenced public reference for a Run boundary.

restore(binary, opts \\ [])

@spec restore(
  binary(),
  keyword()
) :: {:ok, t()} | {:error, term()}

Restores and validates a Run checkpoint.