# Component — `operator_bridge`

**Layer**: Action (data plane out)
**Status**: forward-looking design (Rust)

## 1. Purpose

Surfaces POIs to the operator (via the always-on `telemetry_stream`) and routes operator commands (confirm / decline / target-follow start / target-follow release / safety-override / BIT-degraded-acknowledge) back into autopilot. On decline, appends an `IgnoredItem`. On confirm, hands a middle-waypoint hint to `mission_executor`. On target-follow start / release, drives `scan_controller`'s state transition. **Validates every operator command's authentication signature, replay protection, and session binding before dispatching it** — the modem link's encryption alone is not sufficient (per `architecture.md §5` and Q9).

The Ground Station is the operator-facing UI; `operator_bridge` is the autopilot-side counterpart.

## 2. Inputs

| Input | Source | Cadence | Notes |
|---|---|---|---|
| POI surface request | `scan_controller` | per POI | Includes Tier 1, Tier 2, and (optional) Tier 3 evidence. |
| POI dequeue / replace | `scan_controller` | event | When the queue rotates (cap, age-out, or completion). |
| Operator command (confirm / decline / target-follow start / target-follow release) | Ground Station (via `telemetry_stream`) | event | Acked back to operator with command id + result. |
| Modem link state | `telemetry_stream` | event | Used to decide whether to surface POIs at all (see Failure Modes). |

## 3. Outputs

| Output | Consumer | Shape |
|---|---|---|
| Operator-facing POI event | `telemetry_stream` (which pushes to Ground Station) | `{ poi_id, mgrs, class_group, confidence, vlm_status, tier2_evidence_summary, photo_metadata }` |
| `IgnoredItem` append | `mapobjects_store` (via `scan_controller`) | on operator decline |
| Middle-waypoint hint | `mission_executor` (via `scan_controller`) | on operator confirm |
| Target-follow start / release | `scan_controller` | on operator command |
| Health metric | health aggregator | `pois_surfaced_per_min`, `decision_latency_p50/p99` (operator-side), `commands_in_flight`. |

## 4. Key Responsibilities

- Translate `POI` events from `scan_controller` into the wire format defined in `architecture.md §7.10 Drone ⇄ Operator Sync Message Format` and push them through `telemetry_stream`.
- Receive operator commands on the return path; **validate the authentication signature, replay-protection sequence number, and session token** before any other processing. Reject and surface to health on signature failure, sequence-number reuse, or unknown session.
- Validate the command id matches a POI in flight (or a target-follow session, BIT report, or safety-override scope); ack the operator with the result.
- Apply the confidence-scaled operator decision window (40 % → 30 s, 100 % → 120 s, linear) — though the timeout itself is enforced by `scan_controller`; this component just ensures the surfaced POI carries the deadline.
- On confirm, hand `(target_mgrs, target_class)` to `scan_controller` (which forwards a middle-waypoint hint to `mission_executor`).
- On decline, hand `(MGRS, class_group)` to `scan_controller` for `IgnoredItem` append.
- Forward BIT-degraded acknowledgements (signed) to `mission_executor` (F9), and safety-override commands (signed) for battery / lost-link suppression to `mission_executor` (F10).

## 5. Internal State

- Currently surfaced POIs by id (with deadlines).
- In-flight target-follow session (if any).
- Per-command idempotency keys.

State is in-process only.

## 6. Failure Modes

| Failure | Detection | Behaviour |
|---|---|---|
| Modem link down | `telemetry_stream` health | Stop surfacing POIs; queue them in `scan_controller` (whose cap still applies); resume on reconnect. F10 lost-link ladder owns the larger response. |
| Operator command for unknown POI id | command validation | Ack with error; do not act on it. |
| Operator command after deadline | command validation | Ack with `expired`; do not act on it. |
| Duplicate operator command (re-tx) | idempotency key | Ack with the cached result; do not double-act. |
| `scan_controller` rejects the confirm (e.g., already in target-follow) | response from controller | Ack operator with `rejected: already_following`; surface the active target. |
| Operator command signature invalid | auth check | Reject with `auth_failed`; log; surface health → red on sustained failures (potential hostile injection). |
| Operator command sequence number reused | replay-protection check | Reject with `replay_detected`; log; do not act on it. |
| Unknown session token | session validation | Reject with `auth_failed`; log; require operator re-auth at Ground Station. |
| Operator attempts to acknowledge a BIT FAIL as DEGRADED | severity check | Rejected by validation; surface to operator as `cannot_acknowledge_fail`. |

## 7. Dependencies

**In-process** (input): `scan_controller`, `telemetry_stream`.
**In-process** (output): `scan_controller` (for state transitions), indirectly `mapobjects_store` and `mission_executor` (via `scan_controller`).

**External**: Ground Station API (operator-facing); contract owned by `../_docs/04_system_design_clarifications.md`.

## 8. Non-Functional Targets

| Concern | Target |
|---|---|
| POI surface → operator visible | ≤1 s under normal modem conditions |
| Operator command → autopilot effect | ≤1 s under normal modem conditions |
| Idempotency window | 60 s (per-command-id cache) |

## 9. Open Questions

- Ground Station API contract (`architecture.md §8 Q2`): stream protocol (WebRTC / WebSocket-H.264 / gRPC server-streaming?), session/auth model, bbox-overlay rendering.
- **Operator-command authentication scheme** (`architecture.md §8 Q9`): HMAC over (session_token, sequence_number, payload) vs JWT-style ed25519 vs MAVLink-2 signing extended to operator commands vs separate envelope. The principle is committed; the scheme is open.
- **Multi-operator session policy** (`architecture.md §8 Q11`): single active operator at a time, or quorum?

## 10. References

- `architecture.md §3`, `§5 Architectural Principles` (operator commands authenticated, signed, replay-protected), `§7.10 Drone ⇄ Operator Sync Message Format`, `§8 Q9 / Q11`.
- `system-flows.md §F5 Operator round trip`, `§F9 Pre-flight self-test`, `§F10 Lost-link failsafe ladder`.
- `data_model.md §POI`, `§IgnoredItem`, `§OperatorCommand`.
- `../_docs/04_system_design_clarifications.md`.