pdf-umbenenner/docs/workpackages/M4 - Arbeitspakete.md

# M4 - Arbeitspakete

## Geltungsbereich

Dieses Dokument beschreibt ausschließlich die Arbeitspakete für den definierten Meilenstein **M4 – Fingerprint, SQLite-Persistenz und Idempotenz**.

Die Meilensteine **M1**, **M2** und **M3** werden als vollständig umgesetzt vorausgesetzt.

Die Arbeitspakete sind bewusst so geschnitten, dass:

- **KI 1** daraus je Arbeitspaket einen klaren Einzel-Prompt ableiten kann,
- **KI 2** genau dieses eine Arbeitspaket in **einem Durchgang** vollständig umsetzen kann,
- nach **jedem** Arbeitspaket wieder ein **fehlerfreier, buildbarer Stand** vorliegt.

Die Reihenfolge der Arbeitspakete ist verbindlich.

## Zusätzliche Schnittregeln für die KI-Bearbeitung

- Pro Arbeitspaket nur die **minimal notwendigen Querschnitte** durch Domain, Application, Adapter und Bootstrap ändern.
- Keine Annahmen treffen, die nicht durch dieses Dokument oder die verbindlichen Spezifikationen gedeckt sind.
- Kein Vorgriff auf **M5+**.
- Kein Umbau bestehender M1–M3-Strukturen ohne direkten M4-Bezug.
- Neue Typen, Ports und Adapter so schneiden, dass sie aus einem einzelnen Arbeitspaket heraus **klar benennbar, testbar und reviewbar** sind.

## Explizit nicht Bestandteil von M4

- KI-Anbindung
- Prompt-Laden oder Prompt-Verarbeitung
- Validierung von KI-Antworten
- Dateinamensbildung
- Zielkopie in den Zielordner
- Windows-Zeichenbereinigung für Zieldateinamen
- physische Dublettenbehandlung im Zielordner
- M5+-Persistenzfelder wie Modellname, Prompt-Identifikator, KI-Rohantwort, KI-Reasoning, Datumsquelle, finaler Titel oder finaler Zieldateiname
- vollständige laufübergreifende Retry-Logik späterer Meilensteine für KI- und Zielkopie-Fehler
- Logging-Feinschliff des Endstands

## Verbindliche M4-Regeln für **alle** Arbeitspakete

### 1. Identifikation
- Die Identifikation eines Dokuments erfolgt in M4 **ausschließlich über den SHA-256-Fingerprint des Dateiinhalts**.
- Dateiname und Pfad dienen **nicht** als Identifikator.
- Gleicher Inhalt unter anderem Dateinamen oder anderem Pfad ist **dasselbe Dokument**.
- Geänderter Inhalt ist **ein neuer fachlicher Vorgang**.

### 2. Persistenzmodell
M4 führt die Persistenz verbindlich in **zwei Ebenen**:

1. **Dokument-Stammsatz** pro Fingerprint
2. **Versuchshistorie** mit einem Datensatz pro historisiertem dokumentbezogenem Verarbeitungsversuch

### 3. Minimale Pflichtdaten im Dokument-Stammsatz für M4
Im Dokument-Stammsatz müssen in M4 mindestens speicherbar sein:

- interne ID
- Fingerprint
- letzter bekannter Quellpfad
- letzter bekannter Quelldateiname
- aktueller Gesamtstatus
- Anzahl bisheriger Inhaltsfehler
- Anzahl bisheriger transienter Fehler
- letzter Fehlerzeitpunkt
- letzter Erfolgzeitpunkt
- Erstellungszeitpunkt
- Änderungszeitpunkt

**Nicht** Bestandteil von M4-Stammsatzfeldern sind Zielpfad, Zieldateiname oder KI-bezogene Felder.

### 4. Minimale Pflichtdaten der Versuchshistorie für M4
Für jeden in M4 zu historisierenden Versuch müssen mindestens speicherbar sein:

- Versuchs-ID
- Fingerprint-Referenz
- Lauf-ID
- Versuchsnummer
- Startzeitpunkt
- Endzeitpunkt
- Ergebnisstatus
- Fehlerklasse
- Fehlermeldung bzw. Begründung
- Retryable-Flag

