feat(error): add ErrorClassification trait for triage-friendly Error<Kind> categories

Introduces ironrdp_error::{ErrorCategory, ErrorClassification} so consumers
can route errors by coarse category (Protocol, DataCorruption, InternalBug,
Unknown) without inspecting Display strings. Adds a convenience
Error<Kind>::classify() method that is available when Kind: ErrorClassification.

Implements the trait for the two foundational Kind types in ironrdp-core:
DecodeErrorKind classifies all structured variants as Protocol (peer-driven
wire-format failures) and Other as Unknown; EncodeErrorKind classifies all
structured variants as InternalBug (we miscalculated something in our own
serialisation path) and Other as Unknown. ironrdp-core re-exports the trait
and enum so consumers can pull them via the same crate they already use for
DecodeError/EncodeError type aliases.

Primary consumer is the structured-fuzzing oracle code in ironrdp-fuzzing
tracked under #1120: categories let an oracle distinguish "decoder
correctly rejected malformed input" from "decoder hit an internal invariant
violation" without inspecting Display strings. The DataCorruption category
is defined now and reserved for the deeper-validation variants that other
*ErrorKind enums in the workspace will adopt in follow-on PRs.

Refs #1257, #1120.

Author: Greg Lamberson

crates/ironrdp-core/src/decode.rs

@@ -2,6 +2,8 @@
 use alloc::string::String;
 use core::fmt;
 
