mirror of
https://github.com/azaion/autopilot.git
synced 2026-06-21 15:21:11 +00:00
[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:
@@ -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`.
|
||||
Reference in New Issue
Block a user