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

/**
 * Sealed interface representing the outcome of parsing an AI response into its JSON structure.
 * <p>
 * Implementations distinguish between:
 * <ul>
 *   <li>{@link AiResponseParsingSuccess} — JSON structure was parsed and required fields extracted</li>
 *   <li>{@link AiResponseParsingFailure} — JSON parsing failed or required fields are missing</li>
 * </ul>
 * <p>
 * <strong>Usage in the processing pipeline:</strong>
 * <ul>
 *   <li>Input: {@link AiRawResponse} from a successful HTTP invocation</li>
 *   <li>Operation: Parse the raw response body as JSON and extract required fields</li>
 *   <li>Output: Either a {@code ParsedAiResponse} (success) or a classified failure</li>
 * </ul>
 * <p>
 * This distinction is crucial for error classification: an unparseable JSON response
 * is a technical error (retryable), while a valid JSON with semantically invalid field
 * values is a functional error (deterministic).
 */
public sealed interface AiResponseParsingResult
        permits AiResponseParsingSuccess, AiResponseParsingFailure {
}
