# AI-Maintainer-Handoff

## Projekt und Sicherheitsziel

Das Repository enthält ein .NET-Framework-4.6.1-WinForms-Tool für kontrollierte BizTalk-2020-Wartungsoperationen. Änderungen müssen Dry-run, explizite Freigabe realer Aktionen, sichere Reihenfolgen und wiederherstellbare Installergrenzen erhalten. Die aktuelle Produktversion ist 2.3.4.

## Installerinvarianten

- Vor der ersten Mutation müssen Manifest, Länge, SHA-256 und Staging-Self-Test erfolgreich sein.
- Eine laufende installierte Anwendung blockiert Update und Deinstallation.
- Ein Update darf die aktive Vorversion erst nach erfolgreichem Staging verändern.
- Das Backup einer bestehenden Installation wird nur atomar per `Directory.Move` erzeugt. Bei dauerhaftem Fehler bleibt die Vorversion aktiv; es gibt keinen In-place-Kopierfallback.
- Nach ausgeschöpften Aktivierungs-Move-Retries darf eine erneut SHA-256-geprüfte Kopie nur in ein nicht vorhandenes Ziel geschrieben werden: bei einer Neuinstallation oder nachdem eine Update-Vorversion vollständig atomar ins Backup verschoben wurde.
- Nach jeder Aktivierungsart läuft der Self-Test erneut aus dem endgültigen Installationsziel.
- Sobald ein Zielverzeichnis teilweise angelegt sein kann, muss `activated=true` gesetzt sein, damit der Catch-Pfad es entfernt.
- Scheitert der Ziel-Self-Test nach einem Update-Kopierfallback, muss die teilweise neue Version entfernt und das atomare Backup wieder als aktives Verzeichnis eingesetzt werden.
- Windows-Integration wird erst nach bestandenem Ziel-Self-Test verändert und bei Folgefehlern aus dem Snapshot restauriert.
- Startmenü-Link, Uninstaller und Uninstall-Registry sind verpflichtend; Fehler müssen weiterhin den vollständigen Rollback auslösen.
- Der gemeinsame Desktop-Link ist optional und standardmäßig abgewählt. Snapshot, Erstellen/Entfernen, Validierung, Rollback und Uninstall müssen jeden Fehler als sichtbare Warnung isolieren und dürfen keine Kernoperation abbrechen.
- Diagnose-Logging darf das eigentliche Setup-Ergebnis nie ersetzen.

Die zentrale Implementierung liegt in `src/BizTalkPlatformManagementTool.Setup/InstallerEngine.cs`. Move-Retries sind auf acht Versuche und 19,75 Sekunden Wartezeit begrenzt. Die injizierbaren `directoryMover`- und `retryDelay`-Delegates existieren ausschließlich, damit Sperrpfade ohne echte Wartezeit portabel getestet werden können.

## Runtime- und Recovery-Invarianten

