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

import de.gecheckt.pdf.umbenenner.domain.model.SourceDocumentCandidate;

/**
 * Outbound port for computing the content-based fingerprint of exactly one
 * processing candidate.
 * <p>
 * Implementations must derive the fingerprint <em>exclusively</em> from the binary
 * content of the file referenced by the candidate. File name, path, and metadata must
 * not influence the result.
 * <p>
 * <strong>Architecture boundary:</strong> All hashing logic and file I/O are confined
 * to the {@code adapter-out} implementation. This interface exposes no
 * {@code java.nio.file.Path}, {@code java.io.File}, or cryptographic types to Domain
 * or Application.
 * <p>
 * <strong>Failure semantics:</strong> Technical failures (unreadable file, I/O error)
 * are returned as {@link FingerprintTechnicalError} rather than thrown as exceptions.
 * A {@link FingerprintTechnicalError} result means no
 * {@link de.gecheckt.pdf.umbenenner.domain.model.DocumentFingerprint} is available
 * and the candidate cannot be identified; consequently no SQLite attempt record is
 * created for this candidate.
 *
 */
public interface FingerprintPort {

    /**
     * Computes the fingerprint for the given candidate.
     * <p>
     * This method never throws. All outcomes, including technical failures, are
     * encoded in the returned {@link FingerprintResult}.
     *
     * @param candidate the candidate whose file content is to be hashed; must not be null
     * @return {@link FingerprintSuccess} on success, or {@link FingerprintTechnicalError}
     *         on any infrastructure failure
     */
    FingerprintResult computeFingerprint(SourceDocumentCandidate candidate);
}
