feat(log): add bounded diagnostic transport

libs/kaptan-mavlink/src/transmitter.rs

@@ -1,6 +1,7 @@
 //! MAVLink frame encoding and UART transmission API.
 
 use kaptan_dma::{DmaTxBufferFactory, DmaTxEngine, TxCompletion};
+use kaptan_log::KaptanError;
 use kaptan_tx::{PendingFrame, TransmitQueue};
 
 use crate::MavlinkFrame;
@@ -9,7 +10,7 @@ use crate::MavlinkFrame;
 pub use kaptan_tx::{EnqueueResult, FrameClass};
 
 /// Failure while preparing or starting a MAVLink frame transfer.
-#[derive(Debug)]
+#[derive(Debug, KaptanError)]
 pub enum MavlinkTransmitFault<MemoryError, EngineError> {
     /// DMA-visible frame preparation failed.
     Memory(MemoryError),
@@ -17,6 +18,40 @@ pub enum MavlinkTransmitFault<MemoryError, EngineError> {
     Engine(EngineError),
 }
 
+/// Transport-neutral class of a terminal link fault.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum TransmitFaultKind {
+    /// DMA-visible frame preparation failed.
+    Memory,
+    /// The UART DMA engine rejected a transfer start.
+    Engine,
+    /// An active DMA transfer ended with a terminal fault or halt.
+    Terminal,
+}
+
+impl<MemoryError, EngineError> MavlinkTransmitFault<MemoryError, EngineError> {
+    /// Returns the bounded category a platform may convert to a static log
+    /// message without exposing a generic HAL error value on the wire.
+    pub const fn kind(&self) -> TransmitFaultKind {
+        match self {
+            Self::Memory(_) => TransmitFaultKind::Memory,
+            Self::Engine(_) => TransmitFaultKind::Engine,
+        }
+    }
+}
+
+/// Combined bounded-admission and DMA-start outcome.
+///
+/// The two outcomes stay distinct so a platform can account for a failed DMA
+/// start without falsely treating a queue-full source frame as retained.
+#[must_use]
+pub struct AdmissionStart<MemoryError, EngineError> {
+    /// Queue admission for the source frame.
+    pub admission: EnqueueResult,
+    /// One bounded attempt to start pending DMA work.
+    pub start: Result<(), MavlinkTransmitFault<MemoryError, EngineError>>,
+}
+
 /// Owns MAVLink frame admission and UART DMA lifecycle.
 ///
 /// Exactly one worker invokes this type. It accepts local encoded frames and
@@ -54,8 +89,23 @@ where
         class: FrameClass,
         frame: MavlinkFrame,
     ) -> Result<EnqueueResult, MavlinkTransmitFault<Memory::Error, Engine::StartError>> {
+        let outcome = self.admit_and_start(class, frame);
+        outcome.start.map(|()| outcome.admission)
+    }
+
+    /// Admits one frame and attempts one bounded DMA start while preserving
+    /// both outcomes. Platform policy uses this to account for a failed DMA
+    /// start without mistaking an admission rejection for a retained frame.
+    /// A start failure retains the selected frame in the queue reservation for
+    /// a later service-turn retry.
+    pub fn admit_and_start(
+        &mut self,
+        class: FrameClass,
+        frame: MavlinkFrame,
+    ) -> AdmissionStart<Memory::Error, Engine::StartError> {
         let admission = self.enqueue_frame(class, frame);
-        self.start_pending().map(|()| admission)
+        let start = self.start_pending();
+        AdmissionStart { admission, start }
     }
 
     /// Admits a frame without attempting to start the DMA engine.