# Output Contract

## Reducer run

所有普通减速器生成结果必须写入：

```text
output/runs/<run_name>/
  input_snapshot/
  formula/
  kinematics/
  placement/
  cad/
  validation/
  exports/
```

关键文件：

```text
formula/formula_instance.json
formula/parameter_search_report.json
formula/topology_graph.json
kinematics/kinematic_solution.json
kinematics/motion_samples.json
placement/placement_plan.json
cad/reducer.step
cad/reducer.model.json
cad/reducer.session.json
cad/assembly_manifest.json
cad/build_meta.json
validation/assembly_snapshot.json
validation/validation_report.json
```

工业级 reducer 还应包含：

```text
formula/industrial_parameters.json
formula/assembly_topology.json
cad/component_steps/*.step
cad/industrial_parameters.json
cad/assembly_topology.json
```

## Joint module run

关节模组生成结果必须写入：

```text
output/runs/<run_name>/
  reducer/
  external_step_metrics.json
  joint_placement.json
  joint_module.step
  joint_module_manifest.json
  joint_module_validation_report.json
  joint_interference_report.json
```

`reducer/` 内部继续使用 reducer run 的标准结构：

```text
reducer/input_snapshot/
reducer/formula/
reducer/kinematics/
reducer/placement/
reducer/cad/
reducer/validation/
```

## URDF export

URDF 导出结果必须写入 `output/runs/<run_name>/exports/urdf/` 或其子目录。必须包含：

```text
*.urdf
package.xml
validation_report.json
export_manifest.json
meshes/
```

URDF 必须体现传动关系，不能只导出固定几何。当前项目用 `mimic` joint 表达太阳轮输入和行星架输出之间的传动比。

## 路径规则

- CLI 的 `--input` 必须在 `input/` 下。
- CLI 的 `--output` 必须在 `output/` 下。
- 不允许写入项目根目录、`src/`、`tests/`、`docs/` 作为生成结果。
- 不允许把生成物复制到旧目录或临时参考目录作为交付。