Stabilize control surface and external bridge v1

2026-04-20 01:13:27 +02:00
parent a56cecb23d
commit 07c52db5fb
29 changed files with 8818 additions and 1510 deletions
--- a/docs/external_control_bridge.md
+++ b/docs/external_control_bridge.md
@@ -0,0 +1,126 @@
+# External Control Bridge
+
+## Zweck
+
+Der External-Control-Bridge-Prozess ist eine duenne generische Prozess-Aussenkante fuer die eingefrorene Show-Control-v1-Semantik.
+
+Er:
+
+- bildet externe Commands auf die bestehenden Show-Control-Primitives ab
+- haelt staged Sessions pro `session_id`
+- reicht Host-Fehlercodes unveraendert durch
+- fuegt keine neue Geschaeftslogik hinzu
+
+Implementierung:
+
+- `crates/infinity_host/src/external_bridge.rs`
+- CLI-Einstieg ueber `cargo run -p infinity_host -- external-control-bridge ...`
+
+## Start
+
+```bash
+. "$HOME/.cargo/env"
+cargo run -p infinity_host -- external-control-bridge --config config/project.example.toml --runtime-state data/runtime_state.json
+```
+
+Der Prozess nutzt `stdin`/`stdout` im JSONL-Format:
+
+- eine JSON-Nachricht pro Zeile nach `stdin`
+- eine JSON-Antwort pro Zeile auf `stdout`
+
+## Request-Form
+
+```json
+{
+  "request_id": "ext-1",
+  "session_id": "desk-a",
+  "command": {
+    "type": "execute_primitive",
+    "payload": {
+      "primitive": {
+        "primitive": "set_pattern",
+        "payload": {
+          "pattern_id": "noise"
+        }
+      }
+    }
+  }
+}
+```
+
+Weitere Bridge-Commands:
+
+- `execute_primitive`
+- `get_state`
+- `clear_session`
+
+Hinweis:
+
+- `request_snapshot` bleibt ein Show-Control-Primitive und laeuft deshalb ueber `execute_primitive`
+- `get_state` liefert die read-only State-Projektion ohne Preview
+
+## Response-Form
+
+```json
+{
+  "semantic_version": "v1",
+  "request_id": "ext-1",
+  "session_id": "desk-a",
+  "result": {
+    "type": "primitive_buffered",
+    "payload": {
+      "summary": "pattern staged: noise"
+    }
+  },
+  "session": {
+    "session_id": "desk-a",
+    "pending": {
+      "pattern_id": "noise",
+      "has_group_target": false,
+      "group_id": null,
+      "parameters": {},
+      "transition_style": null,
+      "transition_duration_ms": null
+    }
+  }
+}
+```
+
+Moegliche Result-Typen:
+
+- `primitive_buffered`
+- `command_accepted`
+- `snapshot`
+- `state`
+- `session_cleared`
+- `error`
+
+## Fehlerverhalten
+
+Primitive-Fehler bleiben unveraendert:
+
+- `unknown_group`
+- `unknown_preset`
+- `unknown_creative_snapshot`
+- `group_exists`
+- `persist_failed`
+- `show_control_session_required`
+- `transition_pattern_required`
+
+Bridge-spezifische Rahmenfehler:
+
+- `invalid_bridge_request_json`
+- `session_id_required`
+
+## Session-Regeln
+
+- staged Primitive mit `session_id` werden in einer isolierten Session gepuffert
+- staged Primitive ohne `session_id` laufen absichtlich gegen den stateless Port und liefern `show_control_session_required`
+- direkte Primitive koennen mit oder ohne Session aufgerufen werden
+- `clear_session` verwirft nur die angegebene Session
+
+## Ownership
+
+Die Konflikt- und Ownership-Regeln fuer mehrere Control-Quellen stehen in:
+
+- `docs/control_ownership.md`