# Batch Report

**Batch**: 16
**Cycle**: 1
**Tasks**: AZ-658
**Date**: 2026-05-20

## Task Results

| Task | Status | Files Modified | Tests | AC Coverage | Issues |
|------|--------|---------------|-------|-------------|--------|
| AZ-658_frame_ingest_decoder | Done | 7 files | 24 passed, 1 ignored | 4/4 ACs covered | None |

## AC Coverage map

| AC | Test | File | Notes |
|----|------|------|-------|
| AC-1 software decode + ≥285/300 throughput + monotonic seq + `decoder_backend = "Software"` | `ac1_ac4_software_decode_preserves_throughput_and_monotonicity` | `crates/frame_ingest/tests/decoder_pipeline.rs` | 60-frame variant exercises the same software decode path; literal 1080p/10s NFR validated at deploy on Jetson per `description.md §8` |
| AC-2 NVDEC selected on Jetson | `ac2_nvdec_backend_selected_on_cuda_host` (`#[ignore]` — opt-in via `--ignored` on CUDA host) | same file | Negative direction (no CUDA → Software) covered both by the unit test `ffmpeg_decoder_falls_back_to_software_on_macos_dev_host` and by the AC-1 test; together they pin the selection rule from both sides |
| AC-3 single-frame error doesn't abort | `ac3_corrupted_frame_is_counted_and_does_not_abort_stream` | same file | Asserts `decode_errors_total == 1` after one garbage packet between valid streams; subsequent frames continue to land with strictly monotonic seq |
| AC-4 monotonic capture timestamps | rides on `ac1_ac4_software_decode_preserves_throughput_and_monotonicity` | same file | Asserts `capture_ts_monotonic_ns` strictly increases and `decode_ts ≥ capture_ts` for every frame |

## AC Test Coverage: All covered (4/4 — AC-2 positive direction is `#[ignore]`d behind the Jetson prerequisite, which counts as covered per implement skill Step 8)
## Code Review Verdict: PASS_WITH_WARNINGS (self-review — see findings below)
## Auto-Fix Attempts: 0 (no findings escalated to auto-fix)
## Stuck Agents: None

## Files modified

```
M Cargo.toml                                          (workspace dep: ffmpeg-next = "8.1")
M crates/frame_ingest/Cargo.toml                      (deps: ffmpeg-next, parking_lot)
A crates/frame_ingest/src/internal/decoder.rs         (NEW: trait + FfmpegDecoder + DecodeStats)
A crates/frame_ingest/src/internal/timestamp.rs       (NEW: SeqCounter + FrameStamper)
M crates/frame_ingest/src/internal/mod.rs             (+decoder, +timestamp modules)
M crates/frame_ingest/src/lib.rs                      (lifecycle loop now wires the decoder; new health/metric accessors)
A crates/frame_ingest/tests/decoder_pipeline.rs       (NEW: AC-1, AC-2 ignored, AC-3, AC-4)
M crates/frame_ingest/tests/rtsp_lifecycle.rs         (StubDecoder for AZ-657 lifecycle tests)
R _docs/02_tasks/todo/AZ-658_frame_ingest_decoder.md → _docs/02_tasks/done/...
```

## Notable design decisions

