Spectre.Operation.Runtime (Spectre v0.3.0)

Copy Markdown View Source

Pure transition engine for Work, Vigil and external operational controllers.

Slow execution is deliberately absent from this module. It prepares fenced attempts and reduces their results; Spectre.Instance owns serialization, canonical commit, supervision and scheduling.

The engine is split by concern: Runtime.Contract enforces the code-owned definition, Runtime.Transitions builds loop-state transitions, Runtime.Results reduces Runner results, Runtime.Controls handles the control plane and Runtime.Recovery validates restored checkpoints. This module keeps loop start, attempt preparation, trigger delivery and the public entry points.

Summary

Types

env()
event_spec()
pid_action()

Functions

advance_control(loop, control, env)

Advances a pending pause/update/resume sequence once the loop is quiescent.

apply_result(loop, control, result, env)

Applies one correlated Runner result and leaves completion evaluation for the next commit.

evaluate(loop, control, env)

Evaluates deterministic completion only after the result transition was committed.

prepare(loop, control, env)

Prepares the next registered operation from committed loop state.

recover(loop, control, env)

Recovers portable loop state after an Agent restart and invalidates the old epoch.

request_control(loop, control, command, env)

Commits a durable control request without executing it reentrantly.

runner_down(loop, control, spec, reason, env)

Reduces an unexpected DOWN for the currently fenced Runner.

start(kind, controller, input, opts, env)
start_program(program, input, opts, env)

Starts a data-only Work on the same fenced operational runtime.

trigger(loop, control, trigger, opts, env)

Applies a correlated timer, event or human trigger to a waiting loop.

validate_checkpoint(loop, control, env)

Validates a restored loop and its control plane against the current code-owned definition.

Types

env()

@type env() :: map()

event_spec()

@type event_spec() :: %{:type => atom(), optional(:payload) => term()}

pid_action()

@type pid_action() :: Spectre.Operation.Runtime.Controls.pid_action()

Functions

advance_control(loop, control, env)

@spec advance_control(
  Spectre.Operation.Loop.t(),
  Spectre.Operation.Control.t(),
  env()
) ::
  {:ok, Spectre.Operation.Loop.t(), Spectre.Operation.Control.t(),
   [event_spec()]}
  | {:error, term()}

Advances a pending pause/update/resume sequence once the loop is quiescent.

apply_result(loop, control, result, env)

@spec apply_result(
  Spectre.Operation.Loop.t(),
  Spectre.Operation.Control.t(),
  Spectre.Operation.Result.t(),
  env()
) ::
  {:ok, Spectre.Operation.Loop.t(), Spectre.Operation.Control.t(),
   [event_spec()]}
  | {:duplicate, Spectre.Operation.Loop.t()}
  | {:error, term()}

Applies one correlated Runner result and leaves completion evaluation for the next commit.

evaluate(loop, control, env)

@spec evaluate(Spectre.Operation.Loop.t(), Spectre.Operation.Control.t(), env()) ::
  {:ok, Spectre.Operation.Loop.t(), Spectre.Operation.Control.t(),
   [event_spec()]}
  | {:error, term()}

Evaluates deterministic completion only after the result transition was committed.

prepare(loop, control, env)

@spec prepare(Spectre.Operation.Loop.t(), Spectre.Operation.Control.t(), env()) ::
  {:run, Spectre.Operation.Loop.t(), Spectre.Operation.Attempt.t(),
   Spectre.Operation.Spec.t(), Spectre.Operation.Request.t(), boolean(),
   [event_spec()]}
  | {:transition, Spectre.Operation.Loop.t(), Spectre.Operation.Control.t(),
     [event_spec()]}
  | {:error, term()}

Prepares the next registered operation from committed loop state.

recover(loop, control, env)

@spec recover(Spectre.Operation.Loop.t(), Spectre.Operation.Control.t(), env()) ::
  {:ok, Spectre.Operation.Loop.t(), Spectre.Operation.Control.t(),
   [event_spec()]}
  | {:error, term()}

Recovers portable loop state after an Agent restart and invalidates the old epoch.

request_control(loop, control, command, env)

@spec request_control(
  Spectre.Operation.Loop.t(),
  Spectre.Operation.Control.t(),
  Spectre.Operation.Control.Command.t(),
  env()
) ::
  {:ok, Spectre.Operation.Loop.t(), Spectre.Operation.Control.t(), pid_action(),
   [event_spec()]}
  | {:duplicate, Spectre.Operation.Loop.t(), Spectre.Operation.Control.t()}
  | {:error, term()}

Commits a durable control request without executing it reentrantly.

runner_down(loop, control, spec, reason, env)

@spec runner_down(
  Spectre.Operation.Loop.t(),
  Spectre.Operation.Control.t(),
  Spectre.Operation.Spec.t(),
  term(),
  env()
) ::
  {:ok, Spectre.Operation.Loop.t(), Spectre.Operation.Control.t(),
   [event_spec()]}
  | {:error, term()}

Reduces an unexpected DOWN for the currently fenced Runner.

start(kind, controller, input, opts, env)

@spec start(Spectre.Operation.Loop.kind(), module(), term(), keyword(), env()) ::
  {:ok, Spectre.Operation.Loop.t(), Spectre.Operation.Control.t(),
   [event_spec()]}
  | {:error, term()}

start_program(program, input, opts, env)

@spec start_program(Spectre.Execution.Program.t(), term(), keyword(), env()) ::
  {:ok, Spectre.Operation.Loop.t(), Spectre.Operation.Control.t(),
   [event_spec()]}
  | {:error, term()}

Starts a data-only Work on the same fenced operational runtime.

trigger(loop, control, trigger, opts, env)

@spec trigger(
  Spectre.Operation.Loop.t(),
  Spectre.Operation.Control.t(),
  term(),
  keyword(),
  env()
) ::
  {:ok, Spectre.Operation.Loop.t(), Spectre.Operation.Control.t(),
   [event_spec()]}
  | {:error, term()}

Applies a correlated timer, event or human trigger to a waiting loop.

validate_checkpoint(loop, control, env)

@spec validate_checkpoint(
  Spectre.Operation.Loop.t(),
  Spectre.Operation.Control.t(),
  env()
) ::
  :ok | {:error, term()}

Validates a restored loop and its control plane against the current code-owned definition.