# Trace-runtime 可执行一致性闭环

本文件用于解决“Trace 已命中并进入 inventory，但当前 runtime 仍存在大量未补、错误返回、错误原型或错误分支”的问题。Trace inventory 只说明 API 被发现；只有本文件定义的行为契约、Node audit 和深度 diff 全部通过，才能说明环境闭环。

## 硬性原则

- Trace 必须转换成机器可验证的 `trace-runtime-contract.json`，不能只生成 API 名称和人工状态。
- `implemented-first-pass` 只有在实现文件存在、runtime 实际加载、audit-only 执行成功且 P0/P1 深度 diff 为零时才成立。
- `matched` 必须由 `check_trace_runtime_conformance.js` 计算，不得由 Markdown 或手写 JSON 自行声明。
- 每次修改 `result/`、刷新动态 JS、切换 baseline 或重新采集 Trace 后，旧 audit 立即失效；必须重新计算 `traceSourceHash`、`contractHash` 和 `runtimeSourceHash`。
- Trace-runtime audit 必须在 `no-send` 模式运行。审计阶段禁止访问目标网络，XHR/fetch 只允许记录准备发送的 transcript。
- 在 P0/P1 runtime closure 完成前，不得运行真实请求、不得继续扩大 POST 次数、不得把 writer 未触发归因于流程或 TLS。
- 状态型 API 必须比较原始 happens-before 时间线。不得把 sequence 排序后只比数量，也不得从按 API 分组的 observations 反推全局顺序。
- 自动发现到多份原始 Trace 时不得跨历史采集静默合并；必须使用 `--trace` 显式选择当前 `baselineId` 的完整 Trace。多文件分片只有在事件 sequence 跨文件全局唯一时才允许合并。

## 强制产物

```text
case/notes/trace-runtime-contract.json
case/tmp/node-trace-runtime-audit.json
case/notes/trace-runtime-diff.md
```

`trace-runtime-contract.json` 必须由以下命令从原始 Trace 生成：

```bash
node scripts/build_trace_runtime_contract.js --case-dir case --trace case/ruyi-trace/logs/current.ndjson --baseline-id <baselineId> --markdown
```

不得手工创建空 contract，也不得只保留 Top 30 API。所有不同的 API、access type、realm、receiver 和 phase 组合都必须进入契约。

## 契约维度

Trace 有证据时必须记录：

- API path、访问类型、receiver、realm、writer/navigation phase。
- owner、descriptor、getter/setter 所在 prototype。
- `Object.prototype.toString` brand、constructor name、`instanceof`。
- `Object.keys`、own names、own symbols、`Reflect.ownKeys`。
- prototype chain，包括 XHR/EventTarget 等中间原型层。
- 参数、返回值、异常和副作用的稳定摘要。
- 调用顺序、stack 证据和 navigation epoch。
- XHR open/send/readyState、reload/navigation、Worker/MessagePort、terminate/close、DOM mutation 和 observer callback 等状态事件的折叠时间线、完整 sequence hash 与来源 Trace。

缺少真实值时应标记为待同 baseline 采样，而不是用空值或默认值生成匹配契约。

## audit-only 入口

最终入口或专用内部审计模式必须支持：

```text
--audit-only
WEB_JS_ENV_PATCHER_AUDIT_ONLY=1
WEB_JS_ENV_PATCHER_NO_NETWORK=1
WEB_JS_ENV_PATCHER_NETWORK_MODE=no-send
WEB_JS_ENV_PATCHER_TRACE_CONTRACT=<contract path>
WEB_JS_ENV_PATCHER_TRACE_AUDIT_OUT=<audit path>
```

audit-only 模式：

- 必须安装与正常运行完全相同的 env/runtime。
- 必须执行目标初始化和当前 signer/writer 路径，但网络层只记录请求，不发送目标网络。
- 必须把逐项观测写入 `WEB_JS_ENV_PATCHER_TRACE_AUDIT_OUT`。
- 不得额外安装“只在审计时存在”的假 API。
- 不得通过读取 contract 后直接复制 expected 值生成 audit。
- 必须记录真实网络尝试次数；大于零直接失败。

入口写出的原始 observations 至少使用以下结构：

```json
{
  "probeVersion": "case-runtime-audit/v3",
  "networkAttempts": 0,
  "timeline": [
    {"contractId": "contract item id", "sequence": 101},
    {"contractId": "another contract item id", "sequence": 102}
  ],
  "observations": [
    {
      "id": "contract item id",
      "api": "XMLHttpRequest",
      "accessType": "construct",
      "realm": "main",
      "receiver": "Window",
      "phase": "challenge-init",
      "observations": {
        "owner": ["XMLHttpRequest"],
        "brand": ["[object XMLHttpRequest]"],
        "constructorName": ["XMLHttpRequest"],
        "prototypeChain": [["XMLHttpRequest", "XMLHttpRequestEventTarget", "EventTarget", "Object"]],
        "ownKeys": [[]]
      }
    }
  ]
}
```

`id` 应直接使用 contract item id。观测值必须来自当前 runtime 的真实 probe，不得复制 contract 中的 digest；`run_trace_runtime_audit.js` 会统一计算并写入可信元数据。

`timeline` 必须由 runtime 在事件实际发生时追加，且保留严格递增 sequence。只给每个 observation 填写局部 `sequences`、再由审计脚本排序重建，不足以证明交错事件、terminate/close、reload 销毁或 DOM mutation 的真实顺序。

运行：

```bash
node scripts/run_trace_runtime_audit.js --case-dir case --entry case/result/final.js --markdown
node scripts/check_trace_runtime_conformance.js --case-dir case --markdown
```

Python 入口使用 `case/result/final.py`。

## 阻断条件

- contract 或 Node audit 缺失。
- `contractHash`、`traceSourceHash`、`baselineId` 不一致。
- Node audit 缺少 `runtimeSourceHash` 或 `probeVersion`。
- audit-only 阶段发生真实网络访问。
- contract 仍为 v1/v2、Node audit 仍为 v1/v2，或 timeline 不是由原始 runtime event timeline 生成。
- 多份 Trace 无法建立唯一全局顺序，或 browser/Node 折叠状态时间线 hash 不一致。
- 任一 P0/P1 契约缺少 runtime observation。
- owner、descriptor、brand、prototype、ownKeys、返回值、异常或副作用不一致。
- Node 多出 Trace 未记录的宿主 API 观测，且未分类为动态新分支或 Node 泄露。

P2 差异可记录为风险，但涉及当前 writer、请求生成、Cookie、fingerprint 或检测分支时必须提升为 P0/P1。

## 强制循环

```text
原始 Trace
  -> build_trace_runtime_contract
  -> 第一轮 env
  -> run_trace_runtime_audit(no-send)
  -> check_trace_runtime_conformance
  -> 修复差异
  -> 重新 audit
  -> P0/P1 差异清零
  -> XHR/fetch 请求语义审计
  -> 真实请求
```

用户不需要额外提出“把 Trace 和当前环境一一对比”；只要存在 Trace，该循环就是默认流程。