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

/**
 * Sealed interface representing the complete outcome of document processing.
 * <p>
 * This interface models all possible document outcomes:
 * <ul>
 *   <li>{@link PreCheckPassed}: Document passed all pre-checks</li>
 *   <li>{@link PreCheckFailed}: Document failed a pre-check (deterministic content error: no usable text or page limit exceeded)</li>
 *   <li>{@link TechnicalDocumentError}: Technical failure during candidate access or PDF extraction (I/O, access, parsing, etc.)</li>
 * </ul>
 * <p>
 * Design principles:
 * <ul>
 *   <li>Exhaustive: All document processing outcomes are covered</li>
 *   <li>Document-centric: Each outcome carries the source candidate for correlation and traceability</li>
 *   <li>No exceptions: Results are encoded in the type system</li>
 *   <li>Clear distinction: Deterministic content errors (PreCheckFailed) vs. technical failures (TechnicalDocumentError)</li>
 * </ul>
 * <p>
 * Error classification:
 * <ul>
 *   <li>PreCheckPassed: Extraction succeeded and all pre-checks passed (ready for further processing)</li>
 *   <li>PreCheckFailed: Extraction succeeded but deterministic content check failed (no usable text, page limit exceeded)</li>
 *   <li>TechnicalDocumentError: Extraction failed due to technical issue (I/O, file access, PDF parsing, etc.)</li>
 * </ul>
 */
public sealed interface DocumentProcessingOutcome
    permits PreCheckPassed, PreCheckFailed, TechnicalDocumentError,
            NamingProposalReady, AiTechnicalFailure, AiFunctionalFailure {
    // Marker interface; concrete implementations define structure
}