Netzwerksolution Documentation Report

ET-PKG-GAP-WORK-PACKAGE-CONTRACT-001

Vertrag des GAP-Arbeitspakets#

Zweck#

erzeugt und validiert das einheitliche Zwei-Archiv-Arbeitspaket für genau einen GAP-Sprint. Die wiederverwendbare Paketmechanik liegt in engineering-tools; lokale Pfade und Aufrufe verbleiben in runtime.

Paketstruktur#

Die erzeugte Arbeitspaketausgabe enthält die beiden äußeren Archive und ihr maschinenlesbares Manifest:

gap-work-package/
                ├── package-manifest.json
                ├── SHA256SUMS.txt
                ├── sources.zip
                └── targets.zip

Es wird kein zusätzlicher Container um sources.zip und targets.zip erzeugt. Damit bleibt der seit GAP 2.1.5 geltende Zwei-Archiv-Vertrag führend.

sources.zip enthält ausschließlich Root-Dateien:

sources.zip
                ├── PROMPT.md
                └── <unveränderliche Referenz-Repositories>.zip

targets.zip enthält ausschließlich Root-Dateien:

targets.zip
                ├── gap.zip
                └── <veränderbare Repository-Arbeitskopien>.zip

Prompt#

PROMPT.md wird aus zwei unveränderten GAP-Artefakten zusammengesetzt:

  1. dem stabilen Root-PROMPT.md,
  2. dem im GAP-Manifest aktivierten Work Item.

Der erzeugte Prompt nennt den relativen Pfad des Work Items und übernimmt dessen Inhalt vollständig. Andere Work Items werden nicht in den Prompt kopiert.

Validierung vor Erzeugung#

Absolute Pfade, ..-Segmente und symbolische Links in ZIPs sind unzulässig. Originalarchive werden ausschließlich gelesen. Ohne aktivierte Uploadfilter werden sie byteweise unverändert in die inneren Archive übernommen.

Konfigurierbare Uploadfilter#

Uploadfilter werden ausschließlich über die versionierte Datei aktiviert. Der Aufruf übergibt sie mit --filter-config. Die Konfiguration benennt Repository, Regelversion, Ausschlussmuster, Flat-Root-Äquivalente, Begründung und die zu bewahrenden Originalartefakte; Filterregeln sind nicht im Programmcode fest verdrahtet.

Für runtime gilt:

Nach dem Paketieren öffnet das Werkzeug die gefilterte ZIP erneut und weist negativ nach, dass kein Eintrag mehr eines aktiven Ausschlussmusters erfüllt. Ein Treffer bricht die Erzeugung ab.

Für workspace wird archive/** (bei umschließendem Root workspace/archive/**) aus der temporären Uploadkopie ausgeschlossen. Das sind lokale Vorherstände und Importarchive, keine Quellartefakte. Der Ordner im lokalen Workspace wird weder verändert noch gelöscht. Die Regel wird auf Sources und Targets angewandt, damit auch ein historisch bereits enthaltenes archive/ nicht erneut übertragen wird.

Determinismus#

Paketmanifest#

package-manifest.json beschreibt mindestens:

Bei aktivierten Uploadfiltern enthält das Manifest zusätzlich für jede angewandte Regel:

Integritätsmanifest#

SHA256SUMS.txt verwendet ausschließlich kleingeschriebene SHA-256-Hashes und zwei Leerzeichen vor dem logischen Pfad. Die Datei enthält eindeutig sortierte Prüfsummen für:

SHA256SUMS.txt enthält keine Selbstprüfsumme. Validierung berechnet sämtliche Werte neu; fehlende, zusätzliche, doppelte oder abweichende Zeilen sind Fehler.

Sicherheitsprüfungen#

Vor Veröffentlichung werden alle Archive vollständig dekomprimiert und auf CRC-Fehler geprüft. Unzulässig sind ZIP-Slip-Pfade, Backslashes, doppelte kanonische Einträge, symbolische Links, unerwartete Repository-Roots, beschädigte Archive, widersprüchliche Identitäten sowie Manifest- oder Prüfsummenabweichungen.

Repository-ZIPs dürfen entweder einen exakt zum deklarierten Repositorynamen passenden umschließenden Root oder einen flachen Root besitzen. Das Semantic GAP muss unter seinem manifestierten Repository- beziehungsweise Artefaktnamen liegen.

allowedTargetRepositories ist eine duplikatfreie fachliche Menge. Manifest und Work-Item-Frontmatter muessen dieselben Repositorynamen enthalten; ihre Reihenfolge ist nicht semantisch und darf voneinander abweichen.

Atomare Veröffentlichung#

Die Erzeugung schreibt alle vier Ausgabedateien in ein neues Staging-Verzeichnis neben dem Ziel, validiert dieses vollständig und benennt erst danach das gesamte Verzeichnis atomisch auf den Zielnamen um. Das Zielverzeichnis darf vorher nicht existieren. Bei jedem Fehler wird das Staging entfernt; ein teilweise veröffentlichtes Arbeitspaket ist unzulässig.

Validierung eines bestehenden Pakets#

Der Modus validate prüft Rootstruktur, beide inneren Archive, Paketmanifest, Prüfsummen, erzeugten Prompt, GAP-Identität, aktives Work Item, Repositoryrollen, Repository-Identitäten und Allowed Target Scope erneut. Deklarierte Uploadfilter werden gegen die Source-ZIP geprüft; ausgeschlossene Pfade dürfen darin nicht vorkommen. Erfolgreiche Validierung verändert keine Eingabe.

CLI und Exit-Codes#

Erzeugung:

python3 gap_work_package.py create \
                  --gap semantic-gap.zip \
                  --filter-config upload-filters.json \
                  --source engineering-tools=engineering-tools-source.zip \
                  --target engineering-tools=engineering-tools-target.zip \
                  --output-dir gap-work-package

Validierung:

python3 gap_work_package.py validate gap-work-package

Fehler werden auf stderr ausgegeben. Eine fehlgeschlagene Vorprüfung erzeugt kein teilweise gültiges Zielpaket.

Traceability#

↑