# Batch 13 / Cycle 1 — Implementation Report

**Date**: 2026-05-20
**Tasks**: AZ-683
**Verdict**: PASS_WITH_WARNINGS (pre-existing autopilot lint from batch 4
still open — see Findings §A1; unchanged by this batch)

## 1. Scope

| Ticket | Title | Crate | Complexity |
|---|---|---|---|
| AZ-683 | scan_controller POI queue + ≤5/min cap + decision-window mapping | `scan_controller` | 5 |

Batch 13 ships AZ-683 as a stand-alone unit. AZ-684 (evidence ladder) was
considered for the same batch but pulled because its dependencies
(AZ-660 detections wire, AZ-671 VLM provider runtime) are not yet
landed; co-batching it would have created an artificial blocker. POI
queue is fully self-contained on top of the AZ-682 FSM substrate, so
shipping it alone keeps the batch unblocked and review tractable.

## 2. Approach

Per `02_tasks/done/AZ-683_scan_controller_poi_queue_and_window.md`, the
deliverable is the **prioritized POI queue, rolling 5/min surface cap,
confidence-scaled decision window, and the timeout-vs-decline semantic
split**. The evidence-ladder gate (AZ-684) and mapobjects-store
IgnoredItem persist (AZ-685) are intentionally *not* in this batch — the
queue surfaces priorities and returns dispatchable actions, but the
actual gimbal slew (`scan_controller` issuing an ROI) and IgnoredItem
write live in their own tickets. The split is enforced by:

- `next_poi_for_surface` returns the `Poi` once the cap allows it and
  the confidence is ≥ 40 % — but does **not** itself drive the gimbal
  or change FSM state; AZ-684 will plumb that.
- `decline_poi` returns a `DeclineAction { poi_id, mgrs, class_group,
  declined_at, source_detection_ids }` — the caller (AZ-685
  mapobjects-store dispatch) is responsible for the actual
  `IgnoredItem` persist. This keeps the queue free of `mapobjects_store`
  I/O.
- `tick()`'s timeout sweep **silently forgets** expired POIs. No
  IgnoredItem is emitted for a timeout per spec §3 — only a *positive
  operator decline* creates an IgnoredItem.

### Component pieces shipped

- `internal/poi_queue/priority.rs` — pure functions:
  - `decision_window(confidence) -> Option<Duration>` — linear 40 % →
    30 s, 100 % → 120 s, `None` below floor.
  - `age_factor(age_seconds) -> f32` — linear decay 1.0 → 0.1 over
    300 s, clamped.
  - `priority_score(confidence, proximity, age_seconds) -> f32` —
    `c × p × age_factor`.
- `internal/poi_queue/mod.rs` — `PoiQueue` actor-private struct:
  - `insert(poi, proximity, now_ns)` — enqueues with stamped
    `enqueued_at_ns`.
  - `next_for_surface(now_ns) -> Option<Poi>` — picks the highest
    priority entry that clears the confidence floor and the rolling
    cap, removes it from the queue, records a surface timestamp.
  - `decline(poi_id) -> Option<DeclineAction>` — removes entry, returns
    the IgnoredItem payload data.
  - `timeout_sweep(now_wallclock) -> Vec<Uuid>` — drops expired entries,
    returns the removed IDs for metric accounting.
  - `surfaces_in_window(now_ns) -> usize` — number of POIs surfaced in
    the rolling 60 s window after trimming.
  - `SURFACE_CAP_PER_WINDOW = 5`.
- `crates/scan_controller/src/lib.rs` — wiring:
  - `Inner` now owns `poi_queue: PoiQueue` and counters
    `pois_surfaced_total`, `pois_forgotten_total`, `pois_declined_total`.
  - `ScanControllerHandle::submit_poi_candidate`,
    `next_poi_for_surface`, `decline_poi`, `poi_queue_len`,
    `pois_in_window` — public async surface.
  - `ScanControllerHandle::tick` now also runs the timeout sweep.
  - `ScanControllerHandle::submit_operator_cmd` now handles
    `DeclinePoi` end-to-end — payload `{ poi_id }` is parsed,
    `decline_poi` is called, and the result is returned as
    `SubmitOutcome::Declined(DeclineAction)` for the caller. The
    method's return type changed from `Result<()>` to
    `Result<SubmitOutcome>`.
  - `ScanMetrics` gained four POI fields:
    `poi_queue_len`, `pois_surfaced_total`, `pois_forgotten_total`,
    `pois_declined_total`.
  - `health()` detail now includes `poi_queue=<len>`.

## 3. Files touched

### AZ-683
- `crates/scan_controller/Cargo.toml` — added `serde_json` (for
  operator-command payload parsing) and `chrono` (for wallclock
  deadlines).
- `crates/scan_controller/src/lib.rs` — wired POI queue into `Inner`,
  added `submit_poi_candidate` / `next_poi_for_surface` / `decline_poi`
  / `poi_queue_len` / `pois_in_window`, changed
  `submit_operator_cmd` return type and added `DeclinePoi` handling,
  extended `ScanMetrics` and `health()`.
- `crates/scan_controller/src/internal/mod.rs` — added `pub mod
  poi_queue`.
- `crates/scan_controller/src/internal/poi_queue/mod.rs` — new
  (`PoiQueue`, `DeclineAction`, `SURFACE_CAP_PER_WINDOW`, 5 unit tests).
- `crates/scan_controller/src/internal/poi_queue/priority.rs` — new
  (pure priority math + 8 unit tests).
