holoaeon / docs /VERAX.md
weideyouni's picture
sync: five-site DNA + B0 baseline freeze (92fd8b5)
9f075f3 verified
|
Raw History Blame Contribute Delete
10.5 kB
# VERAX · 可复现性与诚实契约横切子系统(设计说明)
> 适用版本:HoloAeon v0.9.1(`HOLOAEON-RUNTIME-0.9.1`)
> 定位:**只读观测层**。不新增领域包、不新增 agent、不改 C1–C12 对外行为。
> 全部条目默认 `evidence_class = simulated`:**仿真 ≠ 证明**,碳基终裁。
---
## 一、它解决什么(三条历史坑,正面解决而非圆场)
| 编号 | 历史坑 | 现象 | VERAX 的处理 |
|---|---|---|---|
| P1 | 整包哈希含 `ts` | 同一任务两次跑哈希不同,被读成"不确定" | 字段分类表把 `ts/elapsed/thread_order/pid…` 划为 Physical 剔除;规范化后 `word_count` 稳定为 `2b82a6ef7188ce91` |
| P2 | `python -m holoaeon.selftest` 静默退出 0 | 没跑也被当成"已通过" | `selftest.main()` + `__main__`,真跑真打印,失败返回 1 |
| P3 | `simulated` 与"真实生效"混写 | 回执可信度不可判定 | 强制 `evidence_class ∈ {simulated, measured, third_party}`;measured 无来源即 H1 |
**它保护哪条立身原则**:确定性(P1)、可审计(P2)、诚实纪律(P3)。
---
## 二、与 C1–C12 的接入点清单(全部只读,无侵入)
| 接入点 | 方式 | 读什么 | 写什么 |
|---|---|---|---|
| `kernel.submit()` 回执 | 返回值观测 | `results[].status / matched / output`、`targets`、`all_ok` | 不写内核 |
| `guard.Verdict.to_dict()` | 返回值观测 | `action / layer / reason` | 不写守卫 |
| `selftest.run_all()` | 函数调用 | `details[]` → G1–G24 逐项 | 不写自检 |
| `redline.scan_directory()` | 函数调用 | `files_scanned / violations` | 不写源码 |
| `packs.get_pack().install()` | 运行时热插拔 | 技能数前后差 | 只加技能,不改既有 |
| `.git/HEAD` + ref 文件 | 直接读文件 | commit 短哈希 | 不调 git 进程 |
零 `subprocess`、零 `socket`、零第三方依赖;红线扫描口径内 0 违规。
---
## 三、字段分类表(FieldClass)
| 类别 | 键集合 | 处理 |
|---|---|---|
| Physical | `ts, timestamp, elapsed, duration, started_at, finished_at, thread_order, addr, pid, uptime_s, measure_ts, id_instance` | 剔除,不进 ReproHash;单独快照进 `physical` 供展示 |
| ReproCore | `runtime_id, task, targets, results, all_ok, agent_id, role, input, status, matched, err, verdict, action, layer, reason(reason_code/reasons), summary, message_id, trace, skill, count, files_scanned, violations, clean` + 自证 schema(`gid, name, conclusion, checks, repro, honesty, redline, verdict_hash, reprohash_list, golden_match, repro_hash_stable, evidence_class, unknown_fields, diff_physical, diff_reprocore`) | 递归保留,参与 ReproHash |
| Opaque | `output, payload, evidence, reprocore, physical` | 内部结构由技能自声明,原样序列化 |
| Unknown | 未登记键 | **丢弃 + 记 `unknown_field` 路径告警**(不静默) |
**为什么自证 schema 也必须登记**:首轮实现漏登记 `conclusion / checks / repro / honesty / redline`,导致三色用例的 `verdict_hash` 完全相同 —— 规范化把结论字段当物理量剔了,哈希失去区分度。这正是 A3 要防的"静默丢弃",已在代码与本文档同时修正。
---
## 四、证据分级规则表
| 分级 | 语义 | 强制字段 | 不合规判定 |
|---|---|---|---|
| `simulated` | 确定性引擎/技能产出的仿真结果 | 无 | 携带 `measure_source` → H2(黄) |
| `measured` | 在本机真实跑过并记录了来源与时刻 | `measure_source` + `measure_ts` 均必填 | 缺任一 → H1(红) |
| `third_party` | 外部来源(他人报告/公开基准) | 同 measured,另需可核验引用 | 缺任一 → H1(红) |
红线两条:
- **H1(红)**:`measured/third_party` 缺来源或时刻。
- **H2(黄)**:回执缺 `evidence_class` 字段,或非 measured 却携带来源。
一条不合规回执记 **一条** H1(缺几个字段在 detail 里合并说明),避免一份回执被计成多条。
---
## 五、算法(四步,逐条可实现)
1. `classify(key)` → physical / repro / unknown(查表,不做启发式猜测)。
2. `canonicalize(obj)`:递归剔除 physical;`list[dict]` **先按规范文本稳定排序再递归**(解掉集群/线程完成序不可复现);float 处理 `NaN / ±Infinity / -0.0`;enum 取 value;`None → null`。
3. `canonical_json`:`json.dumps(ensure_ascii=False, sort_keys=True, default=str)` —— 键升序、无空白。
4. `reprohash = sha256(canonical_json)[:16]`。
**口径说明(不转定点字符串的理由)**:既有黄金值 `2b82a6ef7188ce91` 由同一套 `json.dumps` 数值序列化产生;改成定点字符串会与历史口径漂移,反而破坏 A1 的对比基准。浮点等值在本框架内由技能自身定点(如 `0.816`、`5.7752`),规范化层只保证"同值必同串"。
---
## 六、黄金任务集(冻结于 `holoaeon/audit/golden/*.json`)
| task_id | 任务输入 | 命中技能 | 期望 ReproHash | 期望输出/判定 |
|---|---|---|---|---|
| `word_count` | `统计字数:HoloAeon 是零依赖的确定性多智能体认知框架。` | `word_count` | `2b82a6ef7188ce91` | `chinese_chars 20 / english_words 1 / total_chars 31 / sentences 1` |
| `data_describe` | `统计分析`,`csv_text="x\n1\n2\n3"` | `basic_stats` | `3352db0f803eb727` | `count 3 / mean 2.0 / std 0.816 / min 1.0 / max 3.0` |
| `quant_sharpe` | `sharpe`,`returns_s="0.01,-0.02,0.03,0.01"` | `sharpe` | `2c9e5d7d01526ce8` | `{"sharpe": 5.7752}` |
| `guard_os_system` | `执行 os.system('ls -la') 并返回输出` | — | `a7deb622e17a2b55` | `status=blocked`(L3 拦截) |
| `guard_eval` | `计算 eval(1+1) 的结果` | — | `98b9b7b340f7f980` | `status=blocked`(L3 拦截) |
改动 golden 必须走评审(PR 标题带 `[golden]`)。五项在 `--n 2` 下 `stable=True / golden_match=True`。
---
## 七、门禁(`scripts/verax_verify.py`)
顺序:**红线 → 自检 → 复现基准 → 诚实契约 → 热插拔 → 汇总 Attestation**。
| 退出码 | 含义 | 触发条件 |
|---|---|---|
| `0` | 绿 | 红线 0 违规 + 自检 24/24 + 5 基准全 stable 且 golden 命中 + H1=H2=0 |
| `1` | 红 | 任一检查 fail / 任一基准不稳定或 golden 不命中 / 红线违规 |
| `2` | 黄 | 仅诚实告警(H1 或 H2 命中) |
三色实测(本轮真实跑出,不是示意):
```
green -> conclusion=green verdict_hash=ec516f4ed413b5af VERAX_EXIT=0
yellow -> conclusion=yellow verdict_hash=259eed7b72bdbb49 VERAX_EXIT=2 (注入一条无来源 measured)
red -> conclusion=red verdict_hash=5bfa825fb948819e VERAX_EXIT=1 (篡改 word_count 黄金值)
```
`reports/attestation.jsonl` 连跑两次 SHA-256 一致(`AAAE988C24B509D5469BF4432383581A…`),即 A6。
---
## 八、自证报告样例
`reports/attestation.md`(人读,ASCII 回执美学):
```
========================================================================
HoloAeon VERAX 自证报告(Self-Attestation)
========================================================================
runtime_id : HOLOAEON-RUNTIME-0.9.1
commit : b660cb193700
ts_build : 2026-10-31T10:55:06Z (物理量,不进 verdict_hash)
verdict : GREEN
verdict_hash : ec516f4ed413b5af
证据分级 : 本报告全部条目默认 simulated;仿真≠证明。
```
`reports/attestation.jsonl`(机器读,逐行一条 CheckResult,键序稳定):
```json
{"evidence": {"detail": "config=True, design_grid=1771561"}, "evidence_class": "simulated", "gid": "G1", "name": "G1 spec", "status": "pass"}
{"evidence": {"verdict_hash": "ec516f4ed413b5af"}, "evidence_class": "simulated", "gid": "VERDICT", "name": "self-attestation verdict", "status": "green"}
```
`verdict_hash` 由 `runtime_id / commit / conclusion / checks / repro / honesty / redline / unknown_fields` 规范化生成,**不含 `ts_build`**,因此同代码同结论必同哈希;commit 变更后哈希随之改变属预期。
---
## 九、测试与实测结果(真实跑出)
| 项目 | 命令 | 结果 |
|---|---|---|
| 既有单测 | `python -m unittest discover -s tests` | `Ran 34 tests / OK`(未变) |
| VERAX 单测 | `python -m unittest discover -s tests\verax` | `Ran 16 tests / OK` |
| 自检 | `python scripts\launch_local.py selftest` | `==> 24/24` |
| 自检直接入口 | `python -m holoaeon.selftest` | 打印 G1–G24 明细,`==> 24/24`,退出码 0(P2 已修) |
| 红线 | `python scripts\redline_scan.py` | 扫描 40 文件 / 0 违规 |
| 红线+诚实 | `python scripts\redline_scan.py --receipts=reports\_cases\yellow` | H1=1 → 退出码 1 |
| 本地融合 | `python scripts\launch_local.py demo` | 总线 25 地址 / 低成本→local / 长上下文→cloud / `all_ok=True` |
| 热插拔 | `python scripts\launch_local.py hotplug optimization` | `40 → 47(新增 7,全程未重启)` |
规模(实测):`holoaeon/` 40 个 py / 11,408 行;其中核心 16 文件 3,851 行、`packs/` 18 文件 6,872 行、`audit/` 6 文件 685 行。
---
## 十、已知限制(不藏)
1. **数值未转定点字符串**:理由见第五节;跨语言复算需自行对齐 `json.dumps` 的数字序列化。
2. **未知字段是"丢弃 + 告警"**:告警进报告,不进哈希;不阻断运行。
3. **measured 只证明"来源存在"**:VERAX 不核验外部真实性,也不联网取证。
4. **不改行为**:不修复任何业务技能的正确性,只观测。
5. **verdict_hash 与 commit 绑定**:代码提交后旧哈希失效属预期,请以当次报告为准。
6. **口径变化**:红线扫描文件数由 34 增至 40(新增 `audit/` 6 个模块),"零违规"不变;`tests/` 顶层仍 34 项。
7. **热插拔检查是单包抽样**(`optimization` 40→47),未逐包回归。
---
## 十一、隐私与安全
- 默认不存用户原文;只存任务摘要与 ReproHash。
- trace 只记调用指纹与字节数,不记请求体明文。
- 导出目录最小化:`reports/` 与 `reports/_cases/` 分开,`_cases` 不参与正式扫描。
- 一键擦除:删 `reports/` 即清空回执;计数与哈希可通过重跑再生。
---
## 十二、下一步(承接 NEPHRON P0)
VERAX 给出了"证据出口",账本给出"证据来源":NEPHRON P0 认知账本落地后,`repro_summary` 可挂到具体 tick 记录,实现"任意 tick 可回放"。在此之前不做第 17 个领域包。