127 lines
2.7 KiB
Markdown
127 lines
2.7 KiB
Markdown
# 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`
|