v0.1.1-pre.002

crates/ksp-core-lib/src/error.rs

@@ -0,0 +1,130 @@
+// file: crates/ksp-core-lib/src/error.rs
+// version: 1
+
+/// Stable structured identifier for a KSP error.
+#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
+pub struct ErrorCode {
+    domain: &'static str,
+    code: &'static str,
+}
+
+impl ErrorCode {
+    /// Creates an error code from a stable domain and code identifier.
+    #[must_use]
+    pub const fn new(domain: &'static str, code: &'static str) -> Self {
+        return Self { domain, code };
+    }
+
+    /// Returns the stable error domain identifier.
+    #[must_use]
+    pub const fn domain(&self) -> &'static str {
+        return self.domain;
+    }
+
+    /// Returns the stable error code identifier within the domain.
+    #[must_use]
+    pub const fn code(&self) -> &'static str {
+        return self.code;
+    }
+}
+
+/// Structured contextual field attached to a KSP error.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct ErrorContext {
+    key: &'static str,
+    value: std::string::String,
+}
+
+impl ErrorContext {
+    /// Creates one contextual field from a stable key and an owned value.
+    #[must_use]
+    pub fn new(key: &'static str, value: impl std::convert::Into<std::string::String>) -> Self {
+        return Self { key, value: value.into() };
+    }
+
+    /// Returns the stable contextual key.
+    #[must_use]
+    pub fn key(&self) -> &'static str {
+        return self.key;
+    }
+
+    /// Returns the contextual value.
+    #[must_use]
+    pub fn value(&self) -> &str {
+        return self.value.as_str();
+    }
+}
+
+/// Common KSP error carrying a stable code, human-readable message, structured context and optional source.
+#[derive(Debug)]
+pub struct Error {
+    code: crate::ErrorCode,
+    message: std::string::String,
+    context: std::vec::Vec<crate::ErrorContext>,
+    source: std::option::Option<std::boxed::Box<dyn std::error::Error + std::marker::Send + std::marker::Sync + 'static>>,
+}
+
+impl Error {
+    /// Creates a KSP error without context or external source.
+    #[must_use]
+    pub fn new(code: crate::ErrorCode, message: impl std::convert::Into<std::string::String>) -> Self {
+        return Self { code, message: message.into(), context: std::vec::Vec::new(), source: std::option::Option::None };
+    }
+
+    /// Returns the stable structured error code.
+    #[must_use]
+    pub const fn code(&self) -> crate::ErrorCode {
+        return self.code;
+    }
+
+    /// Returns the human-readable diagnostic message.
+    #[must_use]
+    pub fn message(&self) -> &str {
+        return self.message.as_str();
+    }
+
+    /// Returns the contextual fields in insertion order.
+    #[must_use]
+    pub fn context(&self) -> &[crate::ErrorContext] {
+        return self.context.as_slice();
+    }
+
+    /// Appends one contextual field and returns the enriched error.
+    #[must_use]
+    pub fn with_context(mut self, key: &'static str, value: impl std::convert::Into<std::string::String>) -> Self {
+        self.context.push(crate::ErrorContext::new(key, value));
+        return self;
+    }
+
+    /// Attaches an external error as the standard source and returns the enriched error.
+    #[must_use]
+    pub fn with_source<E>(mut self, source: E) -> Self
+    where
+        E: std::error::Error + std::marker::Send + std::marker::Sync + 'static,
+    {
+        self.source = std::option::Option::Some(std::boxed::Box::new(source));
+        return self;
+    }
+}
+
+impl std::fmt::Display for Error {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        return write!(formatter, "{}.{}: {}", self.code.domain(), self.code.code(), self.message);
+    }
+}
+
+impl std::error::Error for Error {
+    fn source(&self) -> std::option::Option<&(dyn std::error::Error + 'static)> {
+        return match self.source.as_deref() {
+            std::option::Option::Some(source) => std::option::Option::Some(source),
+            std::option::Option::None => std::option::Option::None,
+        };
+    }
+}
+
+/// Common result type returned by KSP APIs using [`crate::Error`].
+pub type Result<T> = std::result::Result<T, crate::Error>;
+
+#[cfg(test)]
+#[path = "../unit_tests/error.rs"]
+mod tests;

crates/ksp-core-lib/src/lib.rs

@@ -1,7 +1,18 @@
 // file: crates/ksp-core-lib/src/lib.rs
