wasmeld/docs/design/wasmeld-capabilities.md

Wasmeld Host Capabilities

状态： Implemented

首个能力： wasmeld:clock/monotonic-clock@0.1.0

边界

所有组件实现稳定的 service-component 导出契约。宿主能力不加入这个基础 World， 而是定义成独立 WIT interface，由组件专属 World 按需 import。

wit/
├── service/package.wit  # wasmeld:service@0.1.0
└── clock/package.wit    # wasmeld:clock@0.1.0

例如普通 Echo 不导入宿主能力：

package component:echo@0.1.0;

world echo-component {
  include wasmeld:service/service-component@0.1.0;
}

Clock Probe 显式申请单调时钟：

package component:clock-probe@0.1.0;

world clock-probe-component {
  include wasmeld:service/service-component@0.1.0;
  import wasmeld:clock/monotonic-clock@0.1.0;
}

组件通过自己的 World 生成 binding：

wit_bindgen::generate!({
    path: "wit",
    world: "clock-probe-component",
    generate_all,
});

组件根目录中的 wit/deps 由 wasmeld wit fetch 根据 wasmeld.toml 和 wit.lock 生成。这几行只是编译期 binding 入口，不是网络协议。组件最终只包含 所选 World 的 imports 和 exports。

Runtime

Runtime 注册 Component 时读取真实 imports，并映射为内部 HostCapability。未知 import 会在注册阶段拒绝。Actor 创建 Linker 时，只为该 Component 实际导入的能力 注册实现。

Component imports
       |
       v
validate_component_imports
       |
       v
Vec<HostCapability>
       |
       v
Actor Linker

当前 monotonic-clock.now 返回 Actor 创建后经过的纳秒数。它不提供系统时间、网络、 文件或其他宿主访问。

Rust std::time::Instant 会引入 wasi:clocks/monotonic-clock，该 WASI 接口仍不在 Sandbox 白名单内。组件必须使用平台明确提供的 wasmeld:clock/monotonic-clock， 不能通过标准库绕过能力控制。

新增能力

新增能力时必须同时完成：

1. 在独立 .wit 文件中定义小型 interface。
2. 只在需要它的组件 World 中 import。
3. 在 Runtime 中实现生成的 Host trait。
4. 将完全限定的 import 名称映射到新的 HostCapability。
5. 在 Actor Linker 中注册实现。
6. 增加允许和拒绝两类 Sandbox 测试。

不要把可选能力加入 service-component。不要仅依据包 manifest 授权，Runtime 必须 以编译后 Component 的真实 imports 为准。

版本策略

• 已发布的 WIT 版本不可原地修改。
• 破坏性变更发布新的 major version。
• Runtime 在迁移期可以同时实现两个版本。
• 不相关能力独立演进，不能迫使所有组件重新编译。

service 和 clock 已经是两个独立版本的 WIT package。源码只维护当前版本，历史 版本由 Git tag 与不可变 Registry 制品保留；组件通过包名、版本和锁文件选择依赖。