M4 AP-001 Kernobjekte, Statusmodell und Port-Verträge präzisieren

.claude/settings.local.json

@@ -17,7 +17,8 @@
       "Bash(grep \"\\\\.java$\")",
       "Bash(mvn -q clean compile -DskipTests)",
       "Bash(mvn -q test)",
-      "Bash(mvn -q clean test)"
+      "Bash(mvn -q clean test)",
+      "Bash(./mvnw.cmd:*)"
     ]
   }
 }

pdf-umbenenner-application/src/main/java/de/gecheckt/pdf/umbenenner/application/port/out/DocumentKnownProcessable.java

@@ -0,0 +1,30 @@
+package de.gecheckt.pdf.umbenenner.application.port.out;
+
+import java.util.Objects;
+
+/**
+ * Lookup result indicating that a master record exists and the document is not yet terminal.
+ * <p>
+ * The document is known (fingerprint exists in the persistence store) but its overall
+ * status is neither {@link de.gecheckt.pdf.umbenenner.domain.model.ProcessingStatus#SUCCESS}
+ * nor {@link de.gecheckt.pdf.umbenenner.domain.model.ProcessingStatus#FAILED_FINAL}.
+ * The use case may continue with normal M4 processing using the provided record.
+ * <p>
+ * The existing {@link DocumentRecord} is supplied so the use case can inspect the
+ * current status, failure counters, and other fields required to apply M4 retry rules
+ * without an additional lookup.
+ *
+ * @param record the current master record for this document; never null
+ * @since M4-AP-001
+ */
+public record DocumentKnownProcessable(DocumentRecord record) implements DocumentRecordLookupResult {
+
+    /**
+     * Compact constructor validating the non-null contract.
+     *
+     * @throws NullPointerException if {@code record} is null
+     */
+    public DocumentKnownProcessable {
+        Objects.requireNonNull(record, "record must not be null");
+    }
+}

pdf-umbenenner-application/src/main/java/de/gecheckt/pdf/umbenenner/application/port/out/DocumentPersistenceException.java

@@ -0,0 +1,48 @@
+package de.gecheckt.pdf.umbenenner.application.port.out;
+
+/**
+ * Unchecked exception thrown by persistence write operations when a technical
+ * infrastructure failure prevents the operation from completing.
+ * <p>
+ * This exception is thrown by {@link DocumentRecordRepository} and
+ * {@link ProcessingAttemptRepository} write methods, and by
+ * {@link PersistenceSchemaInitializationPort#initializeSchema()}, when the underlying
+ * persistence layer (SQLite) cannot be reached or returns an unrecoverable error.
+ * <p>
+ * <strong>Batch run impact:</strong>
+ * <ul>
+ *   <li>If thrown during <em>schema initialisation</em> at startup, the run must abort
+ *       with exit code&nbsp;1.</li>
+ *   <li>If thrown during <em>per-document write operations</em>, the current candidate
+ *       is treated as a transient failure; the batch run continues with the remaining
+ *       candidates.</li>
+ * </ul>
+ * <p>
+ * The exception is <em>not</em> used for read operations; read failures are modelled
+ * as {@link PersistenceLookupTechnicalFailure} in the sealed
+ * {@link DocumentRecordLookupResult} hierarchy to allow exhaustive pattern matching
+ * at the call site.
+ *
+ * @since M4-AP-001
+ */
+public class DocumentPersistenceException extends RuntimeException {
+
+    /**
+     * Constructs a new {@code DocumentPersistenceException} with the given message.
+     *
+     * @param message human-readable description of the persistence failure
+     */
+    public DocumentPersistenceException(String message) {
+        super(message);
+    }
+
+    /**
+     * Constructs a new {@code DocumentPersistenceException} with message and cause.
+     *
+     * @param message human-readable description of the persistence failure
+     * @param cause   the underlying throwable that caused this failure
+     */
+    public DocumentPersistenceException(String message, Throwable cause) {
+        super(message, cause);
+    }
+}

pdf-umbenenner-application/src/main/java/de/gecheckt/pdf/umbenenner/application/port/out/DocumentRecord.java

