docs(cdsl_engine): document package layout and the add-atomic-operation workflow

Phase 8: README now maps every module of the split package, documents
the executor registration + schema-contract workflow for new atomic
operations, and restates the schema maintenance rule for executors/.

backend/engine/cdsl_engine/README.md

@@ -4,17 +4,53 @@ 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
+## Package layout
-feature/topology lifecycle. `build123d_adapter.py` is the only layer that
+
-creates or mutates B-rep objects. `runtime_types.py` owns runtime-neutral
+| Module | Responsibility |
-feature, context, selector, and topology contracts. `llm_compiler.py` and
+|---|---|
-`llm_engine.py` remain available for legacy engine-plan compatibility but are
+| `specs.py` | Vector math, plane/axis helpers, parametric feature specs (no kernel deps) |
-not used by `run_cdsl_only`.
+| `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` in `runtime.py`.
+Supported feature atomic operations are defined by `EXECUTORS` (populated from
-Their human-readable contract is in `profile_schema.json`; the complete,
+`executors/` at import time). Their human-readable contract is in
-machine-enforced CDSL object contract is in `cdsl_schema.json`.
+`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`.
@@ -24,10 +60,11 @@ The Studio only accepts self-contained profile data and requires successful
 `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
+`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 or
+`backend/tests/test_profile_schema.py` fails when the registered profiles,
-supported atomic operations diverge from the document.
+supported atomic operations, or `runtime_capability` flags diverge from the
+document.
 
 ## Batch baseline