Phase 6: Gitea-Cross-Builds, Paketprüfung und gesperrten Releasepfad implementieren

docs/distribution.md

@@ -0,0 +1,145 @@
+# Gitea-Build und Distribution
+
+Change 06 baut ausschließlich am Origin `git.rfc1437.de/hugo/TerminalBasic`.
+Die Actions verwenden das bestätigte Label `linux-arm64` und vier Zieltriple.
+Kein Cross-Build ist ein Windows-/macOS-/Linux-Emulatornachweis.
+
+## Buildumgebung
+
+| Ziel | Builder | Fixierte Baseline |
+|---|---|---|
+| Windows amd64 | cargo-xwin 0.23.0 | VS-Kanal 17 mit festen SDK-/CRT-Versionen: SDK 10.0.26100, CRT 14.44.17.14; statische CRT |
+| macOS arm64 | cargo-zigbuild 0.23.0, Zig 0.16.0 | enthaltenes MacOSX11.3.sdk; Deployment Target 11.0 |
+| Linux amd64/arm64 | cargo-zigbuild 0.23.0, Zig 0.16.0 | glibc 2.28 |
+
+Rust 1.97.1 ist in `rust-toolchain.toml` fixiert. Die Images stehen mit Digest
+in `.gitea/workflows/build.yml`; SDK/Clang/Zig stammen aus diesen Images.
+7-Zip 25.01 wird mit fester SHA-256 in `bootstrap.sh` bereitgestellt.
+Zusätzlich prüft der Windows-Build einen festen Hash aller SDK-/CRT-Dateien
+und Symlinks. Änderungen unter derselben Microsoft-Versionsbezeichnung
+werden damit abgelehnt; der Pin muss dann ausdrücklich aktualisiert werden.
+Die Tabelle nennt Buildvorgaben, keine gemessenen minimalen OS-Versionen.
+Die tatsächliche Cross-Matrix und OS-Läufe sind im Changebericht auszuweisen.
+
+Der Builder erfordert Linux aarch64. Zwei Cargo-Buildjobs und eine sequenzielle
+Zielmatrix begrenzen die Last. Host-`tb-template` prüft über denselben Parser
+wie der Exportdienst PE32+/amd64/Console, Mach-O/arm64 oder ELF/Linux/64-Bit;
+fremde Executables werden beim Paketieren nicht ausgeführt.
+
+Lokaler Aufruf innerhalb des betreffenden gepinnten Containers:
+
+```sh
+sh .gitea/scripts/bootstrap.sh
+python3 .gitea/scripts/build.py --target x86_64-pc-windows-msvc --output dist
+```
+
+Eigene native Testpakete lassen sich mit `distribution.py pack --bin-dir ...
+--target ... --output ... --inspector .../tb-template` erstellen. Uncommittete
+Quellen bleiben in `manifest.json` markiert und sind nicht freigabefähig.
+
+## Origin-Konfiguration und Rechte
+
+Actions sind am Repository aktiviert. Der gemeinsame Runner heißt
+`gitea-arm64-01`. Sein Neustartfehler wurde separat gemeldet; der Aufbau der
+Repository-Workflows ändert keine globale Docker-/AppArmor-Konfiguration.
+
+Erforderliche Konfiguration:
+
+- Variable `TB_VBDOS_REPOSITORY`: erreichbarer Git-Bestand des in
+  `foreign.rs` fixierten Referenzprojekts. Der Checkout muss exakt
+  `1cdd2b32b829fe1721d0b6aecc433abc47a96fb6` liefern. Fehlende Konfiguration
+  lässt den Pflichtjob scheitern; Fremdprogramme werden nicht übersprungen.
+- Secret `TB_RELEASE_TOKEN`: Gitea-Zugang nur für dieses Repository und die
+  Releaseverwaltung. Nur der Tag-Entwurfsjob und der manuelle Freigabeworkflow
+  referenzieren es. Es wird weder im Checkout gespeichert noch geloggt.
+- PRs aus fremden Repositories führen keinen unkontrollierten Code auf dem
+  gemeinsamen persönlichen Runner aus. Interne PRs/Pushes erhalten keine
+  Veröffentlichungsschritte. Die tatsächliche Gitea-/Runner-Kompatibilität
+  einschließlich Jobrechten muss der erste Origin-Lauf bestätigen.
+
+Die Actions-URLs sind explizite Gitea-URLs mit festen Commit-IDs.
+[Absolute Action-URLs](https://docs.gitea.com/usage/actions/comparison/)
+und [Runnerlabels](https://docs.gitea.com/runner/) entsprechen dem Gitea-Modell.
+
+## Pakete und Zielprüfungen
+
+`terminalbasic-<version>-windows-amd64.7z` sowie `...-macos-arm64.tar.gz`,
+`...-linux-amd64.tar.gz`, `...-linux-arm64.tar.gz` enthalten `tb`/`tbc` im Hauptverzeichnis und
+`runtimes/<Target-Triple>/tbrt` samt `tbrt.meta` (Windows jeweils `.exe`
+bzw. `tbrt.exe.meta`),
+`LICENSE`, `INSTALL.txt` und `manifest.json`. Unix-Executables besitzen 0755.
+Das Manifest bindet Version, Revision, Rust, Buildhost/Image, Target und
+SHA-256 jeder Datei. Jedes Paket erhält zusätzlich eine `.sha256`-Datei.
+
+Auf dem passenden Prüfsystem das unveränderte Paket herunterladen und ausführen:
+
+```sh
+python3 .gitea/scripts/distribution.py target-check \
+  --archive /pakete/terminalbasic-0.1.0-macos-arm64.tar.gz \
+  --target aarch64-apple-darwin --output /nachweise/aarch64-apple-darwin
+```
+
+Das Prüfsystem braucht Python und den Prüfharness dieser Revision; die
+Produkte selbst laufen aus einem neu entpackten temporären Verzeichnis.
+Native-/TBL-Prüfungen verwenden einen leeren PATH, separate Verbraucher,
+keine Library-Quellen und die vorhandenen paketierten Metadaten. Auf macOS
+bleibt `/usr/bin/codesign` als Systemhilfe zulässig. Erzeugte Executables
+laufen nach Entfernen von Quellen, TBL/TBC und Vorlagen weiter.
+Die gemeinsame `portable.tbl` wird auf allen Zielen unverändert verwendet,
+SHA-256 `5d25c2f8c95ae535e55a6c84c1ddd0d964358863f4f3c780c50ac4a2eb3594df`.
+
+Windows erfordert zusätzlich `--windows-console-test <tb-ui-Testexecutable>`
+derselben Revision. Dieses Testexecutable kann der Linux-Builder mit
+`cargo xwin test --locked --target x86_64-pc-windows-msvc -p tb-ui
+--features terminal --no-run` erzeugen; es gehört zum Prüfharness, nicht zum
+Anwenderpaket. DOSBox kann diese Windows-PE-Programme nicht ausführen.
+Windows bleibt auf Benutzerentscheidung vorerst offen.
+
+Der automatisch erzeugte `report.json` lässt die manuelle Terminalabnahme
+offen. Die Bedienfolge steht in `docs/plattformmatrix.md`. Je Target sind
+zusätzlich `manual.json` und die referenzierten nichtleeren Belegdateien nötig:
+
+```json
+{
+  "target": "aarch64-apple-darwin",
+  "revision": "<40-stellige Revision>",
+  "package_sha256": "<SHA-256 des Originalpakets>",
+  "passed": true,
+  "tester": "<Prüfer>",
+  "terminal_versions": {"terminal.app": "<gemessene Version>"},
+  "cases": {"f1_f12": true, "modifiers": true, "mouse": true,
+    "unicode_colors": true, "resize": true, "input_break": true, "shell": true},
+  "evidence": ["terminal-protokoll.txt"]
+}
+```
+
+Windows verlangt `windows-terminal`, beide Linux-Ziele jeweils `xterm` und
+`vte` mit Versionen. Nur tatsächlich bestandene Schritte auf true setzen.
+Die Felder dienen einer verantworteten manuellen Bestätigung; sie ersetzen
+keine Durchführung. Herkunft wird über den geprüften Origin-Commit gebunden.
+
+## Entwurf und Veröffentlichung
+
+Ein Push des passenden Tags `v<version>` baut/testet alle vier Ziele und lädt
+erst danach neun Assets in einen Gitea-Entwurf: vier Pakete, vier SHA-Dateien,
+`acceptance.json`. Dessen Referenzlauf enthält Fremdprogramme, Inventar,
+Workspace/Clippy/Format, Compile-/VM-Benchmarks und die ausdrücklich gestartete
+native IDE-Abnahme. Golden-Erzeugung bleibt bewusst ignoriert. Echte native
+Paket-/Terminalprüfungen sind eine zusätzliche Freigabebedingung.
+
+Nachweise auf separaten Systemen beziehen sich auf diese Originalpakete.
+Unter `release-evidence/v<version>/<target>/` werden `report.json`, Logs,
+`manual.json` und dessen Belege in einem Origin-Commit bereitgestellt.
+Der manuell auf main gestartete Workflow „Geprüften Gitea-Entwurf freigeben“
+erhält Tag und vollständige Nachweisrevision. Er lädt die ursprünglichen
+Entwurfsassets, prüft vier exakte Paketbindungen, Ziel-/Terminalresultate,
+gemeinsame TBL-Prüfsumme und die Grundabnahme aus dem ursprünglichen Taglauf.
+Er baut die Pakete dabei nicht erneut. Fehlende oder abweichende Daten sperren
+Freigabe. Der Tag muss zur Paketversion und zur geprüften Revision passen.
+
+Uploads werden zurückgelesen und bytegenau geprüft. Wiederholungen ergänzen
+nur fehlende identische Assets eines Entwurfs. Abweichende Assets oder ein
+bereits veröffentlichter Release werden nicht überschrieben. Erst der letzte
+API-Aufruf ändert `draft` auf false. Die Regressionen simulieren insbesondere
+fehlende Uploads, falsche Nachweise, korrupte Pakete und bestehende Releases;
+sie erzeugen keine öffentlichen Testreleases.