@@ -0,0 +1,83 @@
+package de.gecheckt.pdf.umbenenner.application.port.out;
+
+import de.gecheckt.pdf.umbenenner.domain.model.DocumentFingerprint;
+import de.gecheckt.pdf.umbenenner.domain.model.ProcessingStatus;
+import de.gecheckt.pdf.umbenenner.domain.model.SourceDocumentLocator;
+
+import java.time.Instant;
+import java.util.Objects;
+
+/**
+ * Application-facing representation of the document master record (Dokument-Stammsatz).
+ * <p>
+ * One {@code DocumentRecord} exists per unique {@link DocumentFingerprint}. It carries
+ * the current overall status, failure counters, and the most recently known source
+ * location of the document.
+ * <p>
+ * <strong>Architecture boundary:</strong> This type contains no SQLite or JDBC types.
+ * Mapping between {@code DocumentRecord} and the persistence layer is performed
+ * exclusively by the repository adapter in {@code adapter-out}.
+ * <p>
+ * <strong>M4 field semantics:</strong>
+ * <ul>
+ *   <li>{@link #fingerprint()} — primary identity; never changes for a given record.</li>
+ *   <li>{@link #lastKnownSourceLocator()} — opaque locator used by adapters; the
+ *       application passes it through without interpreting the value.</li>
+ *   <li>{@link #lastKnownSourceFileName()} — human-readable file name for logging and
+ *       diagnostics; not used for identity.</li>
+ *   <li>{@link #overallStatus()} — the current terminal or active status of the document
+ *       across all runs. See {@link ProcessingStatus} for semantics.</li>
+ *   <li>{@link #failureCounters()} — independent counters for content and transient errors;
+ *       never increased by skip events.</li>
+ *   <li>{@link #lastFailureInstant()} — timestamp of the most recent failure; {@code null}
+ *       if no failure has been recorded yet.</li>
+ *   <li>{@link #lastSuccessInstant()} — timestamp of the successful processing; {@code null}
+ *       if the document has never been processed successfully.</li>
+ *   <li>{@link #createdAt()} — timestamp when this master record was first created.</li>
+ *   <li>{@link #updatedAt()} — timestamp of the most recent update to this master record.</li>
+ * </ul>
+ * <p>
+ * <strong>Not included in M4:</strong> target path, target file name, AI-related fields.
+ * These are added in later milestones.
+ *
+ * @param fingerprint             content-based identity; never null
+ * @param lastKnownSourceLocator  opaque locator to the physical source file; never null
+ * @param lastKnownSourceFileName file name at the time of the last known access; never null or blank
+ * @param overallStatus           current processing status; never null
+ * @param failureCounters         counters for content and transient errors; never null
+ * @param lastFailureInstant      timestamp of the most recent failure, or {@code null}
+ * @param lastSuccessInstant      timestamp of the successful processing, or {@code null}
+ * @param createdAt               timestamp when this record was first created; never null
+ * @param updatedAt               timestamp of the most recent update; never null
+ * @since M4-AP-001
+ */
+public record DocumentRecord(
+        DocumentFingerprint fingerprint,
+        SourceDocumentLocator lastKnownSourceLocator,
+        String lastKnownSourceFileName,
+        ProcessingStatus overallStatus,
+        FailureCounters failureCounters,
+        Instant lastFailureInstant,
+        Instant lastSuccessInstant,
+        Instant createdAt,
+        Instant updatedAt) {
+
+    /**
+     * Compact constructor validating mandatory non-null fields.
+     *
+     * @throws NullPointerException     if any mandatory field is null
+     * @throws IllegalArgumentException if {@code lastKnownSourceFileName} is blank
+     */
+    public DocumentRecord {
+        Objects.requireNonNull(fingerprint, "fingerprint must not be null");
+        Objects.requireNonNull(lastKnownSourceLocator, "lastKnownSourceLocator must not be null");
+        Objects.requireNonNull(lastKnownSourceFileName, "lastKnownSourceFileName must not be null");
+        if (lastKnownSourceFileName.isBlank()) {
+            throw new IllegalArgumentException("lastKnownSourceFileName must not be blank");
+        }
+        Objects.requireNonNull(overallStatus, "overallStatus must not be null");
+        Objects.requireNonNull(failureCounters, "failureCounters must not be null");
+        Objects.requireNonNull(createdAt, "createdAt must not be null");
+        Objects.requireNonNull(updatedAt, "updatedAt must not be null");
+    }
+}

pdf-umbenenner-application/src/main/java/de/gecheckt/pdf/umbenenner/application/port/out/DocumentRecordLookupResult.java

@@ -0,0 +1,32 @@
+package de.gecheckt.pdf.umbenenner.application.port.out;
+
+/**
+ * Sealed result type for a document master record lookup via {@link DocumentRecordRepository}.
+ * <p>
+ * The use case uses this result to make the per-document processing decision in M4
+ * without additional assumptions:
+ * <ul>
+ *   <li>{@link DocumentUnknown} — the fingerprint is not yet in the persistence store;
+ *       the document must be processed for the first time.</li>
+ *   <li>{@link DocumentKnownProcessable} — a master record exists but the document is
+ *       not in a terminal state; normal processing may continue.</li>
+ *   <li>{@link DocumentTerminalSuccess} — the document was already processed
+ *       successfully; skip with {@link de.gecheckt.pdf.umbenenner.domain.model.ProcessingStatus#SKIPPED_ALREADY_PROCESSED}.</li>
+ *   <li>{@link DocumentTerminalFinalFailure} — the document has finally failed; skip
+ *       with {@link de.gecheckt.pdf.umbenenner.domain.model.ProcessingStatus#SKIPPED_FINAL_FAILURE}.</li>
+ *   <li>{@link PersistenceLookupTechnicalFailure} — the lookup itself failed due to a
+ *       technical infrastructure problem; the document cannot be processed in this run.</li>
+ * </ul>
+ * <p>
+ * <strong>Architecture boundary:</strong> No JDBC, SQLite, or filesystem types appear
+ * in this sealed hierarchy or in any of its implementations.
+ *
+ * @since M4-AP-001
+ */
+public sealed interface DocumentRecordLookupResult
+        permits DocumentUnknown,
+                DocumentKnownProcessable,
+                DocumentTerminalSuccess,
+                DocumentTerminalFinalFailure,
+                PersistenceLookupTechnicalFailure {
+}

pdf-umbenenner-application/src/main/java/de/gecheckt/pdf/umbenenner/application/port/out/DocumentRecordRepository.java

