docs(wit): document capability and component contracts

wit/kv/package.wit

@@ -1,17 +1,37 @@
 package wasmeld:kv@0.1.0;
 
+/// Small persistent byte-value store scoped to the stable service ID.
+///
+/// Revisions of the same service share a namespace, so a deployment change
+/// preserves values. Keys are non-empty UTF-8 strings of at most 256 bytes and
+/// values are at most 64 KiB in this version of the Host implementation.
+/// Operations are not multi-key transactions.
 interface store {
+  /// Expected validation or backend failures.
   variant kv-error {
+    /// The key is empty or exceeds the Host byte limit.
     invalid-key(string),
+    /// The attempted or stored value exceeds the Host byte limit.
     value-too-large(u64),
+    /// Persistence failed, timed out, or was temporarily unavailable.
+    ///
+    /// A timeout is not cancellation: a mutation may finish after the caller
+    /// receives this error. Retried `set` and `delete` operations should be
+    /// idempotent.
     operation-failed(string),
   }
 
+  /// Returns the current value, or `none` when the key does not exist.
   get: func(key: string) -> result<option<list<u8>>, kv-error>;
+
+  /// Creates or replaces one value.
   set: func(key: string, value: list<u8>) -> result<_, kv-error>;
+
+  /// Removes one value; deleting a missing key succeeds.
   delete: func(key: string) -> result<_, kv-error>;
 }
 
+/// Host-side world used by Wasmeld to link persistent KV.
 world kv-host {
   import store;
 }