punkgo-core 0.5.0

Core types and protocol for PunkGo kernel: actors, actions, energy, boundaries, and consent
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
113
114
115
116
117
118
119
120

use serde_json::Value;
use thiserror::Error;

/// Unified error type for all kernel operations.
#[derive(Debug, Error)]
pub enum KernelError {
    #[error("invalid request: {0}")]
    InvalidRequest(String),
    #[error("policy violation: {0}")]
    PolicyViolation(String),
    #[error("actor not found: {0}")]
    ActorNotFound(String),
    #[error("insufficient energy: actor={actor_id}, required={required}, available={available}")]
    InsufficientEnergy {
        actor_id: String,
        required: i64,
        available: i64,
    },
    #[error("actor frozen: {0}")]
    ActorFrozen(String),
    #[error("boundary violation: {0}")]
    BoundaryViolation(String),
    #[error("authorization required: {0}")]
    AuthorizationRequired(String),
    #[error("hold triggered: hold_id={hold_id}, agent={agent_id}")]
    HoldTriggered { hold_id: String, agent_id: String },
    #[error("execute payload invalid: {0}")]
    ExecutePayloadInvalid(String),
    #[error("audit error: {0}")]
    Audit(String),
    #[error(transparent)]
    Io(#[from] std::io::Error),
    #[error(transparent)]
    Db(#[from] sqlx::Error),
    #[error(transparent)]
    Json(#[from] serde_json::Error),
}

impl KernelError {
    /// Structured error payload for IPC responses.
    ///
    /// Returns a JSON object with `error_type` (machine-readable variant name),
    /// `message` (human-readable, backward-compatible), and structured fields.
    pub fn to_error_payload(&self) -> Value {
        match self {
            KernelError::InvalidRequest(detail) => serde_json::json!({
                "error_type": "InvalidRequest",
                "message": self.to_string(),
                "detail": detail,
            }),
            KernelError::PolicyViolation(detail) => serde_json::json!({
                "error_type": "PolicyViolation",
                "message": self.to_string(),
                "detail": detail,
            }),
            KernelError::ActorNotFound(actor_id) => serde_json::json!({
                "error_type": "ActorNotFound",
                "message": self.to_string(),
                "actor_id": actor_id,
            }),
            KernelError::InsufficientEnergy {
                actor_id,
                required,
                available,
            } => serde_json::json!({
                "error_type": "InsufficientEnergy",
                "message": self.to_string(),
                "actor_id": actor_id,
                "required": required,
                "available": available,
            }),
            KernelError::ActorFrozen(actor_id) => serde_json::json!({
                "error_type": "ActorFrozen",
                "message": self.to_string(),
                "actor_id": actor_id,
            }),
            KernelError::BoundaryViolation(detail) => serde_json::json!({
                "error_type": "BoundaryViolation",
                "message": self.to_string(),
                "detail": detail,
            }),
            KernelError::AuthorizationRequired(detail) => serde_json::json!({
                "error_type": "AuthorizationRequired",
                "message": self.to_string(),
                "detail": detail,
            }),
            KernelError::HoldTriggered { hold_id, agent_id } => serde_json::json!({
                "error_type": "HoldTriggered",
                "message": self.to_string(),
                "hold_id": hold_id,
                "agent_id": agent_id,
            }),
            KernelError::ExecutePayloadInvalid(detail) => serde_json::json!({
                "error_type": "ExecutePayloadInvalid",
                "message": self.to_string(),
                "detail": detail,
            }),
            KernelError::Audit(detail) => serde_json::json!({
                "error_type": "Audit",
                "message": self.to_string(),
                "detail": detail,
            }),
            KernelError::Io(err) => serde_json::json!({
                "error_type": "Io",
                "message": err.to_string(),
            }),
            KernelError::Db(err) => serde_json::json!({
                "error_type": "Db",
                "message": err.to_string(),
            }),
            KernelError::Json(err) => serde_json::json!({
                "error_type": "Json",
                "message": err.to_string(),
            }),
        }
    }
}

/// Convenience alias for `Result<T, KernelError>`.
pub type KernelResult<T> = Result<T, KernelError>;