docs(runtime): explain actor and resident invariants

crates/wasmeld-runtime/src/error.rs

@@ -9,98 +9,158 @@ use crate::manifest::ServiceKey;
 /// Failures from Runtime configuration, sandbox validation, or Actor execution.
 #[derive(Debug, Error)]
 pub enum RuntimeError {
+    /// Service ID or revision is empty.
     #[error("service id and revision must not be empty")]
     InvalidServiceKey,
 
+    /// Manifest identity, world, path, or resource limits are invalid.
     #[error("invalid manifest: {0}")]
     InvalidManifest(String),
 
+    /// Runtime manifest TOML could not be decoded.
     #[error("manifest parse failed: {0}")]
     ManifestParse(#[from] toml::de::Error),
 
+    /// A lifecycle operation addressed an unknown service revision.
     #[error("service revision {0} is not registered")]
     ServiceNotRegistered(ServiceKey),
 
+    /// Registration attempted to overwrite an immutable service revision.
     #[error("service revision {0} is already registered")]
     ServiceAlreadyRegistered(ServiceKey),
 
+    /// Wasmtime rejected the Component before it entered the registry.
     #[error("component compilation failed: {0}")]
     ComponentCompilation(#[source] wasmtime::Error),
 
+    /// The Component imports a WASI or Wasmeld interface outside the allowlist.
     #[error("component imports unsupported capability {0}")]
     UnsupportedImport(String),
 
+    /// A supported capability has no configured Host backend.
     #[error("component requires unavailable capability {0}")]
     CapabilityUnavailable(String),
 
+    /// The shared Wasmtime Engine could not be created.
     #[error("runtime creation failed: {0}")]
     RuntimeCreation(#[source] wasmtime::Error),
 
+    /// The configured compiled-Component cache directory could not be prepared.
     #[error("failed to prepare Component compilation cache {path}: {source}")]
     CacheDirectory {
+        /// Requested cache directory.
         path: PathBuf,
+        /// Underlying filesystem failure.
         #[source]
         source: std::io::Error,
     },
 
+    /// Wasmtime rejected the persistent cache configuration.
     #[error("invalid Component compilation cache configuration: {0}")]
     CacheConfiguration(#[source] wasmtime::Error),
 
+    /// A Component path from a manifest could not be read.
     #[error("failed to read component artifact {path}: {source}")]
     ArtifactRead {
+        /// Manifest-provided artifact path.
         path: String,
+        /// Underlying filesystem failure.
         #[source]
         source: std::io::Error,
     },
 
+    /// The operating system refused to create an Actor worker thread.
     #[error("failed to spawn actor thread: {0}")]
     ActorThread(#[source] std::io::Error),
 
+    /// Linking, instantiation, or the Component `init` export failed.
     #[error("actor initialization failed: {0}")]
     ActorInitialization(String),
 
+    /// The Actor is stopped, faulted, starting, or no longer accepting work.
     #[error("actor for {0} is unavailable")]
     ActorUnavailable(ServiceKey),
 
+    /// The bounded Actor mailbox has no capacity for another command.
     #[error("actor mailbox for {0} is full")]
     ActorOverloaded(ServiceKey),
 
+    /// The worker exited before returning a queued response.
     #[error("actor for {0} stopped before returning a result")]
     ActorStopped(ServiceKey),
 
+    /// Resident dispatch was attempted on a passive service Component.
     #[error("service revision {0} does not export the resident actor interface")]
     NotResident(ServiceKey),
 
+    /// A Host event payload exceeds its configured resident or input limit.
     #[error("resident event for {service} exceeds the {limit}-byte payload limit")]
-    ResidentEventTooLarge { service: ServiceKey, limit: usize },
+    ResidentEventTooLarge {
+        /// Actor revision receiving the event.
+        service: ServiceKey,
+        /// Maximum accepted bytes.
+        limit: usize,
+    },
 
+    /// A Component returned more effects than one event is allowed to produce.
     #[error("resident event for {service} returned more than {limit} effects")]
-    TooManyResidentEffects { service: ServiceKey, limit: usize },
+    TooManyResidentEffects {
+        /// Actor revision that returned the effect list.
+        service: ServiceKey,
+        /// Maximum effects accepted per event.
+        limit: usize,
+    },
 
+    /// A raw Component effect has invalid IDs, payloads, names, or timer values.
     #[error("invalid resident effect: {0}")]
     InvalidResidentEffect(String),
 
+    /// Invocation input exceeds the service manifest limit.
     #[error("input for {service} exceeds the {limit}-byte limit")]
-    InputTooLarge { service: ServiceKey, limit: usize },
+    InputTooLarge {
+        /// Actor revision receiving the input.
+        service: ServiceKey,
+        /// Maximum accepted bytes.
+        limit: usize,
+    },
 
+    /// Invocation output exceeds the service manifest limit.
     #[error("output for {service} exceeds the {limit}-byte limit")]
-    OutputTooLarge { service: ServiceKey, limit: usize },
+    OutputTooLarge {
+        /// Actor revision returning the output.
+        service: ServiceKey,
+        /// Maximum accepted bytes.
+        limit: usize,
+    },
 
+    /// Queue waiting and Component execution exceeded the end-to-end deadline.
     #[error("actor for {service} exceeded its {deadline:?} execution deadline")]
     DeadlineExceeded {
+        /// Actor revision whose command expired.
         service: ServiceKey,
+        /// Configured end-to-end command deadline.
         deadline: Duration,
     },
 
+    /// A Wasm trap made the current Actor instance unusable.
     #[error("actor for {service} faulted: {message}")]
     ActorFault {
+        /// Faulted Actor revision.
         service: ServiceKey,
+        /// Wasmtime trap or call failure detail.
         message: String,
     },
 
+    /// Guest code returned a typed WIT error without trapping the Actor.
     #[error("component returned {kind}: {message}")]
-    ComponentError { kind: &'static str, message: String },
+    ComponentError {
+        /// Export phase such as `init`, `invoke`, or `resident-event`.
+        kind: &'static str,
+        /// Guest-provided diagnostic text.
+        message: String,
+    },
 
+    /// An internal registry or lifecycle mutex was poisoned by a panic.
     #[error("runtime lock was poisoned")]
     LockPoisoned,
 }