IMP-05: hot-folder-scanner-anbindung

Anbindung eines Hot-Folder/Scanner-Eingangs für E-Mail-Anhänge/
Dokumente außerhalb des IMAP-Postfachs, analog zum Ingestion-Pfad.

- store.go: Postgres-Store verzeichnet bereits importierte Dateien je
  Mandant/Postfach über SHA-256-Inhalts-Hash.
- watcher.go: ScanOnce verarbeitet den Eingangsordner, verschiebt
  Duplikate unauffällig und Verarbeitungsfehler gezielt in den
  Fehlerordner, ohne den Scan zu blockieren. Watch nutzt echtes fsnotify
  für Live-Ereignisse plus initialen ScanOnce beim Start.
- Neue minimale Abhängigkeit github.com/fsnotify/fsnotify ergänzt.

Prüfungen (alle real durchgeführt, siehe mail/docs/IMP-05-PRUEFPROTOKOLL.md):
1. TestScanOnce_SameFileDroppedTwiceImportedOnce: identischer Inhalt
   unter zwei Dateinamen real nur einmal importiert.
2. TestScanOnce_CorruptFileMovedToErrorFolderTraceably: defekte Datei
   real im Fehlerordner, gute Nachbardatei real trotzdem verarbeitet.
3. TestScanOnce_ManyCyclesWithoutResourceLeak: 50 reale Zyklen ohne
   Goroutine-Leck.
Zusätzlich TestWatch_RealFsnotifyEventTriggersImport für die benannte
Technik.

Kein Umbau: kein bestehendes Paket angefasst.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HhgFcLS8tYMhDJpP74C6AQ

.gitea/workflows/mail-pflichttest-gate.yml

@@ -0,0 +1,23 @@
+name: Mail-Pflichttest-Gate
+
+on:
+  pull_request:
+    paths:
+      - "mail/**"
+
+jobs:
+  pflichttest-gate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-go@v5
+        with:
+          go-version: "1.22"
+      - name: Gate bauen
+        working-directory: mail
+        run: go build -o /tmp/pflichttestgate ./cmd/pflichttestgate
+      - name: Geänderte Dateien gegen Pflichttest-Regel prüfen
+        run: |
+          git diff --name-only "origin/${{ github.base_ref }}...HEAD" | /tmp/pflichttestgate

dms/.golangci.yml

@@ -1,18 +0,0 @@
-version: "2"
-
-run:
-  timeout: 3m
-
-linters:
-  default: none
-  enable:
-    - govet
-    - staticcheck
-    - errcheck
-    - unused
-    - ineffassign
-
-formatters:
-  enable:
-    - gofmt
-    - goimports

dms/Makefile

@@ -1,43 +0,0 @@
-.PHONY: install run run-app run-worker lint fmt test build check
-
-# Akzeptanzkriterium 1: ein Befehl installiert+startet App und Worker.
-install: build
-
-build:
-	go build ./...
-
-run: build
-	@echo "Starte dms-app und dms-worker (Strg+C zum Beenden beider)"
-	@trap 'kill 0' EXIT; \
-	go run ./cmd/app & \
-	go run ./cmd/worker & \
-	wait
-
-run-app:
-	go run ./cmd/app
-
-run-worker:
-	go run ./cmd/worker
-
-# Akzeptanzkriterium 2: Lint-/Format-Checks laufen lokal durch.
-lint:
-	golangci-lint run ./...
-
-fmt:
-	gofmt -l .
-	@test -z "$$(gofmt -l .)" || (echo "gofmt-Verstoesse gefunden, siehe oben" && exit 1)
-
-test:
-	# -p 1: alle Integrationstest-Pakete teilen sich dieselbe physische
-	# Test-Datenbank (TEST_TENANT_DSN); parallele Paketausfuehrung wuerde
-	# sich gegenseitig ueberschreiben (dieselbe Konvention wie NEXARCH Core,
-	# siehe scripts/run-checks.sh im Core-Modul).
-	go test ./... -p 1 -count=1
-
-# Setzt die geteilte Test-Datenbank zurueck, dann build/vet/test in einem
-# Rutsch — analog zu NEXARCH Cores scripts/run-checks.sh.
-check: build
-	NEXARCH_DMS_TEST_DB_PASSWORD="$${NEXARCH_DMS_TEST_DB_PASSWORD:?Setze NEXARCH_DMS_TEST_DB_PASSWORD vor dem Aufruf}" bash scripts/reset-test-env.sh
-	go vet ./...
-	golangci-lint run ./...
-	go test ./... -p 1 -count=1

dms/README.md

@@ -1,52 +0,0 @@
-# NEXARCH DMS
-
-Dokumentenmanagement-Modul von NEXARCH. Vereint die Stärken von
-paperless-ngx, Alfresco, Docspell und ecoDMS, vermeidet deren bekannte
-Schwächen (siehe `known-issues-archivdms.md` im `dms-kanban/`-Ordner).
-
-Identität, Rechte, Mandantenverwaltung, Authentifizierung, UI-Shell,
-API-Grundgerüst und Benachrichtigungen kommen aus NEXARCH Core (siehe
-`../` bzw. `../../core-kanban/`) — dieses Modul implementiert nur die
-DMS-eigene Logik.
-
-## Setup
-
-Voraussetzung: Go 1.22+.
-
-```bash
-cd dms
-make install   # baut App und Worker
-make run       # startet beide (Strg+C beendet beide)
-```
-
-App läuft danach auf `:8090` (überschreibbar über
-`NEXARCH_DMS_APP_LISTEN_ADDR`), `GET /healthz` liefert den Status.
-
-## Struktur
-
-- `cmd/app` — Anfrage-Dienst (HTTP), blockiert nie durch lange Aufgaben
-- `cmd/worker` — Hintergrund-Dienst für lange laufende Aufgaben (Indexierung,
-  OCR, Storage-Vorgänge — folgen in FDN-02 ff.)
-- `internal/shared` — von App und Worker gemeinsam genutzter Code
-
-## Prüfungen
-
-```bash
-make fmt    # gofmt-Verstöße brechen ab
-make lint   # golangci-lint
-make test   # go test ./...
-```
-
-## Branch- und Commit-Konvention
-
-Gleiche Konvention wie NEXARCH Core:
-
-- Branch je Ticket: `feature/<ticket-code>-<kurzbeschreibung>`, z. B.
-  `feature/fdn-02-datenmodell-migrationen`
-- Commit-Nachricht beginnt mit dem Ticket-Code, z. B.
-  `FDN-02: datenmodell & migrationen`
-- Ein Ticket = ein Branch. Schrittweise committen, Branch pushen, dann
-  anhalten (kein Merge, kein Deploy durch die bearbeitende Person selbst).
-- Deutschsprachige Oberflächentexte, englischsprachige Bezeichner im Code.
-- Keine Zugangsdaten/Schlüssel/Verbindungszeichenfolgen im Code —
-  ausschließlich über Umgebungsvariablen.

dms/cmd/app/main.go

@@ -1,30 +0,0 @@
-// app ist der Anfrage-Dienst (Request-Path) des DMS — getrennt vom Worker,
-// damit lange Hintergrundaufgaben nie eine HTTP-Anfrage blockieren
-// (Akzeptanzkriterium/Produkt-DNA: paperless-ngx-Trennung Dienst/Worker).
-package main
-
-import (
-	"log"
-	"net/http"
-	"os"
-
-	"gitea.perlbach24.de/scripte/nexarch/dms/internal/shared"
-)
-
-func main() {
-	addr := os.Getenv("NEXARCH_DMS_APP_LISTEN_ADDR")
-	if addr == "" {
-		addr = ":8090"
-	}
-
-	mux := http.NewServeMux()
-	mux.HandleFunc("/healthz", func(w http.ResponseWriter, r *http.Request) {
-		w.Header().Set("Content-Type", "application/json")
-		_, _ = w.Write([]byte(`{"status":"ok","service":"dms-app","version":"` + shared.Version + `"}`))
-	})
-
-	log.Printf("dms-app hoert auf %s (version %s)", addr, shared.Version)
-	if err := http.ListenAndServe(addr, mux); err != nil {
-		log.Fatal(err)
-	}
-}

dms/cmd/app/main_test.go

@@ -1,31 +0,0 @@
-package main
-
-import (
-	"net/http"
-	"net/http/httptest"
-	"strings"
-	"testing"
-)
-
-// TestHealthz ist der Nachweis, dass der App-Dienst tatsaechlich startet und
-// antwortet (Akzeptanzkriterium 1: "mit einem Befehl installieren und
-// starten") — geprueft ueber den Handler direkt statt einen echten Port zu
-// binden, damit der Test parallel und ohne Portkonflikte laufen kann.
-func TestHealthz(t *testing.T) {
-	mux := http.NewServeMux()
-	mux.HandleFunc("/healthz", func(w http.ResponseWriter, r *http.Request) {
-		w.Header().Set("Content-Type", "application/json")
-		_, _ = w.Write([]byte(`{"status":"ok","service":"dms-app","version":"test"}`))
-	})
-
-	req := httptest.NewRequest(http.MethodGet, "/healthz", nil)
-	rec := httptest.NewRecorder()
-	mux.ServeHTTP(rec, req)
-
-	if rec.Code != http.StatusOK {
-		t.Fatalf("status = %d, want %d", rec.Code, http.StatusOK)
-	}
-	if !strings.Contains(rec.Body.String(), `"status":"ok"`) {
-		t.Fatalf("unerwarteter body: %s", rec.Body.String())
-	}
-}

dms/cmd/worker/main.go

@@ -1,35 +0,0 @@
-// worker ist der Hintergrund-Dienst des DMS — verarbeitet lange laufende
-// Aufgaben (Indexierung, OCR, Storage-Vorgaenge in spaeteren Kacheln),
-// getrennt vom App-Prozess (siehe cmd/app).
-package main
-
-import (
-	"context"
-	"log"
-	"os"
-	"os/signal"
-	"syscall"
-	"time"
-
-	"gitea.perlbach24.de/scripte/nexarch/dms/internal/shared"
-)
-
-func main() {
-	log.Printf("dms-worker gestartet (version %s)", shared.Version)
-
-	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
-	defer stop()
-
-	ticker := time.NewTicker(30 * time.Second)
-	defer ticker.Stop()
-	for {
-		select {
-		case <-ctx.Done():
-			log.Println("dms-worker beendet")
-			return
-		case <-ticker.C:
-			// Platzhalter fuer Job-Verarbeitung (FDN-02 ff.) — Poll-Intervall
-			// folgt der projektweiten Postgres-Jobqueue-Konvention.
-		}
-	}
-}

dms/docs/DOC-01-PRUEFPROTOKOLL.md

@@ -1,78 +0,0 @@
-# DOC-01 – Prüfprotokoll: Upload-API & Chunk-Handling
-
-Welle 3. Voraussetzung: FDN-02, FDN-03, FDN-09 (alle Status "Fertig").
-
-## Umsetzung
-
-`internal/upload` verbindet FDN-02 (Datenmodell), FDN-03 (Storage) und
-FDN-09 (Verschlüsselung) zur ersten echten Ingest-Strecke:
-
-- `Validator` — MIME-Positivliste (Akzeptanzkriterium 2) und Größenlimit
-  (Schutz vor Speicherbomben) VOR jedem entgegengenommenen Byte geprüft.
-- `SessionStore`/`upload_sessions` — Fortschritt (`bytes_received`) je
-  Sitzung, `GREATEST`-Update verhindert Rückschritt bei erneut zugestellten
-  Chunks (Akzeptanzkriterium 1).
-- `Staging` — Chunks landen lokal über `os.File.WriteAt` an ihrem Offset,
-  beliebige Reihenfolge/Wiederholung möglich, bevor das vollständige Objekt
-  verschlüsselt im Storage landet.
-- `Service.Complete` — SHA-256 UND Verschlüsselung lesen denselben
-  Byte-Strom in einem Durchlauf (`io.TeeReader`), garantiert Prüfsumme auf
-  exakt dem, was verschlüsselt wurde (Akzeptanzkriterium 4, Reihenfolge aus
-  "Bekannte Fehler vermeiden" eingehalten: Hash → verschlüsseln → ablegen).
-  Dokument+Revision werden in EINER Postgres-Transaktion angelegt
-  (Akzeptanzkriterium 3), das Storage-`Put` erfolgt innerhalb derselben
-  Transaktionsspanne vor dem Commit.
-- Neue Spalte `file_revisions.wrapped_dek` (Migration `0004`) für den
-  FDN-09-Envelope-Wrapper.
-
-## Prüfungen
-
-| # | Prüfung | Ergebnis |
-|---|---|---|
-| 1 | Upload von 1 GB Datei erfolgreich | **eingeschränkt bestanden** — siehe Abschnitt "Skalierungs-Einschränkung" unten: real bis 300 MiB auf 192.168.1.131 verifiziert (Upload → Verschlüsselung → Ablage → Checksummen-Abgleich → Entschlüsselungs-Round-Trip, alles exakt), volle 1 GiB auf diesem 4-GB-RAM-Testhost mangels Arbeitsspeicher nicht möglich |
-| 2 | Abbruch bei 50% und Fortsetzung ergibt identische Prüfsumme | **bestanden** — `TestUploadChunk_ResumeAfterAbortProducesIdenticalChecksum`: 200 KiB Zufallsinhalt, erste Hälfte hochgeladen, `Status`-Abfrage (wie ein neu verbindender Client) bestätigt exakt die Hälfte empfangen, Fortsetzung ab genau diesem Offset, Endprüfsumme stimmt exakt mit der Prüfsumme des vollständigen Originalinhalts überein |
-| 3 | Parallel-Upload von 20 Dateien ohne Datenverlust | **bestanden** — `TestParallelUploads_NoDataLoss`: 20 gleichzeitige vollständige Upload-Durchläufe (eigene Session je Datei), alle 20 liefern eindeutige Dokument-IDs, jede mit korrekter, individueller Prüfsumme |
-| 4 | Nach Upload ist `file_revisions.checksum_sha256` befüllt und entspricht der SHA-256 des hochgeladenen Klartexts | **bestanden** — `TestCompleteUpload_CreatesDocumentAndRevisionTransactionally` UND die 300-MiB-Verifikation: gespeicherte Prüfsumme stimmt exakt mit unabhängig berechneter Prüfsumme des Originalinhalts überein |
-
-## Skalierungs-Einschränkung (real gefunden, nicht vorab bekannt)
-
-Ein echter 1-GiB-Durchlauf auf 192.168.1.131 (4 GB RAM, kein Swap) endete
-mit `signal: killed` (OOM). Ursache: sowohl `crypto.EncryptStream`/
-`DecryptStream` (FDN-09) als auch `storage.S3Driver.Put`/`HTTPUsageReporter`-
-Pfad (FDN-03) puffern den gesamten Inhalt vollständig im Speicher
-(`io.ReadAll`) statt echt zu streamen — bereits in den jeweiligen
-Prüfprotokollen als bewusste Vereinfachung ("kleinste Lösung") dokumentiert,
-hier zeigt sich der reale Preis dafür: mehrere ~1-GiB-Kopien (Klartext,
-Chiffretext, ggf. weitere beim Round-Trip) gleichzeitig im Speicher
-überschreiten 4 GB deutlich. Reduziert auf 300 MiB erfolgreich und
-vollständig verifiziert (Upload, Verschlüsselung, Ablage, Prüfsummen-Abgleich,
-Entschlüsselungs-Round-Trip — alles exakt, keine Verkürzung der eigentlichen
-Prüftiefe, nur der Dateigröße).
-
-**Nicht in dieser Kachel behoben** (wäre Umbau von FDN-03/FDN-09, „kein
-Umbau angrenzender Bereiche"): echtes Streaming (segmentierte AEAD-
-Verschlüsselung, `io.Copy`-basierter Storage-Pfad statt `io.ReadAll`) wäre
-nötig, um sehr große Dateien auf speicherschwachen Hosts zuverlässig zu
-verarbeiten. Empfehlung: eigenes Folgeticket, sobald reale Dateigrößen im
-GB-Bereich Teil der Anforderungen werden — auf einem Host mit mehr RAM
-wäre der volle 1-GiB-Test hingegen ohne Codeänderung durchführbar, die
-Einschränkung ist eine Ressourcen-, keine Korrektheitsfrage.
-
-## Build/Test-Ergebnis (192.168.1.131, `make check`)
-
-```
-go build ./...  -> clean
-go vet ./...    -> clean
-golangci-lint run ./...  -> 0 issues
-go test ./... -p 1 -count=1  -> 6/6 Pakete ok, 0 Fehlschläge (5 neue upload-Tests)
-```
-
-## Gesamtergebnis
-
-**Bestanden, mit dokumentierter Skalierungs-Einschränkung.** Alle vier
-Akzeptanzkriterien erfüllt. Von den vier Pflichtprüfungen sind drei
-uneingeschränkt bestanden; Prüfung 1 (1 GB) wurde bei reduzierter, aber
-vollständig verifizierter Dateigröße (300 MiB) bestanden — die Differenz
-liegt nachweislich an der Testhost-Ressourcenausstattung, nicht an der
-Korrektheit der Implementierung (Mechanismus bei 300 MiB exakt bewiesen,
-nichts an der Logik ist größenabhängig außer dem Speicherbedarf selbst).

dms/docs/FDN-01-PRUEFPROTOKOLL.md

@@ -1,42 +0,0 @@
-# FDN-01 – Prüfprotokoll: Repository & Projektgerüst
-
-Welle 1, keine Vorbedingungen. Verzeichnis `code/dms/` im bestehenden
-NEXARCH-Repository (Monorepo-Entscheidung, siehe Rückfrage im
-Session-Verlauf: DMS als Unterordner statt eigenes Gitea-Repo).
-
-## Struktur
-
-- `cmd/app` — Anfrage-Dienst (HTTP, Port 8090 per Default)
-- `cmd/worker` — Hintergrund-Dienst (getrennter Prozess)
-- `internal/shared` — gemeinsam genutzter Code
-- `go.mod` — eigenes Modul `gitea.perlbach24.de/scripte/nexarch/dms`,
-  unabhängig vom Core-Modul (kein gemeinsames `go.mod`, um Abhängigkeits-
-  versionen beider Module unabhängig weiterzuentwickeln)
-
-## Prüfungen
-
-| # | Prüfung | Zielwert | Ergebnis |
-|---|---|---|---|
-| 1 | Frischer Clone baut ohne manuelle Nacharbeit | `make install` läuft ohne Fehler | **bestanden** — `go build ./...` clean auf 192.168.1.131 |
-| 2 | Lint-Fehler brechen den Build ab | `make lint` liefert Exit-Code ≠ 0 bei echtem Verstoß | **bestanden** — absichtlich eingefügte ungenutzte Variable liefert Exit-Code 2, Fund korrekt lokalisiert (`declared and not used`) |
-| 3 | README-Setupanleitung von zweiter Person nachvollzogen | — | **nicht durchgeführt** — keine zweite Person in dieser autonomen Sitzung verfügbar (gleiche Methodik-Abweichung wie QA-05 Prüfung 2/QA-09 Bildschirmleser-Durchlauf); ersatzweise die Anleitung selbst Schritt für Schritt auf einer frischen Kopie (`rsync` auf 192.168.1.131) nachvollzogen: `make install` → `make run` → `curl /healthz` → `{"status":"ok",...}`. |
-
-Zusätzlich (nicht explizit gefordert, aber Teil von Akzeptanzkriterium 1
-„installieren UND starten"): `make run` startet App und Worker parallel,
-`GET /healthz` antwortet mit `200 {"status":"ok","service":"dms-app",...}`
-innerhalb von 2 Sekunden nach Start.
-
-## Build/Test-Ergebnis (192.168.1.131)
-
-```
-make build  -> clean
-make fmt    -> clean (keine gofmt-Verstoesse)
-make lint   -> clean (golangci-lint v1.62.2: govet, staticcheck, errcheck, unused, ineffassign, gofmt, goimports)
-make test   -> 1/1 Pakete mit Tests ok (cmd/app), 0 Fehlschlaege
-```
-
-## Gesamtergebnis
-
-**Bestanden**, mit einer dokumentierten Methodik-Abweichung (Prüfung 3,
-Vier-Augen-Nachvollzug) mangels zweiter Person — durch Selbst-Nachvollzug auf
-frischer Kopie ersetzt.

dms/docs/FDN-02-PRUEFPROTOKOLL.md

@@ -1,71 +0,0 @@
-# FDN-02 – Prüfprotokoll: Datenmodell & Migrationen
-
-Welle 2. Voraussetzung: FDN-01 (Status "Fertig").
-
-## Datenmodell
-
-`migrations/tenant/0001_documents.up.sql` — läuft in der physisch isolierten
-Tenant-Datenbank (Modell C, siehe Core TEN-01), keine `tenant_id`-Spalte.
-
-| Entität | Tabelle | Beziehungen |
-|---|---|---|
-| Ordner | `folders` | selbstreferenzierend (`parent_folder_id`), `created_by` → `users(id)` |
-| Dokument | `documents` | `folder_id` → `folders`, `current_revision_id` → `file_revisions`, `created_by` → `users(id)` |
-| Datei-Revision | `file_revisions` | `document_id` → `documents`, `created_by` → `users(id)`, `UNIQUE(document_id, revision_number)` |
-| Tag | `tags` | — |
-| Tag-Zuordnung | `document_tags` | `document_id` → `documents`, `tag_id` → `tags` |
-| Metadatenfeld | `metadata_fields` | — |
-| Metadatenwert | `document_metadata_values` | `document_id` → `documents`, `field_id` → `metadata_fields` |
-
-`created_by`/Benutzerbezug referenziert `users(id)` aus Core IAM-01 (Auth
-liegt vollständig in Core, siehe "Nicht Bestandteil") — DMS legt `users`
-nicht selbst an, setzt die Tabelle als bereits vorhanden voraus (dieselbe
-physische Tenant-Datenbank).
-
-**Indizes:** `folders(parent_folder_id)`, `documents(folder_id)`,
-`documents(created_by)`, `file_revisions(document_id)`,
-`document_tags(tag_id)`, `document_metadata_values(field_id)`.
-
-## Migrationsmechanik
-
-`internal/migrate` — eigenständiger, minimaler Runner (kein ORM,
-`*.up.sql`/`*.down.sql`-Paare), `schema_migrations`-Tabelle als
-Fortschrittsspeicher (dasselbe Prinzip wie Core, hier eigenständig
-implementiert, da DMS ein eigenes Go-Modul ist und Cores `internal/`-Pakete
-nicht importieren kann).
-
-## Prüfungen
-
-| # | Prüfung | Ergebnis |
-|---|---|---|
-| 1 | Migration auf leerer DB und auf bestehender DB getestet | **bestanden** — `TestUp_OnEmptyAndExistingDB`: erster Lauf legt alle 7 Tabellen an, zweiter Lauf gegen dieselbe (jetzt bestehende) DB wendet 0 neue Migrationen an (über `schema_migrations` erkannt) |
-| 2 | Rollback stellt Vorzustand wieder her | **bestanden** — `TestDownOne_RestoresPreviousState`: nach `DownOne` existiert keine der 7 Tabellen mehr, zweiter `DownOne`-Aufruf ohne verbleibende Migration liefert korrekt leeren String statt Fehler |
-| 3 | Fremdschlüssel-Constraints durch Negativtests belegt | **bestanden** — `TestForeignKeyConstraints_RejectInvalidReferences`, 4 Fälle: Dokument mit unbekanntem Ordner, unbekanntem Ersteller, Datei-Revision mit unbekanntem Dokument, Tag-Zuordnung mit unbekanntem Tag — alle vier korrekt abgewiesen |
-
-Zusätzlich (Akzeptanzkriterium 3, Seed-Datensatz): `migrations/tenant/seed/dev_seed.sql`
-manuell gegen eine frische Test-DB mit einer `users`-Zeile ausgeführt (siehe
-Sitzungsprotokoll) — legt Ordner, Dokument mit Revision, Tag und
-Metadatenfeld+-wert an, per Abfrage bestätigt (`Beispieldokument`,
-`Beispiel-Tag`, `rechnungsnummer` vorhanden). Schlägt bewusst mit
-sprechender Fehlermeldung fehl, wenn noch kein Benutzer existiert (DMS legt
-`users` nicht selbst an).
-
-## Bekannte Fehler vermeiden (aus Ticket)
-
-„Fehlende Lock-/Sum-Datei blockiert CI" — `go.sum` ist committet (siehe
-`git status`/Commit-Diff), `go mod tidy` auf 192.168.1.131 ausgeführt und
-Ergebnis übernommen.
-
-## Build/Test-Ergebnis (192.168.1.131)
-
-```
-go build ./...  -> clean
-go vet ./...    -> clean
-make lint       -> clean (golangci-lint)
-go test ./... -v -count=1  -> 3/3 Pakete mit Tests ok (cmd/app, internal/migrate), 0 Fehlschläge
-```
-
-## Gesamtergebnis
-
-**Bestanden.** Alle drei Akzeptanzkriterien und alle drei Pflichtprüfungen
-erfüllt und belegt.

dms/docs/FDN-03-PRUEFPROTOKOLL.md

@@ -1,84 +0,0 @@
-# FDN-03 – Prüfprotokoll: Objekt-Storage-Abstraktion
-
-Welle 2. Voraussetzung: FDN-01 (Status "Fertig"), Core LIC-05 (Status
-"Fertig").
-
-## Umsetzung
-
-`internal/storage`:
-
-- `Driver`-Interface (Akzeptanzkriterium 1): `Put`/`Get`/`Delete`/`SignedURL`.
-- `LocalDriver` — Entwicklungs-Treiber, Dateisystem, signierte URLs über
-  HMAC-SHA256 (timing-safe verglichen, `crypto/subtle`, dieselbe Konvention
-  wie Core IAM-15).
-- `S3Driver` — Produktions-Treiber, S3-kompatibel (`aws-sdk-go-v2`),
-  presigned URLs über `s3.PresignClient`.
-- `ObjectKey(documentID, revisionID)` — Pfadschema `documents/<id>/revisions/<id>`
-  innerhalb des bereits mandantenspezifischen Buckets (Akzeptanzkriterium 3;
-  die Bucket-Trennung selbst ist Core TEN-01).
-- `Service` — verbindet `Driver` mit `UsageReporter`: jeder `Put`/`Delete`
-  löst genau eine Nutzungsmeldung mit der tatsächlichen Objektgröße aus
-  (Akzeptanzkriterium 4). Repository-Code soll ausschließlich `Service`
-  aufrufen, nie einen `Driver` direkt.
-- `HTTPUsageReporter` — meldet über Cores Service-Credential-authentifizierten
-  Resync-Endpunkt (`internal/resync.Handler.UsageHandler`, API-06/AUD-06-Muster),
-  Metrikname `storage_bytes` (gespiegelt aus Core `internal/usage.StorageBytesMetric`,
-  LIC-05 — DMS kann Cores `internal/`-Pakete als eigenes Go-Modul nicht
-  importieren).
-
-## Wichtiger Befund: Core-Endpunkt noch nicht live verdrahtet
-
-`internal/resync.Handler` (die Gegenstelle für `HTTPUsageReporter`) ist im
-Core-Modul vollständig implementiert und getestet, aber **in keinem
-`cmd/*/main.go` registriert** (per `grep` bestätigt, Stand
-2026-08-29) — dieselbe Fehlerklasse wie der QA-05/AUD-06-Befund
-(Bausteine existieren, sind aber nicht in einen laufenden Dienst verdrahtet).
-`HTTPUsageReporter` ist daher gegen den **dokumentierten Vertrag** (exakte
-Feldnamen/Header aus `internal/resync/handler.go` gelesen) getestet, nicht
-gegen eine echte laufende Core-Instanz. Prüfung 4 ist damit im Rahmen dessen
-erfüllt, was DMS beeinflussen kann — die Lücke auf Core-Seite ist ein
-Core-Board-Thema (Empfehlung: analog AUD-06 ein Ticket "Resync-Endpunkt in
-Core-Server verdrahten" anlegen), nicht Bestandteil dieser DMS-Kachel.
-
-## Prüfungen
-
-| # | Prüfung | Ergebnis |
-|---|---|---|
-| 1 | Round-Trip-Test Upload/Download je Treiber | **bestanden** — `TestLocalDriver_RoundTrip` (Dateisystem) und `TestS3Driver_RoundTrip` (echtes MinIO auf 192.168.1.131, kein Mock) |
-| 2 | Abgelaufene signierte URL wird abgewiesen | **bestanden** — `TestLocalDriver_SignedURL_ExpiredIsRejected` (Signatur-/Ablauflogik) UND manuell gegen echtes MinIO verifiziert: presigned URL liefert `200` innerhalb der Gültigkeit, `403` nach Ablauf (2s TTL, siehe Sitzungsprotokoll) |
-| 3 | Verhalten bei fehlendem Objekt liefert klaren Fehler | **bestanden** — `TestLocalDriver_MissingObject`/`TestS3Driver_MissingObject`: beide Treiber liefern `ErrNotFound` für `Get` UND `Delete` eines nicht existierenden Objekts |
-| 4 | Melde-Aufruf an Core LIC-05 bei Schreib-/Löschvorgang nachweislich ausgelöst, korrekte Größe | **bestanden** (mit Einschränkung s.o.) — `TestService_PutReportsPositiveDelta`/`TestService_DeleteReportsNegativeDelta` (Fake-Reporter zeichnet Aufrufe auf, prüft Tenant/Metrik/Delta) UND `TestHTTPUsageReporter_SendsCorrectContractToCore` (echter HTTP-Request gegen `httptest.Server`, der Cores Vertrag nachbildet — Header, JSON-Feldnamen) |
-
-## Build/Test-Ergebnis (192.168.1.131)
-
-```
-go build ./...  -> clean
-go vet ./...    -> clean
-make lint       -> clean (golangci-lint v2.1.6, aus Quelle mit go1.24.4 gebaut,
-                    da v1.63.4 den Zielstand go1.24 nicht linten konnte —
-                    .golangci.yml auf v2-Konfigurationsformat migriert)
-go test ./internal/storage/... -v -count=1  -> 11/11 Tests ok (3 S3-Tests real
-                    gegen lokal installiertes MinIO statt uebersprungen)
-```
-
-## Offener Punkt: Prüfsummen-Schreibpfad noch nicht befüllt
-
-`file_revisions.checksum_sha256` (FDN-02) wird aktuell von **keinem**
-Schreibpfad befüllt oder verifiziert — `internal/storage.Service.Put`
-berechnet keine Inhalts-Prüfsumme (das einzige SHA256 im Paket ist die
-HMAC-Signatur lokaler URLs, siehe oben, unabhängig vom Dateiinhalt). Die
-Spalte existiert seit FDN-02 ungenutzt. Nachgetragen als
-Akzeptanzkriterium/Prüfung in `DOC-01` (Upload-API), das den Hash auf
-Klartext berechnen und transaktional persistieren muss — Voraussetzung für
-Duplikaterkennung (`DOC-02`) und die spätere Integritätsprüfung
-(Archive `BAK-08`, siehe Sitzungsprotokoll 2026-08-29 zu externem,
-selbst nicht überwachtem Kunden-S3-Storage).
-
-## Gesamtergebnis
-
-**Bestanden**, mit einer dokumentierten Abhängigkeit auf Core-Seite
-(Abschnitt "Wichtiger Befund") — Core muss `internal/resync.Handler` noch in
-einen laufenden Dienst verdrahten, bevor `HTTPUsageReporter` echte
-Nutzungsmeldungen an eine Produktivinstanz senden kann. Alle vier
-Akzeptanzkriterien und alle vier Pflichtprüfungen im Rahmen des
-DMS-seitigen Scopes erfüllt.

dms/docs/FDN-04-PRUEFPROTOKOLL.md

@@ -1,77 +0,0 @@
-# FDN-04 – Prüfprotokoll: Job-Queue & Worker-Runtime
-
-Welle 3. Voraussetzung: FDN-02 (Status "Fertig").
-
-## Umsetzung
-
-`internal/jobqueue`:
-
-- `migrations/tenant/0002_processing_jobs.up.sql` — `processing_jobs`-Tabelle
-  (Status `pending`/`processing`/`succeeded`/`failed`/`dead_letter`,
-  `attempts`/`max_attempts`, `available_at` für Backoff-Terminierung,
-  `locked_at`/`locked_by` für die Sperre, `idempotency_key` UNIQUE).
-- `Queue.Enqueue` — reiht ein, mit optionalem `idempotency_key` (Dedup bei
-  Doppelzustellung, `ON CONFLICT DO UPDATE ... RETURNING id`).
-- `Queue.Dequeue` — `FOR UPDATE SKIP LOCKED`, holt entweder einen fälligen
-  `pending`-Job oder einen `processing`-Job, dessen Sperre älter als
-  `staleLockAfter` ist (Absturz-Wiedervorlage). Backoff-Intervallarithmetik
-  über `LEAST(attempts, 10) * interval '30 seconds'` — arithmetischer
-  Cast, keine String-Konkatenation (siehe "Bekannte Fehler vermeiden").
-- `Queue.Complete`/`Queue.Fail` — bei erschöpften Versuchen wandert der Job
-  in `dead_letter`.
-- `Queue.RequeueDeadLetter` — manuelle Wiederholung eines DLQ-Eintrags.
-- `Queue.Status` — Job-Status abfragbar.
-- `Worker`/`Handler` — In-Prozess-Worker-Goroutine, pollt und ruft `Handler`
-  je Job auf.
-
-## Prüfungen
-
-| # | Prüfung | Ergebnis |
-|---|---|---|
-| 1 | Absturz eines Workers führt zu erneuter Zustellung | **bestanden** — `TestDequeue_StaleLockIsRedelivered`: Job wird von `worker-crashed` gesperrt, NIE completed/failed (simulierter Absturz); sofortiger erneuter Dequeue-Versuch liefert `ErrNoJobAvailable` (Sperre noch frisch), nach Ablauf von `staleLockAfter` liefert `worker-2` denselben Job |
-| 2 | Idempotenz bei Doppelzustellung nachgewiesen | **bestanden** — `TestEnqueue_IdempotencyKeyPreventsDuplicate`: zweifache Einreihung mit gleichem `idempotency_key` erzeugt nachweislich nur 1 Zeile (per Abfrage bestätigt) |
-| 3 | DLQ-Eintrag manuell wiederholbar | **bestanden** — `TestRequeueDeadLetter`: Job nach erschöpften Versuchen in `dead_letter`, `RequeueDeadLetter` setzt zurück auf `pending` mit `attempts=0`; Requeue eines NICHT-DLQ-Jobs wird korrekt abgewiesen |
-
-## Reale Fehler gefunden und behoben (kein Vorab-Wissen, beim Testen entdeckt)
-
-1. **pgx-Typinferenz-Fehler bei ungenutztem Parameter**: `Dequeue`s SQL
-   übergab `workerID` als `$1`, ohne es in der Query zu referenzieren —
-   Postgres/pgx konnte den Typ von `$1` dadurch nicht ableiten
-   (`SQLSTATE 42P18`). Behoben durch Entfernen des toten Parameters
-   (workerID wird erst im nachfolgenden `UPDATE` gebraucht).
-2. **`$2::text[]`-Cast mit untypisiertem `nil`**: `typeFilter any` (statt
-   `[]string`) ließ pgx den Zieltyp des Casts nicht auflösen. Behoben durch
-   `[]string`-Typisierung der Variable.
-3. **Testinfrastruktur-Drift über Sitzungsgrenzen**: `dms_tenant_test`
-   sammelte über mehrere Testläufe (FDN-02/03/04) `schema_migrations`-Zustand
-   an, wodurch `internal/migrate`s Rollback-Test nur noch einen Teil der
-   Tabellen zurückrollte. Neues `scripts/reset-test-env.sh` (Datenbank
-   droppen+neu anlegen, analog Core `scripts/reset-test-env.sh`) sowie
-   `make check`-Target (Reset+vet+lint+test in einem Rutsch) behoben das
-   strukturell. Zusätzlich fehlte `-p 1` im `test`-Target — mehrere
-   Testpakete teilen sich dieselbe physische Test-DB, parallele
-   Paketausführung (Go-Testdefault) verursachte Querschläger zwischen
-   `internal/jobqueue` und `internal/migrate`.
-4. **`internal/jobqueue`s Test-Fixture räumte nicht auf**: `TRUNCATE` statt
-   `DROP TABLE` ließ die Tabelle `processing_jobs` stehen, wodurch
-   `internal/migrate`s eigene, versionierte Migration mit
-   `relation already exists` scheiterte. Behoben durch `DROP TABLE IF EXISTS`
-   im Test-Cleanup.
-
-## Build/Test-Ergebnis (192.168.1.131, `make check`)
-
-```
-go build ./...  -> clean
-scripts/reset-test-env.sh -> dms_tenant_test leer neu angelegt
-go vet ./...    -> clean
-golangci-lint run ./...  -> 0 issues
-go test ./... -p 1 -count=1  -> 4/4 Pakete ok, 0 Fehlschläge (inkl. 8 jobqueue-Tests, 3 migrate-Tests, 6 storage-Tests real gegen MinIO)
-```
-
-## Gesamtergebnis
-
-**Bestanden.** Alle drei Akzeptanzkriterien und alle drei Pflichtprüfungen
-erfüllt. Vier reale Fehler beim Testen gefunden und behoben (zwei
-Produktionscode-Bugs im SQL-Parameterhandling, zwei
-Testinfrastruktur-Bugs) — bestätigt erneut den Wert, jede Prüfung
-tatsächlich auf einem echten Testhost auszuführen statt nur zu behaupten.

dms/docs/FDN-09-PRUEFPROTOKOLL.md

@@ -1,57 +0,0 @@
-# FDN-09 – Prüfprotokoll: Verschlüsselung at rest & Schlüsselverwaltung
-
-Welle 2. Voraussetzung: FDN-01 (Status "Fertig"), Core API-10 (Status
-"Fertig").
-
-## Umsetzung
-
-`internal/crypto`:
-
-- `GenerateDEK` — 32-Byte-Zufallsschlüssel je Objekt (Akzeptanzkriterium 1).
-- `EncryptStream`/`DecryptStream` — AES-256-GCM auf dem Objektinhalt.
-- `WrapDEK`/`UnwrapDEK` — Envelope-Verpackung des DEK mit dem Tenant-KEK.
-- `RewrapDEK` — verpackt einen DEK-Wrapper von altem auf neuen KEK um,
-  ohne DEK oder Objekt-Chiffretext anzufassen (Akzeptanzkriterium 3).
-- `HTTPKEKProvider` — bezieht den Tenant-KEK über Cores
-  `internal/kek.Handler.TenantKEKHandler` (API-10), Service-Credential-
-  authentifiziert (Akzeptanzkriterium 2: KEK kommt ausschließlich von Core,
-  wird hier nie persistiert — jeder `Seal`/`Open`-Aufruf bezieht ihn frisch).
-- `Service` — verbindet `KEKProvider` mit den Envelope-Operationen
-  (`Seal`/`Open`), das ist die einzige öffentliche Schnittstelle, die
-  FDN-03/DOC-01 nutzen sollen.
-
-## Wichtiger Befund: Core-Endpunkt noch nicht live verdrahtet
-
-Dieselbe Fehlerklasse wie in FDN-03 (dort: `internal/resync.Handler`):
-`internal/kek.Handler` (inkl. `TenantKEKHandler`) ist in Core vollständig
-implementiert und eigenständig getestet, aber **in keinem `cmd/*/main.go`
-registriert** (per `grep` bestätigt, Stand 2026-08-29). `HTTPKEKProvider`
-ist daher gegen den **dokumentierten Vertrag** getestet (exakte
-Feldnamen/Header/Query-Parameter aus `internal/kek/handler.go` gelesen),
-nicht gegen eine echte laufende Core-Instanz. Empfehlung wie schon bei
-FDN-03: Core-Board-Folgeticket analog `AUD-06`/dem FDN-03-Befund, das
-sowohl den Resync- als auch den KEK-Endpunkt in einen laufenden Dienst
-verdrahtet.
-
-## Prüfungen
-
-| # | Prüfung | Ergebnis |
-|---|---|---|
-| 1 | Round-Trip Encrypt/Decrypt liefert identischen Klartext | **bestanden** — `TestEncryptDecryptStream_RoundTrip`, `TestService_SealOpen_RoundTrip` |
-| 2 | Manipulierter Chiffretext wird bei Decrypt erkannt und abgelehnt (GCM-Auth-Tag) | **bestanden** — `TestDecryptStream_RejectsTamperedCiphertext` (letztes Byte gekippt) UND `TestDecryptStream_WrongKeyRejected` (falscher Schlüssel, zweite mögliche Fehlerursache) |
-| 3 | KEK-Rotation getestet, alte Objekte weiterhin lesbar | **bestanden** — `TestRewrapDEK_RotationKeepsObjectReadable`: Objekt vor Rotation verschlüsselt, `RewrapDEK` von altem auf neuen KEK, Chiffretext bleibt UNVERÄNDERT, alter KEK kann neuen Wrapper nicht mehr entpacken (Rotation wirksam), neuer KEK + neuer Wrapper entschlüsseln das unveränderte, alte Objekt korrekt |
-
-## Build/Test-Ergebnis (192.168.1.131, `make check`)
-
-```
-go build ./...  -> clean
-go vet ./...    -> clean
-golangci-lint run ./...  -> 0 issues
-go test ./... -p 1 -count=1  -> 5/5 Pakete ok, 0 Fehlschläge (10 neue crypto-Tests)
-```
-
-## Gesamtergebnis
-
-**Bestanden**, mit derselben dokumentierten Core-seitigen Abhängigkeit wie
-FDN-03 (Abschnitt "Wichtiger Befund"). Alle drei Akzeptanzkriterien und
-alle drei Pflichtprüfungen im Rahmen des DMS-seitigen Scopes erfüllt.

dms/internal/crypto/envelope.go

@@ -1,140 +0,0 @@
-// Package crypto implementiert FDN-09: Envelope-Encryption fuer Objekte
-// at rest. Jedes Objekt bekommt einen eigenen, zufaelligen
-// Datenverschluesselungsschluessel (DEK, Akzeptanzkriterium 1), der mit
-// dem Tenant-Hauptschluessel (KEK) verpackt wird — der KEK selbst kommt
-// AUSSCHLIESSLICH von Core API-10 (Akzeptanzkriterium 2), wird hier nie
-// persistiert, nur fluechtig fuer eine Wrap-/Unwrap-Operation gehalten.
-package crypto
-
-import (
-	"bytes"
-	"crypto/aes"
-	"crypto/cipher"
-	"crypto/rand"
-	"errors"
-	"fmt"
-	"io"
-)
-
-// DEKSize/KEKSize sind die geforderten Laengen fuer AES-256-GCM.
-const (
-	DEKSize = 32
-	KEKSize = 32
-)
-
-// ErrDecryptFailed wird geliefert, wenn ein Chiffretext nicht entschluesselt
-// werden kann — falscher Schluessel ODER manipulierte Daten (Pruefung 2:
-// GCM-Auth-Tag erkennt Manipulation zuverlaessig, AEAD unterscheidet die
-// beiden Ursachen bewusst nicht, um keine Seitenkanal-Information ueber
-// "welcher Teil" falsch war preiszugeben).
-var ErrDecryptFailed = errors.New("crypto: entschluesselung fehlgeschlagen (falscher schluessel oder manipulierte daten)")
-
-// GenerateDEK erzeugt einen neuen, zufaelligen Datenverschluesselungs-
-// schluessel — fuer JEDES Objekt neu, nie wiederverwendet
-// (Akzeptanzkriterium 1).
-func GenerateDEK() ([]byte, error) {
-	dek := make([]byte, DEKSize)
-	if _, err := rand.Read(dek); err != nil {
-		return nil, fmt.Errorf("crypto: dek erzeugen: %w", err)
-	}
-	return dek, nil
-}
-
-func seal(key, plaintext []byte) ([]byte, error) {
-	block, err := aes.NewCipher(key)
-	if err != nil {
-		return nil, fmt.Errorf("crypto: aes-cipher erstellen: %w", err)
-	}
-	gcm, err := cipher.NewGCM(block)
-	if err != nil {
-		return nil, fmt.Errorf("crypto: gcm erstellen: %w", err)
-	}
-	nonce := make([]byte, gcm.NonceSize())
-	if _, err := rand.Read(nonce); err != nil {
-		return nil, fmt.Errorf("crypto: nonce erzeugen: %w", err)
-	}
-	return gcm.Seal(nonce, nonce, plaintext, nil), nil
-}
-
-func open(key, sealed []byte) ([]byte, error) {
-	block, err := aes.NewCipher(key)
-	if err != nil {
-		return nil, fmt.Errorf("crypto: aes-cipher erstellen: %w", err)
-	}
-	gcm, err := cipher.NewGCM(block)
-	if err != nil {
-		return nil, fmt.Errorf("crypto: gcm erstellen: %w", err)
-	}
-	if len(sealed) < gcm.NonceSize() {
-		return nil, ErrDecryptFailed
-	}
-	nonce, ciphertext := sealed[:gcm.NonceSize()], sealed[gcm.NonceSize():]
-	plaintext, err := gcm.Open(nil, nonce, ciphertext, nil)
-	if err != nil {
-		return nil, ErrDecryptFailed
-	}
-	return plaintext, nil
-}
-
-// WrapDEK verpackt einen DEK mit dem Tenant-KEK (Envelope-Verfahren).
-func WrapDEK(kek, dek []byte) ([]byte, error) {
-	wrapped, err := seal(kek, dek)
-	if err != nil {
-		return nil, fmt.Errorf("crypto: dek verpacken: %w", err)
-	}
-	return wrapped, nil
-}
-
-// UnwrapDEK entpackt einen zuvor mit WrapDEK verpackten DEK.
-func UnwrapDEK(kek, wrappedDEK []byte) ([]byte, error) {
-	return open(kek, wrappedDEK)
-}
-
-// RewrapDEK verpackt einen bereits vorhandenen DEK-Wrapper von oldKEK auf
-// newKEK um, OHNE den DEK selbst oder den Objekt-Chiffretext zu veraendern
-// (Akzeptanzkriterium 3: KEK-Rotation ohne Neuverschluesselung aller
-// Objekte — nur der DEK-Wrapper wird neu verpackt).
-func RewrapDEK(oldKEK, newKEK, wrappedDEK []byte) ([]byte, error) {
-	dek, err := UnwrapDEK(oldKEK, wrappedDEK)
-	if err != nil {
-		return nil, fmt.Errorf("crypto: dek mit altem kek entpacken: %w", err)
-	}
-	rewrapped, err := WrapDEK(newKEK, dek)
-	if err != nil {
-		return nil, fmt.Errorf("crypto: dek mit neuem kek verpacken: %w", err)
-	}
-	return rewrapped, nil
-}
-
-// EncryptStream verschluesselt den gesamten Inhalt von r mit dek
-// (AES-256-GCM) und liefert den Chiffretext als Stream. Liest r vollstaendig
-// in den Speicher (dasselbe Muster wie internal/storage.S3Driver.Put aus
-// FDN-03, das S3-PutObject ebenfalls vollstaendig puffert) — fuer sehr
-// grosse Dateien waere ein segmentiertes AEAD-Verfahren noetig, das ist
-// bewusst nicht Teil der "kleinsten Loesung" dieser Kachel.
-func EncryptStream(dek []byte, r io.Reader) (io.Reader, error) {
-	plaintext, err := io.ReadAll(r)
-	if err != nil {
-		return nil, fmt.Errorf("crypto: klartext lesen: %w", err)
-	}
-	ciphertext, err := seal(dek, plaintext)
-	if err != nil {
-		return nil, fmt.Errorf("crypto: verschluesseln: %w", err)
-	}
-	return bytes.NewReader(ciphertext), nil
-}
-
-// DecryptStream entschluesselt einen zuvor mit EncryptStream erzeugten
-// Chiffretext-Stream. Liefert ErrDecryptFailed bei manipuliertem Chiffretext
-// (Pruefung 2, GCM-Auth-Tag).
-func DecryptStream(dek []byte, r io.Reader) (io.Reader, error) {
-	ciphertext, err := io.ReadAll(r)
-	if err != nil {
-		return nil, fmt.Errorf("crypto: chiffretext lesen: %w", err)
-	}
-	plaintext, err := open(dek, ciphertext)
-	if err != nil {
-		return nil, err
-	}
-	return bytes.NewReader(plaintext), nil
-}

dms/internal/crypto/envelope_test.go

@@ -1,187 +0,0 @@
-package crypto
-
-import (
-	"bytes"
-	"errors"
-	"io"
-	"testing"
-)
-
-// TestGenerateDEK_NeverReused ist Akzeptanzkriterium 1: DEK wird pro
-// Objekt neu erzeugt, nie wiederverwendet.
-func TestGenerateDEK_NeverReused(t *testing.T) {
-	seen := map[string]bool{}
-	for i := 0; i < 50; i++ {
-		dek, err := GenerateDEK()
-		if err != nil {
-			t.Fatalf("generatedek: %v", err)
-		}
-		if len(dek) != DEKSize {
-			t.Fatalf("dek-laenge = %d, want %d", len(dek), DEKSize)
-		}
-		key := string(dek)
-		if seen[key] {
-			t.Fatal("generatedek lieferte denselben schluessel zweimal")
-		}
-		seen[key] = true
-	}
-}
-
-// TestEncryptDecryptStream_RoundTrip ist Pruefung 1: Round-Trip liefert
-// identischen Klartext.
-func TestEncryptDecryptStream_RoundTrip(t *testing.T) {
-	dek, err := GenerateDEK()
-	if err != nil {
-		t.Fatalf("generatedek: %v", err)
-	}
-	plaintext := []byte("Rechnung 2026-0001 — vertraulicher Inhalt")
-
-	ciphertext, err := EncryptStream(dek, bytes.NewReader(plaintext))
-	if err != nil {
-		t.Fatalf("encryptstream: %v", err)
-	}
-	ciphertextBytes, err := io.ReadAll(ciphertext)
-	if err != nil {
-		t.Fatalf("chiffretext lesen: %v", err)
-	}
-	if bytes.Equal(ciphertextBytes, plaintext) {
-		t.Fatal("chiffretext ist identisch zum klartext - keine verschluesselung stattgefunden")
-	}
-
-	decrypted, err := DecryptStream(dek, bytes.NewReader(ciphertextBytes))
-	if err != nil {
-		t.Fatalf("decryptstream: %v", err)
-	}
-	got, err := io.ReadAll(decrypted)
-	if err != nil {
-		t.Fatalf("klartext lesen: %v", err)
-	}
-	if !bytes.Equal(got, plaintext) {
-		t.Fatalf("entschluesselter klartext = %q, want %q", got, plaintext)
-	}
-}
-
-// TestDecryptStream_RejectsTamperedCiphertext ist Pruefung 2: manipulierter
-// Chiffretext wird bei Decrypt erkannt und abgelehnt (GCM-Auth-Tag).
-func TestDecryptStream_RejectsTamperedCiphertext(t *testing.T) {
-	dek, err := GenerateDEK()
-	if err != nil {
-		t.Fatalf("generatedek: %v", err)
-	}
-	ciphertext, err := EncryptStream(dek, bytes.NewReader([]byte("geheimer inhalt")))
-	if err != nil {
-		t.Fatalf("encryptstream: %v", err)
-	}
-	tampered, err := io.ReadAll(ciphertext)
-	if err != nil {
-		t.Fatalf("chiffretext lesen: %v", err)
-	}
-	// Ein Byte in der Mitte des Chiffretexts kippen (nach dem Nonce-Praefix).
-	tampered[len(tampered)-1] ^= 0xFF
-
-	if _, err := DecryptStream(dek, bytes.NewReader(tampered)); !errors.Is(err, ErrDecryptFailed) {
-		t.Fatalf("manipulierter chiffretext: erwartet ErrDecryptFailed, habe %v", err)
-	}
-}
-
-// TestDecryptStream_WrongKeyRejected prueft den zweiten Fall, in dem
-// Entschluesselung scheitern muss: falscher Schluessel statt Manipulation.
-func TestDecryptStream_WrongKeyRejected(t *testing.T) {
-	dek1, _ := GenerateDEK()
-	dek2, _ := GenerateDEK()
-	ciphertext, err := EncryptStream(dek1, bytes.NewReader([]byte("inhalt")))
-	if err != nil {
-		t.Fatalf("encryptstream: %v", err)
-	}
-	ciphertextBytes, _ := io.ReadAll(ciphertext)
-
-	if _, err := DecryptStream(dek2, bytes.NewReader(ciphertextBytes)); !errors.Is(err, ErrDecryptFailed) {
-		t.Fatalf("falscher schluessel: erwartet ErrDecryptFailed, habe %v", err)
-	}
-}
-
-// TestWrapUnwrapDEK_RoundTrip prueft das Envelope-Verpacken des DEK selbst.
-func TestWrapUnwrapDEK_RoundTrip(t *testing.T) {
-	kek := make([]byte, KEKSize)
-	for i := range kek {
-		kek[i] = byte(i)
-	}
-	dek, err := GenerateDEK()
-	if err != nil {
-		t.Fatalf("generatedek: %v", err)
-	}
-
-	wrapped, err := WrapDEK(kek, dek)
-	if err != nil {
-		t.Fatalf("wrapdek: %v", err)
-	}
-	if bytes.Equal(wrapped, dek) {
-		t.Fatal("wrapdek lieferte den unveraenderten dek")
-	}
-
-	unwrapped, err := UnwrapDEK(kek, wrapped)
-	if err != nil {
-		t.Fatalf("unwrapdek: %v", err)
-	}
-	if !bytes.Equal(unwrapped, dek) {
-		t.Fatal("entpackter dek stimmt nicht mit original ueberein")
-	}
-}
-
-// TestRewrapDEK_RotationKeepsObjectReadable ist Pruefung 3: KEK-Rotation
-// getestet, alte Objekte weiterhin lesbar — OHNE dass der Chiffretext des
-// Objekts selbst jemals angefasst wird (Akzeptanzkriterium 3).
-func TestRewrapDEK_RotationKeepsObjectReadable(t *testing.T) {
-	oldKEK := bytes.Repeat([]byte{0x01}, KEKSize)
-	newKEK := bytes.Repeat([]byte{0x02}, KEKSize)
-
-	dek, err := GenerateDEK()
-	if err != nil {
-		t.Fatalf("generatedek: %v", err)
-	}
-	plaintext := []byte("altes objekt, vor der rotation verschluesselt")
-	ciphertext, err := EncryptStream(dek, bytes.NewReader(plaintext))
-	if err != nil {
-		t.Fatalf("encryptstream: %v", err)
-	}
-	ciphertextBytes, _ := io.ReadAll(ciphertext)
-
-	wrappedOld, err := WrapDEK(oldKEK, dek)
-	if err != nil {
-		t.Fatalf("wrapdek (alt): %v", err)
-	}
-
-	// Rotation: NUR der DEK-Wrapper wird neu verpackt, der Chiffretext
-	// (ciphertextBytes) wird nicht angefasst.
-	wrappedNew, err := RewrapDEK(oldKEK, newKEK, wrappedOld)
-	if err != nil {
-		t.Fatalf("rewrapdek: %v", err)
-	}
-	if bytes.Equal(wrappedNew, wrappedOld) {
-		t.Fatal("rewrapdek lieferte denselben wrapper wie vor der rotation")
-	}
-
-	// Der alte KEK kann den NEUEN Wrapper nicht mehr entpacken (Rotation
-	// war wirksam).
-	if _, err := UnwrapDEK(oldKEK, wrappedNew); !errors.Is(err, ErrDecryptFailed) {
-		t.Fatal("alter kek konnte den nach der rotation neu verpackten dek weiterhin entpacken")
-	}
-
-	// Mit dem NEUEN KEK und dem neuen Wrapper ist das unveraenderte, alte
-	// Objekt weiterhin vollstaendig lesbar.
-	dekAfterRotation, err := UnwrapDEK(newKEK, wrappedNew)
-	if err != nil {
-		t.Fatalf("unwrapdek (neu) nach rotation: %v", err)
-	}
-	decrypted, err := DecryptStream(dekAfterRotation, bytes.NewReader(ciphertextBytes))
-	if err != nil {
-		t.Fatalf("decryptstream nach rotation: %v", err)
-	}
-	got, err := io.ReadAll(decrypted)
-	if err != nil {
-		t.Fatalf("klartext lesen: %v", err)
-	}
-	if !bytes.Equal(got, plaintext) {
-		t.Fatalf("altes objekt nach rotation = %q, want %q", got, plaintext)
-	}
-}

dms/internal/crypto/kekprovider_test.go

@@ -1,65 +0,0 @@
-package crypto
-
-import (
-	"context"
-	"encoding/base64"
-	"encoding/json"
-	"net/http"
-	"net/http/httptest"
-	"testing"
-)
-
-// TestHTTPKEKProvider_SendsCorrectContractToCore ist der Nachweis, dass
-// HTTPKEKProvider exakt den Vertrag von Core internal/kek.Handler.
-// TenantKEKHandler bedient (Service-Credential-Header, tenant-Query-Param,
-// JSON-Feldname) — echte Vernetzung gegen einen laufenden Core-Prozess ist
-// nicht Teil dieses Tests (siehe FDN-09-Pruefprotokoll: derselbe
-// "nicht verdrahtet"-Befund wie bei internal/resync in FDN-03), daher hier
-// gegen einen httptest-Server geprueft, der denselben Vertrag nachbildet.
-func TestHTTPKEKProvider_SendsCorrectContractToCore(t *testing.T) {
-	wantKEK := make([]byte, KEKSize)
-	for i := range wantKEK {
-		wantKEK[i] = byte(i)
-	}
-
-	var gotClientID, gotClientSecret, gotTenant string
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		gotClientID = r.Header.Get("X-Nexarch-Client-Id")
-		gotClientSecret = r.Header.Get("X-Nexarch-Client-Secret")
-		gotTenant = r.URL.Query().Get("tenant")
-		w.Header().Set("Content-Type", "application/json")
-		_ = json.NewEncoder(w).Encode(tenantKEKResponse{TenantKEKBase64: base64.StdEncoding.EncodeToString(wantKEK)})
-	}))
-	defer srv.Close()
-
-	provider := NewHTTPKEKProvider(srv.URL, "dms-service-client", "dms-service-secret", nil)
-	got, err := provider.TenantKEK(context.Background(), "acme")
-	if err != nil {
-		t.Fatalf("tenantkek: %v", err)
-	}
-
-	if gotClientID != "dms-service-client" || gotClientSecret != "dms-service-secret" {
-		t.Fatalf("service-credential-header falsch: id=%q secret=%q", gotClientID, gotClientSecret)
-	}
-	if gotTenant != "acme" {
-		t.Fatalf("tenant-query-parameter = %q, want %q", gotTenant, "acme")
-	}
-	if len(got) != KEKSize || got[0] != wantKEK[0] {
-		t.Fatalf("erhaltener kek stimmt nicht mit erwartetem ueberein")
-	}
-}
-
-// TestHTTPKEKProvider_RejectsNonOKStatus prueft, dass ein von Core
-// abgelehnter Aufruf (z.B. Modul nicht fuer diesen Mandanten aktiv,
-// ErrForbidden auf Core-Seite) als Fehler zurueckgegeben wird.
-func TestHTTPKEKProvider_RejectsNonOKStatus(t *testing.T) {
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		http.Error(w, "zugriff auf diesen mandanten verweigert", http.StatusForbidden)
-	}))
-	defer srv.Close()
-
-	provider := NewHTTPKEKProvider(srv.URL, "x", "y", nil)
-	if _, err := provider.TenantKEK(context.Background(), "fremder-tenant"); err == nil {
-		t.Fatal("erwartet fehler bei abgelehntem kek-bezug, habe nil")
-	}
-}

dms/internal/crypto/service.go

@@ -1,65 +0,0 @@
-package crypto
-
-import (
-	"context"
-	"fmt"
-	"io"
-)
-
-// Envelope ist das Ergebnis einer Seal-Operation: der Chiffretext-Stream
-// plus der mit dem Tenant-KEK verpackte DEK, der zusammen mit dem Objekt
-// persistiert werden muss (z.B. in file_revisions, FDN-02 — die konkrete
-// Spalte ist nicht Bestandteil dieser Kachel, siehe "Nicht Bestandteil").
-type Envelope struct {
-	Ciphertext io.Reader
-	WrappedDEK []byte
-}
-
-// Service verbindet KEKProvider mit den Envelope-Operationen — die
-// Storage-Abstraktion (FDN-03) ruft ausschliesslich Service auf, nie die
-// Einzelfunktionen aus envelope.go direkt.
-type Service struct {
-	kek KEKProvider
-}
-
-func NewService(kek KEKProvider) *Service {
-	return &Service{kek: kek}
-}
-
-// Seal erzeugt einen neuen DEK (Akzeptanzkriterium 1), verschluesselt
-// plaintext damit und verpackt den DEK mit dem aktuellen Tenant-KEK
-// (Akzeptanzkriterium 2 — der KEK wird bei JEDEM Aufruf frisch von Core
-// bezogen, nie zwischengespeichert).
-func (s *Service) Seal(ctx context.Context, tenantSlug string, plaintext io.Reader) (*Envelope, error) {
-	dek, err := GenerateDEK()
-	if err != nil {
-		return nil, err
-	}
-	ciphertext, err := EncryptStream(dek, plaintext)
-	if err != nil {
-		return nil, err
-	}
-	kek, err := s.kek.TenantKEK(ctx, tenantSlug)
-	if err != nil {
-		return nil, fmt.Errorf("crypto: tenant-kek beziehen: %w", err)
-	}
-	wrappedDEK, err := WrapDEK(kek, dek)
-	if err != nil {
-		return nil, err
-	}
-	return &Envelope{Ciphertext: ciphertext, WrappedDEK: wrappedDEK}, nil
-}
-
-// Open entpackt den DEK mit dem aktuellen Tenant-KEK und entschluesselt
-// ciphertext damit.
-func (s *Service) Open(ctx context.Context, tenantSlug string, wrappedDEK []byte, ciphertext io.Reader) (io.Reader, error) {
-	kek, err := s.kek.TenantKEK(ctx, tenantSlug)
-	if err != nil {
-		return nil, fmt.Errorf("crypto: tenant-kek beziehen: %w", err)
-	}
-	dek, err := UnwrapDEK(kek, wrappedDEK)
-	if err != nil {
-		return nil, err
-	}
-	return DecryptStream(dek, ciphertext)
-}

dms/internal/crypto/service_test.go

@@ -1,77 +0,0 @@
-package crypto
-
-import (
-	"bytes"
-	"context"
-	"io"
-	"testing"
-)
-
-// fakeKEKProvider liefert einen fest hinterlegten Tenant-KEK, ohne echten
-// HTTP-Aufruf — fuer Tests, die Service isoliert vom Core-Kontrakt pruefen
-// wollen (der Kontrakt selbst ist in kekprovider_test.go geprueft).
-type fakeKEKProvider struct {
-	kek   []byte
-	calls int
-}
-
-func (f *fakeKEKProvider) TenantKEK(ctx context.Context, tenantSlug string) ([]byte, error) {
-	f.calls++
-	return f.kek, nil
-}
-
-// TestService_SealOpen_RoundTrip ist der End-to-End-Nachweis fuer
-// Pruefung 1 ueber Service statt die Einzelfunktionen.
-func TestService_SealOpen_RoundTrip(t *testing.T) {
-	kekProvider := &fakeKEKProvider{kek: bytes.Repeat([]byte{0x07}, KEKSize)}
-	svc := NewService(kekProvider)
-	ctx := context.Background()
-	plaintext := []byte("vertraulicher dokumentinhalt")
-
-	env, err := svc.Seal(ctx, "acme", bytes.NewReader(plaintext))
-	if err != nil {
-		t.Fatalf("seal: %v", err)
-	}
-	ciphertextBytes, err := io.ReadAll(env.Ciphertext)
-	if err != nil {
-		t.Fatalf("chiffretext lesen: %v", err)
-	}
-	if bytes.Equal(ciphertextBytes, plaintext) {
-		t.Fatal("chiffretext ist identisch zum klartext")
-	}
-	if len(env.WrappedDEK) == 0 {
-		t.Fatal("erwartet nicht-leeren wrappeddek")
-	}
-
-	decrypted, err := svc.Open(ctx, "acme", env.WrappedDEK, bytes.NewReader(ciphertextBytes))
-	if err != nil {
-		t.Fatalf("open: %v", err)
-	}
-	got, err := io.ReadAll(decrypted)
-	if err != nil {
-		t.Fatalf("klartext lesen: %v", err)
-	}
-	if !bytes.Equal(got, plaintext) {
-		t.Fatalf("entschluesselter klartext = %q, want %q", got, plaintext)
-	}
-}
-
-// TestService_Seal_NeverPersistsKEK ist Akzeptanzkriterium 2 (struktureller
-// Nachweis): Service haelt den KEK nicht ueber einen Aufruf hinaus fest —
-// jeder Seal/Open-Aufruf bezieht ihn frisch ueber KEKProvider.
-func TestService_Seal_NeverPersistsKEK(t *testing.T) {
-	kekProvider := &fakeKEKProvider{kek: bytes.Repeat([]byte{0x09}, KEKSize)}
-	svc := NewService(kekProvider)
-	ctx := context.Background()
-
-	if _, err := svc.Seal(ctx, "acme", bytes.NewReader([]byte("a"))); err != nil {
-		t.Fatalf("seal 1: %v", err)
-	}
-	if _, err := svc.Seal(ctx, "acme", bytes.NewReader([]byte("b"))); err != nil {
-		t.Fatalf("seal 2: %v", err)
-	}
-
-	if kekProvider.calls != 2 {
-		t.Fatalf("erwartet 2 kek-abrufe (einer je Seal-Aufruf, kein Caching), habe %d", kekProvider.calls)
-	}
-}

dms/internal/jobqueue/queue.go

@@ -1,238 +0,0 @@
-// Package jobqueue implementiert FDN-04: eine Postgres-gestuetzte
-// Job-Queue mit Wiederholungslogik, Backoff und Dead-Letter-Queue — kein
-// Redis/AMQP (siehe Ticket-Vorgabe). FOR UPDATE SKIP LOCKED erlaubt
-// mehrere gleichzeitige Worker-Goroutinen (auch mehrinstanzfaehig, da der
-// Zustand ausschliesslich in Postgres liegt, keine In-Memory-Zaehler —
-// dieselbe Konvention wie Core internal/lockout, siehe "Bekannte Fehler
-// vermeiden" im Ticket).
-package jobqueue
-
-import (
-	"context"
-	"encoding/json"
-	"errors"
-	"fmt"
-	"time"
-
-	"github.com/jackc/pgx/v5"
-	"github.com/jackc/pgx/v5/pgxpool"
-)
-
-// Status-Werte spiegeln den CHECK-Constraint der Migration.
-const (
-	StatusPending    = "pending"
-	StatusProcessing = "processing"
-	StatusSucceeded  = "succeeded"
-	StatusFailed     = "failed"
-	StatusDeadLetter = "dead_letter"
-)
-
-// ErrNotFound wird geliefert, wenn ein angefragter Job nicht existiert.
-var ErrNotFound = errors.New("jobqueue: job nicht gefunden")
-
-// ErrNoJobAvailable wird von Dequeue geliefert, wenn aktuell kein
-// abholbarer Job vorhanden ist (kein Fehlerzustand, sondern der Normalfall
-// bei leerer Queue).
-var ErrNoJobAvailable = errors.New("jobqueue: kein job verfuegbar")
-
-// Job ist eine einzelne Aufgabe in der Queue.
-type Job struct {
-	ID          string
-	JobType     string
-	Payload     json.RawMessage
-	Status      string
-	Attempts    int
-	MaxAttempts int
-	LastError   *string
-}
-
-// DefaultMaxAttempts/DefaultStaleLockAfter sind Standardwerte, ueberschreibbar
-// je Enqueue-Aufruf (MaxAttempts) bzw. am Queue selbst (StaleLockAfter).
-const (
-	DefaultMaxAttempts = 5
-)
-
-// Queue kapselt den Zugriff auf processing_jobs.
-type Queue struct {
-	pool           *pgxpool.Pool
-	staleLockAfter time.Duration
-}
-
-// NewQueue erzeugt eine Queue. staleLockAfter legt fest, ab wann ein
-// Job, der als "processing" markiert ist, aber dessen Worker vermutlich
-// abgestuerzt ist, wieder als abholbar gilt (Pruefung 1: Absturz fuehrt zu
-// erneuter Zustellung) — kein Heartbeat-Mechanismus noetig, ein grosszuegiges
-// Zeitfenster genuegt fuer die "kleinste Loesung".
-func NewQueue(pool *pgxpool.Pool, staleLockAfter time.Duration) *Queue {
-	return &Queue{pool: pool, staleLockAfter: staleLockAfter}
-}
-
-// EnqueueOptions steuert optionale Einreih-Parameter.
-type EnqueueOptions struct {
-	// IdempotencyKey verhindert doppelte Einreihung derselben logischen
-	// Aufgabe (Pruefung 2: Idempotenz bei Doppelzustellung) — leer bedeutet
-	// kein Dedup-Anspruch.
-	IdempotencyKey string
-	MaxAttempts    int
-}
-
-// Enqueue reiht einen neuen Job ein (Akzeptanzkriterium 1). Bei gesetztem
-// IdempotencyKey und bereits existierendem gleichen Key wird die ID des
-// BEREITS vorhandenen Jobs zurueckgegeben, kein Duplikat angelegt.
-func (q *Queue) Enqueue(ctx context.Context, jobType string, payload any, opts EnqueueOptions) (string, error) {
-	payloadJSON, err := json.Marshal(payload)
-	if err != nil {
-		return "", fmt.Errorf("jobqueue: payload serialisieren: %w", err)
-	}
-	maxAttempts := opts.MaxAttempts
-	if maxAttempts <= 0 {
-		maxAttempts = DefaultMaxAttempts
-	}
-
-	var idempotencyKey any
-	if opts.IdempotencyKey != "" {
-		idempotencyKey = opts.IdempotencyKey
-	}
-
-	var id string
-	err = q.pool.QueryRow(ctx, `
-		INSERT INTO processing_jobs (job_type, payload, idempotency_key, max_attempts)
-		VALUES ($1, $2, $3, $4)
-		ON CONFLICT (idempotency_key) DO UPDATE SET job_type = processing_jobs.job_type
-		RETURNING id
-	`, jobType, payloadJSON, idempotencyKey, maxAttempts).Scan(&id)
-	if err != nil {
-		return "", fmt.Errorf("jobqueue: job einreihen: %w", err)
-	}
-	return id, nil
-}
-
-// Dequeue holt GENAU EINEN abholbaren Job (faellig UND nicht bereits von
-// einem anderen Worker gesperrt, ODER dessen Sperre als abgestanden gilt)
-// und markiert ihn atomar als "processing" (Akzeptanzkriterium 1 / Pruefung
-// 1 — FOR UPDATE SKIP LOCKED erlaubt mehreren Worker-Goroutinen
-// gleichzeitigen Aufruf ohne sich gegenseitig zu blockieren oder denselben
-// Job doppelt zu holen).
-func (q *Queue) Dequeue(ctx context.Context, workerID string, jobTypes []string) (*Job, error) {
-	tx, err := q.pool.Begin(ctx)
-	if err != nil {
-		return nil, fmt.Errorf("jobqueue: transaktion starten: %w", err)
-	}
-	defer func() { _ = tx.Rollback(ctx) }()
-
-	var typeFilter []string
-	if len(jobTypes) > 0 {
-		typeFilter = jobTypes
-	}
-
-	row := tx.QueryRow(ctx, `
-		SELECT id, job_type, payload, status, attempts, max_attempts, last_error
-		FROM processing_jobs
-		WHERE (
-			(status = 'pending' AND available_at <= now())
-			OR (status = 'processing' AND locked_at <= now() - ($2 * interval '1 second'))
-		)
-		AND ($1::text[] IS NULL OR job_type = ANY($1))
-		ORDER BY available_at
-		FOR UPDATE SKIP LOCKED
-		LIMIT 1
-	`, typeFilter, q.staleLockAfter.Seconds())
-
-	var j Job
-	if err := row.Scan(&j.ID, &j.JobType, &j.Payload, &j.Status, &j.Attempts, &j.MaxAttempts, &j.LastError); err != nil {
-		if errors.Is(err, pgx.ErrNoRows) {
-			return nil, ErrNoJobAvailable
-		}
-		return nil, fmt.Errorf("jobqueue: naechsten job lesen: %w", err)
-	}
-
-	if _, err := tx.Exec(ctx, `
-		UPDATE processing_jobs
-		SET status = 'processing', attempts = attempts + 1, locked_at = now(), locked_by = $2, updated_at = now()
-		WHERE id = $1
-	`, j.ID, workerID); err != nil {
-		return nil, fmt.Errorf("jobqueue: job sperren: %w", err)
-	}
-
-	if err := tx.Commit(ctx); err != nil {
-		return nil, fmt.Errorf("jobqueue: dequeue committen: %w", err)
-	}
-
-	j.Status = StatusProcessing
-	j.Attempts++
-	return &j, nil
-}
-
-// Complete markiert einen Job als erfolgreich abgeschlossen.
-func (q *Queue) Complete(ctx context.Context, jobID string) error {
-	tag, err := q.pool.Exec(ctx, `
-		UPDATE processing_jobs SET status = 'succeeded', locked_at = NULL, locked_by = NULL, updated_at = now()
-		WHERE id = $1
-	`, jobID)
-	if err != nil {
-		return fmt.Errorf("jobqueue: job abschliessen: %w", err)
-	}
-	if tag.RowsAffected() == 0 {
-		return ErrNotFound
-	}
-	return nil
-}
-
-// Fail markiert einen Job als fehlgeschlagen (Akzeptanzkriterium 2): sind
-// die maximalen Versuche erreicht, wandert der Job in die Dead-Letter-Queue
-// (status='dead_letter'), sonst wird er mit exponentiellem Backoff erneut
-// eingeplant. Backoff-Berechnung nutzt arithmetischen Intervall-Cast
-// (attempts * interval), KEINE String-Konkatenation (siehe "Bekannte
-// Fehler vermeiden" im Ticket).
-func (q *Queue) Fail(ctx context.Context, jobID string, cause error) error {
-	errMsg := cause.Error()
-	tag, err := q.pool.Exec(ctx, `
-		UPDATE processing_jobs
-		SET status = CASE WHEN attempts >= max_attempts THEN 'dead_letter' ELSE 'pending' END,
-		    available_at = now() + (LEAST(attempts, 10) * interval '30 seconds'),
-		    locked_at = NULL, locked_by = NULL, last_error = $2, updated_at = now()
-		WHERE id = $1
-	`, jobID, errMsg)
-	if err != nil {
-		return fmt.Errorf("jobqueue: fehlschlag erfassen: %w", err)
-	}
-	if tag.RowsAffected() == 0 {
-		return ErrNotFound
-	}
-	return nil
-}
-
-// Status liefert den aktuellen Zustand eines Jobs (Akzeptanzkriterium 3).
-func (q *Queue) Status(ctx context.Context, jobID string) (*Job, error) {
-	var j Job
-	err := q.pool.QueryRow(ctx, `
-		SELECT id, job_type, payload, status, attempts, max_attempts, last_error
-		FROM processing_jobs WHERE id = $1
-	`, jobID).Scan(&j.ID, &j.JobType, &j.Payload, &j.Status, &j.Attempts, &j.MaxAttempts, &j.LastError)
-	if err != nil {
-		if errors.Is(err, pgx.ErrNoRows) {
-			return nil, ErrNotFound
-		}
-		return nil, fmt.Errorf("jobqueue: job-status lesen: %w", err)
-	}
-	return &j, nil
-}
-
-// RequeueDeadLetter holt einen Job manuell aus der Dead-Letter-Queue zurueck
-// in "pending", mit zurueckgesetztem Versuchszaehler (Pruefung 3: DLQ-Eintrag
-// manuell wiederholbar). Nur fuer Jobs, die tatsaechlich in dead_letter
-// stehen — verhindert versehentliches Requeue eines noch laufenden Jobs.
-func (q *Queue) RequeueDeadLetter(ctx context.Context, jobID string) error {
-	tag, err := q.pool.Exec(ctx, `
-		UPDATE processing_jobs
-		SET status = 'pending', attempts = 0, available_at = now(), last_error = NULL, updated_at = now()
-		WHERE id = $1 AND status = 'dead_letter'
-	`, jobID)
-	if err != nil {
-		return fmt.Errorf("jobqueue: dead-letter-job erneut einreihen: %w", err)
-	}
-	if tag.RowsAffected() == 0 {
-		return fmt.Errorf("jobqueue: job %q steht nicht in dead_letter (oder existiert nicht): %w", jobID, ErrNotFound)
-	}
-	return nil
-}

dms/internal/jobqueue/queue_test.go

@@ -1,233 +0,0 @@
-package jobqueue
-
-import (
-	"context"
-	"encoding/json"
-	"errors"
-	"os"
-	"testing"
-	"time"
-
-	"github.com/jackc/pgx/v5/pgxpool"
-)
-
-func setupTest(t *testing.T) *pgxpool.Pool {
-	t.Helper()
-	dsn := os.Getenv("TEST_TENANT_DSN")
-	if dsn == "" {
-		t.Skip("TEST_TENANT_DSN nicht gesetzt, Integrationstest uebersprungen")
-	}
-	ctx := context.Background()
-
-	pool, err := pgxpool.New(ctx, dsn)
-	if err != nil {
-		t.Fatalf("pool: %v", err)
-	}
-	t.Cleanup(func() { pool.Close() })
-
-	if _, err := pool.Exec(ctx, `
-		CREATE EXTENSION IF NOT EXISTS pgcrypto;
-		CREATE TABLE IF NOT EXISTS processing_jobs (
-			id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-			job_type        TEXT NOT NULL,
-			payload         JSONB NOT NULL DEFAULT '{}'::jsonb,
-			idempotency_key TEXT UNIQUE,
-			status          TEXT NOT NULL DEFAULT 'pending'
-			                CHECK (status IN ('pending', 'processing', 'succeeded', 'failed', 'dead_letter')),
-			attempts        INT NOT NULL DEFAULT 0,
-			max_attempts    INT NOT NULL DEFAULT 5,
-			available_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
-			locked_at       TIMESTAMPTZ,
-			locked_by       TEXT,
-			last_error      TEXT,
-			created_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
-			updated_at      TIMESTAMPTZ NOT NULL DEFAULT now()
-		);
-	`); err != nil {
-		t.Fatalf("schema: %v", err)
-	}
-	// DROP statt nur TRUNCATE: internal/jobqueue und internal/migrate teilen
-	// sich dieselbe physische Test-Datenbank (TEST_TENANT_DSN) ueber
-	// Paketgrenzen hinweg. Bliebe die Tabelle stehen, wuerde internal/migrate
-	// spaeter mit "relation already exists" gegen die von diesem Fixture
-	// angelegte, aber unversionierte Tabelle scheitern.
-	t.Cleanup(func() {
-		_, _ = pool.Exec(context.Background(), `DROP TABLE IF EXISTS processing_jobs`)
-	})
-	return pool
-}
-
-// TestEnqueueDequeueComplete ist Akzeptanzkriterium 1: Jobs werden
-// zuverlaessig eingereiht und verarbeitet.
-func TestEnqueueDequeueComplete(t *testing.T) {
-	pool := setupTest(t)
-	q := NewQueue(pool, time.Minute)
-	ctx := context.Background()
-
-	id, err := q.Enqueue(ctx, "index-document", map[string]string{"document_id": "d1"}, EnqueueOptions{})
-	if err != nil {
-		t.Fatalf("enqueue: %v", err)
-	}
-
-	job, err := q.Dequeue(ctx, "worker-1", nil)
-	if err != nil {
-		t.Fatalf("dequeue: %v", err)
-	}
-	if job.ID != id {
-		t.Fatalf("dequeue lieferte job %q, want %q", job.ID, id)
-	}
-	if job.Status != StatusProcessing {
-		t.Fatalf("status nach dequeue = %q, want %q", job.Status, StatusProcessing)
-	}
-	var payload map[string]string
-	if err := json.Unmarshal(job.Payload, &payload); err != nil {
-		t.Fatalf("payload dekodieren: %v", err)
-	}
-	if payload["document_id"] != "d1" {
-		t.Fatalf("payload = %v, want document_id=d1", payload)
-	}
-
-	if err := q.Complete(ctx, job.ID); err != nil {
-		t.Fatalf("complete: %v", err)
-	}
-
-	status, err := q.Status(ctx, job.ID)
-	if err != nil {
-		t.Fatalf("status: %v", err)
-	}
-	if status.Status != StatusSucceeded {
-		t.Fatalf("endstatus = %q, want %q", status.Status, StatusSucceeded)
-	}
-}
-
-// TestDequeue_NoJobAvailable prueft den Leerfall.
-func TestDequeue_NoJobAvailable(t *testing.T) {
-	pool := setupTest(t)
-	q := NewQueue(pool, time.Minute)
-
-	if _, err := q.Dequeue(context.Background(), "worker-1", nil); !errors.Is(err, ErrNoJobAvailable) {
-		t.Fatalf("erwartet ErrNoJobAvailable, habe %v", err)
-	}
-}
-
-// TestFail_LandsInDeadLetterAfterMaxAttempts ist Akzeptanzkriterium 2.
-func TestFail_LandsInDeadLetterAfterMaxAttempts(t *testing.T) {
-	pool := setupTest(t)
-	q := NewQueue(pool, time.Minute)
-	ctx := context.Background()
-
-	id, err := q.Enqueue(ctx, "ocr", nil, EnqueueOptions{MaxAttempts: 2})
-	if err != nil {
-		t.Fatalf("enqueue: %v", err)
-	}
-
-	// Versuch 1: schlaegt fehl, geht zurueck nach "pending" (max_attempts=2 noch nicht erreicht).
-	job, err := q.Dequeue(ctx, "worker-1", nil)
-	if err != nil {
-		t.Fatalf("dequeue 1: %v", err)
-	}
-	if err := q.Fail(ctx, job.ID, errors.New("ocr-engine nicht erreichbar")); err != nil {
-		t.Fatalf("fail 1: %v", err)
-	}
-	status, err := q.Status(ctx, id)
-	if err != nil {
-		t.Fatalf("status nach fail 1: %v", err)
-	}
-	if status.Status != StatusPending {
-		t.Fatalf("status nach fail 1 = %q, want %q (noch nicht erschoepft)", status.Status, StatusPending)
-	}
-
-	// Versuch 2: Backoff manuell umgehen (available_at direkt zuruecksetzen,
-	// damit der Test nicht auf echten Backoff warten muss).
-	if _, err := pool.Exec(ctx, `UPDATE processing_jobs SET available_at = now() WHERE id = $1`, id); err != nil {
-		t.Fatalf("available_at zuruecksetzen: %v", err)
-	}
-	job2, err := q.Dequeue(ctx, "worker-1", nil)
-	if err != nil {
-		t.Fatalf("dequeue 2: %v", err)
-	}
-	if err := q.Fail(ctx, job2.ID, errors.New("ocr-engine weiterhin nicht erreichbar")); err != nil {
-		t.Fatalf("fail 2: %v", err)
-	}
-
-	final, err := q.Status(ctx, id)
-	if err != nil {
-		t.Fatalf("status nach fail 2: %v", err)
-	}
-	if final.Status != StatusDeadLetter {
-		t.Fatalf("status nach erschoepften versuchen = %q, want %q", final.Status, StatusDeadLetter)
-	}
-	if final.LastError == nil || *final.LastError == "" {
-		t.Fatal("erwartet gesetzten last_error im dead-letter-eintrag")
-	}
-}
-
-// TestRequeueDeadLetter ist Pruefung 3: DLQ-Eintrag manuell wiederholbar.
-func TestRequeueDeadLetter(t *testing.T) {
-	pool := setupTest(t)
-	q := NewQueue(pool, time.Minute)
-	ctx := context.Background()
-
-	id, err := q.Enqueue(ctx, "convert", nil, EnqueueOptions{MaxAttempts: 1})
-	if err != nil {
-		t.Fatalf("enqueue: %v", err)
-	}
-	job, err := q.Dequeue(ctx, "worker-1", nil)
-	if err != nil {
-		t.Fatalf("dequeue: %v", err)
-	}
-	if err := q.Fail(ctx, job.ID, errors.New("konverter abgestuerzt")); err != nil {
-		t.Fatalf("fail: %v", err)
-	}
-	status, _ := q.Status(ctx, id)
-	if status.Status != StatusDeadLetter {
-		t.Fatalf("voraussetzung nicht erfuellt: job sollte in dead_letter stehen, ist %q", status.Status)
-	}
-
-	if err := q.RequeueDeadLetter(ctx, id); err != nil {
-		t.Fatalf("requeuedeadletter: %v", err)
-	}
-	afterRequeue, err := q.Status(ctx, id)
-	if err != nil {
-		t.Fatalf("status nach requeue: %v", err)
-	}
-	if afterRequeue.Status != StatusPending {
-		t.Fatalf("status nach requeue = %q, want %q", afterRequeue.Status, StatusPending)
-	}
-	if afterRequeue.Attempts != 0 {
-		t.Fatalf("attempts nach requeue = %d, want 0", afterRequeue.Attempts)
-	}
-
-	// Requeue eines NICHT in dead_letter stehenden Jobs wird abgewiesen.
-	if err := q.RequeueDeadLetter(ctx, id); !errors.Is(err, ErrNotFound) {
-		t.Fatalf("requeue eines pending-jobs: erwartet ErrNotFound, habe %v", err)
-	}
-}
-
-// TestEnqueue_IdempotencyKeyPreventsDuplicate ist Pruefung 2: Idempotenz
-// bei Doppelzustellung nachgewiesen (auf Einreih-Ebene).
-func TestEnqueue_IdempotencyKeyPreventsDuplicate(t *testing.T) {
-	pool := setupTest(t)
-	q := NewQueue(pool, time.Minute)
-	ctx := context.Background()
-
-	id1, err := q.Enqueue(ctx, "ocr", nil, EnqueueOptions{IdempotencyKey: "ocr:revision-42"})
-	if err != nil {
-		t.Fatalf("enqueue 1: %v", err)
-	}
-	id2, err := q.Enqueue(ctx, "ocr", nil, EnqueueOptions{IdempotencyKey: "ocr:revision-42"})
-	if err != nil {
-		t.Fatalf("enqueue 2 (doppelzustellung): %v", err)
-	}
-	if id1 != id2 {
-		t.Fatalf("doppelte einreihung mit gleichem idempotency-key erzeugte zwei jobs: %q != %q", id1, id2)
-	}
-
-	var count int
-	if err := pool.QueryRow(ctx, `SELECT count(*) FROM processing_jobs WHERE idempotency_key = 'ocr:revision-42'`).Scan(&count); err != nil {
-		t.Fatalf("zeilen zaehlen: %v", err)
-	}
-	if count != 1 {
-		t.Fatalf("erwartet genau 1 zeile fuer den idempotency-key, habe %d", count)
-	}
-}

dms/internal/jobqueue/worker.go

@@ -1,75 +0,0 @@
-package jobqueue
-
-import (
-	"context"
-	"errors"
-	"log"
-	"time"
-)
-
-// Handler verarbeitet einen einzelnen Job. Ein zurueckgegebener Fehler
-// fuehrt zu Queue.Fail (Backoff/DLQ), nil zu Queue.Complete.
-type Handler func(ctx context.Context, job *Job) error
-
-// Worker pollt die Queue in einer In-Prozess-Goroutine und ruft Handler je
-// abgeholtem Job auf — die "In-Prozess-Worker-Goroutinen" aus der
-// Ticket-Vorgabe, kein separater Prozess/Redis noetig.
-type Worker struct {
-	queue        *Queue
-	workerID     string
-	jobTypes     []string
-	pollInterval time.Duration
-	handler      Handler
-}
-
-func NewWorker(queue *Queue, workerID string, jobTypes []string, pollInterval time.Duration, handler Handler) *Worker {
-	return &Worker{queue: queue, workerID: workerID, jobTypes: jobTypes, pollInterval: pollInterval, handler: handler}
-}
-
-// Run blockiert, bis ctx beendet wird, und verarbeitet dabei fortlaufend
-// Jobs. Absturzsicherheit (Pruefung 1) entsteht NICHT durch Run selbst,
-// sondern dadurch, dass ein abgestuerzter Prozess (der Run gar nicht mehr
-// ausfuehrt) seine "processing"-Sperren nie verlaengert — ein ANDERER
-// Worker-Prozess holt den Job nach Ablauf von staleLockAfter erneut ab
-// (siehe Queue.Dequeue).
-func (w *Worker) Run(ctx context.Context) {
-	ticker := time.NewTicker(w.pollInterval)
-	defer ticker.Stop()
-	for {
-		select {
-		case <-ctx.Done():
-			return
-		case <-ticker.C:
-			w.processOne(ctx)
-		}
-	}
-}
-
-// processOne holt und verarbeitet EINEN Job, falls verfuegbar. Oeffentlich
-// über RunOnce fuer Tests, die deterministisch (ohne Polling-Timing) einen
-// einzelnen Verarbeitungsschritt auslösen wollen.
-func (w *Worker) processOne(ctx context.Context) {
-	job, err := w.queue.Dequeue(ctx, w.workerID, w.jobTypes)
-	if err != nil {
-		if !errors.Is(err, ErrNoJobAvailable) {
-			log.Printf("jobqueue: dequeue fehlgeschlagen: %v", err)
-		}
-		return
-	}
-
-	if handlerErr := w.handler(ctx, job); handlerErr != nil {
-		if err := w.queue.Fail(ctx, job.ID, handlerErr); err != nil {
-			log.Printf("jobqueue: fehlschlag fuer job %q nicht erfassbar: %v", job.ID, err)
-		}
-		return
-	}
-	if err := w.queue.Complete(ctx, job.ID); err != nil {
-		log.Printf("jobqueue: abschluss fuer job %q fehlgeschlagen: %v", job.ID, err)
-	}
-}
-
-// RunOnce verarbeitet synchron genau einen Job (falls verfuegbar) und
-// kehrt zurueck — fuer Tests, die ohne Polling-Intervall arbeiten wollen.
-func (w *Worker) RunOnce(ctx context.Context) {
-	w.processOne(ctx)
-}

dms/internal/jobqueue/worker_test.go

@@ -1,115 +0,0 @@
-package jobqueue
-
-import (
-	"context"
-	"errors"
-	"sync/atomic"
-	"testing"
-	"time"
-)
-
-// TestWorker_RunOnce_ProcessesAndCompletesJob ist der End-to-End-Nachweis
-// fuer Akzeptanzkriterium 1 ueber den Worker statt direkt ueber Queue.
-func TestWorker_RunOnce_ProcessesAndCompletesJob(t *testing.T) {
-	pool := setupTest(t)
-	q := NewQueue(pool, time.Minute)
-	ctx := context.Background()
-
-	id, err := q.Enqueue(ctx, "index-document", nil, EnqueueOptions{})
-	if err != nil {
-		t.Fatalf("enqueue: %v", err)
-	}
-
-	var handled int32
-	w := NewWorker(q, "worker-1", nil, time.Millisecond, func(ctx context.Context, job *Job) error {
-		atomic.AddInt32(&handled, 1)
-		return nil
-	})
-	w.RunOnce(ctx)
-
-	if atomic.LoadInt32(&handled) != 1 {
-		t.Fatalf("handler wurde %d mal aufgerufen, want 1", handled)
-	}
-	status, err := q.Status(ctx, id)
-	if err != nil {
-		t.Fatalf("status: %v", err)
-	}
-	if status.Status != StatusSucceeded {
-		t.Fatalf("status = %q, want %q", status.Status, StatusSucceeded)
-	}
-}
-
-// TestWorker_HandlerErrorTriggersFail prueft, dass ein Handler-Fehler zu
-// Queue.Fail fuehrt (Backoff/DLQ-Pfad ueber den Worker statt direkt).
-func TestWorker_HandlerErrorTriggersFail(t *testing.T) {
-	pool := setupTest(t)
-	q := NewQueue(pool, time.Minute)
-	ctx := context.Background()
-
-	id, err := q.Enqueue(ctx, "ocr", nil, EnqueueOptions{MaxAttempts: 5})
-	if err != nil {
-		t.Fatalf("enqueue: %v", err)
-	}
-
-	w := NewWorker(q, "worker-1", nil, time.Millisecond, func(ctx context.Context, job *Job) error {
-		return errors.New("ocr fehlgeschlagen")
-	})
-	w.RunOnce(ctx)
-
-	status, err := q.Status(ctx, id)
-	if err != nil {
-		t.Fatalf("status: %v", err)
-	}
-	if status.Status != StatusPending {
-		t.Fatalf("status nach handler-fehler = %q, want %q (erneut eingeplant)", status.Status, StatusPending)
-	}
-	if status.LastError == nil || *status.LastError != "ocr fehlgeschlagen" {
-		t.Fatalf("last_error = %v, want %q", status.LastError, "ocr fehlgeschlagen")
-	}
-}
-
-// TestDequeue_StaleLockIsRedelivered ist Pruefung 1: Absturz eines Workers
-// fuehrt zu erneuter Zustellung. Simuliert einen Absturz, indem ein Job
-// dequeued (auf "processing" gesperrt), aber NIE completed/failed wird —
-// nach Ablauf von staleLockAfter muss ein ANDERER Worker denselben Job
-// erneut abholen koennen.
-func TestDequeue_StaleLockIsRedelivered(t *testing.T) {
-	pool := setupTest(t)
-	// Sehr kurzes Stale-Fenster, damit der Test nicht lange warten muss.
-	q := NewQueue(pool, 50*time.Millisecond)
-	ctx := context.Background()
-
-	id, err := q.Enqueue(ctx, "convert", nil, EnqueueOptions{})
-	if err != nil {
-		t.Fatalf("enqueue: %v", err)
-	}
-
-	crashed, err := q.Dequeue(ctx, "worker-crashed", nil)
-	if err != nil {
-		t.Fatalf("dequeue (worker-crashed): %v", err)
-	}
-	if crashed.ID != id {
-		t.Fatalf("dequeue lieferte unerwarteten job %q", crashed.ID)
-	}
-	// worker-crashed ruft absichtlich weder Complete noch Fail auf — simuliert
-	// einen Prozessabsturz mitten in der Verarbeitung.
-
-	// Sofortiger erneuter Dequeue-Versuch (Sperre noch frisch) darf den Job
-	// NICHT liefern.
-	if _, err := q.Dequeue(ctx, "worker-2", nil); !errors.Is(err, ErrNoJobAvailable) {
-		t.Fatalf("job wurde trotz frischer sperre erneut ausgeliefert (oder anderer fehler): %v", err)
-	}
-
-	time.Sleep(80 * time.Millisecond) // > staleLockAfter
-
-	redelivered, err := q.Dequeue(ctx, "worker-2", nil)
-	if err != nil {
-		t.Fatalf("dequeue nach ablauf der sperre: %v", err)
-	}
-	if redelivered.ID != id {
-		t.Fatalf("erneut zugestellter job = %q, want %q", redelivered.ID, id)
-	}
-	if err := q.Complete(ctx, redelivered.ID); err != nil {
-		t.Fatalf("complete durch worker-2: %v", err)
-	}
-}

dms/internal/migrate/migrate.go

@@ -1,165 +0,0 @@
-// Package migrate implementiert FDN-02s Migrationsmechanik: versionierte,
-// rueckrollbare SQL-Migrationsdateien (kein ORM), mit einer
-// schema_migrations-Tabelle als Fortschrittsspeicher — dasselbe Prinzip wie
-// NEXARCH Core (internal/migrate), hier eigenstaendig implementiert, da DMS
-// ein eigenes Go-Modul ist und Cores internal/-Pakete nicht importieren
-// kann.
-package migrate
-
-import (
-	"context"
-	"fmt"
-	"os"
-	"path/filepath"
-	"sort"
-	"strings"
-
-	"github.com/jackc/pgx/v5/pgxpool"
-)
-
-// Migration ist eine einzelne versionierte Migrationsdatei.
-type Migration struct {
-	Version string // Dateiname ohne .up.sql/.down.sql, z.B. "0001_documents"
-	UpSQL   string
-	DownSQL string
-}
-
-// Load liest alle *.up.sql/*.down.sql-Paare aus dir, sortiert nach
-// Dateiname (Akzeptanzkriterium: Migrationen sind versioniert).
-func Load(dir string) ([]Migration, error) {
-	entries, err := os.ReadDir(dir)
-	if err != nil {
-		return nil, fmt.Errorf("migrationsverzeichnis %q lesen: %w", dir, err)
-	}
-	var versions []string
-	for _, e := range entries {
-		if e.IsDir() || !strings.HasSuffix(e.Name(), ".up.sql") {
-			continue
-		}
-		versions = append(versions, strings.TrimSuffix(e.Name(), ".up.sql"))
-	}
-	sort.Strings(versions)
-
-	migrations := make([]Migration, 0, len(versions))
-	for _, v := range versions {
-		up, err := os.ReadFile(filepath.Join(dir, v+".up.sql"))
-		if err != nil {
-			return nil, fmt.Errorf("migration %q: up.sql lesen: %w", v, err)
-		}
-		down, err := os.ReadFile(filepath.Join(dir, v+".down.sql"))
-		if err != nil {
-			return nil, fmt.Errorf("migration %q: down.sql lesen (jede Migration braucht ein Rollback): %w", v, err)
-		}
-		migrations = append(migrations, Migration{Version: v, UpSQL: string(up), DownSQL: string(down)})
-	}
-	return migrations, nil
-}
-
-func ensureTrackingTable(ctx context.Context, pool *pgxpool.Pool) error {
-	_, err := pool.Exec(ctx, `
-		CREATE TABLE IF NOT EXISTS schema_migrations (
-			version    TEXT PRIMARY KEY,
-			applied_at TIMESTAMPTZ NOT NULL DEFAULT now()
-		)
-	`)
-	if err != nil {
-		return fmt.Errorf("schema_migrations anlegen: %w", err)
-	}
-	return nil
-}
-
-func appliedVersions(ctx context.Context, pool *pgxpool.Pool) (map[string]bool, error) {
-	rows, err := pool.Query(ctx, `SELECT version FROM schema_migrations`)
-	if err != nil {
-		return nil, fmt.Errorf("angewendete migrationen lesen: %w", err)
-	}
-	defer rows.Close()
-
-	applied := map[string]bool{}
-	for rows.Next() {
-		var v string
-		if err := rows.Scan(&v); err != nil {
-			return nil, fmt.Errorf("migrationsversion lesen: %w", err)
-		}
-		applied[v] = true
-	}
-	return applied, rows.Err()
-}
-
-// Up wendet alle noch nicht angewendeten Migrationen in Reihenfolge an
-// (Akzeptanzkriterium 2: vorwaerts ausfuehrbar) — bereits angewendete
-// werden uebersprungen, damit Up auf einer leeren UND auf einer bestehenden
-// DB funktioniert (Pruefung 1).
-func Up(ctx context.Context, pool *pgxpool.Pool, migrations []Migration) (applied []string, err error) {
-	if err := ensureTrackingTable(ctx, pool); err != nil {
-		return nil, err
-	}
-	already, err := appliedVersions(ctx, pool)
-	if err != nil {
-		return nil, err
-	}
-
-	for _, m := range migrations {
-		if already[m.Version] {
-			continue
-		}
-		tx, err := pool.Begin(ctx)
-		if err != nil {
-			return applied, fmt.Errorf("transaktion fuer %q starten: %w", m.Version, err)
-		}
-		if _, err := tx.Exec(ctx, m.UpSQL); err != nil {
-			_ = tx.Rollback(ctx)
-			return applied, fmt.Errorf("migration %q anwenden: %w", m.Version, err)
-		}
-		if _, err := tx.Exec(ctx, `INSERT INTO schema_migrations (version) VALUES ($1)`, m.Version); err != nil {
-			_ = tx.Rollback(ctx)
-			return applied, fmt.Errorf("migration %q als angewendet markieren: %w", m.Version, err)
-		}
-		if err := tx.Commit(ctx); err != nil {
-			return applied, fmt.Errorf("migration %q committen: %w", m.Version, err)
-		}
-		applied = append(applied, m.Version)
-	}
-	return applied, nil
-}
-
-// DownOne macht die zuletzt angewendete Migration rueckgaengig
-// (Akzeptanzkriterium 2: rueckwaerts ausfuehrbar) und liefert deren Version,
-// oder "" falls keine Migration angewendet war.
-func DownOne(ctx context.Context, pool *pgxpool.Pool, migrations []Migration) (version string, err error) {
-	if err := ensureTrackingTable(ctx, pool); err != nil {
-		return "", err
-	}
-	already, err := appliedVersions(ctx, pool)
-	if err != nil {
-		return "", err
-	}
-
-	var last *Migration
-	for i := len(migrations) - 1; i >= 0; i-- {
-		if already[migrations[i].Version] {
-			last = &migrations[i]
-			break
-		}
-	}
-	if last == nil {
-		return "", nil
-	}
-
-	tx, err := pool.Begin(ctx)
-	if err != nil {
-		return "", fmt.Errorf("transaktion fuer rollback von %q starten: %w", last.Version, err)
-	}
-	if _, err := tx.Exec(ctx, last.DownSQL); err != nil {
-		_ = tx.Rollback(ctx)
-		return "", fmt.Errorf("migration %q zurueckrollen: %w", last.Version, err)
-	}
-	if _, err := tx.Exec(ctx, `DELETE FROM schema_migrations WHERE version = $1`, last.Version); err != nil {
-		_ = tx.Rollback(ctx)
-		return "", fmt.Errorf("migration %q aus schema_migrations entfernen: %w", last.Version, err)
-	}
-	if err := tx.Commit(ctx); err != nil {
-		return "", fmt.Errorf("rollback von %q committen: %w", last.Version, err)
-	}
-	return last.Version, nil
-}

dms/internal/migrate/migrate_test.go

@@ -1,213 +0,0 @@
-package migrate
-
-import (
-	"context"
-	"os"
-	"path/filepath"
-	"testing"
-
-	"github.com/jackc/pgx/v5/pgxpool"
-)
-
-// usersFixtureSQL spiegelt Core IAM-01s reales Schema
-// (migrations/tenant/0001_users.up.sql im NEXARCH-Core-Modul) - DMS ist ein
-// eigenes Go-Modul und kann Cores Migrationsdateien nicht importieren, daher
-// hier als Testfixture kopiert, NICHT als Produktionsmigration (DMS legt
-// users nicht selbst an, siehe "Nicht Bestandteil" in FDN-02).
-const usersFixtureSQL = `
-CREATE EXTENSION IF NOT EXISTS pgcrypto;
-CREATE TABLE IF NOT EXISTS users (
-    id         UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-    email      TEXT NOT NULL UNIQUE,
-    name       TEXT NOT NULL,
-    status     TEXT NOT NULL DEFAULT 'active',
-    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
-    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
-);
-`
-
-func setupTest(t *testing.T) (*pgxpool.Pool, []Migration) {
-	t.Helper()
-	dsn := os.Getenv("TEST_TENANT_DSN")
-	if dsn == "" {
-		t.Skip("TEST_TENANT_DSN nicht gesetzt, Integrationstest uebersprungen")
-	}
-	ctx := context.Background()
-
-	pool, err := pgxpool.New(ctx, dsn)
-	if err != nil {
-		t.Fatalf("pool: %v", err)
-	}
-	t.Cleanup(func() { pool.Close() })
-
-	if _, err := pool.Exec(ctx, usersFixtureSQL); err != nil {
-		t.Fatalf("users-fixture anlegen: %v", err)
-	}
-	if _, err := pool.Exec(ctx, `
-		INSERT INTO users (email, name) VALUES ('seed@example.test', 'Seed-Benutzer')
-		ON CONFLICT (email) DO NOTHING
-	`); err != nil {
-		t.Fatalf("seed-benutzer anlegen: %v", err)
-	}
-
-	migrations, err := Load(migrationsDir(t))
-	if err != nil {
-		t.Fatalf("migrationen laden: %v", err)
-	}
-	return pool, migrations
-}
-
-func migrationsDir(t *testing.T) string {
-	t.Helper()
-	wd, err := os.Getwd()
-	if err != nil {
-		t.Fatalf("getwd: %v", err)
-	}
-	return filepath.Join(wd, "..", "..", "migrations", "tenant")
-}
-
-func tableExists(t *testing.T, ctx context.Context, pool *pgxpool.Pool, name string) bool {
-	t.Helper()
-	var exists bool
-	if err := pool.QueryRow(ctx, `
-		SELECT EXISTS (SELECT 1 FROM information_schema.tables WHERE table_name = $1)
-	`, name).Scan(&exists); err != nil {
-		t.Fatalf("tabellenexistenz von %q pruefen: %v", name, err)
-	}
-	return exists
-}
-
-// TestUp_OnEmptyAndExistingDB ist Pruefung 1: Migration auf leerer DB und
-// auf bestehender DB getestet.
-func TestUp_OnEmptyAndExistingDB(t *testing.T) {
-	pool, migrations := setupTest(t)
-	ctx := context.Background()
-
-	applied, err := Up(ctx, pool, migrations)
-	if err != nil {
-		t.Fatalf("up (leere db): %v", err)
-	}
-	if len(applied) == 0 {
-		t.Fatal("erwartet mindestens 1 angewendete migration auf leerer db")
-	}
-	for _, table := range []string{"folders", "documents", "file_revisions", "tags", "document_tags", "metadata_fields", "document_metadata_values"} {
-		if !tableExists(t, ctx, pool, table) {
-			t.Fatalf("tabelle %q existiert nach Up nicht", table)
-		}
-	}
-
-	// Zweiter Up-Lauf gegen die JETZT BESTEHENDE db - muss ohne Fehler
-	// durchlaufen und darf nichts erneut anwenden (idempotent ueber
-	// schema_migrations).
-	appliedAgain, err := Up(ctx, pool, migrations)
-	if err != nil {
-		t.Fatalf("up (bestehende db, zweiter lauf): %v", err)
-	}
-	if len(appliedAgain) != 0 {
-		t.Fatalf("zweiter Up-Lauf haette 0 neue migrationen anwenden sollen, hat %d", len(appliedAgain))
-	}
-}
-
-// TestDownOne_RestoresPreviousState ist Pruefung 2: Rollback stellt den
-// Vorzustand wieder her.
-func TestDownOne_RestoresPreviousState(t *testing.T) {
-	pool, migrations := setupTest(t)
-	ctx := context.Background()
-
-	if _, err := Up(ctx, pool, migrations); err != nil {
-		t.Fatalf("up: %v", err)
-	}
-	if !tableExists(t, ctx, pool, "documents") {
-		t.Fatal("voraussetzung nicht erfuellt: documents sollte nach Up existieren")
-	}
-
-	// DownOne rollt IMMER nur die zuletzt angewendete Migration zurueck
-	// (dokumentiertes Verhalten) — bei mehreren Migrationen (z.B. FDN-02
-	// documents + FDN-04 processing_jobs) muss man entsprechend oft
-	// aufrufen. Anzahl der Wiederholungen richtet sich NICHT nach dem
-	// Rueckgabewert von Up() (der nur die in DIESEM Aufruf NEU angewendeten
-	// Migrationen zaehlt, siehe Kommentar an Up) — stattdessen wird
-	// wiederholt, bis DownOne "" liefert (schema_migrations leer).
-	for i := 0; i < len(migrations); i++ {
-		version, err := DownOne(ctx, pool, migrations)
-		if err != nil {
-			t.Fatalf("downone (lauf %d): %v", i, err)
-		}
-		if version == "" {
-			break
-		}
-	}
-
-	for _, table := range []string{"folders", "documents", "file_revisions", "tags", "document_tags", "metadata_fields", "document_metadata_values", "processing_jobs"} {
-		if tableExists(t, ctx, pool, table) {
-			t.Fatalf("tabelle %q existiert nach vollstaendigem Rollback noch - Vorzustand nicht wiederhergestellt", table)
-		}
-	}
-
-	// Erneutes DownOne ohne verbleibende angewendete Migration liefert "".
-	versionAfterAll, err := DownOne(ctx, pool, migrations)
-	if err != nil {
-		t.Fatalf("downone (nichts mehr anzuwenden): %v", err)
-	}
-	if versionAfterAll != "" {
-		t.Fatalf("erwartet leeren string bei leerer schema_migrations, habe %q", versionAfterAll)
-	}
-}
-
-// TestForeignKeyConstraints_RejectInvalidReferences ist Pruefung 3:
-// Fremdschluessel-Constraints durch Negativtests belegt.
-func TestForeignKeyConstraints_RejectInvalidReferences(t *testing.T) {
-	pool, migrations := setupTest(t)
-	ctx := context.Background()
-	if _, err := Up(ctx, pool, migrations); err != nil {
-		t.Fatalf("up: %v", err)
-	}
-
-	var userID string
-	if err := pool.QueryRow(ctx, `SELECT id FROM users LIMIT 1`).Scan(&userID); err != nil {
-		t.Fatalf("seed-benutzer lesen: %v", err)
-	}
-
-	t.Run("dokument mit unbekanntem ordner wird abgewiesen", func(t *testing.T) {
-		_, err := pool.Exec(ctx, `
-			INSERT INTO documents (folder_id, title, created_by) VALUES (gen_random_uuid(), 'x', $1)
-		`, userID)
-		if err == nil {
-			t.Fatal("insert mit unbekanntem folder_id haette scheitern muessen")
-		}
-	})
-
-	t.Run("dokument mit unbekanntem ersteller wird abgewiesen", func(t *testing.T) {
-		_, err := pool.Exec(ctx, `
-			INSERT INTO documents (title, created_by) VALUES ('x', gen_random_uuid())
-		`)
-		if err == nil {
-			t.Fatal("insert mit unbekanntem created_by haette scheitern muessen")
-		}
-	})
-
-	t.Run("datei-revision mit unbekanntem dokument wird abgewiesen", func(t *testing.T) {
-		_, err := pool.Exec(ctx, `
-			INSERT INTO file_revisions (document_id, revision_number, storage_key, checksum_sha256, size_bytes, mime_type, created_by)
-			VALUES (gen_random_uuid(), 1, 'k', repeat('0',64), 1, 'text/plain', $1)
-		`, userID)
-		if err == nil {
-			t.Fatal("insert mit unbekanntem document_id haette scheitern muessen")
-		}
-	})
-
-	t.Run("tag-zuordnung mit unbekanntem tag wird abgewiesen", func(t *testing.T) {
-		var docID string
-		if err := pool.QueryRow(ctx, `
-			INSERT INTO documents (title, created_by) VALUES ('fk-test-doc', $1) RETURNING id
-		`, userID).Scan(&docID); err != nil {
-			t.Fatalf("testdokument anlegen: %v", err)
-		}
-		_, err := pool.Exec(ctx, `
-			INSERT INTO document_tags (document_id, tag_id) VALUES ($1, gen_random_uuid())
-		`, docID)
-		if err == nil {
-			t.Fatal("insert mit unbekanntem tag_id haette scheitern muessen")
-		}
-	})
-}

dms/internal/shared/version.go

@@ -1,8 +0,0 @@
-// Package shared enthaelt Code, der von App und Worker gemeinsam genutzt
-// wird (FDN-01) — Datenmodell, Storage-Zugriff etc. kommen in spaeteren
-// Kacheln (FDN-02/FDN-03) hierher, dieses Paket ist bewusst noch schlank.
-package shared
-
-// Version ist die aktuelle DMS-Version, per -ldflags ueberschreibbar
-// (siehe Makefile) — Platzhalter fuer echtes Versionsmanagement.
-var Version = "dev"

dms/internal/storage/driver.go

@@ -1,45 +0,0 @@
-// Package storage implementiert FDN-03: eine einheitliche Objekt-Storage-
-// Abstraktion mit zwei austauschbaren Treibern (lokal fuer Entwicklung,
-// S3-kompatibel fuer Produktion). Verschluesselung at rest ist NICHT
-// Bestandteil dieser Kachel (siehe FDN-09) — dieses Paket legt Bytes
-// unveraendert ab.
-package storage
-
-import (
-	"context"
-	"errors"
-	"io"
-	"time"
-)
-
-// ErrNotFound wird geliefert, wenn ein angefragtes Objekt nicht existiert
-// (Akzeptanzkriterium/Pruefung 3: klarer Fehler statt treiberspezifischer
-// Fehlertypen, die der Aufrufer sonst je Treiber unterschiedlich behandeln
-// muesste).
-var ErrNotFound = errors.New("storage: objekt nicht gefunden")
-
-// Driver ist die EINE Schnittstelle, gegen die der Rest von DMS arbeitet
-// (Akzeptanzkriterium 1). Zwei Implementierungen: LocalDriver (Entwicklung)
-// und S3Driver (Produktion, S3-kompatibel).
-type Driver interface {
-	// Put legt die Bytes aus r unter key ab und liefert die tatsaechlich
-	// geschriebene Groesse in Bytes.
-	Put(ctx context.Context, key string, r io.Reader, size int64, contentType string) (int64, error)
-	// Get liefert die Bytes unter key. Existiert key nicht, liefert Get
-	// ErrNotFound.
-	Get(ctx context.Context, key string) (io.ReadCloser, error)
-	// Delete entfernt das Objekt unter key. Existiert key nicht, liefert
-	// Delete ErrNotFound.
-	Delete(ctx context.Context, key string) error
-	// SignedURL liefert eine zeitlich begrenzte, signierte URL zum Lesen des
-	// Objekts (Akzeptanzkriterium 2: konfigurierbare Gueltigkeit ueber ttl).
-	SignedURL(ctx context.Context, key string, ttl time.Duration) (string, error)
-}
-
-// ObjectKey liefert das Pfadschema fuer ein Dokument/Revision INNERHALB des
-// Mandanten-Buckets (Akzeptanzkriterium 3) — die Bucket-Trennung selbst ist
-// Sache von Core TEN-01, hier geht es nur um den Pfad innerhalb eines
-// bereits mandantenspezifischen Buckets.
-func ObjectKey(documentID, revisionID string) string {
-	return "documents/" + documentID + "/revisions/" + revisionID
-}

dms/internal/storage/localdriver.go

@@ -1,113 +0,0 @@
-package storage
-
-import (
-	"context"
-	"crypto/hmac"
-	"crypto/sha256"
-	"crypto/subtle"
-	"encoding/base64"
-	"errors"
-	"fmt"
-	"io"
-	"os"
-	"path/filepath"
-	"strconv"
-	"strings"
-	"time"
-)
-
-// ErrURLExpired wird von VerifySignedURL geliefert, wenn eine signierte URL
-// nach Ablauf ihrer Gueltigkeit verwendet wird (Pruefung 2).
-var ErrURLExpired = errors.New("storage: signierte url ist abgelaufen")
-
-// ErrInvalidSignature wird geliefert, wenn die Signatur einer URL nicht zum
-// Schluessel passt (manipulierte oder falsche URL).
-var ErrInvalidSignature = errors.New("storage: signatur der url ist ungueltig")
-
-// LocalDriver legt Objekte im lokalen Dateisystem ab — der Entwicklungs-
-// Treiber (Akzeptanzkriterium 1), keine externe Abhaengigkeit noetig.
-type LocalDriver struct {
-	baseDir       string
-	signingSecret []byte
-	publicBaseURL string
-}
-
-// NewLocalDriver erzeugt einen LocalDriver. signingSecret authentifiziert
-// die von SignedURL ausgestellten URLs (HMAC-SHA256, konstant-zeit-
-// verglichen bei der Verifikation — timing-safe wie projektweite Konvention,
-// siehe Core IAM-15).
-func NewLocalDriver(baseDir string, signingSecret []byte, publicBaseURL string) *LocalDriver {
-	return &LocalDriver{baseDir: baseDir, signingSecret: signingSecret, publicBaseURL: publicBaseURL}
-}
-
-func (d *LocalDriver) path(key string) string {
-	return filepath.Join(d.baseDir, filepath.FromSlash(key))
-}
-
-func (d *LocalDriver) Put(ctx context.Context, key string, r io.Reader, size int64, contentType string) (int64, error) {
-	full := d.path(key)
-	if err := os.MkdirAll(filepath.Dir(full), 0o755); err != nil {
-		return 0, fmt.Errorf("storage: verzeichnis anlegen: %w", err)
-	}
-	f, err := os.Create(full)
-	if err != nil {
-		return 0, fmt.Errorf("storage: datei anlegen: %w", err)
-	}
-	defer func() { _ = f.Close() }()
-
-	written, err := io.Copy(f, r)
-	if err != nil {
-		return 0, fmt.Errorf("storage: schreiben: %w", err)
-	}
-	return written, nil
-}
-
-func (d *LocalDriver) Get(ctx context.Context, key string) (io.ReadCloser, error) {
-	f, err := os.Open(d.path(key))
-	if err != nil {
-		if os.IsNotExist(err) {
-			return nil, ErrNotFound
-		}
-		return nil, fmt.Errorf("storage: lesen: %w", err)
-	}
-	return f, nil
-}
-
-func (d *LocalDriver) Delete(ctx context.Context, key string) error {
-	if err := os.Remove(d.path(key)); err != nil {
-		if os.IsNotExist(err) {
-			return ErrNotFound
-		}
-		return fmt.Errorf("storage: loeschen: %w", err)
-	}
-	return nil
-}
-
-func (d *LocalDriver) SignedURL(ctx context.Context, key string, ttl time.Duration) (string, error) {
-	expiry := time.Now().Add(ttl).Unix()
-	sig := d.sign(key, expiry)
-	return fmt.Sprintf("%s/%s?exp=%d&sig=%s", strings.TrimRight(d.publicBaseURL, "/"), key, expiry, sig), nil
-}
-
-func (d *LocalDriver) sign(key string, expiry int64) string {
-	mac := hmac.New(sha256.New, d.signingSecret)
-	mac.Write([]byte(key))
-	mac.Write([]byte(strconv.FormatInt(expiry, 10)))
-	return base64.RawURLEncoding.EncodeToString(mac.Sum(nil))
-}
-
-// VerifySignedURL prueft key/expiry/sig, wie sie z.B. aus den Query-
-// Parametern einer von SignedURL ausgestellten URL stammen (Pruefung 2:
-// abgelaufene URL wird abgewiesen). Die eigentliche HTTP-Auslieferung ist
-// nicht Bestandteil dieser Kachel (siehe DOC-01) — hier wird nur die
-// Signatur-/Ablauflogik bereitgestellt und getestet.
-func (d *LocalDriver) VerifySignedURL(key string, expiry int64, sig string) error {
-	expected := d.sign(key, expiry)
-	if subtle.ConstantTimeCompare([]byte(expected), []byte(sig)) != 1 {
-		return ErrInvalidSignature
-	}
-	if time.Now().Unix() > expiry {
-		return ErrURLExpired
-	}
-	return nil
-}

dms/internal/storage/localdriver_test.go

@@ -1,108 +0,0 @@
-package storage
-
-import (
-	"bytes"
-	"context"
-	"errors"
-	"io"
-	"net/url"
-	"strconv"
-	"testing"
-	"time"
-)
-
-func newTestLocalDriver(t *testing.T) *LocalDriver {
-	t.Helper()
-	return NewLocalDriver(t.TempDir(), []byte("test-signing-secret"), "https://files.example.test")
-}
-
-// TestLocalDriver_RoundTrip ist Pruefung 1 fuer den lokalen Treiber:
-// Upload/Download-Roundtrip.
-func TestLocalDriver_RoundTrip(t *testing.T) {
-	d := newTestLocalDriver(t)
-	ctx := context.Background()
-	key := "documents/doc-1/revisions/rev-1"
-	content := []byte("hallo welt")
-
-	written, err := d.Put(ctx, key, bytes.NewReader(content), int64(len(content)), "text/plain")
-	if err != nil {
-		t.Fatalf("put: %v", err)
-	}
-	if written != int64(len(content)) {
-		t.Fatalf("geschriebene groesse = %d, want %d", written, len(content))
-	}
-
-	rc, err := d.Get(ctx, key)
-	if err != nil {
-		t.Fatalf("get: %v", err)
-	}
-	defer func() { _ = rc.Close() }()
-	got, err := io.ReadAll(rc)
-	if err != nil {
-		t.Fatalf("lesen: %v", err)
-	}
-	if !bytes.Equal(got, content) {
-		t.Fatalf("gelesener inhalt = %q, want %q", got, content)
-	}
-}
-
-// TestLocalDriver_MissingObject ist Pruefung 3: klarer Fehler bei
-// fehlendem Objekt, sowohl fuer Get als auch Delete.
-func TestLocalDriver_MissingObject(t *testing.T) {
-	d := newTestLocalDriver(t)
-	ctx := context.Background()
-
-	if _, err := d.Get(ctx, "nie-angelegt"); !errors.Is(err, ErrNotFound) {
-		t.Fatalf("get eines fehlenden objekts: erwartet ErrNotFound, habe %v", err)
-	}
-	if err := d.Delete(ctx, "nie-angelegt"); !errors.Is(err, ErrNotFound) {
-		t.Fatalf("delete eines fehlenden objekts: erwartet ErrNotFound, habe %v", err)
-	}
-}
-
-// TestLocalDriver_SignedURL_ExpiredIsRejected ist Pruefung 2: eine
-// abgelaufene signierte URL wird abgewiesen.
-func TestLocalDriver_SignedURL_ExpiredIsRejected(t *testing.T) {
-	d := newTestLocalDriver(t)
-	ctx := context.Background()
-	key := "documents/doc-2/revisions/rev-1"
-
-	// Gueltige, noch nicht abgelaufene URL wird akzeptiert.
-	urlValid, err := d.SignedURL(ctx, key, time.Hour)
-	if err != nil {
-		t.Fatalf("signedurl (gueltig): %v", err)
-	}
-	expiry, sig := parseSignedURLQuery(t, urlValid)
-	if err := d.VerifySignedURL(key, expiry, sig); err != nil {
-		t.Fatalf("gueltige url wurde abgewiesen: %v", err)
-	}
-
-	// Bereits abgelaufene URL (negative TTL) wird abgewiesen.
-	urlExpired, err := d.SignedURL(ctx, key, -time.Hour)
-	if err != nil {
-		t.Fatalf("signedurl (abgelaufen): %v", err)
-	}
-	expiredExpiry, expiredSig := parseSignedURLQuery(t, urlExpired)
-	if err := d.VerifySignedURL(key, expiredExpiry, expiredSig); !errors.Is(err, ErrURLExpired) {
-		t.Fatalf("abgelaufene url: erwartet ErrURLExpired, habe %v", err)
-	}
-
-	// Manipulierte Signatur wird abgewiesen.
-	if err := d.VerifySignedURL(key, expiry, "manipuliert"); !errors.Is(err, ErrInvalidSignature) {
-		t.Fatalf("manipulierte signatur: erwartet ErrInvalidSignature, habe %v", err)
-	}
-}
-
-func parseSignedURLQuery(t *testing.T, rawURL string) (expiry int64, sig string) {
-	t.Helper()
-	parsed, err := url.Parse(rawURL)
-	if err != nil {
-		t.Fatalf("signierte url parsen: %v (%s)", err, rawURL)
-	}
-	q := parsed.Query()
-	expInt, err := strconv.ParseInt(q.Get("exp"), 10, 64)
-	if err != nil {
-		t.Fatalf("exp parsen: %v", err)
-	}
-	return expInt, q.Get("sig")
-}

dms/internal/storage/s3driver_test.go

@@ -1,98 +0,0 @@
-package storage
-
-import (
-	"bytes"
-	"context"
-	"errors"
-	"io"
-	"os"
-	"testing"
-	"time"
-)
-
-// requireS3TestEnv liefert die S3-Testkonfiguration oder ueberspringt den
-// Test — dasselbe Muster wie TEST_ADMIN_DSN im Core-Modul: kein S3-
-// kompatibler Speicher in dieser Umgebung verfuegbar/geprueft (siehe
-// FDN-03-Pruefprotokoll), daher hier bewusst als optional markiert statt
-// den Treiber ungetestet zu lassen.
-func requireS3TestEnv(t *testing.T) *S3Driver {
-	t.Helper()
-	bucket := os.Getenv("TEST_S3_BUCKET")
-	if bucket == "" {
-		t.Skip("TEST_S3_BUCKET nicht gesetzt, S3-Integrationstest uebersprungen")
-	}
-	endpoint := os.Getenv("TEST_S3_ENDPOINT")
-	region := os.Getenv("TEST_S3_REGION")
-	if region == "" {
-		region = "us-east-1"
-	}
-	accessKey := os.Getenv("TEST_S3_ACCESS_KEY_ID")
-	secretKey := os.Getenv("TEST_S3_SECRET_ACCESS_KEY")
-
-	d, err := NewS3Driver(context.Background(), bucket, region, endpoint, accessKey, secretKey, true)
-	if err != nil {
-		t.Fatalf("s3-treiber aufbauen: %v", err)
-	}
-	return d
-}
-
-// TestS3Driver_RoundTrip ist Pruefung 1 fuer den S3-Treiber.
-func TestS3Driver_RoundTrip(t *testing.T) {
-	d := requireS3TestEnv(t)
-	ctx := context.Background()
-	key := "fdn03-test/roundtrip"
-	content := []byte("s3 roundtrip inhalt")
-
-	t.Cleanup(func() { _ = d.Delete(ctx, key) })
-
-	if _, err := d.Put(ctx, key, bytes.NewReader(content), int64(len(content)), "text/plain"); err != nil {
-		t.Fatalf("put: %v", err)
-	}
-	rc, err := d.Get(ctx, key)
-	if err != nil {
-		t.Fatalf("get: %v", err)
-	}
-	defer func() { _ = rc.Close() }()
-	got, err := io.ReadAll(rc)
-	if err != nil {
-		t.Fatalf("lesen: %v", err)
-	}
-	if !bytes.Equal(got, content) {
-		t.Fatalf("gelesener inhalt = %q, want %q", got, content)
-	}
-}
-
-// TestS3Driver_MissingObject ist Pruefung 3 fuer den S3-Treiber.
-func TestS3Driver_MissingObject(t *testing.T) {
-	d := requireS3TestEnv(t)
-	ctx := context.Background()
-
-	if _, err := d.Get(ctx, "fdn03-test/nie-angelegt"); !errors.Is(err, ErrNotFound) {
-		t.Fatalf("get eines fehlenden objekts: erwartet ErrNotFound, habe %v", err)
-	}
-	if err := d.Delete(ctx, "fdn03-test/nie-angelegt"); !errors.Is(err, ErrNotFound) {
-		t.Fatalf("delete eines fehlenden objekts: erwartet ErrNotFound, habe %v", err)
-	}
-}
-
-// TestS3Driver_SignedURL ist Pruefung 2 fuer den S3-Treiber: eine
-// presigned URL wird erzeugt und ist innerhalb der Gueltigkeit abrufbar.
-func TestS3Driver_SignedURL(t *testing.T) {
-	d := requireS3TestEnv(t)
-	ctx := context.Background()
-	key := "fdn03-test/signed-url"
-	content := []byte("presigned")
-	t.Cleanup(func() { _ = d.Delete(ctx, key) })
-
-	if _, err := d.Put(ctx, key, bytes.NewReader(content), int64(len(content)), "text/plain"); err != nil {
-		t.Fatalf("put: %v", err)
-	}
-
-	url, err := d.SignedURL(ctx, key, time.Minute)
-	if err != nil {
-		t.Fatalf("signedurl: %v", err)
-	}
-	if url == "" {
-		t.Fatal("erwartet nicht-leere presigned url")
-	}
-}

dms/internal/storage/service.go

@@ -1,59 +0,0 @@
-package storage
-
-import (
-	"context"
-	"fmt"
-	"io"
-	"time"
-)
-
-// Service verbindet einen Driver mit der Nutzungsmeldung an Core
-// (Akzeptanzkriterium 4) — jeder Schreib-/Loeschvorgang ueber Service loest
-// GENAU EINE Meldung mit der tatsaechlich geschriebenen/geloeschten
-// Objektgroesse aus. Repository-/Handler-Code (spaetere Kacheln, z.B.
-// DOC-01) ruft ausschliesslich Service auf, nie einen Driver direkt — das
-// verhindert einen Schreibpfad, der die Nutzungsmeldung vergisst.
-type Service struct {
-	driver     Driver
-	usage      UsageReporter
-	tenantSlug string
-}
-
-func NewService(driver Driver, usage UsageReporter, tenantSlug string) *Service {
-	return &Service{driver: driver, usage: usage, tenantSlug: tenantSlug}
-}
-
-// Put legt das Objekt ab und meldet die geschriebene Groesse als positives
-// Delta (Pruefung 4).
-func (s *Service) Put(ctx context.Context, key string, r io.Reader, size int64, contentType string) (int64, error) {
-	written, err := s.driver.Put(ctx, key, r, size, contentType)
-	if err != nil {
-		return 0, err
-	}
-	if err := s.usage.Report(ctx, s.tenantSlug, UsageMetric, written); err != nil {
-		return written, fmt.Errorf("storage: objekt gespeichert, aber nutzungsmeldung fehlgeschlagen: %w", err)
-	}
-	return written, nil
-}
-
-func (s *Service) Get(ctx context.Context, key string) (io.ReadCloser, error) {
-	return s.driver.Get(ctx, key)
-}
-
-// Delete entfernt das Objekt und meldet dessen Groesse als negatives Delta
-// (Pruefung 4) — dafuer muss der Aufrufer die Groesse kennen (z.B. aus
-// file_revisions.size_bytes, FDN-02), da Delete selbst die Groesse eines
-// bereits geloeschten Objekts nicht mehr ermitteln kann.
-func (s *Service) Delete(ctx context.Context, key string, sizeBytes int64) error {
-	if err := s.driver.Delete(ctx, key); err != nil {
-		return err
-	}
-	if err := s.usage.Report(ctx, s.tenantSlug, UsageMetric, -sizeBytes); err != nil {
-		return fmt.Errorf("storage: objekt geloescht, aber nutzungsmeldung fehlgeschlagen: %w", err)
-	}
-	return nil
-}
-
-func (s *Service) SignedURL(ctx context.Context, key string, ttl time.Duration) (string, error) {
-	return s.driver.SignedURL(ctx, key, ttl)
-}

dms/internal/storage/service_test.go

@@ -1,89 +0,0 @@
-package storage
-
-import (
-	"bytes"
-	"context"
-	"sync"
-	"testing"
-)
-
-// fakeUsageReporter zeichnet jeden Report-Aufruf auf, damit Tests
-// nachweisen koennen, dass Service tatsaechlich meldet (Akzeptanzkriterium
-// 4 / Pruefung 4) — ohne echten HTTP-Aufruf gegen Core.
-type fakeUsageReporter struct {
-	mu     sync.Mutex
-	calls  []reportCall
-	failOn int // wenn >0, schlaegt der reportCall-te Aufruf fehl
-}
-
-type reportCall struct {
-	tenantSlug string
-	metric     string
-	delta      int64
-}
-
-func (f *fakeUsageReporter) Report(ctx context.Context, tenantSlug, metric string, delta int64) error {
-	f.mu.Lock()
-	defer f.mu.Unlock()
-	f.calls = append(f.calls, reportCall{tenantSlug, metric, delta})
-	if f.failOn > 0 && len(f.calls) == f.failOn {
-		return context.DeadlineExceeded
-	}
-	return nil
-}
-
-// TestService_PutReportsPositiveDelta ist Pruefung 4 (Schreibvorgang):
-// Melde-Aufruf an Core wird bei Put ausgeloest, mit korrekter Groesse.
-func TestService_PutReportsPositiveDelta(t *testing.T) {
-	driver := NewLocalDriver(t.TempDir(), []byte("secret"), "https://files.example.test")
-	usage := &fakeUsageReporter{}
-	svc := NewService(driver, usage, "acme")
-
-	content := []byte("zwoelf bytes")
-	if _, err := svc.Put(context.Background(), "documents/d1/revisions/r1", bytes.NewReader(content), int64(len(content)), "text/plain"); err != nil {
-		t.Fatalf("put: %v", err)
-	}
-
-	if len(usage.calls) != 1 {
-		t.Fatalf("erwartet 1 nutzungsmeldung, habe %d", len(usage.calls))
-	}
-	call := usage.calls[0]
-	if call.tenantSlug != "acme" || call.metric != UsageMetric || call.delta != int64(len(content)) {
-		t.Fatalf("unerwarteter meldungsinhalt: %+v", call)
-	}
-}
-
-// TestService_DeleteReportsNegativeDelta ist Pruefung 4 (Loeschvorgang).
-func TestService_DeleteReportsNegativeDelta(t *testing.T) {
-	driver := NewLocalDriver(t.TempDir(), []byte("secret"), "https://files.example.test")
-	usage := &fakeUsageReporter{}
-	svc := NewService(driver, usage, "acme")
-	ctx := context.Background()
-	key := "documents/d2/revisions/r1"
-
-	if _, err := svc.Put(ctx, key, bytes.NewReader([]byte("abc")), 3, "text/plain"); err != nil {
-		t.Fatalf("put: %v", err)
-	}
-	if err := svc.Delete(ctx, key, 3); err != nil {
-		t.Fatalf("delete: %v", err)
-	}
-
-	if len(usage.calls) != 2 {
-		t.Fatalf("erwartet 2 nutzungsmeldungen (put+delete), habe %d", len(usage.calls))
-	}
-	del := usage.calls[1]
-	if del.delta != -3 {
-		t.Fatalf("delete-delta = %d, want -3", del.delta)
-	}
-}
-
-// TestService_GetMissingObjectReturnsClearError ist Pruefung 3 auf
-// Service-Ebene.
-func TestService_GetMissingObjectReturnsClearError(t *testing.T) {
-	driver := NewLocalDriver(t.TempDir(), []byte("secret"), "https://files.example.test")
-	svc := NewService(driver, &fakeUsageReporter{}, "acme")
-
-	if _, err := svc.Get(context.Background(), "nie-angelegt"); err == nil {
-		t.Fatal("get eines fehlenden objekts haette einen fehler liefern muessen")
-	}
-}

dms/internal/storage/usagereport_test.go

@@ -1,62 +0,0 @@
-package storage
-
-import (
-	"context"
-	"encoding/json"
-	"net/http"
-	"net/http/httptest"
-	"testing"
-)
-
-// TestHTTPUsageReporter_SendsCorrectContractToCore ist der Nachweis, dass
-// HTTPUsageReporter exakt den Vertrag von Core internal/resync.Handler.
-// UsageHandler bedient (Service-Credential-Header, JSON-Feldnamen) — echte
-// Vernetzung gegen einen laufenden Core-Prozess ist nicht Teil dieses
-// Tests (internal/resync.Handler ist in Core aktuell in keinem cmd/*/
-// main.go verdrahtet, siehe FDN-03-Pruefprotokoll), daher hier gegen einen
-// httptest-Server geprueft, der denselben Vertrag nachbildet.
-func TestHTTPUsageReporter_SendsCorrectContractToCore(t *testing.T) {
-	var gotClientID, gotClientSecret string
-	var gotBody []usageDeltaDTO
-
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		gotClientID = r.Header.Get("X-Nexarch-Client-Id")
-		gotClientSecret = r.Header.Get("X-Nexarch-Client-Secret")
-		if err := json.NewDecoder(r.Body).Decode(&gotBody); err != nil {
-			t.Errorf("anfrage-koerper dekodieren: %v", err)
-		}
-		w.Header().Set("Content-Type", "application/json")
-		_ = json.NewEncoder(w).Encode(map[string]int{"applied": len(gotBody)})
-	}))
-	defer srv.Close()
-
-	reporter := NewHTTPUsageReporter(srv.URL, "dms-service-client", "dms-service-secret", nil)
-	if err := reporter.Report(context.Background(), "acme", UsageMetric, 4096); err != nil {
-		t.Fatalf("report: %v", err)
-	}
-
-	if gotClientID != "dms-service-client" || gotClientSecret != "dms-service-secret" {
-		t.Fatalf("service-credential-header falsch: id=%q secret=%q", gotClientID, gotClientSecret)
-	}
-	if len(gotBody) != 1 {
-		t.Fatalf("erwartet 1 delta im koerper, habe %d", len(gotBody))
-	}
-	if gotBody[0].TenantSlug != "acme" || gotBody[0].Metric != UsageMetric || gotBody[0].Delta != 4096 {
-		t.Fatalf("unerwarteter delta-inhalt: %+v", gotBody[0])
-	}
-}
-
-// TestHTTPUsageReporter_RejectsNonOKStatus prueft, dass ein von Core
-// abgelehnter Aufruf (z.B. ungueltiges Service-Credential) als Fehler
-// zurueckgegeben wird, statt stillschweigend zu verlieren.
-func TestHTTPUsageReporter_RejectsNonOKStatus(t *testing.T) {
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		http.Error(w, "ungueltiges service-credential", http.StatusUnauthorized)
-	}))
-	defer srv.Close()
-
-	reporter := NewHTTPUsageReporter(srv.URL, "x", "y", nil)
-	if err := reporter.Report(context.Background(), "acme", UsageMetric, 1); err == nil {
-		t.Fatal("erwartet fehler bei abgelehnter nutzungsmeldung, habe nil")
-	}
-}

dms/internal/upload/service.go

@@ -1,157 +0,0 @@
-package upload
-
-import (
-	"bytes"
-	"context"
-	"crypto/sha256"
-	"encoding/hex"
-	"fmt"
-	"io"
-
-	"github.com/jackc/pgx/v5/pgxpool"
-
-	dmscrypto "gitea.perlbach24.de/scripte/nexarch/dms/internal/crypto"
-	"gitea.perlbach24.de/scripte/nexarch/dms/internal/storage"
-)
-
-// Service verbindet Validierung, Staging, Verschlüsselung (FDN-09) und
-// Objekt-Storage (FDN-03) zu der einen Upload-API, gegen die Handler/CLI
-// später aufrufen (Akzeptanzkriterium 3: Dokument+Revision transaktional).
-type Service struct {
-	pool       *pgxpool.Pool
-	sessions   *SessionStore
-	staging    *Staging
-	storageSvc *storage.Service
-	cryptoSvc  *dmscrypto.Service
-	validator  *Validator
-	tenantSlug string
-}
-
-func NewService(pool *pgxpool.Pool, sessions *SessionStore, staging *Staging, storageSvc *storage.Service, cryptoSvc *dmscrypto.Service, validator *Validator, tenantSlug string) *Service {
-	return &Service{
-		pool: pool, sessions: sessions, staging: staging,
-		storageSvc: storageSvc, cryptoSvc: cryptoSvc, validator: validator, tenantSlug: tenantSlug,
-	}
-}
-
-// StartUpload validiert Größe/MIME-Typ (Akzeptanzkriterium 2, VOR jedem
-// entgegengenommenen Byte) und legt eine neue Upload-Sitzung an.
-func (s *Service) StartUpload(ctx context.Context, filename, mimeType string, totalSize int64, folderID *string, createdBy string) (string, error) {
-	if err := s.validator.ValidateMimeType(mimeType); err != nil {
-		return "", err
-	}
-	if err := s.validator.ValidateSize(totalSize); err != nil {
-		return "", err
-	}
-	return s.sessions.Create(ctx, filename, mimeType, totalSize, folderID, createdBy)
-}
-
-// UploadChunk nimmt einen Chunk ab offset entgegen (Akzeptanzkriterium 1:
-// Chunks können nach einem Abbruch ab dem zuletzt bestätigten Offset erneut
-// gesendet werden) und aktualisiert den Fortschritt.
-func (s *Service) UploadChunk(ctx context.Context, sessionID string, offset int64, chunk io.Reader) (int64, error) {
-	newTotal, err := s.staging.WriteChunk(sessionID, offset, chunk)
-	if err != nil {
-		return 0, err
-	}
-	if err := s.sessions.RecordChunk(ctx, sessionID, newTotal); err != nil {
-		return 0, err
-	}
-	return newTotal, nil
-}
-
-// Status liefert den aktuellen Fortschritt — der Client fragt dies nach
-// einem Verbindungsabbruch ab, um zu wissen, ab welchem Offset er
-// fortsetzen muss (Akzeptanzkriterium 1).
-func (s *Service) Status(ctx context.Context, sessionID string) (*Session, error) {
-	return s.sessions.Get(ctx, sessionID)
-}
-
-// Complete wird aufgerufen, sobald alle Bytes empfangen wurden: berechnet
-// SHA-256 auf dem KLARTEXT (Akzeptanzkriterium 4, vor jeder
-// Verschlüsselung — siehe "Bekannte Fehler vermeiden"), verschlüsselt
-// (FDN-09), legt im Objekt-Storage ab (FDN-03) und erzeugt Dokument+
-// Revision TRANSAKTIONAL (Akzeptanzkriterium 3).
-func (s *Service) Complete(ctx context.Context, sessionID string) (documentID, revisionID string, err error) {
-	sess, err := s.sessions.Get(ctx, sessionID)
-	if err != nil {
-		return "", "", err
-	}
-	if sess.BytesReceived < sess.TotalSize {
-		return "", "", fmt.Errorf("upload: sitzung %q unvollstaendig (%d von %d bytes)", sessionID, sess.BytesReceived, sess.TotalSize)
-	}
-
-	f, err := s.staging.OpenForRead(sessionID)
-	if err != nil {
-		return "", "", err
-	}
-	defer func() { _ = f.Close() }()
-
-	// SHA-256 UND Verschluesselung lesen denselben Byte-Strom in EINEM
-	// Durchlauf (io.TeeReader) — die berechnete Pruefsumme bezieht sich
-	// garantiert exakt auf das, was tatsaechlich verschluesselt wurde.
-	hasher := sha256.New()
-	tee := io.TeeReader(f, hasher)
-
-	env, err := s.cryptoSvc.Seal(ctx, s.tenantSlug, tee)
-	if err != nil {
-		return "", "", fmt.Errorf("upload: verschluesseln: %w", err)
-	}
-	checksumHex := hex.EncodeToString(hasher.Sum(nil))
-
-	ciphertext, err := io.ReadAll(env.Ciphertext)
-	if err != nil {
-		return "", "", fmt.Errorf("upload: chiffretext lesen: %w", err)
-	}
-
-	tx, err := s.pool.Begin(ctx)
-	if err != nil {
-		return "", "", fmt.Errorf("upload: transaktion starten: %w", err)
-	}
-	defer func() { _ = tx.Rollback(ctx) }()
-
-	if err := tx.QueryRow(ctx, `
-		INSERT INTO documents (folder_id, title, created_by) VALUES ($1, $2, $3) RETURNING id
-	`, sess.FolderID, sess.Filename, sess.CreatedBy).Scan(&documentID); err != nil {
-		return "", "", fmt.Errorf("upload: dokument anlegen: %w", err)
-	}
-
-	objectKey := storage.ObjectKey(documentID, "pending")
-	if err := tx.QueryRow(ctx, `
-		INSERT INTO file_revisions (document_id, revision_number, storage_key, checksum_sha256, size_bytes, mime_type, created_by, wrapped_dek)
-		VALUES ($1, 1, $2, $3, $4, $5, $6, $7)
-		RETURNING id
-	`, documentID, objectKey, checksumHex, sess.TotalSize, sess.MimeType, sess.CreatedBy, env.WrappedDEK).Scan(&revisionID); err != nil {
-		return "", "", fmt.Errorf("upload: revision anlegen: %w", err)
-	}
-
-	// objectKey haengt vom Pfadschema ab (documents/<id>/revisions/<id>,
-	// FDN-03), die Revision-ID ist aber erst NACH dem INSERT bekannt — der
-	// vorlaeufige Key wird daher mit dem echten aktualisiert, bevor das
-	// Objekt tatsaechlich unter diesem Key im Storage abgelegt wird.
-	finalKey := storage.ObjectKey(documentID, revisionID)
-	if _, err := tx.Exec(ctx, `UPDATE file_revisions SET storage_key = $2 WHERE id = $1`, revisionID, finalKey); err != nil {
-		return "", "", fmt.Errorf("upload: storage-key aktualisieren: %w", err)
-	}
-
-	if _, err := tx.Exec(ctx, `UPDATE documents SET current_revision_id = $2 WHERE id = $1`, documentID, revisionID); err != nil {
-		return "", "", fmt.Errorf("upload: aktuelle revision setzen: %w", err)
-	}
-
-	if _, err := s.storageSvc.Put(ctx, finalKey, bytes.NewReader(ciphertext), int64(len(ciphertext)), "application/octet-stream"); err != nil {
-		return "", "", fmt.Errorf("upload: objekt ablegen: %w", err)
-	}
-
-	if err := tx.Commit(ctx); err != nil {
-		return "", "", fmt.Errorf("upload: transaktion committen: %w", err)
-	}
-
-	if err := s.sessions.MarkCompleted(ctx, sessionID, documentID); err != nil {
-		return "", "", fmt.Errorf("upload: sitzung als abgeschlossen markieren: %w", err)
-	}
-	if err := s.staging.Remove(sessionID); err != nil {
-		return "", "", fmt.Errorf("upload: staging-datei aufraeumen: %w", err)
-	}
-
-	return documentID, revisionID, nil
-}

dms/internal/upload/service_test.go

@@ -1,299 +0,0 @@
-package upload
-
-import (
-	"bytes"
-	"context"
-	"crypto/rand"
-	"crypto/sha256"
-	"encoding/hex"
-	"errors"
-	"fmt"
-	"os"
-	"sync"
-	"testing"
-	"time"
-
-	"github.com/jackc/pgx/v5/pgxpool"
-
-	dmscrypto "gitea.perlbach24.de/scripte/nexarch/dms/internal/crypto"
-	"gitea.perlbach24.de/scripte/nexarch/dms/internal/storage"
-)
-
-// fakeKEKProvider liefert einen fest hinterlegten Tenant-KEK — dieselbe
-// Fixture wie in internal/crypto, hier lokal dupliziert, da Testhilfen
-// nicht paketuebergreifend exportiert sind.
-type fakeKEKProvider struct{ kek []byte }
-
-func (f *fakeKEKProvider) TenantKEK(ctx context.Context, tenantSlug string) ([]byte, error) {
-	return f.kek, nil
-}
-
-func setupServiceTest(t *testing.T) (*Service, *pgxpool.Pool, string) {
-	t.Helper()
-	dsn := os.Getenv("TEST_TENANT_DSN")
-	if dsn == "" {
-		t.Skip("TEST_TENANT_DSN nicht gesetzt, Integrationstest uebersprungen")
-	}
-	ctx := context.Background()
-
-	pool, err := pgxpool.New(ctx, dsn)
-	if err != nil {
-		t.Fatalf("pool: %v", err)
-	}
-	t.Cleanup(func() { pool.Close() })
-
-	if _, err := pool.Exec(ctx, `
-		CREATE EXTENSION IF NOT EXISTS pgcrypto;
-		CREATE TABLE IF NOT EXISTS users (
-			id UUID PRIMARY KEY DEFAULT gen_random_uuid(), email TEXT NOT NULL UNIQUE, name TEXT NOT NULL,
-			status TEXT NOT NULL DEFAULT 'active', created_at TIMESTAMPTZ NOT NULL DEFAULT now(), updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
-		);
-		CREATE TABLE IF NOT EXISTS folders (
-			id UUID PRIMARY KEY DEFAULT gen_random_uuid(), parent_folder_id UUID REFERENCES folders(id) ON DELETE CASCADE,
-			name TEXT NOT NULL, created_by UUID NOT NULL REFERENCES users(id),
-			created_at TIMESTAMPTZ NOT NULL DEFAULT now(), updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
-		);
-		CREATE TABLE IF NOT EXISTS documents (
-			id UUID PRIMARY KEY DEFAULT gen_random_uuid(), folder_id UUID REFERENCES folders(id) ON DELETE SET NULL,
-			title TEXT NOT NULL, current_revision_id UUID, created_by UUID NOT NULL REFERENCES users(id),
-			created_at TIMESTAMPTZ NOT NULL DEFAULT now(), updated_at TIMESTAMPTZ NOT NULL DEFAULT now(), deleted_at TIMESTAMPTZ
-		);
-		CREATE TABLE IF NOT EXISTS file_revisions (
-			id UUID PRIMARY KEY DEFAULT gen_random_uuid(), document_id UUID NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
-			revision_number INT NOT NULL, storage_key TEXT NOT NULL, checksum_sha256 TEXT NOT NULL,
-			size_bytes BIGINT NOT NULL, mime_type TEXT NOT NULL, created_by UUID NOT NULL REFERENCES users(id),
-			created_at TIMESTAMPTZ NOT NULL DEFAULT now(), wrapped_dek BYTEA,
-			UNIQUE (document_id, revision_number)
-		);
-		CREATE TABLE IF NOT EXISTS upload_sessions (
-			id UUID PRIMARY KEY DEFAULT gen_random_uuid(), filename TEXT NOT NULL, mime_type TEXT NOT NULL,
-			total_size BIGINT NOT NULL CHECK (total_size > 0), bytes_received BIGINT NOT NULL DEFAULT 0 CHECK (bytes_received >= 0),
-			folder_id UUID REFERENCES folders(id) ON DELETE SET NULL, created_by UUID NOT NULL REFERENCES users(id),
-			status TEXT NOT NULL DEFAULT 'uploading' CHECK (status IN ('uploading','completed','aborted')),
-			document_id UUID REFERENCES documents(id),
-			created_at TIMESTAMPTZ NOT NULL DEFAULT now(), updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
-		);
-	`); err != nil {
-		t.Fatalf("schema: %v", err)
-	}
-	t.Cleanup(func() {
-		ctx := context.Background()
-		_, _ = pool.Exec(ctx, `TRUNCATE upload_sessions, file_revisions, documents, folders, users CASCADE`)
-	})
-
-	var userID string
-	if err := pool.QueryRow(ctx, `
-		INSERT INTO users (email, name) VALUES ($1, 'Test-Benutzer') RETURNING id
-	`, fmt.Sprintf("upload-test-%d@example.test", time.Now().UnixNano())).Scan(&userID); err != nil {
-		t.Fatalf("testbenutzer anlegen: %v", err)
-	}
-
-	sessions := NewSessionStore(pool)
-	staging := NewStaging(t.TempDir())
-	storageSvc := storage.NewService(storage.NewLocalDriver(t.TempDir(), []byte("secret"), "https://files.example.test"), noopUsageReporter{}, "acme")
-	cryptoSvc := dmscrypto.NewService(&fakeKEKProvider{kek: bytes.Repeat([]byte{0x11}, dmscrypto.KEKSize)})
-	validator := NewValidator(10*1024*1024, []string{"application/pdf", "text/plain"})
-
-	svc := NewService(pool, sessions, staging, storageSvc, cryptoSvc, validator, "acme")
-	return svc, pool, userID
-}
-
-// noopUsageReporter ersetzt den echten HTTPUsageReporter aus FDN-03 fuer
-// diese Tests — Nutzungsmeldung ist bereits in FDN-03 eigenstaendig
-// getestet, hier geht es nur um den Upload-Pfad selbst.
-type noopUsageReporter struct{}
-
-func (noopUsageReporter) Report(ctx context.Context, tenantSlug, metric string, delta int64) error {
-	return nil
-}
-
-// TestUploadChunk_DisallowedMimeTypeRejected ist Akzeptanzkriterium 2.
-func TestUploadChunk_DisallowedMimeTypeRejected(t *testing.T) {
-	svc, _, userID := setupServiceTest(t)
-	ctx := context.Background()
-
-	_, err := svc.StartUpload(ctx, "schadcode.exe", "application/x-msdownload", 100, nil, userID)
-	if !errors.Is(err, ErrDisallowedMimeType) {
-		t.Fatalf("erwartet ErrDisallowedMimeType, habe %v", err)
-	}
-}
-
-// TestUploadChunk_OversizedRejected prueft die Groessenpruefung
-// (Schutz vor Speicherbomben).
-func TestUploadChunk_OversizedRejected(t *testing.T) {
-	svc, _, userID := setupServiceTest(t)
-	ctx := context.Background()
-
-	_, err := svc.StartUpload(ctx, "riesig.pdf", "application/pdf", 100*1024*1024, nil, userID)
-	if !errors.Is(err, ErrFileTooLarge) {
-		t.Fatalf("erwartet ErrFileTooLarge, habe %v", err)
-	}
-}
-
-// TestCompleteUpload_CreatesDocumentAndRevisionTransactionally ist
-// Akzeptanzkriterium 3 UND 4 (Pruefsumme).
-func TestCompleteUpload_CreatesDocumentAndRevisionTransactionally(t *testing.T) {
-	svc, pool, userID := setupServiceTest(t)
-	ctx := context.Background()
-
-	content := []byte("Rechnung 2026-0001 — Testinhalt fuer DOC-01")
-	sum := sha256.Sum256(content)
-	wantChecksum := hex.EncodeToString(sum[:])
-
-	sessionID, err := svc.StartUpload(ctx, "rechnung.pdf", "application/pdf", int64(len(content)), nil, userID)
-	if err != nil {
-		t.Fatalf("startupload: %v", err)
-	}
-	if _, err := svc.UploadChunk(ctx, sessionID, 0, bytes.NewReader(content)); err != nil {
-		t.Fatalf("uploadchunk: %v", err)
-	}
-
-	documentID, revisionID, err := svc.Complete(ctx, sessionID)
-	if err != nil {
-		t.Fatalf("complete: %v", err)
-	}
-	if documentID == "" || revisionID == "" {
-		t.Fatal("erwartet nicht-leere document/revision-ids")
-	}
-
-	var title string
-	var currentRevisionID *string
-	if err := pool.QueryRow(ctx, `SELECT title, current_revision_id FROM documents WHERE id = $1`, documentID).Scan(&title, &currentRevisionID); err != nil {
-		t.Fatalf("dokument lesen: %v", err)
-	}
-	if title != "rechnung.pdf" {
-		t.Fatalf("titel = %q, want %q", title, "rechnung.pdf")
-	}
-	if currentRevisionID == nil || *currentRevisionID != revisionID {
-		t.Fatalf("current_revision_id = %v, want %q", currentRevisionID, revisionID)
-	}
-
-	var checksum string
-	var wrappedDEK []byte
-	if err := pool.QueryRow(ctx, `SELECT checksum_sha256, wrapped_dek FROM file_revisions WHERE id = $1`, revisionID).Scan(&checksum, &wrappedDEK); err != nil {
-		t.Fatalf("revision lesen: %v", err)
-	}
-	if checksum != wantChecksum {
-		t.Fatalf("checksum_sha256 = %q, want %q (sha256 des klartexts)", checksum, wantChecksum)
-	}
-	if len(wrappedDEK) == 0 {
-		t.Fatal("erwartet nicht-leeren wrapped_dek (objekt wurde verschluesselt)")
-	}
-}
-
-// TestUploadChunk_ResumeAfterAbortProducesIdenticalChecksum ist
-// Akzeptanzkriterium 1 / Pruefung 2: Abbruch bei 50% und Fortsetzung ergibt
-// identische Pruefsumme.
-func TestUploadChunk_ResumeAfterAbortProducesIdenticalChecksum(t *testing.T) {
-	svc, _, userID := setupServiceTest(t)
-	ctx := context.Background()
-
-	content := make([]byte, 200*1024) // 200 KiB
-	if _, err := rand.Read(content); err != nil {
-		t.Fatalf("zufallsinhalt erzeugen: %v", err)
-	}
-	sum := sha256.Sum256(content)
-	wantChecksum := hex.EncodeToString(sum[:])
-
-	sessionID, err := svc.StartUpload(ctx, "grosse-datei.pdf", "application/pdf", int64(len(content)), nil, userID)
-	if err != nil {
-		t.Fatalf("startupload: %v", err)
-	}
-
-	half := len(content) / 2
-	if _, err := svc.UploadChunk(ctx, sessionID, 0, bytes.NewReader(content[:half])); err != nil {
-		t.Fatalf("uploadchunk (erste haelfte): %v", err)
-	}
-
-	// Simulierter Verbindungsabbruch: Sitzung abfragen wie ein Client, der
-	// nach dem Abbruch neu verbindet und wissen will, wo er stand.
-	status, err := svc.Status(ctx, sessionID)
-	if err != nil {
-		t.Fatalf("status: %v", err)
-	}
-	if status.BytesReceived != int64(half) {
-		t.Fatalf("bytes_received nach abbruch = %d, want %d", status.BytesReceived, half)
-	}
-
-	// Fortsetzung GENAU ab dem zuletzt bestaetigten Offset.
-	if _, err := svc.UploadChunk(ctx, sessionID, int64(half), bytes.NewReader(content[half:])); err != nil {
-		t.Fatalf("uploadchunk (fortsetzung): %v", err)
-	}
-
-	_, revisionID, err := svc.Complete(ctx, sessionID)
-	if err != nil {
-		t.Fatalf("complete: %v", err)
-	}
-
-	got := checksumOf(t, svc, revisionID)
-	if got != wantChecksum {
-		t.Fatalf("checksum nach fortgesetztem upload = %q, want %q", got, wantChecksum)
-	}
-}
-
-func checksumOf(t *testing.T, svc *Service, revisionID string) string {
-	t.Helper()
-	var checksum string
-	if err := svc.pool.QueryRow(context.Background(), `SELECT checksum_sha256 FROM file_revisions WHERE id = $1`, revisionID).Scan(&checksum); err != nil {
-		t.Fatalf("checksum lesen: %v", err)
-	}
-	return checksum
-}
-
-// TestParallelUploads_NoDataLoss ist Pruefung 3: Parallel-Upload von 20
-// Dateien ohne Datenverlust.
-func TestParallelUploads_NoDataLoss(t *testing.T) {
-	svc, _, userID := setupServiceTest(t)
-	ctx := context.Background()
-	const n = 20
-
-	type result struct {
-		documentID string
-		checksum   string
-	}
-	results := make([]result, n)
-	var wg sync.WaitGroup
-	for i := 0; i < n; i++ {
-		wg.Add(1)
-		go func(idx int) {
-			defer wg.Done()
-			content := []byte(fmt.Sprintf("paralleler inhalt nummer %d, eindeutig genug fuer eigenen hash", idx))
-			sum := sha256.Sum256(content)
-			wantChecksum := hex.EncodeToString(sum[:])
-
-			sessionID, err := svc.StartUpload(ctx, fmt.Sprintf("datei-%d.pdf", idx), "application/pdf", int64(len(content)), nil, userID)
-			if err != nil {
-				t.Errorf("startupload %d: %v", idx, err)
-				return
-			}
-			if _, err := svc.UploadChunk(ctx, sessionID, 0, bytes.NewReader(content)); err != nil {
-				t.Errorf("uploadchunk %d: %v", idx, err)
-				return
-			}
-			docID, revID, err := svc.Complete(ctx, sessionID)
-			if err != nil {
-				t.Errorf("complete %d: %v", idx, err)
-				return
-			}
-			results[idx] = result{documentID: docID, checksum: checksumOf(t, svc, revID)}
-			if results[idx].checksum != wantChecksum {
-				t.Errorf("upload %d: checksum = %q, want %q", idx, results[idx].checksum, wantChecksum)
-			}
-		}(i)
-	}
-	wg.Wait()
-
-	seen := map[string]bool{}
-	for i, r := range results {
-		if r.documentID == "" {
-			t.Fatalf("upload %d lieferte keine document-id (fehlgeschlagen)", i)
-		}
-		if seen[r.documentID] {
-			t.Fatalf("document-id %q doppelt vergeben - datenverlust/kollision", r.documentID)
-		}
-		seen[r.documentID] = true
-	}
-	if len(seen) != n {
-		t.Fatalf("erwartet %d eindeutige dokumente, habe %d", n, len(seen))
-	}
-}

dms/internal/upload/session.go

@@ -1,105 +0,0 @@
-package upload
-
-import (
-	"context"
-	"errors"
-	"fmt"
-
-	"github.com/jackc/pgx/v5"
-	"github.com/jackc/pgx/v5/pgxpool"
-)
-
-// ErrSessionNotFound wird geliefert, wenn eine angefragte Upload-Sitzung
-// nicht existiert.
-var ErrSessionNotFound = errors.New("upload: sitzung nicht gefunden")
-
-// Session ist der Zustand eines laufenden oder abgeschlossenen Uploads
-// (Akzeptanzkriterium 1: Grundlage fuer Fortsetzung nach Abbruch).
-type Session struct {
-	ID            string
-	Filename      string
-	MimeType      string
-	TotalSize     int64
-	BytesReceived int64
-	FolderID      *string
-	CreatedBy     string
-	Status        string
-	DocumentID    *string
-}
-
-const (
-	StatusUploading = "uploading"
-	StatusCompleted = "completed"
-	StatusAborted   = "aborted"
-)
-
-// SessionStore verwaltet upload_sessions.
-type SessionStore struct {
-	pool *pgxpool.Pool
-}
-
-func NewSessionStore(pool *pgxpool.Pool) *SessionStore {
-	return &SessionStore{pool: pool}
-}
-
-func (s *SessionStore) Create(ctx context.Context, filename, mimeType string, totalSize int64, folderID *string, createdBy string) (string, error) {
-	var id string
-	err := s.pool.QueryRow(ctx, `
-		INSERT INTO upload_sessions (filename, mime_type, total_size, folder_id, created_by)
-		VALUES ($1, $2, $3, $4, $5)
-		RETURNING id
-	`, filename, mimeType, totalSize, folderID, createdBy).Scan(&id)
-	if err != nil {
-		return "", fmt.Errorf("upload: sitzung anlegen: %w", err)
-	}
-	return id, nil
-}
-
-func (s *SessionStore) Get(ctx context.Context, sessionID string) (*Session, error) {
-	var sess Session
-	err := s.pool.QueryRow(ctx, `
-		SELECT id, filename, mime_type, total_size, bytes_received, folder_id, created_by, status, document_id
-		FROM upload_sessions WHERE id = $1
-	`, sessionID).Scan(&sess.ID, &sess.Filename, &sess.MimeType, &sess.TotalSize, &sess.BytesReceived,
-		&sess.FolderID, &sess.CreatedBy, &sess.Status, &sess.DocumentID)
-	if err != nil {
-		if errors.Is(err, pgx.ErrNoRows) {
-			return nil, ErrSessionNotFound
-		}
-		return nil, fmt.Errorf("upload: sitzung lesen: %w", err)
-	}
-	return &sess, nil
-}
-
-// RecordChunk aktualisiert bytes_received auf das Maximum aus dem
-// bisherigen und dem neu gemeldeten Wert (Akzeptanzkriterium 1: ein
-// erneut zugestellter/uebersprungener Chunk darf den Fortschritt nie
-// zurueckdrehen — GREATEST statt blindem Ueberschreiben).
-func (s *SessionStore) RecordChunk(ctx context.Context, sessionID string, bytesReceivedNow int64) error {
-	tag, err := s.pool.Exec(ctx, `
-		UPDATE upload_sessions
-		SET bytes_received = GREATEST(bytes_received, $2), updated_at = now()
-		WHERE id = $1 AND status = 'uploading'
-	`, sessionID, bytesReceivedNow)
-	if err != nil {
-		return fmt.Errorf("upload: fortschritt aktualisieren: %w", err)
-	}
-	if tag.RowsAffected() == 0 {
-		return ErrSessionNotFound
-	}
-	return nil
-}
-
-func (s *SessionStore) MarkCompleted(ctx context.Context, sessionID, documentID string) error {
-	tag, err := s.pool.Exec(ctx, `
-		UPDATE upload_sessions SET status = 'completed', document_id = $2, updated_at = now()
-		WHERE id = $1
-	`, sessionID, documentID)
-	if err != nil {
-		return fmt.Errorf("upload: sitzung abschliessen: %w", err)
-	}
-	if tag.RowsAffected() == 0 {
-		return ErrSessionNotFound
-	}
-	return nil
-}

dms/internal/upload/staging.go

@@ -1,68 +0,0 @@
-package upload
-
-import (
-	"fmt"
-	"io"
-	"os"
-	"path/filepath"
-)
-
-// Staging haelt Uploads waehrend der Uebertragung lokal auf der Platte —
-// getrennt von der finalen Objekt-Storage-Ablage (FDN-03), die erst nach
-// vollstaendigem, verifiziertem Empfang beschrieben wird. Chunks koennen in
-// beliebiger Reihenfolge und wiederholt an einem Offset geschrieben werden
-// (Akzeptanzkriterium 1: Fortsetzung nach Abbruch) — os.File.WriteAt ist
-// dafuer das richtige Werkzeug, kein sequenzielles Append.
-type Staging struct {
-	dir string
-}
-
-func NewStaging(dir string) *Staging {
-	return &Staging{dir: dir}
-}
-
-func (s *Staging) path(sessionID string) string {
-	return filepath.Join(s.dir, sessionID+".part")
-}
-
-// WriteChunk schreibt r ab byte-offset offset in die Staging-Datei der
-// Sitzung. Ein bereits vorher (auch teilweise) geschriebener Bereich wird
-// beim erneuten Zustellen desselben Chunks (Client-Retry) einfach identisch
-// ueberschrieben — idempotent, kein Duplikat.
-func (s *Staging) WriteChunk(sessionID string, offset int64, r io.Reader) (int64, error) {
-	if err := os.MkdirAll(s.dir, 0o755); err != nil {
-		return 0, fmt.Errorf("upload: staging-verzeichnis anlegen: %w", err)
-	}
-	f, err := os.OpenFile(s.path(sessionID), os.O_CREATE|os.O_WRONLY, 0o600)
-	if err != nil {
-		return 0, fmt.Errorf("upload: staging-datei oeffnen: %w", err)
-	}
-	defer func() { _ = f.Close() }()
-
-	if _, err := f.Seek(offset, io.SeekStart); err != nil {
-		return 0, fmt.Errorf("upload: zu offset %d springen: %w", offset, err)
-	}
-	written, err := io.Copy(f, r)
-	if err != nil {
-		return 0, fmt.Errorf("upload: chunk schreiben: %w", err)
-	}
-	return offset + written, nil
-}
-
-// OpenForRead oeffnet die vollstaendige Staging-Datei zum Lesen (nach
-// Abschluss des Uploads, fuer Hash-Berechnung + Verschluesselung).
-func (s *Staging) OpenForRead(sessionID string) (*os.File, error) {
-	f, err := os.Open(s.path(sessionID))
-	if err != nil {
-		return nil, fmt.Errorf("upload: staging-datei lesen: %w", err)
-	}
-	return f, nil
-}
-
-// Remove entfernt die Staging-Datei nach erfolgreichem Abschluss oder Abbruch.
-func (s *Staging) Remove(sessionID string) error {
-	if err := os.Remove(s.path(sessionID)); err != nil && !os.IsNotExist(err) {
-		return fmt.Errorf("upload: staging-datei entfernen: %w", err)
-	}
-	return nil
-}

dms/internal/upload/validate.go

@@ -1,59 +0,0 @@
-// Package upload implementiert DOC-01: fortsetzbare Server-seitige
-// Dateiaufnahme mit Größen-/MIME-Validierung und transaktionaler
-// Dokument+Revision-Anlage. Nutzt FDN-03 (Storage) und FDN-09
-// (Verschlüsselung) als bereits fertige Bausteine, dupliziert sie nicht.
-package upload
-
-import (
-	"errors"
-	"fmt"
-)
-
-// ErrFileTooLarge wird geliefert, wenn die angekündigte oder tatsächliche
-// Größe das konfigurierte Limit überschreitet (Schutz vor
-// Speicherbomben — siehe "Bekannte Fehler vermeiden" im Ticket).
-var ErrFileTooLarge = errors.New("upload: datei ueberschreitet das erlaubte groessenlimit")
-
-// ErrDisallowedMimeType wird geliefert, wenn der MIME-Typ nicht auf der
-// Positivliste steht (Akzeptanzkriterium 2).
-var ErrDisallowedMimeType = errors.New("upload: dateityp ist nicht erlaubt")
-
-// Validator prüft Größe und MIME-Typ VOR jedem Byte, das tatsächlich
-// entgegengenommen wird — die Prüfung selbst braucht keinen Datei-Inhalt,
-// nur die vom Client angekündigten Metadaten.
-type Validator struct {
-	maxSizeBytes     int64
-	allowedMimeTypes map[string]bool
-}
-
-// NewValidator erzeugt einen Validator. maxSizeBytes<=0 bedeutet kein
-// Limit (bewusst explizit statt eines "magischen" Default — siehe Ticket-
-// Vorgabe "kein Start ohne Konfiguration" NUR für die Voreinstellung
-// selbst, nicht für sicherheitsrelevante Limits).
-func NewValidator(maxSizeBytes int64, allowedMimeTypes []string) *Validator {
-	allowed := make(map[string]bool, len(allowedMimeTypes))
-	for _, m := range allowedMimeTypes {
-		allowed[m] = true
-	}
-	return &Validator{maxSizeBytes: maxSizeBytes, allowedMimeTypes: allowed}
-}
-
-func (v *Validator) ValidateMimeType(mimeType string) error {
-	if len(v.allowedMimeTypes) == 0 {
-		return nil
-	}
-	if !v.allowedMimeTypes[mimeType] {
-		return fmt.Errorf("%w: %q", ErrDisallowedMimeType, mimeType)
-	}
-	return nil
-}
-
-func (v *Validator) ValidateSize(sizeBytes int64) error {
-	if v.maxSizeBytes <= 0 {
-		return nil
-	}
-	if sizeBytes > v.maxSizeBytes {
-		return fmt.Errorf("%w: %d bytes > limit %d bytes", ErrFileTooLarge, sizeBytes, v.maxSizeBytes)
-	}
-	return nil
-}

dms/migrations/tenant/0001_documents.down.sql

@@ -1,8 +0,0 @@
-DROP TABLE IF EXISTS document_metadata_values;
-DROP TABLE IF EXISTS metadata_fields;
-DROP TABLE IF EXISTS document_tags;
-DROP TABLE IF EXISTS tags;
-ALTER TABLE documents DROP CONSTRAINT IF EXISTS fk_documents_current_revision;
-DROP TABLE IF EXISTS file_revisions;
-DROP TABLE IF EXISTS documents;
-DROP TABLE IF EXISTS folders;

dms/migrations/tenant/0001_documents.up.sql

@@ -1,88 +0,0 @@
--- Kern-Entitaeten des DMS (FDN-02): Dokument, Datei-Revision, Ordner, Tag,
--- Metadatenfeld. Laeuft in der DB EINES Mandanten (Modell C, siehe Core
--- TEN-01) — keine tenant_id-Spalte, die Tenant-Zugehoerigkeit ist implizit
--- durch die Datenbankverbindung gegeben. FK auf users(id) spiegelt das
--- Benutzer-Datenmodell aus Core IAM-01 (migrations/tenant/0001_users.up.sql
--- im NEXARCH-Core-Modul) — Auth/Benutzerverwaltung liegt vollstaendig in
--- Core (siehe "Nicht Bestandteil" in FDN-02), diese Migration dupliziert sie
--- NICHT, sondern setzt sie als bereits vorhanden voraus (users-Tabelle wird
--- durch Cores eigene Migration in derselben physischen Tenant-Datenbank
--- angelegt, bevor DMS-Migrationen laufen).
-CREATE EXTENSION IF NOT EXISTS pgcrypto;
-
-CREATE TABLE folders (
-    id               UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-    parent_folder_id UUID REFERENCES folders(id) ON DELETE CASCADE,
-    name             TEXT NOT NULL,
-    created_by       UUID NOT NULL REFERENCES users(id),
-    created_at       TIMESTAMPTZ NOT NULL DEFAULT now(),
-    updated_at       TIMESTAMPTZ NOT NULL DEFAULT now()
-);
-CREATE INDEX idx_folders_parent_folder_id ON folders(parent_folder_id);
-
-CREATE TABLE documents (
-    id                  UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-    folder_id           UUID REFERENCES folders(id) ON DELETE SET NULL,
-    title               TEXT NOT NULL,
-    -- current_revision_id verweist erst NACH der Anlage von file_revisions
-    -- auf eine Zeile (siehe ALTER TABLE unten) — beim INSERT eines Dokuments
-    -- existiert noch keine Revision, daher NULLable und zirkulaer per
-    -- nachtraeglichem FOREIGN KEY statt Inline-Referenz geloest.
-    current_revision_id UUID,
-    created_by          UUID NOT NULL REFERENCES users(id),
-    created_at          TIMESTAMPTZ NOT NULL DEFAULT now(),
-    updated_at          TIMESTAMPTZ NOT NULL DEFAULT now(),
-    deleted_at          TIMESTAMPTZ
-);
-CREATE INDEX idx_documents_folder_id ON documents(folder_id);
-CREATE INDEX idx_documents_created_by ON documents(created_by);
-
-CREATE TABLE file_revisions (
-    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-    document_id     UUID NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
-    revision_number INT NOT NULL,
-    -- storage_key ist ein Platzhalter fuer die Objekt-Storage-Abstraktion
-    -- (FDN-03, "Nicht Bestandteil" dieser Kachel) — hier nur die Spalte, die
-    -- spaetere Kachel legt fest, was tatsaechlich dahinter liegt.
-    storage_key     TEXT NOT NULL,
-    checksum_sha256 TEXT NOT NULL,
-    size_bytes      BIGINT NOT NULL,
-    mime_type       TEXT NOT NULL,
-    created_by      UUID NOT NULL REFERENCES users(id),
-    created_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
-    UNIQUE (document_id, revision_number)
-);
-CREATE INDEX idx_file_revisions_document_id ON file_revisions(document_id);
-
-ALTER TABLE documents
-    ADD CONSTRAINT fk_documents_current_revision
-    FOREIGN KEY (current_revision_id) REFERENCES file_revisions(id) ON DELETE SET NULL;
-
-CREATE TABLE tags (
-    id         UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-    name       TEXT NOT NULL UNIQUE,
-    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
-);
-
-CREATE TABLE document_tags (
-    document_id UUID NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
-    tag_id      UUID NOT NULL REFERENCES tags(id) ON DELETE CASCADE,
-    PRIMARY KEY (document_id, tag_id)
-);
-CREATE INDEX idx_document_tags_tag_id ON document_tags(tag_id);
-
-CREATE TABLE metadata_fields (
-    id         UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-    field_key  TEXT NOT NULL UNIQUE,
-    label      TEXT NOT NULL,
-    field_type TEXT NOT NULL CHECK (field_type IN ('text', 'number', 'date', 'bool', 'select')),
-    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
-);
-
-CREATE TABLE document_metadata_values (
-    document_id UUID NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
-    field_id    UUID NOT NULL REFERENCES metadata_fields(id) ON DELETE CASCADE,
-    value       TEXT NOT NULL,
-    PRIMARY KEY (document_id, field_id)
-);
-CREATE INDEX idx_document_metadata_values_field_id ON document_metadata_values(field_id);

dms/migrations/tenant/0002_processing_jobs.down.sql

@@ -1 +0,0 @@
-DROP TABLE IF EXISTS processing_jobs;

dms/migrations/tenant/0002_processing_jobs.up.sql

@@ -1,30 +0,0 @@
--- FDN-04: Postgres-Jobqueue fuer asynchrone Verarbeitung (OCR, Konvertierung,
--- Indexierung, Exporte) — kein Redis/AMQP, dasselbe Muster wie das
--- projektweite Postgres-Jobqueue-Konzept (siehe SKALIERUNGSKONZEPT.md).
--- Laeuft in der DB EINES Mandanten (Modell C, siehe Core TEN-01).
-CREATE TABLE processing_jobs (
-    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-    job_type        TEXT NOT NULL,
-    payload         JSONB NOT NULL DEFAULT '{}'::jsonb,
-    -- idempotency_key verhindert doppelte Einreihung DERSELBEN logischen
-    -- Aufgabe (z.B. "ocr:<revision_id>") — NULL erlaubt mehrere Zeilen ohne
-    -- Dedup-Anspruch (Standard-Postgres-Verhalten: NULL ist nie gleich NULL
-    -- im UNIQUE-Index).
-    idempotency_key TEXT UNIQUE,
-    status          TEXT NOT NULL DEFAULT 'pending'
-                    CHECK (status IN ('pending', 'processing', 'succeeded', 'failed', 'dead_letter')),
-    attempts        INT NOT NULL DEFAULT 0,
-    max_attempts    INT NOT NULL DEFAULT 5,
-    available_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
-    locked_at       TIMESTAMPTZ,
-    locked_by       TEXT,
-    last_error      TEXT,
-    created_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
-    updated_at      TIMESTAMPTZ NOT NULL DEFAULT now()
-);
-
--- Deckt genau die Zugriffsmuster von Dequeue (status+available_at) und der
--- Stale-Lock-Wiedervorlage (status+locked_at) ab.
-CREATE INDEX idx_processing_jobs_pending ON processing_jobs (available_at) WHERE status = 'pending';
-CREATE INDEX idx_processing_jobs_processing ON processing_jobs (locked_at) WHERE status = 'processing';
-CREATE INDEX idx_processing_jobs_job_type ON processing_jobs (job_type);

dms/migrations/tenant/0003_upload_sessions.down.sql

@@ -1 +0,0 @@
-DROP TABLE IF EXISTS upload_sessions;

dms/migrations/tenant/0003_upload_sessions.up.sql

@@ -1,18 +0,0 @@
--- DOC-01: Sitzungszustand fuer fortsetzbaren Upload (Akzeptanzkriterium 1).
--- Ein Sitzungseintrag je laufendem Upload, bytes_received wird bei jedem
--- angenommenen Chunk aktualisiert — nach einem Verbindungsabbruch kann der
--- Client anhand von bytes_received genau dort fortsetzen, wo er stand.
-CREATE TABLE upload_sessions (
-    id             UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-    filename       TEXT NOT NULL,
-    mime_type      TEXT NOT NULL,
-    total_size     BIGINT NOT NULL CHECK (total_size > 0),
-    bytes_received BIGINT NOT NULL DEFAULT 0 CHECK (bytes_received >= 0),
-    folder_id      UUID REFERENCES folders(id) ON DELETE SET NULL,
-    created_by     UUID NOT NULL REFERENCES users(id),
-    status         TEXT NOT NULL DEFAULT 'uploading'
-                   CHECK (status IN ('uploading', 'completed', 'aborted')),
-    document_id    UUID REFERENCES documents(id),
-    created_at     TIMESTAMPTZ NOT NULL DEFAULT now(),
-    updated_at     TIMESTAMPTZ NOT NULL DEFAULT now()
-);

dms/migrations/tenant/0004_file_revisions_wrapped_dek.down.sql

@@ -1 +0,0 @@
-ALTER TABLE file_revisions DROP COLUMN IF EXISTS wrapped_dek;

dms/migrations/tenant/0004_file_revisions_wrapped_dek.up.sql

@@ -1,6 +0,0 @@
--- DOC-01: file_revisions bekommt den verpackten Datenverschluesselungs-
--- schluessel (DEK) aus FDN-09s Envelope-Encryption. Nullable, weil ein
--- Datensatz theoretisch auch unverschluesselt vorliegen kann (z.B. der
--- FDN-02-Entwicklungs-Seed) — DOC-01s regulaerer Upload-Pfad setzt ihn
--- jedoch immer.
-ALTER TABLE file_revisions ADD COLUMN wrapped_dek BYTEA;

dms/migrations/tenant/seed/dev_seed.sql

@@ -1,43 +0,0 @@
--- Entwicklungs-Seed (Akzeptanzkriterium 3): legt einen Beispielordner, ein
--- Beispieldokument mit einer Revision, ein Tag und ein Metadatenfeld an.
--- Setzt voraus, dass mindestens ein Benutzer existiert (Core IAM-01 legt
--- users an, DMS tut das nicht selbst - siehe "Nicht Bestandteil" in
--- FDN-02) - schlaegt sonst absichtlich mit einer sprechenden Fehlermeldung
--- fehl statt einen Platzhalter-Benutzer anzulegen, den DMS gar nicht
--- verwalten darf.
-DO $$
-DECLARE
-    seed_user_id UUID;
-    seed_folder_id UUID;
-    seed_document_id UUID;
-BEGIN
-    SELECT id INTO seed_user_id FROM users ORDER BY created_at LIMIT 1;
-    IF seed_user_id IS NULL THEN
-        RAISE EXCEPTION 'dev_seed.sql: keine Zeile in users gefunden - zuerst Core-Seed (IAM-01) ausfuehren';
-    END IF;
-
-    INSERT INTO folders (name, created_by) VALUES ('Beispielordner', seed_user_id)
-        RETURNING id INTO seed_folder_id;
-
-    INSERT INTO documents (folder_id, title, created_by) VALUES (seed_folder_id, 'Beispieldokument', seed_user_id)
-        RETURNING id INTO seed_document_id;
-
-    INSERT INTO file_revisions (document_id, revision_number, storage_key, checksum_sha256, size_bytes, mime_type, created_by)
-        VALUES (seed_document_id, 1, 'dev-seed/beispiel.pdf', repeat('0', 64), 12345, 'application/pdf', seed_user_id);
-
-    UPDATE documents SET current_revision_id = (
-        SELECT id FROM file_revisions WHERE document_id = seed_document_id AND revision_number = 1
-    ) WHERE id = seed_document_id;
-
-    INSERT INTO tags (name) VALUES ('Beispiel-Tag')
-    ON CONFLICT (name) DO NOTHING;
-
-    INSERT INTO document_tags (document_id, tag_id)
-        SELECT seed_document_id, id FROM tags WHERE name = 'Beispiel-Tag';
-
-    INSERT INTO metadata_fields (field_key, label, field_type) VALUES ('rechnungsnummer', 'Rechnungsnummer', 'text')
-    ON CONFLICT (field_key) DO NOTHING;
-
-    INSERT INTO document_metadata_values (document_id, field_id, value)
-        SELECT seed_document_id, id, 'RE-2026-0001' FROM metadata_fields WHERE field_key = 'rechnungsnummer';
-END $$;

dms/scripts/reset-test-env.sh

@@ -1,22 +0,0 @@
-#!/usr/bin/env bash
-# Setzt die DMS-Testumgebung zurueck: droppt die Tenant-Test-Datenbank und
-# legt sie leer neu an. Noetig, weil mehrere Testpakete (internal/jobqueue,
-# internal/migrate, ...) dieselbe physische Test-Datenbank ueber
-# Sitzungsgrenzen hinweg teilen — ohne Reset sammelt sich Zustand
-# (z.B. schema_migrations-Eintraege) an, der Migrations-/Rollback-Tests
-# verfaelscht (dieselbe Fehlerklasse wie in NEXARCH Core, siehe
-# [[project-nexarch-test-infra]]).
-#
-# Aufruf: NEXARCH_DMS_TEST_DB_PASSWORD=... TEST_TENANT_DB=dms_tenant_test ./scripts/reset-test-env.sh
-set -euo pipefail
-
-PASS="${NEXARCH_DMS_TEST_DB_PASSWORD:?Setze NEXARCH_DMS_TEST_DB_PASSWORD vor dem Aufruf}"
-ROLE="${TEST_TENANT_ROLE:-nexarch_dms_test}"
-DB="${TEST_TENANT_DB:-dms_tenant_test}"
-
-export PGPASSWORD="$PASS"
-
-psql -h localhost -U "$ROLE" -d postgres -v ON_ERROR_STOP=1 -c "DROP DATABASE IF EXISTS ${DB};"
-psql -h localhost -U "$ROLE" -d postgres -v ON_ERROR_STOP=1 -c "CREATE DATABASE ${DB};"
-
-echo "Testumgebung zurueckgesetzt: ${DB} leer neu angelegt."

mail/cmd/pflichttestgate/main.go

@@ -0,0 +1,39 @@
+// Command pflichttestgate ist das CI-Gate aus docs/TESTSTRATEGIE-MAIL.md
+// Abschnitt 4. Aufruf: pflichttestgate < geänderte-dateien.txt
+package main
+
+import (
+	"bufio"
+	"fmt"
+	"os"
+
+	"gitea.perlbach24.de/scripte/nexarch/mail/internal/pflichttestgate"
+)
+
+func main() {
+	var changedFiles []string
+	scanner := bufio.NewScanner(os.Stdin)
+	for scanner.Scan() {
+		line := scanner.Text()
+		if line != "" {
+			changedFiles = append(changedFiles, line)
+		}
+	}
+	if err := scanner.Err(); err != nil {
+		fmt.Fprintf(os.Stderr, "pflichttestgate: eingabe konnte nicht gelesen werden: %v\n", err)
+		os.Exit(2)
+	}
+
+	violations := pflichttestgate.CheckDiff(changedFiles)
+	if len(violations) == 0 {
+		fmt.Println("pflichttestgate: bestanden — alle sicherheitskritischen Änderungen haben begleitende Tests.")
+		return
+	}
+
+	fmt.Fprintln(os.Stderr, "pflichttestgate: FEHLGESCHLAGEN — Pflichttest fehlt für:")
+	for _, v := range violations {
+		fmt.Fprintf(os.Stderr, "  - Package %q (Datei %q hat keine begleitende _test.go-Änderung)\n", v.Package, v.ChangedFile)
+	}
+	fmt.Fprintln(os.Stderr, "\nSiehe docs/TESTSTRATEGIE-MAIL.md Abschnitt 4.")
+	os.Exit(1)
+}

mail/docs/ARC-01-PRUEFPROTOKOLL.md

@@ -0,0 +1,54 @@
+# ARC-01 – Prüfprotokoll: Objekt-Speicher-Anbindung für Mails/Anhänge
+
+Voraussetzung ING-04 – bereits Fertig. ARC-01 ist der Startpunkt der
+Foundation-Kette (analog DMS FDN-03), nicht nur eine Ergänzung — es
+entsperrt ARC-02 bis ARC-10 sowie mehrere Ingestion-Tickets.
+
+## Umsetzung
+
+Bewährtes Muster aus DMS FDN-03 (LocalDriver/S3Driver-Abstraktion)
+übernommen — bewusste Neuimplementierung statt Cross-Modul-Import
+(Mail ist eigenständiges Go-Modul, kann DMS' `internal/` nicht
+importieren):
+
+- `mail/internal/storage.Driver` — `Put`/`Get`/`Delete`, zwei
+  Implementierungen (`LocalDriver`, `S3Driver`).
+- `ObjectKey(messageID, partIndex)` — festes, dokumentiertes
+  Pfadschema `messages/<id>/parts/<n>` (Akzeptanzkriterium 1).
+  Lesezugriff hängt NUR von `messageID`+`partIndex` ab, nicht vom
+  ursprünglichen Importpfad (Akzeptanzkriterium 3).
+- **Erweiterung gegenüber FDN-03** — Prüfsummenverifikation AN DIESER
+  SCHICHT (Akzeptanzkriterium 2, von ARC-01 explizit gefordert, anders
+  als FDN-03): `Service.Put` schreibt Inhalt + SHA-256-Sidecar-Objekt,
+  liest SOFORT zurück und verifiziert — ein fehlgeschlagener
+  Rücklese-Vergleich lässt `Put` selbst fehlschlagen, keine unbemerkt
+  fehlerhafte Ablage. `Service.GetVerified` wiederholt die Prüfung bei
+  jedem späteren Lesezugriff.
+- `HTTPUsageReporter` — identisches Muster wie DMS FDN-03, meldet über
+  Core API-11 (`resync-api`, `internal/resync.Handler.UsageHandler`,
+  Service-Credential wie API-02) an LIC-05 (Akzeptanzkriterium 4).
+
+## Prüfungen
+
+| # | Prüfung | Ergebnis |
+|---|---|---|
+| 1 | Test: geschriebenes Objekt liefert beim Lesen byteidentischen Inhalt | **bestanden** – `TestPut_ReadBackIsByteIdentical`: `GetVerified` liefert exakt den geschriebenen Inhalt |
+| 2 | Test: absichtlich beschädigtes Objekt wird bei Prüfsummenvergleich erkannt | **bestanden** – `TestGetVerified_DetectsTamperedObject`: Objekt direkt am Dateisystem manipuliert (umgeht `Service` vollständig), `GetVerified` liefert real `ErrChecksumMismatch` |
+| 3 | Lasttest mit vielen kleinen Objekten bestätigt akzeptable Latenz | **bestanden** – `TestPut_ManySmallObjectsAcceptableLatency`: 500 reale `Put`-Aufrufe (inkl. Schreiben+Sidecar+Rücklese-Verifikation) in 52,9 ms — **105,8 µs/Objekt**, weit unter der 10-ms-Grenze |
+| 4 | Melde-Aufruf an Core LIC-05 bei Schreib- und Löschvorgang nachweislich ausgelöst, mit korrekter Größenangabe | **bestanden** – `TestPut_ReportsUsageOnWriteAndDelete` (Fake-Reporter, exakte Delta-Werte); ZUSÄTZLICH real auf 131 gegen den laufenden `nexarch-resync-api.service` (API-11) bewiesen: echtes Service-Credential provisioniert, `Put`→`GetVerified`→`Delete` komplett durchlaufen, `usage_counters` zeigt reales Delta `+29` dann `-29` (Nettosumme 0 — beide Meldungen real angewendet, nicht nur eine) |
+
+## Build/Test-Ergebnis (192.168.1.131)
+
+```
+go build ./...  -> clean
+go vet ./...    -> clean
+golangci-lint run ./...  -> 0 issues
+go test ./... -p 1  -> alle Mail-Pakete bestanden (storage, mimeparse, example, pflichttestgate)
+```
+
+## Gesamtergebnis
+
+**Bestanden.** Alle vier Akzeptanzkriterien und alle vier
+Pflichtprüfungen real erfüllt, inklusive eines echten End-zu-Ende-Laufs
+gegen den live laufenden Core-API-11-Dienst (nicht nur einen Fake).
+Entsperrt ARC-02–ARC-10 sowie mehrere Ingestion-Tickets.

mail/docs/ARC-02-PRUEFPROTOKOLL.md

@@ -0,0 +1,71 @@
+# ARC-02 – Prüfprotokoll: Verschlüsselung at rest
+
+Voraussetzung ARC-01 (Mail, Fertig), Core API-10 (Fertig) + API-12
+(neu angelegt und fertig — API-10 war nicht als Dienst erreichbar,
+siehe API-12-Prüfprotokoll).
+
+## Umsetzung
+
+Bewährtes Muster aus DMS FDN-09 übernommen (bewusste
+Neuimplementierung, Mail kann DMS nicht importieren):
+
+- `mail/internal/crypto` — `GenerateDEK`/`WrapDEK`/`UnwrapDEK`
+  (AES-256-GCM), `HTTPKEKProvider` (bezieht den Tenant-KEK über Core
+  API-12, `X-Nexarch-Client-Id/Secret`), `Service.Seal`/`Open`
+  (Envelope-Verfahren, KEK wird bei JEDEM Aufruf frisch bezogen, nie
+  zwischengespeichert).
+- `mail/internal/encstorage` — verbindet ARC-01 (`storage.Service`) mit
+  ARC-02 (`crypto.Service`) OHNE eines der beiden Pakete zu ändern
+  (`git diff --stat mail/internal/storage/` bleibt leer): `Put`
+  verschlüsselt VOR dem Schreiben, legt Chiffretext + verpackten DEK
+  als zwei Objekte über `storage.Service` ab (Prüfsumme,
+  Nutzungsmeldung — ARC-01 unverändert mitgenutzt).
+- **Reihenfolge beachtet** (Ticket "Bekannte Fehler vermeiden"):
+  `encstorage.Put` nimmt bereits fertigen Klartext entgegen — die
+  SHA-256-Dublettenerkennung (ARC-03) muss VOM AUFRUFER auf dem
+  Klartext berechnet werden, BEVOR er an `Put` übergeben wird; dieses
+  Paket verschlüsselt sofort und hält den Klartext nicht länger als
+  nötig im Speicher.
+
+## Prüfungen
+
+| # | Prüfung | Ergebnis |
+|---|---|---|
+| 1 | Test: Zugriff auf Rohspeicher ohne Schlüssel liefert keine lesbaren Inhalte | **bestanden** – `TestPut_RawStorageAccessWithoutKeyYieldsNoReadableContent`: Objekt über `encstorage.Put` geschrieben, DANACH die Datei DIREKT am Dateisystem gelesen (umgeht Service/Entschlüsselung vollständig) — Klartext UND erkennbare Fragmente sind real NICHT im Rohspeicher auffindbar |
+| 2 | Test: falscher Mandantenschlüssel verweigert Entschlüsselung | **bestanden** – `TestGetDecrypted_WrongTenantKeyDeniesDecryption`: korrekter Tenant entschlüsselt erfolgreich, ein ANDERER Tenant-Slug (anderer KEK) liefert real `ErrDecryptFailed` (GCM-Auth-Tag-Prüfung schlägt fehl); ZUSÄTZLICH real gegen den laufenden `kek-api` (API-12) bewiesen: nicht-existenter Tenant wird bereits beim KEK-Bezug abgelehnt (404), Entschlüsselung damit strukturell unmöglich |
+| 3 | Performance-Test bestätigt akzeptablen Overhead durch Verschlüsselung | **bestanden** – `TestPut_AcceptableEncryptionOverhead`: 50 Objekte à 64 KiB (realistische Anhanggröße) in 45,5 ms — **910 µs/Objekt** (inkl. AES-256-GCM, Prüfsumme, Sidecar-Schreiben, Rücklese-Verifikation aus ARC-01), weit unter der 50-ms-Grenze |
+
+## Echter End-zu-Ende-Beweis auf 192.168.1.131
+
+Vollständiger Roundtrip gegen den ECHT laufenden `nexarch-kek-api.service`
+(API-12, kein Fake): echtes Modul registriert+provisioniert, echter
+Tenant + Tenant-KEK real angelegt, `encstorage.Put` → `GetDecrypted`
+über HTTP gegen API-12 — Inhalt kommt byteidentisch zurück. Zusätzlich:
+Entschlüsselungsversuch mit nicht-existentem Tenant-Slug real
+abgelehnt (Core liefert 404, kein KEK verfügbar). Testdaten
+anschließend entfernt.
+
+## Build/Test-Ergebnis (192.168.1.131)
+
+```
+go build ./...  -> clean
+go vet ./...    -> clean
+golangci-lint run ./...  -> 0 issues
+go test ./... -p 1  -> alle Mail-Pakete bestanden (encstorage, crypto indirekt getestet, storage, mimeparse, example, pflichttestgate)
+```
+
+**Hinweis (offener Punkt, ehrlich vermerkt):** `mail/internal/crypto`
+selbst hat keine eigenen `_test.go`-Dateien — es wird vollständig
+indirekt über `mail/internal/encstorage`s Tests abgedeckt. Zusätzlich:
+`mail/internal/pflichttestgate`s Pfadmuster (`docs/TESTSTRATEGIE-MAIL.md`)
+erfassen `internal/crypto/`/`internal/encstorage/` NICHT explizit als
+"Compliance-kritisch" (nur `internal/arc/`) — sollte in einem
+Folgeticket nachgezogen werden, da Verschlüsselungscode mindestens so
+kritisch ist wie die dort bereits gelisteten Bereiche.
+
+## Gesamtergebnis
+
+**Bestanden.** Alle drei Akzeptanzkriterien und alle drei
+Pflichtprüfungen real erfüllt, inklusive eines vollständigen
+End-zu-Ende-Laufs gegen den live laufenden Core-API-12-Dienst.
+Entsperrt ARC-08 (Schlüsselrotation).

mail/docs/ARC-03-PRUEFPROTOKOLL.md

@@ -0,0 +1,53 @@
+# ARC-03 – Prüfprotokoll: Dublettenerkennung E-Mail
+
+Voraussetzung ARC-01 (Mail, Fertig).
+
+## Umsetzung
+
+- `mail/internal/dedup/hash.go` — `HashAndBuffer(plaintext io.Reader)`:
+  SHA-256-Inhalts-Hash, gebildet auf dem KLARTEXT (Bekannter Fehler
+  vermeiden: muss VOR mail/internal/crypto passieren, siehe ARC-02 —
+  ein Hash auf dem Chiffretext wäre wegen des zufälligen DEK je Objekt
+  bei jedem Import anders). Liefert zusätzlich einen erneut lesbaren
+  Reader zurück, da der Original-Reader beim Hashen verbraucht wird.
+- `mail/internal/dedup/store.go` — `Store.Register(ctx, contentHash, objectKey)`:
+  Postgres-Tabelle `mail_content_hashes`, Primärschlüssel
+  `(tenant_slug, content_hash)` — `tenant_slug` fest im Store gebunden
+  (`NewStore(pool, tenantSlug)`, gleiches Muster wie
+  `storage.Service`/`encstorage.Service`), nicht nur Konvention.
+  `ON CONFLICT DO NOTHING` + Rücklese entscheidet, ob der gefundene
+  Eintrag der gerade übergebene ist (kein Duplikat) oder ein älterer
+  (Duplikat, Original-`object_key` wird zurückgegeben statt erneut
+  gespeichert — Akzeptanzkriterium 2).
+- Kein Umbau: `mail/internal/storage`/`mail/internal/crypto`/
+  `mail/internal/encstorage` unverändert (`git diff --stat` bleibt für
+  alle drei leer). `dedup` kennt keines der drei Pakete — der Aufrufer
+  (spätere Ingest-Tickets) ruft `HashAndBuffer` VOR `encstorage.Put`
+  auf.
+
+## Prüfungen
+
+| # | Prüfung | Ergebnis |
+|---|---|---|
+| 1 | Test: dieselbe Nachricht aus zwei Quellen wird als Duplikat erkannt | **bestanden** – `TestRegister_SameMessageFromTwoSourcesIsDuplicate`: gleicher Hash, zwei verschiedene `object_key` ("quelle-1/objekt", "quelle-2/objekt") — zweite Registrierung liefert real `isDuplicate=true` und referenziert das Original `quelle-1/objekt` |
+| 2 | Test: zwei Mandanten mit identischem Mailinhalt werden nicht fälschlich verknüpft | **bestanden** – `TestRegister_SameContentTwoTenantsNotLinked`: zwei `Store`-Instanzen mit unterschiedlichem `tenantSlug`, IDENTISCHER Hash — beide Registrierungen liefern real `isDuplicate=false`, keine Verknüpfung über die Mandantengrenze |
+| 3 | Test mit knapp unterschiedlichen Nachrichten bestätigt korrekte Nicht-Erkennung | **bestanden** – `TestHashAndBuffer_SlightlyDifferentContentDifferentHash`: zwei Nachrichten, die sich nur im letzten Zeichen unterscheiden (`.` vs `,`) — real unterschiedlicher SHA-256-Hash |
+
+## Build/Test-Ergebnis (192.168.1.131)
+
+```
+go build ./...  -> clean
+go vet ./...    -> clean
+golangci-lint run ./...  -> 0 issues
+TEST_TENANT_DSN=postgresql://nexarch_test:***@localhost:5432/tenant_acme?sslmode=disable \
+  go test ./... -v -p 1  -> alle Pakete bestanden, inkl. internal/dedup (5 Tests)
+```
+
+Testdaten (`mail_content_hashes`, Zeilen mit `tenant_slug` beginnend
+`mandant-arc03-`) werden von den Tests selbst über `t.Cleanup`
+entfernt.
+
+## Gesamtergebnis
+
+**Bestanden.** Alle drei Akzeptanzkriterien und alle drei
+Pflichtprüfungen real erfüllt. Entsperrt SRC-01, SRC-02, SRC-07.

mail/docs/ARC-08-PRUEFPROTOKOLL.md

@@ -0,0 +1,87 @@
+# ARC-08 – Prüfprotokoll: Verschlüsselungsschlüssel-Rotation
+
+Voraussetzung ARC-02 (Fertig).
+
+## Architektur-Ausgangslage (real geprüft)
+
+Core (API-10, `internal/kek.Store.RotateTenantKEK`, bereits Fertig)
+ersetzt den Tenant-KEK bei Rotation durch einen komplett NEUEN Wert und
+hält KEINE Historie vor — der laufende `kek-api`-Dienst (192.168.1.131,
+Port 8102) exponiert ausschließlich `TenantKEKHandler`, der immer nur den
+AKTUELLEN KEK liefert (real im Quelltext von
+`/root/nexarch-code/internal/kek/handler.go` und `cmd/kek-api/main.go`
+auf 131 verifiziert). Damit Mail nach einer Core-seitigen Rotation
+Altbestand weiterhin lesen kann, MUSS Mail selbst jeden bezogenen
+Tenant-KEK versioniert zwischenspeichern — das ist der Kern dieser
+Kachel.
+
+## Umsetzung
+
+- `mail/internal/crypto/kekversions.go` — `KEKVersionStore`: persistiert
+  jede vom Core bezogene Tenant-KEK-Version lokal, verschlüsselt mit
+  einem eigenen, ausschließlich über Umgebungsvariable bezogenen
+  Wrap-Schlüssel (kein Klartext-KEK in der Datenbank). `RecordIfNew`
+  erkennt Rotation (neuer KEK-Wert ≠ letzter bekannter) und legt nur dann
+  eine neue Version an (Akzeptanzkriterium 1). `Revoke` sperrt gezielt
+  eine einzelne Version (Pflichtprüfung 2).
+- `mail/internal/crypto/service.go` — `Service.WithVersionStore`
+  (optional, Rückwärtskompatibilität: ohne Aufruf verhält sich `Service`
+  exakt wie vor ARC-08). `Seal` zeichnet bei aktivierter Versionierung
+  die verwendete KEK-Version im `Envelope` auf. Neue Methode
+  `OpenAtVersion` entpackt mit der historischen statt der aktuellen
+  Tenant-KEK-Version (Akzeptanzkriterium 3) — `Open` bleibt unverändert
+  für Rückwärtskompatibilität.
+- `mail/internal/encstorage/encstorage.go` — neuer Sidecar
+  `<key>.dek.version` (gleiches Muster wie der bestehende `.dek`-Sidecar
+  aus ARC-02) speichert die KEK-Version je Objekt. `GetDecrypted` nutzt
+  jetzt `OpenAtVersion` statt `Open`; fehlt der Sidecar (vor ARC-08
+  geschriebene Objekte), wird Version 0 angenommen (identisches
+  Verhalten wie vorher).
+- Kein Umbau: `mail/internal/storage`/`mail/internal/dedup`/
+  `mail/internal/indexworker`/`mail/internal/search` unverändert;
+  bestehende ARC-02-Tests (`encstorage_test.go`) unverändert lauffähig
+  ohne Codeänderung an ihnen.
+
+## Prüfungen
+
+| # | Prüfung | Ergebnis |
+|---|---|---|
+| 1 | Test: Rotation des Hauptschlüssels lässt Altbestand weiterhin lesbar | **bestanden** – `TestRotation_OldArchiveStaysReadableAfterMasterKeyRotation`: Objekt vor Rotation versiegelt (Version 1), Tenant-Hauptschlüssel real rotiert (Provider liefert ab dann einen anderen Wert, exakt wie `RotateTenantKEK` es bei Core bewirkt), neues Objekt nach Rotation versiegelt (Version 2), Altbestand über `OpenAtVersion` real weiterhin korrekt entschlüsselt — zusätzlich real bestätigt, dass der naive `Open()` mit dem neuen aktuellen KEK für das alte Objekt fehlschlägt (beweist, dass `OpenAtVersion` tatsächlich etwas leistet) |
+| 2 | Test: kompromittierter alter Schlüssel kann gezielt gesperrt werden | **bestanden** – `TestRotation_CompromisedOldKeyCanBeRevoked`: Version gesperrt, `OpenAtVersion` liefert danach real `ErrKEKVersionRevoked`; `TestKEKVersionStore_RevokeBlocksOnlyThatVersion` bestätigt zusätzlich, dass eine ANDERE Version davon unberührt bleibt |
+| 3 | Dokumentierter Rotationsvorgang wurde einmal vollständig durchgespielt | **bestanden** – siehe Abschnitt "Rotationsvorgang" unten, real durchlaufen als `TestRotation_OldArchiveStaysReadableAfterMasterKeyRotation` |
+
+### Rotationsvorgang (Pflichtprüfung 3, vollständig durchgespielt)
+
+1. Objekt A wird mit Tenant-KEK-Version 1 versiegelt (`Seal`, Envelope
+   trägt `KEKVersion=1`, `KEKVersionStore` legt Version 1 real an).
+2. Core rotiert den Tenant-Hauptschlüssel (in diesem Test durch den
+   `KEKProvider` simuliert, exakt am selben Punkt, an dem `Service` mit
+   dem echten `HTTPKEKProvider`/Core API-12 interagieren würde).
+3. Objekt B wird versiegelt — automatisch mit der NEUEN Version 2, ohne
+   dass Objekt A angefasst wird (Akzeptanzkriterium 2: kein
+   Neuverschlüsseln des Bestands).
+4. Objekt A wird über `OpenAtVersion(..., kekVersion=1, ...)` gelesen —
+   real erfolgreich, Klartext identisch zum Original.
+5. Ein naiver Lesezugriff über `Open()` (aktueller KEK) auf Objekt A
+   schlägt real fehl — zeigt, dass ohne Versionsverfolgung der
+   Altbestand nach Rotation unlesbar geworden wäre.
+
+## Build/Test-Ergebnis (192.168.1.131)
+
+```
+go build ./...  -> clean
+go vet ./...    -> clean
+golangci-lint run ./...  -> 0 issues
+TEST_TENANT_DSN=postgresql://nexarch_test:***@localhost:5432/tenant_acme?sslmode=disable \
+TEST_MANTICORE_URL=http://127.0.0.1:9308 \
+  go test ./... -v -p 1  -> alle Pakete bestanden, inkl. internal/crypto (4 Tests, neu)
+  und internal/encstorage (4 Tests, unverändert weiterhin grün — Rückwärtskompatibilität
+  real bestätigt)
+```
+
+## Gesamtergebnis
+
+**Bestanden.** Alle drei Akzeptanzkriterien und alle drei Pflichtprüfungen
+real erfüllt. Trägt (gemeinsam mit SRC-02, SRC-04, SRC-05, SRC-09) zu
+QA-03 bei — QA-03 bleibt weiterhin blockiert, bis auch SRC-08 und SRC-10
+fertig sind.

mail/docs/IMP-01-PRUEFPROTOKOLL.md

@@ -0,0 +1,63 @@
+# IMP-01 – Prüfprotokoll: IMAP-Postfach-Abruf & Scheduler
+
+Voraussetzung ING-01, ING-05 (beide Fertig).
+
+## Umsetzung
+
+- `mail/internal/imap` (ING-01) minimal erweitert: `Message.UID`,
+  `MailboxStore.FetchByUID` (RFC 3501 §6.4.8, `UID FETCH`), `SELECT`
+  meldet jetzt `UIDVALIDITY` (RFC-Pflichtbestandteil, war zuvor nicht
+  Bestandteil der Antwort). Dabei einen echten Bug im selben Zug
+  gefunden und behoben: `UID FETCH n:*` löste `*` fälschlich gegen die
+  Nachrichten**anzahl** statt die höchste UID auf — mit
+  `maxOpenEndedUID`-Begrenzung (statt eines naiven 2³²-1-Sentinels, der
+  eine milliardenfache Schleife ausgelöst hätte) korrigiert.
+- `mail/internal/imapimport/state.go` — `Store` (Postgres,
+  `mail_import_state`): persistiert `last_uidvalidity`,
+  `last_synced_uid`, `interval_seconds` je Mandant/Postfach
+  (Akzeptanzkriterium 3, übersteht Neustarts, da nie im
+  Prozessspeicher).
+- `mail/internal/imapimport/scheduler.go` — `Scheduler.RunOnce`:
+  UID-Vergleich klassifiziert Nachrichten als neu vs. bestehend
+  (Akzeptanzkriterium 1), Fortschritt wird NACH JEDER einzelnen neuen
+  Nachricht persistiert (nicht erst am Ende), UIDVALIDITY-Änderung löst
+  vollständigen Resync aus (Akzeptanzkriterium 2, bekannten
+  archivmail-Fehler UIDVALIDITY=0 vermieden).
+- `mail/internal/imapimport/client_real.go` — `RealClient`: echtes
+  IMAP4rev1 über TCP (LOGIN/SELECT/UID FETCH/LOGOUT), für den
+  realistischen Testpostfach-Nachweis UND als produktive Anbindung an
+  jeden RFC-3501-konformen Server nutzbar.
+- Kein Umbau: `mail/internal/folderstate` (ING-05) unverändert — die
+  UIDVALIDITY-Erzeugung bei echtem Ordner-Neuaufbau bleibt dort, IMP-01
+  reagiert nur auf eine geänderte UIDVALIDITY, erzeugt selbst keine.
+
+## Prüfungen
+
+| # | Prüfung | Ergebnis |
+|---|---|---|
+| 1 | Test: zwei aufeinanderfolgende Läufe importieren keine Nachricht doppelt | **bestanden** – `TestRunOnce_TwoConsecutiveRunsNoDuplicateImport`: 3 Nachrichten im ersten Lauf real importiert, zweiter Lauf gegen unverändertes Postfach liefert real 0 neue, 3 bestehende |
+| 2 | Test: simulierter Dienst-Neustart mitten im Abgleich führt zu konsistentem Endzustand | **bestanden** – `TestRunOnce_SimulatedRestartMidSyncConsistentEndState`: Handler schlägt real nach 2 von 5 Nachrichten fehl, neuer Scheduler auf demselben persistenten Store verarbeitet real GENAU die verbleibenden 3, keine der ersten 2 erneut, `last_synced_uid` real konsistent bei 5 |
+| 3 | Test gegen Testpostfach mit realistischem Nachrichtenaufkommen | **bestanden** – `TestRunOnce_AgainstRealTestMailboxWithRealisticVolume`: echter End-zu-Ende-IMAP4rev1-Lauf (`RealClient` gegen echten laufenden ING-01-Server) mit 30 Nachrichten — alle 30 real importiert, zweiter Lauf real 0 neue/30 bestehende |
+
+Zusätzlich (Akzeptanzkriterium 3, Intervallkonfiguration):
+`TestSetInterval_ConfigurableAndSurvivesRestart` — konfiguriertes
+Intervall bleibt nach simuliertem Neustart (neue Store-Instanz auf
+demselben Postgres-Zustand) real erhalten.
+
+## Build/Test-Ergebnis (192.168.1.131)
+
+```
+go build ./...  -> clean
+go vet ./...    -> clean
+golangci-lint run ./...  -> 0 issues
+TEST_TENANT_DSN=... go test ./internal/imapimport/... -v -timeout 60s  -> 4/4 bestanden
+TEST_TENANT_DSN=... TEST_MANTICORE_URL=... go test ./... -p 1
+  -> alle 15 Pakete bestanden, keine Regression (inkl. ING-01: 6/6 weiterhin grün
+  nach UID-FETCH-Erweiterung)
+```
+
+## Gesamtergebnis
+
+**Bestanden.** Alle drei Akzeptanzkriterien und alle drei Pflichtprüfungen
+real erfüllt. Entsperrt IMP-02, IMP-03, IMP-04, IMP-05, IMP-07, IMP-08,
+IMP-09, INT-05, UX-01.

mail/docs/IMP-02-PRUEFPROTOKOLL.md

@@ -0,0 +1,48 @@
+# IMP-02 – Prüfprotokoll: Anhangsverarbeitung bei Import
+
+Voraussetzung ING-04, IMP-01 (beide Fertig).
+
+## Umsetzung
+
+- `mail/internal/mimeparse/tolerant.go` — additive Erweiterung von ING-04
+  (Parse/parseMultipart bleiben UNVERÄNDERT): `ParseTolerant` bricht bei
+  einem einzelnen fehlerhaften Teil NICHT die gesamte Nachricht ab
+  (Akzeptanzkriterium 3), sondern verzeichnet ihn in `[]PartError` und
+  verarbeitet die übrigen Teile weiter. Setzt zusätzlich ein
+  Gesamtgrößenbudget über alle Teile durch (`ErrMessageTooLarge`,
+  Akzeptanzkriterium 2 — ergänzt das bereits vorhandene
+  Je-Anhang-Limit aus ING-04 um ein Je-Nachricht-Limit).
+- `mail/internal/attachments/attachments.go` — `Extract`: liefert
+  `Attachment{Filename, Size, DeclaredContentType, VerifiedContentType}`
+  je Anhang (Akzeptanzkriterium 1) — `VerifiedContentType` kommt aus
+  `net/http.DetectContentType` (echtes Sniffing der Bytes), nicht aus der
+  ungeprüft übernommenen Absenderbehauptung. `Options{MaxAttachmentSize,
+  MaxMessageSize}` mit sinnvollen Vorgabewerten (25 MiB je Anhang,
+  100 MiB je Nachricht).
+- Kein Umbau: `mail/internal/mimeparse` Parse/parseMultipart (ING-04)
+  unverändert — bestehende Tests laufen unangetastet weiter.
+
+## Prüfungen
+
+| # | Prüfung | Ergebnis |
+|---|---|---|
+| 1 | Test mit Nachricht, die einen überdimensionierten Anhang enthält, wird korrekt begrenzt | **bestanden** – `TestExtract_OversizedAttachmentIsCorrectlyLimited`: Anhang über dem Limit wird real übersprungen (nicht extrahiert), Nachrichtentext bleibt real unangetastet |
+| 2 | Test mit mehreren Anhängen unterschiedlichen Typs importiert alle korrekt | **bestanden** – `TestExtract_MultipleAttachmentDifferentTypesAllImported`: PDF + PNG in einer Nachricht, beide real extrahiert, PNG-Anhang liefert real den korrekten gesniffeten Content-Type `image/png` (echte Magic-Bytes) |
+| 3 | Test: ein defekter Anhang lässt Text und übrige Anhänge unangetastet | **bestanden** – `TestExtract_BrokenAttachmentLeavesTextAndOthersUntouched`: ungültiges Base64 in einem Anhang, Nachrichtentext UND der zweite, gültige Anhang kommen real unverändert an |
+
+## Build/Test-Ergebnis (192.168.1.131)
+
+```
+go build ./...  -> clean
+go vet ./...    -> clean
+golangci-lint run ./...  -> 0 issues
+go test ./internal/attachments/... -v  -> 3/3 bestanden
+TEST_TENANT_DSN=... TEST_MANTICORE_URL=... go test ./... -p 1
+  -> alle 16 Pakete bestanden, keine Regression (mimeparse: 6/6 weiterhin grün
+  nach additiver ParseTolerant-Erweiterung)
+```
+
+## Gesamtergebnis
+
+**Bestanden.** Alle drei Akzeptanzkriterien und alle drei Pflichtprüfungen
+real erfüllt. Entsperrt IMP-06, trägt (gemeinsam mit IMP-03) zu IMP-09 bei.

mail/docs/IMP-03-PRUEFPROTOKOLL.md

@@ -0,0 +1,51 @@
+# IMP-03 – Prüfprotokoll: E-Mail-Regeln (Zuordnung/Tags/Klassifizierung)
+
+Voraussetzung IMP-01 (Fertig).
+
+## Umsetzung
+
+- `mail/internal/mailrules/store.go` — `Store` (Postgres, `mail_rules`,
+  gleiches Muster wie `dedup`/`folderstate`/`savedsearch`): `Rule` mit
+  Absender-, Betreff-, Postfach- UND Anhangstyp-Muster (reguläre
+  Ausdrücke, Akzeptanzkriterium 1), `Category` (einwertig) und `Tag`
+  (mehrwertig durch mehrere Regeln), `Priority` (niedrigere Zahl = höhere
+  Priorität). Regex-Validierung bereits beim Anlegen (`Create`).
+- `mail/internal/mailrules/engine.go` — `Engine.Evaluate`: wertet alle
+  Regeln in Prioritätsreihenfolge aus (Akzeptanzkriterium 2, dokumentiert
+  im Go-Doc-Kommentar von `Rule.Priority`): "first match wins" für die
+  einwertige `Category`, ALLE zutreffenden Regeln tragen zu den
+  mehrwertigen `Tags` bei. Muster werden beim Erzeugen der `Engine`
+  EINMAL kompiliert (`compiledRule`) — Grundlage für die
+  Performance-Anforderung (Akzeptanzkriterium/Pflichtprüfung 3).
+- Bewusst KEINE Funktion zum rückwirkenden Neuklassifizieren bestehender
+  Nachrichten (Akzeptanzkriterium 3) — dieses Paket persistiert keine
+  Klassifizierungsergebnisse und kennt keinen Reindex-Mechanismus; eine
+  Regeländerung wirkt sich nur auf künftige, explizite `Evaluate`-Aufrufe
+  aus.
+- Kein Umbau: kein bestehendes Paket angefasst — IMP-03 ist vollständig
+  neu und eigenständig.
+
+## Prüfungen
+
+| # | Prüfung | Ergebnis |
+|---|---|---|
+| 1 | Test mit widersprüchlichen Regeln bestätigt dokumentierte Priorisierung | **bestanden** – `TestEvaluate_ConflictingRulesRespectDocumentedPriority`: zwei Regeln matchen dieselbe Nachricht mit widersprüchlichen Kategorien, die höherpriorisierte (Priority 10 vor 200) gewinnt real |
+| 2 | Test: neue Regel ändert keine bereits importierten Altbestände automatisch | **bestanden** – `TestNewEngine_NewRuleDoesNotAffectAlreadyCapturedResult`: ein vor Regelanlage erfasstes Ergebnis bleibt real unverändert, nachdem die neue Regel angelegt wurde; erst eine explizite Neuauswertung zeigt real die neue Kategorie |
+| 3 | Regelset mit 20+ Regeln bleibt performant auswertbar | **bestanden** – `TestEvaluate_TwentyPlusRulesStayPerformant`: 31 reale Regeln, 1000 Auswertungen in 2,64ms gesamt (2,64µs/Auswertung) |
+
+## Build/Test-Ergebnis (192.168.1.131)
+
+```
+go build ./...  -> clean
+go vet ./...    -> clean
+golangci-lint run ./...  -> 0 issues
+TEST_TENANT_DSN=... go test ./internal/mailrules/... -v -timeout 60s  -> 3/3 bestanden
+TEST_TENANT_DSN=... TEST_MANTICORE_URL=... go test ./... -p 1
+  -> alle 17 Pakete bestanden, keine Regression
+```
+
+## Gesamtergebnis
+
+**Bestanden.** Alle drei Akzeptanzkriterien und alle drei Pflichtprüfungen
+real erfüllt. Entsperrt INT-06, trägt (gemeinsam mit IMP-02, bereits
+Fertig) vollständig zu IMP-09 bei — IMP-09 ist jetzt ungeblockt.

mail/docs/IMP-04-PRUEFPROTOKOLL.md

@@ -0,0 +1,58 @@
+# IMP-04 – Prüfprotokoll: Fehlerbehandlung nicht-konformer Server
+
+Voraussetzung IMP-01 (Fertig).
+
+## Umsetzung
+
+- `mail/internal/imapimport/client_real.go` erweitert:
+  - `resolveUIDValidity`: eine gemeldete `UIDVALIDITY=0` (bekannte
+    Abweichung nicht-konformer Server, known-issues-archivmail.md #5)
+    oder eine ganz fehlende UIDVALIDITY-Angabe löst KEINEN Abbruch mehr
+    aus, sondern einen definierten Fallback (Akzeptanzkriterium 1):
+    `fallbackUIDValidity` leitet deterministisch (FNV-1a, gleiche Technik
+    wie `search.DocumentID`) einen von 0 verschiedenen Ersatzwert aus dem
+    Postfachnamen ab — bei wiederholten Läufen gegen denselben
+    nicht-konformen Server bleibt der Fallback STABIL, kein unnötiger
+    Voll-Resync bei jedem einzelnen Lauf.
+  - `parseFetchLines`/`parseSingleFetchLine`: eine einzelne unerwartete
+    oder kaputte `FETCH`-Zeile wird protokolliert und übersprungen, alle
+    übrigen, korrekt lesbaren Nachrichten werden trotzdem geliefert
+    (Akzeptanzkriterium 2) — der gesamte Lauf bricht dafür nicht ab.
+  - `Logger`/`RealClient.WithLogger`: jede erkannte Abweichung läuft über
+    ein protokollierbares, austauschbares Logging-Ziel mit festem,
+    durchsuchbarem Präfix (Akzeptanzkriterium 3: für Support
+    nachvollziehbar) — Standard ist `log.Printf`.
+- Dabei einen echten, durch die neue Logging-Logik selbst eingeführten
+  Bug gefunden und behoben: die getaggte Kommando-Abschlusszeile (z. B.
+  `"C3 OK UID FETCH completed"`) enthält ebenfalls die Zeichenfolge
+  `"FETCH "` und wurde beim ersten Anlauf fälschlich als "unerwartete
+  Serverantwort" geloggt — behoben, indem nur echte Untagged-Zeilen
+  (Präfix `"* "`) überhaupt als FETCH-Zeile in Betracht gezogen werden.
+- Kein Umbau: `mail/internal/imap` (ING-01)/`folderstate` (ING-05)/
+  `imapimport/scheduler.go` (IMP-01) unverändert — IMP-04 erweitert
+  ausschließlich `client_real.go`.
+
+## Prüfungen
+
+| # | Prüfung | Ergebnis |
+|---|---|---|
+| 1 | Test simuliert Server mit UIDVALIDITY=0 und bestätigt greifenden Fallback | **bestanden** – `TestResolveUIDValidity_ZeroTriggersDefinedFallbackNotAbort`: hand-gesteuerter Fake-Server meldet real `UIDVALIDITY=0`, `Sync` schlägt real NICHT fehl, liefert real einen von 0 verschiedenen, deterministischen Fallback-Wert und alle 3 Nachrichten, Fallback-Hinweis real protokolliert |
+| 2 | Test mit unerwarteter/kaputter Serverantwort bestätigt Weiterlauf für übrige Nachrichten | **bestanden** – `TestParseFetchLines_UnexpectedResponseSkippedRestContinue`: 2 bewusst kaputte Zeilen zwischen 2 korrekten real gesendet — `Sync` liefert real trotzdem beide korrekt lesbaren Nachrichten, beide kaputten Zeilen real protokolliert und übersprungen, kein Abbruch |
+| 3 | Regressionstest verhindert Wiederauftreten des UIDVALIDITY-Bugs | **bestanden** – `TestResolveUIDValidity_RegressionGuardAgainstZeroAbort`: direkter, vom Netzwerkpfad unabhängiger Test von `resolveUIDValidity` mit `UIDVALIDITY=0` UND mit gänzlich fehlender Angabe — beide liefern real keinen Fehler und einen Fallback-Wert != 0 |
+
+## Build/Test-Ergebnis (192.168.1.131)
+
+```
+go build ./...  -> clean
+go vet ./...    -> clean
+golangci-lint run ./...  -> 0 issues
+TEST_TENANT_DSN=... go test ./internal/imapimport/... -v -timeout 60s  -> 7/7 bestanden
+TEST_TENANT_DSN=... TEST_MANTICORE_URL=... go test ./... -p 1
+  -> alle 15 Pakete bestanden, keine Regression
+```
+
+## Gesamtergebnis
+
+**Bestanden.** Alle drei Akzeptanzkriterien und alle drei Pflichtprüfungen
+real erfüllt. Entsperrt IMP-08 (gemeinsam mit QA-02, bleibt weiterhin
+blockiert bis dessen übrige Abhängigkeiten fertig sind).

mail/docs/IMP-05-PRUEFPROTOKOLL.md

@@ -0,0 +1,57 @@
+# IMP-05 – Prüfprotokoll: Hot-Folder/Scanner-Anbindung
+
+Voraussetzung IMP-01 (Fertig).
+
+## Umsetzung
+
+- `mail/internal/hotfolder/store.go` — `Store` (Postgres,
+  `mail_hotfolder_processed`, gleiches Muster wie `dedup`/`folderstate`):
+  verzeichnet bereits importierte Dateien je Mandant/Postfach über den
+  SHA-256-Inhalts-Hash — Grundlage für Akzeptanzkriterium 2 (identischer
+  Inhalt wird nicht doppelt importiert, auch unter neuem Dateinamen).
+- `mail/internal/hotfolder/watcher.go` — `Watcher`:
+  - `ScanOnce`: verarbeitet alle Dateien im Eingangsordner, ordnet sie
+    strukturell dem beim Konfigurieren festgelegten Mandanten/Postfach zu
+    (Akzeptanzkriterium 1 — ein Watcher je Mandant/Postfach-Paar).
+  - Bereits verarbeiteter Inhalt wandert unauffällig in den
+    Verarbeitet-Ordner, ohne den `Handler` erneut aufzurufen.
+  - Ein Verarbeitungsfehler (defekte Datei) verschiebt NUR diese eine
+    Datei in den Fehlerordner, der Scan läuft mit den übrigen Dateien
+    weiter (Akzeptanzkriterium 3).
+  - `Watch`: echte `fsnotify`-Anbindung (Technische Grundlage laut
+    Ticket) — initialer `ScanOnce` beim Start, danach Live-Ereignisse.
+- Kein Umbau: kein bestehendes Paket angefasst — IMP-05 ist vollständig
+  neu und eigenständig. `github.com/fsnotify/fsnotify` als neue,
+  minimale externe Abhängigkeit ergänzt (`go get` auf 192.168.1.131,
+  `go.mod`/`go.sum` aktualisiert).
+
+## Prüfungen
+
+| # | Prüfung | Ergebnis |
+|---|---|---|
+| 1 | Test: gleiche Datei zweimal abgelegt wird nur einmal importiert | **bestanden** – `TestScanOnce_SameFileDroppedTwiceImportedOnce`: identischer Inhalt unter zwei verschiedenen Dateinamen abgelegt, zweiter Scan meldet real 0 Importe/1 Duplikat, Handler real nur 1x aufgerufen |
+| 2 | Test: fehlerhafte Datei landet nachvollziehbar im Fehlerordner | **bestanden** – `TestScanOnce_CorruptFileMovedToErrorFolderTraceably`: defekte Datei real im Fehlerordner, real aus dem Eingang entfernt, die GUTE Nachbardatei wurde real trotzdem verarbeitet |
+| 3 | Dauertest über mehrere Scan-Zyklen ohne Ressourcenleck | **bestanden** – `TestScanOnce_ManyCyclesWithoutResourceLeak`: 50 reale Scan-Zyklen, Goroutine-Anzahl real stabil (Toleranz eingehalten), Verarbeitet-Ordner real konsistent |
+
+Zusätzlich (benannte Technik `fsnotify` real geprüft):
+`TestWatch_RealFsnotifyEventTriggersImport` — eine neu abgelegte Datei
+wird real über ein echtes Dateisystem-Ereignis erkannt und importiert,
+ohne manuellen `ScanOnce`-Aufruf.
+
+## Build/Test-Ergebnis (192.168.1.131)
+
+```
+go build ./...  -> clean
+go vet ./...    -> clean
+golangci-lint run ./...  -> 0 issues
+TEST_TENANT_DSN=... go test ./internal/hotfolder/... -v -timeout 60s  -> 4/4 bestanden
+TEST_TENANT_DSN=... TEST_MANTICORE_URL=... go test ./... -p 1
+  -> alle 20 Pakete bestanden, keine Regression
+```
+
+## Gesamtergebnis
+
+**Bestanden.** Alle drei Akzeptanzkriterien und alle drei Pflichtprüfungen
+real erfüllt. Trägt zu QA-02 bei — QA-02 bleibt weiterhin blockiert, bis
+dessen übrige Abhängigkeiten (ING-07, ING-08, ING-10, IMP-06, IMP-07)
+fertig sind.

mail/docs/IMP-08-PRUEFPROTOKOLL.md

@@ -0,0 +1,73 @@
+# IMP-08 – Prüfprotokoll: Fehler-Benachrichtigung bei Postfach-Sync-Ausfall
+
+Voraussetzung IMP-01, IMP-04 (beide Fertig), Core CFG-02 (Fertig,
+Benachrichtigungs-Dispatcher).
+
+## Architektur-Hinweis
+
+Core CFG-02 (`internal/notify.Dispatcher.Enqueue`) ist bislang nur als
+Go-interne Schnittstelle im Core-Modul realisiert — kein dokumentiertes
+HTTP-Interface für modulübergreifende Aufrufe war im Rahmen dieser
+Kachel auffindbar (kein `cmd/notify-api`-Quelltext im Repo, ein
+gleichnamiger, laufender Systemdienst auf 192.168.1.131 existiert zwar,
+sein Vertrag war ohne Quelltext nicht zuverlässig ermittelbar). Statt
+gegen einen unbekannten, möglicherweise falschen Vertrag zu raten,
+implementiert `HTTPNotificationDispatcher` einen selbst dokumentierten,
+in sich konsistenten HTTP-Vertrag (JSON `{channel, recipient, payload}`,
+Service-Credential-Header wie `mail/internal/crypto.HTTPKEKProvider`) und
+wird gegen einen echten, im Test aufgebauten HTTP-Server geprüft (gleiche
+Konvention wie `mail/internal/imapimport`s `RealClient`-Tests gegen einen
+hand-gesteuerten Server). Ein reales Core-`notify-api` mit exakt diesem
+Vertrag zu verdrahten ist Sache eines eigenen, Core-seitigen Tickets,
+nicht Bestandteil von IMP-08.
+
+## Umsetzung
+
+- `mail/internal/syncalert/dispatcher.go` — `NotificationDispatcher`
+  (schmale Schnittstelle zu CFG-02) + `HTTPNotificationDispatcher` (echte
+  HTTP-Anbindung, Service-Credential-Header).
+- `mail/internal/syncalert/monitor.go` — `Monitor` (Postgres,
+  `mail_sync_alert_state`, gleiches Muster wie `dedup`/`folderstate`):
+  - `RecordFailure`: erhöht `consecutive_failures`; löst GENAU EINMAL
+    eine Benachrichtigung aus, wenn die Schwelle erstmalig erreicht wird
+    (Akzeptanzkriterium 1) — danach markiert `alerted=true`, weitere
+    Fehlschläge lösen nichts mehr aus, solange nicht zurückgesetzt.
+  - Payload enthält `mailbox`, `reason`, `last_successful_sync`
+    (Akzeptanzkriterium 2).
+  - `RecordSuccess`: setzt `consecutive_failures=0`, `alerted=false`
+    (Akzeptanzkriterium 3).
+- Kein Umbau: `mail/internal/imapimport` (IMP-01/IMP-04) unverändert —
+  `syncalert` ist eigenständig, ein künftiger Aufrufer (Scheduler-
+  Integration) verdrahtet `RecordFailure`/`RecordSuccess` um
+  `Scheduler.RunOnce`, nicht Bestandteil dieser Kachel.
+
+## Prüfungen
+
+| # | Prüfung | Ergebnis |
+|---|---|---|
+| 1 | Test: N aufeinanderfolgende Fehlschläge lösen genau eine Benachrichtigung aus, keine Spam-Flut | **bestanden** – `TestRecordFailure_NConsecutiveFailuresTriggerExactlyOneNotification`: Schwelle 3, erste 2 Fehlschläge real 0 Benachrichtigungen, dritter real genau 1, 5 weitere Fehlschläge danach real weiterhin genau 1 |
+| 2 | Test: erfolgreicher Lauf nach Ausfall beendet den Alarmzustand nachvollziehbar | **bestanden** – `TestRecordSuccess_EndsAlertStateVerifiably`: nach Reset beginnt der Zähler real wieder bei 0 — 2 weitere Fehlschläge lösen real noch nichts aus, erst der erneute Schwellenwert real eine zweite Benachrichtigung |
+| 3 | Test mit mehreren betroffenen Postfächern gleichzeitig bleibt übersichtlich | **bestanden** – `TestRecordFailure_MultipleAffectedMailboxesStayIsolated`: 3 Postfächer real parallel ausgefallen, real genau 3 Benachrichtigungen (eine je Postfach), keine Vermischung |
+
+Zusätzlich (Akzeptanzkriterium 2, real geprüft): `TestRecordFailure_NotificationContainsRequiredFields`
+und `TestHTTPNotificationDispatcher_SendsCorrectRequestFormat` (echter
+HTTP-Wire-Test: Service-Credential-Header und JSON-Struktur real
+bestätigt).
+
+## Build/Test-Ergebnis (192.168.1.131)
+
+```
+go build ./...  -> clean
+go vet ./...    -> clean
+golangci-lint run ./...  -> 0 issues
+TEST_TENANT_DSN=... go test ./internal/syncalert/... -v -timeout 60s  -> 6/6 bestanden
+TEST_TENANT_DSN=... TEST_MANTICORE_URL=... go test ./... -p 1
+  -> alle 18 Pakete bestanden, keine Regression
+```
+
+## Gesamtergebnis
+
+**Bestanden.** Alle drei Akzeptanzkriterien und alle drei Pflichtprüfungen
+real erfüllt. Trägt zu QA-02 bei (dependsOn: ING-10, IMP-09, IMP-04,
+IMP-05, IMP-06, IMP-07, IMP-08, ING-07, ING-08) — QA-02 bleibt weiterhin
+blockiert, bis dessen übrige Abhängigkeiten fertig sind.

mail/docs/IMP-09-PRUEFPROTOKOLL.md

@@ -0,0 +1,61 @@
+# IMP-09 – Prüfprotokoll: Import-Testsuite
+
+Voraussetzung IMP-01, IMP-02, IMP-03 (alle Fertig).
+
+## Umsetzung
+
+- `mail/internal/imapimport/tenant_scoping_test.go` +
+  `mail/internal/mailrules/tenant_scoping_test.go` — echte Lücke
+  geschlossen: vor IMP-09 bewies KEIN Test explizit, dass zwei Mandanten
+  mit identischem Postfachnamen (Scheduler) bzw. bei fehlender eigener
+  Regel (Regelwerk) sich nicht gegenseitig beeinflussen
+  (Akzeptanzkriterium 2).
+- `mail/internal/importtestgate/gate.go` — echtes, ausführbares Gate
+  (spiegelt `qagate`/QA-03): `RunTestSuites` führt `go test -cover` real
+  über die drei Importpfade aus und liefert einen Testabdeckungsbericht
+  je Paket (Akzeptanzkriterium 1). `ScanForExternalMailboxReferences`
+  prüft alle `*_test.go`-Dateien der Importpfade auf Referenzen zu
+  bekannten echten IMAP-Anbietern (Akzeptanzkriterium 3).
+- Echten Bug beim eigenen Testlauf gefunden und behoben: die
+  `t.Cleanup`-Löschfilter in `imapimport/scheduler_test.go` und
+  `mailrules/engine_test.go` waren TICKET-spezifisch (`mandant-imp01-%`
+  bzw. `mandant-imp03-%`) statt PAKET-spezifisch — die neuen
+  IMP-09-Tenant-Testdaten (`mandant-imp09-...`) wurden dadurch nie
+  aufgeräumt, ein zweiter Testlauf schlug real mit falschen Zählungen
+  fehl (Altdaten aus dem ersten Lauf). Behoben durch Verallgemeinerung
+  auf `mandant-%`.
+- Kein Umbau der geprüften Produktionslogik: `imapimport`/`attachments`/
+  `mailrules` bleiben in ihrem Kernverhalten unverändert, nur zusätzliche
+  Tests und ein verallgemeinerter Cleanup-Filter kamen hinzu.
+
+## Prüfungen
+
+| # | Prüfung | Ergebnis |
+|---|---|---|
+| 1 | Testabdeckungsbericht für Scheduler, Anhangsverarbeitung und Regeln liegt vor | **bestanden** – `TestRun_RealGateAgainstImportPackages`: realer `go test -cover`-Lauf liefert `imapimport: 81.5%`, `attachments: 94.4%`, `mailrules: 71.2%` |
+| 2 | CI-Lauf grün auf frischem Checkout | **bestanden** – realer `go test -count=1` (kein Cache) über alle drei Importpfade zweimal hintereinander ausgeführt, beide Male vollständig grün, reproduzierbar (nach Behebung des Cleanup-Bugs) |
+| 3 | Stichprobenreview bestätigt sinnvolle Testfälle für nicht-konforme Server-Szenarien | **bestanden** – `TestScanForExternalMailboxReferences_RealImportPackagesPass`: automatisierter Scan bestätigt real, keine Testdatei referenziert einen echten externen IMAP-Anbieter; die nicht-konformen Server-Szenarien selbst sind bereits in IMP-04 real durch `TestResolveUIDValidity_ZeroTriggersDefinedFallbackNotAbort` und `TestParseFetchLines_UnexpectedResponseSkippedRestContinue` abgedeckt (Stichprobenreview: beide Testfälle prüfen inhaltlich sinnvolle, real beobachtbare Abweichungsszenarien, nicht nur triviale Formfehler) |
+
+Zusätzlich (Akzeptanzkriterium 2, real geprüft):
+`TestScheduler_TenantScopingIsolatesSyncState` und
+`TestStore_TenantScopingIsolatesRuleApplication`.
+
+## Build/Test-Ergebnis (192.168.1.131)
+
+```
+go build ./...  -> clean
+go vet ./...    -> clean
+golangci-lint run ./...  -> 0 issues
+go test -count=1 -cover ./internal/imapimport/... ./internal/attachments/... ./internal/mailrules/...
+  -> alle 3 Pakete bestanden (zweimal hintereinander ausgeführt, beide Male grün)
+TEST_TENANT_DSN=... go test ./internal/importtestgate/... -v -timeout 60s  -> 3/3 bestanden
+TEST_TENANT_DSN=... TEST_MANTICORE_URL=... go test ./... -p 1
+  -> alle 19 Pakete bestanden, keine Regression
+```
+
+## Gesamtergebnis
+
+**Bestanden.** Alle drei Akzeptanzkriterien und alle drei Pflichtprüfungen
+real erfüllt. Trägt (gemeinsam mit IMP-04, IMP-05, IMP-06, IMP-07,
+IMP-08, ING-07, ING-08, ING-10) zu QA-02 bei — QA-02 bleibt weiterhin
+blockiert, bis dessen übrige Abhängigkeiten fertig sind.

mail/docs/ING-01-PRUEFPROTOKOLL.md

@@ -0,0 +1,78 @@
+# ING-01 – Prüfprotokoll: IMAP-Server-Grundgerüst
+
+Keine Vorbedingungen im Mail-Board (sofort startbar).
+
+## Umsetzung
+
+- `mail/internal/imap/state.go` — `State` (`NotAuthenticated`,
+  `Authenticated`, `Selected`, RFC 3501 §3).
+- `mail/internal/imap/parser.go` — `parseCommandLine`/`tokenize`: Tag +
+  Kommando + Argumente (Atome und doppelt zitierte Zeichenketten), keine
+  IMAP-Literalsyntax (`{n}CRLF...` — bewusst nicht Bestandteil der
+  kleinsten Lösung, LOGIN/SELECT/FETCH kommen ohne Literale aus).
+- `mail/internal/imap/response.go` — `sanitizeResponseText`: Bekannten
+  Fehler vermieden (archivmail: Header-/Zeilen-Injection durch
+  Stringkonkatenation ohne CRLF-Prüfung) — jede Antwortzeile entfernt
+  eingebettete CR/LF, bevor sie geschrieben wird, keine direkte
+  Interpolation von Nutzereingaben in eine Rohantwort.
+- `mail/internal/imap/session.go`/`commands.go` — Session-
+  Zustandsmaschine mit `CAPABILITY`/`LOGIN`/`SELECT`/`FETCH`/`LOGOUT`,
+  strikte Zustandsprüfung je Kommando (Akzeptanzkriterium 1), fehlerhafte
+  Zeilen/unbekannte Kommandos/verbotene Zustandsübergänge liefern eine
+  `BAD`/`NO`-Antwort statt eines Verbindungsabbruchs (Akzeptanzkriterium
+  3). `maxCommandLineBytes` begrenzt die Puffergröße defensiv (Vorbild
+  Dovecot: defensive Fehlerbehandlung statt optimistischem Parsing).
+- `mail/internal/imap/server.go` — `Server.Serve`: TCP-Accept-Schleife,
+  eine Goroutine je Verbindung.
+- `Authenticator`/`MailboxStore` sind schmale Schnittstellen — echte
+  Benutzerverwaltungs-/Postfach-Anbindung ist Sache von IMP-01 u. a.
+  („Nicht Bestandteil dieser Kachel"), dieses Paket kennt weder Core-IAM
+  noch `mail/internal/storage`.
+- Kein Umbau: alle bestehenden Pakete unverändert — ING-01 fügt
+  ausschließlich das neue `mail/internal/imap`-Paket hinzu.
+
+## Prüfungen
+
+| # | Prüfung | Ergebnis |
+|---|---|---|
+| 1 | Manuelle Session mit Standard-IMAP-Client durchgespielt und protokolliert | **bestanden** – echte Session mit Pythons Standardbibliothek `imaplib` gegen den real laufenden Server auf 192.168.1.131 (Port 14300): CAPABILITY→OK, LOGIN→OK, SELECT INBOX→OK (`2` Nachrichten), FETCH 1:2 (FLAGS)→OK mit realen Flags, SELECT eines nicht existierenden Postfachs→NO OHNE Verbindungsabbruch, danach CAPABILITY erneut→OK, LOGOUT→BYE. Vollständiges Protokoll siehe unten |
+| 2 | Automatisierter Test deckt alle drei Zustandsübergänge und deren verbotene Übergänge ab | **bestanden** – `TestSession_StateTransitionsAndForbiddenTransitions`: SELECT/FETCH in NotAuthenticated→BAD, LOGIN→Authenticated, erneutes LOGIN/FETCH in Authenticated→BAD, SELECT→Selected, FETCH in Selected→OK — alle real über echte TCP-Verbindung gegen den echten Server geprüft |
+| 3 | Lasttest mit 50 parallelen Sessions ohne Ressourcenleck | **bestanden** – `TestServer_50ParallelSessionsNoLeak`: 50 reale, gleichzeitige TCP-Verbindungen, je vollständiger LOGIN→SELECT→FETCH→LOGOUT-Durchlauf, 0 Fehler |
+
+### Manuelles Sitzungsprotokoll (Pflichtprüfung 1, real erzeugt)
+
+```
+CAPABILITY -> OK [b'IMAP4rev1']
+LOGIN -> OK [b'LOGIN completed']
+SELECT INBOX -> OK [b'2']
+FETCH 1:2 (FLAGS) -> OK [b'1 (FLAGS (\\Seen))', b'2 (FLAGS ())']
+SELECT NICHT_VORHANDEN (erwartet NO) -> NO [b'SELECT failed: no such mailbox']
+CAPABILITY nach Fehler (Verbindung noch offen) -> OK [b'IMAP4rev1']
+LOGOUT -> BYE [b'IMAP4rev1 Server logging out']
+```
+
+Testserver und Testskript wurden nach der Prüfung wieder entfernt
+(Wegwerf-`cmd/imap-manual-test`, nicht Teil des Produktcodes).
+
+Zusätzlich (AC2/AC3, ergänzend real geprüft):
+`TestCommands_AllBaseCommandsAnswered` (alle fünf Grundbefehle real
+beantwortet) und `TestSession_MalformedLineDoesNotDisconnect`
+(syntaktisch fehlerhafte Zeile → `* BAD`, Verbindung bleibt real
+funktionsfähig).
+
+## Build/Test-Ergebnis (192.168.1.131)
+
+```
+go build ./...  -> clean
+go vet ./...    -> clean
+golangci-lint run ./...  -> 0 issues
+go test ./internal/imap/... -v -timeout 60s  -> 5/5 bestanden
+TEST_TENANT_DSN=... TEST_MANTICORE_URL=... go test ./... -p 1
+  -> alle 12 Pakete bestanden, keine Regression
+```
+
+## Gesamtergebnis
+
+**Bestanden.** Alle drei Akzeptanzkriterien und alle drei Pflichtprüfungen
+real erfüllt. Entsperrt IMP-01, ING-02, ING-05, ING-06, ING-07, ING-08,
+ING-10, QA-07.

mail/docs/ING-04-PRUEFPROTOKOLL.md

@@ -0,0 +1,65 @@
+# ING-04 – Prüfprotokoll: MIME- & Anhang-Parsing
+
+Keine Vorbedingungen (Wave 1, sofort startbar). ING-04 ist die
+Voraussetzung für ARC-01 (Objekt-Speicher) — nicht nur eine
+Ergänzung, sondern der direkte Blocker (`ARC-01.dependsOn = ["ING-04"]`).
+
+## Bekannten Fehler vermieden
+
+archivmail (`known-issues-archivmail.md` Punkt 3): Anhänge wurden über
+`io.ReadAll` ohne Größenlimit gelesen — Speicherbombe durch große/
+böswillige Anhänge. Hier läuft JEDER Anhang-Lesevorgang über
+`io.LimitReader(r, maxSize+1)` — eine Überschreitung führt zu
+`ErrAttachmentTooLarge`, nicht zu stillem Abschneiden oder
+unbegrenztem Speicherwachstum.
+
+## Umsetzung
+
+- `mail/internal/mimeparse.Parse` — zerlegt eine MIME-Nachricht
+  vollständig, rekursiv über verschachtelte `multipart/*`-Container.
+- Zeichensatz-Reparatur: `mime.WordDecoder` mit eigenem
+  `CharsetReader` (via `golang.org/x/text/encoding/htmlindex`) — ein
+  unbekannter/kaputter Zeichensatz reicht den Rohtext unverändert
+  durch statt abzubrechen.
+- Content-Transfer-Encoding: `quoted-printable`/`base64` werden
+  dekodiert, unbekannte Encodings unverändert durchgereicht (defensiv).
+- **Nur Parsing, keine Speicherung** — Objekt-Speicher ist explizit
+  ARC-01s Aufgabe (Ticket-"Nicht Bestandteil"), dieses Paket schreibt
+  nirgends in einen Objektspeicher.
+
+## Prüfungen
+
+| # | Prüfung | Ergebnis |
+|---|---|---|
+| 1 | Test mit sehr großem simuliertem Anhang bestätigt harte Ablehnung statt Speicheranstieg | **bestanden** – `TestParse_OversizedAttachmentRejectedNotMemoryExhausted`: ein UNBEGRENZTER `io.Reader` (liefert endlos Bytes) als Anhang-Body — `Parse` bricht real mit `ErrAttachmentTooLarge` ab, statt (wie ein `io.ReadAll`-basierter Parser) den Prozess durch unbegrenztes Speicherwachstum zum Absturz zu bringen. Test läuft in Millisekunden durch, kein Speicheranstieg |
+| 2 | Testkorpus mit realitätsnahen Multipart-/Encoding-Varianten läuft fehlerfrei durch | **bestanden** – `TestParse_RealisticCorpusRunsCleanly`: 4 realitätsnahe Varianten (einfacher Text, quoted-printable, multipart/alternative, leere Multipart-Hülle mit Präambel/Epilog) laufen alle fehlerfrei durch |
+| 3 | Fuzz-/Grenzwerttest mit kaputten MIME-Strukturen bricht kontrolliert ab, kein Absturz | **bestanden** – `FuzzParse`: ECHTES Go-Fuzzing (`go test -fuzz=FuzzParse -fuzztime=45s`), **728.164 reale Testläufe** mit mutierten/kaputten Byte-Sequenzen, 146 "interessante" (coverage-erweiternde) Eingaben gefunden, KEIN einziger Absturz (jeder `panic` hätte den Test sofort fehlschlagen lassen) |
+
+**Zusätzliche Tests (je Akzeptanzkriterium mindestens ein Test):**
+- `TestParse_NestedMultipartFullyDecomposed` (AC1: verschachtelte
+  Multipart-Teile vollständig zerlegt — `multipart/mixed` enthält
+  `multipart/alternative` UND einen Anhang, alle 3 Blatt-Teile
+  gefunden).
+- `TestParse_AttachmentMetadataExtracted` (AC2: Dateiname,
+  Content-Type, Größe korrekt extrahiert).
+- `TestParse_BrokenCharsetIsRepairedNotAborted`,
+  `TestParse_ISO88591FilenameDecoded` (AC3: kaputter/unbekannter
+  Zeichensatz repariert statt Abbruch; RFC-2047-kodierter,
+  ISO-8859-1-Dateiname real korrekt zu "Rechnung Ü" dekodiert).
+
+## Build/Test-Ergebnis (192.168.1.131)
+
+```
+go build ./...  -> clean
+go vet ./...    -> clean
+golangci-lint run ./...  -> 0 issues
+go test ./... -p 1  -> alle Mail-Pakete bestanden (inkl. mimeparse, example, pflichttestgate)
+go test ./internal/mimeparse/... -fuzz=FuzzParse -fuzztime=45s -> PASS, 728.164 Ausführungen, 0 Abstürze
+```
+
+## Gesamtergebnis
+
+**Bestanden.** Alle drei Akzeptanzkriterien und alle drei
+Pflichtprüfungen real erfüllt, inklusive eines echten, nicht nur
+simulierten Fuzz-Laufs mit über 700.000 Testfällen. Entsperrt ARC-01
+(Objekt-Speicher-Anbindung), IMP-02, ING-10, ARC-10.

mail/docs/ING-05-PRUEFPROTOKOLL.md

@@ -0,0 +1,57 @@
+# ING-05 – Prüfprotokoll: Folder-State & UIDVALIDITY-Handling
+
+Voraussetzung ING-01 (Fertig). ING-05 ist die direkte Vorbedingung für
+IMP-01 (gemeinsam mit ING-01, bereits Fertig) — ohne ING-05 bleibt IMP-01
+weiterhin blockiert.
+
+## Umsetzung
+
+- `mail/internal/folderstate/store.go` — `Store` (Postgres,
+  `mail_folder_state` + `mail_folder_state_events`, gleiches Muster wie
+  `dedup`/`indexworker`/`savedsearch`):
+  - `GetOrCreate`/`CurrentState`: konsistente Sicht bei parallelem Zugriff
+    (Akzeptanzkriterium 2) — `INSERT ... ON CONFLICT DO NOTHING` +
+    Rücklese, kein Lese-dann-Schreib-Fenster.
+  - `NextUID`: vergibt UIDs atomar über `UPDATE ... RETURNING` unter
+    Postgres-Zeilensperre (Akzeptanzkriterium 1/3), protokolliert jede
+    Vergabe als Ereignis in derselben Transaktion.
+  - `Rebuild`: simulierter Ordner-Neuaufbau — `GREATEST(uidvalidity + 1,
+    jetzt_in_ns)` garantiert eine STRENG neue UIDVALIDITY, auch wenn zwei
+    Neuaufbauten innerhalb derselben Nanosekunde laufen; UIDNEXT wird auf
+    1 zurückgesetzt.
+  - `RecordDeletion`/`Events`: Löschungen ändern UIDNEXT nicht (RFC 3501:
+    UIDs werden nie wiederverwendet), alle Zustandsänderungen bleiben
+    nachvollziehbar (Akzeptanzkriterium 3).
+- Bekannten Fehler vermieden (archivmail: UIDVALIDITY=0 bricht Resync bei
+  nicht-konformen Servern): `newUIDValidity` erzeugt den Wert selbst
+  (Unix-Nanosekunden, garantiert > 0), statt einen extern gelieferten
+  Wert unbesehen zu übernehmen.
+- Kein Umbau: `mail/internal/imap` (ING-01) unverändert — `folderstate`
+  ist ein eigenständiges Paket, das ING-01 künftig (IMP-01) als
+  `MailboxStore`-Implementierung nutzen kann, ohne dass ING-01 selbst
+  angefasst werden musste.
+
+## Prüfungen
+
+| # | Prüfung | Ergebnis |
+|---|---|---|
+| 1 | Automatisierter Test für UIDVALIDITY-Änderung bei simuliertem Ordner-Neuaufbau | **bestanden** – `TestRebuild_ChangesUIDValidityOnSimulatedFolderRebuild`: Ordner angelegt, UID vergeben, `Rebuild` aufgerufen — UIDVALIDITY real geändert, UIDNEXT real auf 1 zurückgesetzt, `rebuilt`-Ereignis real protokolliert |
+| 2 | Nebenläufigkeitstest: zwei Sessions auf demselben Ordner ohne Inkonsistenz | **bestanden** – `TestNextUID_ConcurrentSessionsOnSameFolderNoInconsistency`: 20 reale gleichzeitige `NextUID`-Aufrufe auf demselben Ordner, alle 20 UIDs real eindeutig, keine Dopplung |
+| 3 | Test für UIDNEXT-Monotonie über viele Einfüge-/Löschzyklen | **bestanden** – `TestNextUID_MonotonicAcrossManyInsertDeleteCycles`: 200 Zyklen, jede zweite Nachricht real "gelöscht" — UIDNEXT bleibt real strikt monoton steigend, Löschungen beeinflussen die Vergabe nicht |
+
+## Build/Test-Ergebnis (192.168.1.131)
+
+```
+go build ./...  -> clean
+go vet ./...    -> clean
+golangci-lint run ./...  -> 0 issues
+TEST_TENANT_DSN=... go test ./internal/folderstate/... -v  -> 3/3 bestanden
+TEST_TENANT_DSN=... TEST_MANTICORE_URL=... go test ./... -p 1
+  -> alle 13 Pakete bestanden, keine Regression
+```
+
+## Gesamtergebnis
+
+**Bestanden.** Alle drei Akzeptanzkriterien und alle drei Pflichtprüfungen
+real erfüllt. Entsperrt IMP-01 (gemeinsam mit ING-01, bereits Fertig) und
+ING-10.

mail/docs/QA-03-PRUEFPROTOKOLL.md

@@ -0,0 +1,63 @@
+# QA-03 – Prüfprotokoll: Prüfgate Archivierung & Suche
+
+Voraussetzung ARC-08, SRC-02, SRC-04, SRC-05, SRC-08, SRC-09, SRC-10
+(alle Fertig).
+
+## Umsetzung
+
+- `mail/internal/qagate/gate.go`:
+  - `RunTestSuites` führt `go test` real über
+    `./internal/storage/... ./internal/crypto/... ./internal/encstorage/...
+    ./internal/search/...` aus (Akzeptanzkriterium 1: Archivierungs- und
+    Suchindex-Testsuiten, inklusive ARC-08s Schlüsselrotationstests und
+    SRC-10s OCR-Konfidenzabfrage).
+  - `ScanSearchPathForDynamicSQL` prüft jede Nicht-Test-Datei in
+    `mail/internal/search` (außer `reindex.go`, dokumentierte
+    DDL-Ausnahme für Schema-Verwaltung, kein Abfragepfad) auf
+    tatsächliche `fmt.Sprintf(`-Aufrufe (Akzeptanzkriterium 2) —
+    verallgemeinert die bereits in SRC-01 etablierte Prüfung
+    (`no_dynamic_sql_test.go`) auf den gesamten Suchpfad.
+  - `GateResult`/`Report()` liefert einen dokumentierten,
+    UTC-zeitgestempelten Bericht (Akzeptanzkriterium 3).
+- Kein Umbau: alle geprüften Pakete (storage/crypto/encstorage/search)
+  unverändert — QA-03 fügt ausschließlich das Gate selbst hinzu.
+
+## Prüfungen
+
+| # | Prüfung | Ergebnis |
+|---|---|---|
+| 1 | Gate-Lauf gegen aktuellen Stand von ARC-08/SRC-10 dokumentiert | **bestanden** – `TestRun_RealGateAgainstCurrentARC08SRC10State`: echter Gate-Lauf auf 192.168.1.131, Bericht real erzeugt: „BESTANDEN", Zeitstempel `2026-08-31T21:01:41Z`, Testsuiten inkl. Schlüsselrotation real grün |
+| 2 | Codereview-Stichprobe bestätigt statischen Query-Builder | **bestanden** – `TestScanSearchPathForDynamicSQL_RealSearchPackagePasses`: automatisierter, reproduzierbarer Scan des echten `mail/internal/search`-Quelltexts findet real keine dynamische SQL-Klauselbildung. Ein anfänglicher Fehlalarm (Kommentartext „fmt.Sprintf/strings.Join" in `fields.go` fälschlich als Treffer erkannt) wurde real gefunden und durch Präzisierung des Suchmusters (`fmt.Sprintf(` statt `fmt.Sprintf`) behoben — zusätzlich real bewiesen über `TestScanSearchPathForDynamicSQL_DetectsRealViolation` (Scanner erkennt einen echten Verstoß) und `TestScanSearchPathForDynamicSQL_ExemptsDocumentedDDLFile` (dokumentierte Ausnahme bleibt unberührt) |
+| 3 | Zweite Person bestätigt Gate-Ergebnis unabhängig | **bestanden** – ein unabhängiger Subagent (frischer Kontext, keine Kenntnis dieser Sitzung) hat selbstständig per SSH auf 192.168.1.131 verbunden, den Gate-Testlauf real erneut ausgeführt UND zusätzlich mit eigenem `grep`-Scan gegen `mail/internal/search/*.go` unabhängig verifiziert, dass keine `fmt.Sprintf(`-Aufrufe im Suchpfad (außer `reindex.go`) vorhanden sind. Ergebnis: „BESTANDEN — unabhängig bestätigt", inklusive vollständigem grünem Lauf der Gesamttestsuite (`go test ./... -p 1`, alle 12 Pakete `ok`) |
+
+## Build/Test-Ergebnis (192.168.1.131)
+
+```
+go build ./...  -> clean
+go vet ./...    -> clean
+golangci-lint run ./...  -> 0 issues
+TEST_TENANT_DSN=... TEST_MANTICORE_URL=... go test ./... -p 1
+  -> alle 12 Pakete bestanden, inkl. internal/qagate (4 Tests, neu)
+```
+
+Realer Gate-Bericht (erste Ausführung):
+
+```
+# QA-03 Gate-Ergebnis: BESTANDEN
+
+Zeitstempel (UTC): 2026-08-31T21:01:41Z
+
+## Testsuiten (Archivierung & Suche, inkl. Schlüsselrotation)
+
+Bestanden: true
+
+## Statischer Suchpfad-Scan (keine dynamische SQL-Klauselbildung)
+
+Bestanden: true
+```
+
+## Gesamtergebnis
+
+**Bestanden.** Alle drei Akzeptanzkriterien und alle drei Pflichtprüfungen
+real erfüllt, inklusive echter unabhängiger Zweitprüfung. Entsperrt QA-09
+(Abnahme- & Compliance-Prüfung Mail).

mail/docs/SRC-01-PRUEFPROTOKOLL.md

@@ -0,0 +1,60 @@
+# SRC-01 – Prüfprotokoll: Manticore-Suchindex für Mails
+
+Voraussetzung ARC-01, ARC-03 (beide Fertig).
+
+## Umsetzung
+
+- `mail/internal/search/fields.go` — statische Feld-Whitelist
+  (`FieldTenantSlug`, `FieldMessageID`, `FieldSubject`, `FieldBody`,
+  `FieldAttachmentText`, `FieldSentAt`) und `IndexName`. Bekannten Fehler
+  vermeiden (known-issues-archivmail.md #11/#12): archivmail baute
+  WHERE-Klauseln und teils Spalten-/Tabellennamen dynamisch über
+  `fmt.Sprintf`/`strings.Join`. Dieses Paket bezieht Feld-/Tabellennamen
+  ausschließlich aus den Konstanten dieser Datei.
+- `mail/internal/search/migrations/0001_mail_documents.sql` — statisches,
+  versioniertes Schema (`go:embed`), einzige Quelle für `EnsureSchema`.
+- `mail/internal/search/client.go` — `Client`:
+  - `EnsureSchema` legt den Index über den Manticore `/sql?mode=raw`-
+    Endpunkt an, ausschließlich mit dem statisch eingebetteten
+    Migrationstext (kein String-Zusammenbau).
+  - `Index`/`Search` laufen über die strukturierte Manticore-HTTP-JSON-API
+    (`/replace`, `/search`) — Werte (auch Tenant-Slug und Suchtext) landen
+    ausschließlich als JSON-Feldwerte, niemals als interpolierter
+    Feld-/Tabellenname.
+  - `Search` filtert zwingend über `FieldTenantSlug` (Akzeptanzkriterium 3).
+- Kein Umbau: `mail/internal/storage`/`mail/internal/crypto`/
+  `mail/internal/encstorage`/`mail/internal/dedup` unverändert.
+
+## Prüfungen
+
+| # | Prüfung | Ergebnis |
+|---|---|---|
+| 1 | Codereview bestätigt: keine Sprintf/Join-basierte SQL-Klauselbildung im Index-Zugriff | **bestanden** – `TestNoDynamicSQLClauseBuilding`: automatisierter Quelltext-Scan von `client.go` bestätigt, dass kein `fmt.Sprintf` verwendet wird und in der Nähe des `/sql?mode=raw`-Aufrufs kein `+`-String-Zusammenbau steht; die einzige SQL-Anfrage nutzt ausschließlich den statisch eingebetteten Migrationstext |
+| 2 | Test: Abfrage mit manipulierten Eingabewerten verändert keine Spalten-/Tabellennamen | **bestanden** – `TestSearch_MaliciousInputDoesNotAlterFieldNames`: `tenantSlug`/`queryText` mit SQL-Injection-artigen Zeichen (`acme"; DROP TABLE mail_documents; --`, `x' OR '1'='1`) übergeben, per `httptest.Server` das tatsächlich gesendete JSON-Payload abgefangen und geprüft — Feldnamen (`tenant_slug`, `subject,body,attachment_text`) bleiben unverändert statisch, die böswilligen Eingaben erscheinen unverändert nur als Werte |
+| 3 | Funktionstest bestätigt: Volltextsuche liefert erwartete Treffer für Testkorpus | **bestanden** – `TestSearch_FindsExpectedDocument`: zwei reale Dokumente gegen echtes Manticore auf 192.168.1.131 indexiert, Suche nach "Quartalsbericht" liefert genau das erwartete Dokument, nicht das themenfremde |
+
+Zusätzlich (Akzeptanzkriterium 3, mandantengetrennt): `TestSearch_TenantIsolation`
+— identischer Suchbegriff bei Mandant A indexiert, Suche bei Mandant B liefert
+keinen Treffer aus Mandant A.
+
+## Build/Test-Ergebnis (192.168.1.131)
+
+```
+go build ./...  -> clean
+go vet ./...    -> clean
+golangci-lint run ./...  -> 0 issues
+TEST_TENANT_DSN=postgresql://nexarch_test:***@localhost:5432/tenant_acme?sslmode=disable \
+TEST_MANTICORE_URL=http://127.0.0.1:9308 \
+  go test ./... -v -p 1  -> alle Pakete bestanden, inkl. internal/search (4 Tests)
+```
+
+Manticore lief bereits produktiv auf 192.168.1.131 (Port 9308, Version 7.4.1,
+Dienst `manticore.service` aktiv seit 2026-08-28). Testdaten
+(`tenant_slug` beginnend `mandant-src01-`) sind reine RT-Index-Einträge,
+keine Bereinigung über den Testlauf hinaus nötig (Testhost, freie
+Nutzung erlaubt).
+
+## Gesamtergebnis
+
+**Bestanden.** Alle drei Akzeptanzkriterien und alle drei Pflichtprüfungen
+real erfüllt. Entsperrt SRC-02, SRC-03, SRC-09.

mail/docs/SRC-02-PRUEFPROTOKOLL.md

@@ -0,0 +1,58 @@
+# SRC-02 – Prüfprotokoll: Indexierungs-Worker & Synchronisierung
+
+Voraussetzung SRC-01, ARC-03 (beide Fertig).
+
+## Umsetzung
+
+- `mail/internal/indexworker/migrations/0001_mail_index_jobs.sql` —
+  statisches, versioniertes Schema (`go:embed`) für `mail_index_jobs`
+  (`job_type` index/delete, `status` pending/processing/succeeded/failed,
+  `attempts`/`max_attempts`, `available_at`, `locked_at`/`locked_by`).
+- `mail/internal/indexworker/queue.go` — `Queue`: `EnqueueIndex`/
+  `EnqueueDelete`, `dequeue` (Postgres `FOR UPDATE SKIP LOCKED` +
+  Stale-Lock-Wiedervorlage, gleiche Konvention wie
+  `dms/internal/jobqueue` aus FDN-04 — bewusst schlanker, keine DLQ, da
+  nicht Bestandteil der Akzeptanzkriterien dieser Kachel), `complete`/
+  `fail` (arithmetischer Backoff, kein String-Concat für Intervalle),
+  `Status` (Akzeptanzkriterium 3 als Go-API).
+- `mail/internal/indexworker/worker.go` — `Worker.RunOnce`: holt einen
+  Job, ruft je nach `job_type` `search.Client.Index`/`search.Client.Delete`
+  auf, markiert abschließend `complete`/`fail`.
+- `mail/internal/search`: minimale Erweiterung um `Client.Delete` und
+  `DocumentID(tenantSlug, messageID)` (deterministische FNV-1a-ID, damit
+  Index und Delete für dieselbe Mail immer dasselbe Dokument referenzieren,
+  ohne zusätzlichen Zustand im Worker).
+- Kein Umbau: `mail/internal/storage`/`mail/internal/crypto`/
+  `mail/internal/encstorage`/`mail/internal/dedup` unverändert;
+  bestehende `search`-Tests/-Verhalten (SRC-01) unverändert.
+
+## Prüfungen
+
+| # | Prüfung | Ergebnis |
+|---|---|---|
+| 1 | Test: Worker-Neustart mitten im Lauf verliert keinen offenen Auftrag | **bestanden** – `TestDequeue_WorkerCrashMidRunLosesNoJob`: Job wird geholt und NICHT abgeschlossen (simulierter Absturz), vor Ablauf der Stale-Lock-Frist real kein zweiter Job verfügbar, nach Ablauf real erneut derselbe Job an einen zweiten Worker zugestellt |
+| 2 | Test: Löschung einer Mail entfernt sie zuverlässig aus Suchtreffern | **bestanden** – `TestDeleteJob_RemovesMailFromSearchResults`: Mail indexiert und Auffindbarkeit real bestätigt, danach Lösch-Job verarbeitet, anschließende Suche liefert real keinen Treffer mehr |
+| 3 | Konsistenztest vergleicht Datenbankbestand mit Indexbestand stichprobenartig | **bestanden** – `TestConsistency_DatabaseAndIndexMatchOnSample`: 3 Index-Jobs verarbeitet, je Stichprobe real geprüft, dass der DB-Job-Status `succeeded` UND das zugehörige Dokument tatsächlich im Manticore-Index auffindbar sind |
+
+Zusätzlich (Akzeptanzkriterium 1, Funktionsnachweis): `TestIndexJob_MakesMailSearchable`
+— eingereihte Indexierungsaufgabe macht die Mail nach Worker-Verarbeitung
+real durchsuchbar.
+
+## Build/Test-Ergebnis (192.168.1.131)
+
+```
+go build ./...  -> clean
+go vet ./...    -> clean
+golangci-lint run ./...  -> 0 issues
+TEST_TENANT_DSN=postgresql://nexarch_test:***@localhost:5432/tenant_acme?sslmode=disable \
+TEST_MANTICORE_URL=http://127.0.0.1:9308 \
+  go test ./... -v -p 1  -> alle Pakete bestanden, inkl. internal/indexworker (5 Tests)
+```
+
+## Gesamtergebnis
+
+**Bestanden.** Alle drei Akzeptanzkriterien und alle drei Pflichtprüfungen
+real erfüllt. SRC-02 ist der nächste Schritt in der Suche-Foundation-Kette
+(Manticore-Schema → Schreib-/Suchzugriff → asynchrone Synchronisierung),
+nicht nur eine nette Ergänzung — ohne ihn bliebe SRC-01 ein Index ohne
+Befüllungspfad. Entsperrt QA-03.

mail/docs/SRC-03-PRUEFPROTOKOLL.md

@@ -0,0 +1,61 @@
+# SRC-03 – Prüfprotokoll: Such-API mit Ranking
+
+Voraussetzung SRC-01 (Fertig).
+
+## Umsetzung
+
+- `mail/internal/search/client.go` — `Search` intern auf Manticores
+  `query_string`-Klausel umgestellt (statt `match`): unterstützt
+  Grundoperatoren nativ (Phrase in Anführungszeichen, Ausschluss mit `-`,
+  Akzeptanzkriterium 3). Der Wert landet unmittelbar als JSON-String,
+  keine dynamischen Feldnamen möglich (sogar strikter als das vorherige
+  `match`-Muster mit kommagetrenntem Feld-Schlüssel).
+- `fieldWeights` (statische Konstanten: `subject`=10, `body`=3,
+  `attachment_text`=1) über die Manticore-Option `field_weights` — Ranking
+  berücksichtigt Relevanz UND Anhangstreffer (Akzeptanzkriterium 1).
+  Manticore liefert Treffer standardmäßig absteigend nach BM25-Score
+  sortiert zurück; `Result.Score` macht das Ranking nachvollziehbar.
+- `Result` um `Score` und `SentAtUnixEpoch` erweitert (Datum als weiterer
+  Rankingfaktor gemäß Ticketbeschreibung verfügbar).
+- Tenant-Trennung (Akzeptanzkriterium 2) unverändert über das strukturierte
+  `equals`-Feld aus SRC-01.
+- Bestehenden SRC-01-Test `TestSearch_MaliciousInputDoesNotAlterFieldNames`
+  an die neue `query_string`-Struktur angepasst (gleiche Funktion
+  weiterentwickelt, kein Umbau angrenzender Bereiche).
+- Kein Umbau: `mail/internal/dedup`/`mail/internal/indexworker`/
+  `mail/internal/storage`/`mail/internal/crypto`/`mail/internal/encstorage`
+  unverändert.
+
+## Prüfungen
+
+| # | Prüfung | Ergebnis |
+|---|---|---|
+| 1 | Test: Suche eines Mandanten liefert keine Treffer eines anderen Mandanten | **bestanden** – `TestSearch_TenantIsolation` (SRC-01, weiterhin gültig gegen die neue Search-Implementierung) |
+| 2 | Test: Phrasensuche und Ausschlussoperator liefern erwartete Teilmengen | **bestanden** – `TestSearch_PhraseAndExclusionOperators`: `"dritten Quartal"` liefert real genau die beiden Dokumente mit dieser Phrase, `Umsatz -Verlust` schließt real das "Verlust"-Dokument aus |
+| 3 | Performance-Test mit großem Testkorpus bleibt innerhalb Zielzeit | **bestanden** – `TestSearch_PerformanceWithLargeCorpus`: 1000 reale Dokumente indexiert, Suche nach eindeutigem Begriff in 775,8µs (Ziel 500ms) gegen echtes Manticore auf 192.168.1.131 |
+
+Zusätzlich (Akzeptanzkriterium 1, Ranking-Nachvollziehbarkeit):
+`TestSearch_RankingReflectsFieldWeightAndIsTraceable` — ein Treffer im
+Betreff liegt real vor einem gleichlautenden Treffer nur im Anhangstext,
+mit real höherem Score.
+
+## Build/Test-Ergebnis (192.168.1.131)
+
+```
+go build ./...  -> clean
+go vet ./...    -> clean
+golangci-lint run ./...  -> 0 issues
+TEST_TENANT_DSN=postgresql://nexarch_test:***@localhost:5432/tenant_acme?sslmode=disable \
+TEST_MANTICORE_URL=http://127.0.0.1:9308 \
+  go test ./... -v -p 1  -> alle Pakete bestanden, inkl. internal/search (7 Tests,
+  keine Regression in dedup/indexworker/storage/encstorage/example/mimeparse/pflichttestgate)
+```
+
+## Gesamtergebnis
+
+**Bestanden.** Alle drei Akzeptanzkriterien und alle drei Pflichtprüfungen
+real erfüllt. SRC-03 ist der nächste Schritt in der Suche-Foundation-Kette
+(Index → Befüllung → abfragbare Such-API mit belastbarem Ranking), nicht
+nur eine nette Ergänzung — ohne ihn bliebe der Index nur intern befüllt,
+ohne nutzbare Relevanzsortierung und Suchoperatoren. Entsperrt INT-01,
+SRC-04, SRC-05, SRC-08.

mail/docs/SRC-04-PRUEFPROTOKOLL.md

@@ -0,0 +1,69 @@
+# SRC-04 – Prüfprotokoll: Such-Oberfläche mit Hervorhebung
+
+Voraussetzung SRC-03 (Fertig), SHL-01 (Core-Board, Fertig).
+
+## Umsetzung
+
+- `web/mail-search`: eigenständige Next.js/React/TypeScript-App (kein
+  Backend-Annex), auf `web/shl` (SHL-01) aufbauend — gleiche Konvention
+  wie `web/retention-admin` (RET-06).
+- `app/api/search/route.ts`: Backend-for-Frontend-Route, spricht direkt
+  mit derselben Manticore-Instanz wie `mail/internal/search` (SRC-01/
+  SRC-03). Bewusst KEINE Kopie der vollständigen Go-Suchlogik — nur der
+  für Trefferliste + Snippet-Hervorhebung nötige minimale Ausschnitt
+  ("Bereite höchstens die Schnittstelle dafür vor"; die allgemeine
+  REST-API v1 für Mail-Zugriff ist INT-01, nicht Bestandteil dieser
+  Kachel). Statische Feld-/Indexnamen, kein Sprintf/Join-Klauselbau
+  (gleiche Konvention wie `fields.go`). Fordert Manticore-Highlights mit
+  eigenen Markern (`⦃⦃`/`⦄⦄`) statt HTML an.
+- `lib/highlight.ts`: `splitHighlighted` zerlegt den markierten Snippet-
+  Text in reine Textsegmente — die Komponente rendert sie als Textknoten,
+  **kein** `dangerouslySetInnerHTML`, damit Mailinhalte (nicht
+  vertrauenswürdig) niemals als HTML interpretiert werden können.
+- `app/page.tsx`: Sucheingabe (`@nexarch/shl` `TextField`), Live-
+  Trefferliste mit `<mark>`-Hervorhebung, verständlicher Hinweis bei
+  leerem Ergebnis, Link je Treffer zur Mail-Detailseite.
+- `app/mail/[messageId]/page.tsx`: öffnet mit Anker `#fundstelle` und
+  hervorgehobenem Snippet aus den Suchtreffer-Daten. Vollständiger
+  Mail-Inhaltsabruf per messageId existiert noch nicht (keine HTTP-API
+  dafür, folgt mit INT-01) — bis dahin trägt der Link Betreff-/Text-
+  Snippet als Kontext mit, damit die Fundstelle bereits jetzt real
+  anspring- und hervorhebbar ist.
+- `lib/contrast.ts`/`lib/highlightColors.ts`: reale WCAG-2.1-
+  Kontrastberechnung statt behaupteter Werte.
+- Kein Umbau: `mail/internal/*`, `web/shl`, `web/retention-admin`
+  unverändert.
+
+## Prüfungen
+
+| # | Prüfung | Ergebnis |
+|---|---|---|
+| 1 | Manueller Test mit typischen Suchanfragen bestätigt korrekte Hervorhebung | **bestanden** – echter `next build` + `next start` auf 192.168.1.131 gegen die live laufende Manticore-Instanz: `GET /api/search?tenant=src04-manual&q=Umsatz` liefert real `"subjectSnippet":"Quartalsbericht ⦃⦃Umsatz⦄⦄"` — Marker um exakt den Suchbegriff. Zusätzlich automatisiert in `app/page.test.tsx` (Marker im DOM nach Suche) |
+| 2 | Barrierefreiheits-Kontrastprüfung der Hervorhebung | **bestanden** – `lib/highlightColors.test.ts`: echte WCAG-2.1-Berechnung, Hell-Modus 14,29:1, Dunkel-Modus 6,43:1 (beide ≥ 4.5:1 AA-Grenzwert für Fließtext) |
+| 3 | Test mit Sonderzeichen in der Suchanfrage bricht die Anzeige nicht | **bestanden** – real gegen den laufenden Server getestet: Anfrage mit `"dritten Quartal" -Verlust <script>` liefert `200 OK` mit `{"hits":[]}`, kein Absturz. Zusätzlich automatisiert `lib/highlight.test.ts` (Skript-Tags/Unicode/unvollständige Marker als reiner Text) und `app/page.test.tsx` (kein `<script>`-Element im DOM, da kein `dangerouslySetInnerHTML`) |
+
+Zusätzlich (Akzeptanzkriterium 2/3, real geprüft): `GET /mail/m-manual-1?subject=...`
+liefert `200 OK`; automatisiert `app/page.test.tsx` bestätigt Link-Struktur
+(`/mail/<id>?...#fundstelle`) und den "Keine Treffer"-Hinweis bei leerem
+Ergebnis.
+
+## Build/Test-Ergebnis (192.168.1.131)
+
+```
+npx tsc --noEmit                              -> clean
+npx next build                                -> Compiled successfully (4 Routen)
+npx vitest run                                -> 3 Testdateien, 12/12 bestanden
+next start (real) + curl gegen Manticore live -> Hervorhebung, leeres Ergebnis,
+                                                   Sonderzeichen alle real bestätigt
+```
+
+Testprozess (`next start -p 4711`) und Testdokument (`mail_documents`-ID
+992001) nach Prüfung entfernt.
+
+## Gesamtergebnis
+
+**Bestanden.** Alle drei Akzeptanzkriterien und alle drei Pflichtprüfungen
+real erfüllt. SRC-04 ist der nächste Schritt in der Suche-Foundation-Kette
+(Index → Befüllung → Such-API → nutzbare Oberfläche), nicht nur eine nette
+Ergänzung — ohne ihn bliebe die Such-API ohne für Anwenderinnen und
+Anwender erreichbaren Zugang. Entsperrt QA-03 (gemeinsam mit SRC-02).

mail/docs/SRC-05-PRUEFPROTOKOLL.md

@@ -0,0 +1,54 @@
+# SRC-05 – Prüfprotokoll: Facetten- & Filter-API
+
+Voraussetzung SRC-03 (Fertig).
+
+## Umsetzung
+
+- `mail/internal/search/migrations/0002..0005_*.sql`: vier eigene,
+  nummerierte `ALTER TABLE ADD COLUMN`-Migrationen für die neuen
+  Facettenfelder (`sender`, `mailbox`, `attachment_type`, `tag`) — Manticore
+  erlaubt nur eine Spalte je ALTER-Anweisung. `EnsureSchema` wendet sie
+  idempotent nach (Fehlertext `"already in schema"` gilt als bereits
+  angewendet, kein Fehlerzustand).
+- `fields.go`: neue statische Feldkonstanten + `FacetFields`-Whitelist
+  (`sender`, `mailbox`, `attachment_type`, `tag`) — einzige Quelle
+  zulässiger Facettendimensionen, kein beliebiger Client-Feldname möglich.
+- `facets.go` — `Client.Facets(ctx, tenantSlug, queryText, filters)`:
+  nutzt Manticores strukturierte `aggs.terms`/`aggs.range`-API (kein
+  dynamischer SQL-Klauselbau). Tenant-Filter + optionale
+  `FacetFilter`-Liste laufen als zusätzliche `equals`-Klauseln in
+  derselben `bool.must`-Liste (Akzeptanzkriterium 2: UND-Verknüpfung).
+  Zeitraum-Facette über feste Buckets (letzte 7 Tage/30 Tage/Jahr/älter)
+  via `aggs.range` auf `sent_at`.
+- `Document` um optionale Facettenfelder erweitert (`Sender`, `Mailbox`,
+  `AttachmentType`, `Tag`).
+- Kein Umbau: `Search`/`Delete`/`Index`-Verhalten aus SRC-01/SRC-03
+  unverändert, `mail/internal/dedup`/`indexworker`/`storage`/`crypto`/
+  `encstorage` unverändert.
+
+## Prüfungen
+
+| # | Prüfung | Ergebnis |
+|---|---|---|
+| 1 | Test: Facettenzahlen stimmen mit tatsächlicher Treffermenge überein | **bestanden** – `TestFacets_CountsMatchActualHits`: 3 reale Dokumente indexiert, Facette `sender` liefert real `alice@example.com`→2, `bob@example.com`→1, Facette `attachment_type` liefert real `pdf`→2 |
+| 2 | Test: Kombination von drei Filtern liefert korrekt eingeschränkte Treffer | **bestanden** – `TestFacets_ThreeFiltersCombineWithAND`: 4 Dokumente, von denen 3 je genau einen der drei Filter (Sender/Postfach/Anhangstyp) verletzen — nach Kombination aller drei Filter bleibt real genau 1 Treffer übrig |
+| 3 | Test: Facetten eines Mandanten enthalten keine Werte eines anderen | **bestanden** – `TestFacets_TenantSeparation`: identische Feldstruktur bei zwei Mandanten, Facette bei Mandant B enthält real keinen Wert von Mandant A |
+
+## Build/Test-Ergebnis (192.168.1.131)
+
+```
+go build ./...  -> clean
+go vet ./...    -> clean
+golangci-lint run ./...  -> 0 issues
+TEST_TENANT_DSN=postgresql://nexarch_test:***@localhost:5432/tenant_acme?sslmode=disable \
+TEST_MANTICORE_URL=http://127.0.0.1:9308 \
+  go test ./... -p 1  -> alle Pakete bestanden, inkl. internal/search (10 Tests,
+  keine Regression in dedup/indexworker/storage/encstorage/example/mimeparse/pflichttestgate)
+```
+
+## Gesamtergebnis
+
+**Bestanden.** Alle drei Akzeptanzkriterien und alle drei Pflichtprüfungen
+real erfüllt. Entsperrt SRC-06, trägt (gemeinsam mit ARC-08, SRC-02,
+SRC-04, SRC-08, SRC-09, SRC-10) zu QA-03 bei — QA-03 bleibt weiterhin
+blockiert, bis auch die übrigen vier Tickets fertig sind.

mail/docs/SRC-06-PRUEFPROTOKOLL.md

@@ -0,0 +1,60 @@
+# SRC-06 – Prüfprotokoll: Facetten-UI & Filter-Chips
+
+Voraussetzung SRC-05 (Fertig), SHL-01 (Core-Board, Fertig).
+
+## Umsetzung
+
+- `web/mail-search/app/api/facets/route.ts`: neue Backend-for-Frontend-
+  Route, spiegelt `mail/internal/search/facets.go` (`Client.Facets`)
+  minimal — nur Trefferzahl je Facettenwert (Akzeptanzkriterium 2), keine
+  Zeitraum-Buckets (nicht Bestandteil dieser Kachel).
+- `web/mail-search/lib/manticoreQuery.ts`: gemeinsamer, statischer
+  `bool.must`-Aufbau für Such- und Facetten-Route (`buildMust`,
+  `parseFilterParams`) — dieselbe Konvention wie
+  `mail/internal/search/facets.go` `buildFilteredMust`, kein
+  Sprintf/Join-artiger Klauselbau.
+- `app/api/search/route.ts` (SRC-04) minimal erweitert: akzeptiert jetzt
+  wiederholbare `?filter=feld:wert`-Parameter, damit Trefferliste und
+  Facettenzählungen bei aktiven Filtern konsistent bleiben.
+- `app/FacetPanel.tsx`: `ActiveFilterChips` (Akzeptanzkriterium 1: aktive
+  Filter als entfernbare Chips, echte `<button>`-Elemente — nativ per
+  Tastatur fokussier-/auslösbar, keine zusätzliche Tastaturbehandlung
+  nötig) + `FacetPanel` (Facettenwerte mit Live-Zählung, Klick fügt
+  Filter hinzu) + „Alle Filter zurücksetzen"-Button (Akzeptanzkriterium
+  3).
+- `app/page.tsx`: Filterzustand ausgelagert nach `lib/filterState.ts`
+  (reine Funktionen, ohne React), jede Filteränderung löst Such- UND
+  Facettenabfrage parallel neu aus (Akzeptanzkriterium 2: live).
+- Kein Umbau: `mail/internal/*`, `web/shl`, `web/retention-admin`
+  unverändert; bestehendes SRC-04-Verhalten (Hervorhebung, leere
+  Ergebnisse, Fundstellen-Link) unverändert, nur um Filter-Parameter
+  erweitert.
+
+## Prüfungen
+
+| # | Prüfung | Ergebnis |
+|---|---|---|
+| 1 | Manueller Test: Filterkombination und Einzelentfernung funktionieren wie erwartet | **bestanden** – echter `next build` + `next start` auf 192.168.1.131 gegen die live laufende Manticore-Instanz: `GET /api/search` + `/api/facets` ohne Filter liefern real 2 Treffer mit Facettenzählungen (`alice`→1, `bob`→1, `inbox`→2 usw.), mit `filter=sender:alice@example.com` liefern beide Routen real konsistent genau 1 Treffer und auf 1 reduzierte Facettenzählungen |
+| 2 | Tastaturbedienbarkeit der Filter-Chips geprüft | **bestanden** – automatisiert mit `@testing-library/user-event` (echte Tastatursimulation, kein bloßer Klick): Chip fokussieren (`Tab`-Ziel), `{Enter}` löst real dieselbe Entfernung wie ein Klick aus |
+| 3 | Test mit vielen aktiven Filtern bleibt die Ansicht übersichtlich | **bestanden** – 20 gleichzeitig aktivierte Filter real erzeugen real 20 einzeln erkennbare, nicht zusammengefasste Chips im DOM, kein Absturz, `flexWrap` verhindert horizontales Überlaufen |
+
+## Build/Test-Ergebnis (192.168.1.131)
+
+```
+npx tsc --noEmit                              -> clean
+npx next build                                -> Compiled successfully (5 Routen)
+npx vitest run                                -> 4 Testdateien, 19/19 bestanden (8 in app/page.test.tsx,
+                                                   davon 4 neu für SRC-06)
+next start (real) + curl gegen Manticore live -> Filterkombination, Facettenzählungen, Einschränkung
+                                                   auf 1 Treffer alle real bestätigt
+```
+
+Testprozess (`next start -p 4712`) und Testdokumente
+(`mail_documents`-IDs 993001/993002) nach Prüfung entfernt.
+
+## Gesamtergebnis
+
+**Bestanden.** Alle drei Akzeptanzkriterien und alle drei Pflichtprüfungen
+real erfüllt. Entsperrt (gemeinsam mit den übrigen QA-09-Abhängigkeiten)
+einen Teil des Wegs zu QA-09 — QA-09 bleibt weiterhin blockiert (QA-02,
+QA-04..QA-08 noch offen).

mail/docs/SRC-07-PRUEFPROTOKOLL.md

@@ -0,0 +1,69 @@
+# SRC-07 – Prüfprotokoll: OCR für Anhänge
+
+Voraussetzung ARC-01, ARC-03 (beide Fertig). SRC-07 ist die direkte
+Vorbedingung für SRC-10 (Spracherkennung & OCR-Qualitätsbewertung), nicht
+nur eine nette Ergänzung — ohne SRC-07 gibt es keinen erkannten Text, den
+SRC-10 mit Sprache/Konfidenz bewerten könnte.
+
+## Umsetzung
+
+- `mail/internal/ocr/ocr.go` — zustandsloses Paket, kennt weder Mandant
+  noch Speicher (dieselbe Bauart wie `mail/internal/crypto`/`dedup`):
+  nimmt Anhangs-Bytes entgegen, liefert erkannten Text zurück. Kein
+  geteilter Zustand zwischen Aufrufen (jeder Aufruf bekommt ein eigenes
+  Temp-Verzeichnis) — Tenant-Trennung ist dadurch strukturell gegeben,
+  nicht nur konventionell: ein Mandant kann prinzipbedingt nie Zwischen-
+  daten eines anderen sehen. Zuordnung des erkannten Textes zum
+  Mail-Suchdokument (Akzeptanzkriterium 2) erfolgt beim Aufrufer über das
+  bereits vorhandene `search.Document.AttachmentText`-Feld (SRC-01) — kein
+  neues Feld nötig.
+  - `ExtractTextFromImage`: ruft `tesseract` (Sprachen `deu+eng`) mit
+    fester Argumentliste auf, kein Shell-String-Zusammenbau.
+  - `HasTextLayer`/`ExtractTextFromPDF`: nutzt `pdftotext`, um eine
+    vorhandene Textebene zu erkennen und direkt zu übernehmen
+    (Akzeptanzkriterium 3) — nur wenn keine Textebene vorhanden ist
+    (< 10 Zeichen), wird über `pdftoppm` (300dpi) jede Seite gerastert und
+    per Tesseract erkannt (Akzeptanzkriterium 1).
+- Bekannten Fehler vermieden (dupliziertes Sprintf-WHERE-Muster aus
+  archivmail, siehe repos-analyse-mail-reuse.md): dieses Paket baut keine
+  SQL-Klauseln — ausschließlich externe Kommandozeilenwerkzeuge mit
+  festen Argumentlisten (`exec.CommandContext`, keine Shell).
+- Kein Umbau: `mail/internal/search`/`dedup`/`indexworker`/`storage`/
+  `crypto`/`encstorage`/`savedsearch` unverändert.
+
+## Prüfungen
+
+| # | Prüfung | Ergebnis |
+|---|---|---|
+| 1 | Test: Bildanhang mit bekanntem Text liefert erwartete Texterkennung | **bestanden** – `TestExtractTextFromImage_KnownTextRecognized`: reales, über `pdftoppm` gerastertes Bild mit dem Text "Rechnungsnummer 4711", `ExtractTextFromImage` erkennt real beide Wortbestandteile |
+| 2 | Test: PDF mit vorhandener Textebene wird korrekt übersprungen | **bestanden** – `TestExtractTextFromPDF_SkipsOCRWhenTextLayerPresent`: real erzeugtes Vektor-Text-PDF (echte PDF-Textebene, kein Bild), `ExtractTextFromPDF` liefert `OCRPerformed=false` und den Text direkt aus der Textebene |
+| 3 | Durchsatztest bestätigt akzeptable Verarbeitungszeit je Anhang | **bestanden** – `TestExtractTextFromPDF_ThroughputIsAcceptable`: 3 reale Anhänge (Rasterung 300dpi + OCR) in durchschnittlich 3,48s/Anhang (Ziel 8s/Anhang) |
+
+Zusätzlich (Akzeptanzkriterium 1, gescannte PDFs end-zu-Ende):
+`TestExtractTextFromPDF_PerformsOCRWhenNoTextLayer` — ein reales,
+ausschließlich rasterbildbasiertes PDF (kein Textelement, JPEG-Bild via
+`/DCTDecode` eingebettet) wird real per OCR erkannt, `OCRPerformed=true`.
+
+Testfixtures (`testpdf_test.go`) werden vollständig in Go erzeugt (Hand-
+gebautes PDF mit Helvetica-Textebene bzw. eingebettetem JPEG) — keine
+externe Bibliothek, keine Testdateien im Repository, reproduzierbar.
+
+## Build/Test-Ergebnis (192.168.1.131)
+
+```
+go build ./...  -> clean
+go vet ./...    -> clean
+golangci-lint run ./...  -> 0 issues
+go test ./internal/ocr/... -v  -> 4/4 bestanden (14,99s gesamt)
+TEST_TENANT_DSN=... TEST_MANTICORE_URL=... go test ./... -p 1
+  -> alle Pakete bestanden, keine Regression
+```
+
+Werkzeugversionen auf 192.168.1.131: `tesseract 5.5.0` (Sprachpakete
+`deu`, `eng`), `pdftotext`/`pdftoppm` (poppler-utils) — bereits vorhanden,
+keine Installation durch diese Sitzung nötig.
+
+## Gesamtergebnis
+
+**Bestanden.** Alle drei Akzeptanzkriterien und alle drei Pflichtprüfungen
+real erfüllt. Entsperrt SRC-10.

mail/docs/SRC-08-PRUEFPROTOKOLL.md

@@ -0,0 +1,59 @@
+# SRC-08 – Prüfprotokoll: Gespeicherte Suchanfragen
+
+Voraussetzung SRC-03 (Fertig).
+
+## Umsetzung
+
+- `mail/internal/savedsearch/store.go` — `Store` (Postgres,
+  `mail_saved_searches`): `Save` (Upsert über `UNIQUE(tenant_slug,
+  user_id, name)`, Akzeptanzkriterium 1), `List`/`Get` streng auf
+  Mandant UND Benutzer beschränkt (Akzeptanzkriterium 3), `Delete`
+  löscht genau eine Zeile über `tenant_slug + user_id + id`.
+  „Benutzer" ist bis zu einer zentralen Session-/IAM-Anbindung
+  (Core-Board-Scope) ein vom Aufrufer mitgegebener opaker
+  `userID`-String — dieselbe Konvention wie der Tenant-Kontext in
+  `web/mail-search` (SRC-04).
+- `Execute(ctx, client, saved)` führt die gespeicherte Suche LIVE gegen
+  `search.Client` aus — speichert selbst keine Treffer, jeder Aufruf
+  fragt Manticore neu ab (Akzeptanzkriterium 2).
+- `mail/internal/search/facets.go` — kleinste nötige Erweiterung: neue
+  Methode `Client.SearchWithFilters` (gemeinsame `buildFilteredMust`-
+  Hilfsfunktion mit `Facets` extrahiert) liefert TATSÄCHLICH gefilterte
+  Treffer statt nur Facettenzählungen — ohne dies gäbe es keinen echten
+  Weg, gespeicherte Filter beim Wiederausführen anzuwenden.
+- Kein Umbau: `Search`/`Facets`/`Index`/`Delete`-Verhalten sonst
+  unverändert, `mail/internal/dedup`/`indexworker`/`storage`/`crypto`/
+  `encstorage` unverändert.
+
+## Prüfungen
+
+| # | Prüfung | Ergebnis |
+|---|---|---|
+| 1 | Test: gespeicherte Suche mit mehreren Filtern wird korrekt reproduziert | **bestanden** – `TestExecute_SavedSearchWithMultipleFiltersReproducesCorrectly`: 3 Dokumente, 2 Filter (Sender+Postfach) gespeichert, `Execute` liefert real genau das eine Dokument, das beide Filter erfüllt |
+| 2 | Test: Benutzer sieht keine gespeicherten Suchen anderer Mandanten | **bestanden** – `TestList_UserSeesNoOtherTenantsSavedSearches`: zwei Mandanten mit je einer gespeicherten Suche, `List` bei Mandant B liefert real nur die eigene, nicht die von Mandant A |
+| 3 | Test: Löschen einer gespeicherten Suche entfernt nur diese | **bestanden** – `TestDelete_RemovesOnlyThatSavedSearch`: zwei gespeicherte Suchen, eine gelöscht, `Get` liefert für die gelöschte real `ErrNotFound`, die andere bleibt real unverändert abrufbar |
+
+Zusätzlich (Akzeptanzkriterium 2, kein eingefrorener Snapshot):
+`TestExecute_ReturnsCurrentResultsNotFrozenSnapshot` — Ausführung vor
+einer neuen Indexierung liefert real 0 Treffer, danach real 1 Treffer,
+ohne dass die gespeicherte Suche selbst verändert wurde.
+
+## Build/Test-Ergebnis (192.168.1.131)
+
+```
+go build ./...  -> clean
+go vet ./...    -> clean
+golangci-lint run ./...  -> 0 issues
+TEST_TENANT_DSN=postgresql://nexarch_test:***@localhost:5432/tenant_acme?sslmode=disable \
+TEST_MANTICORE_URL=http://127.0.0.1:9308 \
+  go test ./... -p 1  -> alle Pakete bestanden, inkl. internal/savedsearch (4 Tests, neu),
+  keine Regression in dedup/indexworker/storage/encstorage/example/mimeparse/pflichttestgate/
+  crypto/search
+```
+
+## Gesamtergebnis
+
+**Bestanden.** Alle drei Akzeptanzkriterien und alle drei Pflichtprüfungen
+real erfüllt. Trägt (gemeinsam mit ARC-08, SRC-02, SRC-04, SRC-05,
+SRC-09) zu QA-03 bei — QA-03 bleibt weiterhin blockiert, bis auch
+SRC-10 fertig ist.

mail/docs/SRC-09-PRUEFPROTOKOLL.md

@@ -0,0 +1,72 @@
+# SRC-09 – Prüfprotokoll: Suchindex-Neuaufbau/Reindexierung
+
+Voraussetzung SRC-01 (Fertig).
+
+## Umsetzung
+
+- `mail/internal/search/reindex.go` — `Reindexer.Rebuild(ctx, onProgress)`:
+  1. legt eine neue physische Manticore-Tabelle an (Name aus striktem
+     Muster `mail_documents_reindex_<Ziffern>`, per Regex validiert —
+     Verteidigung in der Tiefe, obwohl der Wert ausschließlich
+     paketintern erzeugt wird),
+  2. kopiert alle Dokumente aus der lebenden Tabelle seitenweise
+     (Cursor-Paginierung über `id`, strukturierte JSON-API, kein
+     dynamischer SQL-Klauselbau) — die lebende Tabelle wird dabei nur
+     gelesen, nie verändert (Akzeptanzkriterium 1),
+  3. meldet Fortschritt über einen `onProgress`-Callback
+     (Akzeptanzkriterium 2),
+  4. vergleicht Trefferzahlen alt/neu — bei Abweichung kein Umschalten,
+  5. schaltet erst danach per Manticore `ALTER TABLE ... RENAME`
+     (reine Metadaten-Operation) atomar um. Schlägt ein Schritt vor dem
+     Umschalten fehl, wird die Zwischentabelle entfernt, die lebende
+     Tabelle bleibt unverändert (Akzeptanzkriterium 3 / Pflichtprüfung 2).
+- Echtes Manticore-Verhalten entdeckt und behandelt: frisch eingefügte
+  Dokumente einer neu angelegten RT-Tabelle sind für `match_all`-Zählungen
+  erst nach explizitem `FLUSH RAMCHUNK` zuverlässig sichtbar (SQL-`SELECT`
+  sah sie sofort, `/search`-Zählung zeigte 0) — vor der
+  Konsistenzprüfung eingebaut.
+- Echte Plattformgrenze gefunden und abgefangen: Manticore unterstützt kein
+  atomares Mehrfach-`RENAME` in einer Anweisung — zwischen den zwei
+  nötigen Einzel-`RENAME`s existiert ein Sub-Millisekunden-Fenster ohne
+  `mail_documents`-Tabelle. `Client.Search` bekam dafür einen begrenzten
+  Retry (bis zu 2 Wiederholungen, 20ms Pause) speziell auf den
+  Manticore-Fehler `"unknown local table"` — real durch eine parallele
+  Suchlast während des Umschaltens nachgewiesen (Pflichtprüfung 1).
+- Nebenbei einen echten, latenten Fehler in `Search` gefunden und behoben:
+  ohne explizites `limit` begrenzte Manticore Ergebnisse standardmäßig auf
+  20 Treffer — unbemerkt, weil bisherige Tests (SRC-01/03/05) nur auf das
+  Vorhandensein einzelner Treffer prüften, nie auf die Gesamtzahl. Jetzt
+  `searchResultLimit = 1000`.
+- Kein Umbau: `Index`/`Delete`/`Facets`-Verhalten sonst unverändert,
+  `mail/internal/dedup`/`indexworker`/`storage`/`crypto`/`encstorage`
+  unverändert.
+
+## Prüfungen
+
+| # | Prüfung | Ergebnis |
+|---|---|---|
+| 1 | Test: Reindex während laufender Suchanfragen unterbricht die Suche nicht | **bestanden** – `TestRebuild_SearchKeepsWorkingDuringReindex`: 30 reale Dokumente indexiert, parallele Sucher-Goroutine (alle 2ms) läuft während `Rebuild` mit — 0 fehlgeschlagene Suchen über den gesamten Umschaltvorgang, danach weiterhin real alle 30 Treffer auffindbar |
+| 2 | Test: abgebrochener Reindex hinterlässt keinen inkonsistenten Zustand | **bestanden** – `TestRebuild_AbortedReindexLeavesNoInconsistentState`: Kontext vor `Rebuild` abgebrochen, Fehler kommt real zurück, lebende Tabelle bleibt danach unverändert (weiterhin 1 Treffer real auffindbar), keine verwaisten Zwischentabellen über `SHOW TABLES` real bestätigt |
+| 3 | Stichprobenvergleich Alt-/Neuindex bestätigt gleiche Trefferzahlen | **bestanden** – `TestRebuild_SampleComparisonMatchesOldAndNewIndex`: 3 unterschiedliche Suchbegriffe vor und nach Reindex real verglichen, identische Trefferzahlen je Stichprobe |
+
+Zusätzlich (Akzeptanzkriterium 2): `TestRebuild_ReportsProgress` bestätigt
+reale Fortschrittsmeldungen bis zum vollständigen Abschluss.
+
+## Build/Test-Ergebnis (192.168.1.131)
+
+```
+go build ./...  -> clean
+go vet ./...    -> clean
+golangci-lint run ./...  -> 0 issues
+TEST_TENANT_DSN=postgresql://nexarch_test:***@localhost:5432/tenant_acme?sslmode=disable \
+TEST_MANTICORE_URL=http://127.0.0.1:9308 \
+  go test ./... -v -p 1  -> alle Pakete bestanden, inkl. internal/search (14 Tests,
+  keine Regression in dedup/indexworker/storage/encstorage/example/mimeparse/pflichttestgate)
+```
+
+## Gesamtergebnis
+
+**Bestanden.** Alle drei Akzeptanzkriterien und alle drei Pflichtprüfungen
+real erfüllt. Trägt (gemeinsam mit ARC-08, SRC-02, SRC-04, SRC-05,
+SRC-08, SRC-10) zu QA-03 bei — QA-03 bleibt weiterhin blockiert, bis auch
+ARC-08, SRC-08 und SRC-10 fertig sind.

mail/docs/SRC-10-PRUEFPROTOKOLL.md

@@ -0,0 +1,57 @@
+# SRC-10 – Prüfprotokoll: Spracherkennung & OCR-Qualitätsbewertung
+
+Voraussetzung SRC-07 (Fertig).
+
+## Umsetzung
+
+- `mail/internal/ocr/language.go` — `RecognizeWithLanguageAndConfidence`:
+  Tesseract erkennt bei kombinierten Sprachpaketen (`deu+eng`) nicht,
+  WELCHE Sprache vorlag — daher wird das Bild bewusst EINZELN mit jedem
+  Kandidaten (`deu`, `eng`) im TSV-Ausgabemodus erkannt; die Sprache mit
+  dem höheren durchschnittlichen Worterkennungs-Konfidenzwert gewinnt
+  (Akzeptanzkriterium 1). Derselbe Tesseract-TSV-Lauf liefert den
+  Konfidenzwert direkt mit (Akzeptanzkriterium 2, 0–100, Mittelwert über
+  alle erkannten Wörter) — keine zweite externe Bibliothek nötig.
+- `mail/internal/search`: neue Felder `ocr_language`/`ocr_confidence`
+  (Migrationen 0006/0007, gleiches ALTER-Muster wie SRC-05), in
+  `Document`/`Result` gespiegelt (Akzeptanzkriterium 1: für Anzeige
+  nutzbar). Neue Methode `Client.AttachmentsBelowConfidence(ctx,
+  tenantSlug, threshold)` (Akzeptanzkriterium 3: gezielt für manuelle
+  Nachbearbeitung auffindbar) — filtert `ocr_confidence < threshold`,
+  schließt Dokumente ohne OCR-Anhang (`ocr_confidence` bleibt 0) explizit
+  aus.
+- Echten Regressionsbug beim eigenen Testlauf gefunden und behoben:
+  `reindex.go`s `buildCreateTableSQL` (SRC-09) kannte die neuen
+  OCR-Spalten nicht — ein Reindex nach dieser Kachel wäre mit "unknown
+  column" fehlgeschlagen. Jetzt ergänzt, mit Wartungshinweis im
+  Quelltext für künftige Schema-Erweiterungen.
+- Kein Umbau: `Search`/`Facets`/`SearchWithFilters`/`Index`/`Delete`-
+  Verhalten sonst unverändert, `mail/internal/dedup`/`indexworker`/
+  `storage`/`crypto`/`encstorage`/`savedsearch` unverändert.
+
+## Prüfungen
+
+| # | Prüfung | Ergebnis |
+|---|---|---|
+| 1 | Test mit mehrsprachigem Testkorpus bestätigt korrekte Spracherkennung | **bestanden** – `TestRecognizeWithLanguageAndConfidence_MultilingualCorpus`: reales deutsches Testbild ("Rechnung ueber Lieferung...") real als `deu` erkannt, reales englisches Testbild ("Invoice for delivery...") real als `eng` erkannt |
+| 2 | Test: künstlich verschlechtertes Bild erzeugt niedrigeren Konfidenzwert | **bestanden** – `TestRecognizeWithLanguageAndConfidence_DegradedImageLowersConfidence`: reproduzierbare Pixelierung + Kontrastreduktion (reiner Go-Standardbibliothekscode, kein externes Werkzeug) senkt den real gemessenen Konfidenzwert von 91,76 auf 28,21 |
+| 3 | Abfrage aller Anhänge unterhalb einer Konfidenzschwelle liefert erwartete Treffer | **bestanden** – `TestAttachmentsBelowConfidence_QueryReturnsExpectedResults`: 4 Dokumente (2 niedrig-, 1 hoch-konfident, 1 ohne OCR-Anhang), Abfrage mit Schwelle 50 liefert real genau die 2 niedrig-konfidenten, weder den hoch-konfidenten noch den ohne OCR-Anhang |
+
+## Build/Test-Ergebnis (192.168.1.131)
+
+```
+go build ./...  -> clean
+go vet ./...    -> clean
+golangci-lint run ./...  -> 0 issues
+go test ./internal/ocr/... -v -run 'Language|Degraded'  -> 2/2 bestanden
+TEST_TENANT_DSN=... TEST_MANTICORE_URL=... go test ./... -p 1
+  -> alle Pakete bestanden (Regressionsbug in reindex.go vor diesem
+  Protokoll gefunden und behoben, danach vollständig grün)
+```
+
+## Gesamtergebnis
+
+**Bestanden.** Alle drei Akzeptanzkriterien und alle drei Pflichtprüfungen
+real erfüllt. Entsperrt QA-03 (gemeinsam mit ARC-08, SRC-02, SRC-04,
+SRC-05, SRC-08, SRC-09 — alle jetzt Fertig, letzte fehlende
+Abhängigkeit).

mail/docs/TESTSTRATEGIE-MAIL.md

@@ -0,0 +1,110 @@
+# NEXARCH Mail – Teststrategie
+
+Stand: 2026-08-30. Ticket: QA-01. Vorbild: Core `QA-01` (`docs/TESTSTRATEGIE-CORE.md`,
+Fertig) — dieselbe Struktur, für das Mail-Modul übernommen, wo sinnvoll um
+protokollspezifische Aspekte (IMAP/SMTP/MIME) ergänzt.
+
+## 1. Warum dieses Dokument existiert
+
+archivmail (Vorgängerprojekt) testete 2 von 18 Modulen trotz hoher Kritikalität
+(Compliance-/Protokoll-Logik). Kein zentrales Issue-Tracking — Bugs wurden nur als
+`BUG-N`-Kommentare im Code festgehalten (`known-issues-archivmail.md`). NEXARCH Mail
+übernimmt denselben Grundsatz wie Core: **Testpflicht für Auth, Tenant-Scoping und
+Protokoll-/Compliance-kritische Logik ist ein Merge-Gate, keine Nachrüstung.**
+
+## 2. Testpyramide
+
+| Ebene | Werkzeug | Umfang |
+|---|---|---|
+| Unit | `go test` (Standardbibliothek) | Einzelne Funktionen/Typen, keine externe Abhängigkeit (DB, Netzwerk, IMAP/SMTP-Socket) |
+| Integration | `go test` gegen echte PostgreSQL-Instanz (`nexarch_test`-Rolle) | Repository-/Handler-Schicht, Tenant-Scoping, Objekt-Speicher |
+| Protokoll-Zustandsmaschinen | `go test` gegen echten IMAP-/SMTP-Client-Roundtrip (kein reiner Parser-Unit-Test) | ING-01/ING-02/ING-03: Login-Zustände, Befehlssequenzen, Fehlerpfade |
+| E2E | Echter HTTP-Roundtrip (`httptest.Server`) bis zum ersten Mail-Frontend-Ticket, danach Playwright/Jest gegen die echte UI | Vollständiger Request-Response-Zyklus, kein reiner Funktionsaufruf |
+| Vertragstests | Analog Core `QA-07`/DMS-Äquivalent, sobald Mail öffentliche Modul-Adapter-Schnittstellen (RET-05-Konsument, siehe `ARC-11`) hat | Wire-Contract-Stabilität |
+
+**E2E-Zwischenlösung begründet:** Mail hat aktuell kein Frontend-Ticket (0/66 Board).
+Playwright/Jest bräuchte eine echte Browser-UI zum Testen — bis zum ersten
+Mail-Frontend-Ticket ist ein echter HTTP-Roundtrip (kein reiner In-Process-Funktionsaufruf)
+die ehrliche, tatsächlich verfügbare Untergrenze für "E2E". Siehe Beispiel in
+Abschnitt 3.
+
+## 3. Beispieltests je Testart (Akzeptanzkriterium/Pflichtprüfung 2)
+
+`mail/internal/example` — kein Wegwerf-Demo, sondern eine kleine, tatsächlich nützliche
+Funktion (E-Mail-Adress-Normalisierung), die spätere Ticket ohnehin brauchen:
+
+- **Unit:** `normalize_test.go` — `TestNormalizeAddress_*`, keine externe Abhängigkeit.
+- **Integration:** `store_integration_test.go` — `TestAddressStore_SaveAndCheckExists`,
+  echte Postgres-Instanz, `TEST_TENANT_DSN`, `t.Cleanup`.
+- **E2E:** `handler_e2e_test.go` — `TestNormalizeHandler_RealHTTPRoundTrip`, echter
+  `httptest.Server`-Roundtrip (TCP, nicht nur Funktionsaufruf).
+
+Alle sechs Tests real ausgeführt (siehe Prüfungen, Abschnitt 6).
+
+## 4. Pflichttests als Merge-Gate (Akzeptanzkriterium 3/4)
+
+Verbindlich für jeden Pull Request, der Dateien in einem der folgenden Bereiche ändert:
+
+- **Auth** (`mail/internal/auth/` — sobald durch ein späteres Ticket angelegt)
+- **Tenant-Scoping** (`mail/internal/tenant/`, jede Repository-Schicht mit Mandanten-Bezug)
+- **Protokoll-kritisch** (`mail/internal/ingest/`, `mail/internal/imap/`,
+  `mail/internal/smtp/` — Zustandsmaschinen, Auth-Handshakes der Protokolle selbst)
+- **Compliance-kritisch** (`mail/internal/arc/` oder gleichwertig — RET-05-Konsument,
+  Löschung/Archivierung, siehe `ARC-11`)
+
+Regel (identisch zu Core `QA-01`): **jede geänderte `.go`-Datei in einem dieser
+Bereiche muss von einer geänderten oder neuen `_test.go`-Datei im selben Package
+begleitet sein.**
+
+`mail/internal/pflichttestgate` implementiert das Gate (Code-Kopie des Musters aus
+Core `internal/pflichttestgate`, mit mail-spezifischen Pfadmustern statt Core-Pfaden
+— bewusst keine Cross-Modul-Abhängigkeit, da Mail als eigenständiges Go-Modul Core
+nicht importieren kann). `.gitea/workflows/mail-pflichttest-gate.yml` führt es gegen
+jeden PR-Diff aus.
+
+Negativtest des Gates selbst (Prüfung 1 dieses Tickets):
+`mail/internal/pflichttestgate/gate_test.go` simuliert einen Diff mit geänderter
+`mail/internal/auth/login.go` ohne begleitende Testdatei und erwartet, dass das Gate
+das als Verstoß erkennt.
+
+## 5. Bug-Tracking (Akzeptanzkriterium 3)
+
+**Konvention: Gitea-Issues** auf `gitea.perlbach24.de/scripte/nexarch`, Label `mail`
+plus Schweregrad-Label (`bug-kritisch`/`bug-normal`/`bug-kosmetisch`). Durchsuchbar
+über Gitea-Suche/Label-Filter — explizit KEIN Code-Kommentar-Tracking (`BUG-N` wie in
+archivmail), das laut `known-issues-archivmail.md` genau diese Sichtbarkeitslücke
+verursacht hat.
+
+**Realer Durchspiel-Nachweis (Prüfung 3):** Diese Session (nicht Mail-spezifisch, aber
+derselbe reale Vorgang) fand mehrere echte Bugs, dokumentiert nach exakt diesem
+Muster in den jeweiligen `*-PRUEFPROTOKOLL.md`-Dateien statt als Code-Kommentar, z. B.
+`archive/docs/RET-10-PRUEFPROTOKOLL.md`: fehlende CORS-Header bei RET-06-API,
+gefunden bei einer Sichtprüfung, Symptom (Browser hätte Fetch blockiert), Ursache
+(kein `Access-Control-Allow-Origin`), Fix (RET-10-Ticket), Nachweis (curl-Test vorher/
+nachher) — alles durchsuchbar in der Protokolldatei, nicht im Quelltext verstreut.
+
+**Ehrlich vermerkt:** Ein ECHTER Gitea-Issue konnte in dieser Session nicht angelegt
+werden (kein Gitea-API-Token verfügbar, nur Git-SSH/HTTPS-Push-Zugriff). Das oben
+verlinkte Beispiel demonstriert das Vorgehen strukturell (Symptom → Ursache → Fix →
+Nachweis, durchsuchbar abgelegt), aber NICHT über die Gitea-Issue-Oberfläche selbst.
+Sobald ein Gitea-Zugriffstoken verfügbar ist, sollte mindestens ein Test-Issue real
+angelegt werden, um die Konvention vollständig nachzuweisen — offener Punkt, siehe
+Abschnitt 7.
+
+## 6. Prüfungen (real durchgeführt)
+
+| # | Prüfung | Ergebnis |
+|---|---|---|
+| 1 | Dokument liegt vor und wurde von zweiter Person gegengelesen | **bestanden** — Dokument von der Nutzerin/dem Nutzer (zweite Person) gegengelesen und freigegeben (2026-08-30) |
+| 2 | Stichprobe: mindestens ein Beispieltest je benannter Testart ist umgesetzt | **bestanden** — 6 Tests real ausgeführt auf 131: `go test ./mail/internal/example/... -v -p 1`, alle grün (3 Unit, 1 Integration, 2 E2E) |
+| 3 | Bug-Tracking-Vorgehen wurde einmal exemplarisch für einen realen Befund durchgespielt | **teilweise bestanden** — Vorgehen strukturell durchgespielt anhand eines realen, bereits dokumentierten Befunds (RET-10), aber NICHT über die echte Gitea-Issue-Oberfläche (kein API-Token verfügbar). Siehe Abschnitt 5, offener Punkt in Abschnitt 7 |
+
+## 7. Offene Punkte
+
+- Echter Gitea-Issue als Nachweis der Bug-Tracking-Konvention noch nicht angelegt
+  (fehlendes API-Token in dieser Session). Sollte nachgeholt werden, sobald Zugriff
+  besteht.
+- `mail/internal/auth/`, `mail/internal/tenant/`, `mail/internal/ingest/` etc. existieren
+  noch nicht — die Pflichttest-Gate-Pfadmuster sind auf Basis der geplanten
+  Modulstruktur vordefiniert, nicht an echtem Code verifiziert. Erste Nagelprobe: das
+  erste Ticket, das einen dieser Pfade tatsächlich anlegt (voraussichtlich `ING-01`).

mail/go.mod

@@ -1,4 +1,4 @@
-module gitea.perlbach24.de/scripte/nexarch/dms
+module gitea.perlbach24.de/scripte/nexarch/mail
 
 go 1.24
 
@@ -11,6 +11,7 @@ require (
 	github.com/aws/aws-sdk-go-v2/service/s3 v1.109.1
 	github.com/aws/smithy-go v1.28.1
 	github.com/jackc/pgx/v5 v5.6.0
+	golang.org/x/text v0.14.0
 )
 
 require (
@@ -27,10 +28,11 @@ require (
 	github.com/aws/aws-sdk-go-v2/service/sso v1.35.1 // indirect
 	github.com/aws/aws-sdk-go-v2/service/ssooidc v1.40.1 // indirect
 	github.com/aws/aws-sdk-go-v2/service/sts v1.47.1 // indirect
+	github.com/fsnotify/fsnotify v1.10.1 // indirect
 	github.com/jackc/pgpassfile v1.0.0 // indirect
 	github.com/jackc/pgservicefile v0.0.0-20221227161230-091c0ba34f0a // indirect
 	github.com/jackc/puddle/v2 v2.2.1 // indirect
 	golang.org/x/crypto v0.17.0 // indirect
 	golang.org/x/sync v0.1.0 // indirect
-	golang.org/x/text v0.14.0 // indirect
+	golang.org/x/sys v0.15.0 // indirect
 )

mail/go.sum

@@ -37,6 +37,8 @@ github.com/aws/smithy-go v1.28.1/go.mod h1:YE2RhdIuDbA5E5bTdciG9KrW3+TiEONeUWCqx
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/fsnotify/fsnotify v1.10.1 h1:b0/UzAf9yR5rhf3RPm9gf3ehBPpf0oZKIjtpKrx59Ho=
+github.com/fsnotify/fsnotify v1.10.1/go.mod h1:TLheqan6HD6GBK6PrDWyDPBaEV8LspOxvPSjC+bVfgo=
 github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsIM=
 github.com/jackc/pgpassfile v1.0.0/go.mod h1:CEx0iS5ambNFdcRtxPj5JhEz+xB6uRky5eyVu/W2HEg=
 github.com/jackc/pgservicefile v0.0.0-20221227161230-091c0ba34f0a h1:bbPeKD0xmW/Y25WS6cokEszi5g+S0QxI/d45PkRi7Nk=
@@ -56,6 +58,8 @@ golang.org/x/crypto v0.17.0 h1:r8bRNjWL3GshPW3gkd+RpvzWrZAwPS49OmTGZ/uhM4k=
 golang.org/x/crypto v0.17.0/go.mod h1:gCAAfMLgwOJRpTjQ2zCCt2OcSfYMTeZVSRtQlPC7Nq4=
 golang.org/x/sync v0.1.0 h1:wsuoTGHzEhffawBOhz5CYhcrV4IdKZbEyZjBMuTp12o=
 golang.org/x/sync v0.1.0/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sys v0.15.0 h1:h48lPFYpsTvQJZF4EKyI4aLHaev3CxivZmv7yZig9pc=
+golang.org/x/sys v0.15.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
 golang.org/x/text v0.14.0 h1:ScX5w1eTa3QqT8oi6+ziP7dTV1S2+ALU0bI+0zXKWiQ=
 golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=

mail/internal/attachments/attachments.go

@@ -0,0 +1,109 @@
+// Package attachments implementiert IMP-02: Anhänge aus importierten
+// Nachrichten extrahieren, validieren und für die Weiterverarbeitung
+// (Speicherung, Virenscan — beides spätere Kacheln, siehe "Nicht
+// Bestandteil dieser Kachel") bereitstellen. Baut auf ING-04
+// (mail/internal/mimeparse) auf, unverändert wiederverwendet über die
+// additive Erweiterung mimeparse.ParseTolerant — kein Umbau der
+// bestehenden, fertigen ING-04-Logik.
+package attachments
+
+import (
+	"io"
+	"net/http"
+
+	"gitea.perlbach24.de/scripte/nexarch/mail/internal/mimeparse"
+)
+
+// Attachment ist EIN extrahierter, validierter Anhang
+// (Akzeptanzkriterium 1: Originaldateiname, Größe, geprüfter
+// Content-Type).
+type Attachment struct {
+	Filename string
+	Size     int64
+	Content  []byte
+	// DeclaredContentType kommt unverändert aus dem MIME-Header des
+	// Absenders — NICHT vertrauenswürdig, ein Absender kann hier
+	// beliebiges behaupten.
+	DeclaredContentType string
+	// VerifiedContentType wird aus den tatsächlichen Bytes gesniffed
+	// (net/http.DetectContentType, RFC-basierte Inhaltserkennung) —
+	// Akzeptanzkriterium 1: "geprüfter Content-Type", unabhängig von der
+	// Absenderbehauptung.
+	VerifiedContentType string
+}
+
+// SkippedPart beschreibt einen Anhang/Teil, der NICHT extrahiert werden
+// konnte — der Rest der Nachricht (Text und übrige Anhänge) bleibt davon
+// unangetastet (Akzeptanzkriterium 3).
+type SkippedPart struct {
+	Filename string
+	Reason   error
+}
+
+// Result ist das Ergebnis einer Anhangsextraktion.
+type Result struct {
+	Attachments []Attachment
+	// TextParts sind die Nicht-Anhang-Teile (Nachrichtentext) —
+	// unverändert aus mimeparse übernommen, diese Kachel fasst sie nicht
+	// an.
+	TextParts []mimeparse.Part
+	Skipped   []SkippedPart
+}
+
+// DefaultMaxAttachmentSize/DefaultMaxMessageSize sind Vorgabewerte,
+// überschreibbar über Options — großzügig für typische Geschäftspost
+// (kleinste Lösung, keine Konfigurationsoberfläche in dieser Kachel).
+const (
+	DefaultMaxAttachmentSize = 25 * 1024 * 1024  // 25 MiB je Anhang
+	DefaultMaxMessageSize    = 100 * 1024 * 1024 // 100 MiB je Nachricht gesamt
+)
+
+// Options steuert die Größenlimits (Akzeptanzkriterium 2).
+type Options struct {
+	MaxAttachmentSize int64
+	MaxMessageSize    int64
+}
+
+func (o Options) withDefaults() Options {
+	if o.MaxAttachmentSize <= 0 {
+		o.MaxAttachmentSize = DefaultMaxAttachmentSize
+	}
+	if o.MaxMessageSize <= 0 {
+		o.MaxMessageSize = DefaultMaxMessageSize
+	}
+	return o
+}
+
+// Extract zerlegt eine E-Mail (RFC 5322 + MIME) in Anhänge und
+// Textteile. Ein einzelner fehlerhafter oder überdimensionierter Anhang
+// blockiert NICHT die Verarbeitung der übrigen Teile
+// (Akzeptanzkriterium 3) — nur eine strukturell unlesbare Nachricht
+// (kaputte Kopfzeilen) liefert einen echten Fehler.
+func Extract(r io.Reader, opts Options) (Result, error) {
+	opts = opts.withDefaults()
+
+	msg, partErrors, err := mimeparse.ParseTolerant(r, opts.MaxAttachmentSize, opts.MaxMessageSize)
+	if err != nil {
+		return Result{}, err
+	}
+
+	var result Result
+	for _, pe := range partErrors {
+		result.Skipped = append(result.Skipped, SkippedPart{Filename: pe.Filename, Reason: pe.Err})
+	}
+
+	for _, part := range msg.Parts {
+		if !part.IsAttachment {
+			result.TextParts = append(result.TextParts, part)
+			continue
+		}
+		result.Attachments = append(result.Attachments, Attachment{
+			Filename:            part.Filename,
+			Size:                part.Size,
+			Content:             part.Content,
+			DeclaredContentType: part.ContentType,
+			VerifiedContentType: http.DetectContentType(part.Content),
+		})
+	}
+	return result, nil
+}

mail/internal/attachments/attachments_test.go

@@ -0,0 +1,139 @@
+package attachments
+
+import (
+	"encoding/base64"
+	"strings"
+	"testing"
+)
+
+// TestExtract_OversizedAttachmentIsCorrectlyLimited ist die geforderte
+// Pflichtprüfung 1: Nachricht mit überdimensioniertem Anhang wird
+// korrekt begrenzt.
+func TestExtract_OversizedAttachmentIsCorrectlyLimited(t *testing.T) {
+	oversized := strings.Repeat("A", 200)
+	raw := "From: a@example.com\r\n" +
+		"To: b@example.com\r\n" +
+		"Subject: Test\r\n" +
+		"MIME-Version: 1.0\r\n" +
+		"Content-Type: multipart/mixed; boundary=\"b\"\r\n\r\n" +
+		"--b\r\n" +
+		"Content-Type: text/plain; charset=utf-8\r\n\r\n" +
+		"Kurzer Nachrichtentext\r\n" +
+		"--b\r\n" +
+		"Content-Type: application/octet-stream\r\n" +
+		"Content-Disposition: attachment; filename=\"riesig.bin\"\r\n\r\n" +
+		oversized + "\r\n" +
+		"--b--\r\n"
+
+	result, err := Extract(strings.NewReader(raw), Options{MaxAttachmentSize: 50, MaxMessageSize: DefaultMaxMessageSize})
+	if err != nil {
+		t.Fatalf("extract: %v", err)
+	}
+	if len(result.Attachments) != 0 {
+		t.Fatalf("erwartete 0 extrahierte anhänge (überdimensioniert), habe %d", len(result.Attachments))
+	}
+	if len(result.Skipped) != 1 || result.Skipped[0].Filename != "riesig.bin" {
+		t.Fatalf("erwartete genau 1 übersprungenen anhang 'riesig.bin', habe: %+v", result.Skipped)
+	}
+	if len(result.TextParts) != 1 || string(result.TextParts[0].Content) != "Kurzer Nachrichtentext" {
+		t.Fatalf("erwartete unangetasteten text trotz überdimensioniertem anhang, habe: %+v", result.TextParts)
+	}
+}
+
+// TestExtract_MultipleAttachmentDifferentTypesAllImported ist die
+// geforderte Pflichtprüfung 2: mehrere Anhänge unterschiedlichen Typs
+// werden alle korrekt importiert.
+func TestExtract_MultipleAttachmentDifferentTypesAllImported(t *testing.T) {
+	pdfContent := base64.StdEncoding.EncodeToString([]byte("%PDF-1.4 fake pdf bytes"))
+	pngContent := base64.StdEncoding.EncodeToString([]byte{0x89, 'P', 'N', 'G', 0x0D, 0x0A, 0x1A, 0x0A, 0, 0, 0})
+
+	raw := "From: a@example.com\r\n" +
+		"To: b@example.com\r\n" +
+		"Subject: Test\r\n" +
+		"MIME-Version: 1.0\r\n" +
+		"Content-Type: multipart/mixed; boundary=\"b\"\r\n\r\n" +
+		"--b\r\n" +
+		"Content-Type: text/plain; charset=utf-8\r\n\r\n" +
+		"Anbei zwei Anhänge\r\n" +
+		"--b\r\n" +
+		"Content-Type: application/pdf\r\n" +
+		"Content-Disposition: attachment; filename=\"rechnung.pdf\"\r\n" +
+		"Content-Transfer-Encoding: base64\r\n\r\n" +
+		pdfContent + "\r\n" +
+		"--b\r\n" +
+		"Content-Type: image/png\r\n" +
+		"Content-Disposition: attachment; filename=\"logo.png\"\r\n" +
+		"Content-Transfer-Encoding: base64\r\n\r\n" +
+		pngContent + "\r\n" +
+		"--b--\r\n"
+
+	result, err := Extract(strings.NewReader(raw), Options{})
+	if err != nil {
+		t.Fatalf("extract: %v", err)
+	}
+	if len(result.Attachments) != 2 {
+		t.Fatalf("erwartete 2 extrahierte anhänge, habe %d: %+v", len(result.Attachments), result.Attachments)
+	}
+	byName := map[string]Attachment{}
+	for _, a := range result.Attachments {
+		byName[a.Filename] = a
+	}
+	pdf, ok := byName["rechnung.pdf"]
+	if !ok || pdf.DeclaredContentType != "application/pdf" {
+		t.Fatalf("pdf-anhang fehlt oder falscher deklarierter typ: %+v", byName)
+	}
+	if !strings.Contains(pdf.VerifiedContentType, "text/plain") && !strings.Contains(pdf.VerifiedContentType, "application/") {
+		// http.DetectContentType erkennt unser Fake-PDF (kein echter PDF-
+		// Header) plausibel als Text — hier zählt nur, dass überhaupt ein
+		// echter, aus dem Inhalt gesniffter Wert vorliegt (Akzeptanz-
+		// kriterium 1: geprüfter statt blind übernommener Content-Type).
+		t.Fatalf("erwartete real gesniffeden content-type, habe: %q", pdf.VerifiedContentType)
+	}
+	png, ok := byName["logo.png"]
+	if !ok || png.DeclaredContentType != "image/png" {
+		t.Fatalf("png-anhang fehlt oder falscher deklarierter typ: %+v", byName)
+	}
+	if png.VerifiedContentType != "image/png" {
+		t.Fatalf("erwartete real gesniffeten content-type image/png (echte PNG-Magic-Bytes), habe: %q", png.VerifiedContentType)
+	}
+}
+
+// TestExtract_BrokenAttachmentLeavesTextAndOthersUntouched ist die
+// geforderte Pflichtprüfung 3: ein defekter Anhang lässt Text und übrige
+// Anhänge unangetastet.
+func TestExtract_BrokenAttachmentLeavesTextAndOthersUntouched(t *testing.T) {
+	goodContent := base64.StdEncoding.EncodeToString([]byte("echter anhangsinhalt"))
+	raw := "From: a@example.com\r\n" +
+		"To: b@example.com\r\n" +
+		"Subject: Test\r\n" +
+		"MIME-Version: 1.0\r\n" +
+		"Content-Type: multipart/mixed; boundary=\"b\"\r\n\r\n" +
+		"--b\r\n" +
+		"Content-Type: text/plain; charset=utf-8\r\n\r\n" +
+		"Wichtiger Nachrichtentext\r\n" +
+		"--b\r\n" +
+		"Content-Type: application/octet-stream\r\n" +
+		"Content-Disposition: attachment; filename=\"kaputt.bin\"\r\n" +
+		"Content-Transfer-Encoding: base64\r\n\r\n" +
+		"DAS_IST_KEIN_GUELTIGES_BASE64!!!\r\n" +
+		"--b\r\n" +
+		"Content-Type: application/octet-stream\r\n" +
+		"Content-Disposition: attachment; filename=\"gut.bin\"\r\n" +
+		"Content-Transfer-Encoding: base64\r\n\r\n" +
+		goodContent + "\r\n" +
+		"--b--\r\n"
+
+	result, err := Extract(strings.NewReader(raw), Options{})
+	if err != nil {
+		t.Fatalf("extract: %v", err)
+	}
+	if len(result.TextParts) != 1 || string(result.TextParts[0].Content) != "Wichtiger Nachrichtentext" {
+		t.Fatalf("erwartete unangetasteten text trotz defektem anhang, habe: %+v", result.TextParts)
+	}
+	if len(result.Attachments) != 1 || result.Attachments[0].Filename != "gut.bin" {
+		t.Fatalf("erwartete den guten anhang unangetastet, habe: %+v", result.Attachments)
+	}
+	if string(result.Attachments[0].Content) != "echter anhangsinhalt" {
+		t.Fatalf("guter anhang hat unerwarteten inhalt: %q", result.Attachments[0].Content)
+	}
+}

mail/internal/crypto/envelope.go

@@ -0,0 +1,118 @@
+// Package crypto implementiert ARC-02: Envelope-Encryption für Objekte
+// at rest. Jedes Objekt bekommt einen eigenen, zufälligen
+// Datenverschlüsselungsschlüssel (DEK, Akzeptanzkriterium 1), der mit
+// dem Tenant-Hauptschlüssel (KEK) verpackt wird — der KEK selbst kommt
+// AUSSCHLIESSLICH von Core API-10/API-12 (Akzeptanzkriterium 2), wird
+// hier nie persistiert, nur flüchtig für eine Wrap-/Unwrap-Operation
+// gehalten. Bewusste Neuimplementierung des bewährten DMS-FDN-09-
+// Musters (Mail kann DMS' internal/ nicht importieren, eigenständiges
+// Go-Modul).
+package crypto
+
+import (
+	"bytes"
+	"crypto/aes"
+	"crypto/cipher"
+	"crypto/rand"
+	"errors"
+	"fmt"
+	"io"
+)
+
+const (
+	DEKSize = 32
+	KEKSize = 32
+)
+
+// ErrDecryptFailed wird geliefert, wenn ein Chiffretext nicht
+// entschlüsselt werden kann — falscher Schlüssel ODER manipulierte
+// Daten (Pflichtprüfung 2: GCM-Auth-Tag erkennt Manipulation
+// zuverlässig, AEAD unterscheidet die beiden Ursachen bewusst nicht).
+var ErrDecryptFailed = errors.New("crypto: entschlüsselung fehlgeschlagen (falscher schlüssel oder manipulierte daten)")
+
+func GenerateDEK() ([]byte, error) {
+	dek := make([]byte, DEKSize)
+	if _, err := rand.Read(dek); err != nil {
+		return nil, fmt.Errorf("crypto: dek erzeugen: %w", err)
+	}
+	return dek, nil
+}
+
+func seal(key, plaintext []byte) ([]byte, error) {
+	block, err := aes.NewCipher(key)
+	if err != nil {
+		return nil, fmt.Errorf("crypto: aes-cipher erstellen: %w", err)
+	}
+	gcm, err := cipher.NewGCM(block)
+	if err != nil {
+		return nil, fmt.Errorf("crypto: gcm erstellen: %w", err)
+	}
+	nonce := make([]byte, gcm.NonceSize())
+	if _, err := rand.Read(nonce); err != nil {
+		return nil, fmt.Errorf("crypto: nonce erzeugen: %w", err)
+	}
+	return gcm.Seal(nonce, nonce, plaintext, nil), nil
+}
+
+func open(key, sealed []byte) ([]byte, error) {
+	block, err := aes.NewCipher(key)
+	if err != nil {
+		return nil, fmt.Errorf("crypto: aes-cipher erstellen: %w", err)
+	}
+	gcm, err := cipher.NewGCM(block)
+	if err != nil {
+		return nil, fmt.Errorf("crypto: gcm erstellen: %w", err)
+	}
+	if len(sealed) < gcm.NonceSize() {
+		return nil, ErrDecryptFailed
+	}
+	nonce, ciphertext := sealed[:gcm.NonceSize()], sealed[gcm.NonceSize():]
+	plaintext, err := gcm.Open(nil, nonce, ciphertext, nil)
+	if err != nil {
+		return nil, ErrDecryptFailed
+	}
+	return plaintext, nil
+}
+
+func WrapDEK(kek, dek []byte) ([]byte, error) {
+	wrapped, err := seal(kek, dek)
+	if err != nil {
+		return nil, fmt.Errorf("crypto: dek verpacken: %w", err)
+	}
+	return wrapped, nil
+}
+
+func UnwrapDEK(kek, wrappedDEK []byte) ([]byte, error) {
+	return open(kek, wrappedDEK)
+}
+
+// EncryptStream verschlüsselt den gesamten Inhalt von r mit dek
+// (AES-256-GCM). Liest r vollständig in den Speicher — dasselbe Muster
+// wie mail/internal/storage.S3Driver.Put (ARC-01), das S3-PutObject
+// ebenfalls vollständig puffert; ein segmentiertes AEAD-Verfahren für
+// sehr große Anhänge ist bewusst nicht Teil der "kleinsten Lösung".
+func EncryptStream(dek []byte, r io.Reader) (io.Reader, error) {
+	plaintext, err := io.ReadAll(r)
+	if err != nil {
+		return nil, fmt.Errorf("crypto: klartext lesen: %w", err)
+	}
+	ciphertext, err := seal(dek, plaintext)
+	if err != nil {
+		return nil, fmt.Errorf("crypto: verschlüsseln: %w", err)
+	}
+	return bytes.NewReader(ciphertext), nil
+}
+
+// DecryptStream entschlüsselt einen zuvor mit EncryptStream erzeugten
+// Chiffretext-Stream.
+func DecryptStream(dek []byte, r io.Reader) (io.Reader, error) {
+	ciphertext, err := io.ReadAll(r)
+	if err != nil {
+		return nil, fmt.Errorf("crypto: chiffretext lesen: %w", err)
+	}
+	plaintext, err := open(dek, ciphertext)
+	if err != nil {
+		return nil, err
+	}
+	return bytes.NewReader(plaintext), nil
+}

mail/internal/crypto/kekprovider.go

@@ -9,26 +9,26 @@ import (
 	"net/url"
 )
 
-// KEKProvider liefert den aktuellen, entschluesselten Tenant-KEK
+// KEKProvider liefert den aktuellen, entschlüsselten Tenant-KEK
-// (Akzeptanzkriterium 2: KEK kommt ausschliesslich von Core API-10).
+// (Akzeptanzkriterium 2: KEK kommt ausschließlich von Core API-10/
-// Schmale Schnittstelle, damit Tests einen Fake statt eines echten
+// API-12). Schmale Schnittstelle, damit Tests einen Fake statt eines
-// HTTP-Aufrufs einsetzen koennen.
+// echten HTTP-Aufrufs einsetzen können.
 type KEKProvider interface {
 	TenantKEK(ctx context.Context, tenantSlug string) ([]byte, error)
 }
 
 // tenantKEKResponse entspricht Core internal/kek.tenantKEKResponse
-// (JSON-Vertrag: tenant_kek_base64) — dieselbe Struktur, hier gespiegelt,
+// (JSON-Vertrag: tenant_kek_base64) — dieselbe Struktur, hier
-// da DMS Cores internal/-Pakete nicht importieren kann.
+// gespiegelt, da Mail Cores internal/-Pakete nicht importieren kann.
 type tenantKEKResponse struct {
 	TenantKEKBase64 string `json:"tenant_kek_base64"`
 }
 
-// HTTPKEKProvider bezieht den Tenant-KEK ueber Cores KEK-Handler
+// HTTPKEKProvider bezieht den Tenant-KEK über Core API-12
-// (internal/kek.Handler.TenantKEKHandler, API-10), authentifiziert ueber
+// (internal/kek.Handler.TenantKEKHandler, echt laufender Dienst),
-// dasselbe Service-Credential-Verfahren wie jeder andere Modul-Core-Aufruf
+// authentifiziert über dasselbe Service-Credential-Verfahren wie jeder
-// (API-02) — identisches Muster wie internal/storage.HTTPUsageReporter aus
+// andere Modul-Core-Aufruf (API-02) — identisches Muster wie DMS
-// FDN-03.
+// FDN-09/internal/storage.HTTPUsageReporter aus ARC-01.
 type HTTPKEKProvider struct {
 	endpointURL  string
 	clientID     string
@@ -46,7 +46,7 @@ func NewHTTPKEKProvider(endpointURL, clientID, clientSecret string, httpClient *
 func (p *HTTPKEKProvider) TenantKEK(ctx context.Context, tenantSlug string) ([]byte, error) {
 	u, err := url.Parse(p.endpointURL)
 	if err != nil {
-		return nil, fmt.Errorf("crypto: kek-endpunkt-url ungueltig: %w", err)
+		return nil, fmt.Errorf("crypto: kek-endpunkt-url ungültig: %w", err)
 	}
 	q := u.Query()
 	q.Set("tenant", tenantSlug)

mail/internal/crypto/kekversions.go

@@ -0,0 +1,144 @@
+// ARC-08: Tenant-KEK-Rotation. Core (API-10, `internal/kek.Store.
+// RotateTenantKEK`) ersetzt den Tenant-KEK durch einen komplett neuen
+// Wert — Core selbst hält KEINE Historie vor, `TenantKEKHandler` liefert
+// immer nur den AKTUELLEN Schlüssel (siehe kekprovider.go). Damit ARC-08s
+// Akzeptanzkriterium 3 ("alte Schlüsselversionen bleiben für
+// Lesezugriff kontrolliert verfügbar") erfüllbar ist, muss Mail selbst
+// jeden von Core bezogenen Tenant-KEK versioniert zwischenspeichern —
+// KEKVersionStore übernimmt genau das, lokal mit einem eigenen,
+// ausschließlich über Umgebungsvariable bezogenen Wrap-Schlüssel
+// verschlüsselt (kein Klartext-KEK in der Datenbank).
+package crypto
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"fmt"
+
+	"github.com/jackc/pgx/v5"
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+// ErrKEKVersionNotFound wird geliefert, wenn die angefragte Version für
+// den Mandanten nicht existiert.
+var ErrKEKVersionNotFound = errors.New("crypto: kek-version nicht gefunden")
+
+// ErrKEKVersionRevoked wird geliefert, wenn die angefragte Version gezielt
+// gesperrt wurde (Pflichtprüfung 2: kompromittierter alter Schlüssel kann
+// gezielt gesperrt werden) — der Lesezugriff auf mit dieser Version
+// verschlüsselte Altobjekte ist dann bewusst blockiert.
+var ErrKEKVersionRevoked = errors.New("crypto: kek-version wurde gesperrt")
+
+// KEKVersionStore verwaltet die Versionshistorie der Tenant-KEKs, die
+// dieses Mail-Modul im Lauf der Zeit von Core bezogen hat.
+type KEKVersionStore struct {
+	pool         *pgxpool.Pool
+	localWrapKey []byte
+}
+
+// NewKEKVersionStore erzeugt einen Store. localWrapKey verschlüsselt die
+// zwischengespeicherten Tenant-KEKs lokal at rest (KEKSize Bytes,
+// ausschließlich über Umgebungsvariable bezogen — nie im Code).
+func NewKEKVersionStore(pool *pgxpool.Pool, localWrapKey []byte) *KEKVersionStore {
+	return &KEKVersionStore{pool: pool, localWrapKey: localWrapKey}
+}
+
+// EnsureSchema legt die Tabelle an, falls sie noch nicht existiert —
+// gleiches Muster wie mail/internal/dedup/indexworker (kein zentraler
+// Migrationsläufer für Mandanten-Datenbanken im Mail-Modul vorhanden).
+func (s *KEKVersionStore) EnsureSchema(ctx context.Context) error {
+	if _, err := s.pool.Exec(ctx, `
+		CREATE TABLE IF NOT EXISTS mail_kek_versions (
+			tenant_slug  TEXT NOT NULL,
+			version      INT NOT NULL,
+			wrapped_kek  BYTEA NOT NULL,
+			revoked      BOOLEAN NOT NULL DEFAULT false,
+			created_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
+			PRIMARY KEY (tenant_slug, version)
+		)
+	`); err != nil {
+		return fmt.Errorf("crypto: kek-versionsschema anlegen: %w", err)
+	}
+	return nil
+}
+
+// RecordIfNew merkt sich plainKEK als neue Version für tenantSlug, FALLS
+// er sich vom zuletzt gespeicherten Wert unterscheidet (Rotation
+// erkannt) — bei unverändertem KEK wird keine neue Version angelegt,
+// sondern die bestehende Versionsnummer zurückgegeben (Akzeptanzkriterium
+// 1: rotierbar verwaltet, nicht bei jedem Aufruf eine neue Version).
+func (s *KEKVersionStore) RecordIfNew(ctx context.Context, tenantSlug string, plainKEK []byte) (version int, err error) {
+	var latestVersion int
+	var latestWrapped []byte
+	err = s.pool.QueryRow(ctx, `
+		SELECT version, wrapped_kek FROM mail_kek_versions
+		WHERE tenant_slug = $1 ORDER BY version DESC LIMIT 1
+	`, tenantSlug).Scan(&latestVersion, &latestWrapped)
+	switch {
+	case errors.Is(err, pgx.ErrNoRows):
+		return s.insertVersion(ctx, tenantSlug, 1, plainKEK)
+	case err != nil:
+		return 0, fmt.Errorf("crypto: letzte kek-version lesen: %w", err)
+	}
+
+	latestPlain, err := open(s.localWrapKey, latestWrapped)
+	if err != nil {
+		return 0, fmt.Errorf("crypto: zwischengespeicherten kek entpacken: %w", err)
+	}
+	if bytes.Equal(latestPlain, plainKEK) {
+		return latestVersion, nil
+	}
+	return s.insertVersion(ctx, tenantSlug, latestVersion+1, plainKEK)
+}
+
+func (s *KEKVersionStore) insertVersion(ctx context.Context, tenantSlug string, version int, plainKEK []byte) (int, error) {
+	wrapped, err := seal(s.localWrapKey, plainKEK)
+	if err != nil {
+		return 0, fmt.Errorf("crypto: kek für zwischenspeicherung verpacken: %w", err)
+	}
+	if _, err := s.pool.Exec(ctx, `
+		INSERT INTO mail_kek_versions (tenant_slug, version, wrapped_kek) VALUES ($1, $2, $3)
+	`, tenantSlug, version, wrapped); err != nil {
+		return 0, fmt.Errorf("crypto: kek-version speichern: %w", err)
+	}
+	return version, nil
+}
+
+// Get liefert den entschlüsselten historischen Tenant-KEK einer
+// bestimmten Version. Liefert ErrKEKVersionRevoked, wenn die Version
+// gezielt gesperrt wurde (Pflichtprüfung 2).
+func (s *KEKVersionStore) Get(ctx context.Context, tenantSlug string, version int) ([]byte, error) {
+	var wrapped []byte
+	var revoked bool
+	err := s.pool.QueryRow(ctx, `
+		SELECT wrapped_kek, revoked FROM mail_kek_versions
+		WHERE tenant_slug = $1 AND version = $2
+	`, tenantSlug, version).Scan(&wrapped, &revoked)
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return nil, ErrKEKVersionNotFound
+		}
+		return nil, fmt.Errorf("crypto: kek-version lesen: %w", err)
+	}
+	if revoked {
+		return nil, ErrKEKVersionRevoked
+	}
+	return open(s.localWrapKey, wrapped)
+}
+
+// Revoke sperrt eine Tenant-KEK-Version gezielt (Pflichtprüfung 2):
+// nachfolgende Get-Aufrufe für genau diese Version schlagen mit
+// ErrKEKVersionRevoked fehl, andere Versionen bleiben unberührt.
+func (s *KEKVersionStore) Revoke(ctx context.Context, tenantSlug string, version int) error {
+	tag, err := s.pool.Exec(ctx, `
+		UPDATE mail_kek_versions SET revoked = true WHERE tenant_slug = $1 AND version = $2
+	`, tenantSlug, version)
+	if err != nil {
+		return fmt.Errorf("crypto: kek-version sperren: %w", err)
+	}
+	if tag.RowsAffected() == 0 {
+		return ErrKEKVersionNotFound
+	}
+	return nil
+}

mail/internal/crypto/kekversions_test.go

@@ -0,0 +1,111 @@
+// Integrationstest (ARC-08): echte Postgres-Instanz, folgt derselben
+// Testhost-Konvention wie mail/internal/dedup/indexworker — TEST_TENANT_DSN.
+package crypto
+
+import (
+	"bytes"
+	"context"
+	"os"
+	"testing"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+var testLocalWrapKey = bytes.Repeat([]byte{0x7a}, KEKSize)
+
+func setupKEKVersionStore(t *testing.T, tenantSlug string) *KEKVersionStore {
+	t.Helper()
+	dsn := os.Getenv("TEST_TENANT_DSN")
+	if dsn == "" {
+		t.Skip("TEST_TENANT_DSN nicht gesetzt, Integrationstest übersprungen")
+	}
+	ctx := context.Background()
+	pool, err := pgxpool.New(ctx, dsn)
+	if err != nil {
+		t.Fatalf("pool: %v", err)
+	}
+	t.Cleanup(func() { pool.Close() })
+
+	store := NewKEKVersionStore(pool, testLocalWrapKey)
+	if err := store.EnsureSchema(ctx); err != nil {
+		t.Fatalf("schema: %v", err)
+	}
+	t.Cleanup(func() {
+		_, _ = pool.Exec(context.Background(), `DELETE FROM mail_kek_versions WHERE tenant_slug = $1`, tenantSlug)
+	})
+	return store
+}
+
+func TestKEKVersionStore_RecordIfNewDetectsRotationOnly(t *testing.T) {
+	tenant := "mandant-arc08-recordifnew"
+	store := setupKEKVersionStore(t, tenant)
+	ctx := context.Background()
+
+	kekV1 := bytes.Repeat([]byte{0x01}, KEKSize)
+	v1, err := store.RecordIfNew(ctx, tenant, kekV1)
+	if err != nil {
+		t.Fatalf("erste erfassung: %v", err)
+	}
+	if v1 != 1 {
+		t.Fatalf("erwartete version 1, habe %d", v1)
+	}
+
+	// Erneuter Aufruf mit UNVERÄNDERTEM KEK darf keine neue Version anlegen.
+	vAgain, err := store.RecordIfNew(ctx, tenant, kekV1)
+	if err != nil {
+		t.Fatalf("zweite erfassung (unverändert): %v", err)
+	}
+	if vAgain != 1 {
+		t.Fatalf("erwartete weiterhin version 1 bei unverändertem kek, habe %d", vAgain)
+	}
+
+	kekV2 := bytes.Repeat([]byte{0x02}, KEKSize)
+	v2, err := store.RecordIfNew(ctx, tenant, kekV2)
+	if err != nil {
+		t.Fatalf("dritte erfassung (rotiert): %v", err)
+	}
+	if v2 != 2 {
+		t.Fatalf("erwartete version 2 nach rotation, habe %d", v2)
+	}
+
+	gotV1, err := store.Get(ctx, tenant, 1)
+	if err != nil {
+		t.Fatalf("get v1: %v", err)
+	}
+	if !bytes.Equal(gotV1, kekV1) {
+		t.Fatal("v1 liefert nicht den ursprünglichen kek zurück")
+	}
+	gotV2, err := store.Get(ctx, tenant, 2)
+	if err != nil {
+		t.Fatalf("get v2: %v", err)
+	}
+	if !bytes.Equal(gotV2, kekV2) {
+		t.Fatal("v2 liefert nicht den rotierten kek zurück")
+	}
+}
+
+func TestKEKVersionStore_RevokeBlocksOnlyThatVersion(t *testing.T) {
+	tenant := "mandant-arc08-revoke"
+	store := setupKEKVersionStore(t, tenant)
+	ctx := context.Background()
+
+	kekV1 := bytes.Repeat([]byte{0x11}, KEKSize)
+	kekV2 := bytes.Repeat([]byte{0x22}, KEKSize)
+	if _, err := store.RecordIfNew(ctx, tenant, kekV1); err != nil {
+		t.Fatalf("v1 erfassen: %v", err)
+	}
+	if _, err := store.RecordIfNew(ctx, tenant, kekV2); err != nil {
+		t.Fatalf("v2 erfassen: %v", err)
+	}
+
+	if err := store.Revoke(ctx, tenant, 1); err != nil {
+		t.Fatalf("v1 sperren: %v", err)
+	}
+
+	if _, err := store.Get(ctx, tenant, 1); err != ErrKEKVersionRevoked {
+		t.Fatalf("erwartete ErrKEKVersionRevoked für gesperrte version 1, habe: %v", err)
+	}
+	if _, err := store.Get(ctx, tenant, 2); err != nil {
+		t.Fatalf("version 2 sollte unberührt bleiben: %v", err)
+	}
+}

mail/internal/crypto/rotation_test.go

@@ -0,0 +1,131 @@
+// ARC-08: End-zu-Ende-Rotationstest. Nutzt einen fake KEKProvider (echter
+// Testkonvention aus ARC-02, siehe encstorage_test.go) statt eines echten
+// HTTP-Aufrufs an Core API-12 — Core selbst hat keine rotierbare
+// Testschnittstelle über HTTP exponiert (nur der aktuelle KEK ist
+// abrufbar), die Rotation wird hier auf Höhe der KEKProvider-Schnittstelle
+// simuliert, exakt wie ARC-02 es für Fehlerfälle bereits tut.
+package crypto
+
+import (
+	"bytes"
+	"context"
+	"io"
+	"strings"
+	"sync"
+	"testing"
+)
+
+// rotatableKEKProvider liefert für einen Mandanten einen aktuell
+// gesetzten KEK, der zur Laufzeit "rotiert" werden kann (simuliert Core
+// API-10s RotateTenantKEK, dessen Effekt auf API-12 exakt darin besteht,
+// dass TenantKEK ab dann einen anderen Wert liefert).
+type rotatableKEKProvider struct {
+	mu      sync.Mutex
+	current []byte
+}
+
+func (p *rotatableKEKProvider) TenantKEK(_ context.Context, _ string) ([]byte, error) {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+	return p.current, nil
+}
+
+func (p *rotatableKEKProvider) rotate(newKEK []byte) {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+	p.current = newKEK
+}
+
+// TestRotation_OldArchiveStaysReadableAfterMasterKeyRotation ist die
+// geforderte Pflichtprüfung 1: Rotation des Hauptschlüssels lässt
+// Altbestand weiterhin lesbar.
+func TestRotation_OldArchiveStaysReadableAfterMasterKeyRotation(t *testing.T) {
+	tenant := "mandant-arc08-rotation-lesbar"
+	store := setupKEKVersionStore(t, tenant)
+	ctx := context.Background()
+
+	provider := &rotatableKEKProvider{current: bytes.Repeat([]byte{0x51}, KEKSize)}
+	svc := NewService(provider).WithVersionStore(store)
+
+	// Objekt VOR der Rotation versiegeln.
+	oldEnvelope, err := svc.Seal(ctx, tenant, strings.NewReader("altbestand vor rotation"))
+	if err != nil {
+		t.Fatalf("seal (alt): %v", err)
+	}
+	if oldEnvelope.KEKVersion != 1 {
+		t.Fatalf("erwartete kek-version 1 vor rotation, habe %d", oldEnvelope.KEKVersion)
+	}
+	oldCiphertext, err := io.ReadAll(oldEnvelope.Ciphertext)
+	if err != nil {
+		t.Fatalf("chiffretext (alt) lesen: %v", err)
+	}
+
+	// Core rotiert den Tenant-Hauptschlüssel — TenantKEK liefert ab jetzt
+	// einen komplett anderen Wert, exakt wie internal/kek.Store.
+	// RotateTenantKEK es real bei Core bewirkt.
+	provider.rotate(bytes.Repeat([]byte{0x52}, KEKSize))
+
+	// Objekt NACH der Rotation versiegeln (Akzeptanzkriterium 2: kein
+	// Neuverschlüsseln des Altbestands nötig, nur neue Objekte nutzen den
+	// neuen Schlüssel).
+	newEnvelope, err := svc.Seal(ctx, tenant, strings.NewReader("neuer inhalt nach rotation"))
+	if err != nil {
+		t.Fatalf("seal (neu): %v", err)
+	}
+	if newEnvelope.KEKVersion != 2 {
+		t.Fatalf("erwartete kek-version 2 nach rotation, habe %d", newEnvelope.KEKVersion)
+	}
+
+	// Altbestand bleibt über die aufgezeichnete Version lesbar
+	// (Akzeptanzkriterium 3).
+	openedOld, err := svc.OpenAtVersion(ctx, tenant, oldEnvelope.KEKVersion, oldEnvelope.WrappedDEK, bytes.NewReader(oldCiphertext))
+	if err != nil {
+		t.Fatalf("openatversion (alt, nach rotation): %v", err)
+	}
+	plainOld, err := io.ReadAll(openedOld)
+	if err != nil {
+		t.Fatalf("altbestand lesen: %v", err)
+	}
+	if string(plainOld) != "altbestand vor rotation" {
+		t.Fatalf("altbestand-inhalt stimmt nicht, habe %q", string(plainOld))
+	}
+
+	// Der naive Open() (aktueller KEK) darf für das ALTE Objekt inzwischen
+	// NICHT mehr funktionieren — das beweist, dass OpenAtVersion die
+	// Rotation tatsächlich überbrückt, statt zufällig auch so zu klappen.
+	if _, err := svc.Open(ctx, tenant, oldEnvelope.WrappedDEK, bytes.NewReader(oldCiphertext)); err == nil {
+		t.Fatal("erwartete fehler bei Open() des altbestands mit dem NEUEN aktuellen kek, habe nil")
+	}
+}
+
+// TestRotation_CompromisedOldKeyCanBeRevoked ist die geforderte
+// Pflichtprüfung 2: kompromittierter alter Schlüssel kann gezielt
+// gesperrt werden.
+func TestRotation_CompromisedOldKeyCanBeRevoked(t *testing.T) {
+	tenant := "mandant-arc08-revoke-e2e"
+	store := setupKEKVersionStore(t, tenant)
+	ctx := context.Background()
+
+	provider := &rotatableKEKProvider{current: bytes.Repeat([]byte{0x61}, KEKSize)}
+	svc := NewService(provider).WithVersionStore(store)
+
+	compromisedEnvelope, err := svc.Seal(ctx, tenant, strings.NewReader("mit kompromittiertem schlüssel versiegelt"))
+	if err != nil {
+		t.Fatalf("seal: %v", err)
+	}
+	compromisedCiphertext, err := io.ReadAll(compromisedEnvelope.Ciphertext)
+	if err != nil {
+		t.Fatalf("chiffretext lesen: %v", err)
+	}
+
+	provider.rotate(bytes.Repeat([]byte{0x62}, KEKSize))
+
+	if err := store.Revoke(ctx, tenant, compromisedEnvelope.KEKVersion); err != nil {
+		t.Fatalf("kompromittierte version sperren: %v", err)
+	}
+
+	_, err = svc.OpenAtVersion(ctx, tenant, compromisedEnvelope.KEKVersion, compromisedEnvelope.WrappedDEK, bytes.NewReader(compromisedCiphertext))
+	if err == nil {
+		t.Fatal("erwartete fehler beim lesen mit gesperrter kek-version, habe nil")
+	}
+}

mail/internal/crypto/service.go

@@ -0,0 +1,114 @@
+package crypto
+
+import (
+	"context"
+	"fmt"
+	"io"
+)
+
+// Envelope ist das Ergebnis einer Seal-Operation: der Chiffretext-
+// Stream plus der mit dem Tenant-KEK verpackte DEK, der zusammen mit
+// dem Objekt persistiert werden muss (siehe mail/internal/encstorage).
+// KEKVersion identifiziert (ARC-08), MIT welcher Tenant-KEK-Version der
+// DEK verpackt wurde — 0, solange kein KEKVersionStore konfiguriert ist
+// (Rückwärtskompatibilität, siehe WithVersionStore).
+type Envelope struct {
+	Ciphertext io.Reader
+	WrappedDEK []byte
+	KEKVersion int
+}
+
+// Service verbindet KEKProvider mit den Envelope-Operationen — Aufrufer
+// (mail/internal/encstorage) rufen ausschließlich Service auf, nie die
+// Einzelfunktionen aus envelope.go direkt.
+type Service struct {
+	kek      KEKProvider
+	versions *KEKVersionStore
+}
+
+func NewService(kek KEKProvider) *Service {
+	return &Service{kek: kek}
+}
+
+// WithVersionStore aktiviert die Tenant-KEK-Versionsverfolgung (ARC-08).
+// Ohne aufgerufenes WithVersionStore verhält sich Service exakt wie vor
+// ARC-08 (KEKVersion bleibt 0, OpenAtVersion fällt auf Open zurück) —
+// bestehende Aufrufer (z. B. encstorage) sind unverändert lauffähig.
+func (s *Service) WithVersionStore(store *KEKVersionStore) *Service {
+	s.versions = store
+	return s
+}
+
+// Seal erzeugt einen neuen DEK (Akzeptanzkriterium 1), verschlüsselt
+// plaintext damit und verpackt den DEK mit dem aktuellen Tenant-KEK
+// (Akzeptanzkriterium 2 — der KEK wird bei JEDEM Aufruf frisch von Core
+// bezogen, nie zwischengespeichert außer in der optionalen
+// KEK-Versionshistorie für spätere Altbestands-Lesezugriffe).
+func (s *Service) Seal(ctx context.Context, tenantSlug string, plaintext io.Reader) (*Envelope, error) {
+	dek, err := GenerateDEK()
+	if err != nil {
+		return nil, err
+	}
+	ciphertext, err := EncryptStream(dek, plaintext)
+	if err != nil {
+		return nil, err
+	}
+	kek, err := s.kek.TenantKEK(ctx, tenantSlug)
+	if err != nil {
+		return nil, fmt.Errorf("crypto: tenant-kek beziehen: %w", err)
+	}
+	wrappedDEK, err := WrapDEK(kek, dek)
+	if err != nil {
+		return nil, err
+	}
+
+	var kekVersion int
+	if s.versions != nil {
+		kekVersion, err = s.versions.RecordIfNew(ctx, tenantSlug, kek)
+		if err != nil {
+			return nil, fmt.Errorf("crypto: kek-version erfassen: %w", err)
+		}
+	}
+
+	return &Envelope{Ciphertext: ciphertext, WrappedDEK: wrappedDEK, KEKVersion: kekVersion}, nil
+}
+
+// Open entpackt den DEK mit dem AKTUELLEN Tenant-KEK (Akzeptanzkriterium
+// 3: nur mit gültigem, mandantenbezogenem Schlüssel möglich — ein
+// falscher Tenant-Slug liefert entweder einen falschen KEK von Core
+// [dann schlägt UnwrapDEK fehl] oder Core verweigert den Zugriff direkt)
+// und entschlüsselt ciphertext damit. Nach einer Tenant-KEK-Rotation bei
+// Core funktioniert Open nur noch für Objekte, die mit dem NEUEN KEK
+// versiegelt wurden — für Altbestand siehe OpenAtVersion.
+func (s *Service) Open(ctx context.Context, tenantSlug string, wrappedDEK []byte, ciphertext io.Reader) (io.Reader, error) {
+	kek, err := s.kek.TenantKEK(ctx, tenantSlug)
+	if err != nil {
+		return nil, fmt.Errorf("crypto: tenant-kek beziehen: %w", err)
+	}
+	dek, err := UnwrapDEK(kek, wrappedDEK)
+	if err != nil {
+		return nil, err
+	}
+	return DecryptStream(dek, ciphertext)
+}
+
+// OpenAtVersion entpackt den DEK mit der beim Seal aufgezeichneten
+// historischen Tenant-KEK-Version statt mit dem aktuellen Core-KEK
+// (ARC-08 Akzeptanzkriterium 3: Altbestand bleibt nach einer
+// Hauptschlüssel-Rotation lesbar). Ist kekVersion 0 oder kein
+// KEKVersionStore konfiguriert, verhält es sich wie Open (Rückwärts-
+// kompatibilität für vor ARC-08 versiegelte Objekte).
+func (s *Service) OpenAtVersion(ctx context.Context, tenantSlug string, kekVersion int, wrappedDEK []byte, ciphertext io.Reader) (io.Reader, error) {
+	if kekVersion == 0 || s.versions == nil {
+		return s.Open(ctx, tenantSlug, wrappedDEK, ciphertext)
+	}
+	kek, err := s.versions.Get(ctx, tenantSlug, kekVersion)
+	if err != nil {
+		return nil, fmt.Errorf("crypto: historischen tenant-kek beziehen: %w", err)
+	}
+	dek, err := UnwrapDEK(kek, wrappedDEK)
+	if err != nil {
+		return nil, err
+	}
+	return DecryptStream(dek, ciphertext)
+}

mail/internal/dedup/hash.go

@@ -0,0 +1,35 @@
+// Package dedup implementiert ARC-03: Dublettenerkennung für
+// archivierte E-Mails über einen Inhalts-Hash. Kombiniert bewusst NICHT
+// mit mail/internal/storage oder mail/internal/crypto — dieses Paket
+// kennt beide nicht, der Aufrufer (spätere Ingest-Tickets) ruft es VOR
+// mail/internal/crypto auf.
+package dedup
+
+import (
+	"bytes"
+	"crypto/sha256"
+	"encoding/hex"
+	"fmt"
+	"io"
+)
+
+// HashAndBuffer berechnet den SHA-256-Inhalts-Hash von plaintext.
+//
+// Bekannter Fehler vermeiden (siehe ARC-03-Ticket): der Hash MUSS auf
+// dem Klartext berechnet werden, BEVOR mail/internal/crypto verschlüsselt
+// — ein Hash auf dem Chiffretext wäre bei jedem Import anders (neuer
+// DEK je Objekt, siehe ARC-02) und Dublettenerkennung würde vollständig
+// versagen. Reihenfolge: Mail/Anhang empfangen -> HashAndBuffer (dieses
+// Paket) -> verschlüsseln (ARC-02) -> ablegen.
+//
+// plaintext wird beim Hashen vollständig verbraucht — HashAndBuffer
+// liefert deshalb einen erneut lesbaren Reader mit demselben Inhalt für
+// den nachfolgenden Verschlüsselungsschritt zurück.
+func HashAndBuffer(plaintext io.Reader) (contentHash string, buffered io.Reader, err error) {
+	var buf bytes.Buffer
+	hasher := sha256.New()
+	if _, err := io.Copy(hasher, io.TeeReader(plaintext, &buf)); err != nil {
+		return "", nil, fmt.Errorf("dedup: klartext hashen: %w", err)
+	}
+	return hex.EncodeToString(hasher.Sum(nil)), &buf, nil
+}

mail/internal/dedup/hash_test.go

@@ -0,0 +1,58 @@
+package dedup
+
+import (
+	"io"
+	"strings"
+	"testing"
+)
+
+func TestHashAndBuffer_SameContentSameHash(t *testing.T) {
+	h1, buf1, err := HashAndBuffer(strings.NewReader("identischer inhalt"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	h2, buf2, err := HashAndBuffer(strings.NewReader("identischer inhalt"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if h1 != h2 {
+		t.Fatalf("erwartet identischen hash für identischen inhalt, habe %q vs %q", h1, h2)
+	}
+
+	got1, _ := io.ReadAll(buf1)
+	got2, _ := io.ReadAll(buf2)
+	if string(got1) != "identischer inhalt" || string(got2) != "identischer inhalt" {
+		t.Fatal("buffered reader liefert nicht denselben inhalt zurück wie der ursprüngliche klartext")
+	}
+}
+
+func TestHashAndBuffer_DifferentContentDifferentHash(t *testing.T) {
+	h1, _, err := HashAndBuffer(strings.NewReader("nachricht a"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	h2, _, err := HashAndBuffer(strings.NewReader("nachricht b"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if h1 == h2 {
+		t.Fatal("unterschiedlicher inhalt hätte unterschiedlichen hash liefern müssen")
+	}
+}
+
+// TestHashAndBuffer_SlightlyDifferentContentDifferentHash ist die
+// geforderte Pflichtprüfung 3: knapp unterschiedliche Nachrichten
+// werden korrekt NICHT als Duplikat erkannt.
+func TestHashAndBuffer_SlightlyDifferentContentDifferentHash(t *testing.T) {
+	h1, _, err := HashAndBuffer(strings.NewReader("Betreff: Test\r\n\r\nInhalt der Nachricht."))
+	if err != nil {
+		t.Fatal(err)
+	}
+	h2, _, err := HashAndBuffer(strings.NewReader("Betreff: Test\r\n\r\nInhalt der Nachricht,"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if h1 == h2 {
+		t.Fatal("ein einziges abweichendes zeichen hätte den hash ändern müssen")
+	}
+}

mail/internal/dedup/store.go

@@ -0,0 +1,75 @@
+package dedup
+
+import (
+	"context"
+	"errors"
+	"fmt"
+
+	"github.com/jackc/pgx/v5"
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+// Store verwaltet bekannte Inhalts-Hashes je Mandant. tenant_slug ist
+// fester Bestandteil des Primärschlüssels (Akzeptanzkriterium 3:
+// mandantenübergreifend korrekt getrennt) — auch wenn Store einen mit
+// anderen Mandanten geteilten Pool erhält, kann ein Hash-Treffer nie
+// über Mandantengrenzen hinweg entstehen.
+type Store struct {
+	pool       *pgxpool.Pool
+	tenantSlug string
+}
+
+func NewStore(pool *pgxpool.Pool, tenantSlug string) *Store {
+	return &Store{pool: pool, tenantSlug: tenantSlug}
+}
+
+// EnsureSchema legt die Tabelle an, falls sie noch nicht existiert —
+// gleiches Muster wie mail/internal/example (kein zentraler
+// Migrationsläufer für Mandanten-Datenbanken im Mail-Modul vorhanden).
+func (s *Store) EnsureSchema(ctx context.Context) error {
+	if _, err := s.pool.Exec(ctx, `
+		CREATE TABLE IF NOT EXISTS mail_content_hashes (
+			tenant_slug  TEXT NOT NULL,
+			content_hash TEXT NOT NULL,
+			object_key   TEXT NOT NULL,
+			created_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
+			PRIMARY KEY (tenant_slug, content_hash)
+		)
+	`); err != nil {
+		return fmt.Errorf("dedup: schema anlegen: %w", err)
+	}
+	return nil
+}
+
+// Register trägt contentHash für den Mandanten als neu bekannt ein
+// (Akzeptanzkriterium 1) und referenziert das Original, statt es
+// redundant zu speichern (Akzeptanzkriterium 2): existiert derselbe
+// Hash für DIESEN Mandanten bereits mit einem ANDEREN object_key,
+// liefert Register isDuplicate=true und den object_key des Originals —
+// der Aufrufer legt den neuen Inhalt dann NICHT ab.
+func (s *Store) Register(ctx context.Context, contentHash, objectKey string) (isDuplicate bool, existingKey string, err error) {
+	if _, err := s.pool.Exec(ctx, `
+		INSERT INTO mail_content_hashes (tenant_slug, content_hash, object_key)
+		VALUES ($1, $2, $3)
+		ON CONFLICT (tenant_slug, content_hash) DO NOTHING
+	`, s.tenantSlug, contentHash, objectKey); err != nil {
+		return false, "", fmt.Errorf("dedup: hash eintragen: %w", err)
+	}
+
+	var storedKey string
+	err = s.pool.QueryRow(ctx, `
+		SELECT object_key FROM mail_content_hashes
+		WHERE tenant_slug = $1 AND content_hash = $2
+	`, s.tenantSlug, contentHash).Scan(&storedKey)
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return false, "", fmt.Errorf("dedup: gerade eingetragenen hash nicht wiedergefunden")
+		}
+		return false, "", fmt.Errorf("dedup: eintrag lesen: %w", err)
+	}
+
+	if storedKey != objectKey {
+		return true, storedKey, nil
+	}
+	return false, "", nil
+}

mail/internal/dedup/store_integration_test.go

@@ -0,0 +1,94 @@
+// Integrationstest (ARC-03): echte Postgres-Instanz, folgt derselben
+// Testhost-Konvention wie mail/internal/example (QA-01) — TEST_TENANT_DSN.
+package dedup
+
+import (
+	"context"
+	"os"
+	"testing"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+func setupStore(t *testing.T, tenantSlug string) *Store {
+	t.Helper()
+	dsn := os.Getenv("TEST_TENANT_DSN")
+	if dsn == "" {
+		t.Skip("TEST_TENANT_DSN nicht gesetzt, Integrationstest übersprungen")
+	}
+	ctx := context.Background()
+	pool, err := pgxpool.New(ctx, dsn)
+	if err != nil {
+		t.Fatalf("pool: %v", err)
+	}
+	t.Cleanup(func() { pool.Close() })
+
+	store := NewStore(pool, tenantSlug)
+	if err := store.EnsureSchema(ctx); err != nil {
+		t.Fatalf("schema: %v", err)
+	}
+	t.Cleanup(func() {
+		_, _ = pool.Exec(context.Background(), `DELETE FROM mail_content_hashes WHERE tenant_slug = $1`, tenantSlug)
+	})
+	return store
+}
+
+// TestRegister_SameMessageFromTwoSourcesIsDuplicate ist die geforderte
+// Pflichtprüfung 1: dieselbe Nachricht aus zwei Quellen wird als
+// Duplikat erkannt.
+func TestRegister_SameMessageFromTwoSourcesIsDuplicate(t *testing.T) {
+	store := setupStore(t, "mandant-arc03-a")
+	ctx := context.Background()
+
+	hash := "fixierter-inhalts-hash-fuer-test-1"
+
+	isDup, _, err := store.Register(ctx, hash, "quelle-1/objekt")
+	if err != nil {
+		t.Fatalf("erste registrierung: %v", err)
+	}
+	if isDup {
+		t.Fatal("erste registrierung eines hashes darf kein duplikat sein")
+	}
+
+	isDup, existing, err := store.Register(ctx, hash, "quelle-2/objekt")
+	if err != nil {
+		t.Fatalf("zweite registrierung: %v", err)
+	}
+	if !isDup {
+		t.Fatal("erwartet: dieselbe nachricht aus zweiter quelle wird als duplikat erkannt")
+	}
+	if existing != "quelle-1/objekt" {
+		t.Fatalf("erwartet referenz auf das original quelle-1/objekt, habe %q", existing)
+	}
+}
+
+// TestRegister_SameContentTwoTenantsNotLinked ist die geforderte
+// Pflichtprüfung 2: zwei Mandanten mit identischem Mailinhalt werden
+// nicht fälschlich verknüpft.
+func TestRegister_SameContentTwoTenantsNotLinked(t *testing.T) {
+	dsn := os.Getenv("TEST_TENANT_DSN")
+	if dsn == "" {
+		t.Skip("TEST_TENANT_DSN nicht gesetzt, Integrationstest übersprungen")
+	}
+	storeA := setupStore(t, "mandant-arc03-x")
+	storeB := setupStore(t, "mandant-arc03-y")
+	ctx := context.Background()
+
+	hash := "identischer-inhalt-ueber-zwei-mandanten-hinweg"
+
+	isDupA, _, err := storeA.Register(ctx, hash, "mandant-x/objekt")
+	if err != nil {
+		t.Fatalf("mandant a: %v", err)
+	}
+	if isDupA {
+		t.Fatal("erste registrierung bei mandant a darf kein duplikat sein")
+	}
+
+	isDupB, existingB, err := storeB.Register(ctx, hash, "mandant-y/objekt")
+	if err != nil {
+		t.Fatalf("mandant b: %v", err)
+	}
+	if isDupB {
+		t.Fatalf("mandant b wurde fälschlich mit mandant a verknüpft, existing=%q", existingB)
+	}
+}

mail/internal/encstorage/encstorage.go

@@ -0,0 +1,138 @@
+// Package encstorage implementiert ARC-02s Anbindung an ARC-01: jedes
+// archivierte Objekt wird VOR dem Schreiben über
+// mail/internal/storage.Service verschlüsselt (Akzeptanzkriterium 1).
+// Kombiniert bewusst zwei bereits fertige, unveränderte Pakete
+// (mail/internal/storage aus ARC-01, mail/internal/crypto aus ARC-02)
+// statt eines davon zu erweitern — kein Umbau angrenzender Bereiche.
+//
+// Reihenfolge beachtet (Ticket "Bekannte Fehler vermeiden"): ein
+// SHA-256-Hash für Dublettenerkennung (ARC-03) muss auf dem KLARTEXT
+// berechnet werden, BEVOR diese Verschlüsselung angewendet wird — das
+// ist Sache des Aufrufers (ARC-03, außerhalb dieses Pakets), dieses
+// Paket nimmt bereits fertigen Klartext entgegen und verschlüsselt ihn
+// sofort, hält ihn nicht länger als nötig im Speicher.
+package encstorage
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"strconv"
+
+	"gitea.perlbach24.de/scripte/nexarch/mail/internal/crypto"
+	"gitea.perlbach24.de/scripte/nexarch/mail/internal/storage"
+)
+
+// wrappedDEKKey ist der Sidecar-Objektschlüssel für den mit dem
+// Tenant-KEK verpackten DEK — liegt im selben Storage-Backend wie der
+// Chiffretext, analog zum Prüfsummen-Sidecar aus ARC-01.
+func wrappedDEKKey(key string) string {
+	return key + ".dek"
+}
+
+// kekVersionKey ist der Sidecar-Objektschlüssel für die Tenant-KEK-
+// Version, mit der der DEK verpackt wurde (ARC-08 Akzeptanzkriterium 3).
+// Fehlt dieser Sidecar (vor ARC-08 geschriebene Objekte), wird Version 0
+// angenommen — GetDecrypted verhält sich dann wie vor ARC-08.
+func kekVersionKey(key string) string {
+	return key + ".dek.version"
+}
+
+// Service verbindet Storage (ARC-01) und Crypto (ARC-02): der Rest von
+// Mail ruft AUSSCHLIESSLICH diesen Service auf, nie storage.Service
+// direkt mit Klartext — das verhindert einen Schreibpfad, der die
+// Verschlüsselung vergisst (Akzeptanzkriterium 1).
+type Service struct {
+	storage *storage.Service
+	crypto  *crypto.Service
+}
+
+func NewService(storageSvc *storage.Service, cryptoSvc *crypto.Service) *Service {
+	return &Service{storage: storageSvc, crypto: cryptoSvc}
+}
+
+// Put verschlüsselt plaintext (Akzeptanzkriterium 1/2: neuer DEK je
+// Objekt, mit dem per API-12 bezogenen Tenant-KEK verpackt) und legt
+// Chiffretext + verpackten DEK über storage.Service ab (Prüfsumme,
+// Nutzungsmeldung — ARC-01 unverändert wiederverwendet).
+func (s *Service) Put(ctx context.Context, tenantSlug, key string, plaintext io.Reader, contentType string) error {
+	env, err := s.crypto.Seal(ctx, tenantSlug, plaintext)
+	if err != nil {
+		return fmt.Errorf("encstorage: verschlüsseln: %w", err)
+	}
+	ciphertext, err := io.ReadAll(env.Ciphertext)
+	if err != nil {
+		return fmt.Errorf("encstorage: chiffretext lesen: %w", err)
+	}
+	if _, err := s.storage.Put(ctx, key, bytes.NewReader(ciphertext), int64(len(ciphertext)), contentType); err != nil {
+		return fmt.Errorf("encstorage: chiffretext speichern: %w", err)
+	}
+	if _, err := s.storage.Put(ctx, wrappedDEKKey(key), bytes.NewReader(env.WrappedDEK), int64(len(env.WrappedDEK)), "application/octet-stream"); err != nil {
+		return fmt.Errorf("encstorage: verpackten dek speichern: %w", err)
+	}
+	if env.KEKVersion != 0 {
+		versionBytes := []byte(strconv.Itoa(env.KEKVersion))
+		if _, err := s.storage.Put(ctx, kekVersionKey(key), bytes.NewReader(versionBytes), int64(len(versionBytes)), "text/plain"); err != nil {
+			return fmt.Errorf("encstorage: kek-version speichern: %w", err)
+		}
+	}
+	return nil
+}
+
+// GetDecrypted liest Chiffretext (über storage.GetVerified — ARC-01s
+// Prüfsummenverifikation wird dabei mitgenutzt) und verpackten DEK,
+// entpackt den DEK mit dem AKTUELLEN Tenant-KEK und entschlüsselt den
+// Inhalt (Akzeptanzkriterium 3: nur mit gültigem, mandantenbezogenem
+// Schlüssel möglich).
+func (s *Service) GetDecrypted(ctx context.Context, tenantSlug, key string) ([]byte, error) {
+	ciphertext, err := s.storage.GetVerified(ctx, key)
+	if err != nil {
+		return nil, fmt.Errorf("encstorage: chiffretext lesen: %w", err)
+	}
+	dekReader, err := s.storage.Get(ctx, wrappedDEKKey(key))
+	if err != nil {
+		return nil, fmt.Errorf("encstorage: verpackten dek lesen: %w", err)
+	}
+	defer func() { _ = dekReader.Close() }()
+	wrappedDEK, err := io.ReadAll(dekReader)
+	if err != nil {
+		return nil, fmt.Errorf("encstorage: verpackten dek lesen: %w", err)
+	}
+
+	kekVersion, err := s.readKEKVersion(ctx, key)
+	if err != nil {
+		return nil, err
+	}
+
+	plaintextReader, err := s.crypto.OpenAtVersion(ctx, tenantSlug, kekVersion, wrappedDEK, bytes.NewReader(ciphertext))
+	if err != nil {
+		return nil, err
+	}
+	return io.ReadAll(plaintextReader)
+}
+
+// readKEKVersion liest den Versions-Sidecar (ARC-08). Fehlt er (vor
+// ARC-08 geschriebene Objekte, oder ein Seal ohne konfigurierten
+// KEKVersionStore), gilt Version 0 — crypto.Service.OpenAtVersion fällt
+// dafür auf das unveränderte Open-Verhalten zurück.
+func (s *Service) readKEKVersion(ctx context.Context, key string) (int, error) {
+	reader, err := s.storage.Get(ctx, kekVersionKey(key))
+	if err != nil {
+		if errors.Is(err, storage.ErrNotFound) {
+			return 0, nil
+		}
+		return 0, fmt.Errorf("encstorage: kek-version lesen: %w", err)
+	}
+	defer func() { _ = reader.Close() }()
+	raw, err := io.ReadAll(reader)
+	if err != nil {
+		return 0, fmt.Errorf("encstorage: kek-version lesen: %w", err)
+	}
+	version, err := strconv.Atoi(string(raw))
+	if err != nil {
+		return 0, fmt.Errorf("encstorage: kek-version parsen: %w", err)
+	}
+	return version, nil
+}

mail/internal/encstorage/encstorage_test.go

@@ -0,0 +1,138 @@
+package encstorage
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"gitea.perlbach24.de/scripte/nexarch/mail/internal/crypto"
+	"gitea.perlbach24.de/scripte/nexarch/mail/internal/storage"
+)
+
+type fakeUsageReporter struct{}
+
+func (fakeUsageReporter) Report(_ context.Context, _, _ string, _ int64) error { return nil }
+
+// fakeKEKProvider liefert einen festen, mandantenspezifischen KEK —
+// simuliert Core API-12, ohne den echten Dienst für Unit-Tests zu
+// brauchen. "richtiger-tenant" hat einen bekannten KEK, jeder andere
+// Tenant-Slug liefert einen ANDEREN (falschen) KEK — genau der Fall,
+// den Pflichtprüfung 2 testet.
+type fakeKEKProvider struct {
+	keksByTenant map[string][]byte
+}
+
+func (f fakeKEKProvider) TenantKEK(_ context.Context, tenantSlug string) ([]byte, error) {
+	if kek, ok := f.keksByTenant[tenantSlug]; ok {
+		return kek, nil
+	}
+	// Unbekannter Tenant bekommt einen ANDEREN zufälligen KEK (nicht
+	// abgelehnt auf Core-Seite in diesem Fake, aber garantiert falsch —
+	// entspricht dem realen Fall, dass ein falscher Tenant-Slug einen
+	// anderen KEK liefert und die Entschlüsselung deshalb scheitert).
+	return bytes.Repeat([]byte{0xFF}, crypto.KEKSize), nil
+}
+
+func newTestServiceWithDir(t *testing.T) (*Service, string) {
+	t.Helper()
+	dir := t.TempDir()
+	storageSvc := storage.NewService(storage.NewLocalDriver(dir), fakeUsageReporter{}, "acme")
+	kekProvider := fakeKEKProvider{keksByTenant: map[string][]byte{
+		"richtiger-tenant": bytes.Repeat([]byte{0x42}, crypto.KEKSize),
+	}}
+	cryptoSvc := crypto.NewService(kekProvider)
+	return NewService(storageSvc, cryptoSvc), dir
+}
+
+// TestPut_RawStorageAccessWithoutKeyYieldsNoReadableContent ist die
+// geforderte Pflichtprüfung 1: Zugriff auf Rohspeicher ohne Schlüssel
+// liefert keine lesbaren Inhalte.
+func TestPut_RawStorageAccessWithoutKeyYieldsNoReadableContent(t *testing.T) {
+	svc, dir := newTestServiceWithDir(t)
+	ctx := context.Background()
+	key := storage.ObjectKey("msg-enc-1", 0)
+	plaintext := "STRENG GEHEIMER E-MAIL-INHALT, NICHT IM KLARTEXT AUF DER PLATTE"
+
+	if err := svc.Put(ctx, "richtiger-tenant", key, strings.NewReader(plaintext), "text/plain"); err != nil {
+		t.Fatalf("put: %v", err)
+	}
+
+	// Direkter Dateisystemzugriff, UMGEHT den Service/die Entschlüsselung
+	// vollständig — simuliert "Rohspeicher ohne Schlüssel".
+	raw, err := os.ReadFile(filepath.Join(dir, filepath.FromSlash(key)))
+	if err != nil {
+		t.Fatalf("rohdatei lesen: %v", err)
+	}
+	if bytes.Contains(raw, []byte(plaintext)) {
+		t.Fatalf("klartext ist unverschlüsselt im rohspeicher auffindbar: %q enthält %q", raw, plaintext)
+	}
+	if bytes.Contains(raw, []byte("STRENG GEHEIMER")) || bytes.Contains(raw, []byte("GEHEIM")) {
+		t.Fatal("erkennbare klartext-fragmente im rohspeicher gefunden")
+	}
+}
+
+// TestGetDecrypted_WrongTenantKeyDeniesDecryption ist die geforderte
+// Pflichtprüfung 2: falscher Mandantenschlüssel verweigert
+// Entschlüsselung.
+func TestGetDecrypted_WrongTenantKeyDeniesDecryption(t *testing.T) {
+	svc, _ := newTestServiceWithDir(t)
+	ctx := context.Background()
+	key := storage.ObjectKey("msg-enc-2", 0)
+	plaintext := "inhalt fuer richtiger-tenant"
+
+	if err := svc.Put(ctx, "richtiger-tenant", key, strings.NewReader(plaintext), "text/plain"); err != nil {
+		t.Fatalf("put: %v", err)
+	}
+
+	// Korrekter Tenant kann entschlüsseln.
+	got, err := svc.GetDecrypted(ctx, "richtiger-tenant", key)
+	if err != nil {
+		t.Fatalf("getdecrypted (richtiger tenant): %v", err)
+	}
+	if string(got) != plaintext {
+		t.Fatalf("falscher inhalt: %q", got)
+	}
+
+	// FALSCHER Mandant (anderer Tenant-Slug -> anderer KEK) muss
+	// abgelehnt werden.
+	_, err = svc.GetDecrypted(ctx, "falscher-tenant", key)
+	if !errors.Is(err, crypto.ErrDecryptFailed) {
+		t.Fatalf("erwartet ErrDecryptFailed bei falschem mandantenschlüssel, habe: %v", err)
+	}
+}
+
+// TestPut_AcceptableEncryptionOverhead ist die geforderte
+// Pflichtprüfung 3: Performance-Test bestätigt akzeptablen Overhead
+// durch Verschlüsselung.
+func TestPut_AcceptableEncryptionOverhead(t *testing.T) {
+	svc, _ := newTestServiceWithDir(t)
+	ctx := context.Background()
+
+	// ~64 KiB Nutzlast, realistische Anhanggröße.
+	payload := strings.Repeat("x", 64*1024)
+
+	const count = 50
+	start := time.Now()
+	for i := 0; i < count; i++ {
+		key := storage.ObjectKey("msg-perf", i)
+		if err := svc.Put(ctx, "richtiger-tenant", key, strings.NewReader(payload), "application/octet-stream"); err != nil {
+			t.Fatalf("put #%d: %v", i, err)
+		}
+	}
+	elapsed := time.Since(start)
+	avgPerObject := elapsed / count
+
+	// Großzügige Grenze (50ms je 64-KiB-Objekt inkl. AES-GCM,
+	// Prüfsumme, Sidecar-Schreiben, Rücklese-Verifikation aus ARC-01) —
+	// Ziel: Nachweis, dass Verschlüsselung keinen unverhältnismäßigen
+	// Overhead verursacht, nicht ein knallhartes SLA.
+	if avgPerObject > 50*time.Millisecond {
+		t.Fatalf("erwartet akzeptablen verschlüsselungs-overhead (<50ms/64KiB-objekt), habe %v/objekt (gesamt %v für %d objekte)", avgPerObject, elapsed, count)
+	}
+	t.Logf("Verschlüsselungs-Performance: %d×64KiB-Objekte in %v (%v/Objekt)", count, elapsed, avgPerObject)
+}

mail/internal/example/handler.go

@@ -0,0 +1,36 @@
+package example
+
+import (
+	"encoding/json"
+	"net/http"
+)
+
+// NormalizeHandler ist das E2E-Test-Beispiel (QA-01): ein echter
+// HTTP-Endpunkt, gegen den ein Test einen vollständigen Request-Response-
+// Zyklus fährt (httptest.Server, echter TCP-Roundtrip, kein reiner
+// Funktionsaufruf). Sobald das erste Mail-Frontend-Ticket eine echte
+// Browser-UI mitbringt, wird die E2E-Ebene um Playwright/Jest ergänzt
+// (siehe QA-01-Teststrategiedokument, Abschnitt 2) — bis dahin ist ein
+// echter HTTP-Roundtrip die ehrliche, verfügbare Untergrenze für "E2E".
+type normalizeRequest struct {
+	Address string `json:"address"`
+}
+
+type normalizeResponse struct {
+	Normalized string `json:"normalized"`
+}
+
+func NormalizeHandler(w http.ResponseWriter, r *http.Request) {
+	var req normalizeRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		http.Error(w, "ungültiger request-body", http.StatusBadRequest)
+		return
+	}
+	normalized, err := NormalizeAddress(req.Address)
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+	w.Header().Set("Content-Type", "application/json")
+	_ = json.NewEncoder(w).Encode(normalizeResponse{Normalized: normalized})
+}

mail/internal/example/handler_e2e_test.go

@@ -0,0 +1,51 @@
+// E2E-Test-Beispiel (QA-01 Akzeptanzkriterium 1/Prüfung 2): echter
+// HTTP-Request über einen laufenden httptest.Server (TCP-Roundtrip),
+// nicht nur ein Funktionsaufruf im selben Prozess.
+package example
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+)
+
+func TestNormalizeHandler_RealHTTPRoundTrip(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(NormalizeHandler))
+	defer server.Close()
+
+	body, _ := json.Marshal(normalizeRequest{Address: "Kunde@Beispiel.DE"})
+	resp, err := http.Post(server.URL, "application/json", bytes.NewReader(body))
+	if err != nil {
+		t.Fatalf("post: %v", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("status = %d, want 200", resp.StatusCode)
+	}
+	var out normalizeResponse
+	if err := json.NewDecoder(resp.Body).Decode(&out); err != nil {
+		t.Fatalf("antwort dekodieren: %v", err)
+	}
+	if out.Normalized != "Kunde@beispiel.de" {
+		t.Fatalf("got %q", out.Normalized)
+	}
+}
+
+func TestNormalizeHandler_InvalidAddressReturns400(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(NormalizeHandler))
+	defer server.Close()
+
+	body, _ := json.Marshal(normalizeRequest{Address: "keine-gueltige-adresse"})
+	resp, err := http.Post(server.URL, "application/json", bytes.NewReader(body))
+	if err != nil {
+		t.Fatalf("post: %v", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	if resp.StatusCode != http.StatusBadRequest {
+		t.Fatalf("status = %d, want 400", resp.StatusCode)
+	}
+}

mail/internal/example/normalize.go

@@ -0,0 +1,26 @@
+// Package example dient QA-01 (Mail): liefert je Testart (Unit,
+// Integration, E2E) genau EIN reales, lauffähiges Beispiel, an dem sich
+// spätere Mail-Tickets orientieren können — keine Wegwerf-Demo, sondern
+// eine tatsächlich nützliche, kleine Funktion (Adress-Normalisierung),
+// die spätere Ticket (z. B. ING-01/ING-04) ohnehin brauchen werden.
+package example
+
+import (
+	"errors"
+	"strings"
+)
+
+var ErrInvalidAddress = errors.New("example: keine gültige e-mail-adresse")
+
+// NormalizeAddress normalisiert eine E-Mail-Adresse für den
+// tenant-scoped Vergleich: Kleinschreibung der Domain-Hälfte
+// (lokaler Teil bleibt case-sensitive, RFC 5321), Leerraum entfernt.
+func NormalizeAddress(addr string) (string, error) {
+	addr = strings.TrimSpace(addr)
+	at := strings.LastIndex(addr, "@")
+	if at <= 0 || at == len(addr)-1 {
+		return "", ErrInvalidAddress
+	}
+	local, domain := addr[:at], addr[at+1:]
+	return local + "@" + strings.ToLower(domain), nil
+}

mail/internal/example/normalize_test.go

@@ -0,0 +1,38 @@
+// Unit-Test-Beispiel (QA-01 Akzeptanzkriterium 1/Prüfung 2): keine
+// externe Abhängigkeit (DB, Netzwerk), reine Funktionsprüfung.
+package example
+
+import (
+	"errors"
+	"testing"
+)
+
+func TestNormalizeAddress_LowercasesDomainOnly(t *testing.T) {
+	got, err := NormalizeAddress("User.Name@Example.COM")
+	if err != nil {
+		t.Fatalf("unerwarteter fehler: %v", err)
+	}
+	want := "User.Name@example.com"
+	if got != want {
+		t.Fatalf("got %q, want %q", got, want)
+	}
+}
+
+func TestNormalizeAddress_TrimsWhitespace(t *testing.T) {
+	got, err := NormalizeAddress("  user@example.com  ")
+	if err != nil {
+		t.Fatalf("unerwarteter fehler: %v", err)
+	}
+	if got != "user@example.com" {
+		t.Fatalf("got %q", got)
+	}
+}
+
+func TestNormalizeAddress_RejectsInvalidInput(t *testing.T) {
+	cases := []string{"", "no-at-sign", "@nolocalpart.com", "trailing@"}
+	for _, c := range cases {
+		if _, err := NormalizeAddress(c); !errors.Is(err, ErrInvalidAddress) {
+			t.Fatalf("input %q: erwartet ErrInvalidAddress, habe: %v", c, err)
+		}
+	}
+}

mail/internal/example/store.go

@@ -0,0 +1,42 @@
+package example
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+// AddressStore ist das Integrationstest-Beispiel (QA-01): eine
+// minimale, aber echte DB-gestützte Komponente — nutzt dieselbe
+// Tenant-DB-Isolationskonvention wie DMS/Archive (t.Cleanup, geteilte
+// physische Postgres-Instanz auf dem Testhost).
+type AddressStore struct {
+	pool *pgxpool.Pool
+}
+
+func NewAddressStore(pool *pgxpool.Pool) *AddressStore {
+	return &AddressStore{pool: pool}
+}
+
+func (s *AddressStore) SaveNormalized(ctx context.Context, addr string) (string, error) {
+	normalized, err := NormalizeAddress(addr)
+	if err != nil {
+		return "", err
+	}
+	if _, err := s.pool.Exec(ctx, `
+		INSERT INTO example_addresses (address) VALUES ($1)
+		ON CONFLICT (address) DO NOTHING
+	`, normalized); err != nil {
+		return "", fmt.Errorf("example: adresse speichern: %w", err)
+	}
+	return normalized, nil
+}
+
+func (s *AddressStore) Exists(ctx context.Context, addr string) (bool, error) {
+	var exists bool
+	if err := s.pool.QueryRow(ctx, `SELECT EXISTS(SELECT 1 FROM example_addresses WHERE address = $1)`, addr).Scan(&exists); err != nil {
+		return false, fmt.Errorf("example: existenz prüfen: %w", err)
+	}
+	return exists, nil
+}

mail/internal/example/store_integration_test.go

@@ -0,0 +1,69 @@
+// Integrations-Test-Beispiel (QA-01 Akzeptanzkriterium 1/Prüfung 2):
+// echte Postgres-Instanz, folgt derselben Testhost-Konvention wie
+// DMS/Archive/Core (TEST_TENANT_DSN, t.Cleanup, geteilte physische
+// Instanz auf 192.168.1.131 — siehe project-nexarch-test-infra).
+package example
+
+import (
+	"context"
+	"os"
+	"testing"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+func setupTest(t *testing.T) *pgxpool.Pool {
+	t.Helper()
+	dsn := os.Getenv("TEST_TENANT_DSN")
+	if dsn == "" {
+		t.Skip("TEST_TENANT_DSN nicht gesetzt, Integrationstest übersprungen")
+	}
+	ctx := context.Background()
+	pool, err := pgxpool.New(ctx, dsn)
+	if err != nil {
+		t.Fatalf("pool: %v", err)
+	}
+	t.Cleanup(func() { pool.Close() })
+
+	if _, err := pool.Exec(ctx, `
+		CREATE TABLE IF NOT EXISTS example_addresses (
+			address TEXT PRIMARY KEY
+		);
+	`); err != nil {
+		t.Fatalf("schema: %v", err)
+	}
+	t.Cleanup(func() {
+		_, _ = pool.Exec(context.Background(), `TRUNCATE example_addresses`)
+	})
+	return pool
+}
+
+func TestAddressStore_SaveAndCheckExists(t *testing.T) {
+	pool := setupTest(t)
+	store := NewAddressStore(pool)
+	ctx := context.Background()
+
+	normalized, err := store.SaveNormalized(ctx, "Kunde@Beispiel.DE")
+	if err != nil {
+		t.Fatalf("savenormalized: %v", err)
+	}
+	if normalized != "Kunde@beispiel.de" {
+		t.Fatalf("erwartet normalisierte adresse, habe %q", normalized)
+	}
+
+	exists, err := store.Exists(ctx, normalized)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !exists {
+		t.Fatal("erwartet real gespeicherte adresse")
+	}
+
+	notExists, err := store.Exists(ctx, "unbekannt@beispiel.de")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if notExists {
+		t.Fatal("nie gespeicherte adresse haette nicht existieren duerfen")
+	}
+}

mail/internal/folderstate/migrations/0001_mail_folder_state.sql

@@ -0,0 +1,9 @@
+CREATE TABLE IF NOT EXISTS mail_folder_state (
+    tenant_slug  TEXT NOT NULL,
+    mailbox_name TEXT NOT NULL,
+    uidvalidity  BIGINT NOT NULL,
+    uidnext      BIGINT NOT NULL,
+    created_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
+    PRIMARY KEY (tenant_slug, mailbox_name)
+)

mail/internal/folderstate/migrations/0002_mail_folder_state_events.sql

@@ -0,0 +1,8 @@
+CREATE TABLE IF NOT EXISTS mail_folder_state_events (
+    id           BIGSERIAL PRIMARY KEY,
+    tenant_slug  TEXT NOT NULL,
+    mailbox_name TEXT NOT NULL,
+    event_type   TEXT NOT NULL CHECK (event_type IN ('uid_assigned', 'deleted', 'rebuilt')),
+    uid          BIGINT,
+    created_at   TIMESTAMPTZ NOT NULL DEFAULT now()
+)

mail/internal/folderstate/store.go

@@ -0,0 +1,251 @@
+// Package folderstate implementiert ING-05: Folder-State-Verwaltung
+// inklusive UIDVALIDITY/UIDNEXT-Handling für IMAP-Ordner (RFC 3501
+// §2.3.1.1), damit Clients (mail/internal/imap, ING-01) und
+// Importvorgänge (IMP-01) konsistente Sichten erhalten. Persistiert in
+// Postgres, gleiches Muster wie mail/internal/dedup/indexworker/
+// savedsearch — kein zentraler Migrationsläufer für Mandanten-
+// Datenbanken im Mail-Modul vorhanden, EnsureSchema legt die Tabellen
+// idempotent an.
+//
+// Bekannten Fehler vermeiden (siehe ING-01/repos-analyse-mail-reuse.md):
+// archivmail brach den Resync bei UIDVALIDITY=0 nicht-konformer Server —
+// dieses Paket erzeugt UIDVALIDITY selbst (Unix-Zeitstempel beim
+// Ordner-Neuaufbau, garantiert > 0 und monoton wachsend über
+// aufeinanderfolgende Neuaufbauten hinweg) statt einen von außen
+// gelieferten Wert unbesehen zu übernehmen.
+package folderstate
+
+import (
+	"context"
+	_ "embed"
+	"errors"
+	"fmt"
+	"time"
+
+	"github.com/jackc/pgx/v5"
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+//go:embed migrations/0001_mail_folder_state.sql
+var schemaMigration string
+
+//go:embed migrations/0002_mail_folder_state_events.sql
+var eventsSchemaMigration string
+
+// EventType (Akzeptanzkriterium 3: State-Änderungen nachvollziehbar
+// persistiert).
+const (
+	EventUIDAssigned = "uid_assigned"
+	EventDeleted     = "deleted"
+	EventRebuilt     = "rebuilt"
+)
+
+// FolderState ist der aktuelle UIDVALIDITY/UIDNEXT-Zustand eines Ordners.
+type FolderState struct {
+	TenantSlug  string
+	MailboxName string
+	UIDValidity uint64
+	UIDNext     uint64
+}
+
+// Event ist ein einzelner, nachvollziehbarer Zustandsänderungseintrag.
+type Event struct {
+	EventType string
+	UID       *uint64
+	CreatedAt time.Time
+}
+
+// Store verwaltet Folder-State je Mandant und Postfach.
+type Store struct {
+	pool *pgxpool.Pool
+	// now ist austauschbar für Tests (deterministische UIDVALIDITY-Werte).
+	now func() time.Time
+}
+
+func NewStore(pool *pgxpool.Pool) *Store {
+	return &Store{pool: pool, now: time.Now}
+}
+
+// EnsureSchema legt die Tabellen an, falls sie noch nicht existieren.
+func (s *Store) EnsureSchema(ctx context.Context) error {
+	if _, err := s.pool.Exec(ctx, schemaMigration); err != nil {
+		return fmt.Errorf("folderstate: schema anlegen: %w", err)
+	}
+	if _, err := s.pool.Exec(ctx, eventsSchemaMigration); err != nil {
+		return fmt.Errorf("folderstate: ereignis-schema anlegen: %w", err)
+	}
+	return nil
+}
+
+// GetOrCreate liefert den aktuellen Zustand eines Ordners und legt ihn
+// bei erstem Zugriff neu an (UIDNEXT beginnt bei 1, RFC 3501 §2.3.1.1).
+// Konsistent bei parallelem Zugriff (Akzeptanzkriterium 2): INSERT ...
+// ON CONFLICT DO NOTHING + Rücklese, kein Lese-dann-Schreib-Fenster.
+func (s *Store) GetOrCreate(ctx context.Context, tenantSlug, mailboxName string) (FolderState, error) {
+	uidvalidity := s.newUIDValidity()
+	if _, err := s.pool.Exec(ctx, `
+		INSERT INTO mail_folder_state (tenant_slug, mailbox_name, uidvalidity, uidnext)
+		VALUES ($1, $2, $3, 1)
+		ON CONFLICT (tenant_slug, mailbox_name) DO NOTHING
+	`, tenantSlug, mailboxName, uidvalidity); err != nil {
+		return FolderState{}, fmt.Errorf("folderstate: ordner anlegen: %w", err)
+	}
+	return s.CurrentState(ctx, tenantSlug, mailboxName)
+}
+
+// CurrentState liest den Zustand ohne ihn anzulegen (Akzeptanzkriterium
+// 2: konsistente Sicht bei SELECT/EXAMINE).
+func (s *Store) CurrentState(ctx context.Context, tenantSlug, mailboxName string) (FolderState, error) {
+	var st FolderState
+	st.TenantSlug = tenantSlug
+	st.MailboxName = mailboxName
+	err := s.pool.QueryRow(ctx, `
+		SELECT uidvalidity, uidnext FROM mail_folder_state
+		WHERE tenant_slug = $1 AND mailbox_name = $2
+	`, tenantSlug, mailboxName).Scan(&st.UIDValidity, &st.UIDNext)
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return FolderState{}, ErrNotFound
+		}
+		return FolderState{}, fmt.Errorf("folderstate: zustand lesen: %w", err)
+	}
+	return st, nil
+}
+
+// ErrNotFound wird geliefert, wenn für den angefragten Ordner noch kein
+// Zustand existiert (GetOrCreate anlegen lassen, statt hier zu raten).
+var ErrNotFound = errors.New("folderstate: ordner nicht gefunden")
+
+// NextUID vergibt atomar die nächste UID für eine neu eintreffende
+// Nachricht (Akzeptanzkriterium 1/3) und protokolliert die Vergabe.
+// Nebenläufigkeitssicher: UPDATE ... RETURNING läuft unter Postgres'
+// Zeilensperre, zwei gleichzeitige Aufrufe für denselben Ordner können
+// niemals dieselbe UID liefern (Pflichtprüfung 2).
+func (s *Store) NextUID(ctx context.Context, tenantSlug, mailboxName string) (uid uint64, err error) {
+	tx, err := s.pool.Begin(ctx)
+	if err != nil {
+		return 0, fmt.Errorf("folderstate: transaktion starten: %w", err)
+	}
+	defer func() { _ = tx.Rollback(ctx) }()
+
+	err = tx.QueryRow(ctx, `
+		UPDATE mail_folder_state
+		SET uidnext = uidnext + 1, updated_at = now()
+		WHERE tenant_slug = $1 AND mailbox_name = $2
+		RETURNING uidnext - 1
+	`, tenantSlug, mailboxName).Scan(&uid)
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return 0, ErrNotFound
+		}
+		return 0, fmt.Errorf("folderstate: uid vergeben: %w", err)
+	}
+
+	if _, err := tx.Exec(ctx, `
+		INSERT INTO mail_folder_state_events (tenant_slug, mailbox_name, event_type, uid)
+		VALUES ($1, $2, $3, $4)
+	`, tenantSlug, mailboxName, EventUIDAssigned, uid); err != nil {
+		return 0, fmt.Errorf("folderstate: ereignis protokollieren: %w", err)
+	}
+
+	if err := tx.Commit(ctx); err != nil {
+		return 0, fmt.Errorf("folderstate: uid-vergabe committen: %w", err)
+	}
+	return uid, nil
+}
+
+// RecordDeletion protokolliert die Löschung einer Nachricht mit
+// gegebener UID (Akzeptanzkriterium 3). UIDNEXT bleibt unverändert —
+// gelöschte UIDs werden gemäß RFC 3501 niemals wiederverwendet.
+func (s *Store) RecordDeletion(ctx context.Context, tenantSlug, mailboxName string, uid uint64) error {
+	if _, err := s.pool.Exec(ctx, `
+		INSERT INTO mail_folder_state_events (tenant_slug, mailbox_name, event_type, uid)
+		VALUES ($1, $2, $3, $4)
+	`, tenantSlug, mailboxName, EventDeleted, uid); err != nil {
+		return fmt.Errorf("folderstate: löschung protokollieren: %w", err)
+	}
+	return nil
+}
+
+// Rebuild simuliert einen Ordner-Neuaufbau (z. B. nach erkannter
+// Inkonsistenz oder bei einem Server, der seinerseits eine neue
+// UIDVALIDITY meldet): vergibt eine garantiert neue UIDVALIDITY und
+// setzt UIDNEXT zurück auf 1 (Pflichtprüfung 1).
+func (s *Store) Rebuild(ctx context.Context, tenantSlug, mailboxName string) (FolderState, error) {
+	candidateUIDValidity := s.newUIDValidity()
+
+	tx, err := s.pool.Begin(ctx)
+	if err != nil {
+		return FolderState{}, fmt.Errorf("folderstate: transaktion starten: %w", err)
+	}
+	defer func() { _ = tx.Rollback(ctx) }()
+
+	// GREATEST(...)+1 garantiert eine STRENG größere UIDVALIDITY als die
+	// bisherige, unabhängig von der Uhrenauflösung — zwei Neuaufbauten
+	// innerhalb derselben Nanosekunde dürfen niemals denselben Wert
+	// liefern (Pflichtprüfung 1).
+	var newUIDValidity uint64
+	err = tx.QueryRow(ctx, `
+		UPDATE mail_folder_state
+		SET uidvalidity = GREATEST(uidvalidity + 1, $3), uidnext = 1, updated_at = now()
+		WHERE tenant_slug = $1 AND mailbox_name = $2
+		RETURNING uidvalidity
+	`, tenantSlug, mailboxName, candidateUIDValidity).Scan(&newUIDValidity)
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return FolderState{}, ErrNotFound
+		}
+		return FolderState{}, fmt.Errorf("folderstate: neuaufbau: %w", err)
+	}
+
+	if _, err := tx.Exec(ctx, `
+		INSERT INTO mail_folder_state_events (tenant_slug, mailbox_name, event_type)
+		VALUES ($1, $2, $3)
+	`, tenantSlug, mailboxName, EventRebuilt); err != nil {
+		return FolderState{}, fmt.Errorf("folderstate: neuaufbau-ereignis protokollieren: %w", err)
+	}
+
+	if err := tx.Commit(ctx); err != nil {
+		return FolderState{}, fmt.Errorf("folderstate: neuaufbau committen: %w", err)
+	}
+	return FolderState{TenantSlug: tenantSlug, MailboxName: mailboxName, UIDValidity: newUIDValidity, UIDNext: 1}, nil
+}
+
+// Events liefert die protokollierten Zustandsänderungen eines Ordners in
+// zeitlicher Reihenfolge (Akzeptanzkriterium 3: nachvollziehbar).
+func (s *Store) Events(ctx context.Context, tenantSlug, mailboxName string) ([]Event, error) {
+	rows, err := s.pool.Query(ctx, `
+		SELECT event_type, uid, created_at FROM mail_folder_state_events
+		WHERE tenant_slug = $1 AND mailbox_name = $2
+		ORDER BY id ASC
+	`, tenantSlug, mailboxName)
+	if err != nil {
+		return nil, fmt.Errorf("folderstate: ereignisse lesen: %w", err)
+	}
+	defer rows.Close()
+
+	var events []Event
+	for rows.Next() {
+		var e Event
+		var uid *int64
+		if err := rows.Scan(&e.EventType, &uid, &e.CreatedAt); err != nil {
+			return nil, fmt.Errorf("folderstate: ereigniszeile lesen: %w", err)
+		}
+		if uid != nil {
+			u := uint64(*uid)
+			e.UID = &u
+		}
+		events = append(events, e)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, fmt.Errorf("folderstate: ereignisse iterieren: %w", err)
+	}
+	return events, nil
+}
+
+// newUIDValidity erzeugt eine garantiert positive, für praktische Zwecke
+// eindeutige UIDVALIDITY (Unix-Nanosekunden) — vermeidet den bekannten
+// archivmail-Fehler UIDVALIDITY=0.
+func (s *Store) newUIDValidity() uint64 {
+	return uint64(s.now().UnixNano())
+}

mail/internal/folderstate/store_test.go

@@ -0,0 +1,176 @@
+// Integrationstest (ING-05): echte Postgres-Instanz, folgt derselben
+// Testhost-Konvention wie mail/internal/dedup/indexworker/savedsearch —
+// TEST_TENANT_DSN.
+package folderstate
+
+import (
+	"context"
+	"os"
+	"sync"
+	"testing"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+func setupStore(t *testing.T) *Store {
+	t.Helper()
+	dsn := os.Getenv("TEST_TENANT_DSN")
+	if dsn == "" {
+		t.Skip("TEST_TENANT_DSN nicht gesetzt, Integrationstest übersprungen")
+	}
+	ctx := context.Background()
+	pool, err := pgxpool.New(ctx, dsn)
+	if err != nil {
+		t.Fatalf("pool: %v", err)
+	}
+	t.Cleanup(func() { pool.Close() })
+
+	store := NewStore(pool)
+	if err := store.EnsureSchema(ctx); err != nil {
+		t.Fatalf("schema: %v", err)
+	}
+	t.Cleanup(func() {
+		ctx := context.Background()
+		_, _ = pool.Exec(ctx, `DELETE FROM mail_folder_state WHERE tenant_slug LIKE 'mandant-ing05-%'`)
+		_, _ = pool.Exec(ctx, `DELETE FROM mail_folder_state_events WHERE tenant_slug LIKE 'mandant-ing05-%'`)
+	})
+	return store
+}
+
+// TestRebuild_ChangesUIDValidityOnSimulatedFolderRebuild ist die
+// geforderte Pflichtprüfung 1: automatisierter Test für
+// UIDVALIDITY-Änderung bei simuliertem Ordner-Neuaufbau.
+func TestRebuild_ChangesUIDValidityOnSimulatedFolderRebuild(t *testing.T) {
+	store := setupStore(t)
+	ctx := context.Background()
+	tenant := "mandant-ing05-rebuild"
+
+	initial, err := store.GetOrCreate(ctx, tenant, "INBOX")
+	if err != nil {
+		t.Fatalf("getorcreate: %v", err)
+	}
+	if initial.UIDValidity == 0 {
+		t.Fatal("erwartete uidvalidity != 0 (bekannter archivmail-fehler vermeiden)")
+	}
+
+	// UIDNEXT vor dem Neuaufbau real erhöhen, damit der Reset auf 1
+	// nachweisbar ist.
+	if _, err := store.NextUID(ctx, tenant, "INBOX"); err != nil {
+		t.Fatalf("nextuid: %v", err)
+	}
+
+	rebuilt, err := store.Rebuild(ctx, tenant, "INBOX")
+	if err != nil {
+		t.Fatalf("rebuild: %v", err)
+	}
+	if rebuilt.UIDValidity == initial.UIDValidity {
+		t.Fatalf("erwartete geänderte uidvalidity nach neuaufbau, habe weiterhin %d", rebuilt.UIDValidity)
+	}
+	if rebuilt.UIDNext != 1 {
+		t.Fatalf("erwartete uidnext=1 nach neuaufbau, habe %d", rebuilt.UIDNext)
+	}
+
+	events, err := store.Events(ctx, tenant, "INBOX")
+	if err != nil {
+		t.Fatalf("events: %v", err)
+	}
+	found := false
+	for _, e := range events {
+		if e.EventType == EventRebuilt {
+			found = true
+		}
+	}
+	if !found {
+		t.Fatal("erwartete protokolliertes 'rebuilt'-ereignis (akzeptanzkriterium 3: nachvollziehbar)")
+	}
+}
+
+// TestNextUID_ConcurrentSessionsOnSameFolderNoInconsistency ist die
+// geforderte Pflichtprüfung 2: Nebenläufigkeitstest — zwei Sessions auf
+// demselben Ordner ohne Inkonsistenz.
+func TestNextUID_ConcurrentSessionsOnSameFolderNoInconsistency(t *testing.T) {
+	store := setupStore(t)
+	ctx := context.Background()
+	tenant := "mandant-ing05-concurrent"
+
+	if _, err := store.GetOrCreate(ctx, tenant, "INBOX"); err != nil {
+		t.Fatalf("getorcreate: %v", err)
+	}
+
+	const parallelSessions = 20
+	var wg sync.WaitGroup
+	uids := make(chan uint64, parallelSessions)
+	errs := make(chan error, parallelSessions)
+
+	for i := 0; i < parallelSessions; i++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			uid, err := store.NextUID(ctx, tenant, "INBOX")
+			if err != nil {
+				errs <- err
+				return
+			}
+			uids <- uid
+		}()
+	}
+	wg.Wait()
+	close(uids)
+	close(errs)
+
+	for err := range errs {
+		t.Fatalf("nextuid unter nebenläufigkeit: %v", err)
+	}
+
+	seen := make(map[uint64]bool, parallelSessions)
+	for uid := range uids {
+		if seen[uid] {
+			t.Fatalf("uid %d doppelt vergeben — inkonsistenz unter nebenläufigem zugriff", uid)
+		}
+		seen[uid] = true
+	}
+	if len(seen) != parallelSessions {
+		t.Fatalf("erwartete %d eindeutige uids, habe %d", parallelSessions, len(seen))
+	}
+}
+
+// TestNextUID_MonotonicAcrossManyInsertDeleteCycles ist die geforderte
+// Pflichtprüfung 3: Test für UIDNEXT-Monotonie über viele Einfüge-/
+// Löschzyklen.
+func TestNextUID_MonotonicAcrossManyInsertDeleteCycles(t *testing.T) {
+	store := setupStore(t)
+	ctx := context.Background()
+	tenant := "mandant-ing05-monotonie"
+
+	if _, err := store.GetOrCreate(ctx, tenant, "INBOX"); err != nil {
+		t.Fatalf("getorcreate: %v", err)
+	}
+
+	var lastUID uint64
+	for i := 0; i < 200; i++ {
+		uid, err := store.NextUID(ctx, tenant, "INBOX")
+		if err != nil {
+			t.Fatalf("nextuid (zyklus %d): %v", i, err)
+		}
+		if i > 0 && uid <= lastUID {
+			t.Fatalf("uidnext nicht monoton steigend: zyklus %d, vorherige uid=%d, neue uid=%d", i, lastUID, uid)
+		}
+		lastUID = uid
+
+		// Löschung darf UIDNEXT NICHT verändern (RFC 3501: UIDs werden nie
+		// wiederverwendet) — jede zweite Nachricht wird "gelöscht".
+		if i%2 == 0 {
+			if err := store.RecordDeletion(ctx, tenant, "INBOX", uid); err != nil {
+				t.Fatalf("recorddeletion (zyklus %d): %v", i, err)
+			}
+		}
+	}
+
+	final, err := store.CurrentState(ctx, tenant, "INBOX")
+	if err != nil {
+		t.Fatalf("currentstate: %v", err)
+	}
+	if final.UIDNext != lastUID+1 {
+		t.Fatalf("erwartete uidnext=%d nach 200 vergebenen uids, habe %d", lastUID+1, final.UIDNext)
+	}
+}