Workflow-Aufbewahrung und Archive sicher betreiben

Diese Anleitung beschreibt, wie Sie Workflow-Aufbewahrung prüfen, Archivprofile vorbereiten, einzelne Instanzen verifiziert archivieren und geschützte Nachweise erhalten. Workspace führt periodische Löschungen tenantgebunden über Taskstream aus. Die Administrationsoberfläche zeigt den Status ausschließlich read-only; verändernde Schritte führen Sie mit nucli gegen den laufenden Server aus.

Die Retention-Jobs werden nach der Installation zunächst pausiert angelegt. Aktivieren Sie sie erst nach Schema-, Inventory-, Provider- und Canary-Prüfung. Starten Sie keinen alten lokalen Workflow-Janitor parallel.

Aufbewahrungsvertrag

retention_days besitzt drei Bedeutungen:

• nicht gesetzt: den Tenant-Standard erben,
• 0: Workflow-Instanzen unbegrenzt behalten,
• größer als 0: eigene Frist des Workflows verwenden.

Workspace beginnt die Frist an einer unveränderlichen Terminalepoche. Ein Workflow, der einen terminalen Zustand verlässt und später erneut terminal wird, erhält eine neue Epoche. Die Migration erfindet keine Terminalzeit für alte Datensätze. Legacy-Instanzen ohne belastbare Epoche bleiben deshalb geschützt.

Workspace löscht eine Instanz nicht, solange mindestens einer dieser Blocker besteht:

• ein Dead-Letter-Eintrag,
• ein laufender Transition-Request oder eine laufende Execution,
• eine aktive Trigger-Delivery, ein noch nicht terminales Occurrence-Target oder eine Artefaktoperation,
• ein aktiver Legal Hold.

Terminale Request-, Execution-, Action-Checkpoint- und Trigger-Historie bleibt mindestens 365 Tage erhalten. Abgeschlossene Request-Replays bleiben mindestens 30 Tage erhalten. Aufgelöste oder nicht wiederholbare Dead Letters folgen ihrem getrennten, standardmäßig 30-tägigen Horizont; offene Dead Letters werden nicht gelöscht. Offene Claims und laufende Arbeit werden nicht als Historie gelöscht.

Inventory und Dry-Run prüfen

Lesen Sie zuerst die tenantgebundene Inventur:

nucli --tenant <mandantenalias> workflow retention inventory --json

Prüfen Sie insbesondere fehlende Terminalepochen, Dead Letters, aktive Requests, Executions, Deliveries, Artefaktoperationen, Legal Holds und die Anzahl aktuell löschbarer Instanzen.

Führen Sie danach einen Reconcile ohne Mutation aus:

nucli --tenant <mandantenalias> workflow retention reconcile --json

Ohne --apply sendet nucli ausschließlich den Preflight. Wenn Sie den begrenzten Lauf ausdrücklich freigeben, wiederholt nucli den Preflight und sendet anschließend den Apply-Request:

nucli --tenant <mandantenalias> workflow retention reconcile --apply --json

Ein Lauf verarbeitet höchstens 20 Batches mit je 500 Instanzen, insgesamt höchstens 10.000 Instanzen und höchstens fünf Minuten. Parallel laufende Worker verwenden gesperrte, übersprungene Zeilen und löschen keine Instanz doppelt.

Archivprofil einrichten

Für ein lokales, fest vom Server vorgegebenes Datenverzeichnis benötigen Sie keine Credentials:

nucli --tenant <mandantenalias> workflow retention profile set \
  --provider filesystem \
  --retention-days 365 \
  --config '{"prefix":"workflow"}'

Für S3-kompatiblen Storage hinterlegen Sie Access Key, Secret Key und gegebenenfalls Session Token als tenantgebundenes Secret. Übergeben Sie an das Archivprofil nur dessen UUID:

nucli --tenant <mandantenalias> workflow retention profile set \
  --provider s3-compatible \
  --credential-secret-id <secret-uuid> \
  --retention-days 365 \
  --config '{"endpoint":"https://objects.example","bucket":"workflow-archive","region":"eu-central-1","prefix":"nucleus"}'

Schreiben Sie keine Credential-Werte in --config, Logs, Work-Orders oder Shell-Historien. Workspace speichert nur die Secret-Referenz im Profil. Archivfristen sind entweder unbegrenzt (0) oder mindestens 365 Tage.

S3-kompatible Profile benötigen zusätzlich eine installationsweite Archiv-Egress-Freigabe. Die gesperrten globalen Schlüssel workflow.archive.egress.mode und workflow.archive.egress.allowed_destinations verwenden standardmäßig allowlist_only mit leerer Liste. Tragen Sie den normalisierten Endpoint mit Schema, Host und Port in die Allowlist ein. Workspace prüft DNS und Ziel-IP bei jeder Operation neu, pinnt den Transport auf die geprüfte Adresse und folgt keinen Redirects. Fehlt die Freigabe oder ist sie ungültig, bleibt das Profil fail-closed.

Prüfen Sie den Provider durch einen write-once/read-back-Test:

nucli --tenant <mandantenalias> workflow retention profile readiness

Ein Profil ist erst bereit, wenn Workspace das Probeobjekt unverändert zurückliest. Ein Konstruktor- oder Netzwerkcheck allein reicht nicht.

