# 慧博真实性能协调器 UTF-8 与写前校验修复方案 V001

- task_id：`DEV-ANA-HIBOR-FAST-COLLECTION-20260729-001`
- repair_id：`REPAIR-ANA-HIBOR-FAST-COLLECTION-COORDINATOR-UTF8-20260730-001`
- owner / reviewer：`dev.developer.ana.cai` / `dev.reviewer.ana.cai`
- predecessor：`AUDIT-DEV-ANA-HIBOR-FAST-COLLECTION-REAL-PERFORMANCE-SUCCESSOR-FAILURE-001=PASS_FAILURE_PATH/1/1`
- blocker：`BLOCK-HIBOR-PERF-SUCCESSOR-FAILURE-01=COORDINATOR_UNICODE_TRANSPORT_AND_PREMUTATION_VALIDATION_GAP`
- functional baseline：`CODE-DESIGN-ANA-HIBOR-FAST-COLLECTION-V011`、`TEST-PLAN-ANA-HIBOR-FAST-COLLECTION-REAL-PERFORMANCE-V003`

## 1. 目标与边界

修复真实性能执行入口，不改变采集器的 FAST 选择、额度、归档、manifest、terminal 或 SLA 语义：

1. 不再把含中文 literal 的 Python 源码通过 PowerShell native pipeline、`python -c` 或 shell 重编码链传输。
2. 在创建 evidence root、子目录或文件之前，先于内存完成 execution context 的 schema、固定值、Unicode codepoint、UTF-8、JSON roundtrip 与目标路径校验。
3. 未来真实性能执行使用新的 evidence root；旧 `HIBOR-FAST-PERFORMANCE-20260730-003` 及其唯一失败文件永久只读，不删除、不覆盖、不补造。
4. 本修复阶段只修改本方案列出的 Python 源码、测试和开发登记，只运行 compile/unit/subprocess regression。禁止真实 APP/ADB、quota、download、pdfinfo、数据库、网络、正文分析、研究结论和 `BATCH-001`。

本方案使用项目已批准的 L1 可修复重跑与语义验收规则。只有失败 evidence root、正式 receipt/manifest 等真实消费者证据保持强不可变；普通源码和测试不做无消费者价值的逐字节冻结。

## 2. 方案

### 2.1 物理 UTF-8 协调入口

新增 `dev/ana-dev/hibor_fast_collection/performance_coordinator.py`，以受审的物理 UTF-8 Python 模块承载固定中文主题。未来入口只允许：

```text
<reviewed-python> -m hibor_fast_collection.performance_coordinator --evidence-root <new-exact-root> [--started-at-utc <UTC-Z>]
```

argv 只含 ASCII 选项、ASCII 路径和 UTC 文本；不接收 Python 源码，不接收 stdin 源码，不接收 subject/task/design/timezone/trigger-cap 覆盖值，不使用 PowerShell native pipe。中文固定值只从物理模块加载。

### 2.2 唯一 execution context 构造

在 `performance.py` 中保留既有 8 键 schema，并抽出可复用的纯内存构造/校验入口。协调器按固定顺序构造：

1. `schema_version=HIBOR_FAST_PERFORMANCE_EXECUTION_CONTEXT_V001`
2. `task_id=DEV-ANA-HIBOR-FAST-COLLECTION-20260729-001`
3. `design_plan_id=PERF-TEST-PLAN-ANA-HIBOR-FAST-COLLECTION-V003`
4. `evidence_root=<new-exact-root>`
5. `execution_started_at_utc=<valid UTC-Z>`
6. `timezone=Asia/Shanghai`
7. `trigger_cap=10`
8. `subjects=[三环集团,国瓷材料,MLCC]`

固定主题 codepoint 必须分别为：

- `三环集团`：`U+4E09 U+73AF U+96C6 U+56E2`
- `国瓷材料`：`U+56FD U+74F7 U+6750 U+6599`
- `MLCC`：`U+004D U+004C U+0043 U+0043`

纯内存 gate 顺序：参数与 root 校验 → 8 键/固定值/UTC 校验 → codepoint 校验 → canonical UTF-8 JSON 构造 → strict UTF-8 decode → JSON parse → canonical reserialize byte equality。任一步失败时 evidence root 必须仍不存在。

