Add resilient emergency restore for partial BizTalk operations

docs/ACC-Runtime-Shutdown-Exception-2026-08-19.md

@@ -0,0 +1,92 @@
+# ACC-Runtime-Abbruch beim Shutdown vom 19.08.2026
+
+## Befund
+
+Der reale Shutdown auf `AV23AGPWBI01` mit Version 2.1.3 wurde bei der Receive Location `RV_PMP_Trigger_Schedule` abgebrochen. Der WMI-Aufruf `MSBTS_ReceiveLocation.Disable` meldete sinngemäß:
+
+```text
+Could not validate TransportTypeData, Address or Public Address properties for Receive Location.
+Could not load file or assembly Microsoft.BizTalk.Scheduler, Version=3.13.0.0 or one of its dependencies.
+```
+
+Die unmittelbar vorher erzeugte `before.json` blieb vorhanden. Weil der Executor die erste Schrittausnahme erneut warf, wurden alle späteren Planschritte und der Nachher-Snapshot nicht mehr ausgeführt. Anschließend wurden die Host Instances und Enterprise Single Sign-On manuell gestoppt. Damit entstand ein gemischter Teilzustand.
+
+Die Exception belegt einen Validierungs-/Assemblyfehler des Scheduler-Adapters oder einer Abhängigkeit im BizTalk-WMI-Pfad. Sie belegt nicht, dass `before.json` beschädigt wurde. Der Snapshot wurde bereits vor jeder Laufzeitmutation atomar gespeichert und bleibt die maßgebliche Wiederherstellungsquelle.
+
+## Sicherheitsproblem in Version 2.1.3
+
+- Ein isolierter Adapterfehler stoppte alle späteren unabhängigen Schritte.
+- Der erste Fehler verhinderte `shutdown-after.json` und einen strukturierten Ergebnisreport.
+- Restore-Pläne beschrieben zwar den Sollzustand aus `before.json`, prüften aber vor `Start`, `Stop`, `Enable` oder `Disable` nicht allgemein, ob dieser Zustand bereits erreicht war.
+- Ein erneuter Restore nach einem Teilabbruch konnte deshalb an einer redundanten Operation erneut stoppen.
+- Die dokumentierte Kategorie-Reihenfolge war nur innerhalb einer einzelnen Anwendung umgesetzt; über mehrere Anwendungen hinweg konnten Kategorien ineinandergreifen.
+- Enterprise SSO lag außerhalb des Snapshots und wurde bei einer manuellen Abschaltung nicht automatisch als Wiederanlaufvoraussetzung behandelt.
+
+## Fix in Version 2.2.0
+
+### Best-effort mit klarer Fehlergrenze
+
+Jeder Planschritt hat nun einen eigenen Fehlerfang. Ein Fehler erhält das Ergebnis `Failed` mit kompletter Exception-Kette; anschließend wird der nächste unabhängige Schritt versucht. Der Gesamtlauf bleibt bei mindestens einem Fehler ausdrücklich fehlgeschlagen und verlangt Operator-Review.
+
+### Zustandsbewusste und idempotente Ausführung
+
+Vor jeder Mutation wird der aktuelle WMI- beziehungsweise Servicezustand gelesen. Entspricht er bereits dem Ziel, wird keine Methode aufgerufen und das Ergebnis lautet `AlreadySatisfied`. Dadurch kann ein Restore sicher an einem gemischten Zustand ansetzen. Im konkreten ACC-Fall wird die weiterhin aktiv gebliebene Scheduler-Receive-Location beim Restore nicht erneut über WMI aktiviert, wenn `before.json` ebenfalls `Enabled=true` enthält.
+
+### Dauerhafte Evidenz
+
+Reguläre Operationen schreiben `shutdown-result.json` beziehungsweise `restore-result.json`. Jeder Report enthält Ergebnis, Zeit und Exception pro Schritt. Der Nachher-Snapshot wird auch nach Einzelfehlern separat versucht; ein Fehler dieser Aufnahme wird ebenfalls im Report gesichert.
+
+### Emergency Restore nur aus `before.json`
+
+Der neue Button **Emergency Restore** benötigt außer der erhaltenen `before.json` keine Datei des fehlgeschlagenen Laufs. Er:
+
+1. validiert Snapshot und Zielserver,
+2. schreibt eine timestamp-basierte, unveränderte Recovery-Kopie,
+3. erzeugt und speichert einen neuen Emergency-Plan,
+4. stellt zuerst den Windows-Dienst `ENTSSO` auf `Running`,
+5. gleicht Host Instances, Send Ports, Orchestrations und Receive Locations zustandsbewusst ab,
+6. arbeitet nach isolierten Fehlern weiter,
+7. versucht einen Nachher-Snapshot und schreibt immer den vollständigen Ergebnisreport, soweit das Ausgabeverzeichnis verfügbar ist.
+
+### Globale Reihenfolge
+
+Shutdown:
+
+1. alle Receive Locations,
+2. alle Orchestrations,
+3. alle Send Ports,
+4. alle Host Instances.
+
+Restore und Emergency Restore:
+
+1. bei Emergency Restore zuerst `ENTSSO`,
+2. alle Host Instances,
+3. alle Send Ports,
+4. alle Orchestrations,
+5. alle Receive Locations.
+
+Diese Reihenfolge gilt nun über alle Anwendungen hinweg.
+
+## Verifikation
+
+Die portable Regressionstestsuite enthält ab Version 2.2.0 unter anderem folgende Vorfallsprüfungen:
+
+- simulierte `Microsoft.BizTalk.Scheduler`-Exception in einem mittleren Schritt,
+- erfolgreiche Ausführung aller späteren Schritte,
+- vollständige Persistenz des Teilfehlerreports,
+- Überspringen eines bereits erreichten Sollzustands ohne Mutation,
+- `ENTSSO` als erster Emergency-Schritt,
+- globale Shutdown-/Restore-Reihenfolge mit mehreren Anwendungen,
+- Kurzname/FQDN-Gleichheit für Host-Instance-Schritte.
+
+Die lokale Suite umfasst 23 bestandene Tests. Die abschließende Freigabe für PROD benötigt weiterhin einen Windows-/BizTalk-Test auf ACC: echter Scheduler-Fehlerpfad, vollständige Fortsetzung, Ergebnisreport, Emergency-Dry-run und realer Wiederanlauf aus einer Kopie der vorhandenen `before.json`.
+
+## PROD-Freigabekriterien
+
+- Version 2.2.0 installieren und Installer-Self-Test bestätigen.
+- `Diagnose` und einen vollständigen Shutdown-Dry-run ausführen.
+- Kontrolliert nachweisen, dass eine isolierte Scheduler-Exception spätere Schritte nicht blockiert.
+- `shutdown-result.json` und Nachher-Snapshot prüfen.
+- Emergency Restore zuerst ausschließlich als Dry-run aus einer Snapshot-Kopie prüfen.
+- Realen Emergency Restore auf ACC abschließen und `FailedCount=0` oder jeden verbleibenden Einzelfehler fachlich freigeben.
+- Erst danach dasselbe Releasepaket für PROD verwenden.