Phase 0: Repository-Initialisierung nach Bauplan v1.2

- Struktur gemäß §8 (Eigentumsgrenzen), PLAN.md als normative Basis - Pflichtdokumente: STATUS.md, ERRORS.md, TEST_REPORT.md, CHANGELOG.md, ADRs - ADR-0001 Python 3.13-Pin, ADR-0002 GStreamer 1.28.6-Pin (Windows), ADR-0003 IPC TCP+MessagePack v1 - Kernpakete: hms_protocol, hms_domain, hms_parameter, hms_artnet, hms_adaptive, hms_capabilities, hms_plugin_sdk - Renderer-Spike: D3D11-Primärpfad + Dev-GL-Pfad (§36 Nr. 4-5) - Control Core: FastAPI REST + WebSocket (§36 Nr. 9) - Beispielplugins: Passthrough + Gaussian Blur (3 Adaptive-Quality- Varianten, HLSL/GLSL/GLES) - Tools: Art-Net-Emulator, Fixture-Generator (Master32/Layer64-CSV), Capability-Probe - JSON-Schemas: IPC, Plugin, Projekt, Cluster - 121 Unit-/Integrationstests grün, Ruff grün Gate 0 bleibt offen: Hardwaremessungen nur auf echter Windows-Referenz- hardware gültig (§29.7, §33).
2026-09-11 00:36:59 +02:00
commit 0922cc1d68
133 changed files with 7939 additions and 0 deletions
@@ -0,0 +1,27 @@
+# ADR-0001: Python-Version pinnen
+
+- **Status:** Angenommen
+- **Datum:** 2026-09-10
+- **Phase:** 0
+- **Bauplan:** §7 („Python, unterstützte Version exakt pinnen“)
+
+## Entscheidung
+
+Der Control Core und alle Python-Pakete pinnen **Python 3.13** (`requires-python = "==3.13.*"` in `pyproject.toml`).
+
+## Kontext
+
+Der Bauplan verlangt eine exakt gepinnte Python-Version. 3.13 ist die aktuelle stabile Version mit ausgereiftem `asyncio`, breitem Wheel-Support für FastAPI/Pydantic und PyGObject-Kompatibilität für die GStreamer-Bindings.
+
+## Alternativen
+
+- 3.12: kein messbarer Vorteil, kürzeres Supportfenster als 3.13.
+- 3.14: bei Projektstart zu neu für stabile Binärwheels aller Abhängigkeiten.
+
+## Folgen
+
+- uv-Lockfile und CI pinnen 3.13; Versionssprünge erfolgen bewusst per ADR-Änderung.
+
+## Freigabe
+
+- Auftragsvorgabe „exakt pinnen“ aus PLAN.md §7; Umsetzung ohne Abweichung.
@@ -0,0 +1,28 @@
+# ADR-0002: GStreamer-Pin für Windows
+
+- **Status:** Angenommen (Bündelungsumfang folgt nach Phase-0-Build)
+- **Datum:** 2026-09-10
+- **Phase:** 0
+- **Bauplan:** §7.1, §30.2
+
+## Entscheidung
+
+Für die portable Windows-Ausgabe wird **GStreamer 1.28.6 (MSVC, x86_64)** gebündelt (Runtime-Paket, exakt manifestierte Plugin-Untermenge). Details: `build/windows/GSTREAMER.md`.
+
+## Kontext
+
+Die 1.28-Serie ist die aktuelle stabile Release-Serie mit gepflegtem D3D11-Stack (`d3d11h264dec`, `d3d11convert`, `d3d11compositor`, `d3d11videosink`). Version ermittelt von https://gstreamer.freedesktop.org/download/ (Stand 2026-09-10).
+
+## Alternativen
+
+- Ältere LTS-Releases: keine Vorteile, ältere D3D11-Elemente.
+- Eigener GStreamer-Build: höherer Wartungsaufwand, für Phase 0 nicht nötig.
+
+## Folgen
+
+- Phase 0 prüft die Bündelung in einer sauberen Windows-VM ohne installiertes GStreamer (§29.6); Pluginliste und SHA-256 werden nach dem ersten Onefolder-Build manifestiert.
+- Muss mit der Packaging-Entscheidung (ADR-0005 offen) zusammenarbeiten.
+
+## Freigabe
+
+- Entspricht PLAN.md §7.1 (Version pinnen); Bündelungsumfang wird nach dem ersten Portabilitätstest ergänzt.
@@ -0,0 +1,23 @@
+# ADR-0003: IPC – lokales TCP mit length-prefixed MessagePack
+
+- **Status:** Angenommen (Bauplan-Vorgabe §6.2; umgesetzt in `packages/protocol`)
+- **Datum:** 2026-09-10
+- **Phase:** 0
+
+## Entscheidung
+
+Control Core ↔ Renderer kommunizieren über lokales TCP auf `127.0.0.1` mit length-prefixed MessagePack (4-Byte-Big-Endian-Länge, Protokollversion 1, Idempotency-Keys; Heartbeat ab Phase 1). JSON ausschließlich im Debugmodus.
+
+## Alternativen
+
+- Named Pipes/Unix Sockets: plattformspezifische API-Unterschiede, kein Nutzen im Spike.
+- JSON-Lines: langsamer und größer; nur für Debug erlaubt (§6.2).
+
+## Folgen
+
+- `hms_protocol` definiert Envelope, Framing und Idempotency-Registry mit Unit-Tests.
+- IPC bindet niemals an eine externe Netzwerkschnittstelle (§6.2).
+
+## Freigabe
+
+- Direkte Umsetzung der normativen Vorgabe PLAN.md §6.2.
@@ -0,0 +1,17 @@
+# Architecture Decision Records
+
+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
+
+## Offen (Phase 0 entscheidet, §32 / §7.1)
+
+- 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-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)
@@ -0,0 +1,30 @@
+# ADR-NNNN: <Titel>
+
+- **Status:** Vorgeschlagen | Angenommen | Ersetzt (durch ADR-xxxx) | Verworfen
+- **Datum:** YYYY-MM-DD
+- **Phase:** (z. B. Phase 0)
+- **Betroffene Bauplan-Abschnitte:** (z. B. §7.1, §31 Phase 0)
+
+## Kontext
+
+Welches Problem, welche Optionen, welche Messungen/Zahlen liegen vor?
+
+## Entscheidung
+
+Die gewählte Option, klar und eindeutig formuliert.
+
+## Alternativen
+
+Die geprüften Alternativen und warum sie verworfen wurden.
+
+## Folgen
+
+Positiv, negativ, Risiken, Migrationspfad, Testfolgen.
+
+## Messwerte / Nachweise
+
+Verweis auf TEST_REPORT.md oder Rohdaten, die die Entscheidung stützen.
+
+## Freigabe
+
+Auftraggeber: (Freigabe erforderlich gemäß PLAN.md §1)
@@ -0,0 +1,41 @@
+# Architekturüberblick (Phase 0)
+
+Verbindliche Referenz: `PLAN.md`. Diese Seite fasst Prozess- und Besitzgrenzen zusammen.
+
+## Prozesse (§6.1)
+
+| Prozess | Technologie | Aufgabe |
+| --- | --- | --- |
+| Launcher/Supervisor | Python (Phase 1) | Start, Portwahl, portable Pfade, Heartbeat, kontrolliertes Beenden |
+| Control Core | Python, asyncio, FastAPI, Pydantic, SQLite/WAL (ab Phase 1) | autoritativer Zustand, REST/WS, Art-Net, Persistenz |
+| Render Worker | Python-Orchestrator + GStreamer + nativer Renderkern (ADR-0004 offen) | Decode, GPU-Compositing, Ausgabe, Telemetrie |
+| Web-Frontend | TypeScript, Vite (Phase 5, ADR-0006 offen) | Bedienoberfläche; niemals Videoausgang (§3.2) |
+
+## Besitzgrenzen (§8)
+
+- Jedes Paket hat eindeutige `hms_*`-Namen; kein Quereinbau zwischen `packages/*`.
+- Control Core und Renderer verbinden ausschließlich über das versionierte IPC (ADR-0003).
+- Der Renderer erhält pro Frame einen unveränderlichen Parametersnapshot (§11.4).
+
+## Kernregeln (§33, Auszug)
+
+- Python steuert, decodiert nicht und rendert keine Pixel.
+- Windows: D3D11Memory durchgängig; kein CPU-Rundweg im Normalpfad.
+- Plugins: versioniertes Manifest, kein Datei-/DB-Zugriff, Quarantäne bei Fehler.
+- Alle Steuerquellen (Browser, Art-Net, später Timeline/Audio/KI) laufen über die zentrale Parameter-Engine.
+
+## Steuerfluss Phase 0
+
+```text
+Lichtpult/Emulator → ArtDMX (UDP 6454) → hms_artnet.receiver
+    → Control Core (hms_parameter.engine: Priorität CONSOLE)
+    → IPC-Snapshot → Renderer (GStreamer-D3D11) → Opacity/Parameter an Frame-Grenze
+
+Browser → REST/WebSocket → derselbe Command-/Parameter-Pfad (Priorität WEB)
+```
+
+Beide Quellen adressieren denselben Parametersatz; es gibt genau eine autoritative Instanz (Control Core).
+
+## Phase-0-Spike
+
+`hms_renderer` definiert die Pipelines als Launch-Strings; Ausführung und Messung erfolgen auf Referenz-Windows-Hardware (Gate 0). Messprotokoll: `TEST_REPORT.md`.