### 5. Statusmodell für M4
Für M4 müssen folgende Statuswerte fachlich klar verwendbar sein:

- `SUCCESS`
- `FAILED_RETRYABLE`
- `FAILED_FINAL`
- `SKIPPED_ALREADY_PROCESSED`
- `SKIPPED_FINAL_FAILURE`

Ein technischer Zwischenstatus `PROCESSING` ist zusätzlich zulässig, aber für M4 nicht verpflichtend.

### 6. Verbindliche M4-Minimalregeln für Status und Zähler
Für M4 gelten **genau** diese Minimalregeln:

- Bereits erfolgreich verarbeitete Dokumente werden in späteren Läufen übersprungen.
- Bereits final fehlgeschlagene Dokumente werden in späteren Läufen übersprungen.
- Ein **deterministischer Inhaltsfehler aus M3**  
  - beim **ersten** historisierten Auftreten führt zu `FAILED_RETRYABLE`, erhöht den **Inhaltsfehlerzähler** auf 1 und setzt `retryable = true`,
  - beim **zweiten** historisierten Auftreten in einem späteren Lauf führt zu `FAILED_FINAL`, erhöht den **Inhaltsfehlerzähler** auf 2 und setzt `retryable = false`.
- In M4 sind die deterministischen Inhaltsfehler ausschließlich die bereits aus M3 bekannten Fälle:
  - kein brauchbarer Text
  - Seitenlimit überschritten
- Dokumentbezogene **technische** Fehler nach erfolgreicher Fingerprint-Ermittlung bleiben in M4 `FAILED_RETRYABLE`, erhöhen den **Transientfehlerzähler** und setzen `retryable = true`.
- Skip-Ereignisse ändern **keinen** Fehlerzähler.

### 7. Historisierung in M4
- Jeder **identifizierte** dokumentbezogene Verarbeitungsversuch wird separat historisiert.
- Die Versuchsnummer beginnt pro Fingerprint bei **1** und steigt pro historisiertem Versuch monoton um **1**.
- Auch Skip-Fälle werden historisiert:
  - `SKIPPED_ALREADY_PROCESSED`
  - `SKIPPED_FINAL_FAILURE`
- Ein in M4 historisierter Versuch setzt einen **erfolgreich ermittelten Fingerprint** voraus.
- Technische Fehler **vor** erfolgreicher Fingerprint-Ermittlung sind in M4 **keine** SQLite-historisierten Versuche; sie werden nur kontrolliert als dokumentbezogene Laufereignisse behandelt.

### 8. Reihenfolge pro Dokument in M4
Die Verarbeitung eines einzelnen Kandidaten erfolgt in M4 verbindlich in dieser Reihenfolge:

1. Fingerprint berechnen
2. Dokument-Stammsatz laden
3. bei `SUCCESS` Skip-Entscheidung treffen und Skip-Versuch historisieren
4. bei `FAILED_FINAL` Skip-Entscheidung treffen und Skip-Versuch historisieren
5. sonst bestehenden M3-Ablauf ausführen
6. M3-Ergebnis in M4-Status, Zähler und Retryable-Flag überführen
7. Versuch historisieren
8. Dokument-Stammsatz fortschreiben

### 9. Konsistenz pro identifiziertem Dokument
- Für jeden identifizierten dokumentbezogenen Versuch müssen **Versuchshistorie und Stammsatz konsistent** fortgeschrieben werden.
- Teilaktualisierungen zwischen Historie und Stammsatz sind zu vermeiden.
- Wenn die Persistenz eines dokumentbezogenen Versuchs technisch scheitert, darf **kein inkonsistenter Teilzustand** zurückbleiben.

### 10. Schema-Initialisierung
- Die Initialisierung des SQLite-Schemas erfolgt in M4 **beim Programmstart**, bevor der Batch-Lauf mit der Dokumentverarbeitung beginnt.
- Eine nur implizite oder ausschließlich lazy Initialisierung während des laufenden Dokumentdurchsatzes ist **nicht** Ziel von M4.

---

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

### Voraussetzung
Keine. Dieses Arbeitspaket ist der M4-Startpunkt.

### Ziel
Die M4-relevanten Typen, Statusbedeutungen und Port-Verträge werden eindeutig eingeführt, damit spätere Arbeitspakete ohne Interpretationsspielraum implementiert werden können.