- Ein isolierter WMI-, Adapter- oder Servicefehler darf keine späteren unabhängigen Planschritte verhindern.
- Teilfehler werden vollständig pro Schritt persistiert; der Gesamtlauf bleibt sichtbar fehlgeschlagen und darf nicht als Erfolg ausgegeben werden.
- Vor jeder Mutation wird der aktuelle Zustand geprüft. Bereits erreichte Sollzustände werden ohne Methodenaufruf als `AlreadySatisfied` erfasst.
- Der Nachher-Snapshot wird unabhängig von Einzelfehlern versucht; sein Fehler gehört in denselben Ergebnisreport.
- Die Runtime-WMI-Klassen liefern keine verlässliche Application-Zuordnung. `BizTalkApplicationResolver` liest deshalb die Management-DB-Position aus `MSBTS_GroupSetting` und indiziert die read-only ExplorerOM-Anwendungshierarchie. WMI bleibt Quelle für Zustand und Mutationen; ExplorerOM wird ohne Compile-time-Abhängigkeit und nur mit geprüfter Microsoft-Assemblyidentität geladen.
- Scheitert die Katalogauflösung, bleibt die WMI-Zustandserfassung verfügbar, aber alle betroffenen Artefakte werden sichtbar unter `(Unknown Application)` gruppiert und Diagnose, Grid sowie Laufzeitlog müssen eine verwertbare Warnung ausgeben.
- Shutdown-Kategorien gelten global über alle Anwendungen: Receive Locations, Orchestrations, Send Ports, Host Instances.
- Zwischen der globalen Receive-Location-Phase und allen späteren Shutdown-Kategorien liegt ein persistierter Operator-Checkpoint. Ein realer Lauf darf nur nach explizitem Continue fortsetzen; Stop oder Handlerfehler markiert alle späteren Zeilen als `NotExecuted` und arbeitet fail-closed.
- Dry-run zeigt den Checkpoint ohne Callback. Der Ergebnisreport muss Entscheidung, Zeitpunkt, OperatorStopped und NotExecutedCount dauerhaft enthalten.
- Ein BizTalk-Application-Stop wird nicht zusätzlich ausgeführt: `Partially Started` ist während des Drains erwartbar, während Application-Stop-Optionen eine breitere, teils destruktive Semantik als das reine Setzen eines Statuswerts besitzen.
- Restore-Kategorien gelten global über alle Anwendungen: Host Instances, Send Ports, Orchestrations, Receive Locations.
- Emergency Restore überschreibt niemals die Eingabe-`before.json`, erzeugt eine timestamp-basierte Kopie und stellt `ENTSSO` vor Host Instances sicher.
- Emergency Restore muss mit genau einer validen `before.json` funktionieren; Dateien eines vorherigen fehlgeschlagenen Laufs dürfen keine Voraussetzung sein.
- Ein älterer kompatibler Snapshot, insbesondere aus 2.1.3, darf nicht allein anhand seines `ToolVersion`-Werts abgelehnt werden.
- Alle laufzeitrelevanten Bestätigungsdialoge müssen mit dem Hauptformular als Owner angezeigt werden. Vor dem echten Drain-Checkpoint muss der Status sichtbar `ACTION REQUIRED`/pausiert melden; Dry-run muss ausdrücklich erklären, dass keine Runtime-Änderung und keine echte Drain-Entscheidung erfolgt.
- Der echte Emergency Restore erzeugt nach Möglichkeit automatisch einen timestamp-basierten Soll/Ist-Diff aus Recovery-Quelle und Nachher-Snapshot.
- Die zentrale best-effort Orchestrierung liegt in `OperationPlanExecutor`; die WMI-/Service-Zustandsprüfung bleibt im produktiven Runtime-Adapter.
- Datei-Logging und optionale GUI-Logweiterleitung sind Diagnosekanäle und dürfen niemals einen fachlichen Planschritt oder dessen Fehlerbehandlung unterbrechen.
- Ein Laufzeitlogpfad gilt erst nach erfolgreichem Create/Write/Flush/Delete-Test als verfügbar. Die Reihenfolge ProgramData, LocalAppData, EXE-`Logs`, Temp ist stabil; ein Append-Fehler muss denselben Datensatz auf dem nächsten Kandidaten erneut versuchen.
- Fallback und Totalausfall des Dateiloggings müssen mit Pfad und Exception im Grid sichtbar sein. Jeder GUI-Start persistiert einen Verifikationsdatensatz; der WMI-freie Self-Test prüft einen vollständigen Log-Write/Read-Roundtrip.
- Scheduler-Preflight darf nur für Receive Locations mit passendem Adaptername oder `scheduler:`-URI laufen; normale Adapter dürfen keine zusätzliche Abhängigkeit erhalten.
- Adapter-DLLs dürfen nur aus explizit konfigurierten, per Registry erkannten oder konventionellen Produktverzeichnissen und nur nach vollständiger Assemblyidentitätsprüfung geladen werden. Der Toolprozess verändert niemals den GAC.
- Laufzeitlogs halten 30 Kalendertage, komprimieren abgeschlossene Tage und rehydrieren maximal 10.000 neue Einträge ins Grid. Ein Archiv-/Lesefehler darf keine BizTalk-Operation beeinflussen.

## Versionierung

Bei einem Release sind mindestens diese Stellen konsistent zu ändern:

- `InstallerEngine.ProductVersion`
- Setup-Titel in `MainForm`
- beide `Properties/AssemblyInfo.cs`
- beide `app.manifest`
- `BizTalkOperationService.Version`
- `CHANGELOG.md`

## Verifikation

Portable Befehle:

```sh
msbuild BizTalkPlatformManagementTool.sln /t:Rebuild /p:Configuration=Release '/p:Platform=Any CPU' /m:1
mono tests/BizTalkPlatformManagementTool.Tests/bin/Release/BizTalkPlatformManagementTool.Tests.exe
mono src/BizTalkPlatformManagementTool/bin/Release/BizTalkPlatformManagementTool.exe --self-test
mono src/BizTalkPlatformManagementTool.Packager/bin/Release/BizTalkPlatformManagementTool.Packager.exe . Release
```

Nach der Paketierung müssen ZIP, Base64-TXT und SHA-256-Datei gegengeprüft werden. Die abschließende Freigabe braucht zusätzlich einen repräsentativen Windows-/ACC-Test von UAC, `Program Files`-ACL/EDR, Registry, Verknüpfungen, Update, Rollback und Deinstallation sowie BizTalk-Diagnose und Dry-run.