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

package/assets/ops-direct-invoke/skills/cannbot-dsl-test-generator/assets/test.py

@@ -0,0 +1,571 @@
+#!/usr/bin/env python3
+# -*- coding: UTF-8 -*-
+# ----------------------------------------------------------------------------------------------------------
+# 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, EITHER 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.
+# ----------------------------------------------------------------------------------------------------------
+
+"""Fixed CANNBotDSL runner for testcase.csv blackbox/whitebox/TDD rows."""
+
+import argparse
+from concurrent.futures import ProcessPoolExecutor, as_completed
+from typing import NamedTuple, Any
+import csv
+import importlib
+import importlib.util
+import json
+import multiprocessing
+import os
+import sys
+from pathlib import Path
+
+import torch
+
+from cannbotdsl_case_contract import case_calls, check_inputs, check_probe
+
+TEST_DIR = Path(__file__).resolve().parent
+OP_NAME = "__CANNBOTDSL_OP_NAME__"  # Bound from spec.op.name by prepare_golden.py.
+CASEBOOK = TEST_DIR / "testcase.csv"
+_WORKER_INVOCATION = None
+_WORKER_ERROR = None
+
+
+def _result_path(sheet, case_id):
+    suffix = f"_{case_id}" if case_id else ""
+    output_dir = TEST_DIR / "testcase_output" / sheet
+    output_dir.mkdir(exist_ok=True)
+    return output_dir / f"verify_result_{sheet}{suffix}.csv"
+
+
+def _golden():
+    path = TEST_DIR / f"{OP_NAME}_golden.py"
+    spec = importlib.util.spec_from_file_location("cannbotdsl_golden", path)
+    if spec is None or spec.loader is None:
+        raise RuntimeError(f"missing golden: {path}")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def _rows(sheet, case_id):
+    if not CASEBOOK.is_file():
+        raise RuntimeError(f"missing casebook: {CASEBOOK}")
+    with CASEBOOK.open(encoding="utf-8-sig", newline="") as handle:
+        reader = csv.DictReader(handle)
+        if "sheet" not in (reader.fieldnames or []):
+            raise ValueError("testcase.csv has no sheet column")
+        all_rows = list(reader)
+    if any(row.get("sheet") not in ("blackbox", "whitebox", "tdd") for row in all_rows):
+        raise ValueError("testcase.csv contains an unsupported logical sheet")
+    found = []
+    for row in all_rows:
+        if row.get("sheet") != sheet or row.get("status") != "active":
+            continue
+        if case_id is None or row.get("case_id") == case_id:
+            found.append(row)
+    if not found:
+        raise ValueError(f"no cases selected: sheet={sheet!r} case_id={case_id!r}")
+    keys = [(row["sheet"], row["case_id"]) for row in all_rows]
+    if len(keys) != len(set(keys)) or any(not row.get("inputs_json") for row in found):
+        raise ValueError("duplicate case or missing inputs_json in testcase.csv")
+    return found
+
+
+def _to_device(value, device):
+    if isinstance(value, torch.Tensor):
+        return value.to(device)
+    if isinstance(value, tuple):
+        return tuple(_to_device(item, device) for item in value)
+    if isinstance(value, list):
+        return [_to_device(item, device) for item in value]
+    if isinstance(value, dict):
+        return {key: _to_device(item, device) for key, item in value.items()}
+    return value
+
+
+def _assert_device(value, device, path="output"):
+    if isinstance(value, torch.Tensor):
+        if value.device.type != torch.device(device).type:
+            raise AssertionError(
+                f"{path}: output on {value.device}, requested {device}"
+            )
+    elif isinstance(value, dict):
+        for key, item in value.items():
+            _assert_device(item, device, f"{path}.{key}")
+    elif isinstance(value, (tuple, list)):
+        for index, item in enumerate(value):
+            _assert_device(item, device, f"{path}[{index}]")
+
+
+def _synchronize(device):
+    device_type = torch.device(device).type
+    if device_type == "cpu":
+        return
+    backend = getattr(torch, device_type, None)
+    if backend is None or not hasattr(backend, "synchronize"):
+        raise RuntimeError(
+            f"cannot synchronize target device {device_type}; probe evidence is not reliable"
+        )
+    backend.synchronize()
+
+
+def _assert_nonnumeric(actual, inputs, assertions, device, probe):
+    if not isinstance(assertions, list) or not assertions:
+        raise ValueError("nonnumeric TDD case has no assertions")
+    records = []
+    for assertion in assertions:
+        records.append(_observe_assertion(actual, inputs, assertion, device, probe))
+    return records
+
+
+def _compare(actual, expected, tolerance, path="output", equal_nan=False):
+    if isinstance(expected, dict):
+        if not isinstance(actual, dict) or set(actual) != set(expected):
+            raise AssertionError(f"{path}: output structure mismatch")
+        measurements = []
+        for key in expected:
+            measurements.extend(
+                _compare(
+                    actual[key], expected[key], tolerance, f"{path}.{key}", equal_nan
+                )
+            )
+        return measurements
+    if isinstance(expected, (tuple, list)):
+        if not isinstance(actual, (tuple, list)) or len(actual) != len(expected):
+            raise AssertionError(f"{path}: output count mismatch")
+        measurements = []
+        for index, (a, e) in enumerate(zip(actual, expected)):
+            measurements.extend(
+                _compare(a, e, tolerance, f"{path}[{index}]", equal_nan)
+            )
+        return measurements
+    return _compare_tensor(actual, expected, tolerance, path, equal_nan)
+
+
+def _has_nan(value):
+    if isinstance(value, torch.Tensor):
+        return bool(torch.isnan(value).any())
+    if isinstance(value, dict):
+        return any(_has_nan(item) for item in value.values())
+    if isinstance(value, (tuple, list)):
+        return any(_has_nan(item) for item in value)
+    return False
+
+
+def _error_matches(exc, code):
+    if code in (getattr(exc, "code", None), getattr(exc, "error_code", None)):
+        return True
+    module_name = os.environ.get("CANNBOTDSL_ERROR_MATCHER")
+    if not module_name:
+        return False
+    matcher = getattr(importlib.import_module(module_name), "match_error")
+    return matcher(exc, code) is True
+
+
+class Invocation(NamedTuple):
+    run: Any
+    golden: Any
+    device: str
+
+
+def _invoke(invocation, inputs, output_map, expected_error_code=None):
+    run, golden, device = invocation
+    inputs = _to_device(inputs, device)
+    outputs = {}
+    if output_map:
+        if not isinstance(output_map, dict) or set(output_map) != set(
+            golden.OUTPUT_NAMES
+        ):
+            raise ValueError("output_json must contain exactly the spec outputs")
+        outputs = _to_device(golden.make_inputs(output_map, seed=0), device)
+        for tensor in outputs.values():
+            if isinstance(tensor, torch.Tensor):
+                tensor.zero_()
+    try:
+        result = run(**inputs, **outputs)
+    except Exception as target_error:
+        if expected_error_code is None:
+            raise
+        if not _error_matches(target_error, expected_error_code):
+            raise AssertionError(
+                f"target error does not match spec code {expected_error_code}: {target_error}"
+            ) from target_error
+        return None
+    if expected_error_code is not None:
+        raise AssertionError(
+            f"target accepted an input that should raise {expected_error_code}"
+        )
+    if not outputs:
+        return result
+    return (
+        outputs[golden.OUTPUT_NAMES[0]]
+        if len(outputs) == 1
+        else tuple(outputs[name] for name in golden.OUTPUT_NAMES)
+    )
+
+
+def _positive_int(value):
+    number = int(value)
+    if number < 1:
+        raise argparse.ArgumentTypeError("must be a positive integer")
+    return number
+
+
+def _load_invocation(golden, device):
+    module_name = os.environ.get("CANNBOTDSL_OP_MODULE")
+    if not module_name:
+        raise RuntimeError("CANNBOTDSL_OP_MODULE is unset")
+    entry_name = os.environ.get("CANNBOTDSL_OP_ENTRY", "run")
+    run = getattr(importlib.import_module(module_name), entry_name)
+    return Invocation(run, golden, device)
+
+
+def _init_worker(device):
+    # Keep module/probe state private and amortize imports across many rows.
+    global _WORKER_INVOCATION, _WORKER_ERROR
+    _WORKER_INVOCATION, _WORKER_ERROR = None, None
+    try:
+        # Avoid multiplying the CPU Golden's intra-op threads by the pool size.
+        torch.set_num_threads(1)
+        _WORKER_INVOCATION = _load_invocation(_golden(), device)
+    except Exception as exc:
+        _WORKER_ERROR = str(exc)
+
+
+def _case_result(row, device, invocation=None, load_error=None):
+    try:
+        if invocation is None:
+            raise RuntimeError(load_error)
+        status, detail = _run_case(row, invocation)
+    except Exception as exc:
+        status, detail = "failed", str(exc)
+    return {
+        "sheet": row["sheet"],
+        "case_id": row["case_id"],
+        "device": device,
+        "status": status,
+        "detail": detail,
+    }
+
+
+def _worker_case(row, device):
+    return _case_result(row, device, _WORKER_INVOCATION, _WORKER_ERROR)
+
+
+def _run_rows(rows, golden, device, workers):
+    workers = min(workers, len(rows))
+    if workers == 1:
+        invocation, load_error = None, None
+        try:
+            invocation = _load_invocation(golden, device)
+        except Exception as exc:
+            load_error = str(exc)
+        return [_case_result(row, device, invocation, load_error) for row in rows]
+
+    results = [None] * len(rows)
+    # Never fork an initialized accelerator runtime. Only recipes cross processes;
+    # tensors, Golden and target/probe modules stay in their worker.
+    with ProcessPoolExecutor(
+        max_workers=workers,
+        mp_context=multiprocessing.get_context("spawn"),
+        initializer=_init_worker,
+        initargs=(device,),
+    ) as executor:
+        pending = {}
+        for index, row in enumerate(rows):
+            try:
+                pending[executor.submit(_worker_case, row, device)] = index
+            except RuntimeError as exc:
+                results[index] = _case_result(row, device, load_error=str(exc))
+        for future in as_completed(pending):
+            index = pending[future]
+            try:
+                results[index] = future.result()
+            except Exception as exc:
+                results[index] = _case_result(
+                    rows[index], device, load_error=f"worker failed: {exc}"
+                )
+    return results
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--sheet", required=True, choices=("blackbox", "whitebox", "tdd")
+    )
+    parser.add_argument("--case-id")
+    parser.add_argument("--device", required=True)
+    parser.add_argument("--require-accelerator", action="store_true")
+    parser.add_argument(
+        "--workers",
+        type=_positive_int,
+        default=4,
+        help="concurrent case processes (default: 4); use 1 for serial execution",
+    )
+    args = parser.parse_args()
+    if args.require_accelerator and torch.device(args.device).type == "cpu":
+        print(
+            "precision verification requires a non-CPU target device", file=sys.stderr
+        )
+        return 2
+    try:
+        rows = _rows(args.sheet, args.case_id)
+        golden = _golden()
+    except (RuntimeError, ValueError) as exc:
+        print(str(exc), file=sys.stderr)
+        return 2
+    results = _run_rows(rows, golden, args.device, args.workers)
+    result_path = _result_path(args.sheet, args.case_id)
+    with result_path.open("w", encoding="utf-8-sig", newline="") as handle:
+        writer = csv.DictWriter(
+            handle, fieldnames=("sheet", "case_id", "device", "status", "detail")
+        )
+        writer.writeheader()
+        writer.writerows(results)
+    print(
+        f"wrote {result_path} total={len(results)} failed={sum(row['status'] != 'passed' for row in results)}"
+    )
+    return 1 if any(row["status"] != "passed" for row in results) else 0
+
+
+def _compare_tensor(actual, expected, tolerance, path, equal_nan):
+    if not isinstance(actual, torch.Tensor) or not isinstance(expected, torch.Tensor):
+        raise AssertionError(f"{path}: expected tensor output")
+    if actual.shape != expected.shape or actual.dtype != expected.dtype:
+        raise AssertionError(
+            f"{path}: shape/dtype mismatch: {actual.shape}/{actual.dtype} vs {expected.shape}/{expected.dtype}"
+        )
+    dtype = str(expected.dtype).removeprefix("torch.")
+    limits = tolerance.get(dtype)
+    if not isinstance(limits, dict):
+        raise AssertionError(f"{path}: no tolerance for {dtype}")
+    metric = limits.get("metric")
+    if metric not in ("max_relative", "bitwise_equal"):
+        raise AssertionError(
+            f"{path}: unsupported metric {metric}; do not substitute assert_close"
+        )
+    if metric == "bitwise_equal":
+        # Numeric equality would treat +0.0 and -0.0 as equal; compare storage bits.
+        passed = torch.equal(
+            actual.contiguous().reshape(-1).view(torch.uint8),
+            expected.contiguous().reshape(-1).view(torch.uint8),
+        )
+        detail = {"path": path, "dtype": dtype, "metric": metric, "equal": passed}
+        if not passed:
+            raise AssertionError(json.dumps(detail, ensure_ascii=False))
+        return [detail]
+    rtol, atol = limits.get("rtol"), limits.get("atol")
+    numeric_limits = isinstance(rtol, (int, float)) and isinstance(atol, (int, float))
+    if not numeric_limits or rtol < 0 or atol < 0:
+        raise AssertionError(f"{path}: invalid rtol/atol")
+    finite = torch.isfinite(actual) & torch.isfinite(expected)
+    if bool(finite.any()):
+        reference = expected[finite].double()
+        absolute_error = (actual[finite].double() - reference).abs()
+        allowance = atol + rtol * reference.abs()
+        normalized = torch.where(
+            allowance > 0,
+            absolute_error / allowance,
+            torch.where(
+                absolute_error == 0,
+                torch.zeros_like(absolute_error),
+                torch.full_like(absolute_error, float("inf")),
+            ),
+        )
+        max_abs = float(absolute_error.max())
+        max_normalized = float(normalized.max())
+    else:
+        max_abs = max_normalized = 0.0
+    detail = {
+        "path": path,
+        "dtype": dtype,
+        "metric": metric,
+        "rtol": rtol,
+        "atol": atol,
+        "max_abs": max_abs,
+        "max_normalized_error": max_normalized,
+    }
+    try:
+        torch.testing.assert_close(
+            actual, expected, rtol=rtol, atol=atol, equal_nan=equal_nan
+        )
+    except AssertionError as exc:
+        raise AssertionError(
+            f"{json.dumps(detail, ensure_ascii=False)}; {exc}"
+        ) from exc
+    return [detail]
+
+
+def _run_case(row, invocation):
+    _, golden, device = invocation
+    spec_map = json.loads(row["inputs_json"])
+    if not isinstance(spec_map, dict):
+        raise ValueError("inputs_json must be a mapping")
+    public_names = (
+        set(golden.INPUT_NAMES)
+        | set(golden.ATTR_DEFAULTS)
+        | set(golden.REQUIRED_ATTR_NAMES)
+    )
+    if set(spec_map) - public_names:
+        raise ValueError("inputs_json contains names outside spec")
+    expectation = row.get("expected")
+    output_map = json.loads(row.get("output_json") or "{}")
+    if expectation and expectation.startswith("raises_error:"):
+        code = expectation.removeprefix("raises_error:")
+        inputs = golden.make_inputs(spec_map, seed=int(row.get("seed") or 42))
+        _invoke(invocation, inputs, output_map, expected_error_code=code)
+        return "passed", json.dumps({"expected_error_code": code}, ensure_ascii=False)
+    if expectation not in ("match_golden", "match_golden_nan", "assertions"):
+        raise ValueError(f"unsupported expected outcome: {expectation}")
+    assertions = json.loads(row.get("assertions_json") or "[]")
+    repeat, bitwise, calls = case_calls(
+        spec_map, int(row.get("seed") or 42), assertions
+    )
+    baselines = {}
+    measurements = []
+    for repetition in range(repeat):
+        for index, call in enumerate(calls):
+            if set(call["inputs"]) - public_names:
+                raise ValueError("sequence inputs contain names outside spec")
+            inputs = golden.make_inputs(call["inputs"], seed=call["seed"])
+            checks = [
+                c
+                for a in call["assertions"]
+                if a["kind"] == "input_conditions"
+                for c in a["checks"]
+            ]
+            records = check_inputs(inputs, checks) if checks else []
+            numeric = expectation != "assertions"
+            expected = None
+            if numeric:
+                _, expected = golden.simulate(call["inputs"], seed=call["seed"])
+                if expectation == "match_golden_nan" and not _has_nan(expected):
+                    raise AssertionError("spec expects NaN but Golden returned no NaN")
+            probe_assertions = any(
+                a["kind"] in {"probe_events", "probe_predicates"}
+                for a in call["assertions"]
+            )
+            probe = None
+            if probe_assertions:
+                module = os.environ.get("CANNBOTDSL_PROBE_MODULE")
+                probe = importlib.import_module(module) if module else None
+                if (
+                    probe is None
+                    or not hasattr(probe, "reset")
+                    or not hasattr(probe, "snapshot")
+                ):
+                    raise RuntimeError("probe assertions require reset()/snapshot()")
+                probe.reset()
+            actual = _invoke(invocation, inputs, output_map)
+            _assert_device(actual, device)
+            if probe_assertions or bitwise:
+                _synchronize(device)
+            if numeric:
+                records.extend(
+                    _compare(
+                        _to_device(actual, "cpu"),
+                        expected,
+                        golden.TOLERANCE,
+                        equal_nan=expectation == "match_golden_nan",
+                    )
+                )
+            observable = [
+                a for a in call["assertions"] if a["kind"] != "input_conditions"
+            ]
+            if observable:
+                records.extend(
+                    _assert_nonnumeric(actual, inputs, observable, device, probe)
+                )
+            elif not numeric:
+                raise ValueError("assertions case lacks observable output or probe")
+            if bitwise:
+                snapshot = _clone_cpu(actual)
+                if repetition == 0:
+                    baselines[index] = snapshot
+                else:
+                    _bitwise_equal(snapshot, baselines[index])
+            measurements.append(
+                {"repetition": repetition, "call": index, "records": records}
+            )
+    return "passed", json.dumps(measurements, ensure_ascii=False)
+
+
+def _clone_cpu(value):
+    if isinstance(value, torch.Tensor):
+        return value.detach().cpu().clone()
+    if isinstance(value, dict):
+        return {key: _clone_cpu(item) for key, item in value.items()}
+    if isinstance(value, (list, tuple)):
+        return type(value)(_clone_cpu(item) for item in value)
+    raise ValueError("bitwise repeat requires tensor outputs")
+
+
+def _bitwise_equal(actual, expected):
+    if isinstance(expected, torch.Tensor):
+        if (
+            not isinstance(actual, torch.Tensor)
+            or actual.shape != expected.shape
+            or actual.dtype != expected.dtype
+            or not torch.equal(
+                actual.contiguous().reshape(-1).view(torch.uint8),
+                expected.contiguous().reshape(-1).view(torch.uint8),
+            )
+        ):
+            raise AssertionError("repeated call output changed bitwise")
+    elif isinstance(expected, dict):
+        if not isinstance(actual, dict) or set(actual) != set(expected):
+            raise AssertionError("repeated call output structure changed")
+        for key in expected:
+            _bitwise_equal(actual[key], expected[key])
+    else:
+        if type(actual) is not type(expected) or len(actual) != len(expected):
+            raise AssertionError("repeated call output structure changed")
+        for left, right in zip(actual, expected):
+            _bitwise_equal(left, right)
+
+
+def _observe_assertion(actual, inputs, assertion, device, probe):
+    kind = assertion.get("kind")
+    if kind == "probe_predicates":
+        if probe is None or not hasattr(probe, "snapshot"):
+            raise RuntimeError("probe predicates require snapshot()")
+        observed = check_probe(probe.snapshot(), assertion["checks"])
+    elif kind == "probe_events":
+        if probe is None or not hasattr(probe, "snapshot"):
+            raise RuntimeError(
+                "probe_events requires CANNBOTDSL_PROBE_MODULE.snapshot()"
+            )
+        observed = probe.snapshot()
+        if observed != assertion.get("events"):
+            raise AssertionError(f"probe events mismatch: {observed!r}")
+    elif kind == "output_shape" and isinstance(actual, torch.Tensor):
+        observed = list(actual.shape)
+        if observed != assertion.get("shape"):
+            raise AssertionError(f"output shape {observed} != {assertion.get('shape')}")
+    elif kind == "output_dtype" and isinstance(actual, torch.Tensor):
+        observed = str(actual.dtype).removeprefix("torch.")
+        if observed != assertion.get("dtype"):
+            raise AssertionError(f"output dtype {observed} != {assertion.get('dtype')}")
+    elif kind == "output_device" and isinstance(actual, torch.Tensor):
+        observed = actual.device.type
+        if observed != torch.device(device).type:
+            raise AssertionError(f"output device {observed} != {device}")
+    elif kind == "output_equals_input" and isinstance(actual, torch.Tensor):
+        source = inputs.get(assertion.get("input"))
+        if not isinstance(source, torch.Tensor) or not torch.equal(
+            actual, source.to(actual.device)
+        ):
+            raise AssertionError("output differs from specified input")
+        observed = True
+    else:
+        raise ValueError(f"unsupported or inapplicable assertion: {assertion!r}")
+    return {"kind": kind, "observed": observed}
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/assets/ops-direct-invoke/skills/cannbot-dsl-test-generator/references/cases.md