### Muss umgesetzt werden
- Neue M4-relevante Kernobjekte bzw. Application-nahe Typen anlegen, insbesondere für:
  - Dokument-Fingerprint
  - Dokument-Stammsatz
  - Verarbeitungsversuch
  - Fehlerzählerstände
  - dokumentbezogene Persistenzentscheidung bzw. Lookup-Ergebnis
  - technische Fehlerklassifikation für dokumentbezogene M4-Verarbeitung
- Statusmodell so vervollständigen oder schärfen, dass die verbindlichen M4-Statuswerte fachlich eindeutig abbildbar sind.
- Eindeutige Semantik für folgende Fälle im Typmodell bzw. in JavaDoc festlegen:
  - unbekanntes Dokument
  - bekanntes, noch nicht terminales Dokument
  - bereits erfolgreiches Dokument
  - bereits final fehlgeschlagenes Dokument
  - historisierbarer dokumentbezogener Versuch
  - nicht historisierbarer Vor-Fingerprint-Fehler
- Outbound-Ports definieren für:
  - Erzeugung eines Fingerprints für genau einen Verarbeitungskandidaten
  - Lesen und Schreiben des Dokument-Stammsatzes
  - Schreiben und Lesen der Versuchshistorie
  - technische Initialisierung des SQLite-Schemas
- Port-Verträge so schneiden, dass **weder `Path`/`File` noch JDBC-/SQLite-Typen** in Domain oder Application durchsickern.
- Port-Rückgaben so modellieren, dass spätere Arbeitspakete ohne zusätzliche Annahmen unterscheiden können:
  - Dokument unbekannt
  - Dokument bekannt und aktiv weiter zu verarbeiten
  - Dokument terminal erfolgreich
  - Dokument terminal final fehlgeschlagen
  - technischer Persistenzfehler
- JavaDoc und `package-info` für:
  - Statusbedeutungen
  - Zählersemantik
  - Historisierungsgrenzen
  - Architekturgrenzen
  ergänzen.

### Explizit nicht Teil
- SHA-256-Implementierung
- SQLite-Implementierung
- konkrete SQL-Tabellen
- Batch-Integration
- Repository-Code

### Fertig wenn
- die M4-relevanten Typen und Port-Verträge vorhanden sind,
- die M4-Statussemantik eindeutig dokumentiert ist,
- Historisierung vs. Vor-Fingerprint-Fehler klar abgegrenzt ist,
- Domain und Application frei von Infrastrukturtypen bleiben,
- der Build weiterhin fehlerfrei ist.

---

## AP-002 SHA-256-Fingerprint-Adapter für Verarbeitungskandidaten implementieren

### Voraussetzung
AP-001 ist abgeschlossen.

### Ziel
Für jeden Verarbeitungskandidaten kann ein stabiler, deterministischer SHA-256-Fingerprint erzeugt werden; technische Probleme werden kontrolliert in den Port-Vertrag überführt.

### Muss umgesetzt werden
- Fingerprint-Port technisch im Adapter-Out implementieren.
- SHA-256-basierte Fingerprint-Erzeugung für genau einen Verarbeitungskandidaten umsetzen.
- Sicherstellen, dass der Fingerprint ausschließlich aus dem **Dateiinhalt** abgeleitet wird.
- Kontrolliertes technisches Fehlerverhalten für mindestens folgende Fälle abbilden:
  - Datei nicht lesbar
  - Datei zwischen Kandidatenermittlung und Fingerprint-Erzeugung nicht mehr vorhanden
  - sonstige technische IO-Probleme
- Sicherstellen, dass Dateisystem- und Hashing-Details ausschließlich im Adapter-Out verbleiben.
- JavaDoc für Determinismus, Fehlerverhalten und M4-Grenze ergänzen, dass Vor-Fingerprint-Fehler **nicht** als SQLite-historisierte Versuche gelten.

### Explizit nicht Teil
- SQLite-Persistenz
- Batch-Orchestrierung
- Versuchshistorie
- Skip-Logik
- Zählerfortschreibung

