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

import java.util.Objects;

/**
 * Outcome indicating a deterministic functional (content) failure in the AI naming pipeline.
 * <p>
 * Functional failures occur when the AI returns a structurally valid response but the
 * content violates the applicable fachliche rules, for example:
 * <ul>
 *   <li>Title exceeds the configured maximum base title length</li>
 *   <li>Title contains prohibited special characters</li>
 *   <li>Title is a generic placeholder (e.g., "Dokument", "Scan")</li>
 *   <li>AI-provided date is present but not a valid YYYY-MM-DD string</li>
 * </ul>
 * <p>
 * These failures are deterministic: retrying the same document against the same AI
 * and prompt is unlikely to resolve the issue without a document or prompt change.
 * The content error counter is incremented, and the standard one-retry rule applies.
 *
 * @param candidate       the source document candidate; never null
 * @param errorMessage    human-readable description of the validation failure; never null
 * @param aiContext       AI traceability context for the attempt record; never null
 */
public record AiFunctionalFailure(
        SourceDocumentCandidate candidate,
        String errorMessage,
        AiAttemptContext aiContext) implements DocumentProcessingOutcome {

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