Spectre.Execution (Spectre v0.3.0)

Pure-lifecycle execution workflow for action and extension-owned effects.

Runtime owns the durable commits before and after this workflow; this module validates the effect, invokes the capability once, and applies exactly one terminal lifecycle command.

Summary

Functions

execute_pending(state, ctx, opts \\ [])

Executes or replays the current pending effect in state.

Types

result()

@type result() :: {:ok, Spectre.Result.t()} | {:error, term()}

Functions

execute_pending(state, ctx, opts \\ [])

@spec execute_pending(Spectre.State.t(), Spectre.Context.t() | map(), keyword()) ::
  result()

Executes or replays the current pending effect in state.

The effect must belong to the Agent and scope carried by ctx. Unprotected :pending effects and policy-approved effects are dispatched through Spectre.ActionDispatcher for :action, or through a registered Spectre.Effect.Executor for an extension-owned kind. :waiting_policy, terminal, unscoped, foreign, and unsupported effects are rejected before any capability is invoked.

A terminal effect with the same identifier in state.planned_effects is replayed without invoking the capability again. Successful and failed dispatches are applied through Spectre.Lifecycle and returned as a Spectre.Result containing the terminal state and transition event.

Example

ctx = %{agent: MyApp.Agent, input: input, opts: [user_id: user.id]}

{:ok, result} =
  Spectre.Execution.execute_pending(approved_state, ctx)

{:ok, value} = Spectre.Result.action_outcome(result)

This low-level function does not persist state. Use Spectre.execute/3 when the Agent's configured state adapter must participate in the two-commit execution workflow.