### Fertig wenn
- für denselben Dateiinhalt stabil derselbe SHA-256-Fingerprint erzeugt wird,
- Fingerprint und Fehler kontrolliert über den Port geliefert werden,
- keine Hashing- oder Dateisystemdetails in Domain oder Application durchsickern,
- der Build weiterhin fehlerfrei ist.

---

## AP-003 SQLite-Schema, Start-Initialisierung und Persistenzbasis im Adapter-Out einführen

### Voraussetzung
AP-001 und AP-002 sind abgeschlossen.

### Ziel
Die SQLite-basierte Persistenzgrundlage für M4 wird technisch sauber eingeführt und beim Programmstart kontrolliert initialisiert.

### Muss umgesetzt werden
- SQLite-Dateizugriff im Adapter-Out technisch einführen.
- Technischen Initialisierungsbaustein für SQLite-Schema anlegen und über den dafür vorgesehenen Port anbinden.
- M4-Schema explizit in **zwei Ebenen** anlegen:
  - Dokument-Stammsatz
  - Versuchshistorie
- Tabellen, Primärschlüssel, Fremdschlüssel, Unique-Regeln und sinnvolle Indizes für den M4-Stand definieren.
- Dokument-Stammsatz so anlegen, dass die in diesem Dokument festgelegten M4-Pflichtfelder speicherbar sind.
- Versuchshistorie so anlegen, dass die in diesem Dokument festgelegten M4-Pflichtfelder speicherbar sind.
- Sicherstellen, dass:
  - Versuchsnummer pro Fingerprint eindeutig ist,
  - Skip-Versuche speicherbar sind,
  - keine M5+-Spalten angelegt werden.
- Die Schema-Initialisierung so vorbereiten, dass sie **beim Programmstart** explizit aufgerufen werden kann.
- JavaDoc für Schema-Zweck, Zwei-Ebenen-Modell und Initialisierungszeitpunkt ergänzen.

### Explizit nicht Teil
- Repository-Fachlogik
- Use-Case-Integration
- Statusübergänge im Batch-Lauf
- KI-bezogene Persistenzfelder
- Zielpfad- oder Dateinamenspersistenz

### Fertig wenn
- die SQLite-Datei und das M4-Schema technisch anlegbar sind,
- beide Persistenzebenen den M4-Pflichtumfang abbilden,
- die Start-Initialisierung technisch vorbereitet ist,
- keine M5+-Felder im Schema enthalten sind,
- der Stand fehlerfrei buildbar bleibt.

---

## AP-004 Repository für Dokument-Stammsatz mit vollständigem M4-Minimalumfang implementieren

### Voraussetzung
AP-003 ist abgeschlossen.

### Ziel
Der Dokument-Stammsatz kann pro Fingerprint zuverlässig gelesen, angelegt und fortgeschrieben werden, ohne fachliche Entscheidungslogik in den Adapter-Out zu verlagern.

### Muss umgesetzt werden
- Repository-Adapter für den Dokument-Stammsatz implementieren.
- Folgende technischen Fähigkeiten bereitstellen:
  - Suche eines Stammsatzes über Fingerprint
  - Neuanlage eines Stammsatzes für bisher unbekannte Dokumente
  - Fortschreibung von:
    - letztem bekanntem Quellpfad
    - letztem bekanntem Quelldateinamen
    - Gesamtstatus
    - Inhaltsfehlerzähler
    - Transientfehlerzähler
    - letztem Fehlerzeitpunkt
    - letztem Erfolgzeitpunkt
    - Änderungszeitpunkt
- Sicherstellen, dass die Repository-Operationen **keine** fachlichen Entscheidungen über Retry-Regeln oder Skip-Logik treffen.
- Mapping zwischen Application-Typen und SQLite-Struktur explizit und nachvollziehbar halten.
- Upsert-/Neuanlageverhalten für den M4-Einzelprozess reproduzierbar modellieren.
- JavaDoc für Verantwortlichkeit und Mapping ergänzen.

### Explizit nicht Teil
- Versuchshistorie
- Batch-Skip-Logik
- Versuchsnummernvergabe
- konkrete Statusentscheidungen im Use-Case
- KI- oder Zielkopie-bezogene Persistenz

### Fertig wenn
- der Dokument-Stammsatz pro Fingerprint zuverlässig gelesen und geschrieben werden kann,
- alle M4-Pflichtfelder des Stammsatzes technisch fortschreibbar sind,
- fachliche Entscheidungen nicht in das Repository abgerutscht sind,
- der Build weiterhin fehlerfrei ist.

