# Graph Module Rules

## 适用范围

适用于 `src/host/graph/`。本文件定义图契约模块特有的稳定治理边界与修改规则；通用规范遵循根 `AGENTS.md`，测试规范遵循 `tests/AGENTS.md`。

本文件描述治理原则，不是源码结构说明。文件移动、重命名或内部重构后，只要职责、事实源、依赖方向与对外契约未变，本文件不随之修改。

## 核心职责

提供「工作流图」的确定性契约与判定：图的形状与连接点语义、图的构造与只读查询、结构合法性校验与规范化、编排质量检查（问题清单）、组织元参数的归一化与规模护栏。

判断归属：该修改是否改变**图契约、图判定口径或图的规模约束**？若主要属于其他领域（运行推进、Agent 语义、Tool 协议、UI 展示、持久化），应放到对应模块。

## 非职责

- 不读写持久化、文件、网络或数据库，不管理运行锁与运行状态；
- 不推进生命周期，不拥有任何跨调用存活的状态；
- 不做 Agent 语义判断（是否重规划、是否汇报、是否改变执行策略）；
- 不注册 Tool、不定义 Tool Schema、不渲染界面；
- 不直接修改其他模块的内部状态。

## 纯函数契约

判定与计算一律为纯函数：相同输入 → 相同输出，不修改入参，不依赖全局可变状态、当前时间、随机源、文件系统或运行时实例。

- 唯一例外是节点/连线标识工厂：其唯一性需要随机来源，该来源必须封闭在工厂内部，不得扩散进任何判定或校验逻辑；
- 需要时间等外部因素时，通过显式参数传入；
- 数据必须是「传入即全部事实」：不得从环境或全局读取图状态。

## 单一事实源

同一图概念只允许一处本体。流转通道判定、可执行单元口径、问题级别、问题 code 全集等，必须有唯一来源。

- 禁止以「两份字面量」「结构镜像 + 列表断言」的方式重复维护同一契约；
- 同一口径被多处使用时，使用方引用本体，而不是各自重写；
- 跨半区（Client）因程序隔离**必须**另行实现同一口径时，两侧语义必须由**契约测试**分别锁定同一行为，不得靠跨半区 import 消除重复。

## 子域边界

本模块内部存在变化原因不同的子域：图契约与结构校验、编排质量检查、组织元参数与规模护栏。

- 子域之间只通过明确的输入输出协作，不得互相承担对方职责；
- 结构校验判定「图是否合法」（形状、连接点、拓扑）；质量检查判定「图是否编排得当」（设计提醒），不得互相重新定义对方的结论；
- 元参数护栏只约束**代理**改图，不约束用户手工改图——是否启用由调用方按变更来源决定，本模块不做来源判定；
- 新增能力先判断属于哪个子域，再放到该子域的职责中，不得为了就近而堆进已有文件。

## 问题级别与稳定 code

- 级别语义固定：阻断级即调用方拒绝落盘；提示级只提醒、不阻断；
- 问题 code 属对外契约：发布后不得改名或改级别；新增规则必须登记到 code 注册表；
- 阻断级问题必须给出可执行的修复建议（这是失败方自我修正的唯一通道）；
- 新增或修改 code 时同步检查：注册表、规则实现、聚合层、修复建议、测试。

## 公共边界

- 模块外只允许经模块的**公共入口**导入，禁止直接引用模块内部文件；
- 只把真实、稳定、可维护的契约放进公共入口，禁止「全量 barrel」把内部实现一并暴露；
- 内部实现（单条规则、内部遍历助手、自检工具等）不进入公共入口；
- 新增公共符号前先判断它是否表达对外稳定契约；放宽入口比收紧入口的代价更高。

## 依赖边界

- 只允许依赖共享契约层（Host/Client 共享的形状与协议常量）；
- 不得依赖 orchestrator / tools / agent / storage / service / api / client；
- 依赖方向单向：调用方依赖本模块的判定，本模块不反向依赖任何调用方。

## 契约稳定性

- 校验问题码、检查器 code、字段语义与级别属公共契约，修改必须同步调用方、测试与文档；
- 字段增删遵循兼容优先：新增字段默认可选；删除或改义必须说明旧数据的读取行为与兼容路径；
- 判定口径变化（例如「什么算流程线」「什么算参与流程」）属于行为变化，必须记录：旧行为 → 新行为 → 原因 → 影响范围 → 测试变化。

## 模块内部组织

- 文件结构不是架构契约，禁止为「看起来模块化」机械拆分；拆分依据只能是职责、变化原因、依赖边界与测试边界；
- 文件命名必须表达**稳定职责与所属维度**，同族文件保持一致命名维度；名称失真的文件应立即重命名并同步全部引用；
- 不得创建 `utils.ts`、`helpers.ts`、`common.ts`、`shared.ts`、`misc.ts` 等无明确职责的聚合文件；
- 内部文件之间使用相对路径导入，公共入口不含实现。

## 修改前检查

1. 改动属于图契约、结构校验、质量检查还是元参数？
2. 是否改变判定口径？受影响的上层调用方与测试是哪些？
3. 是否新增/修改稳定 code、级别或字段？注册表与测试是否同步？
4. 是否引入非纯依赖（时钟 / 随机 / IO / 全局状态）？
5. 是否产生第二份事实源？
6. 是否越界进入其他模块职责？

## 验证

至少执行：

```text
pnpm typecheck
pnpm test
pnpm build
```

同时确认：公共入口导出面未意外扩大、无旧路径残留、无循环依赖、无重复实现、判定口径变化已按契约记录。

## 核心原则

1. 图判定确定性优先，纯函数不可含隐藏依赖。
2. 同一图概念只有一处本体，禁止双份维护。
3. 结构合法性、编排质量与规模约束各守其责。
4. 问题 code 与级别是契约，新增必须登记。
5. 模块外只经公共入口协作，内部实现不外溢。
6. 依赖单向，不反向依赖调用方。
7. 判定口径变化必须显式记录并锁定测试。