AGENTS.md@src/host/api git:20260928.0bc633cA

Immutable. This exact content never changes and is served at /api/v1/blob/4315338b6d284be0.

# API Boundary Module Rules

## 范围与职责

适用于 `src/host/api/`。

把 GUI 的 HTTP 请求翻译成对 Host 领域能力的调用，并把结果与失败翻译回稳定的对外响应契约（端点名、响应包形状、错误码、HTTP 状态）。

判断归属：该改动是否改变「请求如何被翻译成领域调用」或「对外响应契约」？只改变领域语义判断（合法性、状态机推进、冲突策略、持久化形状）应放到对应领域模块。

## 契约

- 端点名以共享协议常量为唯一来源；新增端点必须同时进入共享常量与白名单，两者零漂移；
- 未知端点 404、参数缺失 400；调用方错误不得被响应成 500；
- 领域模块只抛稳定错误码，HTTP 状态映射只发生在边界；领域模块不得引用传输层错误类型；
- 响应包形状、错误码语义与端点名属对外契约，变更必须同步客户端、协议常量与测试。

## 状态与副作用

- 本层不持有业务状态：不缓存领域数据、不自建持久化、不保存跨请求可变的实例字段；
- 领域能力只经宿主能力缝注入；能力缺失必须给出明确错误或降级响应，不得静默失效；
- 流式端点必须绑定请求中止信号，在请求结束或断连时释放上游资源；
- 副作用（落盘、子进程、网络调用）必须经对应领域模块的入口，不得在端点或辅助函数中直接实施。

## 依赖边界

- 端点组之间不得互相依赖——新增端点组只登记到汇聚清单；
- 跨模块协作只经能力缝、命令、事件或服务；不得直接修改其他模块的内部状态。

## 核心原则

薄边界、单向依赖、契约稳定、无状态、错误可翻译。