- `crates/scan_controller/tests/poi_queue.rs` — new (6 integration
  tests covering AC-1..AC-5 + DeclinePoi via operator command).

## 4. Test results

| Crate | Unit | Integration | Total |
|---|---|---|---|
| `scan_controller` | 26 | 11 (5 state_machine + 6 poi_queue) | 37 |

Workspace `cargo test --workspace`: all suites green. The single
`mission_executor::state_machine::ac3_bounded_retry_then_success`
ignored test carries over from batch 8 — unchanged by this batch.

Clippy: `cargo clippy -p scan_controller --all-targets -- -D warnings`
is clean. Workspace-wide clippy still hits the pre-existing
`autopilot::Runtime::vlm_provider_name` dead-code error from batch 4
(see Findings §A1 / cumulative C5).

### Acceptance criteria

| AC | Source | Test |
|---|---|---|
| AC-1 priority ordering | `tests/poi_queue.rs::ac1_priority_ordering_via_handle` + `internal/poi_queue/mod.rs::orders_by_priority_score` | ✅ |
| AC-2 ≤5/min rolling cap | `tests/poi_queue.rs::ac2_five_per_minute_cap_via_handle` + `internal/poi_queue/mod.rs::cap_blocks_after_five_surfaces` | ✅ |
| AC-3 decision-window mapping | `tests/poi_queue.rs::ac3_decision_window_public_mapping` + `internal/poi_queue/priority.rs::decision_window_*` | ✅ |
| AC-4 confidence floor (no surface < 40 %) | `tests/poi_queue.rs::ac4_below_floor_never_surfaces` + `internal/poi_queue/priority.rs::decision_window_below_floor` | ✅ |
| AC-5 timeout sweep — silently forget | `tests/poi_queue.rs::ac5_tick_sweep_forgets_expired_pois` + `internal/poi_queue/mod.rs::timeout_sweep_*` | ✅ |
| Decline → IgnoredItem action | `tests/poi_queue.rs::decline_poi_via_operator_command_emits_action` | ✅ |

## 5. Findings (this batch)

### A1. Pre-existing dead-code error in `autopilot::Runtime::vlm_provider_name`

**Severity**: High (still blocks workspace `-D warnings` clippy gate)
**Category**: Maintenance
**Origin**: Batch 4. Unchanged by this batch.

Tracked in `_docs/_process_leftovers/2026-05-20_autopilot_clippy.md`.
Carried as cumulative finding C5 — see §6.

### A2. `submit_operator_cmd` return type changed

**Severity**: Low (API)
**Detail**: Return type went from `Result<()>` to
`Result<SubmitOutcome>` so that `DeclinePoi` can hand back the
`DeclineAction` for AZ-685 to dispatch. No external caller exists yet
(operator-bridge wiring is AZ-685), so this is not a breaking change in
practice. Existing internal call sites (the `tests/state_machine.rs`
suite from batch 12) used `submit_operator_cmd` only for `MissionAbort`
/ `ReleaseTargetFollow` and only via the public handle; both now return
`SubmitOutcome::Accepted` and the existing tests still ignore the
return value via `.unwrap()`-style discard, so they continue to pass
unchanged.

### A3. `Poi.priority` field is **not** mutated by the queue

**Severity**: Low (Architecture / clarification)
**Detail**: The canonical `Poi.priority` field stays whatever the
producer set it to. The queue's internal `Entry` carries the
proximity/age factors needed for ordering separately. This keeps the
`Poi` model in `shared::models::poi` immutable from the queue's
perspective and avoids racing producers/consumers on `priority`.
Documented here in case AZ-684/685 expects to read a final priority
score from the surfaced `Poi`.

## 6. Cumulative findings — open carry-over

Batch-13 is one batch into a new triplet (13 / 14 / 15); cumulative
review will land at the end of batch 15. Carry-over from the batch-12
cumulative review:

| ID | Severity | Category | Status |
|---|---|---|---|
| C1 | Medium | Maintainability | OPEN — duplicated `SendCommandError` mapping in `gimbal_controller` (batches 9-10) |
| C2 | Low | Style | OPEN — `MavlinkCommandIssuer` naming inconsistency (batch 9) |
| C3 | Low | Architecture | OPEN — `module-layout.md` drift: now also covers `scan_controller/internal/poi_queue/{mod,priority}.rs` |
| C4 | Low | Architecture | OPEN — `data_model.md §PanPlan` definition still missing (batch 11) |
| C5 | High | Maintenance | OPEN — pre-existing `autopilot/runtime.rs::vlm_provider_name` dead-code error blocking workspace `-D warnings` clippy (batch 4 origin) |

C3 grows by `poi_queue/{mod,priority}.rs` this batch. C5 is still the
most pressing; the next opportunity to fix it is either a dedicated
maintenance batch or sweep before merging dev.

## 7. Next-batch candidates

- **AZ-684** — scan_controller evidence ladder + VLM hooks. Now
  unblocked by AZ-683 here, but still needs AZ-660 (detections wire)
  and AZ-671 (VLM provider runtime) for end-to-end value. Could be
  partially implemented as a "Tier-2 confirmation handler stub" today.
- **AZ-685** — mapobjects-store dispatch for confirmed POIs and
  `IgnoredItem` (consumes the `DeclineAction` this batch returns).
- **AZ-659** — frame_ingest publisher (slow-consumer drop policy).
- **AZ-658** — frame_ingest decoder (still pending the retina/ffmpeg
  pin decision).
