@cannbot-plugin/cannbot-harness 0.0.0-stage → 0.1.4

package/assets/ops-direct-invoke/skills/ascendc-whitebox-design/references/case-mapper/S5_mapped_case_schema.md

@@ -0,0 +1,131 @@
+# S5 MappedCase Schema
+
+> 本文定义 Step 5 mapped cases 的固定数据结构。Mapper-v1 的唯一字段契约以 `S5_case_json_schema.md` 为准；本文只补充 Step 5 各阶段产物的 source、文件级约束和生命周期要求。
+
+## 1. Schema Authority
+
+所有 Step 5 输出 JSON case 必须遵守 `S5_case_json_schema.md`。
+
+固定顶层字段为：
+
+```json
+{
+  "id": "low_case_00",
+  "source": "shape",
+  "attributes": {},
+  "const_inputs": {},
+  "inputs": {},
+  "outputs": {},
+  "meta": {}
+}
+```
+
+执行参数分为：
+
+- `attributes`：`.Attr("...")` 注册的 operator attributes。
+- `const_inputs`：`.ValueDepend()` 标记的 const input values。
+
+Tensor、TensorList、`shape = null`、`data_range`、`meta` 和 TTK CSV 映射规则均以 `S5_case_json_schema.md` 为准。
+
+## 2. Source And Files
+
+`source` 表示当前 case 在 Step 5 流程中的来源或变体类型。
+
+| source | 使用位置 | 含义 |
+|--------|----------|------|
+| `path` | `S5_mapped_cases_path.json` | 由 `S2P2_cases.json` 映射得到的 path base case。 |
+| `network` | `S5_mapped_cases_network.json` | 由 `S2P1_low_configs.json` 映射得到的 network base case。 |
+| `shape` | `S5_mapped_cases_low_shape.json`、`S5_cases_low.json`、`S5_cases_high.json` | shape low case。 |
+| `empty` | `S5_cases_low.json`、`S5_cases_high.json` | empty low case。 |
+| `range` | `S5_cases_high.json` | data_range high case。 |
+
+文件级 source 约束：
+
+| 文件 | 允许 source |
+|------|-------------|
+| `S5_mapped_cases_path.json` | `path` |
+| `S5_mapped_cases_network.json` | `network` |
+| `S5_mapped_cases_low_shape.json` | `shape` |
+| `S5_cases_low.json` | `shape`、`empty` |
+| `S5_cases_high.json` | `shape`、`empty`、`range` |
+
+## 3. Base Case
+
+`build_low_base_case(record, source, index)` 输出 base case。path 和 network 的 base case 使用同一固定 schema，区别只在字段取值来源和 mapper 指导书指定的映射规则。
+
+base case 要求：
+
+- `source` 必须为 `path` 或 `network`。
+- `attributes` 只包含 `S5_variable_semantics.md` 声明的 operator attributes。
+- `const_inputs` 只包含 `S5_variable_semantics.md` 声明的 `.ValueDepend()` const input values。
+- `inputs` 和 `outputs` 必须按 `S5_case_json_schema.md` 构造完整 descriptor。
+- `outputs` 必须由 mapper 完整生成，不得留给后续脚本根据 input 或 operator model 推导。
+- optional input/output 不出现时不得删除 descriptor，必须保留原位置并写 `shape = null`。
+- 所有 input descriptor 的 `data_range` 必须为 `normal`。
+- `meta` 只写入 mapper 和审计信息，不得写入执行字段。
+
+## 4. Shape Low Case
+
+`make_path_shape_case(case)` 和 `make_network_shape_case(case)` 输出 shape low case。
+
+shape low case 要求：
+
+- `source` 必须为 `shape`。
+- 顶层 schema 与 base case 保持一致。
+- `inputs` 必须包含最终用于 low 档执行的完整 input shape/dtype/format/data_range 信息。
+- `outputs` 必须按最终 `inputs`、`attributes`、`const_inputs` 和 `meta` 重新派生并完整写入。
+- `meta` 必须保留可审计的 base case 关联和 shape variant 信息。
+- 所有 input Tensor 的 `data_range` 必须为 `normal`。
+- 所有 input TensorList 外层和 child Tensor 的 `data_range` 必须为 `normal`。
+
+## 5. Empty Low Case
+
+empty low case 由 Step 5.3 固定脚本基于 `S5_mapped_cases_low_shape.json` 中的 shape low case 机械追加，输出到最终 low 用例文件 `S5_cases_low.json`。
+
+empty low case 要求：
+
+- `source` 必须为 `empty`。
+- 顶层 schema 与 shape low case 保持一致。
+- empty tensor 使用含 0 维度的 `shape` 表达。
+- optional placeholder 仍使用 `shape = null` 表达。
+- TensorList 整体 empty 使用 `tensor_count = 0` 和 `tensors = []` 表达。
+- `meta` 必须保留 empty variant 的审计信息。
+- 所有 input descriptor 的 `data_range` 必须为 `normal`。
+
+## 6. Range High Case
+
+range high case 由 Step 5.4 固定脚本基于 `S5_cases_low.json` 和 `S5_data_range_policy.json` 机械生成，输出到最终 high 用例文件 `S5_cases_high.json`。
+
+range high case 要求：
+
+- `source` 必须为 `range`。
+- 顶层 schema 与 low case 保持一致。
+- `attributes`、`const_inputs`、`inputs`、`outputs` 和 `meta` 的结构不得改变。
+- 至少一个参与 data_range expansion 的 input 使用非 `normal` data_range。
+- output 任何层级不得写入 `data_range`。
+- `meta` 必须保留 range variant 的审计信息。
+
+## 7. Data Range
+
+Step 5.2 只生成 low 档 mapped cases，所有 input 的 `data_range` 必须为 `normal`。
+
+TensorList input 需要同时满足：
+
+- 外层 `data_range = "normal"`。
+- 每个 child Tensor 的 `data_range = "normal"`。
+
+非 `normal` data_range 扩展由 Step 5.4 处理，不属于 Step 5.2 schema 生成范围。
+
+## 8. Final Validation Requirements
+
+最终 low/high validator 必须以 `S5_case_json_schema.md` 为唯一结构契约，检查 `S5_cases_low.json` 和 `S5_cases_high.json` 的结构、字段完整性和基础类型。文件级 source 约束由本文第 2 章定义，并由 Step 5.3/5.4 的固定生成脚本保证。
+
+禁止 validator 或后续脚本根据以下信息补全输出：
+
+- 算子名。
+- 字段名。
+- shape 相等关系。
+- 样例分布。
+- operator model。
+
+outputs 必须由 mapper 的 `derive_outputs(...)` 或等价动态区逻辑完整生成。后续脚本只能校验、复制、机械变换 empty/data_range variant，不得推导缺失 output descriptor。

