autopilot/_docs/02_document/components/operator_bridge/description.md

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.