CLAUDE

Comandos (core/apolo/commands/)

El registro schema-driven: models.py (fachada de los params pydantic = schema de UI, diálogos y tools del agente; viven en models_*.py por familia), escena.py (Feature, DEFINITIONS, _require/_instanced…: la capa de abajo), exec_*.py (executors por familia), registry.py (el shim, el REGISTRY, el despacho y los schemas), spec.py (CommandSpec + run_executor, el despacho), state.py (RegenState, el estado con nombre que execute_command muta y el regenerate guarda como checkpoint; ExecContext, lo que recibe un executor), strict.py (la entrada estricta de params), errors.py (CommandError) y expressions.py (motor de =expr). Lo transversal (locks, log, regenerate, cirugía de modelos) está en el CLAUDE.md raíz; lo común del backend, en core/apolo.

Al agregar o cambiar un comando

• Todo executor es _exec_x(ctx: ExecContext, cmd_id, p): ctx.scene, ctx.joints, ctx.fasteners… son los dicts VIVOS (se mutan en sitio), ctx.attachments los adjuntos y ctx.resolved_variables() las variables evaluadas. Ningún flag elige la firma (lo exige tests/test_despacho_unico.py): si un comando necesita más contexto, es una propiedad de ExecContext, no un flag ni una rama en el despacho. plan
• Params estrictos (strict.py): la ENTRADA de un cliente (las cuatro puertas de Document; también el preview con que el chat ensaya sus propuestas) rechaza la clave que el modelo no declara, con su ruta, las válidas y «¿quisiste decir…?»; el REPLAY la ignora (extra="ignore" explícito) y un edit sólo rechaza las que el cliente INTRODUCE (la UI reenvía los params guardados). Los modelos NO fijan extra: cambiaría el JSON Schema publicado. Quitar o renombrar un campo exige upcaster; un campo nuevo entra con un default que reproduce lo anterior (trinquete D12: tests/test_contrato_comandos.py); si lo NUEVO debe nacer con otro valor, el sello de entrada (CommandSpec.al_crear) se lo pone sólo al comando que nace (join_bolted.criterio, create_belt_conveyor.cierres).
• models.py es FACHADA (partir-nucleo-congelado F2): los params viven por familia —models_base (Vec3, Rot3, _floor_to_int, listas de catálogo), models_basicos (primitivas, patrones, colocación, set_variable), models_maquinas (conveyor, weldment, frame, script, brazo), models_chapa, models_modificar (caras, taladro, circular, espejo, ebanistería), models_croquis (croquis, barrido, loft, superficies) y models_ensamblaje (juntas, mates, restricciones, grupos, insert_project, ground)— y la fachada sólo re-exporta por IDENTIDAD, para siempre (tests/test_rutas_viejas.py, lista cerrada). Un modelo nuevo va a su familia (o a un models_<tema>.py nuevo, como models_rodillos.py) y se re-exporta en la fachada; una familia importa Vec3/Rot3 de .models_base, nunca de .models (ciclo).
• registry.py se partió igual (mismo plan, F3 y F4): capas escena ← exec_* ← registry. escena (Feature, DEFINITIONS, _require, _instanced, _orient_axis, _resolve_sel), exec_basicos (primitivas, booleana, patrones, espejo, borrar, duplicar, set_variable), exec_colocacion (_world_move/_world_place, transform, center_in, distribute, attach, snap_to, _planar_face_frame), exec_modificar (caras, fillet/chamfer/shell, _drill_tool, drill_hole, add_joinery), exec_croquis (sketch_*, barrido, loft, superficies, thicken, revolve, extrude_poly, import_step), exec_ensamblaje (_register_joint, _joint_drag, juntas, mates, restricciones, ground, grupos, _transform_point/_transform_dir, transform_group), exec_insertar (insert_project y su precheck) y exec_biblioteca (run_script, brazo, conveyor + _publish_axis_anchor, weldment/frame + _emit_weldment_parts, chapa). Un exec_* puede importar de otro exec_* (sin ciclos) pero nunca de registry (params de la fachada .models). registry.py sólo DEFINE REGISTRY, _validate_model, validate_params, execute_command, _schema_entry y command_schemas (lo exige tests/test_rutas_viejas.py): un executor nuevo va a su exec_* y aquí sólo se importa. registry re-exporta cada nombre movido por IDENTIDAD, para siempre (lista cerrada en tests/test_rutas_viejas.py; los blobs viejos de la caché nombran apolo.commands.registry.Feature). execute_command/validate_params se quedan en registry y execute_command lee run_executor (de spec) por el módulo registry: los tests parchean registry_mod.run_executor. Mover un executor byte a byte deja su huella igual: nunca se actualiza VERSIONES por un corte.
• Los imports perezosos from .registry import … DENTRO de executors ajenos (cilindro.py, exec_faja.py, tablero.py…) no se tocan: son parte de su huella D11.
• La description del modelo es para el AGENTE (larga a propósito, con nombres de params); la persona lee la PISTA de pistas.py (vista ?vista=persona, vista_persona.py): un comando nuevo sin pista rompe tests/test_pistas.py (ui). Un super-comando reutilizable documenta ahí su MONTAJE (orientación, tensado, soldadura), no sólo qué es.
• Versión del executor (CommandSpec.version): si cambia la geometría que produce con los MISMOS params, sube SU version (entra a la firma del regenerate sólo si es ≠ 1 → invalida la caché sólo de los proyectos que lo usan); si cambiaste un helper compartido, la de cada comando que lo usa; lo que no puedes acotar (kernel, builders, catálogo, Feature) es bump de GEOM_CACHE_EPOCH (regla completa en la raíz). Un comando que reproduce OTROS executors va con composite=True (hoy insert_project). El trinquete D11 (tests/test_contrato_comandos.py) guarda versión + huella del código de cada executor: si el código cambia y la versión no, falla y obliga a decidir (subirla, o sólo la huella si fue un refactor). La lógica de los dos trinquetes vive en apolo/contrato_comandos.py (viaja en la wheel; el test sólo guarda CAMPOS/VERSIONES). Un comando de EXTENSIÓN («x.algo», kind scene/vars) sigue la misma regla, con esas funciones; una ref de su catálogo suma el epoch_catalogo sólo a la firma de quien la nombra en sus params (spec.REFS_DE_EXTENSION; un compuesto, todas). plan (A4)
• Errores de OCCT accionables: fillet/chamfer nombran la arista más corta seleccionada; shell pre-valida 2·espesor ≥ dimensión menor antes de OCCT (condición necesaria, sin falsos positivos). No blindar geometría fina (radio vs caras vecinas): el try/except de OCCT es la red. V6.1