@@ -0,0 +1,72 @@
+package de.gecheckt.pdf.umbenenner.application.port.out;
+
+import de.gecheckt.pdf.umbenenner.domain.model.DocumentFingerprint;
+
+/**
+ * Outbound port for reading and writing the document master record (Dokument-Stammsatz).
+ * <p>
+ * One master record exists per unique {@link DocumentFingerprint}. The repository is
+ * responsible for the persistence of {@link DocumentRecord} values; it holds no
+ * business logic about retry rules, skip decisions, or status transitions.
+ * <p>
+ * <strong>Lookup semantics:</strong>
+ * {@link #findByFingerprint(DocumentFingerprint)} returns a sealed
+ * {@link DocumentRecordLookupResult} that allows the use case to distinguish exhaustively
+ * between an unknown document, a known processable document, a terminal success, a
+ * terminal final failure, and a technical persistence failure — without additional
+ * assumptions or null checks.
+ * <p>
+ * <strong>Write semantics:</strong>
+ * <ul>
+ *   <li>{@link #create(DocumentRecord)} inserts a new record for a previously unknown
+ *       document.</li>
+ *   <li>{@link #update(DocumentRecord)} replaces the mutable fields of an existing
+ *       record identified by its fingerprint.</li>
+ * </ul>
+ * Both write methods throw {@link DocumentPersistenceException} on technical failure.
+ * <p>
+ * <strong>Architecture boundary:</strong> No JDBC, SQLite, or filesystem types appear
+ * in this interface or in any type it references. Mapping to and from the persistence
+ * schema is the exclusive responsibility of the adapter implementation.
+ *
+ * @since M4-AP-001
+ */
+public interface DocumentRecordRepository {
+
+    /**
+     * Looks up the master record for the given fingerprint.
+     * <p>
+     * Returns a {@link DocumentRecordLookupResult} that encodes all possible outcomes
+     * including technical failures; this method never throws.
+     *
+     * @param fingerprint the content-based document identity to look up; must not be null
+     * @return {@link DocumentUnknown} if no record exists,
+     *         {@link DocumentKnownProcessable} if the document is known but not terminal,
+     *         {@link DocumentTerminalSuccess} if the document succeeded,
+     *         {@link DocumentTerminalFinalFailure} if the document finally failed, or
+     *         {@link PersistenceLookupTechnicalFailure} if the lookup itself failed
+     */
+    DocumentRecordLookupResult findByFingerprint(DocumentFingerprint fingerprint);
+
+    /**
+     * Persists a new master record for a previously unknown document.
+     * <p>
+     * The fingerprint within {@code record} must not yet exist in the persistence store.
+     *
+     * @param record the new master record to persist; must not be null
+     * @throws DocumentPersistenceException if the insert fails due to a technical error
+     */
+    void create(DocumentRecord record);
+
+    /**
+     * Updates the mutable fields of an existing master record.
+     * <p>
+     * The record is identified by its {@link DocumentFingerprint}; the fingerprint
+     * itself is never changed. Mutable fields include the overall status, failure
+     * counters, last known source location, and all timestamp fields.
+     *
+     * @param record the updated master record; must not be null; fingerprint must exist
+     * @throws DocumentPersistenceException if the update fails due to a technical error
+     */
+    void update(DocumentRecord record);
+}

pdf-umbenenner-application/src/main/java/de/gecheckt/pdf/umbenenner/application/port/out/DocumentTerminalFinalFailure.java

@@ -0,0 +1,30 @@
+package de.gecheckt.pdf.umbenenner.application.port.out;
+
+import java.util.Objects;
+
+/**
+ * Lookup result indicating that the document has finally and irrecoverably failed.
+ * <p>
+ * The master record's overall status is
+ * {@link de.gecheckt.pdf.umbenenner.domain.model.ProcessingStatus#FAILED_FINAL}.
+ * The use case must skip further processing and historise a
+ * {@link de.gecheckt.pdf.umbenenner.domain.model.ProcessingStatus#SKIPPED_FINAL_FAILURE}
+ * attempt. No failure counters are changed.
+ * <p>
+ * The existing {@link DocumentRecord} is supplied so the use case can read the
+ * current record for the skip attempt historisation without an additional lookup.
+ *
+ * @param record the current (finally failed) master record for this document; never null
+ * @since M4-AP-001
+ */
+public record DocumentTerminalFinalFailure(DocumentRecord record) implements DocumentRecordLookupResult {
+
+    /**
+     * Compact constructor validating the non-null contract.
+     *
+     * @throws NullPointerException if {@code record} is null
+     */
+    public DocumentTerminalFinalFailure {
+        Objects.requireNonNull(record, "record must not be null");
+    }
+}

pdf-umbenenner-application/src/main/java/de/gecheckt/pdf/umbenenner/application/port/out/DocumentTerminalSuccess.java

@@ -0,0 +1,30 @@
+package de.gecheckt.pdf.umbenenner.application.port.out;
+
+import java.util.Objects;
+
+/**
+ * Lookup result indicating that the document was already successfully processed.
+ * <p>
+ * The master record's overall status is
+ * {@link de.gecheckt.pdf.umbenenner.domain.model.ProcessingStatus#SUCCESS}.
+ * The use case must skip further processing and historise a
+ * {@link de.gecheckt.pdf.umbenenner.domain.model.ProcessingStatus#SKIPPED_ALREADY_PROCESSED}
+ * attempt. No failure counters are changed.
+ * <p>
+ * The existing {@link DocumentRecord} is supplied so the use case can read the
+ * current record for the skip attempt historisation without an additional lookup.
+ *
+ * @param record the current (successful) master record for this document; never null
+ * @since M4-AP-001
+ */
+public record DocumentTerminalSuccess(DocumentRecord record) implements DocumentRecordLookupResult {
+
+    /**
+     * Compact constructor validating the non-null contract.
+     *
+     * @throws NullPointerException if {@code record} is null
+     */
+    public DocumentTerminalSuccess {
+        Objects.requireNonNull(record, "record must not be null");
+    }
+}

pdf-umbenenner-application/src/main/java/de/gecheckt/pdf/umbenenner/application/port/out/DocumentUnknown.java

@@ -0,0 +1,14 @@
+package de.gecheckt.pdf.umbenenner.application.port.out;
+
+/**
+ * Lookup result indicating that the fingerprint is not yet present in the persistence store.
+ * <p>
+ * The document has never been processed before. The use case must create a new
+ * {@link DocumentRecord} and proceed with normal M4 processing.
+ * <p>
+ * This variant carries no data because there is no existing record to return.
+ *
+ * @since M4-AP-001
+ */
+public record DocumentUnknown() implements DocumentRecordLookupResult {
+}

pdf-umbenenner-application/src/main/java/de/gecheckt/pdf/umbenenner/application/port/out/FailureCounters.java

