package de.gecheckt.pdf.umbenenner.domain.model;

import java.util.Objects;

/**
 * Outcome indicating a transient technical failure during the AI naming pipeline.
 * <p>
 * Technical failures include:
 * <ul>
 *   <li>AI service not reachable</li>
 *   <li>HTTP timeout</li>
 *   <li>Connection error</li>
 *   <li>Unparseable or structurally invalid AI response (missing mandatory fields, invalid JSON)</li>
 * </ul>
 * <p>
 * These failures are retryable. The transient error counter is incremented.
 *
 * @param candidate    the source document candidate; never null
 * @param errorMessage human-readable description of the failure; never null
 * @param cause        the underlying exception, or {@code null} if not applicable
 * @param aiContext    AI traceability context captured before or during the failure; never null
 */
public record AiTechnicalFailure(
        SourceDocumentCandidate candidate,
        String errorMessage,
        Throwable cause,
        AiAttemptContext aiContext) implements DocumentProcessingOutcome {

    /**
     * Compact constructor validating mandatory fields.
     *
     * @throws NullPointerException if {@code candidate}, {@code errorMessage}, or
     *                              {@code aiContext} is null
     */
    public AiTechnicalFailure {
        Objects.requireNonNull(candidate, "candidate must not be null");
        Objects.requireNonNull(errorMessage, "errorMessage must not be null");
        Objects.requireNonNull(aiContext, "aiContext must not be null");
    }
}
