cadSet/text-to-cad/skills/cad-router/references/designir-3.0.md

# 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.

## Compact single-file storage

A DesignIR remains one source-independent JSON file. For surface-parametric and
hybrid documents, the dense `surface_layer` may use the lossless
`gzip+base64+json` storage envelope:

```json
{
  "surface_layer": {
    "format": "surfaceir-3.0",
    "encoding": "gzip+base64+json",
    "uncompressed_bytes": 10286354,
    "compressed_bytes": 2358852,
    "sha256": "<digest>",
    "data": "<base64>"
  }
}
```

The runtime verifies the byte counts and SHA-256 digest before rebuilding.
Decoding restores the same SurfaceIR object; no coordinate, topology, pcurve,
tolerance, parameter binding, or edit information is discarded. Legacy
documents containing an expanded `surface_layer` remain supported.

Agents must read the ordinary top-level `semantic_layer`, `edit_interface`, and
validated `parameters.json`. They must not place the encoded `surface_layer.data`
string in an LLM prompt. Deterministic CAD runtimes alone decode that field.

## Lazy URDF and MJCF export

URDF and MJCF are derived artifacts, not additional DesignIR authorities.
Generate them only after an explicit download/export request. The deterministic
exporter rebuilds from DesignIR alone and packages:

- the `.urdf` or `.mjcf.xml` description;
- an STL mesh used for visual and collision geometry;
- `robot-export.json` with source hash, scale, reconstruction strategy,
  structural assumptions, and dynamics status.

STEP-derived geometry without authoritative assembly, joint, or material
evidence exports as one fixed `base_link`. Do not infer articulated joints,
limits, actuators, density, mass, or inertia merely from disconnected solids.

## 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.