---

## AP-005 Repository für Versuchshistorie mit monotoner Versuchsnummer implementieren

### Voraussetzung
AP-003 ist abgeschlossen.

### Ziel
Jeder historisierbare dokumentbezogene M4-Versuch kann separat und nachvollziehbar persistiert werden.

### Muss umgesetzt werden
- Repository-Adapter für die Versuchshistorie implementieren.
- Schreiben genau eines Versuchseintrags pro historisiertem dokumentbezogenem M4-Versuch umsetzen.
- Lesefähigkeiten bereitstellen, soweit sie für M4-Use-Case und Tests benötigt werden.
- Versuchsnummern pro Fingerprint reproduzierbar ableiten oder fortschreiben.
- Sicherstellen, dass die Versuchsnummer:
  - bei **1** beginnt,
  - pro Fingerprint monoton steigt,
  - auch bei Skip-Versuchen mitgezählt wird.
- M4-relevante Historisierungsdaten persistieren:
  - Fingerprint-Referenz
  - Lauf-ID
  - Versuchsnummer
  - Startzeitpunkt
  - Endzeitpunkt
  - Ergebnisstatus
  - Fehlerklasse
  - Fehlermeldung bzw. Begründung
  - Retryable-Flag
- Sicherstellen, dass nur **identifizierte** Dokumente historisiert werden.
- JavaDoc für Historisierungszweck, Versuchsnummernlogik und M4-Grenzen ergänzen.

### Explizit nicht Teil
- Dokument-Stammsatz
- fachliche Zählerlogik
- Batch-Orchestrierung
- KI-Rohantwort, Modellname oder Prompt-Identifikator
- Zielname, Zielpfad oder Zielkopie

### Fertig wenn
- pro historisiertem dokumentbezogenem Verarbeitungsvorgang ein separater Versuchseintrag gespeichert werden kann,
- die Versuchsnummern pro Fingerprint reproduzierbar und monoton sind,
- Skip-Versuche historisierbar sind,
- Vor-Fingerprint-Fehler nicht fälschlich historisiert werden,
- der Stand fehlerfrei buildbar bleibt.

---

## AP-006 M4-Entscheidungslogik und Batch-Integration für Idempotenz, Zähler und konsistente Persistenz umsetzen

### Voraussetzung
AP-001 bis AP-005 sind abgeschlossen.

### Ziel
Der bestehende M3-Verarbeitungslauf wird zu einem echten M4-Lauf erweitert, der Dokumente über Fingerprint wiedererkennt, Status und Zähler korrekt fortschreibt, Skip-Fälle historisiert und dabei keinen inkonsistenten Persistenzzustand hinterlässt.

### Muss umgesetzt werden
- Den bestehenden Batch-Use-Case so erweitern, dass pro Verarbeitungskandidat verbindlich diese Reihenfolge gilt:
  1. Fingerprint erzeugen
  2. Dokument-Stammsatz laden
  3. terminale Fälle entscheiden
  4. gegebenenfalls bestehenden M3-Ablauf ausführen
  5. Ergebnis in M4-Status, Zähler und Retryable-Flag überführen
  6. Versuch historisieren
  7. Dokument-Stammsatz fortschreiben
- Folgende M4-Regeln explizit umsetzen:
  - vorhandener Gesamtstatus `SUCCESS` → Dokument wird nicht erneut fachlich verarbeitet, sondern mit `SKIPPED_ALREADY_PROCESSED` historisiert
  - vorhandener Gesamtstatus `FAILED_FINAL` → Dokument wird nicht erneut fachlich verarbeitet, sondern mit `SKIPPED_FINAL_FAILURE` historisiert
  - unbekanntes oder noch nicht terminales Dokument wird regulär weiterverarbeitet
