아키텍처 개요

DispatchAtlas는 dispatchatlas Python 네임스페이스를 공유하는 다섯 개의 집중된 배포 패키지와 루트 집계 패키지로 이루어진 작업 공간입니다. 아키텍처는 도메인 계약을 중심에 두고 벤치마크 생성, 풀이, 캠페인 실행, 분석, 문서, 릴리스 자동화를 바깥으로 옮깁니다. 모든 의존성은 안쪽으로, 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`	루트 배포; 버전 표면을 노출하고 `all` 엑스트라를 통해 다섯 패키지를 고정.	런타임에는 없음; 합성은 엑스트라를 통해 발생.	—

📦 패키지 역할

dispatchatlas.core 는 안쪽 경계입니다. 공유 스케줄링 어휘(ProblemSpec, Schedule, 목표, 제약), 검증, 출처와 시드 계보, 정전적 직렬화, 그리고 모든 바깥 패키지가 구현하는 프로토콜(BenchmarkProvider, Solver, ExperimentRunner, ResultRepository, DisclosurePolicy, AnalysisExporter)을 정의합니다. 그 매니페스트는 의존성 제로를 선언하므로 도메인은 어디서나 임포트 가능한 채로 유지됩니다.
dispatchatlas.bench 는 도메인 어휘를 벤치마크 증거로 바꿉니다: 생성기 패밀리, 도메인 프로파일, 스모크 및 완전 카탈로그, 특성화 지표, 그리고 각 패밀리의 가정이 어디서 오는지 기록하는 인용 매트릭스.
dispatchatlas.solve 는 스케줄을 생산하는 모든 것을 소유합니다: 솔버 메타데이터와 능력 기술자, 솔버 레지스트리, 구성적 베이스라인, 순열 메타휴리스틱, NDSO 패밀리, 스케줄링 연산자, 그리고 엑스트라 뒤에 유지되는 선택적 정확해 솔버 어댑터.
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는 모든 패키지 코드, 빌드 산출물, 보고서를 검사할 수 있습니다. 바깥에서 품질을 게이트하며 제품 패키지의 런타임 의존성이 결코 아닙니다.