Vue d'ensemble de l'architecture

DispatchAtlas est un espace de travail de cinq paquets de distribution ciblés qui partagent l'espace de noms Python dispatchatlas, plus un paquet agrégat racine. L'architecture maintient les contrats du domaine au centre et déplace la génération de benchmarks, la résolution, l'exécution de campagnes, l'analyse, la documentation et l'automatisation des versions vers l'extérieur. Toute dépendance pointe vers l'intérieur, vers dispatchatlas.core — jamais latéralement entre paquets pairs et jamais vers l'extérieur vers l'outillage.

🧭 Direction des dépendances

                 dispatchatlas.lab
                /        |        \
               v         |         v
  dispatchatlas.bench    |    dispatchatlas.solve
               \         |         /
                v        v        v
                dispatchatlas.core
                         ^
                         |
               dispatchatlas.analytica
       (lit aussi des manifestes de campagne stables comme données)

Chaque flèche signifie « importe ». Toutes les flèches pointent vers dispatchatlas.core ; aucune flèche ne pointe vers l'extérieur ou latéralement. dispatchatlas.analytica n'a délibérément aucune flèche vers dispatchatlas.lab : il consomme les manifestes JSON qu'une campagne terminée laisse sur disque, et non le runtime de campagne lui-même.

Dérivé des manifestes des paquets (packages/*/pyproject.toml) et des instructions d'import dans l'arborescence src/ de chaque paquet ; vérifié 2026-06-10.

Couche	Paquet	Responsabilité	Peut importer	Ne doit pas importer
Domaine	`dispatchatlas.core`	Contrats d'ordonnancement, validation, provenance, graines, sérialisation, protocoles.	Bibliothèque standard et dépendances légères approuvées uniquement.	Tout autre paquet DispatchAtlas.
Benchmark	`dispatchatlas.bench`	Taxonomie de benchmarks, générateurs, catalogues, matérialisation, preuves de citation.	`dispatchatlas.core`.	Code de solveur, campagne, analyse ou runtime du site.
Solveur	`dispatchatlas.solve`	Métadonnées de solveurs, registres, lignes de base, métaheuristiques, opérateurs, adaptateurs optionnels.	`dispatchatlas.core`.	Générateurs de benchmarks, exécuteurs de campagnes, exports d'analyse ou code runtime du site.
Campagne	`dispatchatlas.lab`	Configuration reproductible de campagnes, budgets, points de contrôle, réessais, exécution.	`dispatchatlas.core`, `dispatchatlas.bench`, `dispatchatlas.solve`.	Le paquet d'analyse ou les internes runtime du site.
Analyse	`dispatchatlas.analytica`	Statistiques, filtrage par divulgation, lots de preuves, jeux de données du portail, la CLI.	`dispatchatlas.core`, plus des manifestes de campagne stables lus comme données JSON.	Exécution de campagnes en direct ou internes runtime du site.
Agrégat	`dispatchatlas`	Distribution racine ; expose la surface de version et fixe les cinq paquets via son extra `all`.	Rien au runtime ; la composition se fait via les extras.	—

📦 Rôles des paquets

dispatchatlas.core est la frontière interne. Il définit le vocabulaire d'ordonnancement partagé (ProblemSpec, Schedule, objectifs, contraintes), la validation, la provenance et le lignage des graines, la sérialisation canonique, et les protocoles (BenchmarkProvider, Solver, ExperimentRunner, ResultRepository, DisclosurePolicy, AnalysisExporter) que chaque paquet externe implémente. Son manifeste déclare zéro dépendance, donc le domaine reste importable partout.
dispatchatlas.bench transforme le vocabulaire du domaine en preuves de benchmark : familles génératrices, profils de domaine, catalogues de fumée et complets, métriques de caractérisation, et une matrice de citation qui enregistre d'où viennent les hypothèses de chaque famille.
dispatchatlas.solve possède tout ce qui produit des ordonnancements : métadonnées de solveurs et descripteurs de capacité, le registre de solveurs, lignes de base constructives, métaheuristiques de permutation, la famille NDSO, opérateurs d'ordonnancement, et adaptateurs optionnels de solveurs exacts gardés derrière des extras.
dispatchatlas.lab compose benchmarks et solveurs en campagnes à points de contrôle, budgétées et estampillées par environnement, avec des identifiants d'exécution déterministes, et détient la matrice d'applicabilité qui réconcilie chaque famille avec chaque solveur. C'est pourquoi il est le seul paquet autorisé à voir core, bench et solve ensemble : les apparier est précisément sa raison d'être.
dispatchatlas.analytica lit un répertoire de campagne terminé — checkpoint.json, plan.json, environment.json et lignes de résultats — et produit des résumés statistiques, des lots de preuves, des ébauches de rapport et des jeux de données du portail. L'entrée basée sur manifestes garde l'analyse reproductible à partir des seuls artefacts enregistrés.
dispatchatlas (racine) agrège les cinq paquets pour une installation en une commande et porte la surface de version publique.

🔒 Pourquoi la direction est appliquée

La direction uniquement-vers-l'intérieur est un contrat testé, pas une convention :

Testabilité. Core valide problèmes et ordonnancements sans aucune machinerie de solveur, campagne ou analyse installée, donc les tests du domaine s'exécutent avec des imports uniquement de la bibliothèque standard. Bench et solve se testent face aux contrats de core sans s'entraîner l'un l'autre.
Reproductibilité. Parce que dispatchatlas.analytica consomme des manifestes enregistrés plutôt que le runtime de campagne en direct, toute campagne terminée peut être réanalysée octet par octet à partir de ses artefacts.
Version indépendante. Chaque paquet se compile et fixe sa version séparément ; un changement de solveur ne peut pas altérer silencieusement le comportement de benchmark ou d'analyse.

Les tests de frontière d'import vivent dans tests/architecture/ : test_import_boundaries.py parcourt chaque fichier source de paquet avec le module ast et échoue sur tout import qui traverse la table d'imports interdits ci-dessus, et test_workspace_privacy.py protège les artefacts de recherche privés. Le AGENTS.md racine (§ Package Boundary Summary) énonce cette direction de façon canonique et CONTRIBUTING.md la relaie auprès des contributeurs ; cette page est l'approfondissement bâti sur eux, et chaque pull request est revue par rapport à elle.

🌐 Surfaces publiques

Le site de documentation sous site/ consomme des données exportées approuvées — lots du portail filtrés par divulgation et résumés de preuves. Il n'exécute pas de campagnes en direct et ne contourne pas la politique de divulgation.

🛠️ Surfaces de gouvernance

tools/ et la CI peuvent inspecter tout le code des paquets, les artefacts de compilation et les rapports. Ils contrôlent la qualité depuis l'extérieur et ne sont jamais des dépendances runtime des paquets du produit.