# Errors

Public Kaptan error enums derive the pure `KaptanError` implementation:

```rust
#[derive(Debug, kaptan_log::KaptanError)]
enum SensorError {
    TransferFault,
    UnexpectedIdentity(u8),
}
```

The derive implements `core::error::Error`, `Display`, and `ErrorReport`. It
creates a static `module::Type::Variant` error path without allocating,
publishing telemetry, exposing generic source values, or changing safety
state. Renaming a module, type, or variant changes that path; it is not a
stable machine protocol identity.

Normal-task code may use `log::error!("{error}")`; it is routed as a bounded
`KAPTAN_ERROR`. ISR-adjacent flight paths may enqueue the derived static
message through their existing bounded mailbox. Neither route is a replacement
for safety state, actuator inhibit, or typed configuration results.

## What the receiver sees

- Configuration writes receive authoritative structured failures through
  `KAPTAN_CONFIG_RESULT`: operation, lifecycle state, field IDs, validation
  rule, and protocol error code.
- Runtime driver and link faults reach the F722 MAVLink worker as a
  `KAPTAN_ERROR` path, subject to bounded transport admission. The error
  payload is `{ flags, path_length, additional_information_length, path[96],
  additional_information[64] }`; each length identifies the valid UTF-8
  prefix and the optional information field may be empty. A `KaptanError`
  derive supplies the type/variant path and normally leaves additional
  information empty. `log::error!` uses the Rust log target as the path and
  the formatted message as additional information.
- A rejected configuration operation may enqueue a companion `KAPTAN_ERROR`
  whose path is the high-level `ProtocolError` identity. It is intentionally
  not correlated and carries no field/rule detail; the matching
  `KAPTAN_CONFIG_RESULT` remains the sole precise authority.
- Control, navigation, safety, and simulator error types are derive-ready but
  their live owners are not yet attached to a MAVLink worker.
- `KAPTAN_SHUTDOWN`, defined in `definitions/kaptan/shutdown.xml`, represents
  only a future completed orderly,
  output-inhibited shutdown. It is not a shutdown request, panic, hard-fault,
  reset, or retention-record protocol. F722 still uses `panic-halt`; it does
  not claim a live panic frame or retained-record replay.

No diagnostic message may synchronously transmit from a panic handler, hard
fault, ISR, DMA callback, or motor-inhibit path. A later target integration
must inhibit outputs first, persist a validated crash record, then report it
only after the next boot’s static board telemetry is available.