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 {

components/resident-probe/wit.lock

@@ -4,12 +4,12 @@ schema_version = 1
 name = "wasmeld:resident"
 version = "0.1.0"
 source = "path+../../wit/resident"
-sha256 = "683a3c7196a6dd77b3f619227aa093430ff6995c097d39bb82d501b7c59a196c"
+sha256 = "a13728b0e6f000c03eb0f88e2e54bad1c6e5160ac3ca4b9e87619247c0043d1b"
 replaced = true
 
 [[package]]
 name = "wasmeld:service"
 version = "0.1.0"
 source = "path+../../wit/service"
-sha256 = "d5497307bbcd1e159f7707f385b488a6f2e26362d5256d5bc1080ac603a51305"
+sha256 = "1b2069606ccbf5202789667570bc824f702f34b147aa38e81c2ab677444ffa0e"
 replaced = true

components/resident-probe/wit/world.wit

@@ -1,5 +1,7 @@
 package component:resident-probe@0.1.0;
 
+/// Composes ordinary request/response exports with the optional resident actor
+/// export. Network and timer drivers remain Host-owned.
 world resident-probe-component {
   include wasmeld:service/service-component@0.1.0;
   export wasmeld:resident/actor@0.1.0;