### 2.3 首次写盘与失败闭包

只有纯内存 gate 全部通过后，协调器才可依次：

1. `mkdir` 新 evidence root（必须原先不存在）；
2. `mkdir control`（必须新建）；
3. exclusive/no-overwrite 写 `control/execution_context.json`；
4. flush/close 后重新读取，验证 ordinary file、bytes、SHA-256、strict JSON、canonical roundtrip 和完整固定值；
5. 输出不含凭据的 receipt（path、bytes、sha256、execution_started_at_utc）。

root 已存在、link/reparse 或对象类型异常、父目录异常、写入冲突、partial/flush/reopen/hash 漂移均失败关闭；不得删除、重命名、修补或重写已出现的子集。协调器本身不启动 ADB、APP、pdfinfo、数据库或第二个 Python 进程。

未来 production root 使用新的版本化路径，默认候选为 `E:\mb-ms-doc\project-info\ana-data\tmp\HIBOR-FAST-PERFORMANCE-20260730-004`；最终 exact root 仍由新的管理执行授权绑定。实现不能访问旧 `...-003`。

## 3. 代码变更范围

- 新增 `dev/ana-dev/hibor_fast_collection/performance_coordinator.py`。
- 修改 `dev/ana-dev/hibor_fast_collection/performance.py`：提供纯内存 execution-context 构造/校验能力，并把 production root 移至新版本路径；PREPLAN/SUMMARY 既有校验不得放宽。
- 新增 `dev/ana-dev/test/hibor_fast_collection/test_performance_coordinator.py`，必要时小幅调整既有 performance 测试。
- append-only 更新 `dev-doc/ana-doc/开发方案/IMPLEMENTATION-ANA-HIBOR-FAST-COLLECTION-V001.md` 与 `dev-doc/开发执行日志.md`。

不改 FAST workflow、quota、archive、manifest、terminal public schema；不改旧 evidence package。

## 4. 验收矩阵

### 4.1 纯内存与零写入反例

每案执行后断言 root 不存在：

- 中文被替换为 `????`；
- subject 缺失、增项、错序或 Unicode codepoint 漂移；
- malformed UTF-8、BOM、非 canonical JSON 或 decode/roundtrip 异常；
- task/design/timezone/trigger-cap/root/UTC 漂移；
- root 预存在、link/reparse、父路径不是 ordinary directory。

### 4.2 正例与写后证据

- 直接 Python API 正例写出三项主题原始 UTF-8，codepoint 与固定值一致。
- 使用实际 Windows subprocess 启动物理 `-m` 模块，正例保持两项中文，不经过 PowerShell source pipe。
- 正例只有一次 root/control/context 创建；文件 canonical parse/serialize 一致，receipt bytes/hash 与实际文件一致。
- exact replay 不能再次写；已有不同对象不能覆盖；模拟写入/flush/reopen/hash 故障保留实际子集并停止。

### 4.3 无回退

- `python -m compileall -q hibor_fast_collection test\hibor_fast_collection`
- `python -m unittest discover -s test\hibor_fast_collection -p test_*.py -v`
- 新增 Windows subprocess regression 只在临时目录运行物理模块，不接触 APP/ADB/quota/download。
- 既有 46 项 PREPLAN/SUMMARY fake 回归全部通过。
- `git diff --check` 与 `mbx validate --project project-info --governance` 通过。

## 5. Gate 与交付

1. 本方案先提交 exact `dev.reviewer.ana.cai` 独立方案审核。
2. 方案 PASS 后才实施上述源码与离线测试；实现完成后提交同一 reviewer 独立实现复审。
3. 只有实现复审 `PASS/0/0` 后，才可向 management 申请全新 authorization/attempt/chain 和新 evidence root。
4. 新授权未到达前，不运行真实性能 coordinator、ADB/APP、discovery、quota、download 或样本；旧 A001 永不重试或复用。

当前状态：`PENDING_INDEPENDENT_COORDINATOR_UTF8_REPAIR_PLAN_REVIEW`。