재현 가능한 캠페인

experiments/ 작업 공간은 캠페인이 생산하는 모든 것과 그것을 재현하는 데 필요한 모든 것을 보관합니다. 분리는 엄격합니다: 레시피는 추적되고, 출력은 로컬입니다. 캠페인 구성과 러너 스크립트는 소스 관리에 두고, 모든 무거운 출력 — 생성된 벤치마크, 실행 기록, 로그, 체크포인트, 증거 번들, 환경 스냅샷 — 은 그것을 생산한 머신에 남아 필요 시 레시피로 부터 재생성됩니다.

🗂️ 레이아웃

경로	추적됨	보관
`configs/`	예	캠페인 구성 — 완전한 레시피: 솔버 명단, 벤치마크 스위트, 실행 횟수, 예산, 마스터 시드.
`scripts/`	예	캠페인 및 분석 러너(예: `run_smoke_pilot.py`).
`benchmarks/`	아니오	구체화된 벤치마크 인스턴스.
`results/`	아니오	실행 기록, `results/{campaign_id}/{solver_id}/{benchmark_id}/run_{idx}.json` 에.
`logs/`	아니오	실행 로그, `logs/{campaign_id}_{YYYYMMDD_HHMMSS}.log` 에.
`.checkpoints/`	아니오	재개 가능한 캠페인 상태, `.checkpoints/{campaign_id}.json` 에, 구성 해시로 보호.
`evidence-bundles/`	아니오	큐레이션되고 공개-계층화된 내보내기, `evidence-bundles/{campaign_id}-{tier}/` 에.
`ENVIRONMENT.md`	아니오	실행 시 포착된 호스트·OS·Python·커밋 스냅샷.

출력 디렉터리는 로컬에 존재하며 없을 때 캠페인 러너가 자동으로 다시 만듭니다; 그 아래의 어떤 것도 결코 스테이징되지 않습니다.

🧱 두 계층, 하나의 진실 원천

재현성 계층(세분화). 각 실행은 results/{campaign_id}/{solver_id}/{benchmark_id}/run_{idx}.json 의 하나의 JSON 기록입니다. 경로 자체가 색인입니다 — 캠페인, 그다음 솔버, 그다음 벤치마크, 그다음 반복 — 따라서 증거의 어떤 조각이든 데이터베이스 없이 주소 지정 가능합니다. 기록은 타이밍·수렴·해·솔버 노력의 일급 필드를 담으며, 분석적인 것이 자유 형식 메모에 숨지 않습니다.
큐레이션 계층(계층화). evidence-bundles/{campaign_id}-{tier}/ 는 실행 기록에서 파생된 공개-계층화 내보내기를 보관합니다. 계층 id는 고정된 공개 안전 어휘 — core, speed, quality, platform — 에서 오며, 번들은 항상 실행 수준 기록에서 파생되고 결코 독립적 진실 원천이 아닙니다.

🔁 재현성 계약

각 캠페인은 하나의 마스터 시드를 선언합니다; 각 실행의 시드는 그것과 실행 위치로부터 결정적으로 파생됩니다 — 같은 구성, 같은 시드, 같은 기록, 비트 단위로.
.checkpoints/{campaign_id}.json 은 구성 해시를 기록합니다. 변경되지 않은 구성은 체크포인트에서 재개하고 완료된 실행을 건너뜁니다; 어떤 구성 변경이든 체크포인트를 전면 무효화합니다.
ENVIRONMENT.md 는 실행 시 호스트, 운영체제, Python, 저장소 커밋을 스냅샷하므로 모든 결과가 그것을 생산한 정확한 코드와 머신까지 추적 가능합니다.
로그는 실행마다 추가-전용입니다.

이러한 관행 — 실행마다의 시드, 결과를 레시피로부터 재생성할 수 있도록 하는 구성과 환경 포착 — 은 계산 실험을 문서화하고 재현하기 위한 공인 표준을 따릅니다 (ACM Artifact Review and Badging, Version 1.1, 2020; Gundersen & Kjensmo 2018).

재현성 매니페스트는 또한 30-실행 하한을 유도된 검정력 진술로 정당화합니다: 하한에서, 양측 0.05 수준과 0.80 검정력으로, 쌍별 설계는 ARE-보정 Wilcoxon 근사 아래 약 0.523 이상의 표준화된 효과를 탐지합니다(Noether 1987; 프레임워크: Campelo and Takahashi 2019). 이 문장은 렌더 시점에 하한으로부터 다시 계산되므로, 그것이 정당화하는 하한으로부터 결코 어긋날 수 없습니다. 두 개의 추가 프로토콜 서술자가 그 곁에 다닙니다: 평가 예산이 인스턴스 크기에 따라 어떻게 커지는지 기록하는 예산-스케일링 항목(Vallada, Ruiz and Framiñan 2015 의 크기-스케일 프로토콜로, 랩 공정-비교 매니페스트가 평가-스케일 규칙으로 또는 캠페인-고정으로 기록), 그리고 모든 비교 캠페인이 선언하는 알고리즘당 동등 튜닝 예산을 담는 튜닝-패리티 항목(LaTorre, Molina, Osaba, Poyatos, Del Ser and Herrera 2021); 선언되지 않은 패리티는 정직하게 미선언으로 렌더링됩니다.

🏃 캠페인이 작업 공간에 쓰는 방법

configs/ 아래에 캠페인 구성을 작성하거나 조정합니다(smoke-pilot.json 이 추적되는 출발점).
캠페인 러너를 통해 실행합니다 — 튜토리얼 처럼 프로그램적으로, 추적되는 레시피 스크립트(uv run python experiments/scripts/run_smoke_pilot.py)를 통해, 또는 명령줄 인터페이스를 통해:
```
uv run dispatchatlas-lab run --config experiments/configs/smoke-pilot.json
```
러너는 구성을 결정적 계획으로 검증하고, results/{campaign_id}/plan.json 과 environment.json 을 쓰고, 그다음 완료된 각 실행에 더해 실패한 시도가 있으면 그것도, 콘텐츠 해시된 기록을 하나씩 영속화합니다.
results/ 아래 실행 기록을 검사하고 같은 구성에서 재개·재생·재실행합니다. 같은 구성을 다시 실행하면 같은 기록이 비트 단위로 재현됩니다; 변경된 구성은 체크포인트를 조용히 재사용하는 대신 무효화합니다.

캠페인 엔진 페이지는 검증, 드라이런 예산, 실행 모드, 재시도, 재개, 재생 검증을 완전히 문서화합니다.

📦 실행 기록에서 증거 번들로

내보내기 경로는 완료된 캠페인 디렉터리를 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 는 같은 경로를 규모에서 구동하여, 기록된 하나의 구성으로부터 모든 계층의 벤치마크 카탈로그, 캠페인, 분석, 번들을 구축합니다. 증거 번들 페이지는 계층을 기술하고, 분석 내보내기 는 통계 내용을 기술합니다.

🔒 공개 안전 경계

공개 페이지는 이 작업 공간을 직접 읽지 않습니다: 문서 사이트와 결과 포털 은 큐레이션 계층에서 생산된, 커밋되고 공개 필터링된 내보내기만 소비합니다. 작업 공간의 비공개 프로그램 원장은 소스 관리에서 무시되며 결코 공개 표면에 도달하지 않습니다.