# Ticket: Report HPT export-domain failure reasons

Status: complete
Type: ticket
Updated: 2026-08-11
Next Action: none; retain the separate bounded-export latency ticket
Parent: work/wp/active/wp-triple-mirrored-circular-hpt-log-store.md
Project Map: work/maps/map-smi-firmware-stabilization-and-qualification.md

## Problem

A request older than the retained circular window currently reaches the same
generic `Copying log data` error used for corruption. The operator cannot tell
whether to choose a newer range, replace the SD card, or replace the USB stick.

## Required contract

Add an export-domain reason that is independent of raw HPT/SSP/USB status:

| Reason | Meaning |
| --- | --- |
| `RANGE_NOT_RETAINED` | request starts before the true oldest retained customer record |
| `RETAINED_DATA_GAP` | expected data is absent or ambiguous inside advertised retained bounds |
| `HPT_MEDIA_IO` | HPT/driver read or reopen failed |
| `USB_IO` | USB create/write/flush/close/verify/rename failed |
| `INVALID_REQUEST` | date/range violates request policy |
| `EXPORT_CAPACITY` | request exceeds bounded staging/export capacity |

The public status must also expose the true oldest/newest retained timestamps
and sequences, first failure sequence, underlying HPT status, USB status, and
gap counts. Customer messages must prescribe the appropriate correction and
must not call out-of-retention data corrupt.

## Acceptance criteria

- [x] Retained bounds come from the current circular snapshot, not a stale
  pre-reclaim sequence.
- [x] Out-of-retention requests fail before USB publication with
  `RANGE_NOT_RETAINED`.
- [x] Gaps inside advertised retained bounds fail closed as
  `RETAINED_DATA_GAP`.
- [x] HPT and USB failures retain their underlying diagnostic codes.
- [x] No failure leaves a finalized partial CSV; temporary artifacts are
  removed or explicitly reported.
- [x] Existing valid 10-minute and wrap-spanning export behavior remains in
  the unchanged publication path and deterministic regression model.
- [x] Host/model tests cover all six reasons, exact boundary timestamps,
  wrap/reclaim, zero records, degraded quorum records, and USB failure at every
  publication boundary.
- [x] HMI tests verify the reason-to-message mapping and progress-screen
  terminal behavior.
- [x] Clean Debug and Release builds pass.

Software-gate evidence:
`work/evidence/hpt-log-store-circular-mirror/software-completion-gate-20260724.md`.

Final message review, target-evidence reconciliation, current regression
results, and build/package hashes:
`work/evidence/hpt-operator-failure-message-closeout-20260811.md`.

## Source surfaces

- `src/SdCardService.h`
- `src/Thread_SdCard_entry.c`
- `src/Thread_Usb_entry.c`
- `src/HMI_MainEventHandler.c`

## Basis

Promoted from
`work/spikes/spike-clarify-hpt-export-retention-range-messaging.md`.
