# 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`