@@ -0,0 +1,29 @@
+# testcase.csv 用例契约
+
+唯一持久化测试设计文件是 `TEST_DIR/testcase.csv`。UTF-8 CSV 的列顺序固定：
+
+```text
+sheet,case_id,source,branch_ids,unit_id,inputs_json,output_json,seed,expected,assertions_json,obligation_ids,note,status,design_ref,condition,exclude_reason
+```
+
+`sheet` 和 `source` 同为 `blackbox`、`whitebox` 或 `tdd`。`status=active` 的行必须有 `inputs_json` 且无排除理由；`status=excluded` 的行必须有 `exclude_reason` 且无可执行输入。固定测试入口只运行 active 行。JSON 单元格使用标准 JSON；逗号分隔 ID 的字段不允许重复。
+
+CSV 使用 `csv.DictWriter` 等标准 CSV 序列化器写入，JSON 单元格先用 `json.dumps` 编码；不要手工拼接含逗号和引号的 CSV。分批保存时保留其他分组及已有 ID，重读文件检查列序、JSON 可解析性和 ID 唯一性。未完成覆盖不代表验收通过。
+
+`synthesize.dtype` 支持两种形式：`dtype: float16` 要求当前用例所有已提供的张量（含 TensorList 成员）使用该 dtype，不作用于标量属性或未提供的可选输入；`dtype: {query: float16, mask: float32}` 只约束列出的输入。混合 dtype 使用映射。缺省不追加 dtype 约束，仍遵守 spec 输入类型校验。字符串形式可直接绑定相应 spec 路径，无需通过 excluded 绕过。
+
+## 黑盒
+
+先运行 `build_blackbox_cases.py --inventory` 读取标准输出的必需 spec 路径及因子目标。每个 active 行用 `BB-...` ID，`design_ref` 以逗号分隔真实 spec 路径，`condition` 写 `L0`、`L1` 或 `L2`，`note` 写用例目的，`inputs_json` 写公开输入配方，`expected` 写 `match_golden`、`match_golden_nan` 或 `raises_error:<spec 错误码>`。L2 只能对应 spec 声明的异常；NaN 比较须回指相应语义。无法执行的必需 spec 路径写单独 excluded 行，`design_ref` 只写该路径并说明理由。校验器验证所有必需路径均被覆盖或排除，并可用 `--coverage` 在标准输出重算取值、成对组合和未命中目标。路径被引用不等于取值覆盖。
+
+## 白盒
+
+每行 ID 为 `WB-<分支 ID>`，`design_ref` 为所提供设计文件中的实际条目，`condition` 描述分支条件。active 行的 `inputs_json` 是公开输入配方，`note` 统一写 `return_value` 或 `dst_args`；后者还需在 `output_json` 提供全部输出配方。无法执行的 DESIGN 分支写 excluded 行及理由。白盒校验器直接核对 DESIGN 引用、输入和输出；不创建分支图副本。
+
+## 实现单元 TDD
+
+每行 ID 为 `TD-<原生 Unit ID 小写>-<用例名>`，`unit_id` 为原生 ID 小写，`obligation_ids` 以逗号分隔该 Unit 的真实验证义务，`branch_ids` 可关联 active 白盒分支。每条原生义务至少被一个 TDD 行覆盖。数值义务使用 `expected=match_golden`；结构义务在 `assertions_json` 中提供非空的 `probe_events` 或 `probe_predicates`。结构专用行使用 `expected=assertions`，联合数值与结构的行可使用 `match_golden`。CSV 中的 `inputs_json`、`output_json` 和 `assertions_json` 是唯一用例内容；不生成适配 Unit、桥接计划或 TDD JSON 副本。
+
+TDD 义务类型与判定必须对应：`semantic` 至少包含 output_shape、output_dtype、output_equals_input、probe_events 或 probe_predicates；`device` 包含 output_device。`performance` 与未知类型拒绝进入 TDD，性能目标须另有实际测量条件与判据。数值判定与输出/探针断言可由同一次调用共同承担；不以普通 Golden 比较覆盖非数值义务。错误码行为使用黑盒的 raises_error 用例。
+
+实际触发条件、确定性值配方、结构谓词及连续调用使用 [TDD 证据契约](evidence.md)。CSV 列保持不变，扩展均写入 assertions_json；新增条件必须由实际输入触发。