@@ -0,0 +1,75 @@
+package de.gecheckt.pdf.umbenenner.application.port.out;
+
+/**
+ * Immutable snapshot of the two independent failure counters maintained per document.
+ * <p>
+ * M4 tracks two distinct counters separately because they drive different retry rules:
+ * <ul>
+ *   <li><strong>Content error counter</strong> ({@link #contentErrorCount()}):
+ *       counts how many times a deterministic content error occurred for this document
+ *       (no usable text, page limit exceeded). At count&nbsp;1 the document is
+ *       {@code FAILED_RETRYABLE}; at count&nbsp;2 it becomes {@code FAILED_FINAL}.
+ *       Skip events do <em>not</em> increase this counter.</li>
+ *   <li><strong>Transient error counter</strong> ({@link #transientErrorCount()}):
+ *       counts how many times a technical infrastructure error occurred after a
+ *       successful fingerprint was computed. The document remains
+ *       {@code FAILED_RETRYABLE} until the configured maximum is reached in later
+ *       milestones. Skip events do <em>not</em> increase this counter.</li>
+ * </ul>
+ * <p>
+ * A freshly discovered document starts with both counters at zero.
+ * Counters are only written by the repository layer on the instructions of the
+ * application use case; they never change as a side-effect of a read operation.
+ *
+ * @param contentErrorCount  number of deterministic content errors recorded so far;
+ *                           must be &gt;= 0
+ * @param transientErrorCount number of transient technical errors recorded so far;
+ *                            must be &gt;= 0
+ * @since M4-AP-001
+ */
+public record FailureCounters(int contentErrorCount, int transientErrorCount) {
+
+    /**
+     * Compact constructor validating that neither counter is negative.
+     *
+     * @throws IllegalArgumentException if either counter is negative
+     */
+    public FailureCounters {
+        if (contentErrorCount < 0) {
+            throw new IllegalArgumentException(
+                    "contentErrorCount must be >= 0, but was: " + contentErrorCount);
+        }
+        if (transientErrorCount < 0) {
+            throw new IllegalArgumentException(
+                    "transientErrorCount must be >= 0, but was: " + transientErrorCount);
+        }
+    }
+
+    /**
+     * Returns a {@code FailureCounters} instance with both counters at zero.
+     * Use this when initialising a master record for a newly discovered document.
+     *
+     * @return zero-value counters
+     */
+    public static FailureCounters zero() {
+        return new FailureCounters(0, 0);
+    }
+
+    /**
+     * Returns a copy with the content error counter incremented by one.
+     *
+     * @return new instance with {@code contentErrorCount + 1}
+     */
+    public FailureCounters withIncrementedContentErrorCount() {
+        return new FailureCounters(contentErrorCount + 1, transientErrorCount);
+    }
+
+    /**
+     * Returns a copy with the transient error counter incremented by one.
+     *
+     * @return new instance with {@code transientErrorCount + 1}
+     */
+    public FailureCounters withIncrementedTransientErrorCount() {
+        return new FailureCounters(contentErrorCount, transientErrorCount + 1);
+    }
+}

pdf-umbenenner-application/src/main/java/de/gecheckt/pdf/umbenenner/application/port/out/FingerprintPort.java

@@ -0,0 +1,40 @@
+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 in M4.
+ *
+ * @since M4-AP-001
+ */
+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);
+}

pdf-umbenenner-application/src/main/java/de/gecheckt/pdf/umbenenner/application/port/out/FingerprintResult.java

@@ -0,0 +1,20 @@
+package de.gecheckt.pdf.umbenenner.application.port.out;
+
+/**
+ * Sealed result type for a fingerprint computation attempt via {@link FingerprintPort}.
+ * <p>
+ * Exhaustive variants:
+ * <ul>
+ *   <li>{@link FingerprintSuccess} — fingerprint computed successfully.</li>
+ *   <li>{@link FingerprintTechnicalError} — fingerprint computation failed due to a
+ *       technical infrastructure problem (e.g. I/O error, file no longer accessible).</li>
+ * </ul>
+ * <p>
+ * <strong>Historisation impact:</strong> If the result is {@link FingerprintTechnicalError},
+ * the document cannot be identified and <em>no</em> SQLite attempt record is created.
+ * The failure is treated as a non-identifiable run event.
+ *
+ * @since M4-AP-001
+ */
+public sealed interface FingerprintResult permits FingerprintSuccess, FingerprintTechnicalError {
+}

pdf-umbenenner-application/src/main/java/de/gecheckt/pdf/umbenenner/application/port/out/FingerprintSuccess.java

@@ -0,0 +1,27 @@
+package de.gecheckt.pdf.umbenenner.application.port.out;
+
+import de.gecheckt.pdf.umbenenner.domain.model.DocumentFingerprint;
+
+import java.util.Objects;
+
+/**
+ * Successful outcome of a fingerprint computation.
+ * <p>
+ * Carries the computed {@link DocumentFingerprint} that uniquely identifies the
+ * document by its content. The fingerprint can now be used as the primary key
+ * for all subsequent persistence operations in M4.
+ *
+ * @param fingerprint the successfully computed fingerprint; never null
+ * @since M4-AP-001
+ */
+public record FingerprintSuccess(DocumentFingerprint fingerprint) implements FingerprintResult {
+
+    /**
+     * Compact constructor validating the non-null contract.
+     *
+     * @throws NullPointerException if {@code fingerprint} is null
+     */
+    public FingerprintSuccess {
+        Objects.requireNonNull(fingerprint, "fingerprint must not be null");
+    }
+}

pdf-umbenenner-application/src/main/java/de/gecheckt/pdf/umbenenner/application/port/out/FingerprintTechnicalError.java

