ET-ROUNDTRIP-CHANGED-ONLY-IMPORT-001

Changed-only-Roundtrip-Import#

Zweck#

Der Import verarbeitet ausschließlich die in einem Lauf tatsächlich gelieferten vollständigen Repository-ZIPs. Nicht gelieferte Repositorys gelten als unverändert und werden weder verlangt noch berührt. Das Semantic GAP wird als separates Prozesspaket behandelt.

Eingaben#

• ein Verzeichnis mit null oder mehr vollständigen Repository-ZIPs,
• optional genau ein semantic-gap-ZIP,
• eine Runtime-Konfiguration mit erlaubten Repositorynamen, Zielpfaden, Archivpfad und GAP-Zielpfad.

Alternativ darf das Eingabeverzeichnis genau ein Gesamtpaket enthalten. Dieses ist ein ZIP mit roundtrip-package-manifest.json, den darin deklarierten Repository-ZIPs und einem Semantic-GAP-ZIP. Einzel-ZIPs und Gesamtpaket werden nicht im selben Lauf gemischt.

Gesamtpaket#

Das roundtrip-package-manifest.json besitzt artifactType: roundtrip-import-package, packageVersion: "1", repositoryOrder, einen Repositoryeintrag je Ordnungsposition (archive, sha256) und semanticGap mit Archiv und Prüfsumme. Die Reihenfolge ist Teil des Pakets und damit die einzige zulässige Einlesereihenfolge.

Vor der ersten Änderung prüft der Import das komplette Container-ZIP, alle enthaltenen Prüfsummen, sämtliche inneren ZIPs, Repository-Identitäten, Löschkonflikte und das GAP. Fehlschläge in dieser Phase verändern weder Repository noch GAP. Nach erfolgreicher Vorprüfung werden die Repositorys exakt nach repositoryOrder importiert; erst danach wird das GAP übernommen. Bei einem nachträglichen Importfehler endet der Lauf sofort. Bereits importierte Schritte bleiben im einzigen Laufbericht als IMPORTED, alle folgenden Repositorys und das GAP als NOT_EXECUTED sichtbar; der Gesamtstatus ist FAILED.

Prüfungen vor dem Import#

• gültiges ZIP ohne absolute Pfade, .. oder symbolische Links,
• genau ein ◆manifest.json im Paket- oder Repository-Root,
• packageClass: installable,
• passende Repository-Identität über artifactType oder artifactName,
• freigegebenes Repository aus der Konfiguration,
• zulässiger installMode und exportMode.
• deletedFiles ist eine duplikatfreie Liste sicherer relativer Einzeldateien

ohne absolute Pfade, .., Wildcards oder Verzeichnisse,

• eine Datei darf nicht gleichzeitig geliefert und zur Löschung deklariert sein.

Import und Archivierung#

Vor jeder Repository-Aktualisierung wird der bisherige Zielbestand unter dem konfigurierten Archivpfad gesichert. archiveRoot muss außerhalb aller importierbaren Repositorys liegen; eine Konfiguration innerhalb eines Repositorys wird vor jeder Änderung abgewiesen. Der Import erfolgt über ein Staging-Verzeichnis und einen atomaren Austausch. Overlay-Pakete löschen keine nicht gelieferten Dateien. Ausschließlich die im Manifest unter deletedFiles einzeln genannten Dateien werden im Staging entfernt; dadurch leer gewordene Elternverzeichnisse dürfen bis zum Repository-Root aufgeräumt werden. Bereits fehlende deklarierte Dateien gelten als idempotent entfernt. Das Semantic GAP wird separat an seinen Prozesspfad kopiert.

Alle Manifest-, Payload- und Zieltypprüfungen erfolgen vor Archivierung und vor dem ersten Schreibvorgang am Ziel. Eine unzulässige Löschung lässt Ziel und aktives GAP unverändert.

Im ZIP gespeicherte Unix-Dateimodi werden ohne Sonderbits wiederhergestellt, damit ausführbare Adapter und Werkzeuge nach dem Import ausführbar bleiben.

Der Dry-Run prüft dieselben Konflikte zwischen gelieferten Dateien, deklarierten Löschungen und vorhandenem Zielzustand, schreibt jedoch weder Archiv noch Zielbestand.

Laufbericht#

Jeder Lauf erzeugt einen JSON-Bericht mit gelieferten und unveränderten Repositorys, Manifestidentität, Zielpfad, Archivpfad und Status. Ein fehlendes Repository ist kein Fehler. Bei Gesamtpaketen enthält der Bericht zusätzlich inputForm: roundtrip-import-package und die Ergebnisse in der tatsächlich ausgeführten Reihenfolge.