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

/**
 * Unified classification of all document-level errors in the end state.
 * <p>
 * This enumeration provides a single, exhaustive taxonomy for every error category
 * that the retry policy and logging infrastructure must distinguish. It replaces
 * any ad-hoc string-based classification where an authoritative type is needed.
 * <p>
 * <strong>Mapping to failure counters:</strong>
 * <ul>
 *   <li>{@link #DETERMINISTIC_CONTENT_ERROR} → increments the content-error counter
 *       ({@link FailureCounters#contentErrorCount()}). The first occurrence leads to
 *       {@code FAILED_RETRYABLE}; the second leads to {@code FAILED_FINAL}.
 *       There is no further retry after the second deterministic content error.</li>
 *   <li>{@link #TRANSIENT_TECHNICAL_ERROR} → increments the transient-error counter
 *       ({@link FailureCounters#transientErrorCount()}). Remains retryable until the
 *       counter reaches the configured {@code max.retries.transient} limit (Integer &ge; 1).
 *       The attempt that reaches the limit finalises the document to {@code FAILED_FINAL}.</li>
 *   <li>{@link #TARGET_COPY_TECHNICAL_ERROR} → signals a failure on the physical target
 *       file copy path. Within the same run, exactly one immediate technical retry is
 *       allowed. If the immediate retry also fails, the error is treated as a
 *       {@link #TRANSIENT_TECHNICAL_ERROR} for the purposes of counter updates and
 *       cross-run retry evaluation.</li>
 * </ul>
 * <p>
 * <strong>Scope of deterministic content errors:</strong>
 * <ul>
 *   <li>No usable PDF text extracted</li>
 *   <li>Page limit exceeded</li>
 *   <li>AI response functionally invalid (generic/unusable title, unparseable date)</li>
 *   <li>Document content ambiguous or not uniquely interpretable</li>
 * </ul>
 * <p>
 * <strong>Scope of transient technical errors:</strong>
 * <ul>
 *   <li>AI service unreachable, HTTP timeout, network error</li>
 *   <li>Unparseable or structurally invalid AI JSON</li>
 *   <li>Temporary I/O error during PDF text extraction</li>
 *   <li>Temporary SQLite lock or persistence failure</li>
 *   <li>Any other non-deterministic infrastructure failure</li>
 * </ul>
 * <p>
 * <strong>Architecture note:</strong> This type carries no infrastructure dependencies.
 * It is safe to reference from Domain, Application and Adapter layers.
 */
public enum DocumentErrorClassification {

    /**
     * A deterministic content error that cannot be resolved by retrying with the same
     * document content.
     * <p>
     * Examples: no extractable text, page limit exceeded, AI-returned title is generic
     * or unusable, document content is ambiguous.
     * <p>
     * Retry rule: the first historised occurrence of this error for a fingerprint leads
     * to {@code FAILED_RETRYABLE} (one later run may retry). The second historised
     * occurrence leads to {@code FAILED_FINAL} (no further retries).
     */
    DETERMINISTIC_CONTENT_ERROR,

    /**
     * A transient technical infrastructure failure unrelated to the document content.
     * <p>
     * Examples: AI endpoint not reachable, HTTP timeout, malformed or non-parseable
     * JSON, temporary I/O failure, temporary SQLite lock.
     * <p>
     * Retry rule: remains {@code FAILED_RETRYABLE} until the transient-error counter
     * reaches the configured {@code max.retries.transient} limit. The attempt that
     * reaches the limit finalises the document to {@code FAILED_FINAL}.
     * The configured limit must be an Integer &ge; 1; the value {@code 0} is invalid
     * start configuration and prevents the batch run from starting.
     */
    TRANSIENT_TECHNICAL_ERROR,

    /**
     * A technical failure specifically on the physical target-file copy path.
     * <p>
     * This error class is distinct from {@link #TRANSIENT_TECHNICAL_ERROR} because it
     * triggers a special within-run handling: exactly one immediate technical retry of
     * the copy operation is allowed within the same document run. No new AI call and no
     * new naming proposal derivation occur during the immediate retry.
     * <p>
     * If the immediate retry succeeds, the document proceeds to {@code SUCCESS}.
     * If the immediate retry also fails, the combined failure is recorded as a
     * {@link #TRANSIENT_TECHNICAL_ERROR} for counter and cross-run retry evaluation.
     * The immediate retry is not counted in the laufübergreifenden transient-error counter.
     */
    TARGET_COPY_TECHNICAL_ERROR
}