@@ -0,0 +1,34 @@
+package de.gecheckt.pdf.umbenenner.application.port.out;
+
+import java.util.Objects;
+
+/**
+ * Technical failure during fingerprint computation.
+ * <p>
+ * Returned by {@link FingerprintPort} when the adapter cannot read the file content
+ * to compute the SHA-256 hash. Typical causes include the file no longer being
+ * accessible between candidate discovery and hashing, I/O errors, or permission issues.
+ * <p>
+ * <strong>Historisation impact:</strong> Because no {@link de.gecheckt.pdf.umbenenner.domain.model.DocumentFingerprint}
+ * could be produced, this failure is <em>not</em> historised in SQLite. No
+ * {@link ProcessingAttempt} is created.
+ *
+ * @param errorMessage human-readable description of the failure; never null or blank
+ * @param cause        the underlying throwable, or {@code null} if not available
+ * @since M4-AP-001
+ */
+public record FingerprintTechnicalError(String errorMessage, Throwable cause) implements FingerprintResult {
+
+    /**
+     * Compact constructor validating the error message.
+     *
+     * @throws NullPointerException     if {@code errorMessage} is null
+     * @throws IllegalArgumentException if {@code errorMessage} is blank
+     */
+    public FingerprintTechnicalError {
+        Objects.requireNonNull(errorMessage, "errorMessage must not be null");
+        if (errorMessage.isBlank()) {
+            throw new IllegalArgumentException("errorMessage must not be blank");
+        }
+    }
+}

pdf-umbenenner-application/src/main/java/de/gecheckt/pdf/umbenenner/application/port/out/PersistenceLookupTechnicalFailure.java

@@ -0,0 +1,36 @@
+package de.gecheckt.pdf.umbenenner.application.port.out;
+
+import java.util.Objects;
+
+/**
+ * Lookup result indicating that the master record lookup itself failed due to a
+ * technical infrastructure problem.
+ * <p>
+ * The persistence layer (SQLite) could not be reached or returned an unexpected error.
+ * The document state is unknown; the use case must treat this candidate as a
+ * transient technical failure for this run and must not attempt to write any attempt
+ * record (since the underlying persistence is unavailable).
+ * <p>
+ * This variant is distinct from a business-level "document not found" outcome
+ * ({@link DocumentUnknown}): here, the lookup operation itself failed.
+ *
+ * @param errorMessage human-readable description of the persistence failure; never null or blank
+ * @param cause        the underlying throwable, or {@code null} if not available
+ * @since M4-AP-001
+ */
+public record PersistenceLookupTechnicalFailure(String errorMessage, Throwable cause)
+        implements DocumentRecordLookupResult {
+
+    /**
+     * Compact constructor validating the error message.
+     *
+     * @throws NullPointerException     if {@code errorMessage} is null
+     * @throws IllegalArgumentException if {@code errorMessage} is blank
+     */
+    public PersistenceLookupTechnicalFailure {
+        Objects.requireNonNull(errorMessage, "errorMessage must not be null");
+        if (errorMessage.isBlank()) {
+            throw new IllegalArgumentException("errorMessage must not be blank");
+        }
+    }
+}

pdf-umbenenner-application/src/main/java/de/gecheckt/pdf/umbenenner/application/port/out/PersistenceSchemaInitializationPort.java

@@ -0,0 +1,40 @@
+package de.gecheckt.pdf.umbenenner.application.port.out;
+
+/**
+ * Outbound port for initialising the SQLite persistence schema at program startup.
+ * <p>
+ * This port is invoked exactly once per program run, <em>before</em> the batch
+ * document processing loop begins. The initialisation must ensure that all tables,
+ * indices, and constraints required for M4 persistence are present in the SQLite file.
+ * <p>
+ * <strong>Timing:</strong> The adapter implementation must perform the schema
+ * initialisation eagerly and synchronously. Lazy or deferred initialisation during
+ * the document processing loop is not the intent of this port.
+ * <p>
+ * <strong>Failure handling:</strong> If the schema cannot be initialised, the
+ * implementation must throw {@link DocumentPersistenceException}. The bootstrap
+ * layer must catch this exception and abort the run with exit code&nbsp;1.
+ * <p>
+ * <strong>Idempotency:</strong> Calling {@link #initializeSchema()} on a database
+ * that already has the correct schema must succeed without error (e.g. via
+ * {@code CREATE TABLE IF NOT EXISTS} semantics).
+ * <p>
+ * <strong>Architecture boundary:</strong> No JDBC, SQLite, or filesystem types appear
+ * in this interface. All schema DDL and connection management are confined to the
+ * {@code adapter-out} implementation.
+ *
+ * @since M4-AP-001
+ */
+public interface PersistenceSchemaInitializationPort {
+
+    /**
+     * Creates or verifies the M4 persistence schema.
+     * <p>
+     * Must be called once at program start, before any document processing begins.
+     * The method must be idempotent: calling it on an already-initialised database
+     * must not fail or alter existing data.
+     *
+     * @throws DocumentPersistenceException if the schema cannot be created or verified
+     */
+    void initializeSchema();
+}

pdf-umbenenner-application/src/main/java/de/gecheckt/pdf/umbenenner/application/port/out/ProcessingAttempt.java

