# Plan 可重生运行时

> 对应 `plan.md` §3.1 / §4.3。本切片只提供服务端治理模型、持久化和最小 API，不解释算法载荷，也不写 APS 世界状态。

## 运行时契约

L0 意图、L1 策略、L2 任务、L3 动作共用 `PlanNode`。每个版本完整保存 `planId/layer/parentId/version/regenCount/inputsHash/status/payload/evidenceRefs/createdAt/createdBy`，并由 `shared/schemas/plan_node.schema.json` 封闭字段集合。

HTTP 创建与重生请求不接受 `createdBy`；Gateway 将其固定派生为 `USER`，防止客户端伪造 `SYSTEM/LLM` 治理来源。内部 Agent/System 只能通过进程内 `PlanStore` API 显式写入对应来源。

- L0 的 `parentId` 必须为空；L1/L2/L3 分别只能引用 L0/L1/L2 Plan。
- 首版固定为 `version=1`、`regenCount=0`。
- 重生沿用同一 `planId/layer/parentId/inputsHash`，只追加新版本；旧版本不更新、不删除。
- `payload` 是治理层不透明 JSON。算法模块自行定义内容，运行时不耦合求解器字段。

## 输入指纹与熔断

`inputsHash` 是输入 JSON 按对象键排序、紧凑编码后的 SHA-256。重生请求必须同时满足：

1. `expectedInputsHash` 与请求 `inputs` 的实际哈希一致；
2. 实际哈希与该 Plan 最新版本的 `inputsHash` 一致。

任一条件失败都返回 `409 PLAN_INPUTS_HASH_MISMATCH`，且不追加版本。默认最多重生 3 次；再请求返回 `409 PLAN_REGEN_FUSED`，由人工处理。阈值可通过 `APS_PLAN_REGEN_LIMIT` 配置。

## API 与权力边界

| 端点 | 等级 | 语义 |
| --- | --- | --- |
| `POST /api/plans` | P1 | 创建首个不可变版本 |
| `GET /api/plans/{planId}` | P0 | 读取最新版本 |
| `GET /api/plans/{planId}/versions` | P0 | 按版本升序读取完整历史 |
| `POST /api/plans/{planId}/regenerate` | P1 | 校验输入哈希后追加新版本 |

HTTP 认证与项目写权限继续由 Gateway 的统一中间件负责。存储文件位于当前租户/项目世界文件同目录的 `plans.json`，写入采用同目录临时文件加原子替换。

## 当前边界

本切片没有接入 LLM 自动分层、时间线 UI、审计哈希链事件或算法执行；这些消费者后续只应通过 Plan API/模型交换数据，不应直接改写历史版本。单进程线程并发由互斥锁保护，跨进程并发需要后续迁移数据库或增加文件锁。