Eine Instanz explizit archivieren

Prüfen Sie zuerst ohne Mutation:

nucli --tenant <mandantenalias> workflow retention archive <instanz-uuid> --json

Der Preflight verlangt eine abgelaufene Terminalepoche, ein bereites Profil und eine Instanz ohne offene Recovery-, Request-, Trigger- oder Artefaktoperation. Ein aktiver Legal Hold blockiert die periodische Löschung, nicht aber diesen expliziten Archivpfad. Archivieren und löschen Sie anschließend explizit:

nucli --tenant <mandantenalias> workflow retention archive <instanz-uuid> --apply --json

Workspace erstellt ein versioniertes Manifest mit Definition, Kontext, Transitionshistorie, Action-Checkpoints, Recovery-, Trigger-Occurrences, Occurrence-Targets, Deliveries und Artefaktnachweisen. Zum vollständigen Nachweis gehören auch frühere Terminalepochen, alle zur Instanz gehörenden Kontexte sowie soft-gelöschte Runtime-Kinder; fremdtenantige Zeilen werden nicht still herausgefiltert. Workspace verschlüsselt das Manifest unter nucleus/workflow-archive.v1 und schreibt es write-once. Das verschlüsselte Envelope darf höchstens 64 MiB groß sein. Workspace liest die Providerantwort als begrenzten Stream, prüft tatsächliche Größe und SHA-256-Digest und vertraut weder Content-Length noch anderen Provider-Metadaten. Erst danach bindet Workspace einen aktiven Legal Hold an den Archivverifikationsbeleg und löscht die unveränderte Instanz per CAS. Ein bereits verifizierter Beleg bleibt bei einem späteren Delete-CAS-Fehler erhalten und wird beim nächsten Versuch erneut geprüft. Jeder Schreib-, Lese-, Größen-, Entschlüsselungs-, Digest-, Tenant-, Eligibility- oder CAS-Fehler lässt die Quelle unangetastet. Fremdtenantige Context-, Log-, Definitions- oder Runtime-Zeilen gelten als Daten-Drift und blockieren die Archivierung vor dem Provider-Write; Workspace filtert sie nicht still aus.

Der pausiert installierte Taskstream-Retention-Job prüft zusätzlich verifizierte Archivobjekte. Nach Ablauf der beim Snapshot gespeicherten Archivfrist löscht er das Providerobjekt ausschließlich mit der verifizierten opaque Objektversion. Ein aktiver Legal Hold und eine unbegrenzte Archivfrist blockieren die physische Löschung. Der tenantgebundene Verifikationsbeleg bleibt danach als Tombstone erhalten. Provider- Lifecycle-Regeln dürfen die gespeicherte Frist oder einen Legal Hold nicht verkürzen.

Das Löschen eines Stores löst kein verstecktes Teilarchiv mehr aus. Archivieren Sie gebundene Workflow-Instanzen zuerst explizit. Danach kann der Store die bereits entfernte Bindung lösen.

Legal Hold und Recovery-Abschluss

Setzen Sie einen append-only Legal Hold mit nachvollziehbarer Begründung:

nucli --tenant <mandantenalias> workflow retention hold <instanz-uuid> \
  --reason "Aufbewahrung für Fall 4711"

Eine Freigabe ergänzt ein neues Ereignis und überschreibt den Hold nicht:

nucli --tenant <mandantenalias> workflow retention hold <instanz-uuid> \
  --release --reason "Fall 4711 abgeschlossen"

Kann ein Dead Letter fachlich nicht wiederholt werden, schließen Sie die Recovery nur mit aktuellem Fence, Begründung und explizitem Apply:

nucli --tenant <mandantenalias> workflow recovery cancel <dead-letter-uuid> \
  --expected-fence <fence> \
  --reason "Fachlich verworfen" \
  --apply

Workspace protokolliert Actor, Korrelation und Fence. Der Dead Letter bleibt bis zum eigenen History-Horizont ein Retention-Blocker.

Berechtigungen und Abbruchsignale

Vergeben Sie nur die benötigten Berechtigungen:

• workflow_retention:read
• workflow_retention:reconcile
• workflow_retention:archive
• workflow_retention:profile_manage
• workflow_retention:legal_hold
• workflow_recovery:cancel

Brechen Sie bei einem nicht bereiten Profil, fehlenden Terminalepochen, unerwarteten Blockern, Tenant-Abweichungen oder Verifikationsfehlern ab. Brechen Sie ebenfalls ab, wenn ein erzeugtes Envelope die 64-MiB-Grenze überschreitet. Der Apply-Endpunkt meldet dafür den sicheren Code WORKFLOW_ARCHIVE_OBJECT_LIMIT_EXCEEDED. Für größere Archive ist Envelope v1 nicht vorgesehen. Profil- und Archivantworten zeigen nur stabile IDs, Status, Fristen und Readiness-Codes. Endpoint, Bucket, Prefix, Secret-Referenz, Objektpfad, Objektversion, Digest und Kryptometadaten bleiben intern. Ändern Sie keine Workflow-Daten direkt in PostgreSQL und verwenden Sie numin nicht als Remote-Retention-Client.