Spectre.Turn (Spectre v0.3.0)

High-level host-facing turn result.

A turn wraps the raw %Spectre.Result{} and a lifecycle decision that tells the host what to do next without encoding capability-specific branches in the decision vocabulary. This is Spectre's canonical local host result whether the input was routed normally or claimed by a pre-route Spectre.Turn.Handler.

Transport protocols should map their envelope into Spectre.turn/3 and map this result back out. Addressing, correlation, remote task state, retries, and delivery guarantees remain transport concerns.

Summary

Types

decision()

observable()

t()

Functions

from_result(agent, input, opts, result)

Builds a turn from an already available result.

from_step(agent, input, opts, arg)

Projects one closed Runtime step into the stable host-facing Turn.

resolve_policy(turn, resolution, opts \\ [])

Resolves this turn's active policy from a trusted host decision and returns the next lifecycle decision.

run(agent, input, opts \\ [])

Starts a Run and advances it to its first observable boundary.

Types

decision()

@type decision() ::
  {:awaiting, Spectre.Awaitable.t(), Spectre.Result.t()}
  | {:needs, Spectre.Effect.t(), Spectre.Result.t()}
  | {:completed, Spectre.Effect.t() | Spectre.Awaitable.t(), Spectre.Result.t()}
  | {:reply, Spectre.Result.t()}
  | {:no_response, Spectre.Result.t()}

observable()

@type observable() ::
  {:reply, term(), Spectre.Run.Ref.t()}
  | {:awaiting, Spectre.Run.Ref.t()}
  | {:needs, Spectre.Run.Boundary.t()}

t()

@type t() :: %Spectre.Turn{
  agent: module() | GenServer.server(),
  boundary: Spectre.Run.Boundary.t() | Spectre.Invocation.t() | nil,
  decision: decision(),
  input: Spectre.Input.t() | String.t() | map(),
  metadata: map(),
  observable: observable(),
  opts: keyword(),
  ref: Spectre.Run.Ref.t(),
  result: Spectre.Result.t()
}

Functions

from_result(agent, input, opts, result)

@spec from_result(
  module() | GenServer.server(),
  term(),
  keyword(),
  Spectre.Result.t()
) :: t()

Builds a turn from an already available result.

from_step(agent, input, opts, arg)

@spec from_step(
  module() | GenServer.server(),
  term(),
  keyword(),
  Spectre.Runtime.step_result()
) :: t()

Projects one closed Runtime step into the stable host-facing Turn.

The continuation itself remains owned by the runtime/actor. The Turn exposes only a revision-fenced reference and the first observable request or reply.

resolve_policy(turn, resolution, opts \\ [])

@spec resolve_policy(t(), Spectre.Policy.resolution(), keyword()) ::
  {:ok, t()} | {:error, term()}

Resolves this turn's active policy from a trusted host decision and returns the next lifecycle decision.

This keeps application adapters from synthesizing user text or manually rebuilding approved effects.

run(agent, input, opts \\ [])

@spec run(module(), Spectre.Input.t() | String.t() | map(), keyword()) ::
  {:ok, t()} | {:error, term()}

Starts a Run and advances it to its first observable boundary.