Structured error codes: E1000-E5000, no user-facing text in library

Error codes:
 1000-1001: device errors (not found, permission)
 2000-2002: profile errors (unsupported, not found, parse)
 3000-3003: unlock errors (failed, signature, not unlocked, not calibrated)
 4000-4001: SCSI errors (command failed, timeout)
 5000: I/O errors

All errors carry structured data (vendor_id, opcode, etc).
Applications format their own user-facing messages.
Library returns code + data, never English text.

src/error.rs

@@ -1,45 +1,108 @@
-use std::fmt;
+/// libfreemkv error codes.
+///
+/// The library returns structured error codes with context data.
+/// Applications are responsible for formatting user-facing messages.
+/// This keeps the library locale-independent and testable.
 
+/// Error code table.
+///
+/// | Code | Name | Meaning |
+/// |------|------|---------|
+/// | 1000 | DeviceNotFound | Device path doesn't exist or can't be opened |
+/// | 1001 | DevicePermission | Device exists but permission denied |
+/// | 2000 | UnsupportedDrive | Drive not in profile database |
+/// | 2001 | ProfileNotFound | Specific firmware version not in database |
+/// | 2002 | ProfileParse | Profile database is malformed |
+/// | 3000 | UnlockFailed | Drive rejected unlock command |
+/// | 3001 | SignatureMismatch | Wrong signature returned by drive |
+/// | 3002 | NotUnlocked | Raw read attempted before unlock |
+/// | 3003 | NotCalibrated | Raw read attempted before calibrate |
+/// | 4000 | ScsiError | SCSI command failed |
+/// | 4001 | ScsiTimeout | SCSI command timed out |
+/// | 5000 | IoError | OS-level I/O error |
 #[derive(Debug)]
 pub enum Error {
-    DeviceNotFound(String),
-    UnsupportedDrive(String),
-    ScsiError { cdb: Vec<u8>, status: u8, sense: Vec<u8> },
-    UnlockFailed(String),
+    // 1xxx — Device errors
+    DeviceNotFound { path: String },
+    DevicePermission { path: String },
+
+    // 2xxx — Profile errors
+    UnsupportedDrive { vendor_id: String, product_id: String, product_revision: String },
+    ProfileNotFound { vendor_id: String, product_revision: String, vendor_specific: String },
+    ProfileParse { detail: String },
+
+    // 3xxx — Unlock errors
+    UnlockFailed { detail: String },
+    SignatureMismatch { expected: [u8; 4], got: [u8; 4] },
     NotUnlocked,
     NotCalibrated,
-    ProfileNotFound(String),
-    ProfileParse(String),
-    SignatureMismatch { expected: [u8; 4], got: [u8; 4] },
-    Io(std::io::Error),
+
+    // 4xxx — SCSI errors
+    ScsiError { opcode: u8, status: u8, sense_key: u8 },
+    ScsiTimeout { opcode: u8 },
+
+    // 5xxx — I/O errors
+    IoError { source: std::io::Error },
 }
 
-impl fmt::Display for Error {
-    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+impl Error {
+    /// Numeric error code for programmatic handling.
+    pub fn code(&self) -> u16 {
         match self {
-            Error::DeviceNotFound(s) => write!(f, "device not found: {s}"),
-            Error::UnsupportedDrive(s) => write!(f, "unsupported drive: {s}"),
-            Error::ScsiError { status, .. } => write!(f, "SCSI error: status 0x{status:02x}"),
-            Error::UnlockFailed(s) => write!(f, "unlock failed: {s}"),
-            Error::NotUnlocked => write!(f, "drive not unlocked, call unlock() first"),
-            Error::NotCalibrated => write!(f, "speed not calibrated, call calibrate() first"),
-            Error::ProfileNotFound(s) => write!(f, "no profile for: {s}"),
-            Error::ProfileParse(s) => write!(f, "profile parse error: {s}"),
-            Error::SignatureMismatch { expected, got } => {
-                write!(f, "signature mismatch: expected {:02x}{:02x}{:02x}{:02x}, got {:02x}{:02x}{:02x}{:02x}",
-                    expected[0], expected[1], expected[2], expected[3],
-                    got[0], got[1], got[2], got[3])
-            }
-            Error::Io(e) => write!(f, "I/O error: {e}"),
+            Error::DeviceNotFound { .. }    => 1000,
+            Error::DevicePermission { .. }  => 1001,
+            Error::UnsupportedDrive { .. }  => 2000,
+            Error::ProfileNotFound { .. }   => 2001,
+            Error::ProfileParse { .. }      => 2002,
+            Error::UnlockFailed { .. }      => 3000,
+            Error::SignatureMismatch { .. } => 3001,
+            Error::NotUnlocked              => 3002,
+            Error::NotCalibrated            => 3003,
+            Error::ScsiError { .. }         => 4000,
+            Error::ScsiTimeout { .. }       => 4001,
+            Error::IoError { .. }           => 5000,
         }
     }
 }
 
-impl std::error::Error for Error {}
+/// Default Display — terse, for logs. Applications should format their own messages.
+impl std::fmt::Display for Error {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Error::DeviceNotFound { path } => write!(f, "E1000: device not found: {path}"),
+            Error::DevicePermission { path } => write!(f, "E1001: permission denied: {path}"),
+            Error::UnsupportedDrive { vendor_id, product_id, product_revision } =>
+                write!(f, "E2000: unsupported drive: {} {} {}", vendor_id.trim(), product_id.trim(), product_revision.trim()),
+            Error::ProfileNotFound { vendor_id, product_revision, vendor_specific } =>
+                write!(f, "E2001: no profile: {} {} {}", vendor_id.trim(), product_revision.trim(), vendor_specific.trim()),
+            Error::ProfileParse { detail } => write!(f, "E2002: profile parse: {detail}"),
+            Error::UnlockFailed { detail } => write!(f, "E3000: unlock failed: {detail}"),
+            Error::SignatureMismatch { expected, got } =>
+                write!(f, "E3001: signature mismatch: expected {:02x}{:02x}{:02x}{:02x} got {:02x}{:02x}{:02x}{:02x}",
+                    expected[0], expected[1], expected[2], expected[3],
+                    got[0], got[1], got[2], got[3]),
+            Error::NotUnlocked => write!(f, "E3002: not unlocked"),
+            Error::NotCalibrated => write!(f, "E3003: not calibrated"),
+            Error::ScsiError { opcode, status, sense_key } =>
+                write!(f, "E4000: SCSI 0x{opcode:02x} failed: status=0x{status:02x} sense=0x{sense_key:02x}"),
+            Error::ScsiTimeout { opcode } => write!(f, "E4001: SCSI 0x{opcode:02x} timeout"),
+            Error::IoError { source } => write!(f, "E5000: {source}"),
+        }
+    }
+}
+
+impl std::error::Error for Error {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        match self {
+            Error::IoError { source } => Some(source),
+            _ => None,
+        }
+    }
+}
 
 impl From<std::io::Error> for Error {
     fn from(e: std::io::Error) -> Self {
-        Error::Io(e)
+        Error::IoError { source: e }
     }
 }