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

import de.gecheckt.pdf.umbenenner.domain.model.DocumentFingerprint;
import de.gecheckt.pdf.umbenenner.domain.model.RunId;

/**
 * Sealed type carrying the correlation context for all document-related log entries.
 * <p>
 * The logging correlation rule distinguishes two phases of document processing:
 * <ol>
 *   <li><strong>Pre-fingerprint phase:</strong> Before a {@link DocumentFingerprint} has
 *       been successfully computed (e.g. the source file cannot be read for hashing),
 *       log entries are correlated via the batch run identifier and a stable candidate
 *       description derived from the candidate's own identifier (typically its source
 *       file path or name). Use {@link CandidateCorrelation}.</li>
 *   <li><strong>Post-fingerprint phase:</strong> Once the fingerprint has been
 *       successfully computed, all subsequent document-related log entries are correlated
 *       via the batch run identifier and the fingerprint. Use
 *       {@link FingerprintCorrelation}.</li>
 * </ol>
 * <p>
 * <strong>Architecture constraints:</strong>
 * <ul>
 *   <li>This type contains no filesystem ({@code Path}, {@code File}) or NIO types.</li>
 *   <li>This type introduces no additional persistence truth source.</li>
 *   <li>The correlation is a logging concern only and does not influence the processing
 *       outcome, retry decision, or persistence model.</li>
 * </ul>
 */
public sealed interface DocumentLogCorrelation {

    /**
     * Returns the batch run identifier shared by all log entries within one run.
     *
     * @return run identifier; never {@code null}
     */
    RunId runId();

    // -------------------------------------------------------------------------
    // Pre-fingerprint correlation
    // -------------------------------------------------------------------------

    /**
     * Correlation context available before a {@link DocumentFingerprint} has been
     * successfully computed.
     * <p>
     * Used when the fingerprint computation itself fails or when a log entry must be
     * emitted at the very start of candidate processing (before any hashing result is
     * available).
     * <p>
     * The {@code candidateDescription} is a stable, human-readable identifier for the
     * candidate derived from the candidate's own unique identifier — typically the
     * source file name or path representation. It must not change between log entries
     * for the same candidate within a single run.
     *
     * @param runId                batch run identifier; never {@code null}
     * @param candidateDescription stable human-readable candidate identifier;
     *                             never {@code null} or blank
     */
    record CandidateCorrelation(RunId runId, String candidateDescription)
            implements DocumentLogCorrelation {}

    // -------------------------------------------------------------------------
    // Post-fingerprint correlation
    // -------------------------------------------------------------------------

    /**
     * Correlation context available after a {@link DocumentFingerprint} has been
     * successfully computed.
     * <p>
     * Used for all document-related log entries from the point at which the fingerprint
     * is known. The fingerprint is the authoritative, content-stable document identity
     * and must appear in or be unambiguously derivable from every subsequent log entry
     * for this document.
     *
     * @param runId       batch run identifier; never {@code null}
     * @param fingerprint content-based document identity; never {@code null}
     */
    record FingerprintCorrelation(RunId runId, DocumentFingerprint fingerprint)
            implements DocumentLogCorrelation {}
}
