<?php

declare(strict_types=1);

namespace Drupal\flowdrop_pipeline\Constants;

/**
 * Machine reasons stamped on a pipeline paused by an execution budget.
 *
 * Written by the orchestrators into the pipeline's execution context under
 * {@see self::CONTEXT_KEY} when the run loop stops on a budget (the
 * orchestrator settings' `timeout` or `max_iterations`) with ready jobs
 * remaining. A human-in-the-loop pause (interrupted jobs) carries NO
 * reason — that distinction is what gates the automatic Pause-signal
 * creation in flowdrop_interrupt, and what lets clients key a "continue"
 * affordance on `status=paused` + `pausedReason`.
 *
 * Cleared when execution re-enters the pipeline (resume) and on any
 * non-budget-pause outcome, so a stale reason never survives a completed,
 * failed, or HITL-paused run.
 *
 * @api
 */
final class PausedReason {

  /**
   * Execution-context key holding the paused reason.
   */
  public const CONTEXT_KEY = 'paused_reason';

  /**
   * The run loop stopped on the execution-time budget (`timeout`).
   */
  public const TIME_BUDGET = 'time_budget';

  /**
   * The run loop stopped on the iteration budget (`max_iterations`).
   */
  public const MAX_ITERATIONS = 'max_iterations';

  /**
   * The budget reasons that make a pause resumable via a system Pause signal.
   *
   * @return array<int, string>
   *   The budget reason values.
   */
  public static function budgetReasons(): array {
    return [
      self::TIME_BUDGET,
      self::MAX_ITERATIONS,
    ];
  }

}
