# C8 PymavlinkArdupilotAdapter — outbound GPS_INPUT + STATUSTEXT + NAMED_VALUE_FLOAT

**Task**: AZ-393_c8_ardupilot_outbound
**Name**: C8 `PymavlinkArdupilotAdapter` outbound — `GPS_INPUT` 5 Hz + provenance side-channel
**Description**: Implement the `PymavlinkArdupilotAdapter.emit_external_position(EstimatorOutput)` body: encode `EstimatorOutput` into a MAVLink 2.0 `GPS_INPUT` frame (lat/lon/alt from WGS84 conversion via injected `WgsConverter`; `horiz_accuracy` from the injected `CovarianceProjector.to_ardupilot_horiz_accuracy_m`; `vel_n/vel_e/vel_d` from the velocity sub-vector if present in the C5 estimate); write to the pymavlink connection via `mav.gps_input_send(...)`. Side-channel: emit `NAMED_VALUE_FLOAT` with `name="src_lbl"` carrying the `EstimatorOutput.source_label` enum value (encoded as float per the documented enum-to-float mapping); also emit `STATUSTEXT(severity=INFO, "src=<label>")` once per source-label transition (rate-limited — not on every frame). Body of `emit_status_text(msg, severity)` writes pymavlink `STATUSTEXT`. `request_source_set_switch` raises `NotImplementedError("source-set switch owned by AZ-396 task")` — replaced when that task lands. Smoothed-output guard (Invariant 6): `output.smoothed == True` → `FcEmitError`. SPD-violation propagates from `CovarianceProjector` as `FcEmitError`; logged + dropped + continue per § 5 error-handling. Single-writer-thread invariant enforced (Invariant 8). NO signing logic — that's a separate task; `open(...)` here accepts `signing_key=None` for now (signing task replaces this).
**Complexity**: 5 points
**Dependencies**: AZ-390 (Protocol + DTOs), AZ-392 (`CovarianceProjector` helper), AZ-279 (`WgsConverter`), AZ-273 (FDR), AZ-263, AZ-269, AZ-266, AZ-272 (FDR record schema)
**Component**: c8_fc_adapter (epic AZ-261 / E-C8)
**Tracker**: AZ-393
**Epic**: AZ-261 (E-C8)

### Document Dependencies

- `_docs/02_document/contracts/c8_fc_adapter/fc_adapter_protocol.md` — Invariants 3, 4, 5, 6, 8.
- `_docs/02_document/components/10_c8_fc_adapter/description.md` — § 3 External API (MAVLink 2.0), § 5 implementation details.
- `_docs/02_document/architecture.md` — § 5 External Integrations.

## Problem

Without this task, AP-targeted flights cannot run: there is no GPS_INPUT being emitted to ArduPilot's EKF, and the provenance side-channel (`source_label` via NAMED_VALUE_FLOAT + STATUSTEXT) is not feeding GCS observability. The C5 emit driver has no sink.

## Outcome

- `src/gps_denied_onboard/components/c8_fc_adapter/pymavlink_ardupilot_adapter.py` — `PymavlinkArdupilotAdapter` class implementing `FcAdapter`.
- Constructor: `__init__(self, config, wgs_converter, covariance_projector, fdr_client, clock)`.
- Body of `emit_external_position` — encode + emit `GPS_INPUT`; emit `NAMED_VALUE_FLOAT(name="src_lbl")` every frame; emit `STATUSTEXT` on `source_label` transition (rate-limited).
- Body of `emit_status_text` — pymavlink `statustext_send`.
- Body of `open(...)` — open pymavlink connection on the configured port with `mavlink_version=2`; reject `signing_key=None` only when the signing task has landed (this task accepts None and emits unsigned frames; a follow-up integration step in the signing task converts this to require non-None).
- Body of `close()` — flush pending writes, close connection.
- `request_source_set_switch` raises `NotImplementedError("Owned by source-set task; install AZ-396 to enable")`.
- `current_flight_state` already implemented by AZ-391 (inbound task) — this task just doesn't override it.
- INFO log on first successful `GPS_INPUT` emit: `kind="c8.ap.first_emit"`.
- DEBUG log per emit: `kind="c8.ap.emit"` with `{frame_seq, horiz_accuracy_m, source_label}`.
- ERROR log on `FcEmitError`: `kind="c8.ap.emit_failed"` with reason.

## Scope

