# Per-part model specification

Use one `model-spec.json` per generated or imported part. Treat it as the
editable geometry contract. Keep `cad-task.json` separate for routing,
experience use, validation results, and viewer links.

## Native generator

Use `native_generator` when the part has editable Python source:

```json
{
  "schema_version": "1.0",
  "model_spec_kind": "parametric_cad_model",
  "model_id": "example_part",
  "units": "mm",
  "reconstruction": {
    "mode": "native_generator",
    "generator": {
      "path": "example_part.py",
      "entrypoint": "gen_step"
    }
  },
  "parameters": {
    "width": {
      "value": 40,
      "unit": "mm",
      "role": "overall_width"
    }
  },
  "modifications": [],
  "outputs": {
    "step": "example_part.step",
    "stl": "example_part.stl"
  }
}
```

The generator must read its sibling `model-spec.json`. Do not duplicate
authoritative parameter values as editable constants in both files.

## Imported STEP

Convert an explicitly supplied STEP into a task-local exact-base specification:

```bash
python scripts/model_spec.py import-step input.step \
  --task-dir models/cad-router-v1/imported_part \
  --model-id imported_part
```

This copies the source to `source.step`, records its SHA-256 and geometry
signature, writes `model-spec.json`, and exports regenerated STEP/STL files.
With an empty modification list, `verify` requires the imported B-Rep to retain
the same bounds, center, topology counts, solid count, and volume.

STEP normally contains final B-Rep geometry, not the original sketches,
constraints, names, or feature history. Therefore:

- `exact_step_base` guarantees an unchanged imported base, not recovered native
  design history.
- Add later edits as named parametric modifications.
- Use semantic native reconstruction only when the feature family can be
  reliably recognized and validate it independently against the source.
- Never claim arbitrary STEP-to-JSON conversion recovers the author’s original
  parameters or construction order.

## Parametric modification layer

Supported V1 operations are `add_box`, `cut_box`, `add_cylinder`, and
`cut_cylinder`. Values may be literals, direct parameter references, or affine
parameter expressions:

```json
{
  "id": "central_bore",
  "operation": "cut_cylinder",
  "axis": "z",
  "center": [0, 0, 0],
  "diameter": {"parameter": "bore_diameter"},
  "length": {"parameter": "bore_length"},
  "enabled": true
}
```

Use `scale` and `offset` when a tool center must stay anchored while its size
changes. For example, a positive-Z face at `z = 14.1` can remain the lower face
of an added box while `extension` changes:

```json
{
  "center": [
    13.1,
    -1.0,
    {"parameter": "extension", "scale": 0.5, "offset": 14.1}
  ],
  "size": [22.2, 2.0, {"parameter": "extension"}]
}
```

Change a named value and rebuild:

```bash
python scripts/model_spec.py set path/to/model-spec.json bore_diameter 18
python scripts/model_spec.py build path/to/model-spec.json
python scripts/model_spec.py verify path/to/model-spec.json
```

Use `apply_patch` when adding or structurally editing parameters and features so
the modification remains reviewable. After every visible rebuild, run the CAD
inspection and snapshot workflow and update `cad-task.json`.