Phase 1: IPC-Verbindungsschicht + Build-first-Strategie (ADR-0008)

- ADR-0008: Build-first, gesammelte Windows-Validierung (Auftraggeber-Freigabe) - ADR-0004 vorläufig: Rust auf GStreamer-D3D11-Elementpfad - ADR-0005 vorläufig: Nuitka Onefolder - hms_protocol: IpcServer/IpcClient mit Handshake (hello/welcome), Capabilities-Austausch, Heartbeat 500 ms bidirektional, Snapshot/Delta, Loopback-only-Enforcement, Re-Sync nach Reconnect, Version-Mismatch-Fehler - 9 Integrationstests: echter TCP-Loopback, kein Mock
2026-09-11 00:50:03 +02:00
parent b0599d8b86
commit 9536e08748
11 changed files with 753 additions and 27 deletions
@@ -0,0 +1,47 @@
+# ADR-0004: Nativer Renderkern – Rust auf dem GStreamer-D3D11-Elementpfad
+
+- **Status:** Vorläufig angenommen (Bestätigung oder Revision im Windows-Durchlauf)
+- **Datum:** 2026-09-11
+- **Phase:** ursprünglich Phase 0; wegen ADR-0008 vorgezogen
+- **Bauplan:** §6.1C, §7.1, §12.6
+
+## Entscheidung
+
+1. Sprache des nativen Moduls: **Rust**.
+2. Einbindung: **GStreamer-Plugin-Ansatz** – der Rendergraph nutzt die
+   erprobten D3D11-Elemente (d3d11h264dec → d3d11convert → d3d11compositor →
+   d3d11videosink) und eigene Rust-GStreamer-Elemente für Effekt-/Shader-Pässe,
+   statt sofort eine komplett eigenständige Render-Bridge mit eigener
+   Swapchain zu bauen.
+
+## Begründung (ohne Messdaten, deshalb vorläufig)
+
+- D3D11Memory-Residenz ist Eigenschaft der GStreamer-Elemente; das Risiko
+  eigengebauten Swapchain-Compositings entfällt.
+- gstreamer-rs bietet stabile Bindings; Rust liefert Gedächtnissicherheit im
+  nativen Pfad.
+- Die Effektkette skaliert als Elementkette; der Plugin-Vertrag (§14) bleibt
+  vollständig gewahrt.
+- Eine spätere wgpu-/eigenständige Bridge bleibt über dasselbe IPC- und
+  Capability-Protokoll anschließbar (§6.1C).
+
+## Alternativen
+
+- C++: kein Vorteil, höheres Fehlerrisiko im Speichermanagement.
+- Sofortige eigenständige Bridge: mehr Kontrolle, aber hohes Risiko ohne
+  Hardware-Feedback (ADR-0008).
+
+## Folgen
+
+- Der Renderer-Prozess orchestriert Pipelines; Rust-Elemente übernehmen die
+  Shader-Pässe (HLSL aus dem Plugin-Vertrag).
+- Rust-Kompilierung erfolgt im Windows-Durchlauf (Container ohne cargo).
+
+## Messwerte / Nachweise
+
+- Ausstehend. Gate-0-Messungen bestätigen das Elementpfad-Budget oder lösen
+  eine Revision (eigenständige D3D11-Bridge) aus – ohne API-Änderung (§12.6).
+
+## Freigabe
+
+Vorläufig gemäß ADR-0008; endgültig nach Windows-Messung.
@@ -0,0 +1,33 @@
+# ADR-0005: Packaging – Nuitka Onefolder (vorläufig)
+
+- **Status:** Vorläufig angenommen (Vergleich im Windows-Durchlauf)
+- **Datum:** 2026-09-11
+- **Phase:** ursprünglich Phase 0; wegen ADR-0008 vorgezogen
+- **Bauplan:** §7.1, §30.2
+
+## Entscheidung
+
+**Nuitka Standalone/Onefolder** als Packaging-Basis; **PyInstaller Onefolder**
+als dokumentierter Fallback, falls Nuitka die GStreamer-DLL-Bündelung nicht
+sauber abbildet. Onefile bleibt wie geplant ausgeschlossen (§7.1).
+
+## Begründung
+
+- Nuitka kompiliert zu C: weniger Interpreter-Rest, bessere Reproduzierbarkeit
+  per Buildskript (§30.1).
+- Die GStreamer-Bündelung ist von der Packaging-Wahl unabhängig
+  (runtime/-Ordner + GST_PLUGIN_PATH, siehe build/windows/GSTREAMER.md).
+- PLAN.md verlangt den finalen Vergleich auf Windows; hier nur vorläufige Wahl.
+
+## Folgen
+
+- Buildskripte targetieren Nuitka; der Fallback-Pfad bleibt gepflegt.
+
+## Messwerte / Nachweise
+
+- Ausstehend; der erste Onefolder-Build auf sauberem Windows-Rechner
+  entscheidet final (§29.6).
+
+## Freigabe
+
+Vorläufig gemäß ADR-0008; endgültig nach Windows-Build.
@@ -0,0 +1,53 @@
+# ADR-0008: Build-first-Strategie – verzögerte Hardware-Validierung
+
+- **Status:** Angenommen (Auftraggeber-Freigabe)
+- **Datum:** 2026-09-11
+- **Phase:** 0/1 (übergreifend)
+- **Bauplan:** §1, §1.1 Nr. 1/9/10, §29.7, §36 Nr. 16
+
+## Kontext
+
+Die Entwicklungsumgebung ist ein CPU-only-Linux-Container ohne Windows-GPU.
+Der Auftraggeber wünscht am 2026-09-11 ausdrücklich: „erst fertig bauen und dann
+auf Windows testen". PLAN.md §1 erlaubt Abweichungen vom normativen Ablauf,
+wenn sie per ADR dokumentiert, technisch begründet und vom Auftraggeber
+freigegeben werden. Diese Freigabe liegt mit der Anfrage vor.
+
+## Entscheidung
+
+1. Die Phasen 1–5 werden **plattformneutral vollständig gebaut** (Code, Tests
+   auf CPU-Ebene, Schemas, Dokumentation), bevor Hardwaremessungen stattfinden.
+2. Gate 0 und alle renderer-nahen Abnahmen werden **gesammelt in einem
+   Windows-Durchlauf** nachgeholt (reverse validation). Reihenfolge dort:
+   Portabilität → Decode/Residenz → Framezeit/DMX-Latenz → Adaptive Quality →
+   Golden Images → Onefolder-Build.
+3. Kein Gate wird vorher als grün gemeldet; STATUS.md führt die ausstehende
+   Hardware-Validierung offen als Checkliste.
+
+## Alternativen
+
+- Streng planmäßig (Gate 0 zuerst): sicherer, aber ohne Windows-Zugang blockiert;
+  vom Auftraggeber verworfen.
+- Windows-Cloud-VM in der Entwicklungsumgebung: hier nicht verfügbar.
+
+## Folgen und Risiken
+
+- ADR-0004/0005 müssen ohne Messdaten vorläufig entschieden werden →
+  ausdrücklicher Bestätigungsvorbehalt für den Windows-Durchlauf.
+- Der D3D11-Elementpfad bleibt bis dahin unvalidiert. Absicherung: der
+  Backend-Vertrag (§12.6) hält Korrekturen im Adapter lokal; Projekt-,
+  Parameter-, DMX- und Web-API ändern sich nicht.
+- Shader werden nur statisch bereitgestellt; Compile- und Golden-Image-Tests
+  entstehen im Windows-Durchlauf.
+- Fällt Gate 0 rot aus: gezielte Sanierung nach §1.1 Nr. 9 mit ERRORS.md-Eintrag;
+  kein Architektur-Neubau erforderlich (Vertragsabsicherung).
+
+## Messwerte / Nachweise
+
+- CPU-Ebene: pytest/Ruff grün je Etappe (TEST_REPORT.md, fortlaufend).
+- Hardware: ausstehend; Checkliste in STATUS.md.
+
+## Freigabe
+
+Auftraggeber: per Chat-Anfrage 2026-09-11 („erst fertig bauen und dann auf
+Windows testen") – hiermit dokumentiert.
@@ -1,17 +1,25 @@
 # Architecture Decision Records

-Vorlage: `_template.md`. Nummerierung fortlaufend. Abweichungen vom Bauplan nur mit ADR und Freigabe (PLAN.md §1).
+Vorlage: `_template.md`. Nummerierung fortlaufend. Abweichungen vom Bauplan nur
+mit ADR und Freigabe (PLAN.md §1).

 ## Angenommen

 - ADR-0001: Python-Version-Pin 3.13
 - ADR-0002: GStreamer-Pin 1.28.6 (Windows)
 - ADR-0003: IPC – lokales TCP + length-prefixed MessagePack v1
+- ADR-0008: Build-first-Strategie – verzögerte Hardware-Validierung
+  (Auftraggeber-Freigabe 2026-09-11)

-## Offen (Phase 0 entscheidet, §32 / §7.1)
+## Vorläufig angenommen (Bestätigung im Windows-Durchlauf, ADR-0008)

- ADR-0004: Nativer Renderkern – Rust vs. C++, eigenständige Bridge vs. GStreamer-Plugin
- ADR-0005: Packaging – Nuitka vs. PyInstaller (Onefolder)
- ADR-0006: Frontend – React vs. Svelte
+- ADR-0004: Nativer Renderkern – Rust auf dem GStreamer-D3D11-Elementpfad
+- ADR-0005: Packaging – Nuitka Onefolder (Fallback PyInstaller)
+
+## Offen
+
+- ADR-0006: Frontend – React vs. Svelte (Entscheidung zu Beginn Phase 5)
 - ADR-0007: Typprüfung – mypy vs. pyright
- weitere gemäß Bauplan §32 (Persistenz, Preview, Show-Codec, Ownership, Display-Abstraktion, Adaptive-Quality-Policy, Discovery, Clusterprotokoll, Paarung/TLS, Clock-Sync, UI-Design-Tokens)
+- weitere gemäß Bauplan §32 (Persistenz, Preview, Show-Codec, Ownership,
+  Display-Abstraktion, Adaptive-Quality-Policy, Discovery, Clusterprotokoll,
+  Paarung/TLS, Clock-Sync, UI-Design-Tokens)