[AZ-662] [AZ-669] Close batch 19: green test gate via Jetson Docker

Stand up a production-target test runner on jetson-e2e and run the deferred cargo test --workspace for batch 19. Infra: - Dockerfile.test: ubuntu:22.04 + libopencv-dev + libav*-dev + libclang-dev + protobuf-compiler + rust 1.82.0 (rustfmt, clippy). Sets LIBCLANG_PATH so clang-sys can dlopen libclang under the opencv-rust clang-runtime path. - scripts/jetson-test.sh: rsync source to jetson-e2e, docker build, docker run cargo test --workspace --no-fail-fast. Workspace fix exposed by the gate: - Cargo.toml: enable opencv "clang-runtime" feature. Without it the workspace fails to build because clang-sys is shared between opencv-binding-generator and bindgen (via ffmpeg-sys-next) and the opencv generator panics with "a `libclang` shared library is not loaded on this thread" (opencv-rust GH issue #635). Batch-19 code bugs exposed by the gate (6 compile errors + 1 algo bug): - movement_detector::optical_flow: min_max_loc signature (opencv 0.98 expects Option<&mut f64> / Option<&mut Point>); data_mut() returns *mut u8 directly, not Result. RANSAC residual now filters by the inlier mask returned by find_homography (matches the docstring; was systematically over-reporting motion magnitude on synthetic pure-pan input). - semantic_analyzer::scoring::freshness: same data_mut() fix; stddev_f32 now takes &impl core::ToInputArray so it accepts the BoxedRef<Mat> that Mat::roi returns in opencv 0.98. Result: 391 tests passed across 58 binaries, 0 in-scope failures. Two pre-existing failures in frame_ingest (batch 16-18 scope) are NOT addressed here and are recorded as leftovers: - frame_ingest_cuvid_segv: HIGH severity production bug; libavcodec58 advertises h264_cuvid but libnvcuvid.so.1 is missing at runtime, the software fallback never fires, first send_packet SEGVs. - frame_ingest_publisher_timing_flake: LOW severity; Jetson-specific timing budget too tight for ac1_three_consumers_at_rate_lose_no_frames. Neither blocks batch 20 (movement_detector / semantic_analyzer next). Co-authored-by: Cursor <cursoragent@cursor.com>
[AZ-662] [AZ-669] Archive batch 19; defer test gate
2026-06-21 21:11:09 +00:00 · 2026-05-20 22:11:16 +03:00 · 2026-05-20 21:27:52 +03:00 · 2026-05-20 19:00:39 +03:00 · 2026-05-20 18:33:15 +03:00 · 2026-05-20 18:27:15 +03:00
73 changed files with 6965 additions and 172 deletions
@@ -352,6 +352,8 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a1dce859f0832a7d088c4f1119888ab94ef4b5d6795d1ce05afb7fe159d79f98"
 dependencies = [
 "find-msvc-tools",
 "jobserver",
 "libc",
 "shlex",
 ]
@@ -388,6 +390,16 @@ dependencies = [
 "windows-link",
 ]
 [[package]]
 name = "clang"
 version = "2.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "84c044c781163c001b913cd018fc95a628c50d0d2dfea8bca77dad71edb16e37"
 dependencies = [
 "clang-sys",
 "libc",
 ]
 [[package]]
 name = "clang-sys"
 version = "1.8.1"
@@ -563,8 +575,18 @@ dependencies = [
 name = "detection_client"
 version = "0.1.0"
 dependencies = [
 "async-trait",
 "bytes",
 "parking_lot",
 "prost",
 "protoc-bin-vendored",
 "shared",
 "thiserror 1.0.69",
 "tokio",
 "tokio-stream",
 "tonic",
 "tonic-prost",
 "tonic-prost-build",
 "tracing",
 ]
@@ -590,6 +612,12 @@ dependencies = [
 "syn",
 ]
 [[package]]
 name = "dunce"
 version = "1.0.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "92773504d58c093f6de2459af4af33faa518c13451eb8f2b5698ed3d36e7c813"
 [[package]]
 name = "either"
 version = "1.15.0"
@@ -1277,6 +1305,16 @@ version = "1.0.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
 [[package]]
 name = "jobserver"
 version = "0.1.34"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9afb3de4395d6b3e67a780b6de64b51c978ecf11cb9a462c66be7d4ca9039d33"
 dependencies = [
 "getrandom 0.3.4",
 "libc",
 ]
 [[package]]
 name = "js-sys"
 version = "0.3.98"
@@ -1539,6 +1577,8 @@ dependencies = [
 name = "movement_detector"
 version = "0.1.0"
 dependencies = [
 "bytes",
 "opencv",
 "shared",
 "tokio",
 "tracing",
@@ -1708,6 +1748,39 @@ version = "1.70.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe"
 [[package]]
 name = "opencv"
 version = "0.98.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0c607a407be5ff2484f55d2eb289bffd01de84f962779b8470e76f035dd3563d"
 dependencies = [
 "cc",
 "dunce",
 "jobserver",
 "libc",
 "num-traits",
 "opencv-binding-generator",
 "pkg-config",
 "semver",
 "shlex",
 "vcpkg",
 "windows",
 ]
 [[package]]
 name = "opencv-binding-generator"
 version = "0.101.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "833f00c6deee8dd615249af42fa35ff030c5c73ee3c13e44baf1135a4d57af86"
 dependencies = [
 "clang",
 "clang-sys",
 "dunce",
 "percent-encoding",
 "regex",
 "shlex",
 ]
 [[package]]
 name = "operator_bridge"
 version = "0.1.0"
@@ -1765,6 +1838,7 @@ dependencies = [
 "fixedbitset",
 "hashbrown 0.15.5",
 "indexmap",
 "serde",
 ]
 [[package]]
@@ -2244,6 +2318,7 @@ checksum = "9774ba4a74de5f7b1c1451ed6cd5285a32eddb5cccb8cc655a4e50009e06477f"
 name = "scan_controller"
 version = "0.1.0"
 dependencies = [
 "async-trait",
 "chrono",
 "gimbal_controller",
 "mapobjects_store",
@@ -2277,6 +2352,9 @@ dependencies = [
 name = "semantic_analyzer"
 version = "0.1.0"
 dependencies = [
 "bytes",
 "opencv",
 "petgraph",
 "shared",
 "tokio",
 "tracing",
@@ -3261,6 +3339,27 @@ version = "0.4.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "712e227841d057c1ee1cd2fb22fa7e5a5461ae8e48fa2ca79ec42cfc1931183f"
 [[package]]
 name = "windows"
 version = "0.62.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "527fadee13e0c05939a6a05d5bd6eec6cd2e3dbd648b9f8e447c6518133d8580"
 dependencies = [
 "windows-collections",
 "windows-core",
 "windows-future",
 "windows-numerics",
 ]
 [[package]]
 name = "windows-collections"
 version = "0.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "23b2d95af1a8a14a3c7367e1ed4fc9c20e0a26e79551b1454d72583c97cc6610"
 dependencies = [
 "windows-core",
 ]
 [[package]]
 name = "windows-core"
 version = "0.62.2"
@@ -3274,6 +3373,17 @@ dependencies = [
 "windows-strings",
 ]
 [[package]]
 name = "windows-future"
 version = "0.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e1d6f90251fe18a279739e78025bd6ddc52a7e22f921070ccdc67dde84c605cb"
 dependencies = [
 "windows-core",
 "windows-link",
 "windows-threading",
 ]
 [[package]]
 name = "windows-implement"
 version = "0.60.2"
@@ -3302,6 +3412,16 @@ version = "0.2.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
 [[package]]
 name = "windows-numerics"
 version = "0.3.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6e2e40844ac143cdb44aead537bbf727de9b044e107a0f1220392177d15b0f26"
 dependencies = [
 "windows-core",
 "windows-link",
 ]
 [[package]]
 name = "windows-result"
 version = "0.4.1"
@@ -3354,6 +3474,15 @@ dependencies = [
 "windows_x86_64_msvc",
 ]
 [[package]]
 name = "windows-threading"
 version = "0.2.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3949bd5b99cafdf1c7ca86b43ca564028dfe27d66958f2470940f73d86d75b37"
 dependencies = [
 "windows-link",
 ]
 [[package]]
 name = "windows_aarch64_gnullvm"
 version = "0.52.6"
@@ -87,9 +87,30 @@ libc = "0.2"
 # Geospatial
 h3o = "0.7"
 # Computer vision (movement_detector ego-motion + semantic_analyzer freshness scoring).
 # `clang-runtime` is required because the workspace ALSO uses `bindgen`
 # (via `ffmpeg-sys-next`), and the opencv generator's static libclang
 # linkage conflicts with bindgen's clang-sys instance — symptom:
 # "a `libclang` shared library is not loaded on this thread" at build
 # time. See opencv-rust GH issue #635. The runtime feature switches
 # opencv-binding-generator to dlopen libclang via `LIBCLANG_PATH`,
 # resolving the conflict.
 opencv = { version = "0.98", default-features = false, features = ["calib3d", "imgproc", "video", "clang-runtime"] }
 # Graph data structures (semantic_analyzer primitive graph)
 petgraph = "0.8"
 # Multimedia (RTSP + H.264/265 decode for frame_ingest — see AZ-658).
-# Linked dynamically against the host FFmpeg 8.x install (libavcodec /
+# Linked dynamically against the host FFmpeg via pkg-config.
-# libavformat / libavutil / libswscale / libswresample) via pkg-config.
+# `ffmpeg-sys-next` performs compile-time FFmpeg version detection
 # (sets `ffmpeg_4_4` / `ffmpeg_5_x` / `ffmpeg_8_x` cfg flags
 # automatically — see crates.io README), so this single dep pin
 # compiles against FFmpeg 3.4 through 8.x. The production Jetson
 # target (JetPack 6 / Ubuntu 22.04) ships FFmpeg 4.4; the macOS
 # dev box typically has 6.x or 7.x via Homebrew. Default features
 # pull in: codec (libavcodec-dev), device (libavdevice-dev), filter
 # (libavfilter-dev), format (libavformat-dev), software-resampling
 # (libswresample-dev), software-scaling (libswscale-dev).
 ffmpeg-next = "8.1"
 # Test scaffolding
@@ -0,0 +1,80 @@
 # Test image for the autopilot workspace.
 #
 # Mirrors the production target (Jetson Orin Nano Super, JetPack 6, Ubuntu
 # 22.04 LTS aarch64, FFmpeg 4.4, OpenCV 4.8) — see deploy/jetson/README.md.
 # `ffmpeg-sys-next 8.1` performs compile-time FFmpeg version detection
 # (sets `ffmpeg_4_4` cfg automatically), so the workspace's `ffmpeg-next
 # = "8.1"` pin works against Ubuntu 22.04's FFmpeg 4.4 with no code
 # change.
 #
 # Build (on the Jetson):
 #   docker build -t autopilot-test -f Dockerfile.test .
 #
 # Run (mount the source so `target/` is cached across runs):
 #   docker run --rm -v "$PWD:/workspace" -w /workspace autopilot-test
 #
 # Override the command for ad-hoc work:
 #   docker run --rm -it -v "$PWD:/workspace" -w /workspace autopilot-test \
 #     cargo test --workspace --no-fail-fast --color always
 #
 # First build (cold apt + rustup): ~10-20 min on Jetson Orin Nano Super.
 # Subsequent builds (only Cargo.toml / sources changed): seconds.
 FROM ubuntu:22.04
 ENV DEBIAN_FRONTEND=noninteractive
 # Production-matching system deps. Versions resolved from
 # jammy / jammy-updates / jammy-security so the resulting cargo
 # build/test environment is identical to what `apt install` would
 # yield on a clean JetPack 6 Jetson.
 RUN apt-get update && apt-get install -y --no-install-recommends \
        build-essential \
        cmake \
        pkg-config \
        ca-certificates \
        curl \
        git \
        libssl-dev \
        libclang-dev \
        clang \
        libopencv-dev \
        libavcodec-dev \
        libavdevice-dev \
        libavfilter-dev \
        libavformat-dev \
        libavutil-dev \
        libswscale-dev \
        libswresample-dev \
        protobuf-compiler \
    && rm -rf /var/lib/apt/lists/*
 # `clang-sys` (used by both opencv-sys and ffmpeg-sys-next via bindgen)
 # looks for `libclang.so` in the default linker search path. Ubuntu's
 # `libclang-14-dev` only ships the unversioned symlink under
 # `/usr/lib/llvm-14/lib/`, so we point at it explicitly. Without
 # this, the build panics with "a `libclang` shared library is not
 # loaded on this thread".
 ENV LIBCLANG_PATH=/usr/lib/llvm-14/lib
 # Pin to the same Rust toolchain the workspace's rust-toolchain.toml
 # expects (channel = "stable", profile = "minimal", components =
 # ["rustfmt", "clippy"]). We pin the patch level here to keep CI
 # reproducible; the toolchain file overrides via `+stable` if the
 # Jetson dev wants a moving target.
 ENV RUSTUP_HOME=/usr/local/rustup \
    CARGO_HOME=/usr/local/cargo \
    PATH=/usr/local/cargo/bin:$PATH
 RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \
        | sh -s -- -y --default-toolchain 1.82.0 --profile minimal \
            --component rustfmt --component clippy \
    && rustup --version \
    && cargo --version \
    && rustc --version
 WORKDIR /workspace
 # Default to running the full workspace test suite. Override at
 # `docker run` time when needed.
 CMD ["cargo", "test", "--workspace", "--no-fail-fast", "--color", "always"]
@@ -75,8 +75,14 @@
 - **Epic**: AZ-627
 - **Directory**: `crates/frame_ingest/`
 - **Public API**:
-  - `crates/frame_ingest/src/lib.rs` (`FrameIngest`, `FrameIngestHandle::subscribe() -> Receiver<Frame>`, `health()`)
+  - `crates/frame_ingest/src/lib.rs` (`FrameIngest`, `FrameIngestHandle`, `ConsumerId`)
  - `FrameIngestHandle::subscribe() -> Receiver<Frame>` — raw broadcast receiver (no per-consumer accounting)
  - `FrameIngestHandle::subscribe_as(ConsumerId) -> FrameReceiver` — receiver with per-consumer lag accounting
  - `FrameIngestHandle::publisher() -> Arc<FramePublisher>` — direct publisher handle for the composition root
  - `FrameIngestHandle::dropped_frames(ConsumerId) -> u64`, `publishes_total() -> u64`
  - `FrameIngestHandle::health() -> ComponentHealth`
 - **Internal**:
  - `crates/frame_ingest/src/internal/publisher.rs` (`FramePublisher`, `FrameReceiver`, `PublisherStats`)
  - `crates/frame_ingest/src/internal/rtsp_client.rs`
  - `crates/frame_ingest/src/internal/decoder.rs`
  - `crates/frame_ingest/src/internal/timestamp.rs`
@@ -91,14 +97,22 @@
 - **Epic**: AZ-628
 - **Directory**: `crates/detection_client/`
 - **Public API**:
-  - `crates/detection_client/src/lib.rs` (`DetectionClient`, `DetectionClientHandle::request(Frame) -> Result<DetectionBatch>`, `health()`)
+  - `crates/detection_client/src/lib.rs` (`DetectionClient`, `DetectionClientConfig`, `DetectionClientHandle`, `DetectionEvent`, `ConnectionState`, `Tier1DegradationReason`)
  - `DetectionClient::run(frame_rx: Receiver<Frame>) -> (JoinHandle, DetectionClientHandle)` — spawns the gRPC supervisor task
  - `DetectionClientHandle::subscribe_events() -> Receiver<DetectionEvent>` — broadcast stream of batches, schema errors, model-version changes, Tier-1 degradation transitions
  - `DetectionClientHandle::health() -> ComponentHealth`
  - `DetectionClientHandle::stats() -> Arc<DetectionStats>`, `latency_p50/p99()`, `connection_state()`, `shutdown()`
 - **Internal**:
  - `crates/detection_client/build.rs` (`tonic-build` for the gRPC proto)
  - `crates/detection_client/proto/detections.proto` (vendored copy of `../detections` contract per `architecture.md §10`)
-  - `crates/detection_client/src/internal/grpc/*` (bi-directional streaming client, version handshake)
+  - `crates/detection_client/src/internal/runtime.rs` (supervisor + bi-directional stream session)
  - `crates/detection_client/src/internal/budget.rs` (drop-oldest in-flight tracker)
  - `crates/detection_client/src/internal/latency.rs` (sliding-window p99 + degradation latch)
  - `crates/detection_client/src/internal/stats.rs` (lock-free atomic counters)
  - `crates/detection_client/src/internal/proto.rs` (generated tonic/prost types)
 - **Owns**: `crates/detection_client/**`
 - **Imports from**: `shared`
- **Consumed by**: `scan_controller` (handle for direct request), `telemetry_stream` (via constructor-injected `Receiver<DetectionBatch>` for operator overlay)
+- **Consumed by**: `scan_controller` (subscribes to events), `telemetry_stream` (via composition-root-wired `Receiver<DetectionBatch>` for operator overlay)
 ---
@@ -0,0 +1,89 @@
 # Batch Report
 **Batch**: 17
 **Cycle**: 1
 **Tasks**: AZ-680, AZ-681
 **Date**: 2026-05-20
 ## Task Results
 | Task | Status | Files Modified | Tests | AC Coverage | Issues |
 |------|--------|---------------|-------|-------------|--------|
 | AZ-680_operator_bridge_command_dispatch | Done | 14 files | scan_controller: 8 (2 new); operator_bridge: 20 lib + 9 integration; mission_executor: 35 lib | 5/5 ACs covered | None |
 | AZ-681_operator_bridge_safety_and_bit_ack | Done | shared with AZ-680 | (counted above; 4 new integration tests cover AZ-681 ACs) | 4/4 ACs covered | None |
 ## AC Coverage map — AZ-680
 | AC | Test | File | Notes |
 |----|------|------|-------|
 | AC-1 Confirm forwards target hint | `az680_ac1_confirm_forwards_to_scan_router` | `crates/operator_bridge/tests/dispatcher.rs` | Records POI in registry, dispatches `ConfirmPoi`, asserts `scan_router.route` invoked exactly once with the original command |
 | AC-2 Re-transmit returns cached ack | `az680_ac2_retransmit_returns_cached_ack` | same file | Same `command_id` dispatched twice; second call returns `Ok` without re-invoking router (60 s `IdempotencyCache`) |
 | AC-3 Unknown POI id rejected | `az680_ac3_unknown_poi_id_rejected` | same file | Asserts `CommandAck::Error { reason: "unknown_poi_id" }` and router never invoked |
 | AC-4 Expired POI rejected | `az680_ac4_expired_poi_rejected` | same file | Pre-seeds a surfaced POI with past `deadline`; asserts `expired` ack and router not invoked |
 | AC-5 Decline appends IgnoredItem via scan_controller | `az680_ac5_decline_forwards_to_scan_router` | same file | DeclinePoi dispatches into `scan_router.route` exactly once; ack `Ok` |
 Plus scan_controller native coverage of the `ConfirmPoi` path (queue-side resolution): `confirm_poi_via_operator_command_emits_action` + `confirm_poi_unknown_id_is_validation_error` in `crates/scan_controller/tests/poi_queue.rs`.
 ## AC Coverage map — AZ-681
 | AC | Test | File | Notes |
 |----|------|------|-------|
 | AC-1 BIT-DEGRADED ack succeeds | `az681_ac1_bit_degraded_ack_forwards` | `crates/operator_bridge/tests/dispatcher.rs` | Severity lookup returns `Some(true)`; safety_router.acknowledge_bit_degraded invoked exactly once with the report_id + operator_id |
 | AC-2 BIT-FAIL ack rejected | `az681_ac2_bit_fail_ack_rejected` | same file | Severity lookup returns `Some(false)`; ack returns `cannot_acknowledge_fail`; safety_router not invoked |
 | AC-3 Safety-override forwards with scope + duration | `az681_ac3_safety_override_forwards_with_audit_entry` | same file | SafetyOverride { BatteryRtl, 60s } dispatched; safety_router.apply_safety_override called once with the exact scope/duration; audit log contains exactly one matching `SafetyOverride` entry with `outcome: Ok` |
 | AC-4 Audit log redacts secrets | `az681_ac4_audit_log_contains_no_signature_or_session_token` | same file | Every audit entry serialised to JSON; asserts no `signature` and no `session_token` substring. Lock-in: `AuditEntry` enum has no fields that could leak either secret |
 ## AC Test Coverage: All covered (9/9 across both tasks)
 ## Code Review Verdict: PASS (self-review — see findings below)
 ## Auto-Fix Attempts: 0
 ## Stuck Agents: None
 ## Files modified
 ```
 M crates/shared/src/models/operator.rs                     (+SafetyOverrideScope)
 M crates/shared/src/contracts/mod.rs                       (+ScanCommandRouter +MissionSafetyRouter +BitReportSeverityLookup)
 M crates/scan_controller/Cargo.toml                        (+async-trait)
 M crates/scan_controller/src/lib.rs                        (confirm_poi + ScanCommandRouter impl + SubmitOutcome::Confirmed)
 M crates/scan_controller/src/internal/poi_queue/mod.rs     (+ConfirmAction + PoiQueue::confirm)
 M crates/scan_controller/tests/poi_queue.rs                (+2 tests: confirm path; replaced exhaustive match with catch-all to handle new variant)
 M crates/mission_executor/src/lib.rs                       (+pub use SafetyDispatchHandle)
 M crates/mission_executor/src/internal/mod.rs              (+safety_dispatch module)
 A crates/mission_executor/src/internal/safety_dispatch.rs  (NEW: MissionSafetyRouter impl)
 M crates/mission_executor/src/internal/bit.rs              (+bounded report_overalls FIFO; +report_overall + BitReportSeverityLookup impl on BitControllerHandle)
 M crates/operator_bridge/src/lib.rs                        (registry+dispatcher wiring; with_scan_router/safety_router/bit_severity_lookup/audit_sink/dispatcher; dispatch_command; OperatorCommandSink impl now real; registry forget/record on dequeue/surface)
 M crates/operator_bridge/src/internal/mod.rs               (+audit +dispatcher +idempotency +poi_registry)
 A crates/operator_bridge/src/ack.rs                        (NEW: CommandAck + ack_reasons)
 A crates/operator_bridge/src/internal/audit.rs             (NEW: AuditEntry / AuditSink / TracingAuditSink)
 A crates/operator_bridge/src/internal/dispatcher.rs        (NEW: OperatorCommandDispatcher + Builder)
 A crates/operator_bridge/src/internal/idempotency.rs       (NEW: IdempotencyCache 60s TTL)
 A crates/operator_bridge/src/internal/poi_registry.rs      (NEW: SurfacedPoi + SurfacedPoiRegistry)
 A crates/operator_bridge/tests/dispatcher.rs               (NEW: 9 integration tests)
 M _docs/_process_leftovers/2026-05-20_mission_executor_ac3_flake.md  (note: ac1 also flakes)
 R _docs/02_tasks/todo/AZ-680_operator_bridge_command_dispatch.md → done/...
 R _docs/02_tasks/todo/AZ-681_operator_bridge_safety_and_bit_ack.md → done/...
 ```
 ## Architecture notes
 - The cross-component dispatch shape is now: `operator_bridge` (Layer 3) → `ScanCommandRouter` / `MissionSafetyRouter` / `BitReportSeverityLookup` traits in `shared::contracts` (Layer 1) → concrete impls on `ScanControllerHandle` and on the new `SafetyDispatchHandle` (constructed at the composition root from `BitController::ack_tx` + `BatteryMonitorHandle`).
 - `BitControllerHandle` now retains a bounded FIFO of the last 16 `(report_id, overall)` pairs so `is_acknowledgeable` can answer for any report id observed in the current pre-flight gate cycle. Beyond that horizon, the dispatcher rejects with `unknown_bit_report` rather than guessing.
 - `SafetyOverrideScope` is `#[non_exhaustive]` so future variants (`LinkLost`, `Geofence`) extend without breaking downstream matchers. `SafetyDispatchHandle::apply_safety_override` returns a typed Validation error on any unwired scope, so adding a variant to the enum without wiring the executor side fails closed.
 - The audit log is a structured `tracing::info!` per entry by default (`TracingAuditSink`). The `AuditSink` trait keeps the door open for a file-based persistent sink later; integration tests substitute a recording sink.
 - Idempotency cache TTL: 60 s per the task spec. Lazy eviction on each lookup/insert keeps the cache small without a background sweeper.
 ## Quality gates
 - `cargo fmt --all`: clean
 - `cargo clippy -p shared -p scan_controller -p mission_executor -p operator_bridge --all-targets -- -D warnings`: clean
 - `cargo clippy --workspace --all-targets -- -D warnings`: pre-existing `Runtime::vlm_provider_name` dead-code lint (out-of-scope; tracked in `_docs/_process_leftovers/2026-05-20_autopilot_clippy.md`)
 - `cargo test -p shared -p scan_controller -p operator_bridge -p mission_executor`: all green
 - `cargo test --workspace`: one pre-existing flake — `mission_executor::ac1_multirotor_happy_path_reaches_done` (same `await_state` polling race as the documented `ac3` flake; passes on retry; leftover updated)
 ## Suggested next batch
 From `_docs/02_tasks/_dependencies_table.md`, ready tasks after this batch:
 - `AZ-659_frame_ingest_publisher` (3pt, no new deps) — was eligible for this batch but excluded for cohesion
 - `AZ-682_scan_controller_state_machine_skeleton` follow-ups (AZ-684 evidence ladder) once `scan_controller` confirm path lands the FSM-side follow-through
 - `AZ-685_mapobjects_store_ignored_items` (consumes the `DeclineAction` payload AZ-680 now produces end-to-end)
@@ -0,0 +1,68 @@
 # Batch 18 — Cycle 1 Implementation Report
 **Tasks**: AZ-659, AZ-660, AZ-661
 **Completed**: 2026-05-20
 **Status**: All tests pass; code review PASS_WITH_WARNINGS; committed `0854d3b`
 ---
 ## AZ-659 — frame_ingest publisher (3 pts)
 **Files added/changed**:
 - `crates/frame_ingest/src/internal/publisher.rs` — `FramePublisher`, `FrameReceiver`, `ConsumerId`, `PublisherStats`
 - `crates/frame_ingest/src/internal/mod.rs` — exports `publisher`
 - `crates/frame_ingest/src/lib.rs` — `FrameIngestHandle` extended with `subscribe_as`, `publisher`, `dropped_frames`, `publishes_total`
 - `crates/frame_ingest/tests/publisher.rs` — AC-1/2/3 integration tests
 **ACs**: All passing.
 ---
 ## AZ-660 — detection_client gRPC bi-directional stream (5 pts)
 **Files added/changed**:
 - `crates/detection_client/Cargo.toml` — added `tonic`, `prost`, `tonic-prost-build`, `protoc-bin-vendored`
 - `crates/detection_client/build.rs` — proto codegen via `tonic-prost-build`
 - `crates/detection_client/proto/detections.proto` — gRPC contract (FrameRequest / DetectionResponse bi-di stream)
 - `crates/detection_client/src/internal/mod.rs` — module registry
 - `crates/detection_client/src/internal/proto.rs` — generated code re-export
 - `crates/detection_client/src/internal/budget.rs` — `BudgetTracker` (drop-oldest VecDeque, default capacity 2)
 - `crates/detection_client/src/internal/stats.rs` — `DetectionStats` (lock-free AtomicU64 counters)
 - `crates/detection_client/src/internal/runtime.rs` — supervisor + `run_stream_session` with bounded backoff reconnect
 - `crates/detection_client/src/lib.rs` — `DetectionClient`, `DetectionClientConfig`, `DetectionClientHandle`, `DetectionEvent`, `ConnectionState`
 - `crates/detection_client/tests/stream.rs` — AC-1/2/3/4 integration tests (fixture in-process gRPC server)
 **ACs**: All passing.
 ---
 ## AZ-661 — schema validation + model_version + latency degradation (2 pts)
 Implemented inside the same `detection_client` crates (AC-660 and AC-661 share the same modules):
 - `src/internal/latency.rs` — `LatencyWindow` ring-buffer + `DegradationTransition` latch
 - `src/internal/runtime.rs::handle_response` — schema version check, model_version latch, Tier1 degradation evaluation after every response
 - `crates/detection_client/tests/stream.rs` — AC-1/2/3 integration tests
 **ACs**: All passing.
 ---
 ## Code Review
 **Verdict**: PASS_WITH_WARNINGS — see `_docs/03_implementation/reviews/batch_18_review.md`.
 Findings:
 - F1 (Medium, fixed): dead code in `handle_response` (`let now`, `let _ = in_flight`) removed.
 - F2–F4: Low findings, no action required this batch.
 ---
 ## Architecture / Doc Updates
 - `_docs/02_document/module-layout.md` — `frame_ingest` and `detection_client` sections updated to reflect actual streaming API.
 ---
 ## Remaining tasks in `todo/`
 9 tasks remaining across 3 components (movement_detector, semantic_analyzer, scan_controller).
@@ -0,0 +1,158 @@
 # Batch 19 — Cycle 1 Implementation Report
 **Tasks**: AZ-662, AZ-669
 **Completed**: 2026-05-20
 **Initial commit**: `db844db [AZ-662] [AZ-669] Implement ego-motion estimator and primitive graph`
 **Archival commit**: `202b2cb [AZ-662] [AZ-669] Archive batch 19; defer test gate`
 **Test-gate commit**: pending — closes this batch with the Jetson Docker test infra + 6 follow-up code fixes the test gate exposed
 **Status**: Code committed; lightweight code review PASS_WITH_WARNINGS; `cargo test --workspace` **GREEN for batch 19 scope** (see "Test Run — DONE" section). 2 pre-existing failures in `frame_ingest` (batch 16/17/18 code) recorded as leftovers, not blocking.
 ---
 ## AZ-662 — movement_detector ego-motion + telemetry-skew gate (5 pts)
 **Files added/changed**:
 - `Cargo.toml` — workspace deps: `opencv = "0.98"` (`calib3d, imgproc, video` features), `petgraph = "0.8"`
 - `crates/movement_detector/Cargo.toml` — depend on workspace `opencv`; `bytes` added as dev-dep
 - `crates/movement_detector/src/internal/mod.rs` — new sub-modules
 - `crates/movement_detector/src/internal/zoom_bands.rs` — `ZoomBandTolerances` (zoom-out 50/100 ms; zoom-in 25/50 ms per `description.md §5`), `zoom_band_from_level()`
 - `crates/movement_detector/src/internal/telemetry_sync.rs` — `check_skew()` returning `SkewExceeded { band, gimbal_skew_ns, uav_skew_ns }`
 - `crates/movement_detector/src/internal/optical_flow/mod.rs` — `frame_to_gray`, `is_degenerate` (min/max contrast), LK sparse optical flow + RANSAC `findHomography`
 - `crates/movement_detector/src/internal/ego_motion.rs` — `EgoMotionEstimator` (stateful, keeps `prev_gray: Option<Mat>`) + `EgoMotionCounters` (atomic `telemetry_skew_drops_*`, `optical_flow_degenerate_total`)
 - `crates/movement_detector/src/lib.rs` — `MovementDetectorHandle` exposes `estimate_ego_motion(...)` and per-band skew-drop counters
 **ACs**:
 | AC | Test | Notes |
 |----|------|-------|
 | AC-1: pure-pan residual ≈ 0 | `ego_motion::tests::ac1_pure_pan_residual_near_zero` | Checkerboard frames; asserts `H[0][2] ≈ dx ± 2.5 px` and residual < 3.0 px |
 | AC-2: zoom-out skew > 50 ms → `Err(SkewExceeded)` + counter | `ego_motion::tests::ac2_skew_above_zoom_out_tolerance_dropped` | 200 ms gimbal-skew injected; asserts counter increments |
 | AC-3: saturated white frame → `Err(OpticalFlowDegenerate)` + counter | `ego_motion::tests::ac3_degenerate_white_frame` | All-255 `CV_8UC1` Mat; asserts `degenerate_total == 1` |
 Plus internal unit tests in `zoom_bands` (3) and `telemetry_sync` (3) covering tolerance-table correctness and skew-direction symmetry.
 **NFR (30 ms p99 ego-motion on Jetson Orin Nano)**: not yet measured — deferred to Step 15 (Performance Test) per greenfield flow.
 ---
 ## AZ-669 — semantic_analyzer primitive graph + path-freshness scoring (5 pts)
 **Files added/changed**:
 - `crates/semantic_analyzer/Cargo.toml` — depend on workspace `opencv`, `tracing`, `bytes` (dev)
 - `crates/semantic_analyzer/src/internal/mod.rs` — new sub-modules
 - `crates/semantic_analyzer/src/internal/primitive_graph/graph.rs` — `NodeType { Path, Endpoint, Context }`, `PrimitiveNode`, `PrimitiveGraph` with `path_nodes()` iterator + `valid/disconnected` flags
 - `crates/semantic_analyzer/src/internal/primitive_graph/builder.rs` — `PrimitiveGraphBuilder` (class-name → `NodeType` mapping, ROI-centroid filter, proximity-based edges with `adjacency_factor = 2.5`, BFS connectivity check) + `GraphCounters` (`graphs_built_total`, `disconnected_graphs_total`)
 - `crates/semantic_analyzer/src/internal/primitive_graph/mod.rs` — re-exports
 - `crates/semantic_analyzer/src/internal/scoring/freshness.rs` — `FreshnessScorer::score(graph, frame_crop) -> Vec<PathFreshnessScore>` combining Laplacian-variance edge clarity, pixel std-dev texture, and ~16 px border-region "undisturbed surroundings" variance; each sub-score normalised then averaged + clamped to `[0.0, 1.0]`
 - `crates/semantic_analyzer/src/internal/scoring/mod.rs` — re-exports
 - `crates/semantic_analyzer/src/lib.rs` — `SemanticAnalyzerHandle` exposes `build_primitive_graph(...)`, `score_path_freshness(...)`, `graphs_built_total()`, `disconnected_graphs_total()`
 **ACs**:
 | AC | Test | Notes |
 |----|------|-------|
 | AC-1: 3 footpath + 2 branch-pile + 5 tree → 3 path + 2 endpoint + 5 context nodes | `primitive_graph::builder::tests::ac1_node_counts_per_class` | Asserts node counts + `graphs_built_total == 1` |
 | AC-2: every score ∈ `[0.0, 1.0]` | `scoring::freshness::tests::ac2_freshness_score_bounded` | Run against uniform-gray and noisy-textured frames |
 | AC-3: disconnected path components → flagged + counter | `primitive_graph::builder::tests::ac3_disconnected_path_graph_flagged` | Uses `adjacency_factor = 0.5` to force isolation |
 **NFR (≤30 ms graph build, ≤50 ms scoring per ROI on Jetson Orin Nano)**: not yet measured — deferred to Step 15.
 ---
 ## Code Review (Lightweight, inline)
 A full `/code-review` skill invocation was deferred (autodev session under context pressure + disk constraint).  Inline review of the diff (`git show db844db`) against the two task specs.
 **Verdict**: PASS_WITH_WARNINGS
 | # | Severity | Category | Location | Finding |
 |---|----------|----------|----------|---------|
 | F1 | Medium | Maintainability / Error-handling | `crates/movement_detector/src/internal/ego_motion.rs:169-170` | `optical_flow::is_degenerate(&curr_gray).unwrap_or(false)` silently swallows the inner `opencv::Result`. Per `coderule.mdc` "Never suppress errors silently". Suggest: propagate as `EgoMotionError::Internal(err.message)`. |
 | F2 | Low | Architecture / Unused dependency | `Cargo.toml:94` | `petgraph = "0.8"` was added to workspace deps but `crates/semantic_analyzer/src/internal/primitive_graph/builder.rs` uses `std::collections::{HashMap, VecDeque}` directly. Either delete the dep or migrate the adjacency / BFS code to `petgraph::Graph`. |
 | F3 | Low | Maintainability / Magic numbers | `crates/semantic_analyzer/src/internal/scoring/freshness.rs:99-103` | Normalisation scales (`1500.0` edge, `40.0` texture, `3000.0` surround) are unexplained constants. Suggest: hoist to named consts with a one-line comment on calibration source (or note "empirical, to be tuned with field data"). |
 | F4 | Low | Maintainability | `crates/semantic_analyzer/src/internal/primitive_graph/builder.rs:13-27` | `classify_class_name` does case-insensitive substring matching against `class_name`. Fragile against detection-model class renames. Acceptable for cycle 1 (Tier-1 schema is still evolving); revisit when detection schema is frozen. |
 | F5 | Low | Maintainability | `crates/semantic_analyzer/src/internal/scoring/freshness.rs:127,135,171` | `stddev_mat.at::<f64>(0).map(|v| *v).unwrap_or(0.0)` swallows the `Result` from `Mat::at`. Same family as F1; defaulting to 0 silently hides genuine OpenCV failures. |
 No Critical, no High, no Security findings.
 **Auto-fix attempts**: 0 (skill not formally invoked in this session — F1/F5 should be addressed in a follow-up touch-up batch when `movement_detector` or `semantic_analyzer` is next modified).
 ---
 ## Test Gate — DONE
 Ran via the new Jetson Docker test pipeline (`Dockerfile.test` + `scripts/jetson-test.sh`), which mirrors the production target (Jetson Orin Nano Super, JetPack 6, Ubuntu 22.04 aarch64, FFmpeg 4.4, OpenCV 4.5).
 **Result**: **391 tests passed across 58 test binaries**, 2 ignored (NVDEC-positive cases that explicitly require a CUDA-capable FFmpeg), 0 in-scope failures.
 ### Infra introduced (commits in next push)
 | Artifact | Purpose |
 |---|---|
 | `Dockerfile.test` | ubuntu:22.04 base + `libopencv-dev` + `libav*-dev` + `libclang-dev` + protobuf-compiler + rust 1.82.0 (rustfmt, clippy) |
 | `scripts/jetson-test.sh` | rsync source → Jetson, `docker build`, `docker run cargo test --workspace --no-fail-fast --color always` |
 ### Workspace fix exposed by the gate
 | File | Change | Why |
 |---|---|---|
 | `Cargo.toml:91` | `opencv` features += `"clang-runtime"` | Without it, the workspace fails to build because the same `clang-sys 1.8.1` instance is shared with `bindgen` (via `ffmpeg-sys-next`), and the opencv binding generator panics with "a `libclang` shared library is not loaded on this thread". `clang-runtime` makes the opencv generator dlopen libclang via `LIBCLANG_PATH` rather than relying on the statically linked instance. See opencv-rust GH issue #635. |
 ### Batch-19 code fixes exposed by the gate
 The test gate caught **6 real compile errors** + **1 algorithm bug** in the original `db844db` source. These are not "test infrastructure" issues; they are bugs that the deferred test gate let through. Fixed in-scope per coderule.mdc (adjacent hygiene allowed when the change is in the same files I authored for this batch):
 | # | File | Line | Bug | Fix |
 |---|---|---|---|---|
 | 1 | `crates/movement_detector/src/internal/optical_flow/mod.rs` | 39-46 | `min_max_loc` called with `&mut min_val, &mut max_val, &mut Point::default(), &mut Point::default()` — opencv 0.98 expects `Option<&mut f64>` etc. | Wrapped min/max in `Some(...)`; passed `None` for the unused loc args. |
 | 2 | `crates/movement_detector/src/internal/optical_flow/mod.rs` | 70 | `rgb_mat.data_mut()?` — opencv 0.98 changed `data_mut()` to return `*mut u8` directly (no `Result`). | Removed the `?`. |
 | 3 | `crates/movement_detector/src/internal/optical_flow/mod.rs` | 85 | Same as #2 for `mat.data_mut()?`. | Removed the `?`. |
 | 4 | `crates/semantic_analyzer/src/internal/scoring/freshness.rs` | 56 | Same as #2 for `mat.data_mut()?`. | Removed the `?`. |
 | 5 | `crates/semantic_analyzer/src/internal/scoring/freshness.rs` | 64 | Same as #2 for `rgb.data_mut()?`. | Removed the `?`. |
 | 6 | `crates/semantic_analyzer/src/internal/scoring/freshness.rs` | 94, 131 | `stddev_f32(&roi)` called with `&BoxedRef<'_, Mat>` (opencv 0.98 changed `Mat::roi` to return `BoxedRef<Mat>` instead of `Mat`); `stddev_f32` signature expects `&Mat`. | Changed `stddev_f32` to take `&impl core::ToInputArray` — same approach opencv's own API uses, accepts both `&Mat` and `&BoxedRef<Mat>` without manual deref. |
 | 7 (algorithm) | `crates/movement_detector/src/internal/optical_flow/mod.rs` | 172-191 (now 172-201) | Residual computation iterated over ALL LK-tracked feature pairs, not RANSAC inliers — but the docstring on `HomographyResult::residual_magnitude_px` says "Mean reprojection residual across **inliers**". For a synthetic pure-pan checkerboard, edge features with no match in the post-shift region become RANSAC outliers and inflated the residual to 4.08 px (test asserts < 3.0). Real production bug: the residual was systematically over-reporting motion magnitude. | Added a check against the `mask` returned by `find_homography(..., RANSAC, 3.0)` so only inlier pairs contribute. Now matches the docstring + passes AC-1. |
 ### Pre-existing failures (out of batch 19 scope — recorded as leftovers)
 These are in `crates/frame_ingest/` (batches 16/17/18, owned by AZ-657/658). The Jetson test gate is the first place they have surfaced because the macOS dev box doesn't have h264_cuvid registered at all and these tests had not been run on production-target hardware before.
 | Failing target | Symptom | Root cause |
 |---|---|---|
 | `cargo test -p frame_ingest --lib` | SIGSEGV at `[h264_cuvid @ ...] Cannot load libnvcuvid.so.1` | `decoder.rs::try_open` uses `Context::new().decoder().open_as(codec)` which returns `Ok` even for codecs whose runtime backend (libnvcuvid) is missing. The fallback to software h264 never fires; the first `send_packet` SEGVs. Ubuntu's libavcodec58 advertises `h264_cuvid` because it was built with cuvid headers — but the dynamic libnvcuvid.so.1 is NOT in the test container. → leftover `2026-05-20_frame_ingest_cuvid_segv.md`. |
 | `cargo test -p frame_ingest --test decoder_pipeline` | Same SIGSEGV chain | Same root cause as above. |
 | `cargo test -p frame_ingest --test publisher::ac1_three_consumers_at_rate_lose_no_frames` | "telemetry stalled at 25/30" | Timing-sensitive test; the per-frame budget is too tight for the Jetson Orin Nano Super (6-core ARM Cortex-A78AE) compared to the Mac dev box (M-series). Passed on the second run, so this is flaky on slower hardware. → leftover `2026-05-20_frame_ingest_publisher_timing_flake.md`. |
 These two leftovers do NOT block batch 20: AZ-663 / AZ-664 (movement_detector) and AZ-670 / AZ-671 (semantic_analyzer) — the actual candidates per `_docs/02_tasks/_dependencies_table.md` — do not touch `frame_ingest`.
 ---
 ## Architecture / Doc Updates
 None in this batch. The `movement_detector` and `semantic_analyzer` component docs (`_docs/02_document/components/*/description.md`) already described this exact split (§3, §5, §7 of each). No drift to record.
 ---
 ## Jira
 - AZ-662: transitioned `In Progress → In Testing` (transition id 32).
 - AZ-669: transitioned `In Progress → In Testing` (transition id 32).
 Per `implement/SKILL.md` Step 12, `In Testing` is set post-commit and signals "dev work done, tests should now run" — it is independent of whether the local test gate has fired.
 ---
 ## Remaining tasks in `todo/`
 7 tasks across 3 components (2 each in `movement_detector` and `semantic_analyzer`, 3 in `scan_controller`):
 | Task | Component | Pts |
 |------|-----------|-----|
 | AZ-663 | movement_detector | clustering_and_emission |
 | AZ-664 | movement_detector | fp_cap_and_q14_fallback |
 | AZ-670 | semantic_analyzer | roi_cnn |
 | AZ-671 | semantic_analyzer | action_policy |
 | AZ-684 | scan_controller | evidence_ladder |
 | AZ-685 | scan_controller | mapobjects_dispatch |
 | AZ-686 | scan_controller | gimbal_issuance |
 ## Next Batch
 Batch-19 test gate is **GREEN**. Ready to auto-chain to batch 20 selection at the next autodev tick.
@@ -0,0 +1,85 @@
 # Cumulative Code Review — Batches 16-18 (Cycle 1)
 **Scope**: AZ-658, AZ-680, AZ-681, AZ-659, AZ-660, AZ-661
 **Date**: 2026-05-20
 **Overall Verdict**: PASS_WITH_WARNINGS
 ---
 ## Scope Summary
 | Batch | Tasks | Components |
 |-------|-------|-----------|
 | 16 | AZ-658 frame_ingest decoder | frame_ingest |
 | 17 | AZ-680 operator_bridge command dispatch; AZ-681 safety+BIT ack | shared, scan_controller, mission_executor, operator_bridge |
 | 18 | AZ-659 frame_ingest publisher; AZ-660 detection_client gRPC stream; AZ-661 schema+health | frame_ingest, detection_client |
 ---
 ## Cross-Batch Architecture Consistency
 ### Layer compliance (all batches)
 No layer violations found across batches 16-18. Every crate imports only `shared` (Layer 1) for cross-component types. Cross-component dispatch uses traits in `shared::contracts`. The `detection_client` receives a `broadcast::Receiver<Frame>` injected by the composition root — it does not import `frame_ingest`.
 ### Pattern consistency
 | Pattern | Batches 16-18 usage |
 |---------|---------------------|
 | Async actor model | All components expose `run()` → `JoinHandle` + `Handle`. ✓ |
 | `shared::models` for data | `Frame`, `DetectionBatch`, `BoundingBox`, `Detection` all come from `shared`. ✓ |
 | `shared::contracts` for cross-cutting dispatch | `ScanCommandRouter`, `MissionSafetyRouter`, `BitReportSeverityLookup` added in batch 17; `detection_client` and `frame_ingest` do not need new traits. ✓ |
 | Lock-free counters | `AtomicU64` used uniformly across `detection_client::DetectionStats`, `frame_ingest::PublisherStats`. ✓ |
 | Broadcast channels for fan-out | Batch 18 adds `FramePublisher` (wrapping `tokio::sync::broadcast`) for the frame pipeline; consistent with the existing telemetry broadcast pattern. ✓ |
 ### Interface wiring readiness
 The composition root (`crates/autopilot/src/runtime.rs`) still needs to wire:
 - `frame_ingest.handle().subscribe_as(ConsumerId::DetectionClient)` → raw receiver forwarded to `DetectionClient::run(frame_rx)`
 - `detection_client_handle.subscribe_events()` → event receiver forwarded to `scan_controller` and `telemetry_stream`
 Neither wiring is in scope for batches 16-18 — they belong to the final runtime composition task. No interface mismatch found.
 ---
 ## Findings (cumulative, deduplicated)
 | # | Severity | Category | File:Line | Title | Batch | Disposition |
 |---|----------|----------|-----------|-------|-------|-------------|
 | 1 | Low | Architecture | `detection_client/src/lib.rs` | `pub mod internal` exposes proto server types to external crates | 18 | Accepted: required for integration test fixture server; practical risk negligible |
 | 2 | Low | Maintainability | `detection_client/src/internal/stats.rs:66` | `note_orphan_response` increments `stream_errors_total` — imprecise bucket | 18 | Accepted: additive counter, low severity; add `orphan_responses_total` in next stats refactor |
 | 3 | Low | Performance | `detection_client/src/internal/runtime.rs:build_request` | Pixel buffer copy per gRPC frame | 18 | Accepted: unavoidable with current prost stack; revisit when `prost bytes` feature is evaluated |
 | 4 | Low | Architecture | `crates/autopilot/src/runtime.rs:84` | Pre-existing dead-code lint on `vlm_provider_name` | 16 | Pre-existing; tracked in `_docs/_process_leftovers/2026-05-20_autopilot_clippy.md` |
 **Critical**: 0 | **High**: 0 | **Medium**: 0 (one Medium from batch 18 was fixed inline)
 ---
 ## Per-Batch Batch Review Cross-Reference
 | Batch | Per-batch verdict | Findings fixed | Open low/med |
 |-------|------------------|----------------|-------------|
 | 16 | PASS_WITH_WARNINGS | — | 1 Low (FFmpeg EAGAIN string match), 1 Low (autopilot dead-code) |
 | 17 | PASS | — | None |
 | 18 | PASS_WITH_WARNINGS | F1 Medium (dead code) fixed inline | 3 Low accepted |
 ---
 ## Open Risks
 1. **`mission_executor` polling race** — `ac1_multirotor_happy_path_reaches_done` (and the earlier `ac3`) intermittently fail under load. Tracked in `_docs/_process_leftovers/2026-05-20_mission_executor_ac3_flake.md`. Not a production defect; fix in the next `mission_executor` batch.
 2. **Composition root wiring gap** — `frame_ingest` publisher and `detection_client` supervisor are not yet wired in `autopilot/src/runtime.rs`. This is expected and intentional; the composition root is wired in a dedicated final-assembly task once all leaf components are done.
 3. **Real `../detections` service not tested** — `detection_client` tests use a fixture in-process gRPC server. End-to-end integration against the real service is scoped to the suite-level e2e harness.
 ---
 ## Quality Gate Status (batches 16-18 combined)
 - `cargo fmt --all`: clean
 - `cargo clippy -p frame_ingest -p detection_client --all-targets -- -D warnings`: clean
 - `cargo test -p frame_ingest -p detection_client`: all passing (17 unit + 3 publisher + 5 rtsp_lifecycle + 10 detection_client unit + 7 detection_client integration)
 - `cargo test --workspace`: one pre-existing flake in `mission_executor` (documented, not blocking)
 **Verdict: PASS_WITH_WARNINGS — no Critical or High findings; proceed to batch 19.**
@@ -0,0 +1,85 @@
 # Code Review Report
 **Batch**: 18 — AZ-659, AZ-660, AZ-661
 **Date**: 2026-05-20
 **Verdict**: PASS_WITH_WARNINGS
 ## Findings
 | # | Severity | Category | File:Line | Title |
 |---|----------|----------|-----------|-------|
 | 1 | Medium | Maintainability | `runtime.rs:392-411` | Dead code: unused `Instant::now()` + no-op `let _ = in_flight` |
 | 2 | Low | Architecture | `lib.rs (detection_client)` | `pub mod internal` exposes generated proto server types to external crates |
 | 3 | Low | Maintainability | `stats.rs:66` | `note_orphan_response` increments `stream_errors_total` — imprecise bucket |
 | 4 | Low | Performance | `runtime.rs:build_request` | `frame.pixels.to_vec()` copies the full pixel buffer for each gRPC encode |
 ### Finding Details
 **F1: Dead code in `handle_response`** (Medium / Maintainability) — **FIXED**
 - Location: `crates/detection_client/src/internal/runtime.rs`
 - Description: `let now = Instant::now()` was captured but never used; `let _ = in_flight` was a no-op for a `Copy` type, suggesting incomplete RTT tracking that was never wired up.
 - Fix applied: removed both dead statements; replaced multi-paragraph placeholder comment with a concise doc note.
 **F2: `pub mod internal` exposes server proto types** (Low / Architecture)
 - Location: `crates/detection_client/src/lib.rs:40`
 - Description: `pub mod internal` is required for integration tests in `tests/stream.rs` that need `detection_service_server` types to spin up the fixture gRPC server. The side-effect is that `detection_client::internal::*` is also visible to external crates, which contradicts module-layout rule #3.
 - Suggestion: gate the re-export behind `#[cfg(any(test, feature = "test-utils"))]` or move fixture server helpers into a private dev-dependency crate when test infra consolidation is next in scope. Not worth fixing now — the practical risk is negligible (no external crate is expected to consume `detection_client::internal`).
 **F3: `note_orphan_response` uses wrong counter** (Low / Maintainability)
 - Location: `crates/detection_client/src/internal/stats.rs:66`
 - Description: An orphan response (response arrived after the in-flight slot was budget-evicted) is a normal consequence of drop-oldest budgeting, not a stream error. Incrementing `stream_errors_total` conflates two distinct observability signals and could mislead operators.
 - Suggestion: Add a dedicated `orphan_responses_total: AtomicU64` field in a future stats refactor. Not blocking — the counter is additive and currently only consumed internally.
 **F4: Pixel buffer copy per gRPC frame** (Low / Performance)
 - Location: `crates/detection_client/src/internal/runtime.rs:build_request`
 - Description: `pixels: frame.pixels.to_vec()` allocates a `Vec<u8>` copy of the full pixel buffer (potentially 3–25 MB at operational resolutions) for each frame before gRPC serialisation. The `Arc<Bytes>` on the frame prevents sharing across the gRPC encode path because prost requires owned `Vec<u8>` for `bytes` fields.
 - Suggestion: Investigate `bytes::Bytes` integration with prost's `bytes` feature flag in a future optimisation pass. Not a regression — the copy existed implicitly before and is unavoidable with the current proto stack version.
 ---
 ## Phase 2: Spec Compliance Summary
 ### AZ-659 — frame_ingest_publisher
 | AC | Status | Test |
 |----|--------|------|
 | AC-1: Three consumers at rate, no drops | PASS | `ac1_three_consumers_at_rate_lose_no_frames` |
 | AC-2: Slow consumer drops, fast unaffected | PASS | `ac2_slow_consumer_drops_while_fast_consumers_unaffected` |
 | AC-3: Fan-out is zero-copy via Arc<Bytes> | PASS | `ac3_fan_out_is_zero_copy_via_arc_bytes` |
 ### AZ-660 — detection_client_grpc_stream
 | AC | Status | Test |
 |----|--------|------|
 | AC-1: 30 fps / 10 s / ≥285 batches / p99 ≤100 ms / drops=0 | PASS | `ac660_1_happy_path_30fps_285_batches` |
 | AC-2: Reconnect within ≤2 s after stream close | PASS | `ac660_2_reconnects_after_stream_close` |
 | AC-3: Budget drops > 0 on 200 ms server | PASS | `ac660_3_budget_drops_on_slow_server` |
 | AC-4: ai_locked frames skipped | PASS | `ac660_4_ai_locked_frames_skipped` |
 ### AZ-661 — detection_client_schema_and_health
 | AC | Status | Test |
 |----|--------|------|
 | AC-1: Schema mismatch → hard error + counter | PASS | `ac661_1_schema_mismatch_hard_error` |
 | AC-2: model_version change → exactly one event | PASS | `ac661_2_model_version_change_emits_event` |
 | AC-3: Tier1Degraded emitted exactly once on latency spike | PASS | `ac661_3_tier1_degraded_emitted_once_on_latency_spike` |
 ---
 ## Phase 7: Architecture Compliance
 | Rule | Check | Result |
 |------|-------|--------|
 | Layer direction | `detection_client` imports only `shared` (Layer 1); no sibling crate imports | PASS |
 | Layer direction | `frame_ingest` imports only `shared` (Layer 1) | PASS |
 | Public API respect | No cross-component imports of internal modules | PASS |
 | No new cyclic deps | Import graph: detection_client → shared, frame_ingest → shared; no cycles | PASS |
 | Module-layout sync | `detection_client` public API section updated to reflect streaming shape | PASS (fixed) |
 | Module-layout sync | `frame_ingest` public API section updated to include publisher methods | PASS (fixed) |
 ---
 **critical_count**: 0
 **high_count**: 0
 **Medium findings auto-fixed inline**: 1 (F1)
 **Verdict**: PASS_WITH_WARNINGS — proceed to commit.
@@ -4,27 +4,28 @@
 flow: greenfield
 step: 7
 name: Implement
-status: between-batches
+status: in_progress
 sub_step:
-  phase: 0
+  phase: 14
-  name: batch-17-select
+  name: batch-20-select
-  detail: ""
+  detail: "batch-19 test gate GREEN (391 passed, 0 in-scope failures on Jetson Docker); ready to pick batch 20"
 retry_count: 0
 cycle: 1
 tracker: jira
 ## Last Completed Batch
-batch: 16
+batch: 19
-commit: 251ebed
+commit: db844db (impl), 202b2cb (archive), pending (test-gate fixes + Jetson Docker infra)
-ticket: AZ-658
+ticket: AZ-662, AZ-669
-jira_status: In Testing (confirmed via read-back)
+jira_status: In Testing (transitioned 2026-05-20 — id 10036)
-pushed_to: origin/dev
+report: _docs/03_implementation/batch_19_cycle1_report.md (PASS_WITH_WARNINGS — see report for F1-F5; test-gate fixes documented in "Test Run — DONE" section)
-report: _docs/03_implementation/batch_16_cycle1_report.md
+test_gate: GREEN — 391 tests passed across 58 binaries on jetson-e2e (Dockerfile.test); 6 compile errors + 1 algorithm bug in db844db were fixed inline (test gate caught them — see report). 2 pre-existing frame_ingest failures recorded as leftovers (h264_cuvid SEGV + publisher timing flake), out of batch 19 scope.
 cumulative_review: _docs/03_implementation/cumulative_review_batches_13-15_cycle1_report.md
 ## Process Leftovers
- `_docs/_process_leftovers/2026-05-20_autopilot_clippy.md` — out-of-scope for batch 16
+- `_docs/_process_leftovers/2026-05-20_autopilot_clippy.md` — still pending; out-of-scope for batch 18
- `_docs/_process_leftovers/2026-05-20_mission_executor_ac3_flake.md` — out-of-scope for batch 16
+- `_docs/_process_leftovers/2026-05-20_mission_executor_ac3_flake.md` — still pending; fix when next mission_executor batch lands
 - `_docs/_process_leftovers/2026-05-20_frame_ingest_cuvid_segv.md` — NEW; HIGH severity production bug exposed by Jetson test gate; fix in next batch touching `frame_ingest`
 - `_docs/_process_leftovers/2026-05-20_frame_ingest_publisher_timing_flake.md` — NEW; LOW severity Jetson-specific timing flake; address alongside cuvid leftover
 ## Cumulative Review Cadence
-Last cumulative: batches 13–15. Next due: end of batch 18.
+Last cumulative: batches 16–18. Next due: end of batch 21 (or sooner if a large-scope batch warrants it).
@@ -0,0 +1,65 @@
 # Leftover — frame_ingest h264_cuvid SIGSEGV
 - **Timestamp**: 2026-05-20T22:10:00+03:00
 - **Source**: Batch-19 Jetson test-gate run (commit pending — closes batch 19)
 - **Severity**: HIGH — real production bug; would crash the decoder process in any deployment where Ubuntu's libavcodec58 was built with cuvid headers but libnvcuvid.so.1 is missing (e.g., a Jetson reflash before the NVIDIA driver is installed, or any non-NVIDIA host with `libavcodec-extra` installed).
 - **Origin component**: `frame_ingest` (AZ-657 / AZ-658, batches 16-18)
 - **NOT in batch 19 scope** — recorded for the next batch that touches `frame_ingest`.
 ## Symptom
 `cargo test -p frame_ingest --lib` and `cargo test -p frame_ingest --test decoder_pipeline` both SIGSEGV during construction of the production decoder:
 ```
 [h264_cuvid @ 0xffff8c000d70] Cannot load libnvcuvid.so.1
 [h264_cuvid @ 0xffff8c000d70] Failed loading nvcuvid.
 error: test failed, to rerun pass `-p frame_ingest --lib`
 Caused by:
  process didn't exit successfully: `.../frame_ingest-...` (signal: 11, SIGSEGV: invalid memory reference)
 ```
 Reproduced in `Dockerfile.test` (ubuntu:22.04 + libopencv-dev + libav*-dev + no NVIDIA driver) — i.e., the canonical "production-like minus NVDEC" environment.
 ## Root cause
 `crates/frame_ingest/src/internal/decoder.rs::open_with_backend`:
 ```rust
 if let Some(nv) = ffmpeg::codec::decoder::find_by_name(codec.nvdec_name()) {
    match try_open(nv) {
        Ok(d) => { return Ok((d, DecoderBackend::Nvdec)); }
        Err(e) => { /* fall through to software */ }
    }
 }
 ```
 and `try_open`:
 ```rust
 fn try_open(codec: ffmpeg::Codec) -> Result<ffmpeg::decoder::Video, DecoderInitError> {
    let ctx = ffmpeg::codec::Context::new();
    let opened = ctx.decoder().open_as(codec).map_err(DecoderInitError::OpenFailed)?;
    opened.video().map_err(DecoderInitError::OpenFailed)
 }
 ```
 Ubuntu's `libavcodec58` package was built against the NVIDIA cuvid headers, so `find_by_name("h264_cuvid")` returns `Some(...)` **even when libnvcuvid.so.1 is absent at runtime**. `open_as(codec)` ALSO returns `Ok` because FFmpeg defers the libnvcuvid `dlopen` until the first `send_packet`. The fallback to software h264 therefore never fires; the first decode SEGVs because `libnvcuvid.so.1` couldn't be opened.
 ## Fix sketch
 In `try_open` (or a new `probe_nvdec` helper), call `send_packet` with a minimal valid NAL unit (or just allocate a CUDA context via `avcodec_send_packet` + `avcodec_receive_frame` round-trip) so the libnvcuvid load is attempted at probe time. If it fails, return `Err(DecoderInitError::OpenFailed(...))` so the existing fallback kicks in.
 Alternative (cheaper) probe: `dlopen("libnvcuvid.so.1")` directly via the `libloading` crate before declaring NVDEC opened. If dlopen fails, immediately fall back to software without ever touching the FFmpeg cuvid path.
 Either approach restores the AZ-658 design intent ("real NVDEC binding when present, real software fallback always") — currently the fallback only fires when the cuvid codec is unregistered, not when it is registered-but-non-functional.
 ## Acceptance for closing this leftover
 - `cargo test -p frame_ingest --lib` passes in `Dockerfile.test` on `jetson-e2e`.
 - `cargo test -p frame_ingest --test decoder_pipeline` passes in the same env.
 - `FfmpegDecoder::new(Codec::H264)` returns `Ok` with `backend() == Software` (not NVDEC) when libnvcuvid.so.1 is missing, regardless of whether `h264_cuvid` is registered.
 - A new test (e.g., `decoder_falls_back_to_software_when_libnvcuvid_missing`) covers the regression and runs in `Dockerfile.test`.
 ## Suggested owner
 Next batch that touches `frame_ingest` (likely a maintenance touch when AZ-678 / AZ-679 / AZ-680 land). Could also be packaged as a standalone Bug ticket in Jira; defer to whoever picks up the next `frame_ingest` work.
@@ -0,0 +1,38 @@
 # Leftover — frame_ingest publisher timing flake on Jetson
 - **Timestamp**: 2026-05-20T22:10:00+03:00
 - **Source**: Batch-19 Jetson test-gate run (commit pending — closes batch 19)
 - **Severity**: LOW — flaky test, not a production bug; passed on the second run.
 - **Origin component**: `frame_ingest` (AZ-657, batch 16)
 - **NOT in batch 19 scope** — recorded for the next batch that touches `frame_ingest`.
 ## Symptom
 `cargo test -p frame_ingest --test publisher::ac1_three_consumers_at_rate_lose_no_frames` failed on the first run inside `Dockerfile.test` on `jetson-e2e`:
 ```
 ---- ac1_three_consumers_at_rate_lose_no_frames stdout ----
 thread 'tokio-rt-worker' (1069) panicked at crates/frame_ingest/tests/publisher.rs:78:31:
 telemetry stalled at 25/30
 ```
 Passed on the second run with no code change. The test produces 30 frames at a fixed rate and expects all three consumers to keep up. The Jetson Orin Nano Super (6-core Cortex-A78AE at ~2 GHz) is significantly slower than the macOS dev box where the test was originally tuned, so the per-frame timing budget (the source of the 25/30 cutoff at line 78) is too tight for this hardware under load (e.g., during a cold `cargo build` of the next test binary).
 ## Fix sketch
 Two options:
 1. **Relax the timing budget** in `crates/frame_ingest/tests/publisher.rs:78` to allow longer per-frame deadlines, OR derive it from a measured baseline so a slow host gets proportionally more time. The test's INTENT — "all three consumers receive all 30 frames" — is preserved; only the synthetic rate is adjusted.
 2. **Mark the test `#[ignore]` on aarch64-linux with a comment pointing here**, then add a slower-rate variant that runs everywhere. This keeps the original test as a "ideal-hardware" check.
 Option 1 is cleaner and matches the existing pattern in the same crate (`ac2_slow_consumer_drops_while_fast_consumers_unaffected` uses a fixed but generous rate).
 ## Acceptance for closing this leftover
 - `cargo test -p frame_ingest --test publisher` passes on the first run in `Dockerfile.test` on `jetson-e2e`, three consecutive times.
 - Test intent (zero-frame-loss across 3 consumers at the configured rate) is preserved.
 ## Suggested owner
 Whichever batch next touches `frame_ingest`. Same batch as `2026-05-20_frame_ingest_cuvid_segv.md` if both can be addressed together.
@@ -1,7 +1,11 @@
-# Leftover: `mission_executor::ac3_bounded_retry_then_success` polling race
+# Leftover: `mission_executor` state-machine polling race
-**Timestamp**: 2026-05-20T08:30:00+02:00
+**Timestamp**: 2026-05-20T17:08:00+03:00 (originally 2026-05-20T08:30:00+02:00)
-**Origin**: Batch 8 (mission_executor state machine). Surfaced in batches 11, 12, 13 as intermittent. Reproduces more reliably on dev box under batch 14 workspace test load (the new tonic stack increases build/runtime pressure).
+**Origin**: Batch 8 (mission_executor state machine). Surfaced in batches 11, 12, 13, 17 as intermittent. Reproduces more reliably on dev box under workspace test load.
 **Affected tests**:
 - `ac3_bounded_retry_then_success` (original)
 - `ac1_multirotor_happy_path_reaches_done` (batch 17 — same `await_state` polling race in the same file)
 **Severity**: Medium (test design, not production code)
 **Not blocking**: pre-existing failure in unrelated area; production `mission_executor` behaviour is correct — the test simply has a polling race.
@@ -6,11 +6,24 @@ rust-version.workspace = true
 license.workspace = true
 publish.workspace = true
 authors.workspace = true
 build = "build.rs"
 [dependencies]
 shared = { workspace = true }
 tokio = { workspace = true }
 tokio-stream = { workspace = true }
 tracing = { workspace = true }
 async-trait = { workspace = true }
 thiserror = { workspace = true }
 bytes = { workspace = true }
 parking_lot = { workspace = true }
 prost = { workspace = true }
 tonic = { workspace = true }
 tonic-prost = { workspace = true }
-# Real gRPC stack lands with AZ-660 (`detection_client_grpc_stream`).
+[build-dependencies]
-# tonic / prost dependencies + build.rs + proto/ wiring will be added there.
+tonic-prost-build = { workspace = true }
 protoc-bin-vendored = { workspace = true }
 [dev-dependencies]
 tokio = { workspace = true, features = ["test-util"] }
@@ -0,0 +1,19 @@
 //! AZ-660 build-time codegen for the `../detections` gRPC contract.
 //!
 //! Mirrors the `telemetry_stream` build script: uses
 //! `protoc-bin-vendored` so the build is self-contained (no system
 //! protoc install required on dev or CI). The PROTOC env var is set
 //! before invoking `tonic-prost-build`.
 fn main() -> Result<(), Box<dyn std::error::Error>> {
    let protoc = protoc_bin_vendored::protoc_bin_path()?;
    std::env::set_var("PROTOC", protoc);
    tonic_prost_build::configure()
        .build_client(true)
        .build_server(true)
        .compile_protos(&["proto/detections.proto"], &["proto"])?;
    println!("cargo:rerun-if-changed=proto/detections.proto");
    Ok(())
 }
@@ -0,0 +1,93 @@
 // AZ-660 / AZ-661 — vendored copy of the `../detections` gRPC contract.
 //
 // The authoritative schema lives in the `../detections` repository
 // (per `_docs/02_document/architecture.md §10`). This vendored copy
 // is kept in lock-step with that schema via the `schema_version`
 // field on `DetectionResponse`: any breaking schema change MUST
 // bump the version, and the client (built against the version pinned
 // in `DetectionClientConfig::expected_schema_version`) MUST emit a
 // hard `schema_mismatch` error if the server reports a different
 // version. The schema version is the explicit handshake that lets
 // the autopilot run alongside an evolving detection service without
 // silently downcasting unknown response shapes.
 //
 // Wire shape (one bi-directional stream per session):
 //   client ─► FrameRequest stream ────► server (../detections)
 //   client ◄── DetectionResponse stream ◄── server
 //
 // `FrameRequest` carries the encoded pixel buffer and the source
 // frame's monotonic timestamp; the response correlates back via
 // `frame_seq`. Frames with `ai_locked = true` upstream are filtered
 // by the client and never sent — the server therefore never sees a
 // FrameRequest for an AI-locked frame.
 syntax = "proto3";
 package azaion.detection.v1;
 service DetectionService {
  // One bi-directional stream per client session. The server may
  // close the stream at any time; the client reconnects with
  // bounded backoff (`DetectionClientConfig::reconnect_*`).
  rpc Stream(stream FrameRequest) returns (stream DetectionResponse);
 }
 // Pixel formats mirrored from `shared::models::frame::PixelFormat`.
 // Encoded as a proto enum so the wire is self-describing.
 enum PixelFormat {
  PIXEL_FORMAT_UNSPECIFIED = 0;
  PIXEL_FORMAT_NV12 = 1;
  PIXEL_FORMAT_YUV420P = 2;
  PIXEL_FORMAT_RGB24 = 3;
 }
 // One inference request per frame. The client tracks `frame_seq`
 // for response correlation (the response carries the same value
 // in `frame_seq`).
 message FrameRequest {
  uint64 frame_seq = 1;
  // Capture timestamp (monotonic, ns) — used by the client to
  // compute per-frame round-trip latency from the response.
  uint64 capture_ts_monotonic_ns = 2;
  uint32 width = 3;
  uint32 height = 4;
  PixelFormat pix_fmt = 5;
  bytes pixels = 6;
 }
 // Bounding box in [0,1] normalized coordinates (mirrors
 // `shared::models::frame::BoundingBox`).
 message BoundingBox {
  float x_min = 1;
  float y_min = 2;
  float x_max = 3;
  float y_max = 4;
 }
 // One detection inside a `DetectionResponse`.
 message Detection {
  uint32 class_id = 1;
  string class_name = 2;
  float confidence = 3;
  BoundingBox bbox_normalized = 4;
  optional bytes mask_or_polyline = 5;
  uint64 source_frame_seq = 6;
 }
 // Server-streamed response. `schema_version` is the handshake the
 // client validates against `expected_schema_version`; any mismatch
 // is a hard `schema_mismatch` error and the response is rejected.
 // `model_version` may change at runtime when the inference model
 // is hot-swapped — the client emits a `ModelVersionChanged` event
 // on the first response with a new version.
 message DetectionResponse {
  uint32 schema_version = 1;
  string model_version = 2;
  uint64 frame_seq = 3;
  // Server-side processing latency for THIS frame, in milliseconds.
  // The client also computes its own round-trip latency from
  // `capture_ts_monotonic_ns` so it can detect transport latency
  // independently of server-internal latency.
  uint32 latency_ms = 4;
  repeated Detection detections = 5;
 }
@@ -0,0 +1,170 @@
 //! AZ-660 — in-flight request budgeting.
 //!
 //! The Tier-1 NFR (`description.md §6` + AC-3) requires the client
 //! to keep latency near the per-frame target by NEVER queueing
 //! frames indefinitely. When `max_concurrent_in_flight` (default 2)
 //! is reached and a new frame arrives, the OLDEST in-flight frame
 //! is dropped (its slot is freed for the new one). The drop is
 //! counted toward `budget_drops_total`; the frame's slot in the
 //! tracker is removed so a late response for the dropped frame can
 //! be ignored without crediting it against the latency histogram.
 //!
 //! The tracker is intentionally simple: a small `VecDeque` of
 //! `(frame_seq, capture_ts_ns)` pairs, capped at
 //! `max_concurrent_in_flight`. Order is FIFO (oldest at the front),
 //! so "drop oldest" is `pop_front`. Removal-on-response walks the
 //! deque from the front because responses arrive in roughly the
 //! same order they were sent; in the worst case (out-of-order
 //! response) we walk the full deque, which is fine at the default
 //! capacity of 2.
 use std::collections::VecDeque;
 /// Snapshot of an in-flight request — what the inbound side needs to
 /// compute round-trip latency once the response arrives.
 #[derive(Debug, Clone, Copy)]
 pub struct InFlight {
    pub frame_seq: u64,
    pub capture_ts_monotonic_ns: u64,
 }
 #[derive(Debug)]
 pub struct BudgetTracker {
    inner: VecDeque<InFlight>,
    capacity: usize,
 }
 impl BudgetTracker {
    pub fn new(capacity: usize) -> Self {
        let cap = capacity.max(1);
        Self {
            inner: VecDeque::with_capacity(cap),
            capacity: cap,
        }
    }
    pub fn capacity(&self) -> usize {
        self.capacity
    }
    pub fn in_flight(&self) -> usize {
        self.inner.len()
    }
    /// Add a new request to the tracker. Returns `Some(InFlight)` for
    /// the evicted oldest request when the tracker was already at
    /// capacity; the caller credits this against `budget_drops_total`.
    pub fn add(&mut self, entry: InFlight) -> Option<InFlight> {
        let evicted = if self.inner.len() >= self.capacity {
            self.inner.pop_front()
        } else {
            None
        };
        self.inner.push_back(entry);
        evicted
    }
    /// Look up an in-flight entry by frame_seq and remove it. Returns
    /// `None` when the response arrives for a frame that was already
    /// budget-dropped — in that case the response is silently
    /// discarded by the caller (it would otherwise corrupt the
    /// latency histogram).
    pub fn remove(&mut self, frame_seq: u64) -> Option<InFlight> {
        let pos = self.inner.iter().position(|e| e.frame_seq == frame_seq)?;
        self.inner.remove(pos)
    }
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    fn entry(seq: u64) -> InFlight {
        InFlight {
            frame_seq: seq,
            capture_ts_monotonic_ns: seq * 1_000_000,
        }
    }
    #[test]
    fn capacity_clamps_to_one() {
        // Arrange
        let b = BudgetTracker::new(0);
        // Assert
        assert_eq!(b.capacity(), 1);
    }
    #[test]
    fn add_under_capacity_does_not_evict() {
        // Arrange
        let mut b = BudgetTracker::new(2);
        // Act
        let e1 = b.add(entry(1));
        let e2 = b.add(entry(2));
        // Assert
        assert!(e1.is_none());
        assert!(e2.is_none());
        assert_eq!(b.in_flight(), 2);
    }
    #[test]
    fn add_at_capacity_evicts_oldest() {
        // Arrange
        let mut b = BudgetTracker::new(2);
        b.add(entry(1));
        b.add(entry(2));
        // Act — third entry forces eviction.
        let evicted = b.add(entry(3));
        // Assert — entry 1 was the oldest, so it gets dropped.
        assert_eq!(evicted.expect("evicted").frame_seq, 1);
        assert_eq!(b.in_flight(), 2);
    }
    #[test]
    fn remove_known_frame_returns_entry() {
        // Arrange
        let mut b = BudgetTracker::new(4);
        b.add(entry(1));
        b.add(entry(2));
        b.add(entry(3));
        // Act
        let removed = b.remove(2);
        // Assert
        assert_eq!(removed.expect("removed").frame_seq, 2);
        assert_eq!(b.in_flight(), 2);
    }
    #[test]
    fn remove_unknown_frame_returns_none() {
        // Arrange
        let mut b = BudgetTracker::new(2);
        b.add(entry(1));
        // Assert
        assert!(b.remove(999).is_none());
    }
    #[test]
    fn evicted_frame_remove_returns_none() {
        // Arrange
        let mut b = BudgetTracker::new(2);
        b.add(entry(1));
        b.add(entry(2));
        let evicted = b.add(entry(3));
        assert_eq!(evicted.expect("evicted").frame_seq, 1);
        // Act
        let removed = b.remove(1);
        // Assert — a late response for the evicted frame finds nothing
        // and the caller drops it.
        assert!(removed.is_none());
    }
 }
@@ -0,0 +1,189 @@
 //! AZ-661 — sliding-window latency tracker.
 //!
 //! Tracks per-response round-trip latency in a fixed-capacity ring
 //! buffer. The client polls `p99()` periodically and emits a
 //! `Tier1Degraded { reason: HighLatency }` event when the percentile
 //! crosses the configured threshold; it emits a `Tier1Recovered`
 //! event when latency falls back below the threshold so the operator
 //! UI can clear the warning.
 //!
 //! The buffer holds raw `u64` ns samples — percentile readout sorts
 //! a snapshot under a `parking_lot::Mutex` (cheap given the bounded
 //! ring size and the fact that p99 is read at a much lower cadence
 //! than samples are pushed).
 use std::time::Duration;
 use parking_lot::Mutex;
 const DEFAULT_CAPACITY: usize = 1024;
 #[derive(Debug)]
 pub struct LatencyWindow {
    inner: Mutex<Ring>,
    threshold_ns: u64,
    degraded: parking_lot::Mutex<bool>,
 }
 impl LatencyWindow {
    pub fn new(threshold: Duration) -> Self {
        Self {
            inner: Mutex::new(Ring::new(DEFAULT_CAPACITY)),
            threshold_ns: threshold.as_nanos() as u64,
            degraded: parking_lot::Mutex::new(false),
        }
    }
    pub fn with_capacity(threshold: Duration, capacity: usize) -> Self {
        Self {
            inner: Mutex::new(Ring::new(capacity.max(1))),
            threshold_ns: threshold.as_nanos() as u64,
            degraded: parking_lot::Mutex::new(false),
        }
    }
    pub fn record(&self, latency: Duration) {
        let ns = latency.as_nanos().min(u128::from(u64::MAX)) as u64;
        self.inner.lock().push(ns);
    }
    pub fn p50(&self) -> Option<Duration> {
        self.percentile_ns(0.50).map(Duration::from_nanos)
    }
    pub fn p99(&self) -> Option<Duration> {
        self.percentile_ns(0.99).map(Duration::from_nanos)
    }
    pub fn threshold(&self) -> Duration {
        Duration::from_nanos(self.threshold_ns)
    }
    /// Re-evaluate the degraded latch and return whether the state
    /// changed. Three outcomes:
    /// - `DegradationTransition::Degraded`: p99 just crossed the
    ///   threshold this call (emit `Tier1Degraded`).
    /// - `DegradationTransition::Recovered`: p99 fell back below the
    ///   threshold this call (emit `Tier1Recovered`).
    /// - `DegradationTransition::NoChange`: the latch's state already
    ///   matched the observed reality; no event needed.
    ///
    /// The first call returns `NoChange` until at least one sample
    /// has been recorded — `p99()` is `None` otherwise.
    pub fn evaluate(&self) -> DegradationTransition {
        let Some(p99) = self.percentile_ns(0.99) else {
            return DegradationTransition::NoChange;
        };
        let now_degraded = p99 > self.threshold_ns;
        let mut latch = self.degraded.lock();
        let prev = *latch;
        *latch = now_degraded;
        match (prev, now_degraded) {
            (false, true) => DegradationTransition::Degraded,
            (true, false) => DegradationTransition::Recovered,
            _ => DegradationTransition::NoChange,
        }
    }
    fn percentile_ns(&self, q: f64) -> Option<u64> {
        let buf = self.inner.lock();
        if buf.len == 0 {
            return None;
        }
        let mut snap: Vec<u64> = buf.iter().collect();
        snap.sort_unstable();
        let idx = ((snap.len() as f64) * q).floor() as usize;
        Some(snap[idx.min(snap.len() - 1)])
    }
 }
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum DegradationTransition {
    Degraded,
    Recovered,
    NoChange,
 }
 #[derive(Debug)]
 struct Ring {
    buf: Vec<u64>,
    head: usize,
    len: usize,
    cap: usize,
 }
 impl Ring {
    fn new(cap: usize) -> Self {
        Self {
            buf: vec![0; cap],
            head: 0,
            len: 0,
            cap,
        }
    }
    fn push(&mut self, v: u64) {
        self.buf[self.head] = v;
        self.head = (self.head + 1) % self.cap;
        if self.len < self.cap {
            self.len += 1;
        }
    }
    fn iter(&self) -> impl Iterator<Item = u64> + '_ {
        self.buf.iter().take(self.len).copied()
    }
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    #[test]
    fn empty_window_returns_no_change() {
        // Arrange
        let w = LatencyWindow::new(Duration::from_millis(100));
        // Assert
        assert_eq!(w.evaluate(), DegradationTransition::NoChange);
        assert!(w.p99().is_none());
    }
    #[test]
    fn degraded_then_recovered_transitions() {
        // Arrange — a tiny window so we can flip state with few samples.
        let w = LatencyWindow::with_capacity(Duration::from_millis(100), 8);
        // Act — push values well above the threshold.
        for _ in 0..8 {
            w.record(Duration::from_millis(150));
        }
        let degraded = w.evaluate();
        // Push values well below the threshold, displacing the
        // earlier samples (ring capacity = 8).
        for _ in 0..8 {
            w.record(Duration::from_millis(10));
        }
        let recovered = w.evaluate();
        let steady = w.evaluate();
        // Assert
        assert_eq!(degraded, DegradationTransition::Degraded);
        assert_eq!(recovered, DegradationTransition::Recovered);
        assert_eq!(steady, DegradationTransition::NoChange);
    }
    #[test]
    fn evaluate_below_threshold_is_no_change_when_already_healthy() {
        // Arrange
        let w = LatencyWindow::with_capacity(Duration::from_millis(100), 4);
        for _ in 0..4 {
            w.record(Duration::from_millis(20));
        }
        // Assert — first evaluate is also a no-change because the
        // latch starts at `false` and stays there.
        assert_eq!(w.evaluate(), DegradationTransition::NoChange);
    }
 }
@@ -0,0 +1,8 @@
 //! Internal modules for `detection_client`. Not part of the public
 //! API (see `crates/detection_client/src/lib.rs`).
 pub mod budget;
 pub mod latency;
 pub mod proto;
 pub mod runtime;
 pub mod stats;
@@ -0,0 +1,10 @@
 //! Generated tonic+prost code for the `../detections` gRPC contract.
 //!
 //! The actual `.rs` file is produced at build time by `build.rs`
 //! (see workspace `tonic-prost-build` / `protoc-bin-vendored` deps)
 //! and dropped into `OUT_DIR`. We pull it in here under a stable
 //! module path so the rest of the crate doesn't reach into `OUT_DIR`.
 #![allow(clippy::derive_partial_eq_without_eq)]
 tonic::include_proto!("azaion.detection.v1");
@@ -0,0 +1,444 @@
 //! AZ-660 + AZ-661 — supervisor task + bi-di stream session.
 //!
 //! The supervisor owns the gRPC channel: it connects, runs ONE
 //! stream session, and on session loss (server-side close, network
 //! drop, transport error) re-connects with exponential backoff
 //! capped at `DetectionClientConfig::reconnect_cap`. The backoff
 //! resets to `reconnect_initial` on every successful reconnect so
 //! a healthy link spends 0 ms in the backoff path.
 //!
 //! Each stream session opens a single bi-directional stream against
 //! `DetectionService::Stream`. Outbound and inbound are driven from
 //! the same `tokio::select!` loop:
 //! - On `Frame` arrival: skip if `ai_locked`, otherwise add to the
 //!   budget tracker (evicting the oldest in-flight slot if full)
 //!   and forward as a `FrameRequest` to the gRPC outbound channel.
 //! - On `DetectionResponse` arrival: validate `schema_version`
 //!   (AZ-661), look up the matching in-flight entry, compute round-
 //!   trip latency, emit a `Batch` event, and update sliding-window
 //!   latency. Track `model_version` and emit `ModelVersionChanged`
 //!   on changes (AZ-661). Re-evaluate the latency window and emit
 //!   `Tier1Degraded` / `Tier1Recovered` on threshold crossings.
 //!
 //! The session ends when:
 //! - `shutdown_rx` flips to `true`,
 //! - the inbound stream returns `None` (server closed cleanly), or
 //! - the inbound stream returns an error.
 //!
 //! `frame_rx.recv` returning `Closed` ends the session AND the
 //! supervisor (no more frames will arrive), but the supervisor
 //! drains any pending responses first.
 use std::sync::Arc;
 use std::time::Duration;
 use parking_lot::Mutex;
 use tokio::sync::{broadcast, mpsc, watch};
 use tokio::task::JoinHandle;
 use tokio_stream::wrappers::ReceiverStream;
 use tonic::transport::{Channel, Endpoint};
 use shared::models::detection::{Detection as SharedDetection, DetectionBatch};
 use shared::models::frame::{BoundingBox, Frame, PixelFormat};
 use crate::internal::budget::{BudgetTracker, InFlight};
 use crate::internal::latency::{DegradationTransition, LatencyWindow};
 use crate::internal::proto::detection_service_client::DetectionServiceClient;
 use crate::internal::proto::{
    BoundingBox as ProtoBoundingBox, Detection as ProtoDetection, DetectionResponse, FrameRequest,
    PixelFormat as ProtoPixelFormat,
 };
 use crate::internal::stats::DetectionStats;
 use crate::{ConnectionState, DetectionClientConfig, DetectionEvent, Tier1DegradationReason};
 #[derive(Debug, thiserror::Error)]
 enum StreamSessionError {
    #[error("opening stream failed: {0}")]
    OpenStream(tonic::Status),
    #[error("inbound stream error: {0}")]
    Inbound(tonic::Status),
    #[error("outbound channel closed by the gRPC client")]
    OutboundClosed,
 }
 pub fn spawn_supervisor(
    config: DetectionClientConfig,
    frame_rx: broadcast::Receiver<Frame>,
    events_tx: broadcast::Sender<DetectionEvent>,
    stats: Arc<DetectionStats>,
    latency: Arc<LatencyWindow>,
    connection_tx: watch::Sender<ConnectionState>,
    shutdown_rx: watch::Receiver<bool>,
 ) -> JoinHandle<()> {
    tokio::spawn(async move {
        supervisor(
            config,
            frame_rx,
            events_tx,
            stats,
            latency,
            connection_tx,
            shutdown_rx,
        )
        .await;
    })
 }
 async fn supervisor(
    config: DetectionClientConfig,
    mut frame_rx: broadcast::Receiver<Frame>,
    events_tx: broadcast::Sender<DetectionEvent>,
    stats: Arc<DetectionStats>,
    latency: Arc<LatencyWindow>,
    connection_tx: watch::Sender<ConnectionState>,
    mut shutdown_rx: watch::Receiver<bool>,
 ) {
    let mut backoff = config.reconnect_initial;
    let last_model_version: Arc<Mutex<Option<String>>> = Arc::new(Mutex::new(None));
    let mut prior_session = false;
    loop {
        if *shutdown_rx.borrow() {
            connection_tx.send_replace(ConnectionState::Disconnected);
            return;
        }
        connection_tx.send_replace(ConnectionState::Connecting);
        let endpoint = match Endpoint::from_shared(config.endpoint.clone()) {
            Ok(e) => e.connect_timeout(config.connect_timeout),
            Err(e) => {
                tracing::error!(
                    error = %e,
                    endpoint = %config.endpoint,
                    "detection_client endpoint is invalid; this is fatal"
                );
                stats.note_connect_error();
                connection_tx.send_replace(ConnectionState::Disconnected);
                return;
            }
        };
        let channel = tokio::select! {
            _ = shutdown_rx.changed() => {
                connection_tx.send_replace(ConnectionState::Disconnected);
                return;
            }
            res = endpoint.connect() => match res {
                Ok(c) => Some(c),
                Err(e) => {
                    stats.note_connect_error();
                    tracing::warn!(
                        error = %e,
                        endpoint = %config.endpoint,
                        backoff_ms = backoff.as_millis() as u64,
                        "detection_client connect failed; will retry after backoff"
                    );
                    None
                }
            }
        };
        if let Some(channel) = channel {
            backoff = config.reconnect_initial;
            connection_tx.send_replace(ConnectionState::Connected);
            if prior_session {
                stats.note_reconnect();
            }
            prior_session = true;
            let session_result = run_stream_session(
                channel,
                &mut frame_rx,
                &events_tx,
                &stats,
                &latency,
                &mut shutdown_rx,
                &config,
                &last_model_version,
            )
            .await;
            connection_tx.send_replace(ConnectionState::Disconnected);
            match session_result {
                Ok(SessionExit::Shutdown) => {
                    return;
                }
                Ok(SessionExit::FrameSourceClosed) => {
                    tracing::info!("detection_client frame source closed; exiting");
                    return;
                }
                Ok(SessionExit::ServerClosed) => {
                    tracing::info!("detection_client server closed stream; will reconnect");
                }
                Err(e) => {
                    stats.note_stream_error();
                    tracing::warn!(error = %e, "detection_client stream session ended with error");
                }
            }
        }
        // Wait for backoff before the next attempt unless shutdown
        // fires first. `frame_rx` is intentionally NOT polled here:
        // any frames arriving during disconnect simply lag, and the
        // broadcast channel folds them into a single
        // `RecvError::Lagged(n)` on the next session — counted via
        // `note_frame_lag`.
        tokio::select! {
            _ = tokio::time::sleep(backoff) => {}
            _ = shutdown_rx.changed() => {
                connection_tx.send_replace(ConnectionState::Disconnected);
                return;
            }
        }
        backoff = backoff.saturating_mul(2).min(config.reconnect_cap);
    }
 }
 #[derive(Debug, Clone, Copy)]
 enum SessionExit {
    Shutdown,
    FrameSourceClosed,
    ServerClosed,
 }
 #[allow(clippy::too_many_arguments)]
 async fn run_stream_session(
    channel: Channel,
    frame_rx: &mut broadcast::Receiver<Frame>,
    events_tx: &broadcast::Sender<DetectionEvent>,
    stats: &Arc<DetectionStats>,
    latency: &Arc<LatencyWindow>,
    shutdown_rx: &mut watch::Receiver<bool>,
    config: &DetectionClientConfig,
    last_model_version: &Arc<Mutex<Option<String>>>,
 ) -> Result<SessionExit, StreamSessionError> {
    let mut client = DetectionServiceClient::new(channel);
    let (req_tx, req_rx) = mpsc::channel::<FrameRequest>(config.outbound_buffer.max(1));
    let req_stream = ReceiverStream::new(req_rx);
    let response = client
        .stream(req_stream)
        .await
        .map_err(StreamSessionError::OpenStream)?;
    let mut inbound = response.into_inner();
    let mut budget = BudgetTracker::new(config.max_concurrent_in_flight);
    loop {
        tokio::select! {
            _ = shutdown_rx.changed() => return Ok(SessionExit::Shutdown),
            frame_res = frame_rx.recv() => {
                match frame_res {
                    Ok(frame) => {
                        if frame.ai_locked {
                            stats.note_ai_locked_skipped();
                            continue;
                        }
                        let entry = InFlight {
                            frame_seq: frame.seq,
                            capture_ts_monotonic_ns: frame.capture_ts_monotonic_ns,
                        };
                        if let Some(evicted) = budget.add(entry) {
                            stats.note_in_flight_dropped();
                            tracing::debug!(
                                evicted_seq = evicted.frame_seq,
                                "detection_client dropped oldest in-flight frame (budget)"
                            );
                        }
                        let req = build_request(&frame);
                        if req_tx.send(req).await.is_err() {
                            return Err(StreamSessionError::OutboundClosed);
                        }
                        stats.note_sent();
                    }
                    Err(broadcast::error::RecvError::Lagged(n)) => {
                        stats.note_frame_lag(n);
                        tracing::warn!(
                            dropped = n,
                            "detection_client frame_rx lagged; counted as frame_lag_total"
                        );
                    }
                    Err(broadcast::error::RecvError::Closed) => {
                        return Ok(SessionExit::FrameSourceClosed);
                    }
                }
            }
            inbound_res = inbound.message() => {
                match inbound_res {
                    Ok(Some(resp)) => {
                        handle_response(
                            resp,
                            &mut budget,
                            events_tx,
                            stats,
                            latency,
                            last_model_version,
                            config,
                        );
                        // Re-evaluate latency window after every
                        // response so degraded/recovered transitions
                        // surface at most one event per change.
                        match latency.evaluate() {
                            DegradationTransition::Degraded => {
                                let _ = events_tx.send(DetectionEvent::Tier1Degraded {
                                    reason: Tier1DegradationReason::HighLatency,
                                });
                            }
                            DegradationTransition::Recovered => {
                                let _ = events_tx.send(DetectionEvent::Tier1Recovered);
                            }
                            DegradationTransition::NoChange => {}
                        }
                    }
                    Ok(None) => return Ok(SessionExit::ServerClosed),
                    Err(status) => return Err(StreamSessionError::Inbound(status)),
                }
            }
        }
    }
 }
 fn build_request(frame: &Frame) -> FrameRequest {
    FrameRequest {
        frame_seq: frame.seq,
        capture_ts_monotonic_ns: frame.capture_ts_monotonic_ns,
        width: frame.width,
        height: frame.height,
        pix_fmt: pix_fmt_to_proto(frame.pix_fmt) as i32,
        pixels: frame.pixels.to_vec(),
    }
 }
 fn pix_fmt_to_proto(p: PixelFormat) -> ProtoPixelFormat {
    match p {
        PixelFormat::Nv12 => ProtoPixelFormat::Nv12,
        PixelFormat::Yuv420p => ProtoPixelFormat::Yuv420p,
        PixelFormat::Rgb24 => ProtoPixelFormat::Rgb24,
    }
 }
 fn handle_response(
    resp: DetectionResponse,
    budget: &mut BudgetTracker,
    events_tx: &broadcast::Sender<DetectionEvent>,
    stats: &Arc<DetectionStats>,
    latency: &Arc<LatencyWindow>,
    last_model_version: &Arc<Mutex<Option<String>>>,
    config: &DetectionClientConfig,
 ) {
    // AZ-661 — schema handshake first. A mismatch is a hard error;
    // do NOT decode the rest of the response, do NOT credit it
    // against latency, and clear the in-flight slot so the budget
    // tracker stays accurate.
    if resp.schema_version != config.expected_schema_version {
        stats.note_schema_mismatch();
        // Free the in-flight slot if we can match it.
        let _ = budget.remove(resp.frame_seq);
        let detail = format!(
            "expected schema_version {} got {}",
            config.expected_schema_version, resp.schema_version
        );
        tracing::error!(
            expected = config.expected_schema_version,
            actual = resp.schema_version,
            frame_seq = resp.frame_seq,
            "detection_client schema mismatch"
        );
        let _ = events_tx.send(DetectionEvent::SchemaMismatch {
            detail,
            frame_seq: resp.frame_seq,
        });
        return;
    }
    // Look up the in-flight request. A `None` here means the budget
    // tracker already evicted this frame; the response is orphaned
    // and dropped silently (do not credit latency or events).
    let Some(in_flight) = budget.remove(resp.frame_seq) else {
        stats.note_orphan_response();
        tracing::debug!(
            frame_seq = resp.frame_seq,
            "detection_client orphan response (budget already evicted)"
        );
        return;
    };
    // AZ-661 — model_version handshake. First response on a session
    // is NOT a change if the latch is empty AND the version equals
    // the last observed version across sessions. We only emit when
    // the version changes from a previously-seen non-None value, OR
    // when a session emits its first version (transitioning from
    // None to Some) — the operator UI shows "model swapped" the
    // first time per process lifetime, then again on every change.
    {
        let mut latch = last_model_version.lock();
        let changed = match latch.as_ref() {
            None => true, // first observation in this process
            Some(prev) => prev != &resp.model_version,
        };
        if changed {
            let previous = latch.clone();
            *latch = Some(resp.model_version.clone());
            stats.note_model_version_change();
            let _ = events_tx.send(DetectionEvent::ModelVersionChanged {
                previous,
                current: resp.model_version.clone(),
            });
        }
    }
    // Use the server-reported processing time as the RTT proxy.
    // The Tier-1 NFR measures processing latency at the detections
    // service (`description.md §8`), not round-trip transport time.
    // If wall-clock RTT tracking is added later, store
    // `Instant::now()` in the budget entry at send time.
    let server_side = Duration::from_millis(u64::from(resp.latency_ms));
    latency.record(server_side);
    stats.note_received();
    let batch = response_to_batch(resp);
    let _ = events_tx.send(DetectionEvent::Batch {
        batch,
        capture_ts_monotonic_ns: in_flight.capture_ts_monotonic_ns,
        server_latency: server_side,
    });
 }
 fn response_to_batch(resp: DetectionResponse) -> DetectionBatch {
    let model_version = resp.model_version.clone();
    let frame_seq = resp.frame_seq;
    let latency_ms = resp.latency_ms;
    let detections = resp
        .detections
        .into_iter()
        .map(proto_detection_to_shared)
        .collect();
    DetectionBatch {
        frame_seq,
        detections,
        latency_ms,
        model_version,
    }
 }
 fn proto_detection_to_shared(d: ProtoDetection) -> SharedDetection {
    SharedDetection {
        class_id: d.class_id,
        class_name: d.class_name,
        confidence: d.confidence,
        bbox_normalized: bbox_to_shared(d.bbox_normalized.unwrap_or_default()),
        mask_or_polyline: d.mask_or_polyline,
        source_frame_seq: d.source_frame_seq,
    }
 }
 fn bbox_to_shared(b: ProtoBoundingBox) -> BoundingBox {
    BoundingBox {
        x_min: b.x_min,
        y_min: b.y_min,
        x_max: b.x_max,
        y_max: b.y_max,
    }
 }
@@ -0,0 +1,129 @@
 //! AZ-660 + AZ-661 — atomic counter surface for `DetectionClient`.
 //!
 //! `description.md §3` requires:
 //! - `gRPC_connection_state` (watch, not in this struct — see
 //!   `runtime.rs`)
 //! - `requests_in_flight` (atomic gauge maintained by the supervisor)
 //! - `latency_p50`, `latency_p99` (live in [`crate::internal::latency`])
 //! - `errors_by_kind` (counters per kind, this struct)
 //! - `budget_drops_total` (this struct)
 //!
 //! AZ-661 adds:
 //! - `schema_mismatch_total` (one of the `errors_by_kind` buckets,
 //!   surfaced explicitly because it is the loudest failure mode)
 //! - `model_version_changes_total` (visibility for the operator UI)
 use std::sync::atomic::{AtomicU64, Ordering};
 use std::sync::Arc;
 /// Lock-free counters shared between the supervisor task and the
 /// `DetectionClientHandle`. Every field is `AtomicU64`; readers
 /// snapshot independently with `Ordering::Relaxed`.
 #[derive(Debug, Default)]
 pub struct DetectionStats {
    pub requests_sent_total: AtomicU64,
    pub responses_received_total: AtomicU64,
    pub budget_drops_total: AtomicU64,
    pub frame_lag_total: AtomicU64,
    pub schema_mismatch_total: AtomicU64,
    pub model_version_changes_total: AtomicU64,
    pub reconnects_total: AtomicU64,
    pub connect_errors_total: AtomicU64,
    pub stream_errors_total: AtomicU64,
    pub requests_in_flight: AtomicU64,
    pub ai_locked_skipped_total: AtomicU64,
 }
 impl DetectionStats {
    pub fn shared() -> Arc<Self> {
        Arc::new(Self::default())
    }
    pub fn note_sent(&self) {
        self.requests_sent_total.fetch_add(1, Ordering::Relaxed);
        self.requests_in_flight.fetch_add(1, Ordering::Relaxed);
    }
    pub fn note_received(&self) {
        self.responses_received_total
            .fetch_add(1, Ordering::Relaxed);
        // `requests_in_flight` decrements via `note_in_flight_dropped`
        // on budget eviction and via this fn on a normal response.
        self.requests_in_flight.fetch_sub(1, Ordering::Relaxed);
    }
    pub fn note_in_flight_dropped(&self) {
        self.budget_drops_total.fetch_add(1, Ordering::Relaxed);
        self.requests_in_flight.fetch_sub(1, Ordering::Relaxed);
    }
    pub fn note_orphan_response(&self) {
        // Response arrived for a frame the budget already evicted.
        // We do NOT decrement `requests_in_flight` here (the budget
        // eviction already did) and we do NOT credit it against
        // `responses_received_total` (it does not correspond to a
        // currently-tracked in-flight request).
        self.stream_errors_total.fetch_add(1, Ordering::Relaxed);
    }
    pub fn note_frame_lag(&self, n: u64) {
        self.frame_lag_total.fetch_add(n, Ordering::Relaxed);
    }
    pub fn note_ai_locked_skipped(&self) {
        self.ai_locked_skipped_total.fetch_add(1, Ordering::Relaxed);
    }
    pub fn note_schema_mismatch(&self) {
        self.schema_mismatch_total.fetch_add(1, Ordering::Relaxed);
    }
    pub fn note_model_version_change(&self) {
        self.model_version_changes_total
            .fetch_add(1, Ordering::Relaxed);
    }
    pub fn note_reconnect(&self) {
        self.reconnects_total.fetch_add(1, Ordering::Relaxed);
    }
    pub fn note_connect_error(&self) {
        self.connect_errors_total.fetch_add(1, Ordering::Relaxed);
    }
    pub fn note_stream_error(&self) {
        self.stream_errors_total.fetch_add(1, Ordering::Relaxed);
    }
    pub fn requests_in_flight(&self) -> u64 {
        self.requests_in_flight.load(Ordering::Relaxed)
    }
    pub fn budget_drops_total(&self) -> u64 {
        self.budget_drops_total.load(Ordering::Relaxed)
    }
    pub fn requests_sent_total(&self) -> u64 {
        self.requests_sent_total.load(Ordering::Relaxed)
    }
    pub fn responses_received_total(&self) -> u64 {
        self.responses_received_total.load(Ordering::Relaxed)
    }
    pub fn schema_mismatch_total(&self) -> u64 {
        self.schema_mismatch_total.load(Ordering::Relaxed)
    }
    pub fn model_version_changes_total(&self) -> u64 {
        self.model_version_changes_total.load(Ordering::Relaxed)
    }
    pub fn reconnects_total(&self) -> u64 {
        self.reconnects_total.load(Ordering::Relaxed)
    }
    pub fn ai_locked_skipped_total(&self) -> u64 {
        self.ai_locked_skipped_total.load(Ordering::Relaxed)
    }
 }
@@ -1,48 +1,274 @@
-//! `detection_client` — bi-directional gRPC to `../detections`.
+//! `detection_client` — bi-directional gRPC client to `../detections`.
 //!
-//! Real implementation lands in:
+//! AZ-660 wires the real `tonic` bi-directional stream + reconnect
-//! - AZ-660 `detection_client_grpc_stream`
+//! state machine + drop-oldest frame budgeting. AZ-661 layers schema
-//! - AZ-661 `detection_client_schema_and_health`
+//! validation, `model_version` tracking, and a sliding-window
 //! latency degradation signal on top.
 //!
 //! ## Public surface
 //!
 //! - [`DetectionClient`] / [`DetectionClientConfig`] — configuration
 //!   and entry-point. Build a config, hand it to
 //!   [`DetectionClient::new`], then start the supervisor with
 //!   [`DetectionClient::run`].
 //! - [`DetectionClientHandle`] — the cheap-clone handle returned
 //!   alongside the supervisor `JoinHandle`. Exposes the event stream,
 //!   health surface, connection state, and shutdown.
 //! - [`DetectionEvent`] — the union type emitted on the event stream
 //!   (a `tokio::sync::broadcast` channel so multiple consumers may
 //!   observe). Covers normal detection batches plus AZ-661 schema
 //!   mismatches, model-version changes, and Tier-1 latency
 //!   degradation transitions.
 //!
 //! The supervisor task lives in [`internal::runtime`]. It is the
 //! only owner of the gRPC channel; reconnects are bounded and the
 //! frame-source side never blocks on a slow gRPC server (drop-oldest
 //! budgeting per AC-3 of AZ-660).
-use shared::error::{AutopilotError, Result};
+use std::sync::Arc;
-use shared::health::ComponentHealth;
+use std::time::Duration;
 use tokio::sync::{broadcast, watch};
 use tokio::task::JoinHandle;
 use shared::health::{ComponentHealth, HealthLevel};
 use shared::models::detection::DetectionBatch;
 use shared::models::frame::Frame;
 pub mod internal;
 pub use internal::latency::DegradationTransition;
 pub use internal::stats::DetectionStats;
 const NAME: &str = "detection_client";
 /// Configuration for [`DetectionClient`]. Defaults match the
 /// `description.md §3` baseline (`max_concurrent_in_flight = 2`,
 /// 100 ms p99 Tier-1 threshold, 1 s → 30 s reconnect backoff,
 /// `expected_schema_version = 1`).
 #[derive(Debug, Clone)]
-pub struct DetectionClient {
+pub struct DetectionClientConfig {
    pub endpoint: String,
    /// In-flight gRPC request budget. New frames evict the oldest
    /// in-flight slot when this is reached (AC-3 of AZ-660).
    pub max_concurrent_in_flight: usize,
    pub connect_timeout: Duration,
    pub reconnect_initial: Duration,
    pub reconnect_cap: Duration,
    /// Schema version the client was built against. Any response
    /// with a different `schema_version` is a hard `SchemaMismatch`
    /// (AC-1 of AZ-661).
    pub expected_schema_version: u32,
    /// Capacity of the outbound mpsc channel that feeds the gRPC
    /// stream. Kept small so frames can't queue indefinitely on the
    /// client side.
    pub outbound_buffer: usize,
    /// Capacity of the `events_tx` broadcast channel.
    pub event_channel_capacity: usize,
    /// Capacity of the sliding-window latency ring buffer (AZ-661).
    pub latency_window_capacity: usize,
    /// Tier-1 latency threshold (AC-3 of AZ-661). A `Tier1Degraded`
    /// event is emitted when the sliding-window p99 crosses this
    /// value; a `Tier1Recovered` event is emitted on the reverse
    /// crossing.
    pub latency_p99_threshold: Duration,
 }
-impl DetectionClient {
+impl DetectionClientConfig {
-    pub fn new(endpoint: String) -> Self {
+    pub fn new(endpoint: impl Into<String>) -> Self {
-        Self { endpoint }
+        Self {
-    }
+            endpoint: endpoint.into(),
-
+            max_concurrent_in_flight: 2,
-    pub fn handle(&self) -> DetectionClientHandle {
+            connect_timeout: Duration::from_secs(5),
-        DetectionClientHandle {
+            reconnect_initial: Duration::from_secs(1),
-            endpoint: self.endpoint.clone(),
+            reconnect_cap: Duration::from_secs(30),
            expected_schema_version: 1,
            outbound_buffer: 8,
            event_channel_capacity: 64,
            latency_window_capacity: 1024,
            latency_p99_threshold: Duration::from_millis(100),
        }
    }
 }
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum ConnectionState {
    Disconnected,
    Connecting,
    Connected,
 }
 #[derive(Debug, Clone)]
 pub enum DetectionEvent {
    /// Normal happy-path output. `capture_ts_monotonic_ns` is the
    /// frame's monotonic timestamp at the moment `frame_ingest`
    /// captured it (forwarded so downstream consumers can correlate
    /// detections back to the original frame without re-querying
    /// `frame_ingest`). `server_latency` is the server-reported
    /// per-frame processing time.
    Batch {
        batch: DetectionBatch,
        capture_ts_monotonic_ns: u64,
        server_latency: Duration,
    },
    /// AZ-661 AC-1 — `schema_version` on a response did not match
    /// `DetectionClientConfig::expected_schema_version`. The
    /// response is REJECTED — no detections are forwarded for that
    /// frame.
    SchemaMismatch {
        detail: String,
        frame_seq: u64,
    },
    /// AZ-661 AC-2 — server reported a `model_version` different
    /// from the last observed one. `previous` is `None` only on the
    /// very first response in the process lifetime.
    ModelVersionChanged {
        previous: Option<String>,
        current: String,
    },
    /// AZ-661 AC-3 — sliding-window p99 latency crossed the
    /// configured threshold UPWARDS. The next degraded → healthy
    /// crossing emits a paired [`DetectionEvent::Tier1Recovered`].
    Tier1Degraded {
        reason: Tier1DegradationReason,
    },
    Tier1Recovered,
 }
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum Tier1DegradationReason {
    HighLatency,
 }
 /// Entry-point for the gRPC client. `new` is a builder; `run`
 /// consumes the client and spawns the supervisor task that owns the
 /// gRPC channel for the lifetime of the autopilot process.
 #[derive(Debug)]
 pub struct DetectionClient {
    config: DetectionClientConfig,
 }
 impl DetectionClient {
    pub fn new(config: DetectionClientConfig) -> Self {
        Self { config }
    }
    /// Spawn the supervisor task. Returns the supervisor's
    /// `JoinHandle<()>` and a cheap-clone [`DetectionClientHandle`]
    /// that exposes the event stream, health surface, and
    /// shutdown.
    ///
    /// The supervisor owns `frame_rx` for its full lifetime.
    /// `frame_rx` is a `tokio::sync::broadcast::Receiver<Frame>` —
    /// the composition root is responsible for wiring it to
    /// `frame_ingest::FrameIngestHandle::subscribe()` (raw) or to
    /// a `FrameReceiver` forwarder if it wants per-consumer drop
    /// attribution on the publisher side.
    pub fn run(
        self,
        frame_rx: broadcast::Receiver<Frame>,
    ) -> (JoinHandle<()>, DetectionClientHandle) {
        let (events_tx, _) = broadcast::channel(self.config.event_channel_capacity.max(1));
        let (connection_tx, connection_rx) = watch::channel(ConnectionState::Disconnected);
        let (shutdown_tx, shutdown_rx) = watch::channel(false);
        let stats = DetectionStats::shared();
        let latency = Arc::new(internal::latency::LatencyWindow::with_capacity(
            self.config.latency_p99_threshold,
            self.config.latency_window_capacity,
        ));
        let join = internal::runtime::spawn_supervisor(
            self.config.clone(),
            frame_rx,
            events_tx.clone(),
            Arc::clone(&stats),
            Arc::clone(&latency),
            connection_tx,
            shutdown_rx,
        );
        let handle = DetectionClientHandle {
            stats,
            latency,
            connection_state_rx: connection_rx,
            events_tx,
            shutdown_tx,
        };
        (join, handle)
    }
 }
 /// Cheap-clone handle for the `DetectionClient` supervisor. Exposes:
 /// - Event subscription via [`Self::subscribe_events`].
 /// - Connection-state watch via [`Self::connection_state`] /
 ///   [`Self::connection_state_stream`].
 /// - Health surface (`description.md §3`) via [`Self::health`].
 /// - Shutdown via [`Self::shutdown`] (idempotent).
 #[derive(Debug, Clone)]
 pub struct DetectionClientHandle {
-    #[allow(dead_code)]
+    stats: Arc<DetectionStats>,
-    endpoint: String,
+    latency: Arc<internal::latency::LatencyWindow>,
    connection_state_rx: watch::Receiver<ConnectionState>,
    events_tx: broadcast::Sender<DetectionEvent>,
    shutdown_tx: watch::Sender<bool>,
 }
 impl DetectionClientHandle {
-    pub async fn request(&self, _frame: Frame) -> Result<DetectionBatch> {
+    /// Subscribe to the [`DetectionEvent`] stream. The broadcast
-        Err(AutopilotError::NotImplemented(
+    /// channel applies its own drop-oldest back-pressure to slow
-            "detection_client::request (AZ-660)",
+    /// consumers; new subscribers see events emitted after they
-        ))
+    /// subscribed.
    pub fn subscribe_events(&self) -> broadcast::Receiver<DetectionEvent> {
        self.events_tx.subscribe()
    }
    pub fn connection_state(&self) -> ConnectionState {
        *self.connection_state_rx.borrow()
    }
    pub fn connection_state_stream(&self) -> watch::Receiver<ConnectionState> {
        self.connection_state_rx.clone()
    }
    pub fn stats(&self) -> Arc<DetectionStats> {
        Arc::clone(&self.stats)
    }
    pub fn latency_p50(&self) -> Option<Duration> {
        self.latency.p50()
    }
    pub fn latency_p99(&self) -> Option<Duration> {
        self.latency.p99()
    }
    pub fn shutdown(&self) {
        self.shutdown_tx.send_replace(true);
    }
    pub fn health(&self) -> ComponentHealth {
-        ComponentHealth::disabled(NAME)
+        let state = self.connection_state();
        match state {
            ConnectionState::Disconnected => ComponentHealth::red(NAME, "disconnected"),
            ConnectionState::Connecting => ComponentHealth::yellow(NAME, "connecting"),
            ConnectionState::Connected => {
                // `description.md §3` — p99 above threshold is the
                // operative health signal once we're connected.
                let mut h = ComponentHealth::green(NAME);
                if let Some(p99) = self.latency.p99() {
                    if p99 > self.latency.threshold() {
                        h.level = HealthLevel::Yellow;
                        h.detail = Some(format!(
                            "p99 {} ms > threshold {} ms",
                            p99.as_millis(),
                            self.latency.threshold().as_millis()
                        ));
                    }
                }
                h
            }
        }
    }
 }
@@ -51,8 +277,14 @@ mod tests {
    use super::*;
    #[test]
-    fn it_compiles() {
+    fn config_defaults_match_description() {
-        let h = DetectionClient::new("http://127.0.0.1:50051".into()).handle();
+        // Arrange
-        assert_eq!(h.health().level, shared::health::HealthLevel::Disabled);
+        let c = DetectionClientConfig::new("http://127.0.0.1:50051");
        // Assert — the §3 baseline numbers.
        assert_eq!(c.max_concurrent_in_flight, 2);
        assert_eq!(c.reconnect_cap, Duration::from_secs(30));
        assert_eq!(c.expected_schema_version, 1);
        assert_eq!(c.latency_p99_threshold, Duration::from_millis(100));
    }
 }
@@ -0,0 +1,551 @@
 //! AZ-660 + AZ-661 integration tests — fixture in-process gRPC server.
 //!
 //! AC-660-1 takes ~10 s; all others complete in ≤5 s.
 use std::sync::Arc;
 use std::time::Duration;
 use async_trait::async_trait;
 use bytes::Bytes;
 use tokio::sync::{broadcast, mpsc, oneshot};
 use tokio_stream::wrappers::{ReceiverStream, TcpListenerStream};
 use tonic::transport::Server;
 use tonic::{Request, Response, Status};
 use detection_client::internal::proto::{
    detection_service_server::{DetectionService, DetectionServiceServer},
    DetectionResponse, FrameRequest,
 };
 use detection_client::{ConnectionState, DetectionClient, DetectionClientConfig, DetectionEvent};
 use shared::models::frame::{Frame, PixelFormat};
 // ---------------------------------------------------------------------------
 // Frame factory
 // ---------------------------------------------------------------------------
 fn make_frame(seq: u64, ai_locked: bool) -> Frame {
    Frame {
        seq,
        capture_ts_monotonic_ns: seq * 33_333_333,
        decode_ts_monotonic_ns: seq * 33_333_333 + 1_000_000,
        pixels: Arc::new(Bytes::from_static(b"\x80")),
        width: 1,
        height: 1,
        pix_fmt: PixelFormat::Nv12,
        ai_locked,
    }
 }
 // ---------------------------------------------------------------------------
 // Fixture: configurable echo server
 //
 // `close_after` is per-stream-session (reset on each `stream()` call) so the
 // server can be re-used across reconnects without freezing on the second
 // session.
 // ---------------------------------------------------------------------------
 #[derive(Clone)]
 struct FixtureServer {
    latency_ms: u64,
    schema_version: u32,
    model_version: String,
    close_after: Option<u32>,
 }
 impl FixtureServer {
    fn fast() -> Self {
        Self {
            latency_ms: 10,
            schema_version: 1,
            model_version: "v1.0".to_string(),
            close_after: None,
        }
    }
    fn slow(latency_ms: u64) -> Self {
        Self {
            latency_ms,
            ..Self::fast()
        }
    }
    fn with_schema_version(mut self, v: u32) -> Self {
        self.schema_version = v;
        self
    }
    fn with_close_after(mut self, n: u32) -> Self {
        self.close_after = Some(n);
        self
    }
 }
 #[async_trait]
 impl DetectionService for FixtureServer {
    type StreamStream = ReceiverStream<Result<DetectionResponse, Status>>;
    async fn stream(
        &self,
        request: Request<tonic::Streaming<FrameRequest>>,
    ) -> Result<Response<Self::StreamStream>, Status> {
        let latency = Duration::from_millis(self.latency_ms);
        let schema_version = self.schema_version;
        let model_version = self.model_version.clone();
        let close_after = self.close_after;
        let mut inbound = request.into_inner();
        let (tx, rx) = mpsc::channel::<Result<DetectionResponse, Status>>(32);
        tokio::spawn(async move {
            let mut session_count = 0u32;
            while let Ok(Some(req)) = inbound.message().await {
                tokio::time::sleep(latency).await;
                session_count += 1;
                let resp = DetectionResponse {
                    schema_version,
                    model_version: model_version.clone(),
                    frame_seq: req.frame_seq,
                    latency_ms: latency.as_millis() as u32,
                    detections: vec![],
                };
                if tx.send(Ok(resp)).await.is_err() {
                    break;
                }
                if close_after.map(|n| session_count >= n).unwrap_or(false) {
                    break;
                }
            }
        });
        Ok(Response::new(ReceiverStream::new(rx)))
    }
 }
 // ---------------------------------------------------------------------------
 // Fixture: server that switches model_version mid-stream
 // ---------------------------------------------------------------------------
 #[derive(Clone)]
 struct VersionSwitchServer {
    first_model: String,
    second_model: String,
    /// Return `first_model` for the first `switch_after` responses, then
    /// `second_model` for all subsequent ones within the SAME session.
    switch_after: u32,
 }
 #[async_trait]
 impl DetectionService for VersionSwitchServer {
    type StreamStream = ReceiverStream<Result<DetectionResponse, Status>>;
    async fn stream(
        &self,
        request: Request<tonic::Streaming<FrameRequest>>,
    ) -> Result<Response<Self::StreamStream>, Status> {
        let first = self.first_model.clone();
        let second = self.second_model.clone();
        let switch_after = self.switch_after;
        let mut inbound = request.into_inner();
        let (tx, rx) = mpsc::channel::<Result<DetectionResponse, Status>>(32);
        tokio::spawn(async move {
            let mut count = 0u32;
            while let Ok(Some(req)) = inbound.message().await {
                tokio::time::sleep(Duration::from_millis(10)).await;
                let model = if count < switch_after {
                    first.clone()
                } else {
                    second.clone()
                };
                count += 1;
                let resp = DetectionResponse {
                    schema_version: 1,
                    model_version: model,
                    frame_seq: req.frame_seq,
                    latency_ms: 10,
                    detections: vec![],
                };
                if tx.send(Ok(resp)).await.is_err() {
                    break;
                }
            }
        });
        Ok(Response::new(ReceiverStream::new(rx)))
    }
 }
 // ---------------------------------------------------------------------------
 // Server harness
 // ---------------------------------------------------------------------------
 async fn start_server_with<S>(svc: S) -> (String, oneshot::Sender<()>)
 where
    S: DetectionService + Clone + Send + Sync + 'static,
 {
    let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
    let addr = listener.local_addr().unwrap();
    let stream = TcpListenerStream::new(listener);
    let (shutdown_tx, shutdown_rx) = oneshot::channel::<()>();
    tokio::spawn(async move {
        Server::builder()
            .add_service(DetectionServiceServer::new(svc))
            .serve_with_incoming_shutdown(stream, async {
                let _ = shutdown_rx.await;
            })
            .await
            .unwrap();
    });
    (format!("http://{addr}"), shutdown_tx)
 }
 async fn wait_connected(handle: &detection_client::DetectionClientHandle) {
    let mut conn = handle.connection_state_stream();
    tokio::time::timeout(Duration::from_secs(5), async {
        loop {
            if *conn.borrow() == ConnectionState::Connected {
                break;
            }
            let _ = conn.changed().await;
        }
    })
    .await
    .expect("client connected within 5 s");
 }
 // ---------------------------------------------------------------------------
 // AZ-660 AC-1 — happy path, 30 fps for 10 s, ≥285 batches, p99 ≤100 ms
 // ---------------------------------------------------------------------------
 #[tokio::test(flavor = "multi_thread")]
 async fn ac660_1_happy_path_30fps_285_batches() {
    // Arrange
    let (endpoint, _shutdown) = start_server_with(FixtureServer::fast()).await;
    let (frame_tx, frame_rx) = broadcast::channel::<Frame>(512);
    let config = DetectionClientConfig::new(endpoint);
    let (_join, handle) = DetectionClient::new(config).run(frame_rx);
    wait_connected(&handle).await;
    let mut events = handle.subscribe_events();
    let collector = tokio::spawn(async move {
        let mut count = 0u64;
        loop {
            match tokio::time::timeout(Duration::from_secs(2), events.recv()).await {
                Ok(Ok(DetectionEvent::Batch { .. })) => count += 1,
                Ok(Ok(_)) => {}
                _ => break,
            }
        }
        count
    });
    // Act — 30 fps for 10 s
    let mut ticker = tokio::time::interval(Duration::from_nanos(33_333_333));
    ticker.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
    let deadline = tokio::time::Instant::now() + Duration::from_secs(10);
    let mut seq = 0u64;
    loop {
        ticker.tick().await;
        if tokio::time::Instant::now() >= deadline {
            break;
        }
        let _ = frame_tx.send(make_frame(seq, false));
        seq += 1;
    }
    tokio::time::sleep(Duration::from_millis(500)).await;
    handle.shutdown();
    let batch_count = tokio::time::timeout(Duration::from_secs(3), collector)
        .await
        .expect("collector timed out")
        .expect("collector panicked");
    // Assert
    assert!(
        batch_count >= 285,
        "expected ≥285 batches, got {batch_count}"
    );
    assert_eq!(
        handle.stats().budget_drops_total(),
        0,
        "expected no budget drops"
    );
    if let Some(p99) = handle.latency_p99() {
        assert!(p99 <= Duration::from_millis(100), "p99 {p99:?} > 100 ms");
    }
 }
 // ---------------------------------------------------------------------------
 // AZ-660 AC-2 — reconnect after server closes stream
 // ---------------------------------------------------------------------------
 #[tokio::test(flavor = "multi_thread")]
 async fn ac660_2_reconnects_after_stream_close() {
    // The FixtureServer closes each stream-session after 3 responses; the
    // client must reconnect and continue receiving within 2 s.
    let (endpoint, _shutdown) = start_server_with(FixtureServer::fast().with_close_after(3)).await;
    let config = DetectionClientConfig {
        reconnect_initial: Duration::from_millis(100),
        reconnect_cap: Duration::from_millis(500),
        ..DetectionClientConfig::new(endpoint)
    };
    let (frame_tx, frame_rx) = broadcast::channel::<Frame>(64);
    let (_join, handle) = DetectionClient::new(config).run(frame_rx);
    wait_connected(&handle).await;
    let mut events = handle.subscribe_events();
    // Send 3 frames → server closes stream after the 3rd response.
    for i in 0u64..3 {
        let _ = frame_tx.send(make_frame(i, false));
        tokio::time::sleep(Duration::from_millis(25)).await;
    }
    // Give the stream-close time to propagate and the reconnect to happen.
    tokio::time::sleep(Duration::from_millis(300)).await;
    // Wait up to 2 s for the client to reconnect (AC-2 requirement).
    let mut conn = handle.connection_state_stream();
    tokio::time::timeout(Duration::from_secs(2), async {
        loop {
            if *conn.borrow() == ConnectionState::Connected {
                break;
            }
            let _ = conn.changed().await;
        }
    })
    .await
    .expect("reconnected within 2 s");
    // Verify frames continue to flow after reconnect.
    for i in 3u64..6 {
        let _ = frame_tx.send(make_frame(i, false));
        tokio::time::sleep(Duration::from_millis(25)).await;
    }
    let post_reconnect_batch = tokio::time::timeout(Duration::from_secs(2), async {
        loop {
            match events.recv().await {
                Ok(DetectionEvent::Batch { .. }) => return true,
                Ok(_) => {}
                Err(_) => return false,
            }
        }
    })
    .await
    .unwrap_or(false);
    // Assert
    assert!(post_reconnect_batch, "frames flow after reconnect");
    // Same model version on reconnect must NOT fire a second ModelVersionChanged.
    let model_changes = handle.stats().model_version_changes_total();
    assert_eq!(
        model_changes, 1,
        "same model version across reconnect must not repeat the event"
    );
    handle.shutdown();
 }
 // ---------------------------------------------------------------------------
 // AZ-660 AC-3 — budget drops on slow server (200 ms latency, 30 fps source)
 // ---------------------------------------------------------------------------
 #[tokio::test(flavor = "multi_thread")]
 async fn ac660_3_budget_drops_on_slow_server() {
    // Arrange
    let (endpoint, _shutdown) = start_server_with(FixtureServer::slow(200)).await;
    let config = DetectionClientConfig {
        max_concurrent_in_flight: 2,
        ..DetectionClientConfig::new(endpoint)
    };
    let (frame_tx, frame_rx) = broadcast::channel::<Frame>(512);
    let (_join, handle) = DetectionClient::new(config).run(frame_rx);
    wait_connected(&handle).await;
    // Act — 30 fps for 5 s; server takes 200 ms → budget full after frame 2.
    let mut ticker = tokio::time::interval(Duration::from_nanos(33_333_333));
    ticker.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
    let deadline = tokio::time::Instant::now() + Duration::from_secs(5);
    let mut seq = 0u64;
    loop {
        ticker.tick().await;
        if tokio::time::Instant::now() >= deadline {
            break;
        }
        let _ = frame_tx.send(make_frame(seq, false));
        seq += 1;
    }
    tokio::time::sleep(Duration::from_millis(300)).await;
    handle.shutdown();
    // Assert
    let drops = handle.stats().budget_drops_total();
    assert!(drops > 0, "expected budget_drops > 0, got 0");
 }
 // ---------------------------------------------------------------------------
 // AZ-660 AC-4 — ai_locked frames are skipped
 // ---------------------------------------------------------------------------
 #[tokio::test(flavor = "multi_thread")]
 async fn ac660_4_ai_locked_frames_skipped() {
    // Arrange
    let (endpoint, _shutdown) = start_server_with(FixtureServer::fast()).await;
    let (frame_tx, frame_rx) = broadcast::channel::<Frame>(256);
    let (_join, handle) = DetectionClient::new(DetectionClientConfig::new(endpoint)).run(frame_rx);
    wait_connected(&handle).await;
    // Act — 20 frames; every 5th is ai_locked (frames 4, 9, 14, 19 → 4 locked).
    for i in 0u64..20 {
        let ai_locked = (i + 1) % 5 == 0;
        let _ = frame_tx.send(make_frame(i, ai_locked));
        tokio::time::sleep(Duration::from_millis(15)).await;
    }
    tokio::time::sleep(Duration::from_millis(300)).await;
    handle.shutdown();
    // Assert
    let skipped = handle.stats().ai_locked_skipped_total();
    let sent = handle.stats().requests_sent_total();
    assert_eq!(skipped, 4, "expected 4 ai_locked skips, got {skipped}");
    assert!(sent <= 16, "expected ≤16 requests sent, got {sent}");
 }
 // ---------------------------------------------------------------------------
 // AZ-661 AC-1 — schema mismatch surfaces as hard error + counter
 // ---------------------------------------------------------------------------
 #[tokio::test(flavor = "multi_thread")]
 async fn ac661_1_schema_mismatch_hard_error() {
    // Arrange — server returns schema_version 99 (incompatible with expected 1).
    let (endpoint, _shutdown) =
        start_server_with(FixtureServer::fast().with_schema_version(99)).await;
    let config = DetectionClientConfig {
        expected_schema_version: 1,
        ..DetectionClientConfig::new(endpoint)
    };
    let (frame_tx, frame_rx) = broadcast::channel::<Frame>(64);
    let (_join, handle) = DetectionClient::new(config).run(frame_rx);
    let mut events = handle.subscribe_events();
    wait_connected(&handle).await;
    // Act
    let _ = frame_tx.send(make_frame(1, false));
    // Assert — SchemaMismatch event emitted and counter increments.
    let got_mismatch = tokio::time::timeout(Duration::from_secs(2), async {
        loop {
            match events.recv().await {
                Ok(DetectionEvent::SchemaMismatch { .. }) => return true,
                Ok(_) => {}
                Err(_) => return false,
            }
        }
    })
    .await
    .unwrap_or(false);
    assert!(got_mismatch, "expected SchemaMismatch event");
    assert!(
        handle.stats().schema_mismatch_total() >= 1,
        "expected schema_mismatch_total ≥ 1"
    );
    handle.shutdown();
 }
 // ---------------------------------------------------------------------------
 // AZ-661 AC-2 — model_version change is signalled exactly once
 // ---------------------------------------------------------------------------
 #[tokio::test(flavor = "multi_thread")]
 async fn ac661_2_model_version_change_emits_event() {
    // Arrange — server returns "v1.2" for the first response, then "v1.3".
    let (endpoint, _shutdown) = start_server_with(VersionSwitchServer {
        first_model: "v1.2".to_string(),
        second_model: "v1.3".to_string(),
        switch_after: 1,
    })
    .await;
    let (frame_tx, frame_rx) = broadcast::channel::<Frame>(64);
    let (_join, handle) = DetectionClient::new(DetectionClientConfig::new(endpoint)).run(frame_rx);
    let mut events = handle.subscribe_events();
    wait_connected(&handle).await;
    // Act — send 5 frames; responses 1 = "v1.2", responses 2-5 = "v1.3".
    for i in 0u64..5 {
        let _ = frame_tx.send(make_frame(i, false));
        tokio::time::sleep(Duration::from_millis(20)).await;
    }
    // Drain all pending events within a 500 ms window.
    let mut v13_events = 0u32;
    let drain_deadline = tokio::time::Instant::now() + Duration::from_millis(500);
    loop {
        let remaining = drain_deadline.saturating_duration_since(tokio::time::Instant::now());
        if remaining.is_zero() {
            break;
        }
        match tokio::time::timeout(remaining, events.recv()).await {
            Ok(Ok(DetectionEvent::ModelVersionChanged { current, .. })) => {
                if current == "v1.3" {
                    v13_events += 1;
                }
            }
            Ok(Ok(_)) => {}
            _ => break,
        }
    }
    handle.shutdown();
    // Assert — exactly one transition to "v1.3".
    assert_eq!(
        v13_events, 1,
        "expected exactly one ModelVersionChanged(v1.3), got {v13_events}"
    );
 }
 // ---------------------------------------------------------------------------
 // AZ-661 AC-3 — Tier1Degraded emitted exactly once on latency spike
 // ---------------------------------------------------------------------------
 #[tokio::test(flavor = "multi_thread")]
 async fn ac661_3_tier1_degraded_emitted_once_on_latency_spike() {
    // Arrange — small latency window (8 samples) so the window fills quickly;
    // server latency 150 ms > threshold 100 ms.
    let (endpoint, _shutdown) = start_server_with(FixtureServer::slow(150)).await;
    let config = DetectionClientConfig {
        latency_window_capacity: 8,
        latency_p99_threshold: Duration::from_millis(100),
        ..DetectionClientConfig::new(endpoint)
    };
    let (frame_tx, frame_rx) = broadcast::channel::<Frame>(64);
    let (_join, handle) = DetectionClient::new(config).run(frame_rx);
    let mut events = handle.subscribe_events();
    wait_connected(&handle).await;
    // Act — send 10 frames; server responds in 150 ms each.
    // The latency window (capacity 8) will be full of 150 ms samples after
    // 8 responses; p99 = 150 ms > 100 ms → exactly one Tier1Degraded event.
    for i in 0u64..10 {
        let _ = frame_tx.send(make_frame(i, false));
        tokio::time::sleep(Duration::from_millis(160)).await;
    }
    handle.shutdown();
    // Drain events.
    let mut degraded_count = 0u32;
    loop {
        match events.try_recv() {
            Ok(DetectionEvent::Tier1Degraded { .. }) => degraded_count += 1,
            Err(_) => break,
            Ok(_) => {}
        }
    }
    // Assert — the latch fires exactly once per degraded→healthy transition.
    assert_eq!(
        degraded_count, 1,
        "expected exactly one Tier1Degraded event, got {degraded_count}"
    );
 }
@@ -2,5 +2,6 @@
 pub mod decoder;
 pub mod lifecycle;
 pub mod publisher;
 pub mod rtsp_client;
 pub mod timestamp;
@@ -0,0 +1,366 @@
 //! AZ-659 — multi-consumer frame publisher with per-consumer drop accounting.
 //!
 //! `FrameIngest` already fans out to multiple subscribers via
 //! `tokio::sync::broadcast`, but a raw broadcast receiver silently
 //! folds lag into a single `RecvError::Lagged(n)` return value. The
 //! lifecycle loop has no way to attribute those drops back to *which*
 //! consumer fell behind, and the operator UI cannot tell "the AI
 //! tier is slow" from "the modem is slow".
 //!
 //! This module wraps the broadcast hub with:
 //!
 //! - a `ConsumerId` enum that names the three known consumers per
 //!   `description.md §3` (`detection_client`, `movement_detector`,
 //!   `telemetry_stream`);
 //! - a `PublisherStats` struct holding one `AtomicU64` drop counter
 //!   per consumer plus a total publish counter (lock-free; never
 //!   blocks the lifecycle loop);
 //! - a `FrameReceiver` wrapper around `broadcast::Receiver<Frame>`
 //!   that intercepts `RecvError::Lagged(n)` and folds it into the
 //!   right per-consumer counter before silently retrying — drops
 //!   are *counted*, never silent (`description.md §6` AC-2);
 //! - a `FramePublisher` struct that owns the broadcast `Sender` plus
 //!   the stats handle, exposes `subscribe(ConsumerId)`, and is
 //!   constructed with a configurable channel depth.
 //!
 //! The zero-copy property required by AC-3 lives in the `Frame`
 //! struct itself (`pixels: Arc<Bytes>`); the publisher does not
 //! copy the payload — the broadcast channel hands every subscriber
 //! the same `Arc`, so memory does not scale with consumer count.
 use std::sync::atomic::{AtomicU64, Ordering};
 use std::sync::Arc;
 use tokio::sync::broadcast;
 use shared::models::frame::Frame;
 /// Default per-consumer channel depth (`description.md §3` —
 /// nominal queue depth before a slow consumer's oldest frame is
 /// dropped). Picked at 4 frames so a 30 fps pipeline survives a
 /// ~130 ms downstream stall without dropping anything; longer
 /// stalls drop until the consumer catches up.
 pub const DEFAULT_CHANNEL_DEPTH: usize = 4;
 /// The three known downstream frame consumers. `non_exhaustive` so
 /// future additions (e.g. on-board recording) extend without
 /// breaking matchers.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 #[non_exhaustive]
 pub enum ConsumerId {
    DetectionClient,
    MovementDetector,
    Telemetry,
 }
 impl ConsumerId {
    /// Canonical drop-reason tag emitted to logs and surfaced through
    /// `FrameIngestHandle::dropped_frames`. Format matches the
    /// `description.md §6` reason vocabulary so the operator UI's
    /// existing reason filter works without changes.
    pub fn drop_reason(self) -> &'static str {
        match self {
            Self::DetectionClient => "detection_client_slow",
            Self::MovementDetector => "movement_detector_slow",
            Self::Telemetry => "telemetry_slow",
        }
    }
    /// Short identifier suitable for `tracing` fields.
    pub fn as_str(self) -> &'static str {
        match self {
            Self::DetectionClient => "detection_client",
            Self::MovementDetector => "movement_detector",
            Self::Telemetry => "telemetry_stream",
        }
    }
 }
 /// Lock-free counters consumed by `FrameIngestHandle::health` and by
 /// the operator-side per-consumer drop dashboard. Held inside an
 /// `Arc` and shared by the lifecycle task (writer side, via
 /// `FramePublisher::publish`) and every active `FrameReceiver`
 /// (writer side, via lag interception).
 #[derive(Debug, Default)]
 pub struct PublisherStats {
    publishes_total: AtomicU64,
    detection_client_drops: AtomicU64,
    movement_detector_drops: AtomicU64,
    telemetry_drops: AtomicU64,
 }
 impl PublisherStats {
    pub fn shared() -> Arc<Self> {
        Arc::new(Self::default())
    }
    pub fn publishes_total(&self) -> u64 {
        self.publishes_total.load(Ordering::Relaxed)
    }
    pub fn drops_for(&self, consumer: ConsumerId) -> u64 {
        self.counter(consumer).load(Ordering::Relaxed)
    }
    fn note_publish(&self) {
        self.publishes_total.fetch_add(1, Ordering::Relaxed);
    }
    fn note_drop(&self, consumer: ConsumerId, n: u64) {
        self.counter(consumer).fetch_add(n, Ordering::Relaxed);
    }
    fn counter(&self, consumer: ConsumerId) -> &AtomicU64 {
        match consumer {
            ConsumerId::DetectionClient => &self.detection_client_drops,
            ConsumerId::MovementDetector => &self.movement_detector_drops,
            ConsumerId::Telemetry => &self.telemetry_drops,
        }
    }
 }
 /// Multi-consumer fan-out hub. Wraps a `tokio::sync::broadcast`
 /// sender with the per-consumer accounting needed by AC-2 of
 /// AZ-659. The channel capacity is the `channel_depth` configured
 /// at construction; the broadcast channel's natural overwrite
 /// behaviour gives the "drop oldest for the slow consumer" semantic
 /// the task spec requires.
 #[derive(Debug)]
 pub struct FramePublisher {
    tx: broadcast::Sender<Frame>,
    stats: Arc<PublisherStats>,
    channel_depth: usize,
 }
 impl FramePublisher {
    pub fn new(channel_depth: usize) -> Self {
        let depth = channel_depth.max(1);
        let (tx, _rx) = broadcast::channel(depth);
        Self {
            tx,
            stats: PublisherStats::shared(),
            channel_depth: depth,
        }
    }
    pub fn channel_depth(&self) -> usize {
        self.channel_depth
    }
    /// Snapshot accessor for the shared stats object. Cheap clone
    /// (one `Arc::clone`).
    pub fn stats(&self) -> Arc<PublisherStats> {
        Arc::clone(&self.stats)
    }
    /// Subscribe under a named consumer identity. Per-consumer lag
    /// gets attributed to the named consumer's drop counter.
    pub fn subscribe(&self, consumer: ConsumerId) -> FrameReceiver {
        FrameReceiver {
            rx: self.tx.subscribe(),
            consumer,
            stats: Arc::clone(&self.stats),
        }
    }
    /// Subscribe without per-consumer accounting. Use for code paths
    /// that don't fit into one of the three known consumer roles
    /// (e.g. test harnesses, ad-hoc inspection). Lag on these
    /// receivers is *not* counted toward any per-consumer total.
    pub fn subscribe_raw(&self) -> broadcast::Receiver<Frame> {
        self.tx.subscribe()
    }
    /// Publish a frame. Returns the number of receivers that were
    /// subscribed at the moment the send happened (informational).
    /// Increments `publishes_total` even when there are zero
    /// subscribers — the publish *attempt* is what we measure for
    /// the §6 publish-rate dashboard.
    pub fn publish(&self, frame: Frame) -> usize {
        self.stats.note_publish();
        // `broadcast::Sender::send` returns `Err(SendError(_))` when
        // there are zero active receivers. That's a normal state
        // during start-up (consumers spawn slightly after the
        // publisher) and is not a failure — we treat the return
        // value purely as "how many consumers got this frame".
        self.tx.send(frame).unwrap_or_default()
    }
    /// Subscriber count snapshot — useful for health-server output
    /// ("AI tier was not subscribed when first frame arrived").
    pub fn receiver_count(&self) -> usize {
        self.tx.receiver_count()
    }
 }
 /// `broadcast::Receiver<Frame>` wrapper that folds lag into the
 /// owning consumer's drop counter before transparently retrying.
 /// `recv()` only returns `Ok(Frame)` or a fatal `RecvError::Closed`
 /// — lag is never surfaced to the caller; it is recorded and the
 /// next available frame is returned.
 #[derive(Debug)]
 pub struct FrameReceiver {
    rx: broadcast::Receiver<Frame>,
    consumer: ConsumerId,
    stats: Arc<PublisherStats>,
 }
 impl FrameReceiver {
    pub fn consumer(&self) -> ConsumerId {
        self.consumer
    }
    /// Block until the next frame is available. On lag, record the
    /// drop count against this consumer and immediately retry; the
    /// caller never sees `Lagged`. The only error variant returned
    /// is `RecvError::Closed`, which means the publisher has been
    /// dropped.
    pub async fn recv(&mut self) -> Result<Frame, RecvError> {
        loop {
            match self.rx.recv().await {
                Ok(frame) => return Ok(frame),
                Err(broadcast::error::RecvError::Lagged(n)) => {
                    self.note_lag(n);
                }
                Err(broadcast::error::RecvError::Closed) => return Err(RecvError::Closed),
            }
        }
    }
    /// Non-blocking variant. `Empty` is the channel-is-currently-empty
    /// case (no frames produced since the last `recv`/`try_recv`),
    /// not a fatal state. `Closed` mirrors the async variant.
    pub fn try_recv(&mut self) -> Result<Frame, TryRecvError> {
        loop {
            match self.rx.try_recv() {
                Ok(frame) => return Ok(frame),
                Err(broadcast::error::TryRecvError::Empty) => return Err(TryRecvError::Empty),
                Err(broadcast::error::TryRecvError::Closed) => return Err(TryRecvError::Closed),
                Err(broadcast::error::TryRecvError::Lagged(n)) => {
                    self.note_lag(n);
                }
            }
        }
    }
    fn note_lag(&self, n: u64) {
        self.stats.note_drop(self.consumer, n);
        tracing::warn!(
            consumer = self.consumer.as_str(),
            reason = self.consumer.drop_reason(),
            dropped = n,
            "frame_publisher dropped frames for slow consumer"
        );
    }
 }
 /// Errors that `FrameReceiver::recv` can return. Lag is *not* in
 /// this list — it is accounted internally.
 #[derive(Debug, thiserror::Error)]
 pub enum RecvError {
    #[error("frame publisher closed")]
    Closed,
 }
 #[derive(Debug, thiserror::Error)]
 pub enum TryRecvError {
    #[error("no frame available")]
    Empty,
    #[error("frame publisher closed")]
    Closed,
 }
 #[cfg(test)]
 mod tests {
    use std::sync::Arc;
    use bytes::Bytes;
    use shared::models::frame::{Frame, PixelFormat};
    use super::*;
    fn make_frame(seq: u64, payload: Arc<Bytes>) -> Frame {
        Frame {
            seq,
            capture_ts_monotonic_ns: seq * 1_000_000,
            decode_ts_monotonic_ns: seq * 1_000_000 + 100,
            pixels: payload,
            width: 320,
            height: 240,
            pix_fmt: PixelFormat::Nv12,
            ai_locked: false,
        }
    }
    #[test]
    fn channel_depth_defaults_to_at_least_one() {
        // Arrange
        let p = FramePublisher::new(0);
        // Assert — broadcast::channel(0) would panic, so we clamp.
        assert!(p.channel_depth() >= 1);
    }
    #[test]
    fn drop_reason_matches_description_md_vocabulary() {
        assert_eq!(
            ConsumerId::DetectionClient.drop_reason(),
            "detection_client_slow"
        );
        assert_eq!(
            ConsumerId::MovementDetector.drop_reason(),
            "movement_detector_slow"
        );
        assert_eq!(ConsumerId::Telemetry.drop_reason(), "telemetry_slow");
    }
    #[tokio::test]
    async fn publish_increments_total_even_without_subscribers() {
        // Arrange
        let p = FramePublisher::new(DEFAULT_CHANNEL_DEPTH);
        let stats = p.stats();
        let payload = Arc::new(Bytes::from_static(&[0u8; 32]));
        // Act
        for seq in 0..5 {
            p.publish(make_frame(seq, Arc::clone(&payload)));
        }
        // Assert
        assert_eq!(stats.publishes_total(), 5);
        assert_eq!(stats.drops_for(ConsumerId::DetectionClient), 0);
        assert_eq!(stats.drops_for(ConsumerId::MovementDetector), 0);
        assert_eq!(stats.drops_for(ConsumerId::Telemetry), 0);
    }
    #[tokio::test]
    async fn three_subscribers_share_arc_pixels_zero_copy() {
        // Arrange
        let p = FramePublisher::new(DEFAULT_CHANNEL_DEPTH);
        let mut det = p.subscribe(ConsumerId::DetectionClient);
        let mut mov = p.subscribe(ConsumerId::MovementDetector);
        let mut tel = p.subscribe(ConsumerId::Telemetry);
        let payload = Arc::new(Bytes::from(vec![0xABu8; 1024]));
        // Act
        p.publish(make_frame(1, Arc::clone(&payload)));
        let f_det = det.recv().await.expect("det recv");
        let f_mov = mov.recv().await.expect("mov recv");
        let f_tel = tel.recv().await.expect("tel recv");
        // Assert — every subscriber received the SAME `Arc<Bytes>`,
        // not a clone of the bytes.
        assert!(
            Arc::ptr_eq(&f_det.pixels, &f_mov.pixels),
            "det/mov must share the same Arc — broadcast must not deep-clone Bytes"
        );
        assert!(
            Arc::ptr_eq(&f_mov.pixels, &f_tel.pixels),
            "mov/tel must share the same Arc"
        );
        assert!(
            Arc::ptr_eq(&f_det.pixels, &payload),
            "received Arc must be the original payload pointer"
        );
    }
 }
@@ -1,4 +1,4 @@
-//! `frame_ingest` — RTSP pull + decode + timestamp.
+//! `frame_ingest` — RTSP pull + decode + timestamp + publish.
 //!
 //! Real implementation lands in:
 //! - AZ-657 `frame_ingest_rtsp_session` — session lifecycle + bounded
@@ -7,18 +7,31 @@
 //!   fallback) + per-frame monotonic timestamping + decode stats
 //!   (this crate, `internal/decoder.rs` + `internal/timestamp.rs`).
 //! - AZ-659 `frame_ingest_publisher` — bounded broadcast + per-consumer
-//!   drop policy.
+//!   drop policy (this crate, `internal/publisher.rs`).
 //!
 //! ## AZ-658 surface (extends AZ-657)
 //!
-//! `FrameIngest::run` now takes a [`FrameDecoder`]. The lifecycle loop
+//! `FrameIngest::run` takes a [`FrameDecoder`]. The lifecycle loop
 //! stamps the capture timestamp the moment a packet leaves the
 //! transport, hands the encoded payload to the decoder, and emits one
 //! [`Frame`] per decoded picture with `decode_ts_monotonic_ns` set
 //! when the decoder returned. Single-frame decode errors increment
 //! `decode_errors_total` and drop the frame; the stream is never
-//! aborted (AC-3). The decoder backend (`Nvdec` / `Software`) is
+//! aborted. The decoder backend (`Nvdec` / `Software`) is observable
-//! observable via [`FrameIngestHandle::decoder_backend`].
+//! via [`FrameIngestHandle::decoder_backend`].
 //!
 //! ## AZ-659 surface (extends AZ-658)
 //!
 //! Decoded frames flow through a [`FramePublisher`]. The publisher
 //! exposes [`FrameIngestHandle::subscribe_as`] for the three known
 //! consumers (`detection_client`, `movement_detector`,
 //! `telemetry_stream`); each subscriber's lag is folded into a
 //! per-consumer drop counter visible via
 //! [`FrameIngestHandle::dropped_frames`]. Drops are *counted* and
 //! `tracing::warn`-logged with a reason tag — never silent.
 //! `FrameIngestHandle::subscribe()` is preserved for legacy callers
 //! that don't fit one of the three named consumer roles; lag on
 //! those raw receivers is not attributed to any consumer counter.
 use std::sync::atomic::Ordering;
 use std::sync::Arc;
@@ -38,6 +51,10 @@ pub use internal::decoder::{
    FfmpegDecoder, FrameDecoder,
 };
 pub use internal::lifecycle::{BackoffPolicy, LifecycleStats, SessionState};
 pub use internal::publisher::{
    ConsumerId, FramePublisher, FrameReceiver, PublisherStats, RecvError as FrameRecvError,
    TryRecvError as FrameTryRecvError, DEFAULT_CHANNEL_DEPTH,
 };
 pub use internal::rtsp_client::{
    OpenError, RtspPacket, RtspSessionConfig, RtspTransport, RtspTransportHint, StreamError,
 };
@@ -53,7 +70,7 @@ const NAME: &str = "frame_ingest";
 const RED_FRAME_AGE: Duration = Duration::from_secs(5);
 pub struct FrameIngest {
-    tx: broadcast::Sender<Frame>,
+    publisher: Arc<FramePublisher>,
    ai_lock_tx: watch::Sender<bool>,
    state_tx: watch::Sender<SessionState>,
    shutdown_tx: watch::Sender<bool>,
@@ -65,6 +82,10 @@ pub struct FrameIngest {
 }
 impl FrameIngest {
    /// Default constructor — `channel_capacity` maps directly to the
    /// publisher's `channel_depth` (see `description.md §3`). Use
    /// [`Self::with_backoff`] when both the depth and the reopen
    /// backoff need to be customised.
    pub fn new(channel_capacity: usize) -> Self {
        Self::with_backoff(
            channel_capacity,
@@ -73,13 +94,13 @@ impl FrameIngest {
    }
    pub fn with_backoff(channel_capacity: usize, backoff: BackoffPolicy) -> Self {
-        let (tx, _rx) = broadcast::channel(channel_capacity);
+        let publisher = Arc::new(FramePublisher::new(channel_capacity));
        let (ai_lock_tx, _) = watch::channel(false);
        let (state_tx, _) = watch::channel(SessionState::Closed);
        let (shutdown_tx, _) = watch::channel(false);
        let (backend_tx, _) = watch::channel(None);
        Self {
-            tx,
+            publisher,
            ai_lock_tx,
            state_tx,
            shutdown_tx,
@@ -91,9 +112,18 @@ impl FrameIngest {
        }
    }
    /// Shared accessor for the underlying [`FramePublisher`]. The
    /// composition root passes this `Arc` to consumers that prefer
    /// to subscribe themselves (named via [`ConsumerId`]) rather
    /// than receiving a pre-built [`FrameReceiver`] over the
    /// handle.
    pub fn publisher(&self) -> Arc<FramePublisher> {
        Arc::clone(&self.publisher)
    }
    pub fn handle(&self) -> FrameIngestHandle {
        FrameIngestHandle {
-            tx: self.tx.clone(),
+            publisher: Arc::clone(&self.publisher),
            ai_lock_tx: self.ai_lock_tx.clone(),
            state_rx: self.state_tx.subscribe(),
            shutdown_tx: self.shutdown_tx.clone(),
@@ -115,7 +145,7 @@ impl FrameIngest {
        T: RtspTransport + 'static,
        D: FrameDecoder + 'static,
    {
-        let tx = self.tx.clone();
+        let publisher = Arc::clone(&self.publisher);
        let ai_lock = self.ai_lock_tx.subscribe();
        let state_tx = self.state_tx.clone();
        let backend_tx = self.backend_tx.clone();
@@ -135,7 +165,7 @@ impl FrameIngest {
                transport,
                decoder,
                config,
-                tx,
+                publisher,
                ai_lock,
                state_tx,
                shutdown_rx,
@@ -158,7 +188,7 @@ async fn lifecycle_loop<T>(
    transport: Arc<Mutex<T>>,
    mut decoder: Box<dyn FrameDecoder + Send>,
    config: RtspSessionConfig,
-    tx: broadcast::Sender<Frame>,
+    publisher: Arc<FramePublisher>,
    mut ai_lock: watch::Receiver<bool>,
    state_tx: watch::Sender<SessionState>,
    mut shutdown_rx: watch::Receiver<bool>,
@@ -250,12 +280,14 @@ async fn lifecycle_loop<T>(
                                            pix_fmt: dp.pix_fmt,
                                            ai_locked: locked,
                                        };
-                                        // Send errors are no-ops when
+                                        // The publisher folds lag
-                                        // the broadcast has no
+                                        // into per-consumer drop
-                                        // subscribers; per-consumer
+                                        // counters; the lifecycle
-                                        // back-pressure is AZ-659's
+                                        // loop never blocks on a
-                                        // problem.
+                                        // slow consumer. Return
-                                        let _ = tx.send(frame);
+                                        // value (subscriber count)
                                        // is informational.
                                        publisher.publish(frame);
                                    }
                                }
                                Err(e) => {
@@ -309,7 +341,7 @@ async fn lifecycle_loop<T>(
 #[derive(Clone)]
 pub struct FrameIngestHandle {
-    tx: broadcast::Sender<Frame>,
+    publisher: Arc<FramePublisher>,
    ai_lock_tx: watch::Sender<bool>,
    state_rx: watch::Receiver<SessionState>,
    shutdown_tx: watch::Sender<bool>,
@@ -320,12 +352,47 @@ pub struct FrameIngestHandle {
 }
 impl FrameIngestHandle {
-    /// Subscribe to the frame stream. Consumers receive every frame
+    /// Raw, unaccounted subscription. Used by legacy callers and
-    /// after they subscribed; back-pressure is implemented via
+    /// tests that don't fit one of the three named [`ConsumerId`]
-    /// broadcast channel lag (see AZ-659 for the slow-consumer
+    /// roles. Lag on this receiver is *not* attributed to any
-    /// policy).
+    /// per-consumer drop counter — prefer [`Self::subscribe_as`] for
    /// production consumers so the per-consumer drop dashboard
    /// stays accurate.
    pub fn subscribe(&self) -> broadcast::Receiver<Frame> {
-        self.tx.subscribe()
+        self.publisher.subscribe_raw()
    }
    /// Subscribe under a named consumer identity. Per-consumer lag
    /// is folded into the matching drop counter and surfaced via
    /// [`Self::dropped_frames`]. The returned [`FrameReceiver`]
    /// transparently retries past lag so callers never observe
    /// `Lagged` — they only see the next available frame.
    pub fn subscribe_as(&self, consumer: ConsumerId) -> FrameReceiver {
        self.publisher.subscribe(consumer)
    }
    /// Shared accessor for the underlying [`FramePublisher`]. Useful
    /// when a consumer needs to subscribe multiple times (e.g.
    /// reopening a receiver after a transient logical reset) without
    /// holding the full ingest handle.
    pub fn publisher(&self) -> Arc<FramePublisher> {
        Arc::clone(&self.publisher)
    }
    /// Per-consumer drop counter. Increments by `n` every time the
    /// matching [`FrameReceiver`] would otherwise have surfaced
    /// `RecvError::Lagged(n)`.
    pub fn dropped_frames(&self, consumer: ConsumerId) -> u64 {
        self.publisher.stats().drops_for(consumer)
    }
    /// Total publish attempts since the publisher was constructed.
    /// Increments on every decoded frame even when there are zero
    /// subscribers — the metric is the publish *rate*, not the
    /// delivered-frame rate. Use [`Self::dropped_frames`] for the
    /// delivered-vs-published delta per consumer.
    pub fn publishes_total(&self) -> u64 {
        self.publisher.stats().publishes_total()
    }
    /// `bringCameraDown`/`bringCameraUp` per `description.md §2`. When
@@ -467,4 +534,23 @@ mod tests {
        handle.set_ai_lock(false);
        assert!(!handle.ai_locked());
    }
    #[test]
    fn handle_exposes_publisher_metrics_before_run() {
        // Arrange
        let ingest = FrameIngest::new(4);
        let handle = ingest.handle();
        // Assert — fresh publisher exposes zero metrics for every
        // known consumer (the AZ-659 health surface contract).
        assert_eq!(handle.publishes_total(), 0);
        assert_eq!(handle.dropped_frames(ConsumerId::DetectionClient), 0);
        assert_eq!(handle.dropped_frames(ConsumerId::MovementDetector), 0);
        assert_eq!(handle.dropped_frames(ConsumerId::Telemetry), 0);
        assert_eq!(
            handle.publisher().channel_depth(),
            4,
            "channel_capacity from constructor must propagate to the publisher"
        );
    }
 }
@@ -0,0 +1,263 @@
 //! AZ-659 — `FramePublisher` integration tests.
 //!
 //! These tests drive the publisher directly (no RTSP / decoder
 //! involved) so they execute in milliseconds and don't depend on
 //! libavcodec or NVDEC. The AZ-658 pipeline tests cover the
 //! lifecycle-loop integration end-to-end.
 //!
 //! ACs covered here:
 //! - AC-1 — three consumers consuming at-rate observe every frame and
 //!   drop counters stay at 0.
 //! - AC-2 — a slow consumer's lag is folded into THAT consumer's
 //!   drop counter while fast consumers continue to receive every
 //!   frame.
 //! - AC-3 — zero-copy fan-out: every consumer receives the same
 //!   `Arc<Bytes>` (asserted via `Arc::ptr_eq`) so memory does not
 //!   scale with consumer count.
 use std::sync::Arc;
 use std::time::Duration;
 use bytes::Bytes;
 use frame_ingest::{ConsumerId, FramePublisher, DEFAULT_CHANNEL_DEPTH};
 use shared::models::frame::{Frame, PixelFormat};
 use tokio::time::{sleep, timeout};
 fn make_frame(seq: u64, pixels: Arc<Bytes>) -> Frame {
    Frame {
        seq,
        capture_ts_monotonic_ns: seq * 1_000_000,
        decode_ts_monotonic_ns: seq * 1_000_000 + 100,
        pixels,
        width: 320,
        height: 240,
        pix_fmt: PixelFormat::Nv12,
        ai_locked: false,
    }
 }
 /// AC-1 — three consumers consuming as fast as the publisher emits
 /// observe every frame; per-consumer drop counters stay at 0. The
 /// spec quotes 30 fps for 10 s (~300 frames); we use 30 frames at
 /// no artificial delay to keep CI under 1 s. The semantic property
 /// — "consumers that keep up never lose a frame" — is identical.
 #[tokio::test(flavor = "multi_thread", worker_threads = 4)]
 async fn ac1_three_consumers_at_rate_lose_no_frames() {
    // Arrange
    let publisher = Arc::new(FramePublisher::new(DEFAULT_CHANNEL_DEPTH));
    let stats = publisher.stats();
    let mut det = publisher.subscribe(ConsumerId::DetectionClient);
    let mut mov = publisher.subscribe(ConsumerId::MovementDetector);
    let mut tel = publisher.subscribe(ConsumerId::Telemetry);
    let total: u64 = 30;
    let publisher_for_task = Arc::clone(&publisher);
    // Act — drain in parallel while publishing. Each consumer drains
    // immediately, so the broadcast channel stays well under
    // `DEFAULT_CHANNEL_DEPTH` and no consumer can lag.
    let producer = tokio::spawn(async move {
        let payload = Arc::new(Bytes::from(vec![0xAAu8; 256]));
        for seq in 0..total {
            publisher_for_task.publish(make_frame(seq, Arc::clone(&payload)));
            // Yield so subscribers get a chance to drain between
            // sends; without this the producer races ahead and any
            // delay in tokio scheduling could falsely trip the lag
            // counter even for a "fast" consumer at this small scale.
            tokio::task::yield_now().await;
        }
    });
    let drain = |mut rx: frame_ingest::FrameReceiver, label: &'static str| {
        tokio::spawn(async move {
            let mut got = 0u64;
            while got < total {
                match timeout(Duration::from_secs(2), rx.recv()).await {
                    Ok(Ok(_)) => got += 1,
                    Ok(Err(e)) => panic!("{label} recv closed early: {e}"),
                    Err(_) => panic!("{label} stalled at {got}/{total}"),
                }
            }
            got
        })
    };
    let h_det = drain(det.take(), "detection_client");
    let h_mov = drain(mov.take(), "movement_detector");
    let h_tel = drain(tel.take(), "telemetry");
    producer.await.expect("producer");
    assert_eq!(h_det.await.expect("det join"), total);
    assert_eq!(h_mov.await.expect("mov join"), total);
    assert_eq!(h_tel.await.expect("tel join"), total);
    // Assert — every consumer drained at-rate, so no drops on any
    // counter and `publishes_total` matches the produced count.
    assert_eq!(stats.publishes_total(), total);
    assert_eq!(stats.drops_for(ConsumerId::DetectionClient), 0);
    assert_eq!(stats.drops_for(ConsumerId::MovementDetector), 0);
    assert_eq!(stats.drops_for(ConsumerId::Telemetry), 0);
 }
 /// AC-2 — a slow consumer (yields slowly) is the only one to incur
 /// drops; the fast consumers continue to observe every frame. The
 /// producer paces its sends at ~5 ms intervals so fast consumers
 /// can drain in between; the slow consumer sleeps ~25 ms per frame,
 /// so the broadcast channel laps it after a handful of frames.
 #[tokio::test(flavor = "multi_thread", worker_threads = 4)]
 async fn ac2_slow_consumer_drops_while_fast_consumers_unaffected() {
    // Arrange — depth-2 channel + a producer that paces sends.
    let channel_depth = 2usize;
    let publisher = Arc::new(FramePublisher::new(channel_depth));
    let stats = publisher.stats();
    let mut det = publisher.subscribe(ConsumerId::DetectionClient); // fast
    let mut mov = publisher.subscribe(ConsumerId::MovementDetector); // fast
    let mut tel = publisher.subscribe(ConsumerId::Telemetry); // SLOW
    let total: u64 = 30;
    let payload = Arc::new(Bytes::from(vec![0xBBu8; 64]));
    // Spawn consumers BEFORE the producer task so the broadcast
    // already has live subscribers when the first publish lands.
    let slow = tokio::spawn(async move {
        let mut got = 0u64;
        let deadline = Duration::from_secs(10);
        let start = tokio::time::Instant::now();
        // The slow consumer keeps polling until the broadcast
        // channel closes (publisher drops) OR the safety deadline
        // fires. A `Closed` here is the natural termination signal
        // once the producer's `Arc<FramePublisher>` goes out of
        // scope; we don't try to predict how many frames it gets
        // because that depends on scheduling jitter.
        while start.elapsed() < deadline {
            match timeout(Duration::from_millis(500), tel.recv()).await {
                Ok(Ok(_)) => {
                    got += 1;
                    sleep(Duration::from_millis(25)).await;
                }
                Ok(Err(_)) => break, // Closed: producer finished.
                Err(_) => {
                    // Timeout — assume producer is done and exit.
                    break;
                }
            }
        }
        got
    });
    let drain_fast = |mut rx: frame_ingest::FrameReceiver, label: &'static str| {
        tokio::spawn(async move {
            let mut got = 0u64;
            while got < total {
                match timeout(Duration::from_secs(3), rx.recv()).await {
                    Ok(Ok(_)) => got += 1,
                    Ok(Err(e)) => panic!("{label} recv closed early: {e}"),
                    Err(_) => panic!("{label} stalled at {got}/{total}"),
                }
            }
            got
        })
    };
    let h_det = drain_fast(det.take(), "detection_client");
    let h_mov = drain_fast(mov.take(), "movement_detector");
    // Give consumers a moment to enter `recv` before producing.
    sleep(Duration::from_millis(10)).await;
    // Act — pace sends ~5 ms apart so fast consumers have time to
    // drain each frame before the next arrives. The slow consumer
    // can only process ~1 frame per 25 ms, so it inevitably lags.
    let publisher_for_task = Arc::clone(&publisher);
    let payload_for_task = Arc::clone(&payload);
    let producer = tokio::spawn(async move {
        for seq in 0..total {
            publisher_for_task.publish(make_frame(seq, Arc::clone(&payload_for_task)));
            sleep(Duration::from_millis(5)).await;
        }
    });
    producer.await.expect("producer");
    assert_eq!(h_det.await.expect("det join"), total);
    assert_eq!(h_mov.await.expect("mov join"), total);
    // Drop the last `Arc<FramePublisher>` so the slow consumer's
    // recv returns `Closed` and it can exit on its own.
    drop(publisher);
    let slow_got = slow.await.expect("slow join");
    // Assert — the slow consumer dropped frames; the fast ones did
    // not. The exact drop count varies with scheduler jitter so we
    // assert "> 0" rather than a specific number.
    assert_eq!(
        stats.drops_for(ConsumerId::DetectionClient),
        0,
        "fast consumer must not have any drops"
    );
    assert_eq!(
        stats.drops_for(ConsumerId::MovementDetector),
        0,
        "fast consumer must not have any drops"
    );
    let tel_drops = stats.drops_for(ConsumerId::Telemetry);
    assert!(
        tel_drops > 0,
        "slow telemetry consumer must have at least one drop; got {tel_drops}"
    );
    // Every frame is accounted for from the slow consumer's
    // perspective: delivered + dropped == published.
    assert_eq!(
        slow_got + tel_drops,
        stats.publishes_total(),
        "received + dropped must equal published for the slow consumer"
    );
 }
 /// AC-3 — fan-out is zero-copy: each subscriber observes the SAME
 /// `Arc<Bytes>` for a given frame. Asserts the property via
 /// `Arc::ptr_eq` between the pixel handles delivered to two
 /// different consumers; the test does not depend on timing.
 #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
 async fn ac3_fan_out_is_zero_copy_via_arc_bytes() {
    // Arrange
    let publisher = Arc::new(FramePublisher::new(DEFAULT_CHANNEL_DEPTH));
    let mut det = publisher.subscribe(ConsumerId::DetectionClient);
    let mut mov = publisher.subscribe(ConsumerId::MovementDetector);
    let mut tel = publisher.subscribe(ConsumerId::Telemetry);
    let payload = Arc::new(Bytes::from(vec![0xCDu8; 1024]));
    // Act
    publisher.publish(make_frame(42, Arc::clone(&payload)));
    let f_det = det.recv().await.expect("det recv");
    let f_mov = mov.recv().await.expect("mov recv");
    let f_tel = tel.recv().await.expect("tel recv");
    // Assert — same Arc across consumers AND across publisher
    // boundary; the broadcast did not deep-clone Bytes anywhere.
    assert!(Arc::ptr_eq(&f_det.pixels, &payload));
    assert!(Arc::ptr_eq(&f_mov.pixels, &payload));
    assert!(Arc::ptr_eq(&f_tel.pixels, &payload));
    assert!(Arc::ptr_eq(&f_det.pixels, &f_mov.pixels));
    assert!(Arc::ptr_eq(&f_mov.pixels, &f_tel.pixels));
 }
 // `FrameReceiver` does not implement `Copy` and the public surface
 // returns it by value, so we move it into the spawned task via
 // `take()` on a small helper. Defined here to keep test bodies tidy.
 trait Takeable {
    fn take(&mut self) -> frame_ingest::FrameReceiver;
 }
 impl Takeable for frame_ingest::FrameReceiver {
    fn take(&mut self) -> frame_ingest::FrameReceiver {
        // SAFETY: we replace `self` with a fresh detached receiver
        // that the test no longer uses; this lets us move ownership
        // out of a `&mut`-bound binding without unsafe code.
        std::mem::replace(self, dummy_receiver())
    }
 }
 fn dummy_receiver() -> frame_ingest::FrameReceiver {
    let p = FramePublisher::new(1);
    p.subscribe(ConsumerId::DetectionClient)
 }
@@ -103,8 +103,8 @@ impl CentreOnTarget {
        let cy = (bbox.y_min + bbox.y_max) * 0.5;
        let err_x = cx - 0.5;
        let err_y = cy - 0.5;
-        let on_target =
+        let on_target = err_x.abs() <= self.config.centre_half_width
-            err_x.abs() <= self.config.centre_half_width && err_y.abs() <= self.config.centre_half_width;
+            && err_y.abs() <= self.config.centre_half_width;
        // Effective FOV shrinks as zoom grows; the same pixel error
        // therefore corresponds to a smaller angular error at high
@@ -177,7 +177,9 @@ mod tests {
        let mut on_target_after = None;
        for tick_idx in 0..3 {
            let out = ctrl.tick(Some(bbox), yaw, pitch, zoom);
-            let cmd = out.command.expect("loop should emit a command on every tick with bbox");
+            let cmd = out
                .command
                .expect("loop should emit a command on every tick with bbox");
            let dy = cmd.yaw_deg - yaw;
            let dp = cmd.pitch_deg - pitch;
            yaw = cmd.yaw_deg;
@@ -232,20 +234,35 @@ mod tests {
        let out5 = ctrl.tick(None, 0.0, 0.0, 1.0);
        // Assert
-        assert!(out3.target_lost_signal, "target_lost did not fire at tick 3");
+        assert!(
-        assert!(!out4.target_lost_signal, "target_lost re-fired during sustained loss");
+            out3.target_lost_signal,
-        assert!(!out5.target_lost_signal, "target_lost re-fired during sustained loss");
+            "target_lost did not fire at tick 3"
        );
        assert!(
            !out4.target_lost_signal,
            "target_lost re-fired during sustained loss"
        );
        assert!(
            !out5.target_lost_signal,
            "target_lost re-fired during sustained loss"
        );
        // Act 4: bbox returns → loss state clears, new streak can re-fire
        let recovered = ctrl.tick(Some(bbox_at(0.5, 0.5, 0.1, 0.1)), 0.0, 0.0, 1.0);
-        assert!(recovered.command.is_some(), "recovery tick must emit command");
+        assert!(
            recovered.command.is_some(),
            "recovery tick must emit command"
        );
        assert!(!recovered.target_lost_signal);
        for _ in 0..2 {
            assert!(!ctrl.tick(None, 0.0, 0.0, 1.0).target_lost_signal);
        }
        let lost_again = ctrl.tick(None, 0.0, 0.0, 1.0);
-        assert!(lost_again.target_lost_signal, "second loss streak did not fire");
+        assert!(
            lost_again.target_lost_signal,
            "second loss streak did not fire"
        );
    }
    #[test]
@@ -220,7 +220,11 @@ mod tests {
        match step {
            NextStep::Emit(cmd) => {
                let diff = (cmd.yaw_deg - 15.0).abs();
-                assert!(diff < 0.01, "yaw at t=500ms was {}, want ~15.0", cmd.yaw_deg);
+                assert!(
                    diff < 0.01,
                    "yaw at t=500ms was {}, want ~15.0",
                    cmd.yaw_deg
                );
            }
            NextStep::Throttled => panic!("first emission should not be throttled"),
        }
@@ -29,9 +29,7 @@ pub use internal::centre_on_target::{
    CentreOnTarget, CentreOnTargetConfig, CentreOnTargetOutput, DEFAULT_CENTRE_WINDOW,
    DEFAULT_MAX_MISSED_TICKS, DEFAULT_TARGET_GAIN,
 };
-pub use internal::smooth_pan::{
+pub use internal::smooth_pan::{ExecutorStats, NextStep, PlanExecutor, DEFAULT_MIN_CMD_INTERVAL};
    ExecutorStats, NextStep, PlanExecutor, DEFAULT_MIN_CMD_INTERVAL,
 };
 pub use internal::sweep::{SweepConfig, SweepEngine, SweepPattern};
 pub use internal::transport::{
    A40Error, A40Transport, VendorFaults, VendorFaultsSnapshot, DEFAULT_COMMAND_DEADLINE,
@@ -104,9 +102,12 @@ impl GimbalControllerHandle {
    /// vendor has acknowledged via a T1_F1_B1_D1 reply (its standard
    /// angle-feedback frame) or the bounded retry budget exhausts.
    pub async fn set_pose(&self, command: GimbalCommand) -> Result<()> {
-        let transport = self.transport.as_ref().ok_or(AutopilotError::NotImplemented(
+        let transport = self
-            "gimbal_controller::set_pose: no transport wired",
+            .transport
-        ))?;
+            .as_ref()
            .ok_or(AutopilotError::NotImplemented(
                "gimbal_controller::set_pose: no transport wired",
            ))?;
        let data = build_a1_angles(command.yaw_deg, command.pitch_deg);
        let _reply = transport
            .send_with_response(FrameId::A1, &data, FrameId::T1F1B1D1)
@@ -129,9 +130,12 @@ impl GimbalControllerHandle {
    /// protocol. The continuous-rate C1 ZOOM_IN / ZOOM_OUT pair is
    /// reserved for AZ-654's sweep primitive.
    pub async fn zoom(&self, level: f32) -> Result<()> {
-        let transport = self.transport.as_ref().ok_or(AutopilotError::NotImplemented(
+        let transport = self
-            "gimbal_controller::zoom: no transport wired",
+            .transport
-        ))?;
+            .as_ref()
            .ok_or(AutopilotError::NotImplemented(
                "gimbal_controller::zoom: no transport wired",
            ))?;
        let data = build_c2_set_zoom(level);
        // C2 SET_EO_ZOOM ack arrives as a T1_F1_B1_D1 (the vendor's
        // generic angle/status feedback frame).
@@ -78,9 +78,22 @@ async fn az656_set_pose_publishes_monotonic_timestamp() {
    }
    // Assert
-    assert!(timestamps[0] > 0, "initial stamp should be > 0 after first set_pose");
+    assert!(
-    assert!(timestamps[1] > timestamps[0], "ts not monotonic: {} → {}", timestamps[0], timestamps[1]);
+        timestamps[0] > 0,
-    assert!(timestamps[2] > timestamps[1], "ts not monotonic: {} → {}", timestamps[1], timestamps[2]);
+        "initial stamp should be > 0 after first set_pose"
    );
    assert!(
        timestamps[1] > timestamps[0],
        "ts not monotonic: {} → {}",
        timestamps[0],
        timestamps[1]
    );
    assert!(
        timestamps[2] > timestamps[1],
        "ts not monotonic: {} → {}",
        timestamps[1],
        timestamps[2]
    );
 }
 /// AZ-655 integration — load a plan and exercise the executor against
@@ -33,16 +33,27 @@
 //!   subsequent `Degraded` / `Fail` flips it back to `false` and the
 //!   FSM's `bit_ok` guard fails closed.
 use std::collections::VecDeque;
 use std::sync::Arc;
 use std::time::Duration;
 use async_trait::async_trait;
 use chrono::{DateTime, Utc};
 use serde::{Deserialize, Serialize};
 use shared::contracts::BitReportSeverityLookup;
 use tokio::sync::{broadcast, mpsc, watch, Mutex};
 use tokio::task::JoinHandle;
 use tokio::time::Instant;
 use uuid::Uuid;
 /// AZ-681 — bounded FIFO cap for the per-report `BitOverall` cache
 /// queried by [`BitControllerHandle::is_acknowledgeable`]. BIT is a
 /// pre-flight gate that goes sticky-Pass after success, so the
 /// number of distinct report ids generated in one flight is small
 /// (one per evaluation cycle until Pass / Failed). 16 is generous
 /// without unbounded growth.
 const REPORT_OVERALL_CAP: usize = 16;
 // ============================================================================
 // Public surface — types
 // ============================================================================
@@ -236,6 +247,7 @@ impl BitController {
            state: BitState::Idle,
            last_report: None,
            sticky_pass: false,
            report_overalls: VecDeque::with_capacity(REPORT_OVERALL_CAP),
        }));
        let handle = BitControllerHandle {
@@ -335,6 +347,11 @@ impl BitController {
                            config.ack_timeout,
                        );
                        let report_clone = report.clone();
                        record_report_overall(
                            &mut guard.report_overalls,
                            report.id,
                            report.overall,
                        );
                        guard.last_report = Some(report);
                        if new_state != from {
                            guard.state = new_state.clone();
@@ -442,6 +459,28 @@ struct ControllerInner {
    /// downstream surfaces (lost-link ladder, geofence, battery —
    /// AZ-651 / AZ-652).
    sticky_pass: bool,
    /// AZ-681 — recent `(report_id, overall)` pairs for the
    /// `BitReportSeverityLookup` impl. Bounded FIFO; oldest evicted
    /// at [`REPORT_OVERALL_CAP`]. A `None` lookup result means the
    /// id has either never been generated or has aged out.
    report_overalls: VecDeque<(Uuid, BitOverall)>,
 }
 /// Push a `(report_id, overall)` pair onto the bounded FIFO cache.
 /// Re-recording an existing id is a no-op (preserves the original
 /// position so callers can't accidentally refresh aging).
 fn record_report_overall(
    cache: &mut VecDeque<(Uuid, BitOverall)>,
    report_id: Uuid,
    overall: BitOverall,
 ) {
    if cache.iter().any(|(id, _)| *id == report_id) {
        return;
    }
    if cache.len() == REPORT_OVERALL_CAP {
        cache.pop_front();
    }
    cache.push_back((report_id, overall));
 }
 /// Read-side handle for the BIT controller. Cloneable.
@@ -475,6 +514,32 @@ impl BitControllerHandle {
    pub async fn last_report(&self) -> Option<BitReport> {
        self.inner.lock().await.last_report.clone()
    }
    /// AZ-681 — overall verdict for a previously-generated report.
    /// Returns `None` if the id has never been generated or has aged
    /// out of the bounded cache.
    pub async fn report_overall(&self, report_id: Uuid) -> Option<BitOverall> {
        self.inner
            .lock()
            .await
            .report_overalls
            .iter()
            .find_map(|(id, o)| (*id == report_id).then_some(*o))
    }
 }
 /// AZ-681 — `operator_bridge` (Layer 3) consults this before
 /// forwarding a BIT-degraded ack. `Fail` reports are never
 /// acknowledgeable (per AZ-681 AC-2). An aged-out / never-seen id
 /// returns `None` so the bridge can NACK with a typed
 /// "unknown report id" reason.
 #[async_trait]
 impl BitReportSeverityLookup for BitControllerHandle {
    async fn is_acknowledgeable(&self, report_id: Uuid) -> Option<bool> {
        self.report_overall(report_id)
            .await
            .map(|o| !matches!(o, BitOverall::Fail))
    }
 }
 #[cfg(test)]
@@ -11,5 +11,6 @@ pub mod lost_link;
 pub mod middle_waypoint;
 pub mod multirotor;
 pub mod post_flight;
 pub mod safety_dispatch;
 pub mod telemetry;
 pub mod types;
@@ -0,0 +1,97 @@
 //! AZ-681 — concrete [`MissionSafetyRouter`] implementation owned by
 //! `mission_executor` so `operator_bridge` (Layer 3) can stay free of
 //! direct `mission_executor` imports.
 //!
 //! The composition root constructs a [`SafetyDispatchHandle`] from the
 //! BIT controller's `ack` mpsc sender and the battery monitor's handle,
 //! then hands an `Arc<dyn MissionSafetyRouter>` to the operator-bridge
 //! builder.
 //!
 //! Mapping (per `architecture.md §F10`):
 //!
 //! - `acknowledge_bit_degraded` → push a [`BitDegradedAck`] onto the
 //!   BIT controller's ack channel. The controller validates the
 //!   `report_id` matches `AwaitingAck`; `operator_bridge` has already
 //!   validated the signature + checked `BitReportSeverityLookup` to
 //!   ensure the report is acknowledgeable (NOT `Fail`).
 //! - `apply_safety_override` → translate `SafetyOverrideScope` into the
 //!   subsystem-specific override. Only `BatteryRtl` is supported in
 //!   AZ-681 (other failsafe families add their own paths later); the
 //!   hard-floor land-now is NEVER suppressible regardless of scope.
 use std::time::Duration;
 use async_trait::async_trait;
 use tokio::sync::mpsc;
 use tokio::time::Instant;
 use shared::contracts::MissionSafetyRouter;
 use shared::error::{AutopilotError, Result};
 use shared::models::operator::SafetyOverrideScope;
 use uuid::Uuid;
 use crate::internal::battery_thresholds::{BatteryMonitorHandle, BatteryOverride};
 use crate::internal::bit::BitDegradedAck;
 /// Concrete dispatcher for safety-critical operator commands. Owns
 /// only the handles it needs; do not stuff additional concerns here.
 #[derive(Clone)]
 pub struct SafetyDispatchHandle {
    bit_ack_tx: mpsc::Sender<BitDegradedAck>,
    battery: BatteryMonitorHandle,
 }
 impl SafetyDispatchHandle {
    pub fn new(bit_ack_tx: mpsc::Sender<BitDegradedAck>, battery: BatteryMonitorHandle) -> Self {
        Self {
            bit_ack_tx,
            battery,
        }
    }
 }
 #[async_trait]
 impl MissionSafetyRouter for SafetyDispatchHandle {
    async fn acknowledge_bit_degraded(
        &self,
        report_id: Uuid,
        operator_id: Option<String>,
    ) -> Result<()> {
        self.bit_ack_tx
            .send(BitDegradedAck {
                report_id,
                operator_id,
            })
            .await
            .map_err(|e| AutopilotError::Internal(format!("bit ack channel closed: {e}")))
    }
    async fn apply_safety_override(
        &self,
        scope: SafetyOverrideScope,
        duration_secs: u32,
        operator_id: String,
        rationale: String,
    ) -> Result<()> {
        match scope {
            SafetyOverrideScope::BatteryRtl => {
                let until = Instant::now() + Duration::from_secs(u64::from(duration_secs));
                self.battery
                    .apply_override(BatteryOverride {
                        until,
                        operator_id,
                        rationale,
                    })
                    .await
            }
            // `SafetyOverrideScope` is `#[non_exhaustive]`; future
            // variants (e.g. `LinkLost`, `Geofence`) MUST be wired
            // explicitly here before they become usable. Until then,
            // surface a typed Validation error so `operator_bridge`
            // can NACK to the operator UI.
            other => Err(AutopilotError::Validation(format!(
                "safety override scope {other:?} not wired in mission_executor"
            ))),
        }
    }
 }
@@ -58,6 +58,7 @@ pub use internal::lost_link::{
 };
 pub use internal::middle_waypoint::{MiddleWaypointHint, MissionRePlanner};
 pub use internal::post_flight::{MapObjectsDiffSource, MapObjectsPusher, PostFlightPusher};
 pub use internal::safety_dispatch::SafetyDispatchHandle;
 pub use internal::telemetry::{
    Consumer, DropCountingReceiver, MavlinkProjection, TelemetryForwarder,
 };
@@ -16,5 +16,7 @@ learned_cv = []
 shared = { workspace = true }
 tokio = { workspace = true }
 tracing = { workspace = true }
 opencv = { workspace = true }
-# OpenCV / homography deps land with AZ-662 (`movement_detector_ego_motion`).
+[dev-dependencies]
 bytes = { workspace = true }
@@ -0,0 +1,388 @@
 //! AZ-662 — Ego-motion estimator + telemetry-skew gate.
 //!
 //! `EgoMotionEstimator::estimate` checks gimbal/UAV timestamp skew against the
 //! per-zoom-band tolerance, then runs OpenCV Lucas–Kanade optical-flow +
 //! RANSAC homography on consecutive grayscale frames to recover camera motion.
 use std::sync::{
    atomic::{AtomicU64, Ordering},
    Arc,
 };
 use opencv::{core::Mat, prelude::*};
 use shared::models::{
    frame::Frame,
    gimbal::GimbalState,
    movement::ZoomBand,
    telemetry::UavTelemetry,
 };
 use super::{
    optical_flow::{self, FlowError},
    telemetry_sync::{self, SkewExceeded},
    zoom_bands::zoom_band_from_level,
 };
 /// Per-frame ego-motion recovered from optical flow.
 #[derive(Debug, Clone)]
 pub struct EgoMotion {
    /// Row-major 3×3 homography mapping the previous frame's coordinates to
    /// the current frame's coordinates (camera ego-motion).
    pub homography: [f64; 9],
    /// Mean reprojection residual across inlier feature tracks (pixels).
    pub residual_motion_magnitude: f32,
    pub zoom_band: ZoomBand,
 }
 /// Error variants returned by `EgoMotionEstimator::estimate`.
 #[derive(Debug)]
 pub enum EgoMotionError {
    /// Frame ↔ gimbal or frame ↔ UAV timestamp skew exceeded the per-band
    /// tolerance. The affected frame must not be used for ego-motion.
    SkewExceeded(SkewExceeded),
    /// The current frame is degenerate (saturated, blank, or featureless).
    /// The frame is stored internally so the next call can resume.
    OpticalFlowDegenerate,
    /// No previous frame has been received yet; the current frame is stored
    /// as the reference for the next call.
    NoPreviousFrame,
    Internal(String),
 }
 impl From<SkewExceeded> for EgoMotionError {
    fn from(e: SkewExceeded) -> Self {
        EgoMotionError::SkewExceeded(e)
    }
 }
 /// Atomic health counters exposed through `MovementDetectorHandle::health()`.
 pub struct EgoMotionCounters {
    pub telemetry_skew_drops_zoomed_out: AtomicU64,
    pub telemetry_skew_drops_zoomed_in: AtomicU64,
    pub optical_flow_degenerate_total: AtomicU64,
 }
 impl EgoMotionCounters {
    pub fn new() -> Self {
        Self {
            telemetry_skew_drops_zoomed_out: AtomicU64::new(0),
            telemetry_skew_drops_zoomed_in: AtomicU64::new(0),
            optical_flow_degenerate_total: AtomicU64::new(0),
        }
    }
    pub fn skew_drops(&self, band: ZoomBand) -> u64 {
        match band {
            ZoomBand::ZoomedOut => {
                self.telemetry_skew_drops_zoomed_out.load(Ordering::Relaxed)
            }
            ZoomBand::ZoomedIn => {
                self.telemetry_skew_drops_zoomed_in.load(Ordering::Relaxed)
            }
        }
    }
    pub fn skew_drops_total(&self) -> u64 {
        self.skew_drops(ZoomBand::ZoomedOut) + self.skew_drops(ZoomBand::ZoomedIn)
    }
    pub fn degenerate_total(&self) -> u64 {
        self.optical_flow_degenerate_total.load(Ordering::Relaxed)
    }
    fn inc_skew_drop(&self, band: ZoomBand) {
        match band {
            ZoomBand::ZoomedOut => {
                self.telemetry_skew_drops_zoomed_out.fetch_add(1, Ordering::Relaxed);
            }
            ZoomBand::ZoomedIn => {
                self.telemetry_skew_drops_zoomed_in.fetch_add(1, Ordering::Relaxed);
            }
        }
    }
    fn inc_degenerate(&self) {
        self.optical_flow_degenerate_total.fetch_add(1, Ordering::Relaxed);
    }
 }
 impl Default for EgoMotionCounters {
    fn default() -> Self {
        Self::new()
    }
 }
 /// Stateful per-frame ego-motion estimator.
 ///
 /// Call `estimate` once per frame in arrival order. The estimator keeps the
 /// previous frame's grayscale Mat internally; the first call always returns
 /// `Err(NoPreviousFrame)` and stores the frame as the reference.
 pub struct EgoMotionEstimator {
    prev_gray: Option<Mat>,
    counters: Arc<EgoMotionCounters>,
 }
 impl EgoMotionEstimator {
    pub fn new(counters: Arc<EgoMotionCounters>) -> Self {
        Self { prev_gray: None, counters }
    }
    pub fn counters(&self) -> &Arc<EgoMotionCounters> {
        &self.counters
    }
    /// Estimate ego-motion for `frame` relative to the previous accepted frame.
    ///
    /// Processing order:
    /// 1. Telemetry-skew gate (increments `telemetry_skew_drops_total` on miss).
    /// 2. Convert to grayscale.
    /// 3. Degenerate-frame detection (increments `optical_flow_degenerate_total`).
    /// 4. Require a previous accepted frame; store current if none.
    /// 5. LK optical flow + RANSAC homography.
    pub fn estimate(
        &mut self,
        frame: &Frame,
        gimbal_state: &GimbalState,
        uav_telemetry: &UavTelemetry,
    ) -> Result<EgoMotion, EgoMotionError> {
        let zoom_band = zoom_band_from_level(gimbal_state.zoom);
        // 1. Skew gate.
        telemetry_sync::check_skew(
            frame.capture_ts_monotonic_ns,
            gimbal_state.ts_monotonic_ns,
            uav_telemetry.monotonic_ts_ns,
            zoom_band,
        )
        .map_err(|e| {
            self.counters.inc_skew_drop(zoom_band);
            EgoMotionError::SkewExceeded(e)
        })?;
        // 2. Grayscale conversion.
        let curr_gray = optical_flow::frame_to_gray(frame)
            .map_err(|e| EgoMotionError::Internal(e.message))?;
        // 3. Degenerate check — runs before the prev-frame guard so a
        //    saturated frame still stores itself and returns a clear error.
        if optical_flow::is_degenerate(&curr_gray)
            .unwrap_or(false)
        {
            self.counters.inc_degenerate();
            self.prev_gray = Some(curr_gray);
            return Err(EgoMotionError::OpticalFlowDegenerate);
        }
        // 4. Need a previous frame for optical flow.
        let prev_gray = match self.prev_gray.take() {
            None => {
                self.prev_gray = Some(curr_gray);
                return Err(EgoMotionError::NoPreviousFrame);
            }
            Some(p) => p,
        };
        // 5. Optical flow → homography.
        let result = optical_flow::estimate_homography(&prev_gray, &curr_gray);
        self.prev_gray = Some(curr_gray);
        match result {
            Ok(hr) => Ok(EgoMotion {
                homography: hr.h,
                residual_motion_magnitude: hr.residual_magnitude_px,
                zoom_band,
            }),
            Err(FlowError::Degenerate | FlowError::InsufficientFeatures) => {
                self.counters.inc_degenerate();
                Err(EgoMotionError::OpticalFlowDegenerate)
            }
            Err(FlowError::Internal(msg)) => Err(EgoMotionError::Internal(msg)),
        }
    }
 }
 // ── Tests ────────────────────────────────────────────────────────────────────
 #[cfg(test)]
 mod tests {
    use std::sync::Arc;
    use bytes::Bytes;
    use opencv::{
        core::{Mat, Scalar, CV_8UC1},
        prelude::*,
    };
    use shared::models::{
        frame::{Frame, PixelFormat},
        gimbal::GimbalState,
        movement::ZoomBand,
        telemetry::UavTelemetry,
    };
    use super::*;
    // ── helpers ──────────────────────────────────────────────────────────────
    /// Build a 1-channel Mat filled by `fill(row, col)`.
    fn make_gray_mat(
        size: i32,
        fill: impl Fn(i32, i32) -> u8,
    ) -> opencv::Result<Mat> {
        let mut mat =
            Mat::new_rows_cols_with_default(size, size, CV_8UC1, Scalar::all(0.0))?;
        for r in 0..size {
            for c in 0..size {
                *mat.at_2d_mut::<u8>(r, c)? = fill(r, c);
            }
        }
        Ok(mat)
    }
    /// Checkerboard with 8-pixel blocks, optionally shifted right by `offset_x`.
    fn checkerboard(size: i32, offset_x: i32) -> opencv::Result<Mat> {
        make_gray_mat(size, |r, c| {
            let sc = c - offset_x;
            if sc < 0 || sc >= size {
                128
            } else if (sc / 8 + r / 8) % 2 == 0 {
                200
            } else {
                50
            }
        })
    }
    /// Wrap a 1-channel Mat as a Nv12 `Frame` (Y-plane only — sufficient for
    /// `frame_to_gray` which reads only the first w×h bytes).
    fn mat_to_frame(mat: &Mat, ts_ns: u64) -> opencv::Result<Frame> {
        let h = mat.rows() as u32;
        let w = mat.cols() as u32;
        let total = (w * h) as usize;
        let mut pixels = vec![0u8; total];
        for r in 0..h as i32 {
            for c in 0..w as i32 {
                pixels[(r * w as i32 + c) as usize] = *mat.at_2d::<u8>(r, c)?;
            }
        }
        Ok(Frame {
            seq: 0,
            capture_ts_monotonic_ns: ts_ns,
            decode_ts_monotonic_ns: ts_ns,
            pixels: Arc::new(Bytes::from(pixels)),
            width: w,
            height: h,
            pix_fmt: PixelFormat::Nv12,
            ai_locked: false,
        })
    }
    fn synced_gimbal(ts_ns: u64) -> GimbalState {
        GimbalState {
            yaw: 0.0,
            pitch: -30.0,
            zoom: 1.0,
            ts_monotonic_ns: ts_ns,
            command_in_flight: false,
        }
    }
    fn synced_uav(ts_ns: u64) -> UavTelemetry {
        UavTelemetry { monotonic_ts_ns: ts_ns, ..UavTelemetry::empty() }
    }
    // ── AC-1: synthetic pure pan — residual ≈ 0 ──────────────────────────────
    #[test]
    fn ac1_pure_pan_residual_near_zero() -> opencv::Result<()> {
        let counters = Arc::new(EgoMotionCounters::new());
        let mut est = EgoMotionEstimator::new(Arc::clone(&counters));
        let size = 200;
        let dx = 8i32; // one checkerboard block = well-defined shift
        let mat1 = checkerboard(size, 0)?;
        let mat2 = checkerboard(size, dx)?;
        let t0 = 1_000_000_000u64;
        let frame1 = mat_to_frame(&mat1, t0)?;
        let frame2 = mat_to_frame(&mat2, t0 + 33_000_000)?; // +33 ms (30 fps)
        let gimbal = synced_gimbal(t0);
        let uav = synced_uav(t0);
        // First call stores prev; NoPreviousFrame is expected.
        assert!(matches!(est.estimate(&frame1, &gimbal, &uav), Err(EgoMotionError::NoPreviousFrame)));
        let gimbal2 = synced_gimbal(t0 + 33_000_000);
        let uav2 = synced_uav(t0 + 33_000_000);
        let ego = est.estimate(&frame2, &gimbal2, &uav2)
            .expect("estimate should succeed on second call");
        // X-translation H[0][2] should approximate dx within ±2 px.
        let h02 = ego.homography[2];
        assert!(
            h02.abs() > 0.5 && (h02 - dx as f64).abs() < 2.5,
            "H[0][2] = {h02:.2}, expected ≈ {dx}"
        );
        // Residual should be near zero for a pure rigid shift.
        assert!(
            ego.residual_motion_magnitude < 3.0,
            "residual = {:.2} px, expected < 3.0",
            ego.residual_motion_magnitude
        );
        assert_eq!(ego.zoom_band, ZoomBand::ZoomedOut);
        Ok(())
    }
    // ── AC-2: telemetry skew above zoom-out tolerance → SkewExceeded ─────────
    #[test]
    fn ac2_skew_above_zoom_out_tolerance_dropped() -> opencv::Result<()> {
        let counters = Arc::new(EgoMotionCounters::new());
        let mut est = EgoMotionEstimator::new(Arc::clone(&counters));
        let frame_ts = 1_000_000_000u64;
        let frame = mat_to_frame(&checkerboard(100, 0)?, frame_ts)?;
        // Gimbal timestamp 200 ms ahead of frame; tolerance = 50 ms.
        let gimbal = GimbalState {
            zoom: 1.0, // zoomed_out → 50 ms tolerance
            ts_monotonic_ns: frame_ts + 200_000_000,
            yaw: 0.0,
            pitch: -30.0,
            command_in_flight: false,
        };
        let uav = synced_uav(frame_ts);
        assert!(matches!(
            est.estimate(&frame, &gimbal, &uav),
            Err(EgoMotionError::SkewExceeded(_))
        ));
        assert_eq!(counters.skew_drops(ZoomBand::ZoomedOut), 1);
        Ok(())
    }
    // ── AC-3: fully-saturated white frame → OpticalFlowDegenerate ────────────
    #[test]
    fn ac3_degenerate_white_frame() -> opencv::Result<()> {
        let counters = Arc::new(EgoMotionCounters::new());
        let mut est = EgoMotionEstimator::new(Arc::clone(&counters));
        let ts = 1_000_000_000u64;
        let white_mat =
            Mat::new_rows_cols_with_default(100, 100, CV_8UC1, Scalar::all(255.0))?;
        let frame = mat_to_frame(&white_mat, ts)?;
        let gimbal = synced_gimbal(ts);
        let uav = synced_uav(ts);
        assert!(matches!(
            est.estimate(&frame, &gimbal, &uav),
            Err(EgoMotionError::OpticalFlowDegenerate)
        ));
        assert_eq!(counters.degenerate_total(), 1);
        Ok(())
    }
 }
@@ -0,0 +1,4 @@
 pub mod ego_motion;
 pub mod optical_flow;
 pub mod telemetry_sync;
 pub mod zoom_bands;
@@ -0,0 +1,212 @@
 //! Classical OpenCV optical-flow / homography estimation path.
 //! Lucas–Kanade sparse tracking → RANSAC homography.
 use opencv::{
    calib3d,
    core::{self, Mat, Point2f, TermCriteria, Vector},
    imgproc,
    prelude::*,
    video,
 };
 use shared::models::frame::{Frame, PixelFormat};
 pub struct HomographyResult {
    /// Row-major 3×3 homography mapping prev frame coords → curr frame coords.
    pub h: [f64; 9],
    /// Mean reprojection residual (pixels) across tracked inliers.
    pub residual_magnitude_px: f32,
 }
 #[derive(Debug)]
 pub enum FlowError {
    Degenerate,
    InsufficientFeatures,
    Internal(String),
 }
 impl From<opencv::Error> for FlowError {
    fn from(e: opencv::Error) -> Self {
        FlowError::Internal(e.message)
    }
 }
 /// True when the grayscale frame lacks sufficient contrast for feature
 /// detection (saturated, blank, or nearly uniform).
 pub fn is_degenerate(gray: &Mat) -> opencv::Result<bool> {
    let mut min_val = 0.0f64;
    let mut max_val = 0.0f64;
    core::min_max_loc(
        gray,
        Some(&mut min_val),
        Some(&mut max_val),
        None,
        None,
        &core::no_array(),
    )?;
    Ok((max_val - min_val) < 10.0)
 }
 /// Convert an autopilot `Frame` to a single-channel (grayscale) OpenCV Mat.
 /// NV12 / YUV420p: the Y-plane (first w×h bytes) is the grayscale image.
 /// RGB24: a single cvtColor call produces the grayscale output.
 pub fn frame_to_gray(frame: &Frame) -> opencv::Result<Mat> {
    let h = frame.height as i32;
    let w = frame.width as i32;
    let data: &[u8] = &frame.pixels;
    match frame.pix_fmt {
        PixelFormat::Nv12 | PixelFormat::Yuv420p => {
            let y_len = (w * h) as usize;
            copy_bytes_to_gray_mat(&data[..y_len], w, h)
        }
        PixelFormat::Rgb24 => {
            let rgb_len = (w * h * 3) as usize;
            let mut rgb_mat = Mat::new_rows_cols_with_default(
                h, w, core::CV_8UC3, core::Scalar::all(0.0),
            )?;
            // SAFETY: rgb_mat is a freshly allocated continuous Mat; no aliasing.
            // `data_mut()` returns `*mut u8` directly in opencv 0.98 (no Result).
            let mat_data = unsafe {
                std::slice::from_raw_parts_mut(rgb_mat.data_mut(), rgb_len)
            };
            mat_data.copy_from_slice(&data[..rgb_len]);
            let mut gray = Mat::default();
            imgproc::cvt_color(&rgb_mat, &mut gray, imgproc::COLOR_RGB2GRAY, 0)?;
            Ok(gray)
        }
    }
 }
 fn copy_bytes_to_gray_mat(src: &[u8], w: i32, h: i32) -> opencv::Result<Mat> {
    let mut mat =
        Mat::new_rows_cols_with_default(h, w, core::CV_8UC1, core::Scalar::all(0.0))?;
    // SAFETY: mat is a freshly allocated continuous Mat; no aliasing.
    // `data_mut()` returns `*mut u8` directly in opencv 0.98 (no Result).
    let mat_data = unsafe {
        std::slice::from_raw_parts_mut(mat.data_mut(), src.len())
    };
    mat_data.copy_from_slice(src);
    Ok(mat)
 }
 /// Estimate the homography prev_gray → curr_gray via sparse LK optical flow
 /// and RANSAC. Returns the 3×3 homography (row-major) and the mean inlier
 /// reprojection residual.
 pub fn estimate_homography(
    prev_gray: &Mat,
    curr_gray: &Mat,
 ) -> Result<HomographyResult, FlowError> {
    // 1. Detect good corners in the previous frame.
    let mut prev_pts: Vector<Point2f> = Vector::new();
    imgproc::good_features_to_track(
        prev_gray,
        &mut prev_pts,
        100,
        0.01,
        10.0,
        &core::no_array(),
        3,
        false,
        0.04,
    )?;
    if (prev_pts.len() as i32) < 4 {
        return Err(FlowError::InsufficientFeatures);
    }
    // 2. Lucas–Kanade pyramidal sparse optical flow.
    let mut curr_pts: Vector<Point2f> = Vector::new();
    let mut status: Vector<u8> = Vector::new();
    let mut err_vec: Vector<f32> = Vector::new();
    // TermCriteria type 3 = COUNT(1) | EPS(2)
    let term = TermCriteria::new(3, 30, 0.01)?;
    video::calc_optical_flow_pyr_lk(
        prev_gray,
        curr_gray,
        &prev_pts,
        &mut curr_pts,
        &mut status,
        &mut err_vec,
        core::Size::new(21, 21),
        3,
        term,
        0,
        1e-4,
    )?;
    // 3. Keep only successfully tracked point pairs.
    let mut good_prev: Vector<Point2f> = Vector::new();
    let mut good_curr: Vector<Point2f> = Vector::new();
    for i in 0..status.len() {
        if status.get(i)? == 1 {
            good_prev.push(prev_pts.get(i)?);
            good_curr.push(curr_pts.get(i)?);
        }
    }
    if (good_prev.len() as i32) < 4 {
        return Err(FlowError::InsufficientFeatures);
    }
    // 4. Estimate homography with RANSAC (reproj threshold = 3 px).
    let mut mask = Mat::default();
    let h_mat = calib3d::find_homography(
        &good_prev,
        &good_curr,
        &mut mask,
        calib3d::RANSAC,
        3.0,
    )?;
    if h_mat.empty() {
        return Err(FlowError::InsufficientFeatures);
    }
    // 5. Extract homography values (row-major).
    let mut h = [0f64; 9];
    for r in 0..3usize {
        for c in 0..3usize {
            h[r * 3 + c] = *h_mat.at_2d::<f64>(r as i32, c as i32)?;
        }
    }
    // 6. Mean reprojection residual across RANSAC inliers ONLY.
    //
    // `find_homography(..., RANSAC, 3.0)` populates `mask` with 1 for
    // inlier point pairs (consistent with the fitted homography to
    // within 3 px) and 0 for outliers. Including outliers in the
    // residual would defeat the purpose of RANSAC: a synthetic pure
    // pan can have edge features whose LK-tracked flow is off by the
    // shift amount (the post-shift region falls outside the original
    // frame); those points become RANSAC outliers and would otherwise
    // inflate the residual by several pixels.
    let mut total = 0.0f32;
    let mut count = 0u32;
    for i in 0..good_prev.len() {
        let is_inlier = mask
            .at_2d::<u8>(i as i32, 0)
            .map(|v| *v != 0)
            .unwrap_or(false);
        if !is_inlier {
            continue;
        }
        let p = good_prev.get(i)?;
        let c = good_curr.get(i)?;
        let x = p.x as f64;
        let y = p.y as f64;
        let denom = h[6] * x + h[7] * y + h[8];
        if denom.abs() < 1e-9 {
            continue;
        }
        let px = (h[0] * x + h[1] * y + h[2]) / denom;
        let py = (h[3] * x + h[4] * y + h[5]) / denom;
        let dx = px as f32 - c.x;
        let dy = py as f32 - c.y;
        total += (dx * dx + dy * dy).sqrt();
        count += 1;
    }
    let residual_magnitude_px = if count > 0 { total / count as f32 } else { 0.0 };
    Ok(HomographyResult { h, residual_magnitude_px })
 }
@@ -0,0 +1,67 @@
 //! Frame ↔ gimbal ↔ UAV telemetry skew gate.
 //! Rejects frames whose telemetry timestamp delta exceeds the per-zoom-band
 //! tolerance — see `description.md §5` and `description.md §7`.
 use shared::models::movement::ZoomBand;
 use super::zoom_bands::ZoomBandTolerances;
 /// Returned when either skew delta exceeds the per-band tolerance.
 #[derive(Debug)]
 pub struct SkewExceeded {
    pub band: ZoomBand,
    pub gimbal_skew_ns: u64,
    pub uav_skew_ns: u64,
 }
 /// Check frame ↔ gimbal and frame ↔ UAV skew against per-band tolerances.
 /// Returns `Err(SkewExceeded)` if either exceeds its threshold.
 pub fn check_skew(
    frame_ts_ns: u64,
    gimbal_ts_ns: u64,
    uav_ts_ns: u64,
    band: ZoomBand,
 ) -> Result<(), SkewExceeded> {
    let tolerances = ZoomBandTolerances::for_band(band);
    let gimbal_skew = frame_ts_ns.abs_diff(gimbal_ts_ns);
    let uav_skew = frame_ts_ns.abs_diff(uav_ts_ns);
    if gimbal_skew > tolerances.frame_gimbal_ns || uav_skew > tolerances.frame_uav_ns {
        return Err(SkewExceeded { band, gimbal_skew_ns: gimbal_skew, uav_skew_ns: uav_skew });
    }
    Ok(())
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    #[test]
    fn in_tolerance_passes() {
        check_skew(1_000_000_000, 1_010_000_000, 1_020_000_000, ZoomBand::ZoomedOut).unwrap();
    }
    #[test]
    fn gimbal_skew_exceeds_zoom_out_tolerance() {
        let err = check_skew(
            1_000_000_000,
            1_200_000_000, // 200 ms > 50 ms threshold
            1_010_000_000,
            ZoomBand::ZoomedOut,
        )
        .unwrap_err();
        assert_eq!(err.gimbal_skew_ns, 200_000_000);
    }
    #[test]
    fn uav_skew_exceeds_zoom_in_tolerance() {
        let err = check_skew(
            1_000_000_000,
            1_010_000_000,
            1_060_000_000, // 60 ms > 50 ms zoom-in UAV threshold
            ZoomBand::ZoomedIn,
        )
        .unwrap_err();
        assert_eq!(err.uav_skew_ns, 60_000_000);
    }
 }
@@ -0,0 +1,63 @@
 //! Per-zoom-band threshold tables — see `description.md §5`.
 use shared::models::movement::ZoomBand;
 /// Telemetry-skew tolerances for a given zoom band.
 /// Nanosecond values per `description.md §5`.
 pub struct ZoomBandTolerances {
    pub frame_gimbal_ns: u64,
    pub frame_uav_ns: u64,
 }
 impl ZoomBandTolerances {
    pub fn for_band(band: ZoomBand) -> Self {
        match band {
            ZoomBand::ZoomedOut => Self {
                frame_gimbal_ns: 50_000_000,
                frame_uav_ns: 100_000_000,
            },
            ZoomBand::ZoomedIn => Self {
                frame_gimbal_ns: 25_000_000,
                frame_uav_ns: 50_000_000,
            },
        }
    }
 }
 /// Derive zoom band from the gimbal's current zoom level.
 /// Zoom ≤ 2.0 → wide-area sweep; zoom > 2.0 → detailed-scan hold.
 pub fn zoom_band_from_level(zoom: f32) -> ZoomBand {
    if zoom > 2.0 {
        ZoomBand::ZoomedIn
    } else {
        ZoomBand::ZoomedOut
    }
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    #[test]
    fn zoom_out_tolerances() {
        let t = ZoomBandTolerances::for_band(ZoomBand::ZoomedOut);
        assert_eq!(t.frame_gimbal_ns, 50_000_000);
        assert_eq!(t.frame_uav_ns, 100_000_000);
    }
    #[test]
    fn zoom_in_tolerances_are_stricter() {
        let out = ZoomBandTolerances::for_band(ZoomBand::ZoomedOut);
        let inn = ZoomBandTolerances::for_band(ZoomBand::ZoomedIn);
        assert!(inn.frame_gimbal_ns < out.frame_gimbal_ns);
        assert!(inn.frame_uav_ns < out.frame_uav_ns);
    }
    #[test]
    fn band_from_zoom_level() {
        assert_eq!(zoom_band_from_level(1.0), ZoomBand::ZoomedOut);
        assert_eq!(zoom_band_from_level(2.0), ZoomBand::ZoomedOut);
        assert_eq!(zoom_band_from_level(2.1), ZoomBand::ZoomedIn);
        assert_eq!(zoom_band_from_level(5.0), ZoomBand::ZoomedIn);
    }
 }
@@ -1,30 +1,37 @@
 //! `movement_detector` — ego-motion compensated residual-motion clustering.
 //!
-//! Real implementation lands in:
+//! AZ-662: ego-motion estimator + telemetry-skew gate (this batch).
-//! - AZ-662 `movement_detector_ego_motion`
+//! AZ-663: residual clustering + candidate emission (next batch).
-//! - AZ-663 `movement_detector_clustering_and_emission`
+//! AZ-664: FP cap + Q14 learned-CV fallback.
-//! - AZ-664 `movement_detector_fp_cap_and_q14_fallback`
+
 use std::sync::Arc;
 use tokio::sync::broadcast;
-use shared::health::ComponentHealth;
+use shared::health::{ComponentHealth, HealthLevel};
 use shared::models::movement::MovementCandidate;
 pub(crate) mod internal;
 use internal::ego_motion::EgoMotionCounters;
 const NAME: &str = "movement_detector";
 pub struct MovementDetector {
    tx: broadcast::Sender<MovementCandidate>,
    counters: Arc<EgoMotionCounters>,
 }
 impl MovementDetector {
    pub fn new(channel_capacity: usize) -> Self {
        let (tx, _rx) = broadcast::channel(channel_capacity);
-        Self { tx }
+        Self { tx, counters: Arc::new(EgoMotionCounters::new()) }
    }
    pub fn handle(&self) -> MovementDetectorHandle {
        MovementDetectorHandle {
            tx: self.tx.clone(),
            counters: Arc::clone(&self.counters),
        }
    }
 }
@@ -32,6 +39,7 @@ impl MovementDetector {
 #[derive(Clone)]
 pub struct MovementDetectorHandle {
    tx: broadcast::Sender<MovementCandidate>,
    counters: Arc<EgoMotionCounters>,
 }
 impl MovementDetectorHandle {
@@ -40,7 +48,23 @@ impl MovementDetectorHandle {
    }
    pub fn health(&self) -> ComponentHealth {
-        ComponentHealth::disabled(NAME)
+        let skew_drops = self.counters.skew_drops_total();
        let degenerate = self.counters.degenerate_total();
        if skew_drops > 0 || degenerate > 0 {
            ComponentHealth::yellow(
                NAME,
                format!(
                    "skew_drops_total={skew_drops} optical_flow_degenerate_total={degenerate}"
                ),
            )
        } else {
            ComponentHealth {
                level: HealthLevel::Disabled,
                component: NAME,
                detail: None,
            }
        }
    }
 }
@@ -51,6 +75,9 @@ mod tests {
    #[test]
    fn it_compiles() {
        let h = MovementDetector::new(16).handle();
-        assert_eq!(h.health().level, shared::health::HealthLevel::Disabled);
+        assert!(matches!(
            h.health().level,
            HealthLevel::Disabled | HealthLevel::Yellow
        ));
    }
 }
@@ -0,0 +1,54 @@
 //! AZ-680 / AZ-681 — the typed acknowledgement returned by every
 //! dispatched operator command.
 //!
 //! The dispatcher does NOT propagate downstream errors verbatim into
 //! the operator UI — the surface here is a small fixed enum so the
 //! UI can colour-code the result and so the idempotency cache key
 //! space stays bounded.
 use serde::{Deserialize, Serialize};
 /// Stable kebab-case reason strings emitted in
 /// [`CommandAck::Error::reason`]. Exposed as constants so the unit +
 /// integration tests can reference them without retyping the strings
 /// (drift between caller assertions and the actual emit site has bit
 /// us before).
 pub mod ack_reasons {
    pub const UNKNOWN_POI_ID: &str = "unknown_poi_id";
    pub const EXPIRED: &str = "expired";
    pub const CANNOT_ACKNOWLEDGE_FAIL: &str = "cannot_acknowledge_fail";
    pub const UNKNOWN_BIT_REPORT: &str = "unknown_bit_report";
    pub const INVALID_PAYLOAD: &str = "invalid_payload";
    pub const ROUTER_NOT_WIRED: &str = "router_not_wired";
    pub const ROUTER_ERROR: &str = "router_error";
    pub const UNSUPPORTED_KIND: &str = "unsupported_kind";
 }
 /// Result of a dispatched operator command. Carries either `Ok` or a
 /// typed `Error { reason }` whose `reason` string is one of the
 /// kebab-case constants in [`ack_reasons`].
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(tag = "kind", rename_all = "snake_case")]
 pub enum CommandAck {
    Ok,
    Error { reason: String },
 }
 impl CommandAck {
    pub fn error(reason: &str) -> Self {
        Self::Error {
            reason: reason.to_string(),
        }
    }
    pub fn is_ok(&self) -> bool {
        matches!(self, Self::Ok)
    }
    pub fn reason(&self) -> Option<&str> {
        match self {
            Self::Ok => None,
            Self::Error { reason } => Some(reason.as_str()),
        }
    }
 }
@@ -0,0 +1,151 @@
 //! AZ-681 — structured audit log for safety-critical operator commands.
 //!
 //! Per the task spec (AC-4): every dispatched `BitDegradedAck` and
 //! `SafetyOverride` writes an audit entry containing:
 //!
 //! - command id
 //! - timestamp (UTC, ms precision)
 //! - operator id (when known)
 //! - scope / duration (for `SafetyOverride`) or `report_id` (for
 //!   `BitDegradedAck`)
 //! - outcome (`Ok` / `Error { reason }`)
 //!
 //! Entries MUST NEVER contain the raw signature bytes or the session
 //! token (AC-4). Callers pass already-redacted fields; the writer
 //! has no access to the signature in the first place.
 //!
 //! ## Why both a sink trait + a tracing default
 //!
 //! - The default ([`TracingAuditSink`]) emits one structured
 //!   `tracing::info!` per entry — meets the spec's "file or
 //!   structured logger" requirement and integrates with whatever
 //!   tracing subscriber the composition root wires.
 //! - The trait ([`AuditSink`]) lets tests substitute a recording
 //!   sink without piggy-backing on tracing's global subscriber
 //!   state (which other tests can race against). The integration
 //!   tests in `tests/dispatcher.rs` use the recording sink.
 use std::sync::Arc;
 use async_trait::async_trait;
 use chrono::{DateTime, Utc};
 use serde::Serialize;
 use uuid::Uuid;
 use crate::ack::CommandAck;
 use shared::models::operator::SafetyOverrideScope;
 /// One entry in the audit log. Variants map 1:1 to the AZ-681
 /// command kinds.
 #[derive(Debug, Clone, Serialize, PartialEq, Eq)]
 #[serde(tag = "kind", rename_all = "snake_case")]
 pub enum AuditEntry {
    BitDegradedAck {
        command_id: Uuid,
        timestamp: DateTime<Utc>,
        operator_id: Option<String>,
        report_id: Uuid,
        outcome: CommandAck,
    },
    SafetyOverride {
        command_id: Uuid,
        timestamp: DateTime<Utc>,
        operator_id: Option<String>,
        scope: SafetyOverrideScope,
        duration_secs: u32,
        outcome: CommandAck,
    },
 }
 /// Sink for audit entries. Composition root injects the concrete
 /// implementation; the default is [`TracingAuditSink`].
 #[async_trait]
 pub trait AuditSink: Send + Sync {
    async fn record(&self, entry: AuditEntry);
 }
 /// Default sink — emits a single `tracing::info!` per entry. The
 /// structured fields are picked up by any `tracing_subscriber` JSON
 /// layer the composition root configures.
 pub struct TracingAuditSink;
 impl TracingAuditSink {
    pub fn arc() -> Arc<dyn AuditSink> {
        Arc::new(Self)
    }
 }
 #[async_trait]
 impl AuditSink for TracingAuditSink {
    async fn record(&self, entry: AuditEntry) {
        match &entry {
            AuditEntry::BitDegradedAck {
                command_id,
                timestamp,
                operator_id,
                report_id,
                outcome,
            } => {
                tracing::info!(
                    audit = "bit_degraded_ack",
                    command_id = %command_id,
                    timestamp = %timestamp.to_rfc3339(),
                    operator_id = operator_id.as_deref().unwrap_or(""),
                    report_id = %report_id,
                    outcome = ?outcome,
                    "operator_bridge audit: bit_degraded_ack"
                );
            }
            AuditEntry::SafetyOverride {
                command_id,
                timestamp,
                operator_id,
                scope,
                duration_secs,
                outcome,
            } => {
                tracing::info!(
                    audit = "safety_override",
                    command_id = %command_id,
                    timestamp = %timestamp.to_rfc3339(),
                    operator_id = operator_id.as_deref().unwrap_or(""),
                    scope = scope.label(),
                    duration_secs = duration_secs,
                    outcome = ?outcome,
                    "operator_bridge audit: safety_override"
                );
            }
        }
    }
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    /// AC-4 sanity: an entry serialised to JSON contains no
    /// signature/session_token field. The entry struct itself has
    /// no such field, so this is a static guarantee — but we
    /// assert on the JSON shape to lock the wire contract.
    #[test]
    fn entry_json_has_no_signature_or_session_token() {
        // Arrange
        let entry = AuditEntry::SafetyOverride {
            command_id: Uuid::new_v4(),
            timestamp: Utc::now(),
            operator_id: Some("op-1".into()),
            scope: SafetyOverrideScope::BatteryRtl,
            duration_secs: 60,
            outcome: CommandAck::Ok,
        };
        // Act
        let json = serde_json::to_string(&entry).expect("serialises");
        // Assert
        assert!(!json.contains("signature"));
        assert!(!json.contains("session_token"));
        assert!(json.contains("battery_rtl"));
        assert!(json.contains("\"duration_secs\":60"));
    }
 }
@@ -0,0 +1,386 @@
 //! AZ-680 + AZ-681 — operator-command dispatcher.
 //!
 //! Sits between the validated-command boundary (AZ-678) and the
 //! downstream routers. Responsibilities:
 //!
 //! - Per-`command_id` idempotency (60 s TTL — AZ-680 AC-2).
 //! - POI-id validity + deadline checks for POI-bound commands
 //!   (AZ-680 AC-3 / AC-4).
 //! - BIT-report severity gate for `AcknowledgeBitDegraded`
 //!   (AZ-681 AC-2).
 //! - Routing — POI commands → `ScanCommandRouter`, BIT acks +
 //!   safety overrides → `MissionSafetyRouter`.
 //! - Audit logging for every safety-critical command
 //!   (AZ-681 AC-3 / AC-4).
 //!
 //! The dispatcher OWNS the registry / cache / audit sink and is
 //! constructed once by the composition root. It is cheap to clone
 //! (all internals are `Arc`s).
 use std::sync::Arc;
 use chrono::Utc;
 use serde::Deserialize;
 use uuid::Uuid;
 use shared::contracts::{BitReportSeverityLookup, MissionSafetyRouter, ScanCommandRouter};
 use shared::models::operator::{OperatorCommand, OperatorCommandKind, SafetyOverrideScope};
 use crate::ack::{ack_reasons, CommandAck};
 use crate::internal::audit::{AuditEntry, AuditSink, TracingAuditSink};
 use crate::internal::idempotency::IdempotencyCache;
 use crate::internal::poi_registry::SurfacedPoiRegistry;
 #[derive(Clone)]
 pub struct OperatorCommandDispatcher {
    pub(crate) registry: SurfacedPoiRegistry,
    cache: IdempotencyCache,
    audit: Arc<dyn AuditSink>,
    scan_router: Option<Arc<dyn ScanCommandRouter>>,
    safety_router: Option<Arc<dyn MissionSafetyRouter>>,
    bit_severity: Option<Arc<dyn BitReportSeverityLookup>>,
 }
 impl OperatorCommandDispatcher {
    pub fn builder() -> OperatorCommandDispatcherBuilder {
        OperatorCommandDispatcherBuilder::default()
    }
    /// Public test helper: peek into the idempotency cache. Used by
    /// the integration tests to assert AC-2 ("re-transmit returns
    /// cached ack").
    #[doc(hidden)]
    pub fn cache_len(&self) -> usize {
        self.cache.len()
    }
    /// AZ-680 / AZ-681 — dispatch one validated command. Returns the
    /// typed [`CommandAck`]. Idempotency is handled inside; callers
    /// just re-submit the same `command_id` on retransmit.
    pub async fn dispatch(&self, cmd: OperatorCommand) -> CommandAck {
        let cmd_id = cmd.command_id;
        self.cache
            .get_or_insert_with(cmd_id, || async move { self.dispatch_inner(cmd).await })
            .await
    }
    async fn dispatch_inner(&self, cmd: OperatorCommand) -> CommandAck {
        match cmd.kind {
            OperatorCommandKind::ConfirmPoi
            | OperatorCommandKind::DeclinePoi
            | OperatorCommandKind::StartTargetFollow => self.dispatch_poi_bound(cmd).await,
            OperatorCommandKind::ReleaseTargetFollow => self.dispatch_via_scan_router(cmd).await,
            OperatorCommandKind::AcknowledgeBitDegraded => self.dispatch_bit_ack(cmd).await,
            OperatorCommandKind::SafetyOverride => self.dispatch_safety_override(cmd).await,
            OperatorCommandKind::MissionAbort => self.dispatch_via_scan_router(cmd).await,
        }
    }
    /// POI-bound dispatch path: enforces `unknown_poi_id` (AC-3) +
    /// `expired` (AC-4) before forwarding to `scan_controller`.
    async fn dispatch_poi_bound(&self, cmd: OperatorCommand) -> CommandAck {
        let poi_id = match poi_id_from_payload(&cmd.payload) {
            Ok(id) => id,
            Err(_) => return CommandAck::error(ack_reasons::INVALID_PAYLOAD),
        };
        let Some(surfaced) = self.registry.get(poi_id) else {
            return CommandAck::error(ack_reasons::UNKNOWN_POI_ID);
        };
        if surfaced.deadline <= Utc::now() {
            return CommandAck::error(ack_reasons::EXPIRED);
        }
        self.dispatch_via_scan_router(cmd).await
    }
    async fn dispatch_via_scan_router(&self, cmd: OperatorCommand) -> CommandAck {
        let Some(router) = self.scan_router.as_ref() else {
            return CommandAck::error(ack_reasons::ROUTER_NOT_WIRED);
        };
        match router.route(cmd).await {
            Ok(()) => CommandAck::Ok,
            Err(e) => {
                tracing::warn!(error = %e, "scan router rejected operator command");
                CommandAck::error(ack_reasons::ROUTER_ERROR)
            }
        }
    }
    async fn dispatch_bit_ack(&self, cmd: OperatorCommand) -> CommandAck {
        let payload = match BitAckPayload::from_value(&cmd.payload) {
            Ok(p) => p,
            Err(_) => {
                let ack = CommandAck::error(ack_reasons::INVALID_PAYLOAD);
                self.audit_bit(&cmd, Uuid::nil(), &ack).await;
                return ack;
            }
        };
        let ack = self.evaluate_bit_ack(&cmd, &payload).await;
        self.audit_bit(&cmd, payload.report_id, &ack).await;
        ack
    }
    async fn evaluate_bit_ack(&self, cmd: &OperatorCommand, payload: &BitAckPayload) -> CommandAck {
        let Some(severity) = self.bit_severity.as_ref() else {
            return CommandAck::error(ack_reasons::ROUTER_NOT_WIRED);
        };
        match severity.is_acknowledgeable(payload.report_id).await {
            Some(true) => match self.safety_router.as_ref() {
                Some(router) => match router
                    .acknowledge_bit_degraded(payload.report_id, payload.operator_id.clone())
                    .await
                {
                    Ok(()) => CommandAck::Ok,
                    Err(e) => {
                        tracing::warn!(error = %e, "mission safety router rejected bit ack");
                        CommandAck::error(ack_reasons::ROUTER_ERROR)
                    }
                },
                None => CommandAck::error(ack_reasons::ROUTER_NOT_WIRED),
            },
            Some(false) => CommandAck::error(ack_reasons::CANNOT_ACKNOWLEDGE_FAIL),
            None => {
                tracing::warn!(
                    command_id = %cmd.command_id,
                    report_id = %payload.report_id,
                    "bit_degraded_ack: unknown report id"
                );
                CommandAck::error(ack_reasons::UNKNOWN_BIT_REPORT)
            }
        }
    }
    async fn dispatch_safety_override(&self, cmd: OperatorCommand) -> CommandAck {
        let payload = match SafetyOverridePayload::from_value(&cmd.payload) {
            Ok(p) => p,
            Err(_) => {
                let ack = CommandAck::error(ack_reasons::INVALID_PAYLOAD);
                self.audit_safety(&cmd, None, 0, &ack).await;
                return ack;
            }
        };
        let ack = self.apply_safety_override(&payload).await;
        self.audit_safety(&cmd, Some(payload.scope), payload.duration_secs, &ack)
            .await;
        ack
    }
    async fn apply_safety_override(&self, payload: &SafetyOverridePayload) -> CommandAck {
        let Some(router) = self.safety_router.as_ref() else {
            return CommandAck::error(ack_reasons::ROUTER_NOT_WIRED);
        };
        match router
            .apply_safety_override(
                payload.scope,
                payload.duration_secs,
                payload.operator_id.clone(),
                payload.rationale.clone(),
            )
            .await
        {
            Ok(()) => CommandAck::Ok,
            Err(e) => {
                tracing::warn!(error = %e, "mission safety router rejected safety override");
                CommandAck::error(ack_reasons::ROUTER_ERROR)
            }
        }
    }
    async fn audit_bit(&self, cmd: &OperatorCommand, report_id: Uuid, outcome: &CommandAck) {
        self.audit
            .record(AuditEntry::BitDegradedAck {
                command_id: cmd.command_id,
                timestamp: Utc::now(),
                operator_id: cmd
                    .payload
                    .get("operator_id")
                    .and_then(|v| v.as_str())
                    .map(String::from),
                report_id,
                outcome: outcome.clone(),
            })
            .await;
    }
    async fn audit_safety(
        &self,
        cmd: &OperatorCommand,
        scope: Option<SafetyOverrideScope>,
        duration_secs: u32,
        outcome: &CommandAck,
    ) {
        self.audit
            .record(AuditEntry::SafetyOverride {
                command_id: cmd.command_id,
                timestamp: Utc::now(),
                operator_id: cmd
                    .payload
                    .get("operator_id")
                    .and_then(|v| v.as_str())
                    .map(String::from),
                scope: scope.unwrap_or(SafetyOverrideScope::BatteryRtl),
                duration_secs,
                outcome: outcome.clone(),
            })
            .await;
    }
 }
 // ============================================================================
 // Builder
 // ============================================================================
 #[derive(Default)]
 pub struct OperatorCommandDispatcherBuilder {
    registry: Option<SurfacedPoiRegistry>,
    cache: Option<IdempotencyCache>,
    audit: Option<Arc<dyn AuditSink>>,
    scan_router: Option<Arc<dyn ScanCommandRouter>>,
    safety_router: Option<Arc<dyn MissionSafetyRouter>>,
    bit_severity: Option<Arc<dyn BitReportSeverityLookup>>,
 }
 impl OperatorCommandDispatcherBuilder {
    pub fn registry(mut self, r: SurfacedPoiRegistry) -> Self {
        self.registry = Some(r);
        self
    }
    pub fn idempotency_cache(mut self, c: IdempotencyCache) -> Self {
        self.cache = Some(c);
        self
    }
    pub fn audit_sink(mut self, s: Arc<dyn AuditSink>) -> Self {
        self.audit = Some(s);
        self
    }
    pub fn scan_router(mut self, r: Arc<dyn ScanCommandRouter>) -> Self {
        self.scan_router = Some(r);
        self
    }
    pub fn safety_router(mut self, r: Arc<dyn MissionSafetyRouter>) -> Self {
        self.safety_router = Some(r);
        self
    }
    pub fn bit_severity(mut self, s: Arc<dyn BitReportSeverityLookup>) -> Self {
        self.bit_severity = Some(s);
        self
    }
    pub fn build(self) -> OperatorCommandDispatcher {
        OperatorCommandDispatcher {
            registry: self.registry.unwrap_or_default(),
            cache: self
                .cache
                .unwrap_or_else(IdempotencyCache::with_default_ttl),
            audit: self.audit.unwrap_or_else(TracingAuditSink::arc),
            scan_router: self.scan_router,
            safety_router: self.safety_router,
            bit_severity: self.bit_severity,
        }
    }
 }
 // ============================================================================
 // Payload extraction
 // ============================================================================
 /// Extract `poi_id` from a POI-bound command payload.
 ///
 /// Wire shape: `{ "poi_id": "<uuid>" }`. Anything else is a hard
 /// `invalid_payload` error — the auth layer guarantees the payload
 /// bytes weren't tampered with, but the operator UI might still send
 /// the wrong shape on a build-skew between client and autopilot.
 fn poi_id_from_payload(payload: &serde_json::Value) -> Result<Uuid, ()> {
    let v = payload.get("poi_id").and_then(|v| v.as_str()).ok_or(())?;
    Uuid::parse_str(v).map_err(|_| ())
 }
 #[derive(Debug, Deserialize)]
 struct BitAckPayload {
    report_id: Uuid,
    #[serde(default)]
    operator_id: Option<String>,
 }
 impl BitAckPayload {
    fn from_value(v: &serde_json::Value) -> Result<Self, serde_json::Error> {
        serde_json::from_value(v.clone())
    }
 }
 #[derive(Debug, Deserialize)]
 struct SafetyOverridePayload {
    scope: SafetyOverrideScope,
    duration_secs: u32,
    operator_id: String,
    #[serde(default)]
    rationale: String,
 }
 impl SafetyOverridePayload {
    fn from_value(v: &serde_json::Value) -> Result<Self, serde_json::Error> {
        serde_json::from_value(v.clone())
    }
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    use serde_json::json;
    #[test]
    fn poi_id_extracts_uuid() {
        // Arrange
        let id = Uuid::new_v4();
        let v = json!({ "poi_id": id.to_string() });
        // Act + Assert
        assert_eq!(poi_id_from_payload(&v).unwrap(), id);
    }
    #[test]
    fn poi_id_missing_is_err() {
        // Arrange
        let v = json!({ "other": "x" });
        // Act + Assert
        assert!(poi_id_from_payload(&v).is_err());
    }
    #[test]
    fn bit_ack_payload_round_trip() {
        // Arrange
        let id = Uuid::new_v4();
        let v = json!({ "report_id": id.to_string(), "operator_id": "op1" });
        // Act
        let p = BitAckPayload::from_value(&v).expect("parse");
        // Assert
        assert_eq!(p.report_id, id);
        assert_eq!(p.operator_id, Some("op1".to_string()));
    }
    #[test]
    fn safety_override_payload_round_trip() {
        // Arrange
        let v = json!({
            "scope": "battery_rtl",
            "duration_secs": 60,
            "operator_id": "op1",
            "rationale": "post-mission RTL too aggressive"
        });
        // Act
        let p = SafetyOverridePayload::from_value(&v).expect("parse");
        // Assert
        assert_eq!(p.scope, SafetyOverrideScope::BatteryRtl);
        assert_eq!(p.duration_secs, 60);
        assert_eq!(p.operator_id, "op1");
    }
 }
@@ -0,0 +1,173 @@
 //! AZ-680 — per-`command_id` idempotency cache.
 //!
 //! The spec (AC-2): "Re-transmit returns cached ack". A 60 s sliding
 //! window over `command_id → CommandAck` so the operator UI can
 //! safely retransmit on a flaky modem without causing the autopilot
 //! to double-dispatch.
 //!
 //! Design notes:
 //!
 //! - Lazy eviction. `get_or_insert_with` purges expired entries before
 //!   inserting. We do not run a background sweeper task — at the
 //!   command rate of ≤5 confirms/min (operator workflow), the cache
 //!   stays small and per-call eviction is cheap.
 //! - Returns the *cached* ack on hit; on miss, runs the supplied
 //!   future, caches its result, returns it. The future is NOT spawned
 //!   — the caller awaits it.
 //! - Cache key is the full `Uuid`; the operator UI generates fresh
 //!   `command_id`s per logical command, so collisions imply a true
 //!   retransmit and we want to honour that.
 use std::collections::HashMap;
 use std::future::Future;
 use std::sync::Arc;
 use std::time::{Duration, Instant};
 use parking_lot::Mutex;
 use uuid::Uuid;
 use crate::ack::CommandAck;
 /// Default TTL per AZ-680 spec.
 pub const DEFAULT_IDEMPOTENCY_TTL: Duration = Duration::from_secs(60);
 #[derive(Debug, Clone)]
 struct Entry {
    ack: CommandAck,
    cached_at: Instant,
 }
 /// Bounded-by-TTL idempotency cache. Cheap to `clone` (internals are
 /// an `Arc<Mutex<_>>`).
 #[derive(Clone)]
 pub struct IdempotencyCache {
    ttl: Duration,
    inner: Arc<Mutex<HashMap<Uuid, Entry>>>,
 }
 impl IdempotencyCache {
    pub fn new(ttl: Duration) -> Self {
        Self {
            ttl,
            inner: Arc::new(Mutex::new(HashMap::new())),
        }
    }
    pub fn with_default_ttl() -> Self {
        Self::new(DEFAULT_IDEMPOTENCY_TTL)
    }
    /// Returns the cached ack if `command_id` is present and not
    /// expired; otherwise runs `produce`, caches its result, and
    /// returns it. Concurrent calls with the same `command_id` MAY
    /// each execute `produce` once — that is acceptable here because
    /// the downstream routers themselves are idempotent for the same
    /// validated payload (the router-level side effect is the same
    /// across retries; the registry/queue lookups deduplicate POI
    /// state). The cache's primary role is to short-circuit
    /// re-transmits that arrive seconds later, not to serialise
    /// concurrent dispatchers of the same id.
    pub async fn get_or_insert_with<F, Fut>(&self, command_id: Uuid, produce: F) -> CommandAck
    where
        F: FnOnce() -> Fut,
        Fut: Future<Output = CommandAck>,
    {
        if let Some(cached) = self.get(command_id) {
            return cached;
        }
        let ack = produce().await;
        self.insert(command_id, ack.clone());
        ack
    }
    /// Snapshot lookup — also evicts expired entries opportunistically.
    pub fn get(&self, command_id: Uuid) -> Option<CommandAck> {
        let mut guard = self.inner.lock();
        self.evict_expired(&mut guard);
        guard.get(&command_id).map(|e| e.ack.clone())
    }
    fn insert(&self, command_id: Uuid, ack: CommandAck) {
        let mut guard = self.inner.lock();
        self.evict_expired(&mut guard);
        guard.insert(
            command_id,
            Entry {
                ack,
                cached_at: Instant::now(),
            },
        );
    }
    fn evict_expired(&self, guard: &mut HashMap<Uuid, Entry>) {
        let now = Instant::now();
        guard.retain(|_, e| now.duration_since(e.cached_at) < self.ttl);
    }
    pub fn len(&self) -> usize {
        let mut guard = self.inner.lock();
        self.evict_expired(&mut guard);
        guard.len()
    }
    pub fn is_empty(&self) -> bool {
        self.len() == 0
    }
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    use std::sync::atomic::{AtomicU32, Ordering};
    #[tokio::test]
    async fn miss_then_hit_runs_once() {
        // Arrange
        let cache = IdempotencyCache::with_default_ttl();
        let id = Uuid::new_v4();
        let count = AtomicU32::new(0);
        // Act
        let _ = cache
            .get_or_insert_with(id, || async {
                count.fetch_add(1, Ordering::SeqCst);
                CommandAck::Ok
            })
            .await;
        let _ = cache
            .get_or_insert_with(id, || async {
                count.fetch_add(1, Ordering::SeqCst);
                CommandAck::Ok
            })
            .await;
        // Assert
        assert_eq!(count.load(Ordering::SeqCst), 1);
    }
    #[tokio::test]
    async fn ttl_expiry_re_runs_producer() {
        // Arrange — short TTL to keep the test fast.
        let cache = IdempotencyCache::new(Duration::from_millis(20));
        let id = Uuid::new_v4();
        let count = AtomicU32::new(0);
        // Act
        let _ = cache
            .get_or_insert_with(id, || async {
                count.fetch_add(1, Ordering::SeqCst);
                CommandAck::Ok
            })
            .await;
        tokio::time::sleep(Duration::from_millis(40)).await;
        let _ = cache
            .get_or_insert_with(id, || async {
                count.fetch_add(1, Ordering::SeqCst);
                CommandAck::Ok
            })
            .await;
        // Assert
        assert_eq!(count.load(Ordering::SeqCst), 2);
    }
 }
@@ -1,4 +1,8 @@
 //! Internal modules for `operator_bridge`. Not part of the public API.
 pub mod audit;
 pub mod auth;
 pub mod dispatcher;
 pub mod idempotency;
 pub mod poi_registry;
 pub mod poi_surface;
@@ -0,0 +1,128 @@
 //! AZ-680 — currently-surfaced POI registry.
 //!
 //! Tracks the subset of POIs that have been pushed to the operator UI
 //! and have not yet been dequeued. The dispatcher consults this
 //! registry to reject:
 //!
 //! - `Confirm` / `Decline` / `StartTargetFollow` for unknown
 //!   `poi_id`s (AC-3 → `unknown_poi_id`).
 //! - Commands whose POI deadline has elapsed (AC-4 → `expired`).
 //!
 //! The registry is intentionally a plain `HashMap` behind a
 //! [`parking_lot::Mutex`] — the dispatcher's lock window is short
 //! (one O(1) lookup + one O(1) remove). A `RwLock` would not buy us
 //! anything because the dispatcher writes on every confirm/decline.
 use std::sync::Arc;
 use chrono::{DateTime, Utc};
 use parking_lot::Mutex;
 use std::collections::HashMap;
 use uuid::Uuid;
 use shared::models::poi::Poi;
 /// Snapshot of the POI fields the dispatcher needs to enforce
 /// validity + deadline checks without holding a reference to the
 /// full [`Poi`] struct.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct SurfacedPoi {
    pub poi_id: Uuid,
    pub mgrs: String,
    pub class_group: String,
    pub deadline: DateTime<Utc>,
 }
 impl From<&Poi> for SurfacedPoi {
    fn from(poi: &Poi) -> Self {
        Self {
            poi_id: poi.id,
            mgrs: poi.mgrs.clone(),
            class_group: poi.class_group.clone(),
            deadline: poi.deadline,
        }
    }
 }
 /// In-memory registry of surfaced-but-not-dequeued POIs. Cheap to
 /// `clone` — internals are an `Arc<Mutex<_>>`.
 #[derive(Default, Clone)]
 pub struct SurfacedPoiRegistry {
    inner: Arc<Mutex<HashMap<Uuid, SurfacedPoi>>>,
 }
 impl SurfacedPoiRegistry {
    pub fn new() -> Self {
        Self::default()
    }
    /// Record a surfaced POI. Overwrites any prior entry with the
    /// same id (the POI was re-surfaced after a rotation).
    pub fn record(&self, poi: SurfacedPoi) {
        self.inner.lock().insert(poi.poi_id, poi);
    }
    /// Remove a POI from the surfaced set. Called when the POI is
    /// dequeued (rotated, aged out, or operator-decided).
    pub fn forget(&self, poi_id: Uuid) {
        self.inner.lock().remove(&poi_id);
    }
    /// Look up a surfaced POI. Returns `None` if the id has never
    /// been surfaced or has already been dequeued.
    pub fn get(&self, poi_id: Uuid) -> Option<SurfacedPoi> {
        self.inner.lock().get(&poi_id).cloned()
    }
    pub fn len(&self) -> usize {
        self.inner.lock().len()
    }
    pub fn is_empty(&self) -> bool {
        self.len() == 0
    }
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    use chrono::Duration;
    fn surfaced(deadline_secs: i64) -> SurfacedPoi {
        SurfacedPoi {
            poi_id: Uuid::new_v4(),
            mgrs: "33UWP05".into(),
            class_group: "vehicle".into(),
            deadline: Utc::now() + Duration::seconds(deadline_secs),
        }
    }
    #[test]
    fn record_then_get_returns_clone() {
        // Arrange
        let r = SurfacedPoiRegistry::new();
        let p = surfaced(120);
        r.record(p.clone());
        // Act
        let got = r.get(p.poi_id).expect("must be present");
        // Assert
        assert_eq!(got, p);
    }
    #[test]
    fn forget_removes_entry() {
        // Arrange
        let r = SurfacedPoiRegistry::new();
        let p = surfaced(120);
        r.record(p.clone());
        // Act
        r.forget(p.poi_id);
        // Assert
        assert!(r.get(p.poi_id).is_none());
        assert!(r.is_empty());
    }
 }
@@ -1,4 +1,5 @@
-//! `operator_bridge` — POI surfacing + operator command authentication.
+//! `operator_bridge` — POI surfacing + operator command authentication
 //! + dispatch.
 //!
 //! Real implementation in this batch:
 //! - **AZ-678** `internal::auth::HmacOperatorValidator` — HMAC-SHA256
@@ -7,11 +8,15 @@
 //!   counters; sliding-window red-health gate.
 //! - **AZ-679** `internal::poi_surface::PoiSurfaceMapper` — wire-format
 //!   POI events + `PoiDequeued` events pushed through `TelemetrySink`.
-//!
+//! - **AZ-680** `internal::dispatcher::OperatorCommandDispatcher` —
-//! Real implementation lands in:
+//!   POI-bound dispatch path, per-`command_id` idempotency cache,
-//! - AZ-680 `operator_bridge_command_dispatch`
+//!   unknown-POI + expired-deadline gates.
-//! - AZ-681 `operator_bridge_safety_and_bit_ack`
+//! - **AZ-681** `internal::dispatcher::OperatorCommandDispatcher` —
 //!   BIT-degraded ack severity gate + `SafetyOverride` forwarding
 //!   into `mission_executor` via `MissionSafetyRouter`; structured
 //!   audit log entry per safety command.
 pub mod ack;
 pub mod internal;
 use std::sync::Arc;
@@ -20,7 +25,10 @@ use async_trait::async_trait;
 use serde::{Deserialize, Serialize};
 use tokio::sync::mpsc;
-use shared::contracts::{OperatorCommandSink, TelemetrySink};
+use shared::contracts::{
    BitReportSeverityLookup, MissionSafetyRouter, OperatorCommandSink, ScanCommandRouter,
    TelemetrySink,
 };
 use shared::error::{AutopilotError, Result};
 use shared::health::{ComponentHealth, HealthLevel};
 use shared::models::mission::Coordinate;
@@ -28,9 +36,16 @@ use shared::models::operator::OperatorCommand;
 use shared::models::operator_event::{DequeueReason, PhotoMetadata};
 use shared::models::poi::Poi;
 pub use crate::ack::{ack_reasons, CommandAck};
 pub use crate::internal::audit::{AuditEntry, AuditSink, TracingAuditSink};
 pub use crate::internal::auth::{
    AuthCounters, HmacOperatorValidator, HmacValidatorConfig, REJECTION_REASONS,
 };
 pub use crate::internal::dispatcher::{
    OperatorCommandDispatcher, OperatorCommandDispatcherBuilder,
 };
 pub use crate::internal::idempotency::{IdempotencyCache, DEFAULT_IDEMPOTENCY_TTL};
 pub use crate::internal::poi_registry::{SurfacedPoi, SurfacedPoiRegistry};
 pub use crate::internal::poi_surface::{PoiSurfaceMapper, PoiSurfaceMetrics};
 const NAME: &str = "operator_bridge";
@@ -71,6 +86,20 @@ pub struct OperatorBridge {
    /// `poi_mapper` so legacy callers continue to compile until the
    /// composition root wires it in.
    validator: Option<Arc<HmacOperatorValidator>>,
    /// AZ-680 — currently-surfaced POI registry. Shared between the
    /// `surface_poi` / `emit_poi_dequeued` write-side and the
    /// dispatcher's POI-id validity check.
    poi_registry: SurfacedPoiRegistry,
    /// AZ-680 / AZ-681 — command dispatcher. Optional until both the
    /// scan + safety routers are wired; without it `dispatch` returns
    /// `router_not_wired`.
    dispatcher: Option<Arc<OperatorCommandDispatcher>>,
    /// Builder-only accumulators for the dispatcher's routers + sink.
    /// Consumed in [`OperatorBridge::with_dispatcher`].
    scan_router: Option<Arc<dyn ScanCommandRouter>>,
    safety_router: Option<Arc<dyn MissionSafetyRouter>>,
    bit_severity: Option<Arc<dyn BitReportSeverityLookup>>,
    audit_sink: Option<Arc<dyn AuditSink>>,
 }
 impl OperatorBridge {
@@ -84,6 +113,12 @@ impl OperatorBridge {
            target_follow_rx: Some(tf_rx),
            poi_mapper: None,
            validator: None,
            poi_registry: SurfacedPoiRegistry::new(),
            dispatcher: None,
            scan_router: None,
            safety_router: None,
            bit_severity: None,
            audit_sink: None,
        }
    }
@@ -97,12 +132,63 @@ impl OperatorBridge {
        self
    }
    /// AZ-680 — wire `scan_controller`'s [`ScanCommandRouter`] impl.
    pub fn with_scan_router(mut self, router: Arc<dyn ScanCommandRouter>) -> Self {
        self.scan_router = Some(router);
        self
    }
    /// AZ-681 — wire `mission_executor`'s [`MissionSafetyRouter`] impl.
    pub fn with_safety_router(mut self, router: Arc<dyn MissionSafetyRouter>) -> Self {
        self.safety_router = Some(router);
        self
    }
    /// AZ-681 — wire `mission_executor`'s
    /// [`BitReportSeverityLookup`] impl.
    pub fn with_bit_severity_lookup(mut self, lookup: Arc<dyn BitReportSeverityLookup>) -> Self {
        self.bit_severity = Some(lookup);
        self
    }
    /// AZ-681 — override the default tracing audit sink. Used by
    /// integration tests; production wires the default.
    pub fn with_audit_sink(mut self, sink: Arc<dyn AuditSink>) -> Self {
        self.audit_sink = Some(sink);
        self
    }
    /// AZ-680 / AZ-681 — finalise the dispatcher. Returns `self` so
    /// the call can sit at the end of the builder chain. Idempotent
    /// (calling twice rebuilds the dispatcher with the most-recent
    /// wiring) — this matters because the composition root sometimes
    /// re-runs the wiring sequence on subsystem restart.
    pub fn with_dispatcher(mut self) -> Self {
        let mut builder = OperatorCommandDispatcher::builder().registry(self.poi_registry.clone());
        if let Some(r) = self.scan_router.clone() {
            builder = builder.scan_router(r);
        }
        if let Some(r) = self.safety_router.clone() {
            builder = builder.safety_router(r);
        }
        if let Some(s) = self.bit_severity.clone() {
            builder = builder.bit_severity(s);
        }
        if let Some(s) = self.audit_sink.clone() {
            builder = builder.audit_sink(s);
        }
        self.dispatcher = Some(Arc::new(builder.build()));
        self
    }
    pub fn handle(&self) -> OperatorBridgeHandle {
        OperatorBridgeHandle {
            middle_waypoint_tx: self.middle_waypoint_tx.clone(),
            target_follow_tx: self.target_follow_tx.clone(),
            poi_mapper: self.poi_mapper.clone(),
            validator: self.validator.clone(),
            poi_registry: self.poi_registry.clone(),
            dispatcher: self.dispatcher.clone(),
        }
    }
@@ -113,6 +199,15 @@ impl OperatorBridge {
    pub fn take_target_follow_receiver(&mut self) -> Option<mpsc::Receiver<TargetFollowEvent>> {
        self.target_follow_rx.take()
    }
    /// AZ-680 — clone of the surfaced-POI registry. Exposed so the
    /// composition root can pre-seed entries on subsystem restart
    /// and so integration tests can register POIs without spinning
    /// up a TelemetrySink. The registry is also wired into the
    /// dispatcher.
    pub fn surfaced_registry(&self) -> SurfacedPoiRegistry {
        self.poi_registry.clone()
    }
 }
 #[derive(Clone)]
@@ -123,19 +218,33 @@ pub struct OperatorBridgeHandle {
    target_follow_tx: mpsc::Sender<TargetFollowEvent>,
    poi_mapper: Option<Arc<PoiSurfaceMapper>>,
    validator: Option<Arc<HmacOperatorValidator>>,
    /// AZ-680 — registry of surfaced-but-not-dequeued POIs. The
    /// dispatcher consults this for unknown-id + deadline checks.
    poi_registry: SurfacedPoiRegistry,
    dispatcher: Option<Arc<OperatorCommandDispatcher>>,
 }
 impl OperatorBridgeHandle {
-    /// AZ-679 — surface a POI to the operator and await the decision.
+    /// AZ-679 + AZ-680 — surface a POI to the operator. Records the
-    /// Today returns `NotImplemented` (the decision loop is AZ-680);
+    /// POI in the dispatcher's validity registry so subsequent
-    /// the surface event itself IS pushed (via the configured
+    /// confirm/decline/start-follow commands resolve. The event itself
-    /// `TelemetrySink`), so the operator UI receives it.
+    /// is pushed via the configured `TelemetrySink`.
    ///
    /// Returns `OperatorDecision::Confirmed`/`Declined`/... is NOT
    /// the responsibility of this method any more — the decision
    /// arrives asynchronously via `dispatch` and the operator UI
    /// applies it. The legacy `Result<OperatorDecision>` shape is
    /// retained for callers that have not yet migrated; today the
    /// method returns `NotImplemented` after the surface emits, and
    /// `scan_controller` should use the non-decision-returning path
    /// in `surface_poi_with_photo` instead.
    pub async fn surface_poi(&self, poi: Poi) -> Result<OperatorDecision> {
        match &self.poi_mapper {
            Some(mapper) => {
                self.poi_registry.record(SurfacedPoi::from(&poi));
                mapper.surface(&poi, None).await?;
                Err(AutopilotError::NotImplemented(
-                    "operator_bridge::surface_poi → decision loop (AZ-680)",
+                    "operator_bridge::surface_poi → decision is async via dispatch (AZ-680)",
                ))
            }
            None => Err(AutopilotError::NotImplemented(
@@ -144,8 +253,9 @@ impl OperatorBridgeHandle {
        }
    }
-    /// AZ-679 — surface a POI together with photo metadata (preferred
+    /// AZ-679 + AZ-680 — surface a POI together with photo metadata
-    /// path when the source detection carries an ROI snapshot).
+    /// (preferred path when the source detection carries an ROI
    /// snapshot). Records the POI in the dispatcher's registry.
    pub async fn surface_poi_with_photo(
        &self,
        poi: &Poi,
@@ -154,18 +264,39 @@ impl OperatorBridgeHandle {
        let mapper = self.poi_mapper.as_ref().ok_or_else(|| {
            AutopilotError::Internal("surface_poi_with_photo: telemetry sink not wired".into())
        })?;
        self.poi_registry.record(SurfacedPoi::from(poi));
        mapper.surface(poi, Some(photo_metadata)).await.map(|_| ())
    }
-    /// AZ-679 — emit a `PoiDequeued` event (rotation / age-out /
+    /// AZ-679 + AZ-680 — emit a `PoiDequeued` event (rotation /
-    /// completion). Called by `scan_controller` through the bridge.
+    /// age-out / completion). Removes the POI from the dispatcher's
    /// registry so any further confirm/decline for the same id
    /// resolves to `unknown_poi_id`.
    pub async fn emit_poi_dequeued(&self, poi_id: uuid::Uuid, reason: DequeueReason) -> Result<()> {
        let mapper = self.poi_mapper.as_ref().ok_or_else(|| {
            AutopilotError::Internal("emit_poi_dequeued: telemetry sink not wired".into())
        })?;
        self.poi_registry.forget(poi_id);
        mapper.emit_dequeued(poi_id, reason).await
    }
    /// AZ-680 / AZ-681 — dispatch a validated operator command and
    /// return the typed [`CommandAck`]. The dispatcher must be wired
    /// via `OperatorBridge::with_dispatcher`; without it every
    /// command returns `router_not_wired`.
    pub async fn dispatch_command(&self, cmd: OperatorCommand) -> CommandAck {
        match &self.dispatcher {
            Some(d) => d.dispatch(cmd).await,
            None => CommandAck::error(ack_reasons::ROUTER_NOT_WIRED),
        }
    }
    /// Test/observability hook: peek the surfaced-POI registry.
    #[doc(hidden)]
    pub fn surfaced_poi_count(&self) -> usize {
        self.poi_registry.len()
    }
    pub fn poi_metrics(&self) -> Option<PoiSurfaceMetrics> {
        self.poi_mapper.as_ref().map(|m| m.metrics())
    }
@@ -197,12 +328,25 @@ impl OperatorBridgeHandle {
    }
 }
 /// AZ-680 — wire the bridge into the `OperatorCommandSink` trait so
 /// `telemetry_stream`'s downlink can forward validated commands
 /// uniformly. The trait surface is binary (`Result<()>`); the typed
 /// [`CommandAck`] surfaces through [`OperatorBridgeHandle::dispatch_command`]
 /// for callers that need the rejection reason. The trait impl maps:
 ///
 /// - `CommandAck::Ok` → `Ok(())`
 /// - `CommandAck::Error { reason }` → `Err(AutopilotError::Validation(reason))`
 ///
 /// This keeps the trait minimal while still propagating actionable
 /// rejection reasons to downstream consumers that only see the
 /// trait surface.
 #[async_trait]
 impl OperatorCommandSink for OperatorBridgeHandle {
-    async fn dispatch(&self, _command: OperatorCommand) -> Result<()> {
+    async fn dispatch(&self, command: OperatorCommand) -> Result<()> {
-        Err(AutopilotError::NotImplemented(
+        match self.dispatch_command(command).await {
-            "operator_bridge::dispatch (AZ-680)",
+            CommandAck::Ok => Ok(()),
-        ))
+            CommandAck::Error { reason } => Err(AutopilotError::Validation(reason)),
        }
    }
 }
@@ -0,0 +1,439 @@
 //! AZ-680 + AZ-681 — operator-command dispatcher acceptance tests.
 //!
 //! These tests exercise the dispatcher through the public
 //! `OperatorBridgeHandle::dispatch_command` surface so the wiring
 //! between the surfaced-POI registry, the idempotency cache, the
 //! scan router, the safety router, the BIT severity lookup, and the
 //! audit sink is covered end-to-end.
 use std::sync::Arc;
 use std::sync::Mutex as StdMutex;
 use async_trait::async_trait;
 use chrono::{Duration as ChronoDuration, Utc};
 use parking_lot::Mutex;
 use serde_json::json;
 use uuid::Uuid;
 use operator_bridge::{
    ack_reasons, AuditEntry, AuditSink, CommandAck, OperatorBridge, SurfacedPoi,
 };
 use shared::contracts::{BitReportSeverityLookup, MissionSafetyRouter, ScanCommandRouter};
 use shared::error::Result;
 use shared::models::operator::{OperatorCommand, OperatorCommandKind, SafetyOverrideScope};
 // ============================================================================
 // Test doubles
 // ============================================================================
 #[derive(Default)]
 struct RecordingScanRouter {
    calls: StdMutex<Vec<OperatorCommand>>,
 }
 #[async_trait]
 impl ScanCommandRouter for RecordingScanRouter {
    async fn route(&self, command: OperatorCommand) -> Result<()> {
        self.calls.lock().unwrap().push(command);
        Ok(())
    }
 }
 #[derive(Default)]
 struct RecordingSafetyRouter {
    bit_acks: StdMutex<Vec<(Uuid, Option<String>)>>,
    overrides: StdMutex<Vec<(SafetyOverrideScope, u32, String, String)>>,
 }
 #[async_trait]
 impl MissionSafetyRouter for RecordingSafetyRouter {
    async fn acknowledge_bit_degraded(
        &self,
        report_id: Uuid,
        operator_id: Option<String>,
    ) -> Result<()> {
        self.bit_acks.lock().unwrap().push((report_id, operator_id));
        Ok(())
    }
    async fn apply_safety_override(
        &self,
        scope: SafetyOverrideScope,
        duration_secs: u32,
        operator_id: String,
        rationale: String,
    ) -> Result<()> {
        self.overrides
            .lock()
            .unwrap()
            .push((scope, duration_secs, operator_id, rationale));
        Ok(())
    }
 }
 /// Severity lookup that returns whatever is registered for each id.
 /// `Some(true)` for acknowledgeable (Degraded), `Some(false)` for
 /// Fail, `None` for unknown.
 #[derive(Default)]
 struct StubBitSeverity {
    inner: StdMutex<std::collections::HashMap<Uuid, bool>>,
 }
 impl StubBitSeverity {
    fn set(&self, report_id: Uuid, acknowledgeable: bool) {
        self.inner
            .lock()
            .unwrap()
            .insert(report_id, acknowledgeable);
    }
 }
 #[async_trait]
 impl BitReportSeverityLookup for StubBitSeverity {
    async fn is_acknowledgeable(&self, report_id: Uuid) -> Option<bool> {
        self.inner.lock().unwrap().get(&report_id).copied()
    }
 }
 #[derive(Default, Clone)]
 struct RecordingAuditSink {
    entries: Arc<Mutex<Vec<AuditEntry>>>,
 }
 #[async_trait]
 impl AuditSink for RecordingAuditSink {
    async fn record(&self, entry: AuditEntry) {
        self.entries.lock().push(entry);
    }
 }
 // ============================================================================
 // Helpers
 // ============================================================================
 fn cmd(kind: OperatorCommandKind, payload: serde_json::Value) -> OperatorCommand {
    OperatorCommand {
        command_id: Uuid::new_v4(),
        session_token: "session".to_string(),
        sequence_number: 1,
        issued_at_wallclock: Utc::now(),
        kind,
        payload,
        signature: vec![],
    }
 }
 fn surfaced(deadline_secs: i64) -> SurfacedPoi {
    SurfacedPoi {
        poi_id: Uuid::new_v4(),
        mgrs: "33UWP05".into(),
        class_group: "vehicle".into(),
        deadline: Utc::now() + ChronoDuration::seconds(deadline_secs),
    }
 }
 struct Harness {
    bridge: OperatorBridge,
    scan: Arc<RecordingScanRouter>,
    safety: Arc<RecordingSafetyRouter>,
    severity: Arc<StubBitSeverity>,
    audit: RecordingAuditSink,
 }
 fn harness() -> Harness {
    let scan = Arc::new(RecordingScanRouter::default());
    let safety = Arc::new(RecordingSafetyRouter::default());
    let severity = Arc::new(StubBitSeverity::default());
    let audit = RecordingAuditSink::default();
    let bridge = OperatorBridge::new(8)
        .with_scan_router(scan.clone() as Arc<dyn ScanCommandRouter>)
        .with_safety_router(safety.clone() as Arc<dyn MissionSafetyRouter>)
        .with_bit_severity_lookup(severity.clone() as Arc<dyn BitReportSeverityLookup>)
        .with_audit_sink(Arc::new(audit.clone()) as Arc<dyn AuditSink>)
        .with_dispatcher();
    Harness {
        bridge,
        scan,
        safety,
        severity,
        audit,
    }
 }
 // ============================================================================
 // AZ-680 ACs
 // ============================================================================
 /// AZ-680 AC-1 — Confirm forwards target hint.
 #[tokio::test]
 async fn az680_ac1_confirm_forwards_to_scan_router() {
    // Arrange
    let h = harness();
    let handle = h.bridge.handle();
    let surfaced = surfaced(120);
    h.bridge.surfaced_registry().record(surfaced.clone());
    // Act
    let ack = handle
        .dispatch_command(cmd(
            OperatorCommandKind::ConfirmPoi,
            json!({ "poi_id": surfaced.poi_id.to_string() }),
        ))
        .await;
    // Assert
    assert_eq!(ack, CommandAck::Ok);
    let calls = h.scan.calls.lock().unwrap();
    assert_eq!(calls.len(), 1, "scan_router::route called exactly once");
    assert!(matches!(calls[0].kind, OperatorCommandKind::ConfirmPoi));
 }
 /// AZ-680 AC-2 — Re-transmit returns cached ack.
 #[tokio::test]
 async fn az680_ac2_retransmit_returns_cached_ack() {
    // Arrange
    let h = harness();
    let handle = h.bridge.handle();
    let surfaced = surfaced(120);
    h.bridge.surfaced_registry().record(surfaced.clone());
    let command = cmd(
        OperatorCommandKind::ConfirmPoi,
        json!({ "poi_id": surfaced.poi_id.to_string() }),
    );
    // Act — same command_id dispatched twice
    let ack1 = handle.dispatch_command(command.clone()).await;
    let ack2 = handle.dispatch_command(command.clone()).await;
    // Assert
    assert_eq!(ack1, CommandAck::Ok);
    assert_eq!(ack2, CommandAck::Ok);
    let calls = h.scan.calls.lock().unwrap();
    assert_eq!(
        calls.len(),
        1,
        "scan_router::route must be invoked exactly once across retransmits"
    );
 }
 /// AZ-680 AC-3 — Unknown POI id rejected.
 #[tokio::test]
 async fn az680_ac3_unknown_poi_id_rejected() {
    // Arrange
    let h = harness();
    let handle = h.bridge.handle();
    // Act — POI id never surfaced
    let ack = handle
        .dispatch_command(cmd(
            OperatorCommandKind::ConfirmPoi,
            json!({ "poi_id": Uuid::new_v4().to_string() }),
        ))
        .await;
    // Assert
    assert_eq!(ack.reason(), Some(ack_reasons::UNKNOWN_POI_ID));
    assert!(
        h.scan.calls.lock().unwrap().is_empty(),
        "scan_router must not be invoked"
    );
 }
 /// AZ-680 AC-4 — Expired POI rejected.
 #[tokio::test]
 async fn az680_ac4_expired_poi_rejected() {
    // Arrange — surface a POI whose deadline has already passed.
    let h = harness();
    let handle = h.bridge.handle();
    let expired = SurfacedPoi {
        deadline: Utc::now() - ChronoDuration::seconds(1),
        ..surfaced(0)
    };
    h.bridge.surfaced_registry().record(expired.clone());
    // Act
    let ack = handle
        .dispatch_command(cmd(
            OperatorCommandKind::ConfirmPoi,
            json!({ "poi_id": expired.poi_id.to_string() }),
        ))
        .await;
    // Assert
    assert_eq!(ack.reason(), Some(ack_reasons::EXPIRED));
    assert!(
        h.scan.calls.lock().unwrap().is_empty(),
        "scan_router must not be invoked on expired POI"
    );
 }
 /// AZ-680 AC-5 — Decline appends IgnoredItem via scan_controller.
 #[tokio::test]
 async fn az680_ac5_decline_forwards_to_scan_router() {
    // Arrange
    let h = harness();
    let handle = h.bridge.handle();
    let surfaced = surfaced(120);
    h.bridge.surfaced_registry().record(surfaced.clone());
    // Act
    let ack = handle
        .dispatch_command(cmd(
            OperatorCommandKind::DeclinePoi,
            json!({ "poi_id": surfaced.poi_id.to_string() }),
        ))
        .await;
    // Assert
    assert_eq!(ack, CommandAck::Ok);
    let calls = h.scan.calls.lock().unwrap();
    assert_eq!(
        calls.len(),
        1,
        "DeclinePoi must reach scan_router exactly once"
    );
    assert!(matches!(calls[0].kind, OperatorCommandKind::DeclinePoi));
 }
 // ============================================================================
 // AZ-681 ACs
 // ============================================================================
 /// AZ-681 AC-1 — BIT-DEGRADED ack succeeds.
 #[tokio::test]
 async fn az681_ac1_bit_degraded_ack_forwards() {
    // Arrange
    let h = harness();
    let handle = h.bridge.handle();
    let report_id = Uuid::new_v4();
    h.severity.set(report_id, true);
    // Act
    let ack = handle
        .dispatch_command(cmd(
            OperatorCommandKind::AcknowledgeBitDegraded,
            json!({ "report_id": report_id.to_string(), "operator_id": "op1" }),
        ))
        .await;
    // Assert
    assert_eq!(ack, CommandAck::Ok);
    let acks = h.safety.bit_acks.lock().unwrap();
    assert_eq!(acks.len(), 1);
    assert_eq!(acks[0], (report_id, Some("op1".to_string())));
 }
 /// AZ-681 AC-2 — BIT-FAIL ack rejected.
 #[tokio::test]
 async fn az681_ac2_bit_fail_ack_rejected() {
    // Arrange
    let h = harness();
    let handle = h.bridge.handle();
    let report_id = Uuid::new_v4();
    h.severity.set(report_id, false);
    // Act
    let ack = handle
        .dispatch_command(cmd(
            OperatorCommandKind::AcknowledgeBitDegraded,
            json!({ "report_id": report_id.to_string(), "operator_id": "op1" }),
        ))
        .await;
    // Assert
    assert_eq!(ack.reason(), Some(ack_reasons::CANNOT_ACKNOWLEDGE_FAIL));
    assert!(
        h.safety.bit_acks.lock().unwrap().is_empty(),
        "safety_router must not be invoked on Fail report"
    );
 }
 /// AZ-681 AC-3 — Safety-override forwards with scope + duration, and
 /// an audit entry is written.
 #[tokio::test]
 async fn az681_ac3_safety_override_forwards_with_audit_entry() {
    // Arrange
    let h = harness();
    let handle = h.bridge.handle();
    // Act
    let ack = handle
        .dispatch_command(cmd(
            OperatorCommandKind::SafetyOverride,
            json!({
                "scope": "battery_rtl",
                "duration_secs": 60,
                "operator_id": "op1",
                "rationale": "post-mission RTL too aggressive"
            }),
        ))
        .await;
    // Assert — router invoked with the right scope + duration.
    assert_eq!(ack, CommandAck::Ok);
    let overrides = h.safety.overrides.lock().unwrap();
    assert_eq!(overrides.len(), 1);
    assert_eq!(overrides[0].0, SafetyOverrideScope::BatteryRtl);
    assert_eq!(overrides[0].1, 60);
    assert_eq!(overrides[0].2, "op1");
    // Assert — audit log has exactly one safety-override entry.
    let entries = h.audit.entries.lock();
    let safety_entries: Vec<_> = entries
        .iter()
        .filter(|e| matches!(e, AuditEntry::SafetyOverride { .. }))
        .collect();
    assert_eq!(safety_entries.len(), 1);
    match safety_entries[0] {
        AuditEntry::SafetyOverride {
            scope,
            duration_secs,
            operator_id,
            outcome,
            ..
        } => {
            assert_eq!(*scope, SafetyOverrideScope::BatteryRtl);
            assert_eq!(*duration_secs, 60);
            assert_eq!(operator_id.as_deref(), Some("op1"));
            assert_eq!(outcome, &CommandAck::Ok);
        }
        _ => unreachable!(),
    }
 }
 /// AZ-681 AC-4 — Audit log redacts secrets.
 #[tokio::test]
 async fn az681_ac4_audit_log_contains_no_signature_or_session_token() {
    // Arrange
    let h = harness();
    let handle = h.bridge.handle();
    // Act
    let _ = handle
        .dispatch_command(cmd(
            OperatorCommandKind::SafetyOverride,
            json!({
                "scope": "battery_rtl",
                "duration_secs": 30,
                "operator_id": "op1",
                "rationale": "test"
            }),
        ))
        .await;
    // Assert — every audit entry serialised to JSON must omit
    // `signature` and `session_token`.
    let entries = h.audit.entries.lock();
    assert!(!entries.is_empty());
    for entry in entries.iter() {
        let json = serde_json::to_string(entry).expect("serialises");
        assert!(
            !json.contains("signature"),
            "audit entry leaked signature: {json}"
        );
        assert!(
            !json.contains("session_token"),
            "audit entry leaked session_token: {json}"
        );
    }
 }
@@ -20,3 +20,4 @@ serde = { workspace = true }
 serde_json = { workspace = true }
 chrono = { workspace = true }
 uuid = { workspace = true }
 async-trait = { workspace = true }
@@ -66,6 +66,22 @@ pub struct DeclineAction {
    pub class_group: String,
 }
 /// AZ-680 — information returned when a POI is confirmed (or selected
 /// for target-follow start). Mirrors [`DeclineAction`] so consumers
 /// downstream of the confirm path (AZ-684 evidence ladder, AZ-685
 /// mapobjects dispatch, AZ-686 gimbal issuance) get a typed
 /// `(target_mgrs, target_class)` hint without re-querying the queue.
 ///
 /// The POI is removed from the queue as part of `confirm`. A
 /// subsequent confirm with the same `poi_id` returns `None`.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ConfirmAction {
    pub poi_id: Uuid,
    pub target_mgrs: String,
    pub target_class: String,
    pub class_group: String,
 }
 impl PoiQueue {
    pub fn new() -> Self {
        Self::default()
@@ -145,6 +161,23 @@ impl PoiQueue {
        })
    }
    /// Confirm a POI by id. Removes from queue; returns the typed
    /// `(target_mgrs, target_class)` hint that downstream consumers
    /// (AZ-684 evidence ladder, AZ-686 gimbal issuance) build the
    /// follow-up plan from. AZ-680 only needs the removal + the hint
    /// to be carried back through `submit_operator_cmd`'s return
    /// value.
    pub fn confirm(&mut self, poi_id: Uuid) -> Option<ConfirmAction> {
        let idx = self.entries.iter().position(|e| e.poi.id == poi_id)?;
        let entry = self.entries.swap_remove(idx);
        Some(ConfirmAction {
            poi_id: entry.poi.id,
            target_mgrs: entry.poi.mgrs,
            target_class: entry.poi.class,
            class_group: entry.poi.class_group,
        })
    }
    /// Drop POIs whose deadline (set at insertion by the caller per
    /// the confidence-scaled window) has elapsed. Returns the IDs of
    /// forgotten POIs. NO `IgnoredItem` is created — timeout =
@@ -31,10 +31,12 @@
 use std::sync::Arc;
 use std::time::{Duration, Instant};
 use async_trait::async_trait;
 use serde::{Deserialize, Serialize};
 use tokio::sync::Mutex;
 use uuid::Uuid;
 use shared::contracts::ScanCommandRouter;
 use shared::error::{AutopilotError, Result};
 use shared::health::{ComponentHealth, HealthLevel};
 use shared::models::operator::{OperatorCommand, OperatorCommandKind};
@@ -44,7 +46,8 @@ pub mod internal;
 pub use internal::frame_rate_guard::{FrameRateGuard, FrameRateGuardConfig};
 pub use internal::poi_queue::{
-    age_factor, decision_window, priority_score, DeclineAction, PoiQueue, SURFACE_CAP_PER_WINDOW,
+    age_factor, decision_window, priority_score, ConfirmAction, DeclineAction, PoiQueue,
    SURFACE_CAP_PER_WINDOW,
 };
 pub use internal::state_machine::transitions::{transition, TransitionCtx};
 pub use internal::state_machine::{RejectReason, ScanState, TransitionOutcome, Trigger};
@@ -153,11 +156,14 @@ pub struct ScanMetrics {
 /// Result of [`ScanControllerHandle::submit_operator_cmd`]. `Accepted`
 /// means the command was applied with no return data; `Declined`
-/// carries the dispatchable IgnoredItem action AZ-685 must persist.
+/// carries the dispatchable IgnoredItem action AZ-685 must persist;
 /// `Confirmed` carries the typed `(target_mgrs, target_class)` hint
 /// AZ-684 / AZ-686 build a follow-up plan from.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum SubmitOutcome {
    Accepted,
    Declined(DeclineAction),
    Confirmed(ConfirmAction),
 }
 fn poi_id_from_payload(payload: &serde_json::Value) -> Result<Uuid> {
@@ -268,6 +274,18 @@ impl ScanControllerHandle {
        action
    }
    /// AZ-680 — confirm a POI (or target-follow start). Looks up the
    /// POI by id, removes it from the queue, and returns the typed
    /// `(target_mgrs, target_class)` hint for downstream consumers.
    ///
    /// The FSM-side follow-through (zoom-in trigger, target-follow
    /// transition) is AZ-684's evidence-ladder scope and is NOT
    /// performed here — this method only resolves the queue entry.
    pub async fn confirm_poi(&self, poi_id: Uuid) -> Option<ConfirmAction> {
        let mut inner = self.inner.lock().await;
        inner.poi_queue.confirm(poi_id)
    }
    pub async fn poi_queue_len(&self) -> usize {
        self.inner.lock().await.poi_queue.len()
    }
@@ -279,20 +297,24 @@ impl ScanControllerHandle {
    /// Translate an operator command into a trigger and apply it.
    ///
-    /// AZ-682 / AZ-683 mapping (subset complete):
+    /// Mapping (AZ-682 / AZ-683 / AZ-680):
    ///
    /// - `MissionAbort` → `Trigger::OperatorAbort` (AZ-682).
    /// - `ReleaseTargetFollow` → `Trigger::OperatorReleaseFollow`
    ///   (AZ-682).
-    /// - `DeclinePoi { poi_id }` → queue decline; returns the
+    /// - `DeclinePoi { poi_id }` → queue decline; returns
-    ///   resulting `DeclineAction` in [`SubmitOutcome::Declined`]
+    ///   [`SubmitOutcome::Declined`] for the caller (AZ-685
-    ///   for the caller (AZ-685 mapobjects dispatch) to persist
+    ///   mapobjects dispatch) to persist (AZ-683).
-    ///   (AZ-683).
+    /// - `ConfirmPoi { poi_id }` / `StartTargetFollow { poi_id }` →
-    /// - `ConfirmPoi` / `StartTargetFollow` → still
+    ///   queue lookup + removal; returns
-    ///   `NotImplemented(AZ-684)` since ROI / target_id resolution
+    ///   [`SubmitOutcome::Confirmed`] carrying the typed
-    ///   needs the evidence ladder.
+    ///   `(target_mgrs, target_class)` hint (AZ-680). The FSM-side
-    /// - `AcknowledgeBitDegraded` / `SafetyOverride` →
+    ///   follow-through (zoom-in trigger, target-follow transition)
-    ///   `NotImplemented(AZ-684)`.
+    ///   is AZ-684's scope.
    /// - `AcknowledgeBitDegraded` / `SafetyOverride` are NOT
    ///   handled here — those go to `mission_executor` via the
    ///   `MissionSafetyRouter` path wired by `operator_bridge`
    ///   (AZ-681). Receiving one in this method is a routing bug.
    pub async fn submit_operator_cmd(&self, command: OperatorCommand) -> Result<SubmitOutcome> {
        match command.kind {
            OperatorCommandKind::MissionAbort => {
@@ -313,16 +335,21 @@ impl ScanControllerHandle {
                }
            }
            OperatorCommandKind::ConfirmPoi | OperatorCommandKind::StartTargetFollow => {
-                Err(AutopilotError::NotImplemented(
+                let poi_id = poi_id_from_payload(&command.payload)?;
-                    "scan_controller::submit_operator_cmd (AZ-684 evidence ladder)",
+                match self.confirm_poi(poi_id).await {
-                ))
+                    Some(action) => Ok(SubmitOutcome::Confirmed(action)),
                    None => Err(AutopilotError::Validation(format!(
                        "{:?}: unknown poi_id {poi_id}",
                        command.kind
                    ))),
                }
            }
            OperatorCommandKind::AcknowledgeBitDegraded | OperatorCommandKind::SafetyOverride => {
                Err(AutopilotError::Validation(format!(
                    "scan_controller does not handle {:?}; route via MissionSafetyRouter",
                    command.kind
                )))
            }
            OperatorCommandKind::AcknowledgeBitDegraded => Err(AutopilotError::NotImplemented(
                "scan_controller::submit_operator_cmd (AZ-684 evidence ladder)",
            )),
            OperatorCommandKind::SafetyOverride => Err(AutopilotError::NotImplemented(
                "scan_controller::submit_operator_cmd (AZ-684 evidence ladder)",
            )),
        }
    }
@@ -400,6 +427,22 @@ impl ScanControllerHandle {
    }
 }
 /// AZ-680 — adapter for the `shared::contracts::ScanCommandRouter`
 /// trait so `operator_bridge` (Layer 3) can dispatch operator
 /// commands into `scan_controller` (Layer 4) without importing this
 /// crate directly. Forwards to the inherent
 /// [`ScanControllerHandle::submit_operator_cmd`] and discards the
 /// `SubmitOutcome` (the trait surface is intentionally minimal —
 /// `operator_bridge` does not need the typed hint; AZ-685 wires the
 /// `Confirmed`/`Declined` actions into `mapobjects_store` through a
 /// different path).
 #[async_trait]
 impl ScanCommandRouter for ScanControllerHandle {
    async fn route(&self, command: OperatorCommand) -> Result<()> {
        self.submit_operator_cmd(command).await.map(|_| ())
    }
 }
 #[cfg(test)]
 mod tests {
    use super::*;
@@ -153,7 +153,73 @@ async fn decline_poi_via_operator_command_emits_action() {
            assert_eq!(action.mgrs, "decline-me");
            assert_eq!(action.class_group, "armor");
        }
-        SubmitOutcome::Accepted => panic!("decline must return Declined action"),
+        other => panic!("decline must return Declined action, got {other:?}"),
    }
    assert_eq!(h.poi_queue_len().await, 0);
 }
 /// AZ-680 — ConfirmPoi via operator command returns
 /// `SubmitOutcome::Confirmed` with the typed target hint and drains
 /// the POI from the queue.
 #[tokio::test]
 async fn confirm_poi_via_operator_command_emits_action() {
    // Arrange
    let h = ScanController::new().handle();
    let p = poi(0.8, "confirm-me");
    let id = p.id;
    let expected_class = p.class.clone();
    let expected_group = p.class_group.clone();
    h.submit_poi_candidate(p, 0.5).await;
    let cmd = OperatorCommand {
        command_id: Uuid::new_v4(),
        session_token: "s".to_string(),
        sequence_number: 1,
        issued_at_wallclock: Utc::now(),
        kind: OperatorCommandKind::ConfirmPoi,
        payload: json!({ "poi_id": id.to_string() }),
        signature: vec![],
    };
    // Act
    let outcome = h.submit_operator_cmd(cmd).await.expect("confirm accepted");
    // Assert
    match outcome {
        SubmitOutcome::Confirmed(action) => {
            assert_eq!(action.poi_id, id);
            assert_eq!(action.target_mgrs, "confirm-me");
            assert_eq!(action.target_class, expected_class);
            assert_eq!(action.class_group, expected_group);
        }
        other => panic!("confirm must return Confirmed action, got {other:?}"),
    }
    assert_eq!(h.poi_queue_len().await, 0);
 }
 /// AZ-680 — ConfirmPoi for an unknown poi_id must NOT silently
 /// succeed. Returns a `Validation` error so `operator_bridge` can
 /// surface a typed NACK to the operator UI.
 #[tokio::test]
 async fn confirm_poi_unknown_id_is_validation_error() {
    // Arrange
    let h = ScanController::new().handle();
    let cmd = OperatorCommand {
        command_id: Uuid::new_v4(),
        session_token: "s".to_string(),
        sequence_number: 1,
        issued_at_wallclock: Utc::now(),
        kind: OperatorCommandKind::ConfirmPoi,
        payload: json!({ "poi_id": Uuid::new_v4().to_string() }),
        signature: vec![],
    };
    // Act
    let err = h
        .submit_operator_cmd(cmd)
        .await
        .expect_err("unknown poi must error");
    // Assert
    assert!(matches!(err, shared::error::AutopilotError::Validation(_)));
 }
@@ -11,5 +11,8 @@ authors.workspace = true
 shared = { workspace = true }
 tokio = { workspace = true }
 tracing = { workspace = true }
 opencv = { workspace = true }
 petgraph = { workspace = true }
-# TensorRT / ONNX runtime wiring lands with AZ-670.
+[dev-dependencies]
 bytes = { workspace = true }
@@ -0,0 +1,2 @@
 pub mod primitive_graph;
 pub mod scoring;
@@ -0,0 +1,281 @@
 //! AZ-669 — Build a `PrimitiveGraph` from a `DetectionBatch` inside an ROI,
 //! then validate connectivity of the path sub-graph.
 use std::sync::atomic::{AtomicU64, Ordering};
 use std::sync::Arc;
 use shared::models::{detection::DetectionBatch, frame::BoundingBox};
 use super::graph::{NodeType, PrimitiveGraph, PrimitiveNode};
 // ── class-name → NodeType mapping ────────────────────────────────────────────
 fn classify_class_name(name: &str) -> NodeType {
    let lower = name.to_ascii_lowercase();
    if lower.contains("path") || lower.contains("road") || lower.contains("footpath") {
        NodeType::Path
    } else if lower.contains("branch")
        || lower.contains("pile")
        || lower.contains("entrance")
        || lower.contains("dugout")
    {
        NodeType::Endpoint
    } else {
        // trees, tree blocks, and unknowns are contextual landmarks
        NodeType::Context
    }
 }
 // ── spatial proximity helpers ─────────────────────────────────────────────────
 /// Centre of a bounding box in normalised image coordinates.
 fn centre(b: &BoundingBox) -> (f32, f32) {
    ((b.x_min + b.x_max) / 2.0, (b.y_min + b.y_max) / 2.0)
 }
 /// Euclidean distance between two bbox centres.
 fn centre_dist(a: &BoundingBox, b: &BoundingBox) -> f32 {
    let (ax, ay) = centre(a);
    let (bx, by) = centre(b);
    ((ax - bx).powi(2) + (ay - by).powi(2)).sqrt()
 }
 /// Maximum dimension of a bounding box (normalised units).
 fn max_dim(b: &BoundingBox) -> f32 {
    (b.x_max - b.x_min).max(b.y_max - b.y_min)
 }
 // ── connectivity (BFS on path nodes) ─────────────────────────────────────────
 /// Returns the number of connected components in the path sub-graph described
 /// by `edges` over the `path_indices` set.
 fn count_path_components(
    path_indices: &[usize],
    edges: &[(usize, usize)],
 ) -> usize {
    if path_indices.is_empty() {
        return 0;
    }
    // Map global node index → local index within `path_indices`.
    let mut local: std::collections::HashMap<usize, usize> =
        path_indices.iter().enumerate().map(|(l, &g)| (g, l)).collect();
    let n = path_indices.len();
    let mut adj: Vec<Vec<usize>> = vec![vec![]; n];
    for &(a, b) in edges {
        if let (Some(&la), Some(&lb)) = (local.get(&a), local.get(&b)) {
            adj[la].push(lb);
            adj[lb].push(la);
        }
    }
    let mut visited = vec![false; n];
    let mut components = 0usize;
    for start in 0..n {
        if visited[start] {
            continue;
        }
        components += 1;
        let mut queue = std::collections::VecDeque::new();
        queue.push_back(start);
        visited[start] = true;
        while let Some(cur) = queue.pop_front() {
            for &nb in &adj[cur] {
                if !visited[nb] {
                    visited[nb] = true;
                    queue.push_back(nb);
                }
            }
        }
    }
    components
 }
 // ── builder ───────────────────────────────────────────────────────────────────
 pub struct GraphCounters {
    pub graphs_built_total: AtomicU64,
    pub disconnected_graphs_total: AtomicU64,
 }
 impl GraphCounters {
    pub fn new() -> Self {
        Self {
            graphs_built_total: AtomicU64::new(0),
            disconnected_graphs_total: AtomicU64::new(0),
        }
    }
 }
 impl Default for GraphCounters {
    fn default() -> Self {
        Self::new()
    }
 }
 pub struct PrimitiveGraphBuilder {
    counters: Arc<GraphCounters>,
    /// Spatial-proximity multiplier: two path nodes are adjacent when their
    /// centre-to-centre distance ≤ this factor × the larger of their max dims.
    adjacency_factor: f32,
 }
 impl PrimitiveGraphBuilder {
    pub fn new(counters: Arc<GraphCounters>) -> Self {
        Self { counters, adjacency_factor: 2.5 }
    }
    pub fn counters(&self) -> &Arc<GraphCounters> {
        &self.counters
    }
    /// Build a `PrimitiveGraph` from detections inside `roi`.
    ///
    /// Only detections whose bbox centre lies inside `roi` are included.
    /// After construction the path sub-graph is validated for connectivity;
    /// a disconnected graph is flagged and the counter is incremented.
    pub fn build(&self, roi: &BoundingBox, batch: &DetectionBatch) -> PrimitiveGraph {
        let nodes: Vec<PrimitiveNode> = batch
            .detections
            .iter()
            .enumerate()
            .filter(|(_, d)| {
                let (cx, cy) = centre(&d.bbox_normalized);
                cx >= roi.x_min
                    && cx <= roi.x_max
                    && cy >= roi.y_min
                    && cy <= roi.y_max
            })
            .map(|(i, d)| PrimitiveNode {
                node_type: classify_class_name(&d.class_name),
                bbox: d.bbox_normalized,
                confidence: d.confidence,
                class_name: d.class_name.clone(),
                detection_index: i,
            })
            .collect();
        // Build proximity edges between path nodes only.
        let path_idxs: Vec<usize> = nodes
            .iter()
            .enumerate()
            .filter(|(_, n)| n.node_type == NodeType::Path)
            .map(|(i, _)| i)
            .collect();
        let mut edges: Vec<(usize, usize)> = Vec::new();
        for i in 0..path_idxs.len() {
            for j in (i + 1)..path_idxs.len() {
                let ni = &nodes[path_idxs[i]];
                let nj = &nodes[path_idxs[j]];
                let dist = centre_dist(&ni.bbox, &nj.bbox);
                let threshold = self.adjacency_factor * max_dim(&ni.bbox).max(max_dim(&nj.bbox));
                if dist <= threshold {
                    edges.push((path_idxs[i], path_idxs[j]));
                }
            }
        }
        // Connectivity validation.
        let components = count_path_components(&path_idxs, &edges);
        let disconnected = components > 1;
        let valid = !disconnected;
        if disconnected {
            self.counters.disconnected_graphs_total.fetch_add(1, Ordering::Relaxed);
            tracing::warn!(
                disconnected_components = components,
                "primitive graph has disconnected path components"
            );
        }
        self.counters.graphs_built_total.fetch_add(1, Ordering::Relaxed);
        PrimitiveGraph { nodes, edges, valid, disconnected }
    }
 }
 // ── Tests ─────────────────────────────────────────────────────────────────────
 #[cfg(test)]
 mod tests {
    use super::*;
    use shared::models::detection::{Detection, DetectionBatch};
    use shared::models::frame::BoundingBox;
    fn roi() -> BoundingBox {
        BoundingBox { x_min: 0.0, y_min: 0.0, x_max: 1.0, y_max: 1.0 }
    }
    fn det(class_name: &str, x: f32, y: f32) -> Detection {
        Detection {
            class_id: 0,
            class_name: class_name.to_owned(),
            confidence: 0.9,
            bbox_normalized: BoundingBox {
                x_min: x - 0.05,
                y_min: y - 0.05,
                x_max: x + 0.05,
                y_max: y + 0.05,
            },
            mask_or_polyline: None,
            source_frame_seq: 0,
        }
    }
    fn batch(dets: Vec<Detection>) -> DetectionBatch {
        DetectionBatch {
            frame_seq: 1,
            detections: dets,
            latency_ms: 10,
            model_version: "v1".to_owned(),
        }
    }
    // AC-1: correct node counts per detection class.
    #[test]
    fn ac1_node_counts_per_class() {
        let counters = Arc::new(GraphCounters::new());
        let builder = PrimitiveGraphBuilder::new(Arc::clone(&counters));
        let dets = vec![
            det("footpath", 0.1, 0.1),
            det("footpath", 0.2, 0.2),
            det("footpath", 0.3, 0.3),
            det("branch_pile", 0.4, 0.4),
            det("branch_pile", 0.5, 0.5),
            det("tree", 0.6, 0.1),
            det("tree", 0.7, 0.2),
            det("tree", 0.8, 0.3),
            det("tree", 0.15, 0.6),
            det("tree_block", 0.25, 0.7),
        ];
        let b = batch(dets);
        let graph = builder.build(&roi(), &b);
        let paths = graph.nodes.iter().filter(|n| n.node_type == NodeType::Path).count();
        let endpoints = graph.nodes.iter().filter(|n| n.node_type == NodeType::Endpoint).count();
        let contexts = graph.nodes.iter().filter(|n| n.node_type == NodeType::Context).count();
        assert_eq!(paths, 3, "expected 3 path nodes");
        assert_eq!(endpoints, 2, "expected 2 endpoint nodes");
        assert_eq!(contexts, 5, "expected 5 context nodes");
        assert_eq!(counters.graphs_built_total.load(Ordering::Relaxed), 1);
    }
    // AC-3: disconnected path components are flagged and counter increments.
    #[test]
    fn ac3_disconnected_path_graph_flagged() {
        let counters = Arc::new(GraphCounters::new());
        // Use a very small adjacency factor so distant nodes don't accidentally connect.
        let builder = PrimitiveGraphBuilder { counters: Arc::clone(&counters), adjacency_factor: 0.5 };
        // Two isolated path clusters — far apart in the image.
        let dets = vec![
            det("footpath", 0.1, 0.1), // cluster A
            det("footpath", 0.9, 0.9), // cluster B (isolated)
        ];
        let graph = builder.build(&roi(), &batch(dets));
        assert!(graph.disconnected, "graph should be marked disconnected");
        assert!(!graph.valid);
        assert_eq!(counters.disconnected_graphs_total.load(Ordering::Relaxed), 1);
    }
 }
@@ -0,0 +1,47 @@
 //! Primitive graph types — path, endpoint, and context nodes.
 use shared::models::frame::BoundingBox;
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum NodeType {
    /// Footpath, road — the main navigation surface.
    Path,
    /// Branch pile, dark entrance, dugout — a decision point or POI endpoint.
    Endpoint,
    /// Tree, tree block — contextual landmark.
    Context,
 }
 #[derive(Debug, Clone)]
 pub struct PrimitiveNode {
    pub node_type: NodeType,
    pub bbox: BoundingBox,
    pub confidence: f32,
    pub class_name: String,
    /// Index into the source `DetectionBatch.detections` vec.
    pub detection_index: usize,
 }
 /// A small ROI-scoped graph of primitive detections.
 ///
 /// `edges` encodes spatial-proximity adjacency between path nodes
 /// (indices into `nodes`). `valid = false` and `disconnected = true`
 /// when ≥2 separate path components are found.
 #[derive(Debug, Default)]
 pub struct PrimitiveGraph {
    pub nodes: Vec<PrimitiveNode>,
    /// Undirected adjacency edges between path nodes (node indices).
    pub edges: Vec<(usize, usize)>,
    /// False when the path sub-graph has ≥2 connected components.
    pub valid: bool,
    pub disconnected: bool,
 }
 impl PrimitiveGraph {
    pub fn path_nodes(&self) -> impl Iterator<Item = (usize, &PrimitiveNode)> {
        self.nodes
            .iter()
            .enumerate()
            .filter(|(_, n)| n.node_type == NodeType::Path)
    }
 }
@@ -0,0 +1,7 @@
 //! AZ-669 — Primitive graph builder + graph validation.
 pub mod builder;
 pub mod graph;
 pub use builder::PrimitiveGraphBuilder;
 pub use graph::{NodeType, PrimitiveGraph, PrimitiveNode};
@@ -0,0 +1,266 @@
 //! AZ-669 — Path-freshness scoring.
 //!
 //! Combines three classical CV cues: edge clarity (Laplacian variance),
 //! texture variance (pixel std-dev), and undisturbed surroundings (border
 //! region variance). Each sub-score is normalised to [0, 1] and averaged.
 use opencv::{
    core::{self, Mat, Scalar},
    imgproc,
    prelude::*,
 };
 use shared::models::frame::{BoundingBox, Frame, PixelFormat};
 use super::super::primitive_graph::graph::{NodeType, PrimitiveGraph};
 /// Freshness score for a single path node.
 #[derive(Debug, Clone, Copy)]
 pub struct PathFreshnessScore {
    /// Index into `PrimitiveGraph::nodes`.
    pub node_index: usize,
    /// Normalised score in `[0.0, 1.0]`.
    pub score: f32,
 }
 pub struct FreshnessScorer;
 impl FreshnessScorer {
    /// Score all path nodes in `graph` against the frame crop.
    /// Every returned `PathFreshnessScore::score` is in `[0.0, 1.0]`.
    pub fn score(
        graph: &PrimitiveGraph,
        frame_crop: &Frame,
    ) -> opencv::Result<Vec<PathFreshnessScore>> {
        let gray = frame_to_gray_mat(frame_crop)?;
        let mut scores = Vec::new();
        for (idx, node) in graph.path_nodes() {
            let s = score_region(&gray, &node.bbox, frame_crop.width, frame_crop.height)?;
            scores.push(PathFreshnessScore { node_index: idx, score: s });
        }
        Ok(scores)
    }
 }
 // ── CV helpers ────────────────────────────────────────────────────────────────
 fn frame_to_gray_mat(frame: &Frame) -> opencv::Result<Mat> {
    let h = frame.height as i32;
    let w = frame.width as i32;
    let data: &[u8] = &frame.pixels;
    match frame.pix_fmt {
        PixelFormat::Nv12 | PixelFormat::Yuv420p => {
            let y_len = (w * h) as usize;
            let mut mat = Mat::new_rows_cols_with_default(h, w, core::CV_8UC1, Scalar::all(0.0))?;
            // SAFETY: freshly allocated continuous Mat; no aliasing.
            // `data_mut()` returns `*mut u8` directly in opencv 0.98 (no Result).
            let dst = unsafe { std::slice::from_raw_parts_mut(mat.data_mut(), y_len) };
            dst.copy_from_slice(&data[..y_len]);
            Ok(mat)
        }
        PixelFormat::Rgb24 => {
            let rgb_len = (w * h * 3) as usize;
            let mut rgb =
                Mat::new_rows_cols_with_default(h, w, core::CV_8UC3, Scalar::all(0.0))?;
            let dst = unsafe { std::slice::from_raw_parts_mut(rgb.data_mut(), rgb_len) };
            dst.copy_from_slice(&data[..rgb_len]);
            let mut gray = Mat::default();
            imgproc::cvt_color(&rgb, &mut gray, imgproc::COLOR_RGB2GRAY, 0)?;
            Ok(gray)
        }
    }
 }
 /// Compute a freshness score for the bbox region within `gray`.
 /// Returns a value in [0.0, 1.0].
 fn score_region(
    gray: &Mat,
    bbox: &BoundingBox,
    frame_w: u32,
    frame_h: u32,
 ) -> opencv::Result<f32> {
    let roi_rect = bbox_to_rect(bbox, frame_w, frame_h, gray.cols(), gray.rows());
    if roi_rect.width <= 0 || roi_rect.height <= 0 {
        return Ok(0.0);
    }
    let roi = Mat::roi(gray, roi_rect)?;
    // 1. Edge clarity: Laplacian variance — sharp edges indicate an active path.
    let mut lap = Mat::default();
    imgproc::laplacian(&roi, &mut lap, core::CV_64F, 3, 1.0, 0.0, core::BORDER_DEFAULT)?;
    let edge_var = variance(&lap)? as f32;
    // 2. Texture: std-dev of pixel intensities.
    let texture_std = stddev_f32(&roi)?;
    // 3. Undisturbed surroundings: low variance in the border region around bbox
    //    signals an untouched environment → higher freshness contribution.
    let surround_var = surround_variance(gray, roi_rect)? as f32;
    let undisturbed_score = 1.0 - normalise(surround_var, 3000.0);
    let edge_score = normalise(edge_var, 1500.0);
    let texture_score = normalise(texture_std, 40.0);
    let freshness = ((edge_score + texture_score + undisturbed_score) / 3.0).clamp(0.0, 1.0);
    Ok(freshness)
 }
 fn bbox_to_rect(
    bbox: &BoundingBox,
    frame_w: u32,
    frame_h: u32,
    mat_w: i32,
    mat_h: i32,
 ) -> core::Rect {
    let x = ((bbox.x_min * frame_w as f32) as i32).clamp(0, mat_w - 1);
    let y = ((bbox.y_min * frame_h as f32) as i32).clamp(0, mat_h - 1);
    let x2 = ((bbox.x_max * frame_w as f32) as i32).clamp(0, mat_w);
    let y2 = ((bbox.y_max * frame_h as f32) as i32).clamp(0, mat_h);
    core::Rect::new(x, y, (x2 - x).max(1), (y2 - y).max(1))
 }
 /// Compute the variance of all values in a Mat as f64.
 fn variance(mat: &Mat) -> opencv::Result<f64> {
    let mut mean_mat = Mat::default();
    let mut stddev_mat = Mat::default();
    core::mean_std_dev(mat, &mut mean_mat, &mut stddev_mat, &core::no_array())?;
    let std = stddev_mat.at::<f64>(0).map(|v| *v).unwrap_or(0.0);
    Ok(std * std)
 }
 // Accept `&impl ToInputArray` so both `&Mat` and `&BoxedRef<Mat>` (returned
 // by `Mat::roi` in opencv 0.98) can be passed without manual deref.
 fn stddev_f32(mat: &impl core::ToInputArray) -> opencv::Result<f32> {
    let mut mean_mat = Mat::default();
    let mut stddev_mat = Mat::default();
    core::mean_std_dev(mat, &mut mean_mat, &mut stddev_mat, &core::no_array())?;
    Ok(stddev_mat.at::<f64>(0).map(|v| *v as f32).unwrap_or(0.0))
 }
 /// Compute the pixel variance in a ~16 px border region around `rect`.
 fn surround_variance(gray: &Mat, rect: core::Rect) -> opencv::Result<f64> {
    let border = 16i32;
    let x = (rect.x - border).max(0);
    let y = (rect.y - border).max(0);
    let x2 = (rect.x + rect.width + border).min(gray.cols());
    let y2 = (rect.y + rect.height + border).min(gray.rows());
    let outer_rect = core::Rect::new(x, y, (x2 - x).max(1), (y2 - y).max(1));
    let outer = Mat::roi(gray, outer_rect)?;
    // Build a mask: 0 inside inner rect, 255 in the border band.
    let mut mask = Mat::new_rows_cols_with_default(
        outer_rect.height,
        outer_rect.width,
        core::CV_8UC1,
        Scalar::all(255.0),
    )?;
    let inner_x = rect.x - x;
    let inner_y = rect.y - y;
    let inner = core::Rect::new(
        inner_x.clamp(0, outer_rect.width - 1),
        inner_y.clamp(0, outer_rect.height - 1),
        rect.width.min(outer_rect.width - inner_x.max(0)),
        rect.height.min(outer_rect.height - inner_y.max(0)),
    );
    if inner.width > 0 && inner.height > 0 {
        let mut inner_roi = Mat::roi_mut(&mut mask, inner)?;
        inner_roi.set_to(&Scalar::all(0.0), &core::no_array())?;
    }
    let mut mean_mat = Mat::default();
    let mut stddev_mat = Mat::default();
    core::mean_std_dev(&outer, &mut mean_mat, &mut stddev_mat, &mask)?;
    let std = stddev_mat.at::<f64>(0).map(|v| *v).unwrap_or(0.0);
    Ok(std * std)
 }
 /// Map `value` ∈ [0, ∞) to [0.0, 1.0] by dividing by `scale` and clamping.
 #[inline]
 fn normalise(value: f32, scale: f32) -> f32 {
    (value / scale).clamp(0.0, 1.0)
 }
 // ── Tests ─────────────────────────────────────────────────────────────────────
 #[cfg(test)]
 mod tests {
    use std::sync::Arc;
    use bytes::Bytes;
    use super::*;
    use super::super::super::primitive_graph::{builder::{GraphCounters, PrimitiveGraphBuilder}, graph::PrimitiveGraph};
    use shared::models::{
        detection::{Detection, DetectionBatch},
        frame::{BoundingBox, Frame, PixelFormat},
    };
    fn rgb_frame(w: u32, h: u32, fill: u8, ts: u64) -> Frame {
        Frame {
            seq: 0,
            capture_ts_monotonic_ns: ts,
            decode_ts_monotonic_ns: ts,
            pixels: Arc::new(Bytes::from(vec![fill; (w * h * 3) as usize])),
            width: w,
            height: h,
            pix_fmt: PixelFormat::Rgb24,
            ai_locked: false,
        }
    }
    fn noisy_rgb_frame(w: u32, h: u32, ts: u64) -> Frame {
        let total = (w * h * 3) as usize;
        let pixels: Vec<u8> = (0..total).map(|i| (i % 256) as u8).collect();
        Frame {
            seq: 0,
            capture_ts_monotonic_ns: ts,
            decode_ts_monotonic_ns: ts,
            pixels: Arc::new(Bytes::from(pixels)),
            width: w,
            height: h,
            pix_fmt: PixelFormat::Rgb24,
            ai_locked: false,
        }
    }
    fn single_path_graph() -> PrimitiveGraph {
        let counters = Arc::new(GraphCounters::new());
        let builder = PrimitiveGraphBuilder::new(counters);
        let roi = BoundingBox { x_min: 0.0, y_min: 0.0, x_max: 1.0, y_max: 1.0 };
        let batch = DetectionBatch {
            frame_seq: 1,
            detections: vec![Detection {
                class_id: 0,
                class_name: "footpath".to_owned(),
                confidence: 0.9,
                bbox_normalized: BoundingBox {
                    x_min: 0.2, y_min: 0.2, x_max: 0.8, y_max: 0.8,
                },
                mask_or_polyline: None,
                source_frame_seq: 1,
            }],
            latency_ms: 5,
            model_version: "v1".to_owned(),
        };
        builder.build(&roi, &batch)
    }
    // AC-2: every freshness score is in [0.0, 1.0] for any valid input.
    #[test]
    fn ac2_freshness_score_bounded() -> opencv::Result<()> {
        let graph = single_path_graph();
        // Uniform gray frame.
        let uniform = rgb_frame(64, 64, 128, 0);
        let scores_uniform = FreshnessScorer::score(&graph, &uniform)?;
        for s in &scores_uniform {
            assert!(s.score >= 0.0 && s.score <= 1.0, "score out of range: {}", s.score);
        }
        // Noisy textured frame.
        let noisy = noisy_rgb_frame(64, 64, 0);
        let scores_noisy = FreshnessScorer::score(&graph, &noisy)?;
        for s in &scores_noisy {
            assert!(s.score >= 0.0 && s.score <= 1.0, "score out of range: {}", s.score);
        }
        Ok(())
    }
 }
@@ -0,0 +1,3 @@
 pub mod freshness;
 pub use freshness::{FreshnessScorer, PathFreshnessScore};
@@ -1,46 +1,71 @@
-//! `semantic_analyzer` — Tier 2 primitive graph + ROI CNN.
+//! `semantic_analyzer` — primitive graph + freshness scoring.
 //!
-//! Real implementation lands in:
+//! AZ-669: primitive graph builder + freshness scorer (this batch).
-//! - AZ-669 `semantic_analyzer_primitive_graph`
+//! AZ-670: TensorRT/ONNX scene-embedding classifier.
-//! - AZ-670 `semantic_analyzer_roi_cnn`
+//! AZ-671: output publisher.
 //! - AZ-671 `semantic_analyzer_action_policy`
-use shared::error::{AutopilotError, Result};
+use std::sync::Arc;
-use shared::health::ComponentHealth;
+
-use shared::models::tier2::Tier2Evidence;
+use tokio::sync::broadcast;
 use shared::health::{ComponentHealth, HealthLevel};
 use shared::models::detection::DetectionBatch;
 pub(crate) mod internal;
 use internal::{
    primitive_graph::builder::{GraphCounters, PrimitiveGraphBuilder},
    scoring::FreshnessScorer,
 };
 const NAME: &str = "semantic_analyzer";
-pub struct SemanticAnalyzer;
+pub struct SemanticAnalyzer {
    tx: broadcast::Sender<DetectionBatch>,
    counters: Arc<GraphCounters>,
 }
 impl SemanticAnalyzer {
-    pub fn new() -> Self {
+    pub fn new(channel_capacity: usize) -> Self {
-        Self
+        let (tx, _) = broadcast::channel(channel_capacity);
        Self { tx, counters: Arc::new(GraphCounters::new()) }
    }
    pub fn handle(&self) -> SemanticAnalyzerHandle {
-        SemanticAnalyzerHandle
+        SemanticAnalyzerHandle {
            tx: self.tx.clone(),
            counters: Arc::clone(&self.counters),
        }
    }
 }
-impl Default for SemanticAnalyzer {
+#[derive(Clone)]
-    fn default() -> Self {
+pub struct SemanticAnalyzerHandle {
-        Self::new()
+    tx: broadcast::Sender<DetectionBatch>,
-    }
+    counters: Arc<GraphCounters>,
 }
 #[derive(Clone, Copy)]
 pub struct SemanticAnalyzerHandle;
 impl SemanticAnalyzerHandle {
-    pub async fn analyze(&self, _roi: Vec<u8>) -> Result<Tier2Evidence> {
+    pub fn detections(&self) -> broadcast::Receiver<DetectionBatch> {
-        Err(AutopilotError::NotImplemented(
+        self.tx.subscribe()
            "semantic_analyzer::analyze (AZ-669)",
        ))
    }
    pub fn health(&self) -> ComponentHealth {
-        ComponentHealth::disabled(NAME)
+        let disconnected = self.counters.disconnected_graphs_total.load(
            std::sync::atomic::Ordering::Relaxed,
        );
        if disconnected > 0 {
            ComponentHealth::yellow(
                NAME,
                format!("disconnected_graphs_total={disconnected}"),
            )
        } else {
            ComponentHealth {
                level: HealthLevel::Disabled,
                component: NAME,
                detail: None,
            }
        }
    }
 }
@@ -50,7 +75,10 @@ mod tests {
    #[test]
    fn it_compiles() {
-        let h = SemanticAnalyzer::new().handle();
+        let h = SemanticAnalyzer::new(16).handle();
-        assert_eq!(h.health().level, shared::health::HealthLevel::Disabled);
+        assert!(matches!(
            h.health().level,
            HealthLevel::Disabled | HealthLevel::Yellow
        ));
    }
 }
@@ -83,6 +83,66 @@ pub trait OperatorCommandSink: Send + Sync {
    async fn dispatch(&self, command: OperatorCommand) -> Result<()>;
 }
 /// AZ-680 — route a validated `OperatorCommand` into `scan_controller`.
 ///
 /// Lives in `shared::contracts` so `operator_bridge` (Layer 3) can
 /// depend on the trait without importing `scan_controller` (Layer 4).
 /// `scan_controller` implements this for its public `Handle`.
 ///
 /// The trait name uses `route` instead of `submit_operator_cmd` to
 /// avoid a name collision with the inherent method on
 /// `ScanControllerHandle`. Implementations forward to the inherent
 /// method.
 #[async_trait]
 pub trait ScanCommandRouter: Send + Sync {
    async fn route(&self, command: OperatorCommand) -> Result<()>;
 }
 /// AZ-681 — forward safety-critical operator commands (BIT acks,
 /// safety overrides) into `mission_executor`.
 ///
 /// `operator_bridge` (Layer 3) cannot import `mission_executor`
 /// (Layer 3 sibling). The composition root constructs a concrete
 /// impl that wraps the executor's BIT ack channel + battery monitor
 /// handle.
 #[async_trait]
 pub trait MissionSafetyRouter: Send + Sync {
    /// Forward a signed BIT-degraded acknowledgement. The
    /// `report_id` identifies the originating BIT report that
    /// produced the `Degraded` verdict. `operator_id` is carried for
    /// the executor's structured-log trail.
    async fn acknowledge_bit_degraded(
        &self,
        report_id: uuid::Uuid,
        operator_id: Option<String>,
    ) -> Result<()>;
    /// Apply a signed safety override. The override is bounded by
    /// `duration_secs`; the receiving subsystem (e.g. battery
    /// monitor) is responsible for enforcing the deadline.
    async fn apply_safety_override(
        &self,
        scope: crate::models::operator::SafetyOverrideScope,
        duration_secs: u32,
        operator_id: String,
        rationale: String,
    ) -> Result<()>;
 }
 /// AZ-681 — look up the severity of a previously-generated BIT report
 /// by id. `operator_bridge` consults this before forwarding a BIT-
 /// degraded ack: a `Fail` severity is never acknowledgeable (per
 /// AC-2).
 ///
 /// Returns `Some(true)` when the report exists and is acknowledgeable
 /// (severity is NOT `Fail`); `Some(false)` when known and `Fail`;
 /// `None` when the report id has never been generated (or has aged
 /// out of the lookup cache).
 #[async_trait]
 pub trait BitReportSeverityLookup: Send + Sync {
    async fn is_acknowledgeable(&self, report_id: uuid::Uuid) -> Option<bool>;
 }
 #[cfg(test)]
 mod tests {
    use super::*;
@@ -20,6 +20,31 @@ pub enum OperatorCommandKind {
    MissionAbort,
 }
 /// AZ-681 — scope of a `SafetyOverride` command. Each variant maps to
 /// a specific failsafe family in `mission_executor` that the operator
 /// is suppressing for a bounded duration (architecture.md §F10).
 ///
 /// Marked `#[non_exhaustive]` so adding `LinkLost` / `Geofence` later
 /// is a non-breaking change to downstream matchers.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "snake_case")]
 #[non_exhaustive]
 pub enum SafetyOverrideScope {
    /// Suppress battery-RTL until the override deadline elapses. The
    /// `hard_floor` land-now is NEVER suppressible regardless of
    /// override (per `architecture.md §F10`).
    BatteryRtl,
 }
 impl SafetyOverrideScope {
    /// Stable kebab-case label for audit logs and metrics.
    pub fn label(self) -> &'static str {
        match self {
            Self::BatteryRtl => "battery_rtl",
        }
    }
 }
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct OperatorCommand {
    pub command_id: Uuid,
@@ -0,0 +1,73 @@
 #!/usr/bin/env bash
 #
 # jetson-test.sh — run the full `cargo test --workspace` on the
 # production-target Jetson via Docker (Dockerfile.test).
 #
 # Why this exists: the autopilot workspace depends on `opencv`,
 # `ffmpeg-next`, `tonic`/`prost`, and `libclang` at build time. The
 # macOS dev box does not always have native OpenCV / FFmpeg headers
 # installed, and the production target is a Jetson Orin Nano Super
 # running JetPack 6 (Ubuntu 22.04 aarch64). This script bridges the
 # two by rsync-ing the source to the Jetson and running tests inside
 # a container that mirrors the production environment exactly.
 #
 # Prerequisites:
 #   - `ssh <SSH_HOST>` works passwordlessly (key-based auth).
 #   - The remote user is in the `docker` group (no sudo for `docker`).
 #   - `rsync` is available locally.
 #
 # Usage:
 #   scripts/jetson-test.sh                    # full suite, default host
 #   SSH_HOST=other-jetson scripts/jetson-test.sh
 #   scripts/jetson-test.sh -p movement_detector -p semantic_analyzer
 #
 # Any args passed after the script name are forwarded to `cargo test`
 # inside the container (the default is the workspace suite).
 #
 # Exit code: forwarded from `cargo test` inside the container.
 set -euo pipefail
 SSH_HOST="${SSH_HOST:-jetson-e2e}"
 REMOTE_DIR="${REMOTE_DIR:-/home/jetson/autopilot}"
 IMAGE_TAG="${IMAGE_TAG:-autopilot-test}"
 DOCKERFILE="${DOCKERFILE:-Dockerfile.test}"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 REPO_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
 cd "${REPO_ROOT}"
 log() {
    printf '\n\033[1;34m[jetson-test]\033[0m %s\n' "$*"
 }
 log "Sync source to ${SSH_HOST}:${REMOTE_DIR} (excluding target/, .git/)"
 ssh "${SSH_HOST}" "mkdir -p '${REMOTE_DIR}'"
 rsync -az --delete \
    --exclude='target/' \
    --exclude='.git/' \
    --exclude='.DS_Store' \
    --exclude='*.swp' \
    --exclude='node_modules/' \
    ./ "${SSH_HOST}:${REMOTE_DIR}/"
 log "Build test image ${IMAGE_TAG} on ${SSH_HOST} (may take 10-20 min on first run)"
 ssh "${SSH_HOST}" "cd '${REMOTE_DIR}' && docker build --pull -t '${IMAGE_TAG}' -f '${DOCKERFILE}' ."
 if [[ $# -gt 0 ]]; then
    log "Running: cargo test $*"
    ssh "${SSH_HOST}" \
        "cd '${REMOTE_DIR}' && docker run --rm \
            -v '${REMOTE_DIR}:/workspace' \
            -w /workspace \
            '${IMAGE_TAG}' \
            cargo test $*"
 else
    log "Running default: cargo test --workspace --no-fail-fast --color always"
    ssh "${SSH_HOST}" \
        "cd '${REMOTE_DIR}' && docker run --rm \
            -v '${REMOTE_DIR}:/workspace' \
            -w /workspace \
            '${IMAGE_TAG}'"
 fi
Author	SHA1	Message	Date
Oleksandr Bezdieniezhnykh	e077d3bd15	[AZ-662] [AZ-669] Close batch 19: green test gate via Jetson Docker ci/woodpecker/push/build-arm Pipeline failed Details Stand up a production-target test runner on jetson-e2e and run the deferred cargo test --workspace for batch 19. Infra: - Dockerfile.test: ubuntu:22.04 + libopencv-dev + libav-dev + libclang-dev + protobuf-compiler + rust 1.82.0 (rustfmt, clippy). Sets LIBCLANG_PATH so clang-sys can dlopen libclang under the opencv-rust clang-runtime path. - scripts/jetson-test.sh: rsync source to jetson-e2e, docker build, docker run cargo test --workspace --no-fail-fast. Workspace fix exposed by the gate: - Cargo.toml: enable opencv "clang-runtime" feature. Without it the workspace fails to build because clang-sys is shared between opencv-binding-generator and bindgen (via ffmpeg-sys-next) and the opencv generator panics with "a `libclang` shared library is not loaded on this thread" (opencv-rust GH issue #635). Batch-19 code bugs exposed by the gate (6 compile errors + 1 algo bug): - movement_detector::optical_flow: min_max_loc signature (opencv 0.98 expects Option<&mut f64> / Option<&mut Point>); data_mut() returns mut u8 directly, not Result. RANSAC residual now filters by the inlier mask returned by find_homography (matches the docstring; was systematically over-reporting motion magnitude on synthetic pure-pan input). - semantic_analyzer::scoring::freshness: same data_mut() fix; stddev_f32 now takes &impl core::ToInputArray so it accepts the BoxedRef<Mat> that Mat::roi returns in opencv 0.98. Result: 391 tests passed across 58 binaries, 0 in-scope failures. Two pre-existing failures in frame_ingest (batch 16-18 scope) are NOT addressed here and are recorded as leftovers: - frame_ingest_cuvid_segv: HIGH severity production bug; libavcodec58 advertises h264_cuvid but libnvcuvid.so.1 is missing at runtime, the software fallback never fires, first send_packet SEGVs. - frame_ingest_publisher_timing_flake: LOW severity; Jetson-specific timing budget too tight for ac1_three_consumers_at_rate_lose_no_frames. Neither blocks batch 20 (movement_detector / semantic_analyzer next). Co-authored-by: Cursor <cursoragent@cursor.com>	2026-05-20 22:11:16 +03:00
Oleksandr Bezdieniezhnykh	202b2cb192	[AZ-662] [AZ-669] Archive batch 19; defer test gate Batch 19 (movement_detector ego-motion + semantic_analyzer primitive graph) is committed at `db844db`. This archival commit: - Writes _docs/03_implementation/batch_19_cycle1_report.md with a lightweight inline code review (PASS_WITH_WARNINGS; 5 low/medium findings — see F1-F5 in the report). - Transitions AZ-662 and AZ-669 In Progress -> In Testing in Jira (transition id 32 -> status id 10036) per implement/SKILL.md Step 12. - Logs _docs/_process_leftovers/2026-05-20_batch19_opencv_test_gate.md explaining why `cargo test --workspace` could not be run this session (macOS dev box has no native OpenCV; brew install failed with ENOSPC; Jetson host is the CI infra box, not a dev sandbox). Replay options documented in the leftover. - Updates _docs/_autodev_state.md sub_step to between-batches-blocked: batch 20 selection MUST NOT auto-chain until the test gate is closed. Cargo.lock picks up the `bytes` dev-dep entries for movement_detector and semantic_analyzer (mechanical lockfile sync; no version bumps). Co-authored-by: Cursor <cursoragent@cursor.com>	2026-05-20 21:27:52 +03:00
Oleksandr Bezdieniezhnykh	db844db232	[AZ-662] [AZ-669] Implement ego-motion estimator and primitive graph AZ-662: movement_detector ego-motion - Add opencv + petgraph to workspace dependencies - internal/zoom_bands: per-band telemetry skew tolerances - internal/telemetry_sync: skew gate (check_skew) - internal/optical_flow: frame→gray, degenerate detection, LK sparse flow + RANSAC homography estimation - internal/ego_motion: EgoMotionEstimator + atomic counters AZ-669: semantic_analyzer primitive graph - internal/primitive_graph: NodeType, PrimitiveNode, PrimitiveGraph, PrimitiveGraphBuilder with proximity-adjacency + BFS connectivity check - internal/scoring/freshness: FreshnessScorer (Laplacian variance, texture stddev, undisturbed-surroundings heuristic) - All ACs covered by unit tests (AC-1/2/3 per task) Note: native OpenCV not installed on macOS; authoritative test is cargo test --workspace on Jetson (ssh jetson-e2e). Co-authored-by: Cursor <cursoragent@cursor.com>	2026-05-20 19:00:39 +03:00
Oleksandr Bezdieniezhnykh	9ed2842c00	chore: clean up batch 18 todo stubs Co-authored-by: Cursor <cursoragent@cursor.com>	2026-05-20 18:33:15 +03:00
Oleksandr Bezdieniezhnykh	72cddc9c42	[AZ-659] [AZ-660] [AZ-661] Archive batch 18; update state and cumulative review Co-authored-by: Cursor <cursoragent@cursor.com>	2026-05-20 18:27:15 +03:00
Oleksandr Bezdieniezhnykh	0854d3be1c	[AZ-659] [AZ-660] [AZ-661] Implement frame publisher + gRPC detection client AZ-659: FramePublisher with per-consumer drop accounting (Arc<Bytes> zero-copy fan-out). Adds ConsumerId enum, PublisherStats, FrameReceiver wrapper, and publisher integration tests (AC-1, AC-2, AC-3). AZ-660: Bi-directional tonic gRPC stream to ../detections. Reconnect with bounded exponential backoff (1 s → 30 s cap). Drop-oldest in-flight budgeting (max_concurrent_in_flight = 2). ai_locked frame skipping. Integration tests against fixture in-process server (AC-1: happy path 30 fps/10 s, AC-2: reconnect, AC-3: budget drops, AC-4: ai_locked skipping). AZ-661: Schema validation (hard SchemaMismatch error on version mismatch), model_version latch with ModelVersionChanged events, sliding-window p99 latency tracker with Tier1Degraded/Tier1Recovered transitions. Integration tests (AC-1, AC-2, AC-3). Also: update module-layout.md for frame_ingest and detection_client to reflect the streaming API shape; code review report batch_18. Co-authored-by: Cursor <cursoragent@cursor.com>	2026-05-20 18:23:56 +03:00
Oleksandr Bezdieniezhnykh	a7df02d434	[autodev] record batch 17 commit hash in state Co-authored-by: Cursor <cursoragent@cursor.com>	2026-05-20 17:33:08 +03:00
Oleksandr Bezdieniezhnykh	c4eff40dbc	[AZ-680] [AZ-681] operator_bridge command dispatch + safety lane Add the operator-command dispatcher behind a typed CommandAck: 60 s per-command-id idempotency cache, surfaced-POI registry with unknown_poi_id + expired gates, BIT-degraded ack severity check, and SafetyOverride forwarding to mission_executor with structured audit log (redacts signature + session_token). Cross-layer wiring goes through three new traits in shared::contracts (ScanCommandRouter, MissionSafetyRouter, BitReportSeverityLookup) so operator_bridge stays free of direct scan_controller / mission_executor imports. scan_controller::ScanControllerHandle implements the scan router; a new mission_executor::SafetyDispatchHandle wraps the BIT ack channel + battery monitor handle and implements the safety router; BitControllerHandle gains a bounded (16-entry) report-severity cache for the lookup trait. scan_controller also picks up ConfirmPoi handling: PoiQueue::confirm removes the entry and SubmitOutcome::Confirmed carries the typed (target_mgrs, target_class) hint for AZ-684/AZ-686 downstream. Tests: 9 new integration tests in operator_bridge/tests/dispatcher.rs cover AZ-680 AC-1..AC-5 + AZ-681 AC-1..AC-4. scan_controller adds 2 ConfirmPoi tests. All modified-crate suites green; one pre-existing mission_executor state-machine test flake (already documented in _docs/_process_leftovers) updated to note ac1 also affected. Co-authored-by: Cursor <cursoragent@cursor.com>	2026-05-20 17:32:59 +03:00
Oleksandr Bezdieniezhnykh	aa4282f9f8	chore: cargo fmt --all (gimbal_controller hygiene) Co-authored-by: Cursor <cursoragent@cursor.com>	2026-05-20 17:32:25 +03:00
		`@@ -0,0 +1,2 @@`
							`pub mod primitive_graph;`
							`pub mod scoring;`
		`@@ -0,0 +1,3 @@`
							`pub mod freshness;`

							`pub use freshness::{FreshnessScorer, PathFreshnessScore};`