Visión general de la arquitectura

DispatchAtlas es un espacio de trabajo de cinco paquetes de distribución enfocados que comparten el espacio de nombres de Python dispatchatlas, más un paquete agregado raíz. La arquitectura mantiene los contratos del dominio en el centro y desplaza la generación de benchmarks, la resolución, la ejecución de campañas, el análisis, la documentación y la automatización de versiones hacia afuera. Toda dependencia apunta hacia adentro, hacia dispatchatlas.core — nunca de lado entre paquetes pares y nunca hacia afuera hacia las herramientas.

🧭 Dirección de dependencias

                 dispatchatlas.lab
                /        |        \
               v         |         v
  dispatchatlas.bench    |    dispatchatlas.solve
               \         |         /
                v        v        v
                dispatchatlas.core
                         ^
                         |
               dispatchatlas.analytica
       (también lee manifiestos estables de campaña como datos)

Cada flecha significa "importa". Todas las flechas apuntan hacia dispatchatlas.core; ninguna flecha apunta hacia afuera o de lado. dispatchatlas.analytica deliberadamente no tiene flecha hacia dispatchatlas.lab: consume los manifiestos JSON que una campaña completada deja en disco, no el tiempo de ejecución de la campaña en sí.

Derivado de los manifiestos de los paquetes (packages/*/pyproject.toml) y las sentencias de importación en el árbol src/ de cada paquete; verificado 2026-06-10.

📦 Roles de los paquetes

• dispatchatlas.core es el límite interno. Define el vocabulario de planificación compartido (ProblemSpec, Schedule, objetivos, restricciones), la validación, la procedencia y el linaje de semillas, la serialización canónica, y los protocolos (BenchmarkProvider, Solver, ExperimentRunner, ResultRepository, DisclosurePolicy, AnalysisExporter) que cada paquete externo implementa. Su manifiesto declara cero dependencias, de modo que el dominio permanece importable en todas partes.
• dispatchatlas.bench convierte el vocabulario del dominio en evidencia de benchmark: familias generadoras, perfiles de dominio, catálogos de humo y completos, métricas de caracterización, y una matriz de citación que registra de dónde provienen los supuestos de cada familia.
• dispatchatlas.solve posee todo lo que produce planificaciones: metadatos de solvers y descriptores de capacidad, el registro de solvers, líneas base constructivas, metaheurísticas de permutación, la familia NDSO, operadores de planificación, y adaptadores opcionales de solvers exactos mantenidos detrás de extras.
• dispatchatlas.lab compone benchmarks y solvers en campañas con puntos de control, presupuestadas y con sello de entorno, con identificadores de ejecución deterministas, y posee la matriz de aplicabilidad que concilia cada familia con cada solver. Por eso es el único paquete autorizado a ver core, bench y solve juntos: emparejarlos es justo aquello para lo que existe.
• dispatchatlas.analytica lee un directorio de campaña terminado — checkpoint.json, plan.json, environment.json y filas de resultados — y produce resúmenes estadísticos, paquetes de evidencia, andamiajes de informe y conjuntos de datos del portal. La entrada basada en manifiestos mantiene el análisis reproducible solo a partir de los artefactos registrados.
• dispatchatlas (raíz) agrega los cinco paquetes para una instalación de un solo comando y lleva la superficie de versión pública.

🔒 Por qué se hace cumplir la dirección

La dirección solo-hacia-adentro es un contrato probado, no una convención:

• Testeabilidad. Core valida problemas y planificaciones sin maquinaria de solver, campaña o análisis instalada, de modo que las pruebas del dominio se ejecutan con importaciones solo de la biblioteca estándar. Bench y solve se prueban frente a los contratos de core sin arrastrarse mutuamente.
• Reproducibilidad. Como dispatchatlas.analytica consume manifiestos registrados en lugar del tiempo de ejecución de la campaña en vivo, cualquier campaña completada puede reanalizarse byte por byte a partir de sus artefactos.
• Versión independiente. Cada paquete se compila y fija su versión por separado; un cambio de solver no puede alterar silenciosamente el comportamiento de benchmark o de análisis.

Las pruebas de límite de importación viven en tests/architecture/: test_import_boundaries.py recorre cada archivo fuente de paquete con el módulo ast y falla ante cualquier importación que cruce la tabla de importaciones prohibidas anterior, y test_workspace_privacy.py protege los artefactos de investigación privados. El AGENTS.md raíz (§ Package Boundary Summary) enuncia esa dirección de forma canónica y CONTRIBUTING.md la traslada a los colaboradores; esta página es la profundización sobre ambos, y cada pull request se revisa frente a ella.

🌐 Superficies públicas

El sitio de documentación bajo site/ consume datos exportados aprobados — paquetes del portal filtrados por divulgación y resúmenes de evidencia. No ejecuta campañas en vivo ni elude la política de divulgación.

🛠️ Superficies de gobernanza

tools/ y la CI pueden inspeccionar todo el código de los paquetes, los artefactos de compilación y los informes. Controlan la calidad desde afuera y nunca son dependencias de tiempo de ejecución de los paquetes del producto.