# 确定性 Agent 运行时规范 v0.1（草案）

> 发起方：HoloAeon 项目（`holoaeon/spec.py` 的 `VERSION` 为版本权威源）。
> 状态：草案，条款可判定、可被第三方实现。**本规范由 HoloAeon 项目发起，欢迎他方实现。**
> 本文不定义产品形态，只定义「什么算可复现」的下限。仿真是仿真，证明是证明。

## 1 范围

本规范面向「声称自己是确定性 Agent 运行时」的任意实现，规定四件事：

1. 复现哈希（DIFF=0）怎么算，什么字段必须剔除；
2. 理由码怎么枚举，什么算「已解释」；
3. 证据怎么分级，什么算「漂移」；
4. 兼容性怎么分级，什么程度的复现算「合格实现」。

不规定：语言、框架、模型、部署形态、许可证。规范只管证据，不管路线。

## 2 术语

| 术语 | 定义 | 判定方式 |
|---|---|---|
| ReproCore 可复现核心 | 裁决、路由目标、命中技能、技能输出等「同一输入应相同」的字段集合 | 字段名登记在实现方的分类表中，未登记即未知 |
| Physical 物理量 | 时间戳、耗时、线程完成序、进程号、内存地址等「本就该每次不同」的字段 | 同上，必须显式剔除而非丢弃 |
| Canonicalize 规范化 | 剔除物理量、统一数值表示、对集合稳定排序后生成规范 JSON 的过程 | 同一逻辑输入两次输出逐字节一致 |
| ReproHash 复现哈希 | `sha256(canonical_json)` 取前 16 个十六进制字符 | 与实现方冻结的黄金值比对 |
| EvidenceClass 证据分级 | `simulated` / `measured` / `third_party` 三档 | `measured` 必须带来源与测量时刻 |
| Golden 黄金回归值 | 随代码评审冻结的期望哈希或期望输出 | 改动须在 PR 标题标注 `[golden]` |
| Self-Attestation 自证报告 | 一次全量自检 + 基准的可复算报告 | 报告自身哈希可复现，`ts_build` 不进哈希 |

## 3 DIFF=0 哈希协议

### 3.1 三条硬规则

- **R1 显式分类**：实现方必须提供字段分类表（`physical` / `repro` / `opaque`）。未登记字段按物理量处理，并**计数告警**，不得静默丢弃。
- **R2 稳定排序**：任何 `list[dict]` 先按稳定键（如 `step` / `seq` / `agent_id`）排序再递归规范化；集群完成序不可复现，必须靠排序消除。
- **R3 定值序列化**：数值统一为定点字符串（抑制浮点抖动）；枚举取 `value`；`None` 序列化为 `null`；键升序、无空白。

### 3.2 必须剔除的字段（最小集）

`ts` / `timestamp` / `elapsed` / `duration` / `started_at` / `finished_at` /
`thread_order` / `addr` / `id_runtime` / `pid` / `uptime_s` / `generated_at`。

> 反例（真实踩过）：把整包回执连 `ts` 一起哈希，必然每次不同，于是得出「不确定」的假结论。
> 另一反例：把未登记的业务字段当物理量整段剔掉，哈希对内容失去敏感性，两次跑当然相同——
> 这叫「恒真空转」，比假红灯更危险。**因此规范要求：凡 DIFF=0 的公开声称，必须同时发布篡改敏感性自检。**

### 3.3 算法

```
canonical = canonicalize(receipt)          # 按 3.1
h = sha256(canonical_json(canonical))[:16] # 前 16 hex
stable = all(h_i == h_0 for i in runs)     # runs ≥ 2，每个 run 用全新内核
```

### 3.4 敏感性自检（强制）

对 ReproCore 的任一字段做单点篡改（如把任务原文改一个字），哈希**必须**变化；
哈希不变即判定该实现「未通过本规范」，因为它的 DIFF=0 是空转。

## 4 理由码规范

### 4.1 结构

每条裁决输出固定三字段：`{action, layer, reason}`。

- `action ∈ {allow, advise, block}`，只允许三值；
- `layer` 为守卫层标识（本实现为 `L1`–`L8`：结构 / 体量 / 危险模式 / 权限 / 身份与失真 / 元数据 / 审计 / 一致性）；
- `reason` 为可枚举理由码或人类可读短语，**不得为空**。

### 4.2 理由码分层（参考 NEPHRON 27 码体例的分类法）

