# Backend and artifact contract

## Router input

Capture these fields when known:

- Natural-language request and normalized part family.
- Units and dimensions.
- Manufacturing intent: machining, printing, laser cutting, simulation, or concept.
- Required primary and secondary output formats.
- New model versus modification, and existing source/artifact paths.
- Part versus assembly, standard components, mating requirements, and motion relationships.
- Required parameter controls, replay, semantic tags, or FreeCAD interchange.
- Geometry and visual validation targets.
- Optional schema `2.0` generalized experience library. Never pass a case
  DesignIR, teacher STEP, source dimensions, coordinates, or surface references
  to the selected backend.
- For modification, accept only an explicitly supplied original model or
  editable generator plus the promoted library. Never inspect the parser
  input/output corpus or a private case JSON.

## Route decision

Record:

- `selected_backend`: `build123d`, `simplecadapi`, or `cadam`.
- Origin project and optional executable adapter.
- `runner_skill`: installed Skill responsible for generation.
- Ranked backend scores and human-readable reasons.
- Fallback order.
- Workflow profiles such as `requirement_refinement` and `visual_repair`.
- Focused downstream Skills.
- Any explicit override and its reason.
- `operation`: create or modify; for modification also record the explicit
  source path and whether the route uses native parameter editing, local feature
  rebuilding, or experience-guided semantic reconstruction.

## Task manifest

Write `cad-task.json` beside the task artifacts with this minimum shape:

```json
{
  "schema_version": "1.0",
  "request": "Create a 120 mm connecting rod",
  "route": {
    "selected_backend": "build123d",
    "runner_skill": "cad",
    "project": "text-to-cad",
    "fallback_order": ["simplecadapi", "cadam"],
    "workflow_profiles": ["requirement_refinement", "visual_repair"]
  },
  "source": {
    "path": "connecting_rod.py",
    "format": "python",
    "backend": "build123d"
  },
  "artifacts": [
    {"path": "connecting_rod.step", "role": "primary"},
    {"path": "connecting_rod.stl", "role": "secondary"}
  ],
  "parameters": {},
  "experience": {
    "library": "../../../cad-experience-library/library.json",
    "context_kind": "generalized_cad_experience_query",
    "methods_applied": []
  },
  "assumptions": [],
  "validation": [],
  "viewer_links": []
}
```

Paths are relative to the task directory unless an external input must remain absolute.
Do not store authoritative model parameters in `cad-task.json`. Every part must
have a sibling `model-spec.json` that owns its parameter values, reconstruction
mode, parametric modification layer, and output paths. See `model-spec.md`.

For an imported STEP, use `exact_step_base`: copy the explicitly supplied file
into the task directory, record its checksum and geometry signature, and keep
the imported B-Rep unchanged when the modification list is empty. This is an
exact geometric base contract, not recovery of the original CAD feature tree.

## Backend adapter requirements

Any future executable adapter must:

1. Accept an explicit task directory and explicit source/output paths.
2. Never scan or generate an entire workspace implicitly.
3. Preserve a human-editable source of truth.
4. Report backend name and version.
5. Return nonzero on generation failure.
6. Emit machine-readable artifact paths and validation facts.
7. Avoid importing code from sibling Skill directories; call installed tools or self-contained runtimes.
8. Keep permanent CAD artifacts under the repository `models/` root when working inside this repository.
9. Start CAD Viewer at the task directory, not the repository-wide examples directory.