arkhe-kernel 0.13.0

Domain-neutral deterministic microkernel for virtual worlds. WAL-backed, bit-identical replay, invariant-lifetime shell brand, no async / no unsafe / no floating-point in canonical paths.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112

//! Kernel-level error taxonomy.
//!
//! The `Domain` variant is opaque to the kernel — code and payload are
//! L2/L1 concerns. This prevents domain-level error paths from being
//! forced into string smuggling or `EmitEvent` side-channels.
//!
//! `#[non_exhaustive]` defends the ABI: external matchers are forbidden
//! from exhaustive-matching, so future variants are not breaking for
//! external consumers.

use bytes::Bytes;

/// Top-level kernel error.
#[non_exhaustive]
#[derive(Clone, Debug)]
pub enum ArkheError {
    /// Requested `InstanceId` is not live.
    InstanceNotFound,

    /// Caller lacks one or more required capability bits.
    CapabilityDenied,

    /// Domain-level error. The kernel does not interpret `code` or
    /// `payload`; they are an L1/L2 protocol. Payload is canonical bytes
    /// (CanonicalEncode discipline) so cross-replay determinism holds.
    Domain {
        /// L1/L2-defined error code; kernel-opaque.
        code: u32,
        /// Canonical bytes carrying L1/L2-defined error payload.
        payload: Bytes,
    },
}

impl core::fmt::Display for ArkheError {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        match self {
            Self::InstanceNotFound => write!(f, "instance not found"),
            Self::CapabilityDenied => write!(f, "capability denied"),
            Self::Domain { code, payload } => {
                write!(
                    f,
                    "domain error: code={} payload_len={}",
                    code,
                    payload.len()
                )
            }
        }
    }
}

impl std::error::Error for ArkheError {}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn domain_error_carries_code_and_payload() {
        let err = ArkheError::Domain {
            code: 42,
            payload: Bytes::from_static(b"opaque"),
        };
        match err {
            ArkheError::Domain { code, payload } => {
                assert_eq!(code, 42);
                assert_eq!(&payload[..], b"opaque");
            }
            _ => panic!("expected Domain variant"),
        }
    }

    #[test]
    fn domain_error_payload_can_be_empty() {
        let err = ArkheError::Domain {
            code: 0,
            payload: Bytes::new(),
        };
        match err {
            ArkheError::Domain { payload, .. } => assert!(payload.is_empty()),
            _ => panic!("expected Domain variant"),
        }
    }

    #[test]
    fn error_display_instance_not_found() {
        let err = ArkheError::InstanceNotFound;
        assert_eq!(format!("{}", err), "instance not found");
    }

    #[test]
    fn error_display_capability_denied() {
        let err = ArkheError::CapabilityDenied;
        assert_eq!(format!("{}", err), "capability denied");
    }

    #[test]
    fn error_display_domain_includes_code() {
        let err = ArkheError::Domain {
            code: 7,
            payload: Bytes::from_static(b"xyz"),
        };
        let s = format!("{}", err);
        assert!(s.contains("code=7"));
        assert!(s.contains("payload_len=3"));
    }

    #[test]
    fn error_implements_std_error() {
        fn assert_std_error<E: std::error::Error>() {}
        assert_std_error::<ArkheError>();
    }
}