Ikhtisar arsitektur

DispatchAtlas adalah ruang kerja berisi lima paket distribusi terfokus yang berbagi namespace Python dispatchatlas, ditambah satu paket agregat akar. Arsitekturnya menjaga kontrak domain di pusat dan memindahkan pembangkitan benchmark, penyelesaian, eksekusi kampanye, analisis, dokumentasi, dan otomasi rilis ke luar. Setiap dependensi menunjuk ke dalam, ke arah dispatchatlas.core — tidak pernah menyamping antar paket sejawat dan tidak pernah ke luar ke arah perkakas.

🧭 Arah dependensi

                 dispatchatlas.lab
                /        |        \
               v         |         v
  dispatchatlas.bench    |    dispatchatlas.solve
               \         |         /
                v        v        v
                dispatchatlas.core
                         ^
                         |
               dispatchatlas.analytica
       (juga membaca manifes kampanye stabil sebagai data)

Setiap panah berarti "mengimpor". Semua panah menunjuk ke dispatchatlas.core; tidak ada panah yang menunjuk ke luar atau menyamping. dispatchatlas.analytica secara sengaja tidak punya panah ke dispatchatlas.lab: ia mengonsumsi manifes JSON yang ditinggalkan kampanye yang selesai di disk, bukan runtime kampanye itu sendiri.

Diturunkan dari manifes paket (packages/*/pyproject.toml) dan pernyataan impor di pohon src/ setiap paket; diverifikasi 2026-06-10.

Lapisan	Paket	Tanggung jawab	Boleh mengimpor	Tidak boleh mengimpor
Domain	`dispatchatlas.core`	Kontrak penjadwalan, validasi, provenans, benih, serialisasi, protokol.	Hanya pustaka standar dan dependensi ringan yang disetujui.	Paket DispatchAtlas lain mana pun.
Benchmark	`dispatchatlas.bench`	Taksonomi benchmark, generator, katalog, materialisasi, bukti sitasi.	`dispatchatlas.core`.	Kode solver, kampanye, analisis, atau runtime situs.
Solver	`dispatchatlas.solve`	Metadata solver, registry, baseline, metaheuristik, operator, adapter opsional.	`dispatchatlas.core`.	Generator benchmark, pelaksana kampanye, ekspor analisis, atau kode runtime situs.
Kampanye	`dispatchatlas.lab`	Konfigurasi kampanye yang dapat direproduksi, anggaran, titik pemeriksaan, percobaan ulang, eksekusi.	`dispatchatlas.core`, `dispatchatlas.bench`, `dispatchatlas.solve`.	Paket analisis atau internal runtime situs.
Analisis	`dispatchatlas.analytica`	Statistik, penyaringan pengungkapan, paket bukti, kumpulan data portal, CLI.	`dispatchatlas.core`, ditambah manifes kampanye stabil yang dibaca sebagai data JSON.	Eksekusi kampanye langsung atau internal runtime situs.
Agregat	`dispatchatlas`	Distribusi akar; mengekspos permukaan versi dan menyematkan lima paket melalui extra `all`-nya.	Tidak ada saat runtime; komposisi terjadi melalui extras.	—

📦 Peran paket

dispatchatlas.core adalah batas dalam. Ia mendefinisikan kosakata penjadwalan bersama (ProblemSpec, Schedule, tujuan, kendala), validasi, provenans dan silsilah benih, serialisasi kanonik, dan protokol (BenchmarkProvider, Solver, ExperimentRunner, ResultRepository, DisclosurePolicy, AnalysisExporter) yang diimplementasikan setiap paket luar. Manifesnya mendeklarasikan nol dependensi, sehingga domain tetap dapat diimpor di mana saja.
dispatchatlas.bench mengubah kosakata domain menjadi bukti benchmark: keluarga generator, profil domain, katalog asap dan penuh, metrik karakterisasi, dan matriks sitasi yang mencatat dari mana asumsi tiap keluarga berasal.
dispatchatlas.solve memiliki segala sesuatu yang menghasilkan jadwal: metadata solver dan deskriptor kapabilitas, registry solver, baseline konstruktif, metaheuristik permutasi, keluarga NDSO, operator penjadwalan, dan adapter solver eksak opsional yang dijaga di balik extras.
dispatchatlas.lab menyusun benchmark dan solver menjadi kampanye bertitik-periksa, beranggaran, bercap-lingkungan dengan pengenal eksekusi deterministik, dan memiliki matriks keberlakuan yang merekonsiliasi setiap keluarga terhadap setiap solver. Karena matriks itulah ia satu-satunya paket yang diizinkan melihat core, bench, dan solve bersama: memasangkan ketiganya adalah alasan keberadaannya.
dispatchatlas.analytica membaca direktori kampanye yang selesai — checkpoint.json, plan.json, environment.json, dan baris hasil — dan menghasilkan ringkasan statistik, paket bukti, kerangka laporan, dan kumpulan data portal. Input berbasis manifes menjaga analisis tetap dapat direproduksi hanya dari artefak yang terekam.
dispatchatlas (akar) mengagregasi lima paket untuk instalasi satu perintah dan membawa permukaan versi publik.

🔒 Mengapa arah ditegakkan

Arah hanya-ke-dalam adalah kontrak teruji, bukan konvensi:

Keterujian. Core memvalidasi masalah dan jadwal tanpa mesin solver, kampanye, atau analisis yang terpasang, sehingga uji domain berjalan dengan impor hanya pustaka standar. Bench dan solve diuji terhadap kontrak core tanpa saling menyeret.
Reprodusibilitas. Karena dispatchatlas.analytica mengonsumsi manifes yang terekam alih-alih runtime kampanye langsung, kampanye selesai mana pun dapat dianalisis ulang byte demi byte dari artefaknya.
Rilis independen. Setiap paket dibangun dan menyematkan versinya secara terpisah; perubahan solver tidak dapat diam-diam mengubah perilaku benchmark atau analisis.

Uji batas impor berada di tests/architecture/: test_import_boundaries.py menelusuri setiap berkas sumber paket dengan modul ast dan gagal pada impor mana pun yang melintasi tabel impor-terlarang di atas, dan test_workspace_privacy.py menjaga artefak penelitian privat. AGENTS.md akar (§ Package Boundary Summary) menyatakan arah itu secara kanonis dan CONTRIBUTING.md meneruskannya kepada kontributor; halaman ini adalah pendalaman di atas keduanya, dan setiap pull request ditinjau terhadapnya.

🌐 Permukaan publik

Situs dokumentasi di bawah site/ mengonsumsi data ekspor yang disetujui — paket portal yang difilter pengungkapan dan ringkasan bukti. Ia tidak menjalankan kampanye langsung dan tidak melewati kebijakan pengungkapan.

🛠️ Permukaan tata kelola

tools/ dan CI boleh menginspeksi semua kode paket, artefak build, dan laporan. Mereka menggerbang kualitas dari luar dan tidak pernah menjadi dependensi runtime paket produk.