# Coordinate-free semantic assembly

This directory defines the LCD25 reducer as a reusable mechanical design rather
than a list of STEP filenames and placement matrices.

## Authority

`lcd25-harmonic-reducer.assembly-designir.json` is the editable assembly
authority. It contains:

- product parameters and expressions;
- replaceable component archetypes;
- semantic interfaces constructed from generated geometry;
- mating and support relations;
- rigid groups, joints and harmonic transmission behavior;
- edit operations and interfaces that must remain stable.

It intentionally contains no XYZ position, rotation, transform matrix, source
STEP path, or occurrence coordinate. A backend generates each component,
discovers its declared interfaces and solves the constraint graph. Numeric
placements are compiler output and may be cached separately, but never become
design authority.

## Generality

The contract is not specific to LCD25. Component identities describe functional
roles such as `fixed_tooth_member`, `combined_load_support`, and
`external_output_interface`. Each role selects a replaceable generation family.
The same contract can express harmonic, planetary, cycloidal, belt, chain and
screw transmissions by changing archetypes, relations and the transmission
block.

## Structural modification

`variants/add-output-shaft.patch.json` demonstrates a structural edit. It adds:

- editable shaft diameter and length;
- a generated stepped-shaft component;
- coaxial, shoulder-mate, insert and torque-lock relations;
- output rigid-group membership;
- a new public shaft-end interface.

No coordinate is supplied. The assembly solver must position the shaft from its
relations to the output flange.

## Validation

Validate the base model:

```bash
python3 models/lcd25-reducer/semantic-assembly/validate_assembly_design.py \
  models/lcd25-reducer/semantic-assembly/lcd25-harmonic-reducer.assembly-designir.json \
  --schema designir-pipeline/contracts/assembly-designir-1.0.schema.json
```

Apply and validate the shaft variant:

```bash
python3 models/lcd25-reducer/semantic-assembly/validate_assembly_design.py \
  models/lcd25-reducer/semantic-assembly/lcd25-harmonic-reducer.assembly-designir.json \
  --schema designir-pipeline/contracts/assembly-designir-1.0.schema.json \
  --patch models/lcd25-reducer/semantic-assembly/variants/add-output-shaft.patch.json \
  --resolved-output models/lcd25-reducer/semantic-assembly/generated/lcd25-with-output-shaft.assembly-designir.json
```

## Compiler boundary

The next compiler stage must:

1. generate or select geometry for each component archetype;
2. resolve every semantic interface against generated topology;
3. solve relations from a scrambled initial state;
4. emit STEP occurrence placements only as derived output;
5. compile joints and transmissions to URDF/MJCF;
6. reject underconstrained, overconstrained or interfering assemblies.

The current validator proves schema integrity, coordinate independence,
reference integrity and graph connectivity. It does not yet solve B-Rep
constraints or generate the final reducer STEP.