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

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

1 范围

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

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

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

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 只表示「有人在本机量过」，不等于「结论为真」。