+use ironrdp_error::{ErrorCategory, ErrorClassification};
+
 use crate::{
     InvalidFieldErr, NotEnoughBytesErr, OtherErr, ReadCursor, UnexpectedMessageTypeErr, UnsupportedValueErr,
     UnsupportedVersionErr,
@@ -66,6 +68,23 @@ pub enum DecodeErrorKind {
 #[cfg(feature = "std")]
 impl core::error::Error for DecodeErrorKind {}
 
+impl ErrorClassification for DecodeErrorKind {
+    fn classify(&self) -> ErrorCategory {
+        // All structured variants are peer-driven: the input came from the
+        // wire and failed to conform to the spec at some level. `Other` is
+        // a free-form catch-all that cannot be classified without inspecting
+        // the description, so it stays `Unknown`.
+        match self {
+            Self::NotEnoughBytes { .. }
+            | Self::InvalidField { .. }
+            | Self::UnexpectedMessageType { .. }
+            | Self::UnsupportedVersion { .. }
+            | Self::UnsupportedValue { .. } => ErrorCategory::Protocol,
+            Self::Other { .. } => ErrorCategory::Unknown,
+        }
+    }
+}
+
 impl fmt::Display for DecodeErrorKind {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         match self {

crates/ironrdp-core/src/encode.rs

@@ -4,6 +4,8 @@ use alloc::string::String;
 use alloc::{vec, vec::Vec};
 use core::fmt;
 
+use ironrdp_error::{ErrorCategory, ErrorClassification};
+
 #[cfg(feature = "alloc")]
 use crate::WriteBuf;
 use crate::{
@@ -70,6 +72,24 @@ pub enum EncodeErrorKind {
 #[cfg(feature = "std")]
 impl core::error::Error for EncodeErrorKind {}
 
+impl ErrorClassification for EncodeErrorKind {
+    fn classify(&self) -> ErrorCategory {
+        // Encode errors are produced by our own code while serialising data
+        // we constructed; every structured variant indicates we hit an
+        // internal invariant violation (under-sized buffer, attempting to
+        // write an out-of-range value, etc.). `Other` is a free-form
+        // catch-all and stays `Unknown`.
+        match self {
+            Self::NotEnoughBytes { .. }
+            | Self::InvalidField { .. }
+            | Self::UnexpectedMessageType { .. }
+            | Self::UnsupportedVersion { .. }
+            | Self::UnsupportedValue { .. } => ErrorCategory::InternalBug,
+            Self::Other { .. } => ErrorCategory::Unknown,
+        }
+    }
+}
+
 impl fmt::Display for EncodeErrorKind {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         match self {

crates/ironrdp-core/src/lib.rs

@@ -22,6 +22,8 @@ mod write_buf;
 
 // Flat API hierarchy of common traits and types
 
+pub use ironrdp_error::{ErrorCategory, ErrorClassification};
+
 pub use self::as_any::*;
 pub use self::cursor::*;
 pub use self::decode::*;

crates/ironrdp-error/src/lib.rs

@@ -26,6 +26,65 @@ struct ErrorMeta {
     source: Option<Box<dyn Source>>,
 }
 
+/// Coarse category assigned to a `*ErrorKind` variant by [`ErrorClassification`],
+/// used to drive triage logic that does not depend on the specific kind shape.
+///
+/// The intended primary consumer is the structured-fuzzing oracle code in
+/// `ironrdp-fuzzing`, which uses the category to distinguish "the decoder
+/// correctly rejected malformed input" from "the decoder hit an internal
+/// invariant violation" without parsing `Display` strings.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
+#[non_exhaustive]
+pub enum ErrorCategory {
+    /// Wire-protocol violation by the peer: the input does not conform to the
+    /// specification (invalid field, unsupported version, unexpected message
+    /// type, premature end of input, etc.).
+    ///
+    /// For a fuzz oracle, this is the expected outcome when fuzzing decoders
+    /// with arbitrary bytes: the decoder caught a malformed input.
+    Protocol,
+
+    /// Logical inconsistency in otherwise spec-conformant data: the peer
+    /// sent something whose individual fields parse but whose meaning is
+    /// internally contradictory (e.g. mismatched lengths, impossible
+    /// references, failed integrity checks).
+    ///
+    /// For a fuzz oracle, this is also an expected rejection; treated
+    /// separately from [`ErrorCategory::Protocol`] because the diagnostic
+    /// implications differ (deeper validation logic was reached before the
+    /// rejection).
+    DataCorruption,
+
+    /// Internal invariant violation in our own code: an unexpected state
+    /// was reached that should not occur for any valid or invalid input.
+    ///
+    /// For a fuzz oracle, this is the bug signal: the kind of failure that
+    /// should be minimized to a crasher and reported.
+    InternalBug,
+
+    /// Classification not specified for this variant. Either the `Kind`
+    /// type has not yet been audited to assign categories to all its
+    /// variants, or the variant is intentionally left uncategorized
+    /// pending design decisions.
+    Unknown,
+}
+
+/// Assigns an [`ErrorCategory`] to each variant of a `*ErrorKind` enum.
+///
+/// Implement on the `Kind` type carried by [`Error<Kind>`]. Once implemented,
+/// [`Error::classify`] becomes available on `Error<Kind>` and forwards to this
+/// trait's [`classify`](Self::classify) method.
+///
+/// Per the [`ErrorCategory`] documentation, the primary consumer is the
+/// structured-fuzzing oracle code. Other consumers may include diagnostic
+/// logging that routes errors to different sinks based on category, or
+/// integration tests that assert on the expected category of an induced
+/// failure without depending on the specific variant shape.
+pub trait ErrorClassification {
+    /// Returns the category for this variant.
+    fn classify(&self) -> ErrorCategory;
+}
+
 /// A typed error wrapper carrying a `Kind` discriminant plus diagnostic metadata.
 ///
 /// # `no_alloc` platforms
@@ -157,6 +216,19 @@ impl<Kind> Error<Kind> {
     }
 }
 
+impl<Kind> Error<Kind>
+where
+    Kind: ErrorClassification,
+{
+    /// Returns the [`ErrorCategory`] of this error, forwarded from the
+    /// inner `Kind` via its [`ErrorClassification`] impl.
+    ///
+    /// Only available when `Kind` implements [`ErrorClassification`].
+    pub fn classify(&self) -> ErrorCategory {
+        self.kind.classify()
+    }
+}
+
 impl<Kind> fmt::Display for Error<Kind>
 where
     Kind: fmt::Display,