package/assets/ops-direct-invoke/skills/ascendc-whitebox-design/references/case-mapper/s5_case_mapper_template.py

@@ -0,0 +1,411 @@
+#!/usr/bin/env python3
+# ----------------------------------------------------------------------------------------------------------
+# Copyright (c) 2026 Huawei Technologies Co., Ltd.
+# This program is free software, you can redistribute it and/or modify it under the terms and conditions of
+# CANN Open Software License Agreement Version 2.0 (the "License").
+# Please refer to the License for details. You may not use this file except in compliance with the License.
+# THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR IMPLIED,
+# INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.
+# See LICENSE in the root of the software repository for the full text of the License.
+# ----------------------------------------------------------------------------------------------------------
+"""Generate Step 5.2 shape-only low mapped cases.
+
+Copy this file to an operator whitebox directory as S5_case_mapper.py.
+Only implement the dynamic region at the end of this file.
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+import logging
+from pathlib import Path
+from typing import Any
+
+_logger = logging.getLogger(__name__)
+
+
+ROOT = Path(__file__).resolve().parent
+
+
+# =========================
+# Static region: do not rewrite
+# =========================
+
+
+def load_json(path: str) -> Any:
+    with (ROOT / path).open("r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+def dump_json(path: str, data: Any) -> None:
+    with (ROOT / path).open("w", encoding="utf-8") as f:
+        json.dump(data, f, indent=2, ensure_ascii=False)
+        f.write("\n")
+
+
+def input_tensor(
+    dtype: str,
+    shape: list[int] | None,
+    param_type: str = "REQUIRED",
+    data_range: str = "normal",
+    fmt: str = "ND",
+    **extra: Any,
+) -> dict[str, Any]:
+    tensor = {
+        "kind": "tensor",
+        "dtype": dtype,
+        "format": fmt,
+        "shape": None if shape is None else list(shape),
+        "param_type": param_type,
+        "data_range": data_range,
+    }
+    tensor.update(extra)
+    return tensor
+
+
+def dynamic_input_tensor(
+    dtype: str,
+    tensors: list[dict[str, Any]],
+    data_range: str = "normal",
+    fmt: str = "ND",
+    **extra: Any,
+) -> dict[str, Any]:
+    tensor = {
+        "kind": "tensor_list",
+        "dtype": dtype,
+        "format": fmt,
+        "param_type": "DYNAMIC",
+        "tensor_count": len(tensors),
+        "data_range": data_range,
+        "tensors": tensors,
+    }
+    tensor.update(extra)
+    return tensor
+
+
+def output_tensor(
+    dtype: str,
+    shape: list[int] | None,
+    param_type: str = "REQUIRED",
+    fmt: str = "ND",
+    **extra: Any,
+) -> dict[str, Any]:
+    tensor = {
+        "kind": "tensor",
+        "dtype": dtype,
+        "format": fmt,
+        "shape": None if shape is None else list(shape),
+        "param_type": param_type,
+    }
+    tensor.update(extra)
+    return tensor
+
+
+def output_tensor_list(
+    dtype: str,
+    tensors: list[dict[str, Any]],
+    fmt: str = "ND",
+    **extra: Any,
+) -> dict[str, Any]:
+    tensor = {
+        "kind": "tensor_list",
+        "dtype": dtype,
+        "format": fmt,
+        "param_type": "DYNAMIC",
+        "tensor_count": len(tensors),
+        "tensors": tensors,
+    }
+    tensor.update(extra)
+    return tensor
+
+
+def clone_case(case: dict[str, Any]) -> dict[str, Any]:
+    return copy.deepcopy(case)
+
+
+def path_case_id(index: int, case: dict[str, Any]) -> str:
+    return str(case.get("id") or f"case{index:05d}")
+
+
+def network_case_id(index: int, config: dict[str, Any]) -> str:
+    return str(config.get("id") or f"network{index:05d}")
+
+
+def network_record(config: dict[str, Any], index: int) -> dict[str, Any]:
+    record = dict(config)
+    record.setdefault("id", network_case_id(index, config))
+    return record
+
+
+def mapped_inputs(case: dict[str, Any]) -> dict[str, dict[str, Any]]:
+    inputs = case.get("inputs")
+    if not isinstance(inputs, dict):
+        raise ValueError(f"{case.get('id', '<unknown>')}: inputs must be an object")
+    return inputs
+
+
+def _reset_tensor_range(tensor: dict[str, Any]) -> None:
+    tensor["data_range"] = "normal"
+    if tensor.get("kind") == "tensor_list":
+        for child in tensor.get("tensors", []):
+            if isinstance(child, dict) and "data_range" in child:
+                child["data_range"] = "normal"
+
+
+def normalize_input_ranges(case: dict[str, Any]) -> dict[str, Any]:
+    normalized = clone_case(case)
+    for tensor in mapped_inputs(normalized).values():
+        _reset_tensor_range(tensor)
+    return normalized
+
+
+def _require_exact_keys(obj: dict[str, Any], expected: set[str], label: str) -> None:
+    actual = set(obj.keys())
+    if actual != expected:
+        raise ValueError(f"{label}: expected keys {sorted(expected)}, got {sorted(actual)}")
+
+
+def _validate_tensor_shape(shape: Any, label: str) -> None:
+    if shape is None:
+        return
+    if not isinstance(shape, list) or not all(isinstance(dim, int) for dim in shape):
+        raise ValueError(f"{label}: shape must be a list[int] or null")
+
+
+def _validate_single_tensor(tensor: dict[str, Any], label: str, *, allow_data_range: bool) -> None:
+    expected = {"kind", "dtype", "format", "shape", "param_type"}
+    if allow_data_range:
+        expected.add("data_range")
+    _require_exact_keys(tensor, expected, label)
+    _validate_tensor_shape(tensor.get("shape"), label)
+    if not isinstance(tensor.get("param_type"), str) or not tensor["param_type"]:
+        raise ValueError(f"{label}: param_type must be a non-empty string")
+    if allow_data_range:
+        if not isinstance(tensor.get("data_range"), str) or not tensor["data_range"]:
+            raise ValueError(f"{label}: data_range must be a non-empty string")
+    elif "data_range" in tensor:
+        raise ValueError(f"{label}: data_range is not allowed")
+
+
+def _validate_tensor_list_children(tensor: dict[str, Any], label: str, *, allow_data_range: bool) -> None:
+    child_expected = {"kind", "dtype", "format", "shape"}
+    if allow_data_range:
+        child_expected.add("data_range")
+    for child_index, child in enumerate(tensor["tensors"]):
+        if not isinstance(child, dict):
+            raise ValueError(f"{label}: child {child_index} must be an object")
+        _require_exact_keys(child, child_expected, f"{label}: child {child_index}")
+        _validate_tensor_shape(child.get("shape"), f"{label}: child {child_index}")
+        if child.get("kind") != "tensor":
+            raise ValueError(f"{label}: child {child_index} kind must be tensor")
+        if not isinstance(child.get("dtype"), str) or not child["dtype"]:
+            raise ValueError(f"{label}: child {child_index} dtype must be a non-empty string")
+        if not isinstance(child.get("format"), str) or not child["format"]:
+            raise ValueError(f"{label}: child {child_index} format must be a non-empty string")
+        if allow_data_range:
+            if not isinstance(child.get("data_range"), str) or not child["data_range"]:
+                raise ValueError(f"{label}: child {child_index} data_range must be a non-empty string")
+        elif "data_range" in child:
+            raise ValueError(f"{label}: child {child_index} data_range is not allowed")
+
+
+def _validate_tensor_list_descriptor(tensor: dict[str, Any], label: str, *, allow_data_range: bool) -> None:
+    expected = {"kind", "dtype", "format", "param_type", "tensor_count", "tensors"}
+    if allow_data_range:
+        expected.add("data_range")
+    _require_exact_keys(tensor, expected, label)
+    if tensor.get("param_type") != "DYNAMIC":
+        raise ValueError(f"{label}: param_type must be DYNAMIC")
+    if not isinstance(tensor.get("tensor_count"), int) or tensor["tensor_count"] < 0:
+        raise ValueError(f"{label}: tensor_count must be a non-negative int")
+    if not isinstance(tensor.get("tensors"), list):
+        raise ValueError(f"{label}: tensors must be a list")
+    if tensor["tensor_count"] != len(tensor["tensors"]):
+        raise ValueError(f"{label}: tensor_count must equal len(tensors)")
+    if allow_data_range:
+        if not isinstance(tensor.get("data_range"), str) or not tensor["data_range"]:
+            raise ValueError(f"{label}: data_range must be a non-empty string")
+    elif "data_range" in tensor:
+        raise ValueError(f"{label}: data_range is not allowed")
+    _validate_tensor_list_children(tensor, label, allow_data_range=allow_data_range)
+
+
+def _validate_tensor_descriptor(
+    tensor: dict[str, Any], label: str, *, allow_data_range: bool, kind: str
+) -> None:
+    if tensor.get("kind") != kind:
+        raise ValueError(f"{label}: kind must be {kind}")
+    if not isinstance(tensor.get("dtype"), str) or not tensor["dtype"]:
+        raise ValueError(f"{label}: dtype must be a non-empty string")
+    if not isinstance(tensor.get("format"), str) or not tensor["format"]:
+        raise ValueError(f"{label}: format must be a non-empty string")
+    if kind == "tensor":
+        _validate_single_tensor(tensor, label, allow_data_range=allow_data_range)
+    else:
+        _validate_tensor_list_descriptor(tensor, label, allow_data_range=allow_data_range)
+
+
+def _validate_mapped_case_fields(case: dict[str, Any], label: str) -> None:
+    if not isinstance(case, dict):
+        raise ValueError(f"{label}: case must be an object")
+    expected = {"id", "source", "attributes", "const_inputs", "inputs", "outputs", "meta"}
+    _require_exact_keys(case, expected, label)
+    if not isinstance(case["id"], str):
+        raise ValueError(f"{label}: id must be a string")
+    if not isinstance(case["source"], str):
+        raise ValueError(f"{label}: source must be a string")
+    if not isinstance(case["attributes"], dict) or not isinstance(case["const_inputs"], dict):
+        raise ValueError(f"{label}: attributes and const_inputs must be objects")
+    if not isinstance(case["inputs"], dict) or not isinstance(case["outputs"], dict):
+        raise ValueError(f"{label}: inputs and outputs must be objects")
+    if not isinstance(case["meta"], dict):
+        raise ValueError(f"{label}: meta must be an object")
+    if "supported_data_ranges" in case["meta"]:
+        raise ValueError(f"{label}: meta.supported_data_ranges is not allowed")
+
+
+def _validate_mapped_input(name: str, tensor: dict[str, Any], label: str) -> None:
+    if not isinstance(tensor, dict):
+        raise ValueError(f"{label}: input {name} must be an object")
+    kind = tensor.get("kind")
+    if kind == "tensor_list" or tensor.get("param_type") == "DYNAMIC":
+        _validate_tensor_descriptor(tensor, f"{label}: input {name}", allow_data_range=True, kind="tensor_list")
+    else:
+        _validate_tensor_descriptor(tensor, f"{label}: input {name}", allow_data_range=True, kind="tensor")
+
+
+def _validate_mapped_outputs(outputs: dict[str, Any], label: str) -> None:
+    for name, tensor in outputs.items():
+        if not isinstance(tensor, dict):
+            raise ValueError(f"{label}: output {name} must be an object")
+        kind = tensor.get("kind")
+        if kind == "tensor_list" or tensor.get("param_type") == "DYNAMIC":
+            _validate_tensor_descriptor(tensor, f"{label}: output {name}", allow_data_range=False, kind="tensor_list")
+        else:
+            _validate_tensor_descriptor(tensor, f"{label}: output {name}", allow_data_range=False, kind="tensor")
+
+
+def validate_mapped_case(case: Any, label: str) -> dict[str, Any]:
+    _validate_mapped_case_fields(case, label)
+    for name, tensor in case["inputs"].items():
+        _validate_mapped_input(name, tensor, label)
+    _validate_mapped_outputs(case["outputs"], label)
+    return normalize_input_ranges(case)
+
+
+def map_path_case(case: dict[str, Any], index: int) -> dict[str, Any]:
+    mapped = build_low_base_case(case, "path", index)
+    mapped.setdefault("id", path_case_id(index, case))
+    mapped.setdefault("source", "path")
+    mapped["id"] = str(mapped["id"])
+    mapped["source"] = "path"
+    return validate_mapped_case(mapped, mapped["id"])
+
+
+def map_network_case(record: dict[str, Any], index: int) -> dict[str, Any]:
+    mapped = build_low_base_case(record, "network", index)
+    mapped.setdefault("id", network_case_id(index, record))
+    mapped.setdefault("source", "network")
+    mapped["id"] = str(mapped["id"])
+    mapped["source"] = "network"
+    return validate_mapped_case(mapped, mapped["id"])
+
+
+def make_shape_variants(case: dict[str, Any]) -> list[dict[str, Any]]:
+    source = case.get("source")
+    if source == "path":
+        return [make_path_shape_case(case)]
+    if source == "network":
+        return [make_network_shape_case(case)]
+    raise ValueError(f"{case.get('id', '<unknown>')}: unsupported source {source!r}")
+
+
+def assert_unique_ids(cases: list[dict[str, Any]], label: str) -> None:
+    seen: set[str] = set()
+    for case in cases:
+        case_id = case["id"]
+        if case_id in seen:
+            raise ValueError(f"duplicate id in {label}: {case_id}")
+        seen.add(case_id)
+
+
+def build_low_shape_cases(
+    path_cases: list[dict[str, Any]], network_cases: list[dict[str, Any]],
+) -> list[dict[str, Any]]:
+    base_cases = path_cases + network_cases
+    shape_cases: list[dict[str, Any]] = []
+
+    for case in base_cases:
+        shape_variants = make_shape_variants(case)
+        if not shape_variants:
+            raise ValueError(f"{case['id']}: make_shape_variants must return at least one shape low case")
+        for variant in shape_variants:
+            if not isinstance(variant, dict):
+                raise ValueError(f"{case['id']}: shape variant must be an object")
+            variant.setdefault("source", "shape")
+            variant.setdefault("meta", {})
+            if not isinstance(variant["meta"], dict):
+                raise ValueError(f"{case['id']}: shape variant meta must be an object")
+            variant["source"] = "shape"
+            variant["id"] = f"low_case_{len(shape_cases):02d}"
+            variant["meta"].setdefault("base_id", case["id"])
+            variant["meta"].setdefault("variant_kind", "shape")
+            shape_cases.append(validate_mapped_case(variant, variant["id"]))
+
+    assert_unique_ids(shape_cases, "S5_mapped_cases_low_shape.json")
+    return shape_cases
+
+
+def main() -> None:
+    logging.basicConfig(level=logging.INFO, format="%(message)s")
+    path_cases = load_json("S2P2_cases.json")
+    network_configs = load_json("S2P1_low_configs.json")
+    mapped_path = [map_path_case(case, index) for index, case in enumerate(path_cases)]
+    mapped_network = [
+        map_network_case(network_record(config, index), index)
+        for index, config in enumerate(network_configs)
+    ]
+    low_shape_cases = build_low_shape_cases(mapped_path, mapped_network)
+
+    dump_json("S5_mapped_cases_path.json", mapped_path)
+    dump_json("S5_mapped_cases_network.json", mapped_network)
+    dump_json("S5_mapped_cases_low_shape.json", low_shape_cases)
+    _logger.info(
+        f"wrote {len(mapped_path)} path cases, {len(mapped_network)} mapped network cases,"
+        f" {len(low_shape_cases)} low shape cases"
+    )
+
+
+# =========================
+# Dynamic region: operator-specific
+# =========================
+
+
+def build_low_base_case(record: dict[str, Any], source: str, index: int) -> dict[str, Any]:
+    """TODO(operator-specific): construct one complete base mapped case."""
+    raise NotImplementedError
+
+
+def make_path_shape_case(case: dict[str, Any]) -> dict[str, Any]:
+    """TODO(operator-specific): map one path base case to one shape low case."""
+    raise NotImplementedError
+
+
+def make_network_shape_case(case: dict[str, Any]) -> dict[str, Any]:
+    """TODO(operator-specific): map one network base case to one shape low case."""
+    raise NotImplementedError
+
+
+def derive_outputs(
+    inputs: dict[str, Any],
+    attributes: dict[str, Any],
+    const_inputs: dict[str, Any],
+    meta: dict[str, Any],
+) -> dict[str, dict[str, Any]]:
+    """TODO(operator-specific): derive complete V1 output descriptors."""
+    raise NotImplementedError
+
+
+if __name__ == "__main__":
+    main()

package/assets/ops-direct-invoke/skills/ascendc-whitebox-design/references/design-verifier/00-execution-order.md

@@ -0,0 +1,114 @@
+# Task D Contract Gate
+
+> **路径约定**：`{skill_base}` = 技能根目录绝对路径，`{output_dir}` = `{op_path}/tests/whitebox`。
+
+Step 3 只检查最终用例 JSON 的覆盖契约：`S2P2_cases.json` 是否完整、合法地覆盖 Task D 声明的 path / tilingkey / param_def entry。
+
+Step 3 不检查：
+
+- `S2P2_gen_cases.py` 的实现细节、随机种子、cap 公式、函数名、seed 生成方式、采样压缩算法。
+- `S2P2_traceability.md` 的小节格式、源码行号或写作质量。
+- Task A/B/C 的源码事实。
+- case 数量是否足够多、case 分布是否均匀、采样值是否最优。
+- 第二层 LLM soft review。
+
+## 输入文件
+
+Step 3 只读取以下文件：
+
+- `S2P1_path_list.json`
+- `S2P2_param_def.json`
+- `S2P2_cases.json`
+
+## 执行命令
+
+```bash
+python3 {skill_base}/scripts/s3_task_d_gate.py \
+  --output-dir {output_dir}
+```
+
+脚本输出：
+
+- `S3_verification_report.json`
+- `S3_verification_report.md`
+
+## 检查项
+
+Step 3 只有一个检查项：`D1 cases_path_key_coverage`。
+
+遍历 `S2P2_cases.json` 中每条 case，检查：
+
+1. case 必须是 object。
+2. case 必须包含 `path`，且为 string。
+3. case 必须包含 `key`，且为 int。
+4. case 必须包含 `_group`，且为 string。
+5. case 必须包含 dtype 参数字段；字段名来自 `S2P2_param_def.json.dtype_tensors[0].param`。
+6. `case.path` 必须存在于 `S2P1_path_list.json.paths[*].id`。
+7. `case.key` 必须存在于 `S2P2_param_def.json.tiling_keys`。
+8. `(case._group, case.dtype, case.path, case.key)` 必须能回连到 `S2P2_param_def.json.groups[*].per_dtype[*]` 中某个 entry。
+
+## 覆盖率要求
+
+计算以下集合：
+
+```text
+reachable_paths = S2P1_path_list.paths[*].id where reachability == "reachable"
+param_def_paths = S2P2_param_def.groups[*].per_dtype[*].path
+expected_tilingkeys = S2P2_param_def.tiling_keys
+param_def_entries = (group_id, dtype, path, key) from S2P2_param_def
+case_paths = S2P2_cases[*].path
+case_tilingkeys = S2P2_cases[*].key
+case_entries = (case._group, case.dtype, case.path, case.key)
+```
+
+必须满足：
+
+1. `reachable_paths ⊆ case_paths`，reachable path 覆盖率为 100%。
+2. `param_def_paths ⊆ case_paths`，param_def path 覆盖率为 100%。
+3. `expected_tilingkeys ⊆ case_tilingkeys`，tilingkey 覆盖率为 100%。
+4. `param_def_entries ⊆ case_entries`，param_def entry 覆盖率为 100%。
+5. `case_paths ⊆ S2P1_path_list.paths[*].id`，不允许未知 path。
+6. `case_tilingkeys ⊆ expected_tilingkeys`，不允许未知 tilingkey。
+
+任一项不满足 → **fail**。
+
+## 报告字段
+
+`S3_verification_report.json` 必须包含：
+
+- `status`: `pass` / `fail`
+- `scope`: 固定为 `cases_path_key_coverage`
+- `check`: 固定为 `cases_path_key_coverage`
+- `checks_total`: 固定为 1
+- `checks_pass` / `checks_fail` / `checks_warn`
+- `metrics`
+- `issues`
+- `inputs`
+- `limitations`
+
+`metrics` 至少包含：
+
+- `case_count`
+- `reachable_path_count`
+- `covered_reachable_path_count`
+- `reachable_path_coverage`
+- `param_def_path_count`
+- `covered_param_def_path_count`
+- `param_def_path_coverage`
+- `expected_tilingkey_count`
+- `covered_tilingkey_count`
+- `tilingkey_coverage`
+- `param_def_entry_count`
+- `covered_param_def_entry_count`
+- `param_def_entry_coverage`
+- `missing_reachable_paths`
+- `missing_param_def_paths`
+- `unknown_paths`
+- `missing_tilingkeys`
+- `unknown_tilingkeys`
+- `missing_param_def_entries`
+
+## 失败处理
+
+- `status == "fail"` → 回 Step 2 Task D 修正 `S2P2_param_def.json` 或重新生成 `S2P2_cases.json`。
+- `status == "pass"` → 进入 Step 4 用户确认。