harn_hostlib/
error.rs

1//! Error type for hostlib host calls.
2//!
3//! Builtins translate this into VM-level errors via [`Into<harn_vm::VmError>`]
4//! so that Harn scripts see structured exceptions rather than panics.
5
6use harn_vm::VmDictExt;
7
8use harn_vm::{VmError, VmValue};
9
10/// All errors a hostlib builtin can surface.
11///
12/// Variants intentionally describe the *kind* of failure rather than the
13/// specific module — every module routes its missing-implementation errors
14/// through [`HostlibError::Unimplemented`] so embedders and tests can
15/// distinguish intentionally scaffolded contracts from runtime failures.
16#[derive(Debug, thiserror::Error)]
17pub enum HostlibError {
18    /// The method exists in the registration table but has no implementation
19    /// yet. This is the canonical scaffold-stage error: it tells callers
20    /// "the contract is stable, but this module has not been implemented."
21    #[error(
22        "hostlib: {builtin} is not implemented yet (scaffolded contract without an implementation)"
23    )]
24    Unimplemented {
25        /// Fully-qualified builtin name, e.g. `"hostlib_ast_parse_file"`.
26        builtin: &'static str,
27    },
28
29    /// A required parameter was missing from the call payload.
30    #[error("hostlib: {builtin}: missing required parameter '{param}'")]
31    MissingParameter {
32        /// Fully-qualified builtin name.
33        builtin: &'static str,
34        /// Name of the missing parameter.
35        param: &'static str,
36    },
37
38    /// A parameter was present but had the wrong shape (wrong type, malformed).
39    #[error("hostlib: {builtin}: invalid parameter '{param}': {message}")]
40    InvalidParameter {
41        /// Fully-qualified builtin name.
42        builtin: &'static str,
43        /// Name of the invalid parameter.
44        param: &'static str,
45        /// Human-readable description of the violation.
46        message: String,
47    },
48
49    /// Catch-all wrapper for I/O, parsing, or other backend failures.
50    #[error("hostlib: {builtin}: {message}")]
51    Backend {
52        /// Fully-qualified builtin name.
53        builtin: &'static str,
54        /// Human-readable failure description.
55        message: String,
56    },
57
58    /// A path the builtin resolved fell outside the session's workspace
59    /// roots under a restricted sandbox profile. The mirror of the
60    /// `harness.fs.*` `tool_rejected` rejection — both surfaces reject an
61    /// out-of-root path with the same message.
62    #[error("{message}")]
63    SandboxViolation {
64        /// Fully-qualified builtin name.
65        builtin: &'static str,
66        /// The normalized path that was rejected, for telemetry.
67        path: String,
68        /// The canonical rejection message (see
69        /// [`harn_vm::process_sandbox::SandboxViolation::message`]).
70        message: String,
71    },
72
73    /// A never-approvable UNIVERSAL catastrophic command (machine/disk/data
74    /// destruction) was rejected by the floor BEFORE spawning, at the shared
75    /// [`crate::process::spawn_process`] chokepoint. Enforced unconditionally
76    /// (no `command_policy` required), so it is universal across every hostlib
77    /// process tool, embedders, and standalone Harn. Mirrors the
78    /// `catastrophic_floor` disposition the `process.exec` command-policy
79    /// preflight surfaces. See
80    /// [`harn_vm::orchestration::universal_catastrophic_reason`].
81    #[error("{message}")]
82    CatastrophicFloor {
83        /// Fully-qualified builtin name.
84        builtin: &'static str,
85        /// The verbatim floor rationale (never-approvable reason).
86        message: String,
87    },
88}
89
90impl HostlibError {
91    /// The fully-qualified builtin name this error came from. Useful for
92    /// embedder logging and for the routing tests in `tests/`.
93    pub fn builtin(&self) -> &'static str {
94        match self {
95            HostlibError::Unimplemented { builtin }
96            | HostlibError::MissingParameter { builtin, .. }
97            | HostlibError::InvalidParameter { builtin, .. }
98            | HostlibError::Backend { builtin, .. }
99            | HostlibError::SandboxViolation { builtin, .. }
100            | HostlibError::CatastrophicFloor { builtin, .. } => builtin,
101        }
102    }
103}
104
105impl From<HostlibError> for VmError {
106    fn from(err: HostlibError) -> VmError {
107        // Surface as a `Thrown` dict so Harn `try`/`catch` can pattern-match
108        // on `kind`, `builtin`, and `message`. This matches how the existing
109        // `host_call` error path shapes its exceptions.
110        let kind = match err {
111            HostlibError::Unimplemented { .. } => "unimplemented",
112            HostlibError::MissingParameter { .. } => "missing_parameter",
113            HostlibError::InvalidParameter { .. } => "invalid_parameter",
114            HostlibError::Backend { .. } => "backend_error",
115            HostlibError::SandboxViolation { .. } => "tool_rejected",
116            HostlibError::CatastrophicFloor { .. } => "catastrophic_floor",
117        };
118        // Carry the offending path on sandbox violations so `catch` blocks
119        // and telemetry can branch on it without re-parsing the message.
120        let path = match &err {
121            HostlibError::SandboxViolation { path, .. } => Some(path.clone()),
122            _ => None,
123        };
124        let builtin = err.builtin();
125        let message = err.to_string();
126
127        let mut dict: harn_vm::value::DictMap = harn_vm::value::DictMap::new();
128        dict.put_str("kind", kind);
129        dict.put_str("builtin", builtin);
130        dict.put_str("message", message);
131        if let Some(path) = path {
132            dict.put_str("path", path);
133        }
134        VmError::Thrown(VmValue::dict(dict))
135    }
136}
harn_hostlib/error.rs

harn_hostlib/
error.rs