- M3-Ergebnisse exakt wie folgt in M4 überführen:
  - M3 erfolgreich abgeschlossen → `SUCCESS`, keine Fehlerzähler erhöhen, `retryable = false`
  - M3-Inhaltsfehler „kein brauchbarer Text“ oder „Seitenlimit überschritten“ beim ersten historisierten Auftreten → `FAILED_RETRYABLE`, Inhaltsfehlerzähler +1, `retryable = true`
  - derselbe Dokumenttyp eines bereits identifizierten Dokuments mit erneutem deterministischen Inhaltsfehler in einem späteren Lauf → `FAILED_FINAL`, Inhaltsfehlerzähler +1, `retryable = false`
  - dokumentbezogener technischer Fehler nach erfolgreicher Fingerprint-Ermittlung → `FAILED_RETRYABLE`, Transientfehlerzähler +1, `retryable = true`
- Skip-Fälle so behandeln, dass:
  - ein eigener Versuchseintrag geschrieben wird,
  - kein Fehlerzähler verändert wird,
  - der Gesamtstatus des Stammsatzes terminal bestehen bleibt.
- Vor-Fingerprint-Fehler ausdrücklich **nicht** als SQLite-Versuch historisieren.
- Für identifizierte Dokumente sicherstellen, dass **Historie und Stammsatz konsistent** fortgeschrieben werden und keine inkonsistenten Teilzustände entstehen.
- Falls eine dokumentbezogene Persistenzoperation technisch scheitert:
  - darf kein teilaktualisierter Zustand zurückbleiben,
  - bleibt der Batch-Lauf für andere Dokumente kontrolliert weiter lauffähig,
  - wird kein M5+-Verhalten vorweggenommen.
- JavaDoc für Idempotenz, Zählerfortschreibung, Skip-Semantik und Persistenzkonsistenz ergänzen.

### Explizit nicht Teil
- KI-Aufruf
- Dateinamensbildung
- Zielkopie
- M5+-Retry-Regeln für KI- oder Zielkopiefehler
- M5+-Persistenzfelder
- spätere Reporting- oder Auswertungslogik

### Fertig wenn
- der Batch-Lauf identische Inhalte über Fingerprint wiedererkennt,
- `SUCCESS`- und `FAILED_FINAL`-Dokumente in späteren Läufen historisiert übersprungen werden,
- die Minimalregel „erster deterministischer Inhaltsfehler retryable, zweiter final“ explizit umgesetzt ist,
- technische dokumentbezogene Fehler nach Fingerprint als retryable behandelt werden,
- Historie und Stammsatz pro identifiziertem Dokument konsistent fortgeschrieben werden,
- weiterhin keine M5+-Funktionalität enthalten ist.

---

## AP-007 Bootstrap- und CLI-Anpassungen für SQLite-Konfiguration, Start-Initialisierung und M4-Verdrahtung durchführen

### Voraussetzung
AP-001 bis AP-006 sind abgeschlossen.

### Ziel
Der Programmeinstieg ist sauber an den M4-Lauf angepasst; die Persistenz wird beim Start initialisiert und die neuen M4-Bausteine sind vollständig verdrahtet.

### Muss umgesetzt werden
- Bootstrap-Verdrahtung auf die neuen M4-Ports, Adapter und Persistenzbausteine erweitern.
- M4-relevante Konfiguration ergänzen bzw. verdrahten, insbesondere für:
  - `sqlite.file`
- Startvalidierung so ergänzen, dass mindestens geprüft wird:
  - SQLite-Dateipfad ist vorhanden oder technisch anlegbar
  - Persistenzkonfiguration ist nutzbar
- Technische Schema-Initialisierung **beim Programmstart** ausführen, bevor der eigentliche Dokumentlauf beginnt.
- CLI-/Batch-Startpfad auf den realen M4-Ablauf ausrichten.
- Sicherstellen, dass harte Start-, Verdrahtungs- oder Initialisierungsfehler weiterhin zu **Exit-Code 1** führen.
- Sicherstellen, dass dokumentbezogene Fehler im späteren Lauf **nicht** als Startfehler fehlmodelliert werden.
- M1–M3-Grundverhalten erhalten und sauber mit den M4-Bausteinen kombinieren.
- JavaDoc und `package-info` für aktualisierte Verdrahtung, Konfiguration und Modulgrenzen ergänzen.

### Explizit nicht Teil
- neue Exit-Code-Semantik späterer Meilensteine
- KI-Verdrahtung
- Zielordner- oder Dateinamensverdrahtung
- Logging-Feinschliff

