feat(diagnostics): split error and shutdown messages

docs/src/architecture.md

@@ -63,15 +63,17 @@ persistence, authenticated ingress, durable audit logging, disarmed
 activation, and atomic consumer reconstruction remain separate reviewed work
 and cannot be implied by a valid CBOR file or CRC.
 
-The MAVLink dialect root includes `kaptan/config.xml` and `kaptan/log.xml`.
+The MAVLink dialect root includes `kaptan/config.xml`, `kaptan/log.xml`,
+`kaptan/error.xml`, and `kaptan/shutdown.xml`.
 The build watches every fragment and generates one `message::kaptan` module;
 fragments are never separately generated Rust modules. `kaptan-log` itself has
 no MAVLink, platform, time, allocation, filesystem, or configuration
 dependency. It assigns bounded Critical and BestEffort queues for text logs.
-The platform drains a record only after TX admission; the diagnostic wire
-contract deliberately contains only severity, flags, bounded text length, and
-text. Local saturation accounting remains inside the hub, facade, and producer
-mailboxes; heartbeat and safety telemetry remain separate from diagnostic text.
+The platform drains a record only after TX admission. `KAPTAN_LOG` carries
+severity plus one bounded text field; `KAPTAN_ERROR` carries flags plus bounded
+path and additional-information fields. Local saturation accounting remains
+inside the hub, facade, and producer mailboxes; heartbeat and safety telemetry
+remain separate from diagnostics.
 
 See [Configuration](configuration.md) for the deployment matrix and GCS upload
 contract, [Logs](logs.md) for the receiver contract, and [Errors](errors.md)

docs/src/errors.md

@@ -11,10 +11,10 @@ enum SensorError {
 ```
 
 The derive implements `core::error::Error`, `Display`, and `ErrorReport`. It
-creates a bounded human-facing `module::Type::Variant` message without
-allocating, publishing telemetry, exposing generic source values, or changing
-safety state. Renaming a module, type, or variant changes that text; it is not
-a stable machine protocol identity.
+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
@@ -26,17 +26,22 @@ for safety state, actuator inhibit, or typed configuration results.
 - 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
-  `KAPTAN_ERROR` text, subject to bounded transport admission. The message
-  carries no per-error numeric catalog: a `KaptanError` derive supplies its
-  type/variant display identity.
+- 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`
-  containing the high-level `ProtocolError` identity. It is intentionally not
-  correlated and carries no field/rule detail; the matching
+  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` represents only a future completed orderly,
+- `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.

docs/src/logs.md

@@ -18,28 +18,35 @@ messages later.
 
 ## Receiver contract
 
-`definitions/kaptan/log.xml` separates ordinary logs from errors:
+`definitions/kaptan/log.xml`, `definitions/kaptan/error.xml`, and
+`definitions/kaptan/shutdown.xml` separate ordinary logs, errors, and
+orderly-shutdown observations:
 
 ```text
 KAPTAN_LOG { level, flags, message_length, message[160] }
-KAPTAN_ERROR { flags, message_length, message[160] }
+KAPTAN_ERROR {
+  flags, path_length, additional_information_length,
+  path[96], additional_information[64]
+}
 KAPTAN_SHUTDOWN { reason }
 ```
 
-A receiver generated from the same `kaptan.xml` revision validates
-`message_length <= 160` and decodes exactly that UTF-8 prefix. `KAPTAN_LOG`
-displays its text at the MAVLink severity in `level`; `TRACE` is encoded as
-`DEBUG` plus the `TRACE` flag. `KAPTAN_ERROR` is error-only and accepts only
-`TRUNCATED` and `COALESCED`; a `TRACE` bit is never emitted there. Unknown
-future flag bits must be ignored.
+A GCS decoder generated from the same `kaptan.xml` revision must validate
+`message_length <= 160` for `KAPTAN_LOG`, and `path_length <= 96` plus
+`additional_information_length <= 64` for `KAPTAN_ERROR`, before slicing the
+fixed arrays into UTF-8 prefixes. Generated MAVLink framing alone does not
+enforce these semantic length fields. `KAPTAN_LOG` displays its text at the
+MAVLink severity in `level`; `TRACE` is encoded as `DEBUG` plus the `TRACE`
+flag.
+`KAPTAN_ERROR` is error-only and accepts only `TRUNCATED` and `COALESCED`; a
+`TRACE` bit is never emitted there. Unknown future flag bits must be ignored.
 
-The derived error display text is intentionally not a numeric error catalog;
-renaming its Rust module/type/variant changes the display identity. Error
-details requiring machine action stay in their owning protocol, notably
-`KAPTAN_CONFIG_RESULT`. `KAPTAN_SHUTDOWN` has only its typed reason and is
-valid only after an orderly output-inhibited completion. Delivery is bounded
-and lossy under link pressure; heartbeat and safety telemetry use separate
-paths.
+The derived error path is intentionally not a numeric error catalog; renaming
+its Rust module/type/variant changes that identity. Error details requiring
+machine action stay in their owning protocol, notably `KAPTAN_CONFIG_RESULT`.
+`KAPTAN_SHUTDOWN` has only its typed reason and is valid only after an orderly
+output-inhibited completion. Delivery is bounded and lossy under link pressure;
+heartbeat and safety telemetry use separate paths.
 
 ## Filtering
 

docs/src/mavlink.md

@@ -19,8 +19,9 @@ replace pending best-effort traffic, but never the DMA-owned active buffer.
 Completion retries preserve ordering and retain a transiently busy frame for a
 later service turn.
 
-The custom Kaptan configuration and log definitions are aggregated by
-`definitions/kaptan.xml` from `kaptan/config.xml` and `kaptan/log.xml`.
+The custom Kaptan definitions are aggregated by `definitions/kaptan.xml` from
+`kaptan/config.xml`, `kaptan/log.xml`, `kaptan/error.xml`, and
+`kaptan/shutdown.xml`.
 `KAPTAN_LOG` is an outbound human-readable four-field record. `KAPTAN_ERROR`
 is its separate bounded error channel, while `KAPTAN_SHUTDOWN` represents only
 a completed orderly output-inhibited shutdown. Configuration messages are GCS

docs/src/reference.md

@@ -8,7 +8,7 @@ This page collects stable limits and points to the detailed contracts.
 | SITL file | Private `[generation, raw-profile-blob]` envelope; not a MAVLink upload blob. |
 | Config transaction | One owner-bound RAM transaction; typed writes or 192-byte idempotent CBOR chunks; commit is restart-required. |
 | Config discovery | Correlated `KAPTAN_CONFIG_INFO_REQUEST` / `KAPTAN_CONFIG_INFO`, then descriptor/value requests. |
-| Diagnostics | `KAPTAN_LOG` (51020) for ordinary severity/text, `KAPTAN_ERROR` (51021) for bounded errors, and `KAPTAN_SHUTDOWN` (51022) for completed orderly output-inhibited shutdowns. |
+| Diagnostics | `KAPTAN_LOG` (51020) for ordinary severity/text; `KAPTAN_ERROR` (51021) for a bounded `{ path[96], additional_information[64] }` error; and `KAPTAN_SHUTDOWN` (51022) for completed orderly output-inhibited shutdowns. |
 | F722 configuration | Immutable compiled board policy only; inbound MAVLink configuration remains disabled. |
 
 Read [Configuration](configuration.md) for the field/consumer matrix and GCS