### Included
- `PymavlinkArdupilotAdapter` class implementing `FcAdapter`.
- `GPS_INPUT` encoding from `EstimatorOutput`.
- `NAMED_VALUE_FLOAT` source-label side-channel (every frame).
- `STATUSTEXT` source-label transition (rate-limited).
- `emit_status_text` body.
- `open` / `close` body (without signing — placeholder).
- Unit tests: encoding fidelity (decode the bytes back via pymavlink + assert fields); rate-limited STATUSTEXT (no flood); smoothed-output rejected; non-SPD covariance rejected; single-writer-thread enforcement.

### Excluded
- MAVLink 2.0 signing handshake — owned by signing task.
- D-C8-2 source-set switch — owned by source-set task.
- iNav adapter — owned by iNav outbound task.
- GCS adapter — owned by GCS task.
- Inbound subscribe (already implemented in `_inbound_mavlink.py` via AZ-391 — this class composes it).
- `current_flight_state` body — already implemented in inbound task.
- C8-IT/PT/ST tests — deferred to E-BBT.

## Acceptance Criteria

**AC-1: GPS_INPUT field fidelity** — emit a known `EstimatorOutput`; decode the wire bytes via pymavlink; assert lat/lon/alt match WgsConverter output; `horiz_accuracy` matches `CovarianceProjector.to_ardupilot_horiz_accuracy_m(cov_6x6)` to within 1e-3 m.

**AC-2: GPS_INPUT every frame** — drive 100 frames; assert exactly 100 `GPS_INPUT` messages on the wire.

**AC-3: NAMED_VALUE_FLOAT every frame** — drive 100 frames; assert 100 `NAMED_VALUE_FLOAT` messages with `name="src_lbl"`; values match the source-label-to-float mapping.

**AC-4: STATUSTEXT rate-limited on transition** — drive 100 frames with `source_label` toggling every 10 frames; assert exactly 10 `STATUSTEXT` messages (one per transition); within-state frames emit zero STATUSTEXT.

**AC-5: Smoothed output rejected** — emit an `EstimatorOutput` with `smoothed=True`; assert `FcEmitError` raised + `kind="c8.ap.emit_failed"` logged + no GPS_INPUT on the wire.

**AC-6: Non-SPD covariance rejected** — emit an `EstimatorOutput` with non-SPD `covariance_6x6`; assert `FcEmitError` raised (propagated from `CovarianceProjector`) + log + no GPS_INPUT.

**AC-7: Single-writer thread** — call `emit_external_position` from a second thread; assert `RuntimeError`.

**AC-8: Open without signing key (placeholder)** — `open(port, signing_key=None)` succeeds in this task's context; signing task tightens this to reject None.

**AC-9: source-set switch raises NotImplementedError** — `request_source_set_switch()` raises with the message `"Owned by source-set task; install AZ-396 to enable"`.

**AC-10: First emit logged once** — the `kind="c8.ap.first_emit"` INFO log fires exactly once per `open(...)` lifetime.

## Non-Functional Requirements

- `emit_external_position` p95 ≤ 5 ms (C8-PT-01 budget).
- p99 ≤ 8 ms (defensive headroom).

## Constraints

- pymavlink bundled unmodified per D-C8-3.
- Single-writer thread enforced.
- The source-label-to-float encoding mapping MUST be documented inline + match the operator-side decoder (E-C12).
- STATUSTEXT rate-limit: at most 1 per source-label transition AND at most 1 per second per severity (defensive against pathological transition spam).

## Risks & Mitigation

- **Risk: pymavlink GPS_INPUT field semantics differ across ArduPilot versions** — *Mitigation*: pinned pymavlink version + integration test against the targeted ArduPilot Plane firmware (verified in IT-3 SITL).
- **Risk: STATUSTEXT flood under rapid source-label transitions** — *Mitigation*: AC-4 verifies one-per-transition; secondary 1 Hz cap as a safety net.
- **Risk: NAMED_VALUE_FLOAT name truncation** — *Mitigation*: `"src_lbl"` is 7 chars (within MAVLink 10-char limit).

## Runtime Completeness

- **Named capability**: AP outbound external-position emission with provenance side-channel.
- **Production code**: real pymavlink encode + send; real WgsConverter + CovarianceProjector usage; real STATUSTEXT rate-limit.
- **Unacceptable substitutes**: a fake `GPS_INPUT` builder that doesn't go through pymavlink (defeats AC-1 wire-level fidelity).

## Contract

Implements `_docs/02_document/contracts/c8_fc_adapter/fc_adapter_protocol.md` — `emit_external_position`, `emit_status_text` for AP; Invariants 3, 4, 5, 6, 8.