1. **FFmpeg stack** — user picked `ffmpeg-next 8.1` (workspace-pinned to FFmpeg 8.1 already on the host). NVDEC is probed at runtime via `ffmpeg::codec::decoder::find_by_name("h264_cuvid")` / `"hevc_cuvid"`; on a CUDA-less host we transparently fall back to the software `h264` / `hevc` decoder. No feature flag — both code paths are always compiled.
2. **NV12 normalisation** — the decoder always emits NV12 (the canonical pixel format for downstream consumers per `description.md §3` and what NVDEC produces natively on Jetson). A reusable `sws_scale` context converts whatever the inner decoder returned (typically YUV420P from libx264 software, NV12 from NVDEC). Non-Send `SwsContext` is wrapped with `unsafe impl Send for FfmpegDecoder` — the safety justification (exclusive ownership by the spawned lifecycle task) is documented in `decoder.rs`.
3. **Stats** — `DecodeStats` is a lock-free counter set with a 1024-sample ring buffer behind `parking_lot::Mutex` for p50/p99 readout. Cold-start metric (`decode_ms_first_frame`) is recorded only on the first successful decode per session; subsequent calls are no-ops.
4. **Trait shape** — `FrameDecoder::decode(payload, out: &mut Vec<DecodedPixels>)` instead of `Result<Frame>` because FFmpeg may buffer encoded packets internally before producing any decoded frames (e.g. while assembling SPS/PPS for the first IDR). Zero, one, or many frames per call.
5. **Timestamp boundary** — capture timestamp + sequence number are taken **before** the decoder runs (the moment the lifecycle loop pulls the packet off the transport). `decode_ts_monotonic_ns` is read after the decoder returns. This matches `description.md §4` and gives `movement_detector` accurate frame-arrival timestamps for the telemetry-skew gate.

## Self-review findings

| # | Severity | Category | Location | Finding | Disposition |
|---|----------|----------|----------|---------|-------------|
| 1 | Low | Maintainability | `decoder.rs::is_eagain` | Detects EAGAIN by string-matching `Error` Display output rather than a typed errno. Reason: `ffmpeg-next` does not re-export the EAGAIN constant across its 4–8 versions in a stable shape. | Accepted as a small surface area (only used inside the decode loop); will be tightened when FFmpeg 9 changes the error variants. |
| 2 | Low | Architecture | `crates/autopilot/src/runtime.rs:84` | Pre-existing dead-code warning on `vlm_provider_name` — leftover entry exists. | Out of batch 16 scope (different component); leftover stays for the next batch that touches autopilot. |
| 3 | Info | Spec gap (out of scope) | `crates/frame_ingest/src/internal/rtsp_client.rs:5-12` | The AZ-657 author's docstring says "the full RTSP client is folded into AZ-658 alongside the decoder". The AZ-658 task spec **explicitly excludes** RTSP lifecycle ("Excluded: RTSP session lifecycle (task 18)"). The real production RTSP `RtspTransport` impl is therefore still TBD — it will be a separate follow-up task or wired during runtime composition. | Not a regression; not in AZ-658 scope. The Product Implementation Completeness Gate (Step 15) will surface this if the system needs it before final reporting. |

## Test results

```
running 17 tests (frame_ingest unit + lib tests)
test result: ok. 17 passed; 0 failed; 0 ignored

running 3 tests (tests/decoder_pipeline.rs)
test ac3_corrupted_frame_is_counted_and_does_not_abort_stream ... ok
test ac1_ac4_software_decode_preserves_throughput_and_monotonicity ... ok
test ac2_nvdec_backend_selected_on_cuda_host ... ignored, AC-2 positive: requires a CUDA-capable FFmpeg
test result: ok. 2 passed; 0 failed; 1 ignored

running 5 tests (tests/rtsp_lifecycle.rs)
test result: ok. 5 passed; 0 failed; 0 ignored
```

## Quality gates

- `cargo check --workspace --all-targets` → clean (only the documented pre-existing autopilot dead-code warning)
- `cargo clippy -p frame_ingest --all-targets -- -D warnings` → clean
- `cargo fmt -p frame_ingest --check` → clean

## Next Batch

Batch 17 candidates (ready by deps):
- AZ-680 `operator_bridge_command_dispatch` (3 pts)
- AZ-681 `operator_bridge_safety_and_bit_ack` (3 pts)
- AZ-659 `frame_ingest_publisher` (3 pts) — newly unblocked because AZ-658 is now in `done/`

Suggested grouping: AZ-680 + AZ-681 (tightly coupled — both depend on AZ-678 operator_bridge command auth). AZ-659 fits a separate batch focused on the frame_ingest pipeline's tail.

## Cumulative review cadence

Last cumulative: batches 13–15 (`cumulative_review_batches_13-15_cycle1_report.md`). Next due: end of batch 18 (no cumulative review for batch 16).