@@ -0,0 +1,88 @@
+package de.gecheckt.pdf.umbenenner.application.port.out;
+
+import de.gecheckt.pdf.umbenenner.domain.model.DocumentFingerprint;
+import de.gecheckt.pdf.umbenenner.domain.model.ProcessingStatus;
+import de.gecheckt.pdf.umbenenner.domain.model.RunId;
+
+import java.time.Instant;
+import java.util.Objects;
+
+/**
+ * Application-facing representation of exactly one historised processing attempt
+ * (Versuchshistorie-Eintrag) for an identified document.
+ * <p>
+ * <strong>Historisation boundary (M4):</strong> Only attempts for documents whose
+ * {@link DocumentFingerprint} was successfully computed are historised. Failures that
+ * occur <em>before</em> the fingerprint is available (e.g. the source file is
+ * unreadable before hashing) are <em>not</em> represented by a {@code ProcessingAttempt}
+ * and are <em>not</em> written to SQLite.
+ * <p>
+ * <strong>Attempt number semantics:</strong> The attempt number starts at&nbsp;1 for the
+ * first historised attempt per fingerprint and increases monotonically by 1 for every
+ * subsequent attempt, including skip attempts
+ * ({@link ProcessingStatus#SKIPPED_ALREADY_PROCESSED},
+ * {@link ProcessingStatus#SKIPPED_FINAL_FAILURE}).
+ * <p>
+ * <strong>Field semantics:</strong>
+ * <ul>
+ *   <li>{@link #fingerprint()} — foreign key to the document master record.</li>
+ *   <li>{@link #runId()} — identifies the batch run during which this attempt occurred.</li>
+ *   <li>{@link #attemptNumber()} — monotonically increasing per fingerprint; assigned
+ *       before the attempt is recorded.</li>
+ *   <li>{@link #startedAt()} — wall-clock timestamp when processing of this candidate
+ *       began in this run.</li>
+ *   <li>{@link #endedAt()} — wall-clock timestamp when processing completed (success,
+ *       failure, or skip).</li>
+ *   <li>{@link #status()} — outcome status of this specific attempt.</li>
+ *   <li>{@link #failureClass()} — short classification of the failure (e.g. enum constant
+ *       name or exception class name); {@code null} for successful or skip attempts.</li>
+ *   <li>{@link #failureMessage()} — human-readable failure description; {@code null} for
+ *       successful or skip attempts.</li>
+ *   <li>{@link #retryable()} — {@code true} if the failure is considered retryable in a
+ *       later run; {@code false} for final failures, successes, and skip attempts.</li>
+ * </ul>
+ * <p>
+ * <strong>Not included in M4:</strong> model name, prompt identifier, AI raw response,
+ * AI reasoning, resolved date, date source, final title, final target file name.
+ * These fields are added in later milestones (M5+).
+ *
+ * @param fingerprint    content-based document identity; never null
+ * @param runId          identifier of the batch run; never null
+ * @param attemptNumber  monotonic sequence number per fingerprint; must be &gt;= 1
+ * @param startedAt      start of this processing attempt; never null
+ * @param endedAt        end of this processing attempt; never null
+ * @param status         outcome status of this attempt; never null
+ * @param failureClass   failure classification, or {@code null} for non-failure statuses
+ * @param failureMessage failure description, or {@code null} for non-failure statuses
+ * @param retryable      whether this failure should be retried in a later run
+ * @since M4-AP-001
+ */
+public record ProcessingAttempt(
+        DocumentFingerprint fingerprint,
+        RunId runId,
+        int attemptNumber,
+        Instant startedAt,
+        Instant endedAt,
+        ProcessingStatus status,
+        String failureClass,
+        String failureMessage,
+        boolean retryable) {
+
+    /**
+     * Compact constructor validating mandatory non-null fields and numeric constraints.
+     *
+     * @throws NullPointerException     if any mandatory field is null
+     * @throws IllegalArgumentException if {@code attemptNumber} is less than 1
+     */
+    public ProcessingAttempt {
+        Objects.requireNonNull(fingerprint, "fingerprint must not be null");
+        Objects.requireNonNull(runId, "runId must not be null");
+        if (attemptNumber < 1) {
+            throw new IllegalArgumentException(
+                    "attemptNumber must be >= 1, but was: " + attemptNumber);
+        }
+        Objects.requireNonNull(startedAt, "startedAt must not be null");
+        Objects.requireNonNull(endedAt, "endedAt must not be null");
+        Objects.requireNonNull(status, "status must not be null");
+    }
+}

pdf-umbenenner-application/src/main/java/de/gecheckt/pdf/umbenenner/application/port/out/ProcessingAttemptRepository.java

@@ -0,0 +1,70 @@
+package de.gecheckt.pdf.umbenenner.application.port.out;
+
+import de.gecheckt.pdf.umbenenner.domain.model.DocumentFingerprint;
+
+import java.util.List;
+
+/**
+ * Outbound port for writing and reading the processing attempt history
+ * (Versuchshistorie).
+ * <p>
+ * Every historisable processing attempt for an <em>identified</em> document results
+ * in exactly one {@link ProcessingAttempt} record written via {@link #save(ProcessingAttempt)}.
+ * <p>
+ * <strong>Historisation boundary:</strong> Only attempts with a successfully computed
+ * {@link de.gecheckt.pdf.umbenenner.domain.model.DocumentFingerprint} are historised.
+ * Failures that occur before the fingerprint is available are <em>not</em> recorded
+ * through this port.
+ * <p>
+ * <strong>Attempt number semantics:</strong>
+ * Attempt numbers start at&nbsp;1 per fingerprint and increase monotonically by&nbsp;1
+ * for every saved attempt, including skip attempts. The use case calls
+ * {@link #loadNextAttemptNumber(DocumentFingerprint)} to obtain the correct sequence
+ * number before constructing a {@link ProcessingAttempt}.
+ * <p>
+ * <strong>Architecture boundary:</strong> No JDBC, SQLite, or filesystem types appear
+ * in this interface. Mapping to and from the persistence schema is the exclusive
+ * responsibility of the adapter implementation.
+ *
+ * @since M4-AP-001
+ */
+public interface ProcessingAttemptRepository {
+
+    /**
+     * Returns the attempt number to assign to the <em>next</em> attempt for the given
+     * fingerprint.
+     * <p>
+     * If no prior attempts exist for the fingerprint, returns&nbsp;1.
+     * Otherwise returns the current maximum attempt number plus&nbsp;1.
+     *
+     * @param fingerprint the document identity; must not be null
+     * @return the next monotonic attempt number; always &gt;= 1
+     * @throws DocumentPersistenceException if the query fails due to a technical error
+     */
+    int loadNextAttemptNumber(DocumentFingerprint fingerprint);
+
+    /**
+     * Persists exactly one processing attempt record.
+     * <p>
+     * The {@link ProcessingAttempt#attemptNumber()} must have been obtained from
+     * {@link #loadNextAttemptNumber(DocumentFingerprint)} in the same run to guarantee
+     * monotonic ordering.
+     *
+     * @param attempt the attempt to persist; must not be null
+     * @throws DocumentPersistenceException if the insert fails due to a technical error
+     */
+    void save(ProcessingAttempt attempt);
+
+    /**
+     * Returns all historised attempts for the given fingerprint, ordered by
+     * {@link ProcessingAttempt#attemptNumber()} ascending.
+     * <p>
+     * Returns an empty list if no attempts have been recorded yet.
+     * Intended for use in tests and diagnostics; not required on the primary batch path.
+     *
+     * @param fingerprint the document identity; must not be null
+     * @return immutable list of attempts, ordered by attempt number; never null
+     * @throws DocumentPersistenceException if the query fails due to a technical error
+     */
+    List<ProcessingAttempt> findAllByFingerprint(DocumentFingerprint fingerprint);
+}

