# Trace API 覆盖矩阵门禁

本文件用于解决“Trace 已经命中 WebAPI，但补环境阶段仍反复遇错新增 WebAPI”的流程问题。只要存在 RuyiTrace NDJSON、Node trace、`missing-env.json`、Hook 环境访问日志或等价环境日志，进入第一版 Node.js 补环境实现前必须读取本文件。

## 核心原则

- Trace 不是调试参考，而是首轮补环境范围的主输入。
- 已在 Trace 中命中的 WebAPI 不得等到 `ReferenceError`、`undefined.prototype`、writer 不触发或 body 长度异常时再临时补。
- Node probe 只用于验证覆盖、发现 Trace 未覆盖的新动态分支和定位行为差异；不得把 probe 当作主要 WebAPI 发现机制。
- Trace 能确认“访问了什么”，但不一定能确认“真实返回值是什么”。需要真实值或浏览器行为语义的 API 必须在矩阵中标为“需要同 baseline 采样”，不得先挂空壳。
- inventory 不能证明 runtime 正确。第一轮实现后必须继续按 `trace-runtime-conformance.md` 生成可执行行为契约、运行 no-send Node audit 并完成 P0/P1 深度 diff。
- `implemented-first-pass` 不是人工状态；只有实现文件存在、runtime 实际加载且 Trace-runtime audit 通过后才能使用。

## 必须产物

进入第一版 `env` / `node-runtime` / signer probe 前，必须生成并写入：

```text
case/notes/trace-api-inventory.json
case/notes/env-coverage-matrix.md
case/notes/missing-env-priority.md
case/notes/trace-runtime-contract.json
case/tmp/node-trace-runtime-audit.json
case/notes/trace-runtime-diff.md
```

`trace-api-inventory.json` 至少包含：

```json
{
  "schemaVersion": "trace-api-coverage/v1",
  "source": "RuyiTrace NDJSON / Node trace / Hook",
  "baselineId": "fp-example-001",
  "apis": [
    {
      "api": "navigator.userAgent",
      "category": "navigator",
      "priority": "P0",
      "accessTypes": ["get"],
      "count": 12,
      "evidence": ["stack.file:line:col"],
      "traceStatus": "complete",
      "implementationStatus": "planned-first-pass",
      "implementationFile": "result/src/node-runtime/env/browser-objects/navigator.js",
      "samplingRequired": false,
      "reason": "Trace 命中，基础 navigator 字段必须首轮实现"
    }
  ]
}
```

`env-coverage-matrix.md` 至少包含：

- Trace 来源、日志覆盖范围、`baselineId`、是否存在 profile / baseline 冲突。
- P0/P1/P2 分类规则。
- 每个 Trace 命中 API 的处理状态。
- 首轮必须实现清单。
- 需要同 baseline 采样后实现清单。
- 暂不挂载清单及原因。
- native 能力缺口清单。
- 计划外新增 WebAPI 记录方式。

## API 状态枚举

每个 Trace 命中的 API 必须选择一个状态：

| 状态 | 含义 | 是否允许进入第一版 env |
|---|---|---|
| `planned-first-pass` | Trace 已命中，首轮必须实现 | 允许，但必须在第一版 env 实现后再 probe |
| `implemented-first-pass` | 已在第一版 env 中实现 | 允许 |
| `needs-baseline-sampling` | 需要同一 `baselineId` 下采样真实值或行为 | 允许作为阻塞采样项，不允许挂空壳 |
| `deferred-not-mounted` | 暂不挂载，且有明确证据说明目标路径不需要或挂载会扰动 writer | 允许，但必须写原因 |
| `native-capability-gap` | 纯 JS / addon / xbs 当前能力都无法可靠表达 | 阻塞，进入 native 能力缺口闭环 |
| `unplanned` | 未规划 | 不允许进入补环境实现 |
| `live-discovered` | Trace 未覆盖，后续 live probe 新分支发现 | 允许后续新增，但必须说明为什么 Trace 未覆盖 |
| `missed-from-trace` | Trace 已命中但前置矩阵遗漏 | 流程缺陷；必须修正矩阵并记录防回退 |

