# Middle-Waypoint POST

**Task**: AZ-645_mission_client_waypoint_post
**Name**: Middle-waypoint POST to missions API
**Description**: POST the updated mission (with operator-confirmed middle waypoint inserted) to the external `missions` API; bounded retry; surface failure to `mission_executor`.
**Complexity**: 2 points
**Dependencies**: AZ-640_initial_structure, AZ-644_mission_client_pull_and_schema
**Component**: mission_client
**Tracker**: AZ-645
**Epic**: AZ-638

## Problem

When the operator confirms a POI, `scan_controller` hands a middle-waypoint hint to `mission_executor`, which computes the patched mission (`current_position → middle_waypoint → resume_original_route`). That patched mission must be POSTed to the external `missions` API for persistence and traceability. If the POST fails, the executor decides whether to halt, RTL, or continue with the in-memory mission — `mission_client` only surfaces the failure.

## Outcome

- `MissionClient::post_middle_waypoint(mission_id, patched_mission) -> Result<MissionUpdateAck, PostError>` performs a `POST /missions/{id}/middle-waypoint` (exact path per `../_docs/02_missions.md`) and awaits an ack.
- Bounded exponential backoff on transient failure (default 3 attempts).
- On final failure returns a typed error; never silent.
- Health field `last_middle_waypoint_post_status` updated.

## Scope

### Included
- POST endpoint call with the patched mission body.
- Bounded retry on 5xx / timeout.
- Error surface to caller.

### Excluded
- The decision to RTL on failure (`mission_executor`).
- Recomputing the patched mission (`mission_executor`).

## Acceptance Criteria

**AC-1: Happy path POST**
Given a fixture missions API that accepts the POST and returns `200`
When `post_middle_waypoint("M1", patched)` is called
Then it returns `Ok(MissionUpdateAck { ... })` within ≤2 s and `health.last_middle_waypoint_post_status = "ok"`.

**AC-2: Transient failure retries**
Given the API returns `503` once then `200`
When the call is made
Then it returns `Ok` on the second attempt.

**AC-3: Cap exhaustion bubbles error**
Given the API returns `500` for all 3 default attempts
When the call is made
Then it returns `Err(MaxRetriesExceeded)` and the error is surfaced to the caller; no silent absorption.

## Non-Functional Requirements

**Performance**
- Single happy-path POST completes in ≤2 s on healthy connectivity.

**Reliability**
- Bounded backoff; no infinite retry.

## Runtime Completeness

- **Named capability**: middle-waypoint POST against the external `missions` API.
- **Production code that must exist**: real HTTPS POST.
- **Allowed external stubs**: `wiremock`/`mockito` for tests.
- **Unacceptable substitutes**: swallowing the error and proceeding is not acceptable.
