Infinity_Vis_Rust/docs/show_control_primitives.md

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