# Wasmeld Host Capabilities

**状态：** Implemented

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

## 边界

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

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

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

```wit
package component:echo@0.1.0;

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

Clock Probe 显式申请单调时钟：

```wit
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：

```rust
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 实际导入的能力
注册实现。

```text
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 制品保留；组件通过包名、版本和锁文件选择依赖。