# Show-Control Primitives

## Ziel

Diese Primitive-Menge ist die kleine, dauerhafte interne Steuersemantik fuer software-only Show-Control. Sie bleibt bewusst generisch:

- keine UI-spezifischen Sonderfaelle
- keine grandMA-spezifische Kopplung
- keine zweite Architektur neben Host-Core und API

Der aktuelle Stand gilt faktisch als eingefrorene Show-Control-v1-Semantik. Erweiterungen muessen kuenftig kompatibel zur bestehenden direct-/staged-Trennung, Fehlercode-Menge und Event-Sicht bleiben.

Der Implementierungspfad liegt in `crates/infinity_host/src/external_control.rs`.

## Primitive

### `blackout`

- Typ: direkt, mutierend
- Semantik: setzt globalen Blackout an oder aus
- Idempotenz: ja, bezogen auf den Zielzustand
- Fehlercodes: unterliegende Host-Fehler nur bei Persistenzproblemen, typischerweise `persist_failed`
- Event-Auswirkung: Info-Event auf Erfolg

### `recall_preset`

- Typ: direkt, mutierend
- Semantik: recalled ein Preset inklusive seiner Zielgruppe und Transition-Metadaten
- Idempotenz: praktisch ja, wenn dasselbe Preset erneut recalled wird
- Fehlercodes: `unknown_preset`, `persist_failed`
- Event-Auswirkung: Info-Event auf Erfolg, Warning-Event bei unbekanntem Preset

### `recall_creative_snapshot`

- Typ: direkt, mutierend
- Semantik: recalled einen gespeicherten Creative Snapshot inklusive Scene- und Transition-State
- Idempotenz: praktisch ja, wenn derselbe Snapshot erneut recalled wird
- Fehlercodes: `unknown_creative_snapshot`, `persist_failed`
- Event-Auswirkung: Info-Event auf Erfolg, Warning-Event bei unbekanntem Snapshot

### `set_master_brightness`

- Typ: direkt, mutierend
- Semantik: setzt globale Helligkeit, intern auf `0.0..1.0` geklemmt
- Idempotenz: ja, bezogen auf den geklemmten Zielwert
- Fehlercodes: typischerweise nur `persist_failed`
- Event-Auswirkung: Info-Event auf Erfolg

### `set_pattern`

- Typ: staged
- Semantik: staged das Pattern fuer die naechste explizite Transition
- Idempotenz: ja, letzter Wert gewinnt
- Fehlercodes: `invalid_pattern_id`
- Event-Auswirkung: kein Host-Event bis `trigger_transition`

### `set_group_parameter`

- Typ: staged
- Semantik: staged einen Scene-Parameter fuer die naechste Transition und kann optional gleichzeitig die Zielgruppe fuer diese Transition setzen
- Idempotenz: ja, letzter Wert pro Parameter-Key gewinnt
- Fehlercodes: `invalid_group_parameter_key`
- Event-Auswirkung: kein Host-Event bis `trigger_transition`

### `upsert_group`

- Typ: direkt, mutierend
- Semantik: legt eine Runtime-Gruppe an oder ueberschreibt sie bewusst mit `overwrite: true`
- Idempotenz: ja mit `overwrite: true`, nein mit `overwrite: false`
- Fehlercodes: `invalid_group_id`, `invalid_group_members`, `group_exists`, `persist_failed`
- Event-Auswirkung: Info-Event auf Erfolg

### `set_transition_style`

- Typ: staged
- Semantik: staged Transition-Style und optional Duration fuer die naechste explizite Transition
- Idempotenz: ja, letzter Wert gewinnt
- Fehlercodes: keine zusaetzlichen Primitive-Fehler
- Event-Auswirkung: kein Host-Event bis `trigger_transition`

### `trigger_transition`

- Typ: ausfuehrend, mutierend
- Semantik: materialisiert den aktuell gestagten Transition-Intent in den Host
- Ausfuehrungsreihenfolge:
  1. `select_group` nur wenn ueber staged Parameter ein Gruppenkontext gesetzt wurde
  2. `set_transition_duration_ms` nur wenn staged
  3. `set_transition_style` nur wenn staged
  4. `select_pattern`
  5. `set_scene_parameter` fuer alle staged Parameter
- Idempotenz: nein, erfolgreicher Trigger konsumiert den gestagten Intent
- Fehlercodes: `transition_pattern_required` plus unterliegende Host-Fehler wie `unknown_group` oder `persist_failed`
- Event-Auswirkung: die unterliegenden Host-Kommandos erzeugen die sichtbaren Info-/Warning-Events

### `request_snapshot`

- Typ: read-only
- Semantik: liefert den aktuellen Host-Snapshot ohne Host-Mutation
- Idempotenz: ja
- Fehlercodes: keine Primitive-eigenen
- Event-Auswirkung: keine

## Hinweis zur Adapter-Nutzung

Die staged Primitive sind fuer externe Show-Control-Adapter gedacht, die absichtlich mehrere kleine Eingaben sammeln und erst mit `trigger_transition` in einen Host-seitigen Uebergang umsetzen. Direkte UI- oder API-Kommandos koennen weiterhin eager bleiben; die stabile interne Adapter-Semantik wird davon nicht aufgeblasen.

Ein stateless Port darf staged Primitive nicht stillschweigend akzeptieren. Wenn `set_pattern`, `set_group_parameter`, `set_transition_style` oder `trigger_transition` ohne Session-/Adapter-Kontext direkt an einem Port landen, ist der erwartete Fehlercode `show_control_session_required`.

## Referenz-Client

Der sehr duenne generische Referenzpfad liegt in `crates/infinity_host/src/external_control.rs`:

- `ReferenceShowControlClient::stateful(...)` fuer direkte plus staged Flows
- `ReferenceShowControlClient::stateless(...)` zum bewussten Nachweis, dass staged Primitive am nackten Port mit `show_control_session_required` abgewiesen werden
- `BufferedShowControlAdapter` und `ShowControlSession` als kleine Buffer-/Commit-Implementierung ohne neue Grundarchitektur

Ergaenzende Randbedingungen:

- `docs/external_control_bridge.md` beschreibt die generische Prozess-Aussenkante auf Basis derselben Primitive
- `docs/control_ownership.md` beschreibt die konfliktfreie Koexistenz mehrerer Control-Quellen