## 优先级规则

P0：影响 JS 能否执行、writer 是否可达、Cookie / Storage / XHR / fetch / sendBeacon / window / document / location / navigator 基础字段 / Function.toString / Node 泄露阻断的 API。

P1：影响高强度检测分支、指纹结构、DOM / CSSOM / 事件 / performance / time / random / screen / Permissions / Plugins / MimeTypes 的 API。

P2：业务页分支、第三方脚本、低频能力、非当前 writer 路径的 API。

P0/P1 中 Trace 已命中的基础 WebAPI 不允许“先不补，遇错再补”。如果暂不实现，必须是 `needs-baseline-sampling`、`deferred-not-mounted` 或 `native-capability-gap`，并写清证据。

进入 signer probe、真实请求或 final writer 判断前，所有 P0/P1 必须进一步通过：

```bash
node scripts/build_trace_runtime_contract.js --case-dir case --baseline-id <baselineId> --markdown
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
node scripts/check_trace_api_coverage.js --case-dir case --require-runtime-closure --markdown
```

具体契约字段、audit-only 环境变量和哈希失效规则见 `trace-runtime-conformance.md`。

## 真实值类 API

以下 API 不允许先挂空壳或随机值：

- Canvas：`toDataURL`、`getImageData`、`measureText`
- WebGL / WebGPU：`getParameter`、`readPixels`、adapter / renderer 信息
- Audio：`getChannelData`、OfflineAudioContext 渲染结果
- DOM 几何：`getBoundingClientRect`、`offsetWidth`、`clientWidth`、字体测量
- Speech / voices、Storage estimate、Permissions 状态、Plugins / MimeTypes

处理方式：

1. Trace 已命中但值缺失、截断、baseline 不一致时，矩阵标为 `needs-baseline-sampling`。
2. 在同一 `baselineId` 下采样完整值或短行为。
3. 接入 fixture 回放。
4. 输出 `fingerprintReplayMisses` 或等价 miss 明细。
5. miss 非空时不得声明指纹回放闭环。

## 后续阶段新增 WebAPI 规则

阶段报告中不得再笼统写“本阶段新增 / 修改的 WebAPI”而不解释来源。必须拆成：

1. Trace 计划内首轮实现 / 调整的 WebAPI。
2. 计划外新增 WebAPI 与原因。

如果新增 / 调整涉及 `XMLHttpRequest`、`fetch`、`sendBeacon`，阶段报告还必须记录 XHR/fetch Session Bridge 模式；如果涉及浏览器对象内部状态、属性枚举或 descriptor，阶段报告还必须记录对象形状审计矩阵和 `_` / `__` 私有状态泄露检查结果。

计划外新增只能属于以下原因之一：

- `trace-not-covered`：原 Trace 没覆盖该动态分支。
- `dynamic-resource-new-branch`：运行时刷新到新的动态 JS / chunk / challenge 分支。
- `baseline-mismatch`：Trace profile 与 fixed baseline 不一致，需重新采样后实现。
- `trace-truncated`：Trace 字段疑似 4000 / 4096 截断，需补采。
- `native-gap`：前置矩阵已标记为 native 能力缺口。
- `missed-from-trace`：Trace 已命中但矩阵遗漏。该项必须标为流程缺陷，补写矩阵和代码变更记忆后才能继续。

如果计划外新增 WebAPI 的真实原因是 `missed-from-trace`，不得把它写成普通能力增量。

## 检查命令

存在 Trace 的 case 在进入 signer probe 前和交付前都应运行：

```bash
node scripts/check_trace_api_coverage.js --case-dir case --markdown
node scripts/check_trace_api_coverage.js --case-dir case --require-stage-audit --require-runtime-closure --json
```

检查失败时，下一阶段只能修复 Trace 覆盖矩阵或补齐首轮实现，不能继续新增 signer、发送请求或宣称阶段验证通过。