pdf-umbenenner-application/src/main/java/de/gecheckt/pdf/umbenenner/application/port/out/package-info.java

@@ -22,12 +22,40 @@
  *       — Extract text content and page count from a single PDF</li>
  * </ul>
  * <p>
+ * M4-AP-001 ports:
+ * <ul>
+ *   <li>{@link de.gecheckt.pdf.umbenenner.application.port.out.FingerprintPort}
+ *       — Compute the content-based SHA-256 fingerprint of a processing candidate</li>
+ *   <li>{@link de.gecheckt.pdf.umbenenner.application.port.out.DocumentRecordRepository}
+ *       — Read and write the document master record (Dokument-Stammsatz)</li>
+ *   <li>{@link de.gecheckt.pdf.umbenenner.application.port.out.ProcessingAttemptRepository}
+ *       — Write and read the per-document attempt history (Versuchshistorie)</li>
+ *   <li>{@link de.gecheckt.pdf.umbenenner.application.port.out.PersistenceSchemaInitializationPort}
+ *       — Initialise the SQLite schema at program startup</li>
+ * </ul>
+ * <p>
+ * M4-AP-001 value types and result types:
+ * <ul>
+ *   <li>{@link de.gecheckt.pdf.umbenenner.application.port.out.FailureCounters}
+ *       — Immutable snapshot of content-error and transient-error counters per document</li>
+ *   <li>{@link de.gecheckt.pdf.umbenenner.application.port.out.DocumentRecord}
+ *       — Application-facing representation of the document master record</li>
+ *   <li>{@link de.gecheckt.pdf.umbenenner.application.port.out.ProcessingAttempt}
+ *       — Application-facing representation of one historised processing attempt</li>
+ *   <li>{@link de.gecheckt.pdf.umbenenner.application.port.out.FingerprintResult}
+ *       — Sealed result of a fingerprint computation (success or technical error)</li>
+ *   <li>{@link de.gecheckt.pdf.umbenenner.application.port.out.DocumentRecordLookupResult}
+ *       — Sealed result of a master record lookup (unknown / processable / terminal / failure)</li>
+ * </ul>
+ * <p>
  * Exception types:
  * <ul>
  *   <li>{@link de.gecheckt.pdf.umbenenner.application.port.out.RunLockUnavailableException}
  *       — Thrown when run lock cannot be acquired (another instance running) (M2)</li>
  *   <li>{@link de.gecheckt.pdf.umbenenner.application.port.out.SourceDocumentAccessException}
  *       — Thrown when source folder cannot be read or accessed (M3)</li>
+ *   <li>{@link de.gecheckt.pdf.umbenenner.application.port.out.DocumentPersistenceException}
+ *       — Thrown when a persistence write operation or schema init fails (M4)</li>
  * </ul>
  * <p>
  * Architecture Rule: Outbound ports are implementation-agnostic and contain no business logic.

pdf-umbenenner-domain/src/main/java/de/gecheckt/pdf/umbenenner/domain/model/DocumentFingerprint.java

@@ -0,0 +1,51 @@
+package de.gecheckt.pdf.umbenenner.domain.model;
+
+import java.util.Objects;
+
+/**
+ * Unique, stable identity of a document derived exclusively from its binary content.
+ * <p>
+ * A {@code DocumentFingerprint} is computed once per file read and used as the primary
+ * key for all subsequent persistence lookups and history entries. It is independent of
+ * the file name, path, or any metadata — only the raw file content determines the value.
+ * <p>
+ * <strong>Identification semantics (M4):</strong>
+ * <ul>
+ *   <li>Two files with identical content have the same fingerprint and are treated as
+ *       the same document, regardless of their location or name.</li>
+ *   <li>A file whose content has changed produces a different fingerprint and is treated
+ *       as a new, independent document (new processing record).</li>
+ * </ul>
+ * <p>
+ * <strong>Architecture boundary:</strong> The hashing algorithm (SHA-256) and all
+ * file I/O required to compute the fingerprint are strictly confined to the
+ * {@code adapter-out} layer. Domain and Application only hold and compare the resulting
+ * hex string; they never access the filesystem or perform cryptographic operations.
+ * <p>
+ * <strong>Pre-fingerprint failures:</strong> If computing the fingerprint fails
+ * (e.g. due to an I/O error), no {@code DocumentFingerprint} is created and the failure
+ * is not historised in SQLite. The attempt is treated as a non-identifiable run event,
+ * not as a documentable processing attempt.
+ *
+ * @param sha256Hex lowercase hex encoding of the SHA-256 digest (exactly 64 characters,
+ *                  characters {@code [0-9a-f]})
+ * @since M4-AP-001
+ */
+public record DocumentFingerprint(String sha256Hex) {
+
+    /**
+     * Compact constructor that validates the hex string format.
+     *
+     * @param sha256Hex lowercase hex encoding of the SHA-256 digest
+     * @throws NullPointerException     if {@code sha256Hex} is null
+     * @throws IllegalArgumentException if {@code sha256Hex} is not exactly 64 lowercase hex characters
+     */
+    public DocumentFingerprint {
+        Objects.requireNonNull(sha256Hex, "sha256Hex must not be null");
+        if (sha256Hex.length() != 64 || !sha256Hex.matches("[0-9a-f]{64}")) {
+            throw new IllegalArgumentException(
+                    "sha256Hex must be a 64-character lowercase hex string, but was: '"
+                            + sha256Hex + "'");
+        }
+    }
+}

