mcgatom/codex-cannbot/ops-spec-gen

算子 spec.yaml 生成与校验

为 CANNBot 算子产出符合 schema 的 spec.yaml，并对其执行完整 9-stage L0 校验：

• stage 1 schema_static — JSON Schema 字段静态校验
• stage 2 category_paradigm_consistency — category↔paradigm 一致性 + 4 套白名单 + paradigm 内部约束
• stage 3 shape_closure — numpy_expr 求值 outputs[].shape_rule（含 data_dependent 分流；折叠/显式维 + np.broadcast_shapes）
• stage 4 dtype_closure — dtype DSL 推导 vs supported_combinations 显式表交叉验证
• stage 5 broadcast_legality — broadcast.kind/rules 模拟（numpy / none / explicit）
• stage 6 boundary_min_set — 按 paradigms 检查 boundary/extreme case 是否覆盖最低集
• stage 7 tolerance_coverage — numerical_tolerance.per_dtype 覆盖输出 dtype + 紧度启发式
• stage 8 formula_smoke_eval — 把 formula 在小 shape ([2,3]) 上跑通，沙箱 numpy 执行
• stage 9 oracle_reachable — 真 import framework + getattr 链找 api + 占位符校验

1. 何时使用

2. 输入与输出

3. 生成 spec.yaml

3.1 交互式向导（推荐）

python3 scripts/generate_spec.py --output-dir <ops_dir>/<op_name>

向导会问：op 名称、category（25 类单选）、paradigms（在 category 必含基础上自由追加）、每个 input/output 名+dtype、promotion / broadcast / accumulation_order。

3.2 非交互式（CI / 脚本）

python3 scripts/generate_spec.py \
    --op-name softmax \
    --category reduction_composite \
    --paradigms Reduction,NumericalStable,FusedComposite \
    --inputs "x:float16,float32,bfloat16" \
    --outputs y \
    --description "Softmax along reduce_axis with max-shift stabilization" \
    --output-dir ops/softmax

注：--inputs 多个时用 ; 分隔（避免与 dtype_set 的 , 冲突），如 "a:float16,float32;b:float16,float32"。

3.3 自动注入

按 op.paradigms 自动注入：

• Reduction（且无 Recurrence）⇒ 添加 dim attribute（int_in_range_relative_to_rank）
• Quantization ⇒ 添加 scale / zero_point attribute
• RandomSampling ⇒ 添加 seed attribute
• Stateful ⇒ 第一个 input 标 role: state
• CollectiveCommunication ⇒ op.platform_constraints.requires_hccl: true
• category=contraction / category=reduction_composite / paradigms 含 NumericalStable+Reduction ⇒ 添加 accumulator_dtype: float32
• FusedComposite ⇒ 添加 composition.primitives（2 条占位）+ dataflow.no_leak: true
• NumericalStable ⇒ numerical_stability.required: true + 一条 technique 占位

更多注入提示见 registries/category_paradigm_map.yaml 的 paradigm_inject_hints 段。

3.4 必须手填的 TODO

生成器只产骨架 + 按 paradigm 自动注入的 boundary/extreme case。算子 owner 必须手填：

• outputs[].shape_rule — numpy 子集表达式（如 c.shape = np.broadcast_shapes(a.shape, b.shape)）。

若是 VariableOutput 范式的算子（shape 由输入值决定），改声明 shape_rule_kind: data_dependent + shape_rule_description + shape_bounds.max_elements，不写表达式。

• outputs[].dtype_rule — numpy 子集表达式（如 c.dtype = np.promote_types(a.dtype, b.dtype)、

y.dtype = x.dtype、y.dtype = np.int32）

• math_semantics.formula — numpy 可 eval 的表达式
• math_semantics.reference_oracle.api — 真实的 torch/numpy/scipy API 全限定名
• dtype_policy.supported_combinations — 显式枚举 (input dtypes) → output dtypes
• numerical_tolerance.per_dtype — 覆盖 supported_combinations 中所有 output dtype

按需补充（生成器已自动注入按 paradigm 必含的最低 case，stage 6 通过；下面这些是把生成器的占位描述改成项目语境下的真值）：

• boundary_conditions — 校核 / 补全自动注入的退化 case 描述（详见 cheatsheet §B6）
• extreme_inputs — 校核 / 补全 NaN / Inf / 全零三类

4. 校验 spec.yaml

python3 scripts/validate_spec.py path/to/spec.yaml          # 文本输出，跑全 9 stage
python3 scripts/validate_spec.py path/to/spec.yaml --json   # 机器可读
python3 scripts/validate_spec.py path/to/spec.yaml --strict # 警告也 fail
python3 scripts/validate_spec.py path/to/spec.yaml --quiet  # 仅打 FAIL 的 stage
python3 scripts/validate_spec.py path/to/spec.yaml --stage 1 --stage 2  # 仅跑选中的 stage

4.1 stage 1 — schema_static

按 schemas/op-spec.json（Draft 2020-12）逐字段校验：必填、类型、enum、pattern、additionalProperties。

4.2 stage 2 — category_paradigm_consistency

