Campanhas reproduzíveis

O espaço de trabalho experiments/ contém tudo o que uma campanha produz e tudo o necessário para reproduzi-la. A separação é estrita: receitas são rastreadas, saídas são locais. As configurações de campanha e os scripts executores vivem no controle de versão; cada saída pesada — benchmarks gerados, registros de execução, logs, pontos de verificação, pacotes de evidência e o instantâneo de ambiente — permanece na máquina que a produziu e é regenerada sob demanda a partir da receita.

🗂️ Layout

Os diretórios de saída existem localmente e são recriados automaticamente pelo executor de campanha quando ausentes; nada sob eles é jamais preparado para commit.

🧱 Duas camadas, uma fonte de verdade

1. Camada de reprodutibilidade (granular). Cada execução é um registro JSON em results/{campaign_id}/{solver_id}/{benchmark_id}/run_{idx}.json. O caminho em si é o índice — campanha, depois solver, depois benchmark, depois réplica — de modo que qualquer fatia da evidência é endereçável sem um banco de dados. Os registros carregam campos de primeira classe de tempo, convergência, solução e esforço do solver; nada analítico se esconde em notas de forma livre.
2. Camada de curadoria (por níveis). evidence-bundles/{campaign_id}-{tier}/ contém as exportações por níveis de divulgação derivadas dos registros de execução. Os identificadores de nível vêm do vocabulário fixo seguro para o público — core, speed, quality, platform — e um pacote é sempre derivado dos registros em nível de execução, nunca uma fonte de verdade independente.

🔁 Contrato de reprodutibilidade

• Cada campanha declara uma semente mestra; a semente de cada execução deriva deterministicamente dela e da posição da execução — mesma configuração, mesmas sementes, mesmos registros, bit a bit.
• .checkpoints/{campaign_id}.json registra o hash da configuração. Uma configuração inalterada retoma do ponto de verificação e pula as execuções concluídas; qualquer mudança de configuração invalida o ponto de verificação por completo.
• ENVIRONMENT.md captura um instantâneo de host, sistema operacional, Python e o commit do repositório em tempo de execução, de modo que cada resultado é rastreável até o código e a máquina exatos que o produziram.
• Os logs são somente-acréscimo por execução.

Essas práticas — semente por execução, captura de configuração e ambiente para que um resultado possa ser regenerado a partir de sua receita — seguem padrões reconhecidos para documentar e reproduzir experimentos computacionais (ACM Artifact Review and Badging, Version 1.1, 2020; Gundersen & Kjensmo 2018).

O manifesto de reprodutibilidade também justifica o piso de 30 execuções com uma declaração de potência derivada: no piso, com um nível bilateral de 0,05 e potência de 0,80, o design emparelhado detecta efeitos padronizados de cerca de 0,523 ou maiores sob a aproximação de Wilcoxon ajustada-por-ARE (Noether 1987; arcabouço: Campelo e Takahashi 2019). A frase é recomputada a partir do piso no momento da renderização, de modo que nunca pode divergir do piso que justifica. Dois descritores de protocolo adicionais a acompanham: uma entrada de escalonamento-de-orçamento registrando como o orçamento de avaliação cresce com o tamanho da instância (o protocolo escalado-por-tamanho de Vallada, Ruiz e Framiñan 2015, registrado pelo manifesto de comparação-justa do laboratório como uma regra escalada-por-avaliação ou como fixa-por-campanha), e uma entrada de paridade-de-ajuste carregando o orçamento de ajuste igual por-algoritmo que toda campanha comparativa declara (LaTorre, Molina, Osaba, Poyatos, Del Ser e Herrera 2021); uma paridade não declarada renderiza honestamente como não declarada.

🏃 Como uma campanha escreve no espaço de trabalho

1. Crie ou ajuste uma configuração de campanha sob configs/ (smoke-pilot.json é o ponto de partida rastreado).

2. Execute-a através do executor de campanha — programaticamente como nos tutoriais, via um script de receita rastreado (uv run python experiments/scripts/run_smoke_pilot.py), ou através da interface de linha de comando:

   uv run dispatchatlas-lab run --config experiments/configs/smoke-pilot.json

3. O executor valida a configuração em um plano determinístico, escreve results/{campaign_id}/plan.json e environment.json, depois persiste um registro com hash de conteúdo por execução concluída mais quaisquer tentativas falhas.

4. Inspecione os registros de execução sob results/ e retome, reproduza ou reexecute a partir da mesma configuração. Reexecutar a mesma configuração reproduz os mesmos registros bit a bit; uma configuração alterada invalida o ponto de verificação em vez de reutilizá-lo silenciosamente.

A página do motor de campanhas documenta a validação, os orçamentos de execução a seco, os modos de execução, as retentativas, a retomada e a verificação por reprodução por completo.

📦 Dos registros de execução aos pacotes de evidência

A rota de exportação transforma um diretório de campanha concluído em um pacote curado sob evidence-bundles/{campaign_id}-{tier}/:

uv run dispatchatlas export `
  --campaign-dir .\experiments\results\smoke-pilot `
  --target-dir .\experiments `
  --authorized-output-root .\experiments `
  --tier core

tools/build_campaign_evidence.py conduz a mesma rota em escala, construindo catálogos de benchmarks, campanhas, análises e pacotes para cada nível a partir de uma configuração registrada. A página pacotes de evidência descreve os níveis; exportações de análise descreve o conteúdo estatístico.

🔒 Fronteira segura para o público

As páginas públicas nunca leem este espaço de trabalho diretamente: o site de documentação e o portal de resultados consomem apenas exportações comprometidas e filtradas por divulgação produzidas a partir da camada curada. Registros de programa privados no espaço de trabalho são ignorados pelo controle de versão e nunca alcançam uma superfície pública.