From a5718da1da6c49707d26c013e482127190124183 Mon Sep 17 00:00:00 2001
From: Maofeng <hornjs@qq.com>
Date: Thu, 30 Jul 2026 07:40:11 +0800
Subject: [PATCH] docs: describe resident component architecture

Document the Host-owned event/effect flow, revision-scoped resource supervision, endpoint policy, versioned resident WIT dependency, and the resident-probe packaging command.
---
 README.md                        | 26 ++++++++++++++++++++++++++
 crates/wasmeld-package/README.md |  6 ++++++
 2 files changed, 32 insertions(+)

diff --git a/README.md b/README.md
index cacd50e..13d28f8 100644
--- a/README.md
+++ b/README.md
@@ -13,6 +13,22 @@ imports，只链接实际请求且版本完全匹配的 Host 能力；未知能
 - `wasmeld:clock/monotonic-clock@0.1.0`：Actor 内单调时钟
 - `wasmeld:kv/store@0.1.0`：按服务隔离、跨 Revision 共享的持久化二进制 KV
 
+常驻型 Component 可额外导出 `wasmeld:resident/actor@0.1.0`。Runtime 将定时器、
+TCP/UDP/Unix、消息订阅和扩展事件放入同一个有界 Actor mailbox；Component 每次只处理
+一个事件并返回 effect。系统 socket、timer task 和 broker consumer 始终由 Host 持有，
+Component 只能引用当前 Revision 内不复用的资源 ID，不能直接取得文件描述符或绕过
+端点策略。
+
+```text
+Host driver -> ResidentSession -> Actor mailbox -> Wasm Component
+Host driver <- validated operation <- raw effect <-
+```
+
+`ResidentSession` 负责 deny-by-default 的网络策略、资源归属、数量限制、流的暂停/半关闭/
+关闭状态以及 effect 批量原子校验。TCP、UDP、Unix listener 等异步驱动运行在 Actor
+线程外；协议级驱动以及文件监听、串口、系统信号等其它来源通过独立版本的 WIT 能力演进，
+不需要扩大基础 service world。
+
 ## 结构
 
 ```text
@@ -93,6 +109,16 @@ cargo run -p wasmeld-package --bin wasmeld -- \
 `kv-probe` 接受 `set:<key>:<value>`、`get:<key>` 和 `delete:<key>`，用于验证 Host KV
 能力；它不是公开 Gateway 的业务协议。
 
+常驻事件示例组件：
+
+```bash
+cargo run -p wasmeld-package --bin wasmeld -- \
+  pack components/resident-probe/Cargo.toml --locked
+```
+
+该组件同时实现基础 service world 与 resident actor export，用于验证 stream、datagram、
+timer、message 和扩展 source 的事件/effect 往返。
+
 发布 WIT Package：
 
 ```bash
diff --git a/crates/wasmeld-package/README.md b/crates/wasmeld-package/README.md
index d7bab9a..fb45348 100644
--- a/crates/wasmeld-package/README.md
+++ b/crates/wasmeld-package/README.md
@@ -156,6 +156,7 @@ url = "http://127.0.0.1:8080"
 [dependencies]
 "wasmeld:service" = "0.1.0"
 "wasmeld:kv" = "0.1.0"
+"wasmeld:resident" = "0.1.0"
 
 [replace."wasmeld:service"]
 path = "../../wit/service"
@@ -164,6 +165,11 @@ path = "../../wit/service"
 依赖解析结果写入 `wit.lock`，源码开发时应提交该文件。解析出的 `wit/deps/` 是生成目录，
 不应提交。
 
+普通请求型 Component 只需要 `wasmeld:service`。需要接收 Host 定时器、网络流、UDP、
+消息订阅或扩展 source 事件时，再依赖并导出 `wasmeld:resident/actor@0.1.0`；例如
+`components/resident-probe`。`resident` 是独立版本化 package，不会把所有 Host 能力
+合并到基础 service world。
+
 同步依赖：
 
 ```bash