cdsl-cad/backend/engine/cdsl_engine

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

Package layout

Module	Responsibility
specs.py	Vector math, plane/axis helpers, parametric feature specs (no kernel deps)
topology.py	Diagnostics, planning contracts, TopologyRegistry, selector resolution
capabilities.py	CapabilityAnalyzer: preflight blockers before any geometry runs
sketch_solver.py	Profile expansion (circle / polygon / analytic contours)
session.py	ExecutionSession and the kernel-facing GeometryAdapter protocol
runtime_base.py	Shared error types and the ExtentVector value
extents.py	End-condition planning (blind / through / up-to-surface / ...)
pattern_transform.py	Translate/mirror/rotate parameter algebra for pattern replay
registry.py	EXECUTORS, the atomic_executor decorator, and execute_node dispatch
executors/	One module per executor family; importing the package registers all
build123d_adapter.py	The only layer that creates or mutates B-rep objects
topology.py / runtime_types.py	Historical re-export shim (runtime_types)
translator/	Frozen SolidWorks-exact code generation (ir / codegen / runtime_lib)
legacy/	Frozen legacy engine paths (llm_compiler, llm_engine, exact rebuilds)
rebuild.py	Legacy three-way facade plus compare_with_gold acceptance

runtime.py keeps the analyze_cdsl / rebuild_cdsl entry points and re-exports the historical names. llm_compiler.py and llm_engine.py are compatibility shims for the frozen legacy/ implementations and are not used by run_cdsl_only.

Adding an atomic operation

1. Add the operation contract to profile_schema.json (operation_contracts), including its runtime_capability flags — this is the single source of truth for preflight classification.
2. Add a decorated executor function in exactly one executors/<family>.py module (@atomic_executor("...")); the shared registry never changes.
3. Add the atomic id to ALL_ATOMIC_IDS in registry.py (registration fails fast on unknown or duplicate ids, and executors/__init__ fails if any declared id has no registered executor).
4. Update cdsl_schema.json in the same change.
5. Extend backend/tests/test_profile_schema.py fixtures if the contract shape changed.

Multiple people can add different operations in parallel without touching a shared registry file: the only shared edits are the two schema documents.

Supported profiles are defined by SHAPE_GENERATORS in sketch_solver.py. Supported feature atomic operations are defined by EXECUTORS (populated from executors/ at import time). 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, executors/, or the build adapter must update both files in the same change. backend/tests/test_profile_schema.py fails when the registered profiles, supported atomic operations, or runtime_capability flags 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.