cdsl-cad/backend/engine/cdsl_engine/README.md

Local CDSL Engine

This package rebuilds cad.cdsl.llm.v1 models through the CDSL-only path:

semantic validation -> capability analysis -> sketch resolution -> session runtime -> STEP

runtime.py owns the executor registry, an ExecutionSession, and the feature/topology lifecycle. build123d_adapter.py is the only layer that creates or mutates B-rep objects. runtime_types.py owns runtime-neutral feature, context, selector, and topology contracts. llm_compiler.py and llm_engine.py remain available for legacy engine-plan compatibility but are not used by run_cdsl_only.

Supported profiles are defined by SHAPE_GENERATORS in sketch_solver.py. Supported feature atomic operations are defined by EXECUTORS in runtime.py. Their human-readable contract is in profile_schema.json; the complete, machine-enforced CDSL object contract is in cdsl_schema.json. The Studio only accepts self-contained profile data and requires successful engine=cdsl_only output. It never uses the legacy translator fallback or compiler_context.

Engine schema maintenance

profile_schema.json and cdsl_schema.json together are the source of truth for the engine contract exposed to the CAD Agent and the backend validator. Any addition, removal, rename, or parameter-contract change in sketch_solver.py, runtime.py, or the build adapter must update both files in the same change. backend/tests/test_profile_schema.py fails when the registered profiles or supported atomic operations diverge from the document.

Batch baseline

Use the resumable batch entry point to produce feature-level eligibility and rebuild reports. --build invokes only the session-based CDSL runtime; it never falls back to compiler_context or the legacy translator.

PYTHONPATH=backend/engine python -m cdsl_engine.batch_rebuild \
  json_to_cdsl/output --out /tmp/cdsl-batch --build --build-timeout 15

The output directory contains manifest.json, one report per part under parts/, summary-by-atomic.json, and summary-by-blocker.json. Re-run the same command to resume completed work; use --max-parts to run a bounded CI shard.

Use --part-ids 046112,053393 to run an exact, comma-separated regression subset. Unknown ids are rejected so a phase baseline cannot silently omit a requested part.

Use --phase p3, --phase p4, or --phase p6 to run a documented strict-closed static pool. The selector lives in phase_pools.py; its membership is regression-tested against the committed exports rather than copied into a shell command.

The runtime foundation test suite also analyzes every committed export without building STEP, so CI verifies that the full corpus always yields one machine-readable capability result per input. Use the batch command above for the slower, resumable truth-build layer.