Обзор архитектуры

DispatchAtlas — это рабочее пространство из пяти сфокусированных пакетов распространения, разделяющих Python-пространство имён dispatchatlas, плюс корневой агрегатный пакет. Архитектура держит контракты предметной области в центре и выносит генерацию бенчмарков, решение, выполнение кампаний, анализ, документацию и автоматизацию релизов наружу. Каждая зависимость указывает внутрь, к dispatchatlas.core — никогда вбок между равноправными пакетами и никогда наружу к инструментарию.

🧭 Направление зависимостей

                 dispatchatlas.lab
                /        |        \
               v         |         v
  dispatchatlas.bench    |    dispatchatlas.solve
               \         |         /
                v        v        v
                dispatchatlas.core
                         ^
                         |
               dispatchatlas.analytica
       (также читает стабильные манифесты кампании как данные)

Каждая стрелка означает «импортирует». Все стрелки указывают к dispatchatlas.core; ни одна стрелка не указывает наружу или вбок. dispatchatlas.analytica намеренно не имеет стрелки к dispatchatlas.lab: он потребляет JSON-манифесты, которые завершённая кампания оставляет на диске, а не само время выполнения кампании.

Выведено из манифестов пакетов (packages/*/pyproject.toml) и инструкций импорта в дереве src/ каждого пакета; проверено 2026-06-10.

Слой	Пакет	Ответственность	Может импортировать	Не должен импортировать
Домен	`dispatchatlas.core`	Контракты планирования, валидация, происхождение, зёрна, сериализация, протоколы.	Только стандартная библиотека и одобренные лёгкие зависимости.	Любой другой пакет DispatchAtlas.
Бенчмарк	`dispatchatlas.bench`	Таксономия бенчмарков, генераторы, каталоги, материализация, доказательства цитирования.	`dispatchatlas.core`.	Код решателя, кампании, анализа или времени выполнения сайта.
Решатель	`dispatchatlas.solve`	Метаданные решателей, реестры, базовые методы, метаэвристики, операторы, опциональные адаптеры.	`dispatchatlas.core`.	Генераторы бенчмарков, исполнители кампаний, экспорты анализа или код времени выполнения сайта.
Кампания	`dispatchatlas.lab`	Воспроизводимая конфигурация кампаний, бюджеты, контрольные точки, повторы, выполнение.	`dispatchatlas.core`, `dispatchatlas.bench`, `dispatchatlas.solve`.	Пакет анализа или внутренности времени выполнения сайта.
Анализ	`dispatchatlas.analytica`	Статистика, фильтрация по раскрытию, пакеты доказательств, наборы данных портала, CLI.	`dispatchatlas.core`, плюс стабильные манифесты кампании, читаемые как данные JSON.	Живое выполнение кампаний или внутренности времени выполнения сайта.
Агрегат	`dispatchatlas`	Корневое распространение; раскрывает поверхность версии и закрепляет пять пакетов через свой extra `all`.	Ничего во время выполнения; композиция происходит через extras.	—

📦 Роли пакетов

dispatchatlas.core — это внутренняя граница. Он определяет общий словарь планирования (ProblemSpec, Schedule, цели, ограничения), валидацию, происхождение и родословную зёрен, каноническую сериализацию, и протоколы (BenchmarkProvider, Solver, ExperimentRunner, ResultRepository, DisclosurePolicy, AnalysisExporter), которые реализует каждый внешний пакет. Его манифест объявляет ноль зависимостей, так что домен остаётся импортируемым везде.
dispatchatlas.bench превращает словарь домена в доказательства бенчмарка: семейства генераторов, профили домена, дымовые и полные каталоги, метрики характеризации, и матрицу цитирования, которая записывает, откуда берутся допущения каждого семейства.
dispatchatlas.solve владеет всем, что производит расписания: метаданные решателей и дескрипторы возможностей, реестр решателей, конструктивные базовые методы, перестановочные метаэвристики, семейство NDSO, операторы планирования, и опциональные адаптеры точных решателей, удерживаемые за extras.
dispatchatlas.lab компонует бенчмарки и решатели в кампании с контрольными точками, бюджетом и штампом окружения, с детерминированными идентификаторами прогонов, и владеет матрицей применимости, которая сверяет каждое семейство с каждым решателем. Поэтому это единственный пакет, которому позволено видеть core, bench и solve вместе: соединять их — это ровно то, ради чего он существует.
dispatchatlas.analytica читает завершённый каталог кампании — checkpoint.json, plan.json, environment.json и строки результатов — и производит статистические сводки, пакеты доказательств, каркасы отчётов и наборы данных портала. Ввод на основе манифестов держит анализ воспроизводимым только из записанных артефактов.
dispatchatlas (корень) агрегирует пять пакетов для установки одной командой и несёт публичную поверхность версии.

🔒 Почему направление принудительно

Направление только-внутрь — это тестируемый контракт, а не соглашение:

Тестируемость. Core валидирует задачи и расписания без установленной машинерии решателя, кампании или анализа, так что доменные тесты выполняются с импортами только из стандартной библиотеки. Bench и solve тестируются против контрактов core, не затягивая друг друга.
Воспроизводимость. Поскольку dispatchatlas.analytica потребляет записанные манифесты, а не живое время выполнения кампании, любая завершённая кампания может быть переанализирована побайтово из своих артефактов.
Независимый релиз. Каждый пакет собирается и закрепляет версию отдельно; изменение решателя не может молча изменить поведение бенчмарка или анализа.

Тесты границ импорта живут в tests/architecture/: test_import_boundaries.py обходит каждый исходный файл пакета модулем ast и падает на любом импорте, пересекающем приведённую выше таблицу запрещённых импортов, а test_workspace_privacy.py охраняет частные исследовательские артефакты. Корневой AGENTS.md (§ Package Boundary Summary) задаёт это направление канонически, а CONTRIBUTING.md доносит его до контрибьюторов; эта страница — углублённый разбор поверх них, и каждый pull request проверяется по ней.

🌐 Публичные поверхности

Сайт документации под site/ потребляет одобренные экспортированные данные — отфильтрованные по раскрытию пакеты портала и сводки доказательств. Он не выполняет живые кампании и не обходит политику раскрытия.

🛠️ Поверхности управления

tools/ и CI могут инспектировать весь код пакетов, артефакты сборки и отчёты. Они контролируют качество снаружи и никогда не являются зависимостями времени выполнения продуктовых пакетов.