Files
marqdo-cli/crates/marqdo-value/src/error.rs
T
cflmy 92bfbf2568 feat(rfc-cm): baseline P0-P3 compute machine, stdlib and resource slices
Implements the first vertical slices of RFC-CM-0001/0002 on top of a113d89:

- P1: opaque Memory regions (64 KiB pages, budgets, grow-only), byte
  read/write, Memory-index place assignment, wire/host-boundary rejection.
- CM-A04/A05: value-semantics List/Map/Text/Table primitives and the
  recoverable Result map convention.
- CM-A06: opaque Resource handles, resource.open/read/write/close, stdout
  write, granted project-file read and buffered write, strict fail-closed.
- CM-A07 Compat-A: explicit .mq.md format/utf8/io chain matching builtin
  print for the covered value types; builtin remains default.
- P2 fixtures: allocators, list/tree/graph/hash, integer codecs, UTF-8
  encode/decode, CSV/JSON subsets, table filter/sort/join, bytecode VM.
- ADRs 0022-0027, spec updates, evidence reports and 68 semantic goldens.

Gate: cargo fmt --check, clippy -D warnings, 407 tests passed.
2026-11-20 21:16:54 +08:00

237 lines
8.7 KiB
Rust

//! Structured runtime errors with source spans and call frames.
use crate::codes;
use crate::diagnostic::Diagnostic;
use marqdo_span::Span;
/// Category of a runtime failure. Each category maps to a stable diagnostic
/// code so that CI and agents can branch on codes instead of message wording.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ErrorCategory {
/// A value had the wrong type for the operation.
Type,
/// A call supplied the wrong number of arguments.
Arity,
/// A name is not bound in any reachable scope.
UnknownSymbol,
/// A name is bound but may be read before assignment.
Uninitialized,
/// Division or modulo by zero.
DivisionByZero,
/// A value was used as a function but is not callable.
NotCallable,
/// A map key or record field does not exist.
UnknownField,
/// A list/map/memory index is out of bounds.
IndexOutOfBounds,
/// An addressable-memory operation failed for a reason other than a plain
/// out-of-bounds read: invalid page counts, an unknown/stale handle, or an
/// arithmetic overflow in an address.
MemoryFault,
/// A resource handle is forged, cross-run or stale.
ResourceFault,
/// A resource operation used an already-closed handle (recoverable as a
/// `Result` by the builtin).
ResourceClosed,
/// The requested resource kind/descriptor/rights are not implemented.
ResourceUnsupported,
/// A resource budget was exhausted (fuel, stack, output size).
ResourceExhausted,
/// A capability check denied the operation.
PermissionDenied,
/// A foreign language kernel is unavailable.
KernelUnavailable,
/// The requested math operation is unsupported.
MathUnsupported,
/// Plugin ABI negotiation failed.
PluginAbi,
/// A resource reference matches more than one resource (S-07: never pick
/// the first silently).
RefAmbiguous,
/// A plugin reported an execution failure.
PluginFailure,
/// A foreign kernel failed (non-zero exit, protocol violation).
ForeignFailure,
/// A host operation failed for an environmental reason.
HostError,
/// Internal invariant violation.
Internal,
}
impl ErrorCategory {
/// Stable diagnostic code for this category.
pub const fn code(self) -> &'static str {
match self {
ErrorCategory::Type => codes::RUNTIME_TYPE,
ErrorCategory::Arity => codes::CALL_ARITY,
ErrorCategory::UnknownSymbol => codes::SYMBOL_UNKNOWN,
ErrorCategory::Uninitialized => codes::SYMBOL_UNINITIALIZED,
ErrorCategory::DivisionByZero => "runtime.division_by_zero",
ErrorCategory::NotCallable => "call.not_callable",
ErrorCategory::UnknownField => "runtime.unknown_field",
ErrorCategory::IndexOutOfBounds => codes::RUNTIME_INDEX,
ErrorCategory::MemoryFault => "runtime.memory",
ErrorCategory::ResourceFault => "runtime.resource",
ErrorCategory::ResourceClosed => "resource.closed",
ErrorCategory::ResourceUnsupported => "resource.unsupported",
ErrorCategory::ResourceExhausted => codes::RESOURCE_EXHAUSTED,
ErrorCategory::PermissionDenied => codes::PERMISSION_DENIED,
ErrorCategory::KernelUnavailable => codes::KERNEL_UNAVAILABLE,
ErrorCategory::MathUnsupported => codes::MATH_UNSUPPORTED,
ErrorCategory::PluginAbi => codes::PLUGIN_ABI_MISMATCH,
ErrorCategory::RefAmbiguous => "ref.ambiguous",
ErrorCategory::PluginFailure => "plugin.failure",
ErrorCategory::ForeignFailure => "foreign.failure",
ErrorCategory::HostError => "host.error",
ErrorCategory::Internal => codes::INTERNAL,
}
}
}
/// Whether an error location points at Marqdo source or a host/plugin
/// callsite with no trustworthy internal stack.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ErrorOrigin {
/// The error points at the Marqdo module and span.
#[default]
Source,
/// The error occurred at the Marqdo callsite of a host/plugin/foreign
/// operation; the callee's internal stack is unavailable.
Callsite,
}
/// One entry of the Marqdo call stack.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct CallFrame {
/// Canonical function name (or `<main>` for the entry function).
pub function: String,
/// Logical module containing the call site.
#[serde(skip_serializing_if = "Option::is_none")]
pub module_id: Option<Box<str>>,
/// Source location of the call site in the caller.
#[serde(skip_serializing_if = "Option::is_none")]
pub span: Option<Span>,
}
/// A structured runtime failure.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct RuntimeError {
/// Failure category.
pub category: ErrorCategory,
/// Logical module containing [`Self::span`].
#[serde(skip_serializing_if = "Option::is_none")]
pub module_id: Option<Box<str>>,
/// Location in the source that caused the failure.
#[serde(skip_serializing_if = "Option::is_none")]
pub span: Option<Span>,
/// Whether the location is Marqdo source or a callsite.
#[serde(default)]
pub origin: ErrorOrigin,
/// Human readable message.
pub message: Box<str>,
/// Call frames from innermost to outermost.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub frames: Vec<CallFrame>,
/// Underlying cause (e.g. a host or foreign kernel error).
#[serde(skip_serializing_if = "Option::is_none")]
pub cause: Option<Box<RuntimeError>>,
/// Effect trace recorded by the host, when available.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub effect_trace: Vec<String>,
}
impl RuntimeError {
/// Create a new runtime error.
pub fn new(category: ErrorCategory, span: Option<Span>, message: impl Into<String>) -> Self {
Self {
category,
module_id: None,
span,
origin: ErrorOrigin::Source,
message: message.into().into_boxed_str(),
frames: Vec::new(),
cause: None,
effect_trace: Vec::new(),
}
}
/// Convenience constructor for type errors.
pub fn type_error(span: Option<Span>, message: impl Into<String>) -> Self {
Self::new(ErrorCategory::Type, span, message)
}
/// Attach a module identity if the error does not have one yet.
pub fn attribute_module(&mut self, module_id: impl Into<String>) {
if self.module_id.is_none() {
self.module_id = Some(module_id.into().into_boxed_str());
}
}
/// Mark this error as occurring at a host/plugin/foreign callsite.
pub fn mark_callsite(&mut self) {
self.origin = ErrorOrigin::Callsite;
}
/// Record a call frame (called while unwinding).
pub fn push_frame(
&mut self,
function: impl Into<String>,
span: Option<Span>,
module_id: Option<String>,
) {
self.frames.push(CallFrame {
function: function.into(),
module_id: module_id.map(String::into_boxed_str),
span,
});
}
/// Add a cause.
pub fn with_cause(mut self, cause: RuntimeError) -> Self {
self.cause = Some(Box::new(cause));
self
}
/// The stable diagnostic code for this failure.
pub fn code(&self) -> &'static str {
self.category.code()
}
/// Render as a user facing diagnostic.
pub fn to_diagnostic(&self) -> Diagnostic {
let mut diag = Diagnostic::error(self.code(), self.span, self.message.clone());
for frame in &self.frames {
diag = diag.with_related(frame.span, format!("in function `{}`", frame.function));
}
if let Some(cause) = &self.cause {
diag = diag.with_related(cause.span, format!("caused by: {}", cause.message));
}
diag
}
}
impl std::fmt::Display for RuntimeError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
write!(f, "{}: {}", self.code(), self.message)
}
}
impl std::error::Error for RuntimeError {}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn frames_are_rendered_as_related_diagnostics() {
let mut err = RuntimeError::type_error(Some(Span::new(1, 2)), "expected Bool");
err.push_frame("阶乘", None, None);
let diag = err.to_diagnostic();
assert_eq!(diag.code, "runtime.type");
assert_eq!(diag.related.len(), 1);
assert_eq!(diag.related[0].message, "in function `阶乘`");
}
}