package/assets/ops-direct-invoke/skills/cannbot-dsl-test-generator/references/evidence.md

@@ -0,0 +1,67 @@
+# TDD 输入、触发条件、结构证据与调用生命周期
+
+TDD 需要有效工作量、结构关系或连续调用时阅读本文件。CSV 列不变；扩展只写入 `assertions_json`。脚本校验可执行契约，设计语义和采集来源须另行核对。
+
+## 调用方提供的检验义务
+
+每份 `U*.yaml` 含一个 unit 对象；unit_id 与文件名一致，verification_obligations 为非空列表，每项有全局唯一的 id 和 kind（numerical、structural、semantic、device）。可选 title、depends_on 用于展示边界和阅读顺序；依赖若填写，须引用现有单元且无环。仅这些字段与义务内容参与用例校验，不要求特定产物生成方式。
+
+义务的 behavior、must_distinguish、observable_result、coverage_axes 和设计引用用于确定可区分的输入与判定。可选 input_conditions 描述必须实际满足的触发条件，格式见下文。其他实现规划字段不参与测试生成；本 Skill 不据此判断实现方案是否可行或是否满足源码、编译产物、设备证据要求。
+
+## 确定性数据
+
+张量配方增加两种 fill，仍由 Golden 的 `make_inputs` 在 CPU 构造：
+
+- `values`：`values` 为数值列表或嵌套列表，按行展平，元素数与 shape 的乘积一致；用于小规模索引、前缀和、页映射及非均匀重复构造。
+- `arange`：`start` 默认 0、`step` 默认 1；未写 axis 时生成全部元素后 reshape，指定 axis 时沿该轴递增并在其他轴重复。例如 `{shape: [2, 129], dtype: int32, fill: arange, axis: -1}` 每行是 0..128。
+
+已有 normal、常量和特殊值配方保留。固定 seed 与配方共同决定输入；新 Golden 的 make_inputs 可采用 prepare_golden.py 中的 SUPPORT。已有 Golden 复用前核对它确实支持当前配方，不修改数学口径。
+
+## 实际触发条件
+
+Unit 义务可写 `input_conditions`，CSV 对应行必须用 `kind=input_conditions` 的 checks 承接。至少一个绑定用例完整包含该义务的所有条件；校验器物化当前 seed 的真实输入并检查，runner 在调用目标实现前再次检查。失败表示用例未触发目标行为，不是算子数值失败。
+
+```json
+[{"kind":"input_conditions","checks":[
+  {"input":"indices","metric":"unique_count","axis":-1,
+   "where":{"min":0,"max":{"input":"key","dimension":1}},
+   "relation":"ge","value":129}
+]}]
+```
+
+metric 支持 dimension（须有 axis）、numel、count、unique_count。count/unique_count 没有 axis 时检查全张量，有 axis 时逐行检查该轴，每行均须满足。where 的 min 为包含下界，max 为排除上界，eq 为等值；边界为有限数或 `{input, dimension}` 引用另一张量维度。relation 为 eq/ne/ge/gt/le/lt。无法由这些谓词表达的关系返回具体缺口，不编造“已覆盖”。自然语言 coverage_axes 仍须与实际输入和判定逐项核对。
+
+输入条件不能单独承担 structural、semantic 或 device 义务；必须同时有输出或实际探针证据。
+
+## 结构关系
+
+保留 `probe_events` 全等断言，确定性的事件流可继续使用。并行执行宜使用 `probe_predicates`，避免冻结无关任务的完整全序：
+
+```json
+[{"kind":"probe_predicates","checks":[
+  {"op":"count","where":{"event":"compute","domain":"required"},"relation":"ge","value":1},
+  {"op":"before","first":{"event":"ready"},"second":{"event":"consume"},"keys":["slot","generation"]},
+  {"op":"paired","first":{"event":"consume"},"second":{"event":"free"},"keys":["slot","generation"]}
+]}]
+```
+
+事件为字典；where/first/second 按字段等值选择。count 检查匹配数量；paired 检查非空的两侧按 keys 分组数量相同；before 另检查对应事件的列表位置严格先后。复用用 generation 等真实代次区分。事件列表只在采集端定义的顺序确实代表发生顺序时用于 before；跨执行域仅按 Host 收集顺序拼接不能证明时序。
+
+这些谓词不直接证明重叠或事件真实性。设计要求重叠时需真实设备时序或 trace，并明确采集来源与判据；采集代码、字段与运行产物须可追溯。固定 snapshot 和阶段名称不能作为完成证明。
+
+numerical 的 `match_golden` 可以同时携带输入条件、输出和探针断言，使同一次调用验证数值与结构；绑定结构义务必须有 probe_events 或 probe_predicates。semantic/device 仍需对应的输出/探针断言。未使用扩展的现有 CSV 行保持原行为。
+
+## 连续调用与重复
+
+用一个 execution 控制本行的调用序列。先执行 inputs_json，再执行 calls；每次均按当前输入运行独立 Golden/断言，整个序列在同一进程重复。repeat 为 1..100，附加 calls 最多 32 个，不允许嵌套 execution。
+
+```json
+[{"kind":"execution","repeat":3,"bitwise":true,"calls":[
+  {"inputs":{"x":{"shape":[3,4],"dtype":"float32","fill":"ones"},
+             "y":{"shape":[3,4],"dtype":"float32","fill":"zeros"}},"seed":7}
+]}]
+```
+
+calls 的 inputs 使用同一公开输入配方；seed 缺省沿用本行，assertions 缺省沿用本行非 execution 断言，显式提供时仍须满足绑定义务类型。必要时随附加调用调整输入条件和 shape 断言。bitwise=true 要求 repeat≥2，比较相同序列位置不同轮次的输出存储位，首轮输出立即克隆，避免返回缓冲后续被覆盖。是否要求 bitwise 来自 spec/设计；不把它推广到所有算子。
+
+调用不会重新导入目标模块，不保证公开入口复用同一编译句柄；句柄生命周期仍需对应的实际结构证据。dst_args 序列当前复用本行 output_json，因此选择与该输出布局兼容的输入；需要不同输出分配布局时记录契约缺口，不伪装成已测。