Spectre.Operation.Loop (Spectre v0.3.0)

Canonical portable state of one operational loop.

The struct intentionally contains no PID, function, client, port or process reference. A temporary Runner is represented only by its fenced Attempt.

Summary

Types

kind()

status()

t()

Functions

quiescent?(loop)

Returns true when no fenced Attempt is in flight, i.e. no temporary Runner exists for this loop.

runnable?(loop)

Returns true when the loop may start a new attempt: it is quiescent, has no outcome, and sits in :queued, :evaluating or :reconciling.

terminal?(loop)

Returns true when the loop has reached terminal status with a committed outcome.

touch(loop, opts \\ [])

Bumps the revision and refreshes updated_at.

validate(loop)

Checks every invariant of the checkpoint envelope: status/field coherence, identity, counters, timestamps, collection limits, nested structs and portability of the whole value.

Types

kind()

@type kind() :: :work | :vigil | :directive

status()

@type status() ::
  :queued
  | :active
  | :evaluating
  | :waiting
  | :pause_requested
  | :paused
  | :reconciling
  | :terminal

t()

@type t() :: %Spectre.Operation.Loop{
  artifacts: [term()],
  attempt: Spectre.Operation.Attempt.t() | nil,
  attempts: non_neg_integer(),
  authorized_origins: [term()],
  base_input: term(),
  blocker: term(),
  budget: Spectre.Operation.Budget.t(),
  causation_id: String.t() | nil,
  cognitive: map(),
  context_revision: non_neg_integer(),
  controller: module(),
  controller_id: atom() | String.t(),
  controller_version: pos_integer() | String.t(),
  correlation_id: String.t(),
  created_at: non_neg_integer(),
  cycles: non_neg_integer(),
  destinations: [term()],
  effective_input: term(),
  events: [String.t()],
  expires_at: non_neg_integer() | nil,
  id: String.t(),
  invalidations: [term()],
  kind: kind(),
  last_crash: term(),
  last_error: term(),
  last_progress: term(),
  last_result: term(),
  last_update: term(),
  metadata: map(),
  next_operation: term(),
  observations: non_neg_integer(),
  operation: term(),
  origin: term(),
  outcome: Spectre.Operation.Outcome.t() | nil,
  phase: term(),
  progress_sequence: non_neg_integer(),
  provenance: map(),
  receipt: term(),
  results: [term()],
  retries: non_neg_integer(),
  revision: non_neg_integer(),
  schema_version: pos_integer(),
  source_turn_id: term(),
  state: term(),
  status: status(),
  subject_id: String.t(),
  trigger_generation: non_neg_integer(),
  updated_at: non_neg_integer(),
  updates: [Spectre.Operation.Update.t()],
  visibility: atom(),
  wait: Spectre.Operation.Wait.t() | nil
}

Functions

quiescent?(loop)

@spec quiescent?(t()) :: boolean()

Returns true when no fenced Attempt is in flight, i.e. no temporary Runner exists for this loop.

runnable?(loop)

@spec runnable?(t()) :: boolean()

Returns true when the loop may start a new attempt: it is quiescent, has no outcome, and sits in :queued, :evaluating or :reconciling.

terminal?(loop)

@spec terminal?(t()) :: boolean()

Returns true when the loop has reached terminal status with a committed outcome.

touch(loop, opts \\ [])

@spec touch(
  t(),
  keyword()
) :: t()

Bumps the revision and refreshes updated_at.

Accepts :at (milliseconds) to override the timestamp; defaults to the current system time.

validate(loop)

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

Checks every invariant of the checkpoint envelope: status/field coherence, identity, counters, timestamps, collection limits, nested structs and portability of the whole value.

Returns :ok or {:error, reason} naming the first violated invariant.