### Fertig wenn
- das Programm im M4-Stand vollständig startbar ist,
- das SQLite-Schema beim Start kontrolliert initialisiert wird,
- die neuen Adapter korrekt verdrahtet sind,
- harte Persistenz-Startfehler kontrolliert zu Exit-Code 1 führen,
- der Build fehlerfrei bleibt.

---

## AP-008 Tests für Fingerprint, SQLite-Repositories, M4-Statusfortschreibung, Historie und Skip-Logik vervollständigen

### Voraussetzung
AP-001 bis AP-007 sind abgeschlossen.

### Ziel
Der vollständige M4-Zielzustand wird automatisiert abgesichert und als konsistenter Übergabestand nachgewiesen.

### Muss umgesetzt werden
- Unit-Tests für die SHA-256-Fingerprint-Erzeugung implementieren.
- Repository-Tests gegen SQLite implementieren, insbesondere für:
  - Schema-Initialisierung
  - Anlegen und Lesen eines Dokument-Stammsatzes
  - Fortschreiben aller M4-Pflichtfelder des Stammsatzes
  - Anlegen und Lesen von Versuchshistorie
  - stabile Versuchsnummern pro Fingerprint
- Tests für M4-Statusfortschreibung und Zähler ergänzen, insbesondere:
  - unbekanntes Dokument mit erfolgreichem M4-Ende wird als `SUCCESS` persistiert
  - erster deterministischer Inhaltsfehler führt zu `FAILED_RETRYABLE`
  - zweiter deterministischer Inhaltsfehler in einem späteren Lauf führt zu `FAILED_FINAL`
  - technischer dokumentbezogener Fehler nach erfolgreicher Fingerprint-Ermittlung erhöht den Transientfehlerzähler und bleibt `FAILED_RETRYABLE`
  - Skip-Fälle verändern keine Fehlerzähler
- Tests für Idempotenz- und Skip-Logik ergänzen, insbesondere:
  - bereits erfolgreiches Dokument wird historisiert übersprungen
  - final fehlgeschlagenes Dokument wird historisiert übersprungen
  - gleicher Inhalt unter anderem Dateinamen wird über denselben Fingerprint erkannt
- Tests ergänzen, die belegen:
  - pro identifiziertem dokumentbezogenem Verarbeitungsvorgang entsteht genau **ein** Historieneintrag
  - Skip-Ereignisse werden historisiert
  - Vor-Fingerprint-Fehler nicht in SQLite-Historie auftauchen
- Tests für Bootstrap- und Startverhalten ergänzen, insbesondere:
  - Schema-Initialisierung beim Start
  - harter Persistenz-Startfehler führt zu Exit-Code 1
- Den M4-Stand abschließend auf Konsistenz, Architekturtreue und Nicht-Vorgriff auf M5+ prüfen.

### Explizit nicht Teil
- Tests für KI, Prompt-Laden oder KI-JSON
- Tests für Zielkopie oder Dateinamensbildung
- Tests für M5+-Persistenzfelder
- Tests für vollständige Retry-Logik späterer Meilensteine

### Fertig wenn
- die Test-Suite für den M4-Umfang grün ist,
- die wichtigsten M4-Randfälle automatisiert abgesichert sind,
- der definierte M4-Zielzustand vollständig erreicht ist,
- ein fehlerfreier, übergabefähiger Stand vorliegt.

---

## Abschlussbewertung

Die Arbeitspakete decken den vollständigen M4-Zielumfang aus den verbindlichen Spezifikationen ab:

- Fingerprint über SHA-256
- SQLite-Persistenz in zwei Ebenen
- Dokument-Stammsatz mit M4-Minimalumfang
- Versuchshistorie pro identifiziertem dokumentbezogenem Versuch
- Idempotenz über Fingerprint
- Skip-Regeln für bereits erfolgreiche und final fehlgeschlagene Dokumente
- explizite Minimalregel für deterministische Inhaltsfehler in M4
- Tests für Fingerprint, Persistenz, Statusfortschreibung, Historie und Skip-Logik

Gleichzeitig bleiben die Grenzen zu M1–M3 sowie zu M5+ gewahrt. Insbesondere werden **keine** KI-Funktionalitäten, **keine** Dateinamensbildung und **keine** Zielkopie vorweggenommen.