-// version: 3
+// version: 4
 #![warn(missing_docs)]
 #![deny(unreachable_pub)]
 #![forbid(unsafe_code)]
 
-//! Minimal core-library skeleton for the KSP foundation phase.
+//! Core contracts shared by the foundational KSP layers.
+
+mod error;
+
+/// Common KSP error type used by higher-level crates.
+pub use self::error::Error;
+/// Stable structured code identifying a KSP error category and condition.
+pub use self::error::ErrorCode;
+/// Structured contextual field attached to a KSP error.
+pub use self::error::ErrorContext;
+/// Common KSP result alias using [`Error`].
+pub use self::error::Result;

crates/ksp-core-lib/tests/public_api.rs

@@ -0,0 +1,22 @@
+// file: crates/ksp-core-lib/tests/public_api.rs
+// version: 1
+
+fn public_result() -> ksp_core_lib::Result<()> {
+    let error = ksp_core_lib::Error::new(ksp_core_lib::ErrorCode::new("consumer", "failed"), "consumer failure").with_context("operation", "public_api");
+    return std::result::Result::Err(error);
+}
+
+#[test]
+fn error_contract_is_consumable_from_crate_root() {
+    let result = public_result();
+    assert!(result.is_err());
+    let error = match result {
+        std::result::Result::Ok(()) => return,
+        std::result::Result::Err(error) => error,
+    };
+    assert_eq!(error.code(), ksp_core_lib::ErrorCode::new("consumer", "failed"));
+    assert_eq!(error.message(), "consumer failure");
+    assert_eq!(error.context(), &[ksp_core_lib::ErrorContext::new("operation", "public_api")]);
+    assert_eq!(std::string::ToString::to_string(&error), "consumer.failed: consumer failure");
+    return;
+}

crates/ksp-core-lib/unit_tests/error.rs

@@ -0,0 +1,78 @@
+// file: crates/ksp-core-lib/unit_tests/error.rs
+// version: 1
+
+#[derive(Debug)]
+struct TestSource;
+
+impl std::fmt::Display for TestSource {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        return formatter.write_str("source failure");
+    }
+}
+
+impl std::error::Error for TestSource {}
+
+fn assert_send_sync<T>()
+where
+    T: std::marker::Send + std::marker::Sync,
+{
+    return;
+}
+
+#[test]
+fn error_code_preserves_domain_and_code() {
+    const CODE: crate::ErrorCode = crate::ErrorCode::new("core", "sample_failure");
+    assert_eq!(CODE.domain(), "core");
+    assert_eq!(CODE.code(), "sample_failure");
+    return;
+}
+
+#[test]
+fn error_context_preserves_key_and_value() {
+    let context = crate::ErrorContext::new("operation", "sample");
+    assert_eq!(context.key(), "operation");
+    assert_eq!(context.value(), "sample");
+    return;
+}
+
+#[test]
+fn error_preserves_code_message_and_context_order() {
+    let code = crate::ErrorCode::new("core", "sample_failure");
+    let error = crate::Error::new(code, "sample message").with_context("first", "one").with_context("second", "two");
+    assert_eq!(error.code(), code);
+    assert_eq!(error.message(), "sample message");
+    assert_eq!(error.context().len(), 2);
+    assert_eq!(error.context()[0].key(), "first");
+    assert_eq!(error.context()[0].value(), "one");
+    assert_eq!(error.context()[1].key(), "second");
+    assert_eq!(error.context()[1].value(), "two");
+    return;
+}
+
+#[test]
+fn display_contains_only_qualified_code_and_message() {
+    let error = crate::Error::new(crate::ErrorCode::new("core", "sample_failure"), "sample message")
+        .with_context("secret_free_context", "not rendered")
+        .with_source(TestSource);
+    assert_eq!(std::string::ToString::to_string(&error), "core.sample_failure: sample message");
+    return;
+}
+
+#[test]
+fn standard_source_is_preserved() {
+    let error = crate::Error::new(crate::ErrorCode::new("core", "sample_failure"), "sample message").with_source(TestSource);
+    let source = std::error::Error::source(&error);
+    assert!(source.is_some());
+    let source_message = match source {
+        std::option::Option::Some(value) => std::string::ToString::to_string(value),
+        std::option::Option::None => std::string::String::new(),
+    };
+    assert_eq!(source_message, "source failure");
+    return;
+}
+
+#[test]
+fn common_error_is_send_and_sync() {
+    assert_send_sync::<crate::Error>();
+    return;
+}