package de.gecheckt.pdf.umbenenner.application.port.out;

/**
 * Sealed interface representing the outcome of invoking an AI service.
 * <p>
 * Implementations allow the Application layer to distinguish between:
 * <ul>
 *   <li>Successful HTTP communication with a response body (which may still contain
 *       functionally invalid content, but is at least technically received)</li>
 *   <li>Technical failure (timeout, network error, endpoint unreachable, malformed response)</li>
 * </ul>
 * <p>
 * Permitted implementations:
 * <ul>
 *   <li>{@link AiInvocationSuccess} — HTTP call completed with a response body</li>
 *   <li>{@link AiInvocationTechnicalFailure} — HTTP call failed or no valid response was received</li>
 * </ul>
 * <p>
 * <strong>Critical distinction:</strong> A successful invocation means the HTTP request
 * was sent and a response was received, but the response content may still be unparseable
 * or semantically invalid. This is crucial for retry logic: a technical HTTP success
 * with unparseable JSON is different from a timeout or network error.
 */
public sealed interface AiInvocationResult
        permits AiInvocationSuccess, AiInvocationTechnicalFailure {
}
