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

import java.util.Objects;

/**
 * Outcome indicating that an AI naming pipeline completed successfully and produced
 * a validated naming proposal ready for persistence.
 * <p>
 * This outcome is returned when:
 * <ol>
 *   <li>PDF text extraction and pre-checks passed.</li>
 *   <li>The AI was invoked and returned a parseable response.</li>
 *   <li>The response passed all semantic validation rules.</li>
 *   <li>A {@link NamingProposal} was produced.</li>
 * </ol>
 * <p>
 * The document master record will be updated to {@link ProcessingStatus#PROPOSAL_READY};
 * a physical target copy is not yet produced at this stage.
 *
 * @param candidate  the source document candidate; never null
 * @param proposal   the validated naming proposal ready for persistence; never null
 * @param aiContext  AI traceability data required for the processing attempt record; never null
 */
public record NamingProposalReady(
        SourceDocumentCandidate candidate,
        NamingProposal proposal,
        AiAttemptContext aiContext) implements DocumentProcessingOutcome {

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