@spec append_artifacts(Spectre.Operation.Loop.t(), term(), pos_integer()) ::
  Spectre.Operation.Loop.t()

Prepends artifacts within the declared and absolute limits.

@spec append_invalidations(Spectre.Operation.Loop.t(), term()) ::
  Spectre.Operation.Loop.t()

Merges invalidation entries within the bounded window.

@spec append_results(Spectre.Operation.Loop.t(), term()) :: Spectre.Operation.Loop.t()

Prepends result values within the bounded window.

@spec authorized_origins(
  term(),
  keyword()
) :: [term()]

Merges the loop origin into the authorized origins.

@spec budget_exhaustion(Spectre.Operation.Loop.t(), map(), keyword()) ::
  {atom(), term(), term()} | nil

Returns the exhausted budget dimension, checking expiry first.

@spec clear_attempt(Spectre.Operation.Loop.t()) :: Spectre.Operation.Loop.t()

Clears the active attempt and operation.

@spec clear_reconciliation_marker(Spectre.Operation.Loop.t()) ::
  Spectre.Operation.Loop.t()

Drops any reconciliation marker.

@spec clear_resume_status(Spectre.Operation.Loop.t()) :: Spectre.Operation.Loop.t()

Drops the remembered resume status.

@spec complete(Spectre.Operation.Loop.t(), term(), map()) ::
  Spectre.Operation.Loop.t()

Terminates a loop with a completed outcome.

@spec effective_budget(Spectre.Operation.Budget.t() | map(), term(), integer()) ::
  {:ok, Spectre.Operation.Budget.t()} | {:error, term()}

Builds the effective budget from the definition default or an override.

@spec fail(Spectre.Operation.Loop.t(), term(), map()) :: Spectre.Operation.Loop.t()

Terminates a loop with a failed outcome.

@spec maybe_increment_observations(Spectre.Operation.Loop.t()) ::
  Spectre.Operation.Loop.t()

Counts one Vigil observation.

@spec normalize_significance(Spectre.Operation.Loop.kind(), term()) ::
  :significant | :silent | nil

Normalizes a declared Vigil significance value.

@spec observation_event(
  Spectre.Operation.Loop.kind(),
  :significant | :silent | nil,
  Spectre.Operation.Result.t()
) :: map() | nil

Builds the Vigil observation event, or nil for other kinds.

@spec origin_provenance(term()) :: map()

Builds provenance for an explicit origin.

@spec put_cognitive_result(Spectre.Operation.Loop.t(), Spectre.Operation.Result.t()) ::
  Spectre.Operation.Loop.t()

Mirrors cognitive fallback and selection metadata from a result.

@spec put_reconciliation_marker(
  Spectre.Operation.Loop.t(),
  Spectre.Operation.Request.t() | nil,
  boolean()
) :: Spectre.Operation.Loop.t()

Marks or clears the reconciliation request the loop must run next.

@spec put_resume_status(Spectre.Operation.Loop.t(), atom()) ::
  Spectre.Operation.Loop.t()

Remembers the pre-pause status a resume should return to.

@spec put_significance(
  Spectre.Operation.Loop.t(),
  :significant | :silent | nil,
  Spectre.Operation.Result.t(),
  map()
) :: Spectre.Operation.Loop.t()

Records the last significant Vigil change in loop metadata.

@spec put_wait(Spectre.Operation.Loop.t(), Spectre.Operation.Wait.t()) ::
  Spectre.Operation.Loop.t()

Places the loop into a waiting state, inheriting the trigger generation.

@spec reconciliation_request?(
  Spectre.Operation.Loop.t(),
  Spectre.Operation.Request.t()
) :: boolean()

Returns true when the request is the marked reconciliation request.

@spec resume_status(Spectre.Operation.Loop.t()) :: atom()

Reads the status a paused loop should resume into.

@spec terminal_budget(Spectre.Operation.Loop.t(), atom(), term(), term(), map()) ::
  Spectre.Operation.Loop.t()

Terminates a loop whose budget dimension is exhausted or expired.

@spec terminal_control(Spectre.Operation.Control.t()) ::
  {Spectre.Operation.Control.t(), [map()]}

Terminalizes the control plane, rejecting a racing pending command.

A terminal transition can race with a pending safe pause/update command. The command can no longer be applied, so it is rejected in the same transition; otherwise the terminal control plane would fail validation and the terminal outcome could never be committed.

@spec trigger_generation_increment(Spectre.Operation.Loop.kind()) :: 0 | 1

Vigil updates invalidate outstanding triggers; other kinds do not.