# 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: - `.designir.json`: independent editable source of truth; - `.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": "", "data": "" } } ``` 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.