package de.gecheckt.pdf.umbenenner.application.port.out;

/**
 * Decision governing whether a within-run immediate technical retry of the target copy
 * operation is permitted.
 * <p>
 * The immediate retry mechanism is strictly scoped:
 * <ul>
 *   <li>It applies <strong>only</strong> to the physical target-file copy path.</li>
 *   <li>It is permitted <strong>at most once</strong> per document per run (first copy
 *       attempt failed; one additional attempt is allowed).</li>
 *   <li>It does <strong>not</strong> involve a new AI call, a new naming-proposal
 *       derivation, or any other pipeline stage.</li>
 *   <li>It does <strong>not</strong> increment the laufübergreifenden
 *       transient-error counter regardless of outcome.</li>
 *   <li>It is a purely technical within-run recovery mechanism and is
 *       <strong>not</strong> counted as a cross-run retry in the sense of
 *       {@code max.retries.transient}.</li>
 * </ul>
 * <p>
 * The concrete retry decision for the subsequent persistence step is derived from the
 * combined outcome after the immediate retry completes (see {@link RetryDecision}).
 */
public enum ImmediateRetryDecision {

    /**
     * An immediate within-run retry of the target copy operation is permitted.
     * <p>
     * This value is produced when the first physical copy attempt within the current
     * document run has failed. The copy must be retried exactly once more.
     * No other pipeline stage is repeated.
     */
    ALLOWED,

    /**
     * No immediate within-run retry is permitted.
     * <p>
     * This value is produced when the immediate retry quota for this document run has
     * already been consumed (i.e. the immediate retry attempt itself has failed), or
     * when the failure did not occur on the target copy path.
     * The error must be escalated to the cross-run retry evaluation.
     */
    DENIED
}
