Architekturübersicht

DispatchAtlas ist ein Arbeitsbereich aus fünf fokussierten Distributionspaketen, die sich den Python-Namensraum dispatchatlas teilen, plus einem aggregierten Wurzelpaket. Die Architektur hält Domänenverträge im Zentrum und verschiebt Benchmark-Generierung, Lösen, Kampagnenausführung, Analyse, Dokumentation und Release-Automatisierung nach außen. Jede Abhängigkeit zeigt nach innen, zu dispatchatlas.core — nie seitwärts zwischen Peer-Paketen und nie nach außen zum Werkzeug.

🧭 Abhängigkeitsrichtung

                 dispatchatlas.lab
                /        |        \
               v         |         v
  dispatchatlas.bench    |    dispatchatlas.solve
               \         |         /
                v        v        v
                dispatchatlas.core
                         ^
                         |
               dispatchatlas.analytica
       (liest auch stabile Kampagnen-Manifeste als Daten)

Jeder Pfeil bedeutet „importiert". Alle Pfeile zeigen zu dispatchatlas.core; kein Pfeil zeigt nach außen oder seitwärts. dispatchatlas.analytica hat absichtlich keinen Pfeil zu dispatchatlas.lab: es konsumiert die JSON-Manifeste, die eine abgeschlossene Kampagne auf der Platte hinterlässt, nicht das Kampagnen-Runtime selbst.

Abgeleitet aus den Paket-Manifesten (packages/*/pyproject.toml) und den Import-Anweisungen im src/-Baum jedes Pakets; verifiziert 2026-06-10.

Schicht	Paket	Verantwortung	Darf importieren	Darf nicht importieren
Domäne	`dispatchatlas.core`	Scheduling-Verträge, Validierung, Provenienz, Seeds, Serialisierung, Protokolle.	Nur Standardbibliothek und freigegebene leichte Abhängigkeiten.	Jedes andere DispatchAtlas-Paket.
Benchmark	`dispatchatlas.bench`	Benchmark-Taxonomie, Generatoren, Kataloge, Materialisierung, Zitationsbelege.	`dispatchatlas.core`.	Solver-, Kampagnen-, Analyse- oder Site-Runtime-Code.
Solver	`dispatchatlas.solve`	Solver-Metadaten, Registries, Baselines, Metaheuristiken, Operatoren, optionale Adapter.	`dispatchatlas.core`.	Benchmark-Generatoren, Kampagnen-Runner, Analyse-Exporte oder Site-Runtime-Code.
Kampagne	`dispatchatlas.lab`	Reproduzierbare Kampagnenkonfiguration, Budgets, Prüfpunkte, Wiederholungen, Ausführung.	`dispatchatlas.core`, `dispatchatlas.bench`, `dispatchatlas.solve`.	Das Analysepaket oder Site-Runtime-Interna.
Analyse	`dispatchatlas.analytica`	Statistik, Offenlegungsfilterung, Belegpakete, Portal-Datensätze, die CLI.	`dispatchatlas.core`, plus stabile Kampagnen-Manifeste, als JSON-Daten gelesen.	Live-Kampagnenausführung oder Site-Runtime-Interna.
Aggregat	`dispatchatlas`	Wurzel-Distribution; legt die Versionsoberfläche offen und pinnt die fünf Pakete über sein `all`-Extra.	Nichts zur Laufzeit; Komposition erfolgt über Extras.	—

📦 Paketrollen

dispatchatlas.core ist die innere Grenze. Es definiert das gemeinsame Scheduling-Vokabular (ProblemSpec, Schedule, Ziele, Constraints), die Validierung, Provenienz und Seed-Abstammung, die kanonische Serialisierung und die Protokolle (BenchmarkProvider, Solver, ExperimentRunner, ResultRepository, DisclosurePolicy, AnalysisExporter), die jedes äußere Paket implementiert. Sein Manifest deklariert null Abhängigkeiten, sodass die Domäne überall importierbar bleibt.
dispatchatlas.bench verwandelt das Domänenvokabular in Benchmark-Belege: Generatorfamilien, Domänenprofile, Smoke- und Vollkataloge, Charakterisierungsmetriken und eine Zitationsmatrix, die festhält, woher die Annahmen jeder Familie stammen.
dispatchatlas.solve besitzt alles, was Schedules erzeugt: Solver-Metadaten und Fähigkeitsdeskriptoren, die Solver-Registry, konstruktive Baselines, Permutations-Metaheuristiken, die NDSO-Familie, Scheduling-Operatoren und optionale exakte Solver-Adapter, hinter Extras gehalten.
dispatchatlas.lab komponiert Benchmarks und Solver zu prüfpunktbasierten, budgetierten, umgebungsgestempelten Kampagnen mit deterministischen Lauf-Identifikatoren und besitzt die Anwendbarkeitsmatrix, die jede Familie mit jedem Solver abgleicht. Deshalb ist es das einzige Paket, das core, bench und solve zusammen sehen darf: sie zu paaren ist genau das, wofür es existiert.
dispatchatlas.analytica liest ein abgeschlossenes Kampagnenverzeichnis — checkpoint.json, plan.json, environment.json und Ergebniszeilen — und erzeugt statistische Zusammenfassungen, Belegpakete, Berichtsgerüste und Portal-Datensätze. Die manifestbasierte Eingabe hält die Analyse allein aus den aufgezeichneten Artefakten reproduzierbar.
dispatchatlas (Wurzel) aggregiert die fünf Pakete für eine Ein-Befehl-Installation und trägt die öffentliche Versionsoberfläche.

🔒 Warum die Richtung erzwungen wird

Die Nur-nach-innen-Richtung ist ein getesteter Vertrag, keine Konvention:

Testbarkeit. Core validiert Probleme und Schedules ohne installierte Solver-, Kampagnen- oder Analysemaschinerie, sodass Domänentests mit Imports nur aus der Standardbibliothek laufen. Bench und solve testen gegen die Core-Verträge, ohne einander hineinzuziehen.
Reproduzierbarkeit. Weil dispatchatlas.analytica aufgezeichnete Manifeste statt des Live-Kampagnen-Runtimes konsumiert, kann jede abgeschlossene Kampagne Byte für Byte aus ihren Artefakten reanalysiert werden.
Unabhängige Veröffentlichung. Jedes Paket baut und pinnt seine Version separat; eine Solver-Änderung kann das Benchmark- oder Analyseverhalten nicht still verändern.

Import-Grenztests liegen in tests/architecture/: test_import_boundaries.py durchläuft jede Paket-Quelldatei mit dem ast-Modul und scheitert an jedem Import, der die obige Verbotene-Imports-Tabelle überschreitet, und test_workspace_privacy.py schützt private Forschungsartefakte. Diese Richtung legt das Wurzel-AGENTS.md (§ Package Boundary Summary) verbindlich fest, und CONTRIBUTING.md trägt sie an die Mitwirkenden weiter; diese Seite ist die Vertiefung darauf, und jeder Pull Request wird an ihr geprüft.

🌐 Öffentliche Oberflächen

Die Dokumentations-Website unter site/ konsumiert freigegebene exportierte Daten — nach Offenlegung gefilterte Portalpakete und Belegzusammenfassungen. Sie führt keine Live-Kampagnen aus und umgeht keine Offenlegungsrichtlinie.

🛠️ Governance-Oberflächen

tools/ und die CI dürfen den gesamten Paketcode, die Build-Artefakte und die Berichte inspizieren. Sie kontrollieren die Qualität von außen und sind nie Laufzeitabhängigkeiten der Produktpakete.