Stabilize control surface and external bridge v1

docs/control_ownership.md

@@ -0,0 +1,92 @@
+# Control Ownership
+
+## Ziel
+
+Diese Regeln definieren die konfliktfreie Steuersemantik zwischen allen aktuellen und spaeteren Control-Quellen auf derselben Host-Core-v1-Aussenkante.
+
+Betroffene Quellen:
+
+- kreative Web-UI
+- technische Desktop-GUI
+- generischer externer Control-Adapter
+- spaetere grandMA-Anbindung
+
+## Gemeinsame Grundregel
+
+Der Host-Core bleibt die einzige mutierende Autoritaet fuer Show-State.
+
+Keine Quelle darf:
+
+- intern an Simulation-, Persistenz- oder UI-Zustaende vorbeischreiben
+- eigene Sonderpfade fuer Pattern-, Preset-, Group- oder Transition-Logik einziehen
+- die LED-Taktung oder Timing-Autoritaet uebernehmen
+
+## Rollen
+
+### Web-UI
+
+- kreative Oberflaeche
+- darf direkte Primitive und lokale staged Sessions benutzen
+- staged Zustand bleibt lokal, bis `trigger_transition` explizit committed wird
+
+### technische Desktop-GUI
+
+- Engineering- und Diagnoseoberflaeche
+- bevorzugt direkte Operationen, Beobachtung und Admin-Aktionen
+- bekommt keine priorisierte Besitzrolle gegenueber anderen Quellen
+
+### externer Control-Adapter
+
+- darf nur auf die eingefrorene v1-Primitive-Semantik abbilden
+- staged Sessions muessen pro externer Session sauber getrennt gehalten werden
+- Fehlercodes aus dem Host werden unveraendert durchgereicht
+
+### spaetere grandMA-Anbindung
+
+- ist spaeter nur eine weitere Quelle auf derselben Bridge-/Primitive-Aussenkante
+- bekommt keine Sonderrechte gegenueber Web-UI, GUI oder anderen Adaptern
+
+## Konfliktregeln
+
+### Direkte Operationen
+
+- direkte Primitive mutieren sofort den globalen Host-State
+- letzte erfolgreich ausgefuehrte Mutation gewinnt
+- dazu gehoeren insbesondere:
+  - `blackout`
+  - `recall_preset`
+  - `recall_creative_snapshot`
+  - `set_master_brightness`
+  - `upsert_group`
+
+### Staged Operationen
+
+- staged Primitive mutieren den globalen Host-State nicht sofort
+- staged Zustand gehoert immer nur zur lokalen Session der jeweiligen Quelle
+- staged Sessions duerfen parallel existieren
+- staged Inhalt wird erst mit `trigger_transition` global wirksam
+
+### Commit-Verhalten
+
+- `trigger_transition` ist der einzige Commit-Punkt fuer staged Pattern-/Parameter-/Transition-Intents
+- ein erfolgreicher Commit konsumiert nur die staged Session der commitenden Quelle
+- andere offene Sessions bleiben unveraendert bestehen
+
+### Beobachtung
+
+- `request_snapshot` und State-Projektionen sind read-only
+- Beobachtung erzeugt keinen Ownership-Anspruch auf den Show-State
+
+## Praktische Auswirkungen
+
+- es gibt aktuell kein verteiltes Locking zwischen Quellen
+- konfliktfreie Zusammenarbeit entsteht ueber:
+  - identische Primitive-Semantik
+  - lokale Session-Isolation fuer staged Flows
+  - last-write-wins fuer direkte globale Mutationen
+  - explizite Commits statt impliziter Side Effects
+
+## Persistenz
+
+- nur global wirksame Host-Mutationen und Persistenz-Kommandos beeinflussen Runtime-State-Dateien
+- uncommittete staged Sessions sind absichtlich nicht Teil des globalen Persistenzzustands