校验 category↔paradigm 必含映射 + 4 套白名单 + paradigm 内部约束：

4.3 stage 3 — shape_closure（numpy_expr 求值）

按 outputs[].shape_rule_kind 分流：

• `numpy_expr`（默认）— 在受限 AST 沙箱中执行 outputs[].shape_rule（numpy 子集表达式），求出每个输出的 SymbolicShape。
• `data_dependent` — 输出 shape 由输入数据值决定（nonzero / unique / masked_select 等）；不求解，但强制校验 data_dependent_shape: true + shape_bounds.max_elements + 建议配 shape_rule_description。

shape_rule 的 numpy_expr 示例（matmul）：

outputs:
  - name: c
    shape_rule_kind: numpy_expr
    shape_rule: |
      c.shape = (
          np.broadcast_shapes(a.shape[:-2], b.shape[:-2])
          + ((a.shape[-1] if transpose_a else a.shape[-2]),)
          + ((b.shape[-2] if transpose_b else b.shape[-1]),)
      )

data_dependent 示例（nonzero）：

outputs:
  - name: indices
    shape_rule_kind: data_dependent
    data_dependent_shape: true
    shape_rule_description: |
      indices.shape = (K, rank(x))，K = count(x != 0)，仅运行时已知
    shape_bounds:
      max_elements: "prod(x.shape) * rank(x)"
      output_rank: 2
      static_dims: [{axis: 1, value: "rank(x)"}]
      dynamic_dims: [{axis: 0, name: K, depends_on_value_of: x}]

numpy_expr 支持的子集（按需可扩展，见 scripts/evaluators/shape_eval.py）：

• x.shape / x.shape[-1] / x.shape[:-2]（切片 + 负索引）
• tuple 拼接 +（(a.shape[-1],) + (b.shape[-1],)）
• np.broadcast_shapes(*shapes)（numpy 标准 API 签名）
• IfExp：a if cond else b（cond 从 attribute 默认值解析为 bool）

沙箱规则同 stage 8：禁 import / def / class / for / while / lambda / dunder attribute；5 秒超时。

4.4 stage 4 — dtype_closure

对 dtype_policy.supported_combinations 的每一行，执行 outputs[].dtype_rule（numpy 子集表达式）推导输出 dtype，与显式表交叉比对。常见形式：

# 同 dtype 直传
dtype_rule: "y.dtype = x.dtype"
# 类型提升
dtype_rule: "c.dtype = np.promote_types(a.dtype, b.dtype)"
# 固定 dtype（如 ArgReduce 输出索引）
dtype_rule: "y.dtype = np.int64"
# 条件分支（如 complex_of）
dtype_rule: |
  out.dtype = np.complex64 if real.dtype == np.float32 else np.complex128

numpy 子集支持：

• x.dtype （input 的 dtype 字符串）
• np.promote_types(a, b) / np.result_type(*xs) — 复用 promote 表
• np.int8 / int16 / int32 / int64 / uint8 / uint16 / uint32 / uint64 / float16 / float32 / float64 / bfloat16 / complex64 / complex128 / bool_ dtype 常量
• 比较与 IfExp：a.dtype == np.float32、x if cond else y

Promotion 表覆盖 fp16 / fp32 / fp64 / bf16 / int8 / int16 / int32 / int64 / uint* / bool / complex64 / complex128 + 窄浮点 fp4_e2m1 / fp8_e4m3fn / fp8_e5m2 / hifloat8（见 scripts/evaluators/promote.py）。

4.5 stage 5 — broadcast_legality

按 broadcast.kind 模拟输入 shape 之间的对齐。

v1 已实现：numpy（含折叠维）/ none / explicit（broadcast.rules 必须恰好一条 scope: trailing + 一条 scope: leading，policy 各支持 numpy / no_broadcast，覆盖 matmul 形式）。explicit 的高阶组合（多于 2 个 input、scope: axis）留待扩展。

4.6 stage 6 — boundary_min_set

按 op.paradigms 检查 boundary_conditions[] / extreme_inputs[] 是否覆盖该范式必含的最低 case 集。数据源：registries/boundary_min_cases.yaml。

匹配方式：每条 requirement 用 match_any 关键词列表与 case 描述做子串包含；任一命中即算覆盖。结构性约束（如 shape_set 数量）走 special_check 直接检查。

覆盖的 paradigms：Reduction / NumericalStable / SlidingWindow / Padding / IndexGather / ScatterUpdate / AtomicUpdate / MaskPredicate / SortSelect / ArgReduce / Histogram / Spectral / DynamicShape / RandomSampling / Quantization / Stateful。其他 paradigms 当前无强制最低 case。

4.7 stage 7 — tolerance_coverage

注：本 skill 用 stage 4 输出 dtype 集合（在 stage 4 实现前用 supported_combinations 显式枚举作为代理）；两者通常一致。

4.8 stage 8 — formula_smoke_eval

把 math_semantics.formula 在小 shape（默认 [2,3]）上用 numpy 跑一遍，确认能跑通且产出预期 dtype。