<?php

declare(strict_types=1);

namespace Drupal\flowdrop\Exception;

/**
 * Marks a node failure as transient — safe for the engine to retry.
 *
 * Retry is opt-in by exception type, mirroring how interrupt signals are
 * recognised by their own marker interface (InterruptExceptionInterface).
 * The orchestrator catches every \Exception a node throws, then discriminates:
 * a failure implementing this marker engages the node's retry policy; any
 * other failure is terminal and goes straight to the node's error output
 * path (or fails the run when no error path is wired).
 *
 * Retry happens IN PLACE and IMMEDIATELY — there is no delay or backoff
 * between attempts. Throw a retryable exception only for failures a same-
 * instant re-run could plausibly clear: an optimistic-concurrency / version
 * conflict on save, a transient lock or race that resolves at once. It is a
 * poor fit for failures that only clear after waiting — a network timeout, an
 * upstream 5xx, rate limiting — because retrying those with zero delay just
 * fails faster and burns the attempt budget; handle those instead by wiring
 * the node's `error` output port to a Delay/Timer node that loops back. Never
 * mark deterministic failures retryable (validation errors, 4xx, malformed
 * config).
 *
 * IMPORTANT: retry re-runs the whole node from the top. Only throw a
 * retryable exception from nodes whose execution is idempotent — otherwise
 * a retry repeats side effects already performed on the first attempt.
 *
 * @see \Drupal\flowdrop\Exception\RetryableNodeProcessingException
 *
 * @api
 */
interface RetryableExceptionInterface extends \Throwable {

}
