# DesignIR 3.0 unified contract

DesignIR 3.0 is the only editable part contract. It has three explicit modes:

- `fully_semantic_parametric`: authored from text or images. `semantic_layer`
  contains design intent, named parameters, constraints and executable
  features.
- `surface_parametric`: inferred from an uploaded STEP. `surface_layer`
  contains analytic/B-spline surfaces, boundary curves, pcurves, vertices,
  tolerances, shells and solids in CadSet's vocabulary.
- `hybrid_semantic_surface_parametric`: a semantic feature program plus a
  compiled SurfaceIR snapshot extracted from its generated STEP. The semantic
  layer remains authoritative.

The two authoring paths share one envelope and edit vocabulary, but they do not
claim equivalent evidence. Text/image generation authors design intent. STEP
ingestion infers semantics from final B-Rep and never claims to recover the
source CAD application's sketch or feature history.

## Text and image authoring

Author these top-level values:

```json
{
  "schema_version": "3.0",
  "designir_kind": "independent_parametric_cad",
  "model_id": "part_id",
  "family": "semantic_part_family",
  "units": "mm",
  "document_status": "geometry_present",
  "reconstruction_mode": "fully_semantic_parametric",
  "authoring_mode": "semantic_feature_program",
  "backend_hint": "build123d",
  "semantic_layer": {
    "reconstruction_status": "ready",
    "coordinate_system": {
      "origin": [0, 0, 0],
      "x_axis": [1, 0, 0],
      "y_axis": [0, 1, 0],
      "z_axis": [0, 0, 1]
    },
    "datums": {},
    "parameters": {},
    "expressions": {},
    "sketches": [],
    "constraints": [],
    "features": [],
    "patterns": [],
    "attachments": [],
    "construction_stages": []
  },
  "edit_interface": {
    "semantic_parameters": [],
    "surface_parameter_groups": [],
    "modification_levels": ["semantic_feature"],
    "preserved_interfaces": []
  },
  "validation_contract": {
    "source_independence": true,
    "geometry_checks": ["solid_count", "bounding_box", "volume"],
    "edit_checks": ["parameter_perturbation"],
    "invariants": [],
    "perturbations": [],
    "thresholds": {}
  }
}
```

Every name in `semantic_parameters` must identify an editable parameter, drive
at least one feature, and have a perturbation test. Prefer intent names such as
`flange_thickness`, `shelf_depth`, `hole_spacing`, `rib_count`,
`bore_diameter`, and `bolt_circle_diameter`.

After isolated compilation, attach SurfaceIR only from the generated STEP and
switch the mode to `hybrid_semantic_surface_parametric`. Never use a teacher
STEP to fill the compiled snapshot.

## Uploaded STEP execution

Run an uploaded file through the router's executable adapter:

```bash
../../.venv/bin/python scripts/route.py \
  "重建上传的 STEP，并返回可修改参数" \
  --edit-source /absolute/path/to/part.step \
  --task-dir /absolute/path/to/task \
  --execute
```

The task directory contains:

- `<part>.designir.json`: independent editable source of truth;
- `<part>.reconstructed.step`: reconstructed geometry;
- `parameters.json`: only parameters that passed perturbation acceptance;
- `validation/geometry.json`: teacher-versus-reconstruction measurements;
- `validation/edits.json`: parameter acceptance outcomes;
- `cad-task.json`: route, artifacts, isolation and validation state.

## Isolation boundary

Extraction and acceptance may read the uploaded STEP. The reconstruction
subprocess receives only DesignIR and an output path. DesignIR must not contain
a teacher path, an import operation, STEP text, embedded B-Rep, or a mesh
substitute.

The runtime performs an anti-cheat scan before rebuilding. Geometry acceptance
requires valid reconstructed topology and the thresholds recorded in
`validation/geometry.json`.

The adapter loads only formally promoted experiences whose scope is
`surfaceir_reconstruction` or `surfaceir_semantic_editing`. These methods are
applied conditionally by the runtime; `cad-task.json` records both the available
method count and the exact method IDs used for the task.

## Parameter boundary

STEP does not contain authoritative feature names or modeling history. The
semantic layer therefore records inferred canonical parameters separately from
validated editable parameters.

Only parameters in `parameters.json` are public edit controls. Each was changed
in isolation, rebuilt, and checked for target response, preserved validity and
non-target stability. Use the `edit_command_template` in `cad-task.json` to
produce an edited DesignIR and STEP.

An accepted baseline reconstruction does not imply that every inferred
parameter is editable. An empty `parameters.json` is valid for an empty source
document and must not be presented as editable geometry.