| 族 | 前缀 | 含义 | 例 |
|---|---|---|---|
| 结构 | `struct_` | 信封字段缺失 / 类型不符 | `struct_missing_recipient` |
| 体量 | `size_` | 载荷或配额超限 | `size_payload_over_1mib` |
| 危险 | `danger_` | 命中危险调用模式 | `danger_os_system` |
| 权限 | `perm_` | 权限等级不足 | `perm_short_2to0` |
| 身份 | `ident_` | 伪造身份或失真输入 | `ident_claim_admin` |
| 元数据 | `meta_` | trace / 模式缺失 | `meta_no_trace` |
| 审计 | `audit_` | 审计链断裂 | `audit_gap` |
| 诚实 | `hon_` | 证据分级不合规 | `hon_measured_no_source` |

### 4.3 判定口径

- 同一输入 + 同一守卫层配置 → 同一 `reason`（理由码不得含时间、随机值、进程号）；
- `block` 必须能指名命中的层与模式；说不出哪一层，就不算「已解释」。

## 5 证据防漂移协议

### 5.1 分级

| 级别 | 含义 | 强制附加字段 |
|---|---|---|
| `simulated` | 仿真 / 构造数据，默认档 | 无（`measure_source` 与 `measure_ts` 必须为 null） |
| `measured` | 本机实测 | `measure_source`（命令或路径）+ `measure_ts` |
| `third_party` | 外部来源 | `measure_source` 指向可核验出处 |

### 5.2 漂移判定

- 出现 `measured` 而缺 `measure_source` → 记诚实告警（`H1`），报告结论至少降为 yellow；
- 回执对象缺 `evidence_class` → 记诚实告警（`H2`）；
- 文档里出现「实测 / 真实生效」字样但同目录无非 `simulated` 证据 → `H1`。

### 5.3 CI 体例

```
python scripts/verax_verify.py --out reports     # 单一入口
退出码 0=绿 / 1=红（红线或复现或单测不过） / 2=黄（诚实或未知字段告警）
```

报告双导出：`reports/attestation.md`（人读）与 `reports/attestation.jsonl`（机器读，逐行一条检查）。
报告自身 `verdict_hash` 由结论字段规范化生成，`ts_build` 不参与——否则报告自己也漂移。

## 6 兼容性分级

| 等级 | 条件 | 允许的声称 |
|---|---|---|
| `full` | 两个独立 run 的 ReproHash 一致；黄金值命中；敏感性自检通过；物理量差异非空（证明剔除真的在起作用） | 「可回放 / DIFF=0」 |
| `sampled` | 仅部分任务有黄金值，或仅在固定机器上复现 | 「有限复现，未覆盖全任务」 |
| `incompatible` | 哈希不稳定，或字段分类表缺失，或敏感性自检失败 | 不得声称确定性 |

分级必须随证据一起发布；只发布等级、不发布证据，视为未分级。

## 7 自检清单（实现方逐条打勾）

- [ ] D1 字段分类表公开，未知字段计数告警（R1）
- [ ] D2 `list[dict]` 稳定排序后再规范化（R2）
- [ ] D3 数值定点化，枚举取 `value`（R3）
- [ ] D4 两次独立 run 哈希一致
- [ ] D5 篡改 ReproCore 后哈希变化（敏感性自检）
- [ ] D6 黄金值冻结并有评审标记 `[golden]`
- [ ] D7 每条裁决含非空 `reason`
- [ ] D8 回执强制 `evidence_class`，`measured` 带来源与时刻
- [ ] D9 报告 `verdict_hash` 可复现，`ts_build` 不进哈希
- [ ] D10 CI 单入口给出 0/1/2 三态退出码

HoloAeon 自身作为第一实现，D1–D10 全部通过（见 `benchmarks/README.md`、
`docs/VERAX.md`、`reports/attestation.md`）。

## 8 已知限制

- 本规范只管**单机确定性**，不管分布式一致性；
- 理由码族表是分类法，不是封闭枚举：实现方可扩展，但不得修改已有语义；
- 本实现语义通道（`holoaeon/semvec.py`）语料只取 47 条技能自述（与 `docs/` 解耦，改文档不漂移），
  实测 **12 条固定意图混合路由 11/12（误路由 8.3%）**（`scripts/bench_semvec.py` 可复跑）。
  参数是在同一批意图上选定的，含过拟合风险；留出集 6 条中 2 条期望名不存在，
  余 4 条命中 2 条，**泛化未验证**。故路由准确率不纳入本规范的合格判据，只作为披露项；
- 维度取舍：`semvec.DIM=32` 与早期投喂建议的 64 维不同。理由是 32 维与 64 维在 12 条意图上
  命中相同，而 `fit` 耗时随维数线性增长（2 GB 旧机口径），故取 32；`MAX_VOCAB=2000`、`MIN_DF=1`
  同理是为让 `review / sample` 这类只出现一两次的专名进入词表，否则查询向量会塌成零向量
  （稳定语料下实际上限用不满，实测词表 334）；
- 规范不承诺任何外部真实性：`measured` 只表示「有人在本机量过」，不等于「结论为真」。