[AZ-626] Decompose complete: 47 tasks + docs + module layout

Greenfield Steps 1-6 baseline for the autopilot rewrite from legacy
Qt/C++ to a Rust workspace.

- Remove legacy Qt/C++ tree (ai_controller, drone_controller,
  misc/camera, python_scaffold, root Dockerfile, autopilot.pro,
  legacy main.py / requirements.txt).
- Add _docs/00_problem (problem, restrictions, acceptance criteria,
  security approach, input data + fixtures).
- Add _docs/01_solution/solution_draft01.
- Add _docs/02_document (architecture, system-flows, data_model,
  glossary, decision-rationale, deployment, 13 component descriptions,
  tests/ specs, FINAL_report, module-layout).
- Add _docs/02_tasks/todo with 47 task specs (AZ-640..AZ-686, one
  bootstrap + 46 component tasks) and _dependencies_table.md.
- Add .cursor/rules/artifact-srp.mdc (single-responsibility rule for
  canonical _docs artifacts).
- Track autodev state in _docs/_autodev_state.md (Step 6 completed,
  ready for Step 7 Implement).

Jira: bootstrap AZ-626; component epics AZ-627..AZ-639; tasks
AZ-640..AZ-686. Total complexity 173 points across 12 epics.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Oleksandr Bezdieniezhnykh
2026-05-19 11:02:01 +03:00
parent f7d6cb4a3a
commit bc40ea7300
235 changed files with 12585 additions and 15097 deletions
@@ -0,0 +1,89 @@
# 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`.