docs(wit): document capability and component contracts

components/resident-probe/src/lib.rs

@@ -1,6 +1,14 @@
+//! Resident event/effect fixture covering every current Host-driven I/O family.
+//!
+//! The callback echoes stream chunks and datagrams, rearms fired timers,
+//! acknowledges messages, and reflects extension commands. It owns no socket,
+//! timer, or subscription handles; those resources remain in the Host driver.
+
 use std::sync::atomic::{AtomicU64, Ordering};
 
 mod bindings {
+    // One generated module contains both the base service export and resident
+    // actor export because this component world composes both WIT packages.
     wit_bindgen::generate!({
         path: "wit",
         world: "resident-probe-component",
@@ -35,6 +43,8 @@ impl ResidentGuest for ResidentProbe {
     fn handle_event(
         input: Event,
     ) -> Result<Vec<Effect>, bindings::exports::wasmeld::resident::actor::ResidentError> {
+        // Event callbacks are serialized with normal invocations by the same
+        // Actor mailbox, so this in-memory count is deterministic per Actor.
         EVENTS_HANDLED.fetch_add(1, Ordering::Relaxed);
         Ok(match input {
             Event::StreamData(chunk) => vec![Effect::WriteStream(StreamWrite {