Visão geral da arquitetura

O DispatchAtlas é um espaço de trabalho de cinco pacotes de distribuição focados que compartilham o espaço de nomes Python dispatchatlas, mais um pacote agregado raiz. A arquitetura mantém os contratos do domínio no centro e move a geração de benchmarks, a resolução, a execução de campanhas, a análise, a documentação e a automação de versões para fora. Toda dependência aponta para dentro, em direção a dispatchatlas.core — nunca de lado entre pacotes pares e nunca para fora em direção às ferramentas.

🧭 Direção de dependências

                 dispatchatlas.lab
                /        |        \
               v         |         v
  dispatchatlas.bench    |    dispatchatlas.solve
               \         |         /
                v        v        v
                dispatchatlas.core
                         ^
                         |
               dispatchatlas.analytica
       (também lê manifestos estáveis de campanha como dados)

Cada seta significa "importa". Todas as setas apontam para dispatchatlas.core; nenhuma seta aponta para fora ou de lado. dispatchatlas.analytica deliberadamente não tem seta para dispatchatlas.lab: ele consome os manifestos JSON que uma campanha concluída deixa em disco, não o tempo de execução da campanha em si.

Derivado dos manifestos dos pacotes (packages/*/pyproject.toml) e das instruções de importação na árvore src/ de cada pacote; verificado 2026-06-10.

📦 Papéis dos pacotes

• dispatchatlas.core é o limite interno. Define o vocabulário de escalonamento compartilhado (ProblemSpec, Schedule, objetivos, restrições), a validação, a proveniência e a linhagem de sementes, a serialização canônica, e os protocolos (BenchmarkProvider, Solver, ExperimentRunner, ResultRepository, DisclosurePolicy, AnalysisExporter) que cada pacote externo implementa. Seu manifesto declara zero dependências, de modo que o domínio permanece importável em todo lugar.
• dispatchatlas.bench transforma o vocabulário do domínio em evidência de benchmark: famílias geradoras, perfis de domínio, catálogos de fumaça e completos, métricas de caracterização, e uma matriz de citação que registra de onde vêm as premissas de cada família.
• dispatchatlas.solve possui tudo o que produz escalonamentos: metadados de solvers e descritores de capacidade, o registro de solvers, linhas de base construtivas, metaheurísticas de permutação, a família NDSO, operadores de escalonamento, e adaptadores opcionais de solvers exatos mantidos atrás de extras.
• dispatchatlas.lab compõe benchmarks e solvers em campanhas com pontos de verificação, orçadas e carimbadas por ambiente, com identificadores de execução determinísticos, e detém a matriz de aplicabilidade que reconcilia cada família com cada solver. Por isso é o único pacote autorizado a ver core, bench e solve juntos: emparelhá-los é exatamente aquilo para que ele existe.
• dispatchatlas.analytica lê um diretório de campanha concluído — checkpoint.json, plan.json, environment.json e linhas de resultados — e produz resumos estatísticos, pacotes de evidência, andaimes de relatório e conjuntos de dados do portal. A entrada baseada em manifestos mantém a análise reproduzível apenas a partir dos artefatos registrados.
• dispatchatlas (raiz) agrega os cinco pacotes para uma instalação de um único comando e carrega a superfície de versão pública.

🔒 Por que a direção é imposta

A direção apenas-para-dentro é um contrato testado, não uma convenção:

• Testabilidade. O core valida problemas e escalonamentos sem nenhuma maquinaria de solver, campanha ou análise instalada, de modo que os testes do domínio rodam com importações apenas da biblioteca padrão. Bench e solve testam contra os contratos do core sem arrastar um ao outro.
• Reprodutibilidade. Como dispatchatlas.analytica consome manifestos registrados em vez do tempo de execução da campanha ao vivo, qualquer campanha concluída pode ser reanalisada byte a byte a partir de seus artefatos.
• Versão independente. Cada pacote compila e fixa sua versão separadamente; uma mudança de solver não pode alterar silenciosamente o comportamento de benchmark ou de análise.

Os testes de limite de importação vivem em tests/architecture/: test_import_boundaries.py percorre cada arquivo-fonte de pacote com o módulo ast e falha em qualquer importação que cruze a tabela de importações proibidas acima, e test_workspace_privacy.py protege os artefatos de pesquisa privados. O AGENTS.md raiz (§ Package Boundary Summary) enuncia essa direção de forma canônica e o CONTRIBUTING.md a repassa aos colaboradores; esta página é o aprofundamento sobre ambos, e cada pull request é revisado em relação a ela.

🌐 Superfícies públicas

O site de documentação sob site/ consome dados exportados aprovados — pacotes do portal filtrados por divulgação e resumos de evidência. Ele não executa campanhas ao vivo nem contorna a política de divulgação.

🛠️ Superfícies de governança

tools/ e a CI podem inspecionar todo o código dos pacotes, os artefatos de compilação e os relatórios. Eles controlam a qualidade de fora e nunca são dependências de tempo de execução dos pacotes do produto.