package de.gecheckt.pdf.umbenenner.application.config;

import de.gecheckt.pdf.umbenenner.application.port.out.AiContentSensitivity;

/**
 * Minimal runtime configuration for the application layer.
 * <p>
 * Contains only the application-level runtime parameters that are needed during
 * batch document processing. Technical infrastructure configuration (paths, API keys,
 * persistence parameters, etc.) is kept in the bootstrap layer.
 * <p>
 * This intentionally small contract ensures the application layer depends only on
 * the configuration values it actually uses, following hexagonal architecture principles.
 *
 * <h2>Validation invariants</h2>
 * <ul>
 *   <li>{@link #maxPages()} must be &ge; 1.</li>
 *   <li>{@link #maxRetriesTransient()} must be &ge; 1. The value {@code 0} is invalid
 *       start configuration and must prevent the batch run from starting with exit
 *       code&nbsp;1.</li>
 *   <li>{@link #aiContentSensitivity()} must not be {@code null}. The safe default is
 *       {@link AiContentSensitivity#PROTECT_SENSITIVE_CONTENT}.</li>
 * </ul>
 *
 * <h2>AI content sensitivity</h2>
 * <p>
 * The {@link #aiContentSensitivity()} field is derived from the {@code log.ai.sensitive}
 * configuration property (default: {@code false}). It governs whether the complete AI raw
 * response and complete AI {@code reasoning} may be written to log files. Sensitive AI
 * content is always persisted in SQLite regardless of this setting; only log output is
 * affected.
 * <p>
 * The safe default ({@link AiContentSensitivity#PROTECT_SENSITIVE_CONTENT}) must be used
 * whenever {@code log.ai.sensitive} is absent, {@code false}, or set to any value other
 * than the explicit opt-in.
 */
public record RuntimeConfiguration(
        /**
         * Maximum number of pages a document can have to be processed.
         * Documents exceeding this limit are rejected during pre-checks.
         */
        int maxPages,

        /**
         * Maximum number of historised transient technical errors allowed per fingerprint
         * across all scheduler runs.
         * <p>
         * The attempt that causes the counter to reach this value finalises the document
         * to {@code FAILED_FINAL}. Must be an Integer &ge; 1; the value {@code 0} is
         * invalid start configuration.
         * <p>
         * Example: {@code maxRetriesTransient = 1} means the first transient error
         * immediately finalises the document.
         */
        int maxRetriesTransient,

        /**
         * Sensitivity decision governing whether AI-generated content may be written to log files.
         * <p>
         * Derived from the {@code log.ai.sensitive} configuration property. The default is
         * {@link AiContentSensitivity#PROTECT_SENSITIVE_CONTENT} (do not log sensitive content).
         * Only {@link AiContentSensitivity#LOG_SENSITIVE_CONTENT} is produced when
         * {@code log.ai.sensitive = true} is explicitly set.
         * <p>
         * Must not be {@code null}.
         */
        AiContentSensitivity aiContentSensitivity
)
{ }