pdf-umbenenner-domain/src/main/java/de/gecheckt/pdf/umbenenner/domain/model/ProcessingStatus.java

@@ -1,20 +1,44 @@
 package de.gecheckt.pdf.umbenenner.domain.model;
 
 /**
- * Enumeration of all valid processing status values for a document within a batch run.
+ * Enumeration of all valid processing status values for a document.
  * <p>
- * Each status reflects the outcome or current state of a document processing attempt.
+ * Each status reflects the outcome or current state of a document in the
- * Status transitions follow the rules defined in the architecture specification and persist
+ * master record ({@code DocumentRecord}) or in a single attempt record
- * across multiple batch runs via the repository layer.
+ * ({@code ProcessingAttempt}).
  * <p>
- * Status Categories:
+ * <strong>Overall-status semantics (master record, M4):</strong>
  * <ul>
- *   <li><strong>Final Success:</strong> {@link #SUCCESS}</li>
+ *   <li>{@link #SUCCESS} — document was fully processed; skip in all future runs.</li>
- *   <li><strong>Retryable Failure:</strong> {@link #FAILED_RETRYABLE}</li>
+ *   <li>{@link #FAILED_RETRYABLE} — last attempt failed but is retryable; process again
- *   <li><strong>Final Failure:</strong> {@link #FAILED_FINAL}</li>
+ *       in the next run according to the applicable retry rule.</li>
- *   <li><strong>Skip (Already Processed):</strong> {@link #SKIPPED_ALREADY_PROCESSED}</li>
+ *   <li>{@link #FAILED_FINAL} — all allowed retries exhausted; skip in all future runs.</li>
- *   <li><strong>Skip (Final Failure):</strong> {@link #SKIPPED_FINAL_FAILURE}</li>
+ *   <li>{@link #PROCESSING} — document is currently being processed (transient, within a
- *   <li><strong>Processing (Transient):</strong> {@link #PROCESSING}</li>
+ *       run); if found persisted after a crash, treat as {@link #FAILED_RETRYABLE}.</li>
+ * </ul>
+ * <p>
+ * <strong>Attempt-status semantics (attempt history, M4):</strong>
+ * <ul>
+ *   <li>{@link #SUCCESS} — this attempt completed successfully.</li>
+ *   <li>{@link #FAILED_RETRYABLE} — this attempt failed; a future attempt is allowed.</li>
+ *   <li>{@link #FAILED_FINAL} — this attempt failed and no further attempts will be made.</li>
+ *   <li>{@link #SKIPPED_ALREADY_PROCESSED} — this attempt was a skip because the
+ *       document's overall status was already {@link #SUCCESS}.</li>
+ *   <li>{@link #SKIPPED_FINAL_FAILURE} — this attempt was a skip because the document's
+ *       overall status was already {@link #FAILED_FINAL}.</li>
+ * </ul>
+ * <p>
+ * <strong>M4 counter rules:</strong>
+ * <ul>
+ *   <li>Only {@link #FAILED_RETRYABLE} and {@link #FAILED_FINAL} outcomes may increase
+ *       a failure counter (content-error or transient-error counter).</li>
+ *   <li>Skip outcomes ({@link #SKIPPED_ALREADY_PROCESSED}, {@link #SKIPPED_FINAL_FAILURE})
+ *       never change any failure counter.</li>
+ *   <li>A deterministic content error at first occurrence → {@link #FAILED_RETRYABLE},
+ *       content-error counter +1.  At second occurrence → {@link #FAILED_FINAL},
+ *       content-error counter +2 (cumulative).</li>
+ *   <li>A transient technical error after a successful fingerprint → {@link #FAILED_RETRYABLE},
+ *       transient-error counter +1.</li>
  * </ul>
  *
  * @since M2-AP-001
@@ -40,13 +64,15 @@ public enum ProcessingStatus {
     FAILED_RETRYABLE,
 
     /**
-     * Processing failed with a deterministic content error (non-recoverable problem).
+     * Processing has failed finally and irrecoverably — no further retries will be attempted.
      * <p>
-     * Examples: PDF has no extractable text, page limit exceeded, document is ambiguous.
+     * This status is reached after all allowed retries for a document are exhausted.
+     * For deterministic content errors (no usable text, page limit exceeded) this means
+     * the second occurrence of the error. For other error types, it means the configured
+     * maximum retry count has been reached.
      * <p>
-     * A document with this status receives exactly one retry in a later batch run.
+     * A document with this overall status is skipped in all future batch runs and
-     * After that retry, if it still fails, status becomes {@link #FAILED_FINAL}.
+     * a {@link #SKIPPED_FINAL_FAILURE} attempt is historised.
-     * No further retries are attempted.
      */
     FAILED_FINAL,
 

pdf-umbenenner-domain/src/main/java/de/gecheckt/pdf/umbenenner/domain/model/package-info.java

@@ -6,6 +6,7 @@
  *   <li>{@link de.gecheckt.pdf.umbenenner.domain.model.ProcessingStatus} — enumeration of all valid document processing states</li>
  *   <li>{@link de.gecheckt.pdf.umbenenner.domain.model.RunId} — unique identifier for a batch run</li>
  *   <li>{@link de.gecheckt.pdf.umbenenner.domain.model.BatchRunContext} — technical context for a batch run</li>
+ *   <li>{@link de.gecheckt.pdf.umbenenner.domain.model.DocumentFingerprint} — content-based document identity (SHA-256 hex); primary key for M4 persistence (M4)</li>
  *   <li>{@link de.gecheckt.pdf.umbenenner.domain.model.SourceDocumentCandidate} — discovered PDF from source folder</li>
  *   <li>{@link de.gecheckt.pdf.umbenenner.domain.model.SourceDocumentLocator} — opaque locator passed from scan adapter to extraction adapter</li>
  *   <li>{@link de.gecheckt.pdf.umbenenner.domain.model.PdfPageCount} — typed page count validation</li>