AGENTS.md@src/host git:20260922.e71ebaeA

Immutable. This exact content never changes and is served at /api/v1/blob/23c4a43ad37ed271.

# Host Root Rules（跨模块规范）

适用于 `src/host/` 下**不属于任何业务模块**的部分。本文件只写 Host 半区跨模块的稳定规则；
各模块内部的治理规则以各模块 `AGENTS.md` 为准，通用规范遵循根 `AGENTS.md`，测试规范遵循 `tests/AGENTS.md`。
本文件不描述当前文件结构、文件名或实现层级；文件移动、拆分或重命名不改变本文件。

## 本层承担什么

Host 根是「包级入口 + 宿主组合 + 宿主级横切契约」的落点，职责只有三类：

1. **包级入口**：对外发布路径固定的插件入口（主插件入口与服务进程入口）。入口只做装配与协调；
2. **宿主组合根**：装配各模块公共能力、建立事件观察、汇总生命周期与清理；
3. **宿主级横切契约**：多个模块共同消费、但不属于任一模块领域的最小契约（输入校验、官方服务最小结构、跨进程共享的解析规则等）。

判断标准：一段代码若只服务一个模块，归属该模块；若被**两个以上模块**以相同语义消费，且它不拥有任何业务状态，
才属于本层。禁止把本层当作「放不下的代码」的收容所。

## 入口规则

- 入口只做三件事：解析装配参数、装配模块能力、协调进程/插件生命周期。**不承载业务语义**（领域决策、协议实现、官方服务适配一律归对应模块）；
- 装配所需的默认值必须来自配置契约的**唯一来源**，入口不得复制默认值清单、校验清单或字段映射；
- 入口对模块的引用只走模块的**公共入口或对外契约文件**（模块声明为对外能力的文件），不得触达内部实现细节；
- 入口的失败必须显式（明确错误 / 非零退出码），不得静默降级成「少装配了一部分」。

## 横切契约规则

- **单一来源**：同一官方能力的最小结构契约、同一官方服务的枚举投影、同一解析规则，全 Host 只允许一处实现；
  任一模块自建第二份最小结构，等于给官方契约增加一个漂移点——本层必须提供该契约，各模块消费而非复制；
- **零业务状态**：横切契约只含纯结构类型与纯函数（解析、投影、校验）；不持有实例状态、缓存、定时器或生命周期；
- **不决定降级语义**：契约只表达事实（服务是否可用、清单是什么），缺失时的降级（报错 / 空清单 / 告警）由调用方按各自语义决定；
- **依赖方向**：横切契约只允许依赖 shared 的纯类型与 Node 内置能力；**不得**反向依赖任何业务模块，也不得依赖 api / client。

## 宿主组合根规则

- 组合根是本层唯一的「知道所有模块」的位置：装配顺序、事件观察、清理顺序在此显式排列，模块之间不得互相偷偷装配；
- 事件观察只做「翻译与转发」：把官方事件翻译成领域调用，不在组合根里实现领域判断；
- 生命周期汇总按**依赖逆序**清理，且每一步都幂等；子资源的撤销权归宿主，模块不得自建第二套撤销表；
- 官方事件与官方 payload 的本地声明属于 program 级事实，只允许在本层收窄声明（只声明本插件真正消费的字段），
  不得伪造官方不存在的契约；对形状漂移一律运行时守卫 + 降级，不得因未知字段抛错。

## 跨模块协作

- 两个模块需要共享同一能力时，优先「一方提供公共入口 + 另一方经注入消费」，其次才是本层的横切契约；
  本层只承接**无领域归属**的共同事实，不承接「两个模块的协作逻辑」；
- 禁止跨模块直接修改对方内部状态；跨进程协作只经磁盘事实与启动参数，不共享内存；
- 同一概念（官方服务的候选清单、路由注册契约、配置字段）只允许一处字面量与一处映射。

## 修改前确认

1. 这段代码属于包级入口、宿主组合，还是横切契约？有没有更合适的模块归属？
2. 是否在入口里复制了模块内的默认值、校验或映射（第二份事实源）？
3. 是否新增了第二个「官方能力最小结构」声明？
4. 横切契约是否持有状态、依赖了业务模块，或替调用方决定了降级语义？
5. 包级入口的对外路径、退出码与启动参数契约是否变化？调用方、装配产物与测试是否同步？

## 核心原则

包级入口只装配不承载语义；横切契约单一来源且无状态；官方能力只收窄不伪造；宿主组合显式且生命周期可追踪；
模块内聚、依赖单向、协作经公共入口。