Aplikasi lama masih melayani antrean. Kamu ingin menggantinya tanpa membawa implementasi lama. Mulai dari pertanyaan kecil: apa yang dikirim operator, apa yang dijawab aplikasi, dan apa yang tetap tersimpan setelah kesalahan?
Di lab ini, kamu mengamati aplikasi antrean loket buatan khusus untuk latihan. Kamu membekukan hasilnya menjadi kontrak. Lalu kamu menguji implementasi pengganti terhadap kontrak itu. Bukan tutorial disassembly, bukan latihan ongkir, dan bukan sampel notes-example.
REA tidak dijalankan dalam lab ini. Tidak ada bypass. Tidak ada keluaran REA. Semua bukti eksekusi berasal dari shell, Python stdlib, dan perilaku aplikasi latihan sendiri.
Pemisahan clean-room adalah praktik pengurangan risiko, bukan jaminan legal. Ini bukan nasihat hukum. Gunakan hanya artefak milik sendiri atau target dengan izin yang jelas. Jangan membawa kredensial, konten proprietary, DRM, atau kontrol akses ke latihan.
1. Pahami empat peran sebelum membuka berkas
| Peran atau artefak | Tugas konkret | Yang boleh diterima |
|---|---|---|
| Observer | Menjalankan aplikasi lama, mencatat input dan output, menetapkan batas | Artefak legacy dan izin target |
| Behavioral spec | Kontrak yang dibekukan sebelum implementasi | Protokol, transkrip, hash, batas pengujian |
| Implementer | Menulis pengganti berdasarkan kontrak | Spec saja, bukan source legacy |
| Compatibility suite | Menilai hasil pengganti terhadap kontrak | Input, stdout, stderr, exit code |
Batas demonstrasi ini: legacy dan pengganti disediakan bersama sebagai contoh pembelajaran. Penulis menyiapkan keduanya. Ini bukan bukti dua penulis independen atau audit clean-room. Runner hanya memisahkan fase observasi dan verifikasi. Ia tidak membatasi akses berkas.
Untuk latihan yang benar-benar memisahkan informasi, jangan buka legacy.py di sesi implementasi. Gunakan dua folder dan dua sesi baru. Sesi kedua jangan diberi riwayat percakapan, akses repository penuh, atau source sesi pertama. Folder saja bukan sandbox. Bila kamu sudah membaca source legacy, kamu tidak bisa mengklaim implementasi berikutnya dibuat tanpa paparan source. Gunakan orang atau sesi implementasi lain yang belum terpapar.
2. Jalankan contoh lengkap dahulu
Semua perintah berikut dijalankan dari root repository. Linux memerlukan bash, python3, mktemp, dan sha256sum yang sudah tersedia. Tidak ada pemasangan paket, jaringan, kredensial, atau hak administrator.
bash scripts/guides/rea-clean-room-lab/run-lab.shRunner membuat folder baru di /tmp/rea-clean-room-lab.*. Ia tidak menimpa kontrak lama atau menghapus foldermu. Di sana tersimpan contract.json. Path ditampilkan saat run agar kamu bisa memeriksanya.
Dijalankan, 13 Oktober 2026: run contoh menghasilkan tujuh baris PASS dan ringkasan berikut. Jumlah dihitung dari record kontrak oleh suite, bukan ditulis manual sebagai klaim kelulusan.
SUMMARY 7/7 PASS; 0 FAILBukti repository tersimpan di docs/guide-source-ledgers/rea-lab-rekonstruksi-aplikasi-lab.txt. Salinan kontraknya ada di docs/guide-source-ledgers/rea-lab-rekonstruksi-aplikasi-contract.json. Bukti ini milik lab antrean, bukan laporan REA.
3. Amati alur operator, bukan implementasinya
Legacy menerima satu objek JSON per baris stdin. Satu proses mewakili satu sesi loket. Operator menambahkan nama dengan enqueue, melihat antrean dengan peek, lalu memanggil orang berikutnya dengan serve.
printf '%s\n' \
'{"op":"enqueue","name":" Mira "}' \
'{"op":"enqueue","name":"Budi"}' \
'{"op":"serve"}' \
'{"op":"peek"}' \
| python3 scripts/guides/rea-clean-room-lab/legacy.pyRespons yang harus kamu cocokkan di layar:
{"queued":1}
{"queued":2}
{"served":"Mira"}
{"waiting":["Budi"]}Jangan langsung menebak struktur datanya. Yang terlihat adalah nama dipangkas, jumlah antrean bertambah, orang pertama dilayani lebih dahulu, dan orang berikutnya tetap menunggu. Coba kesalahan juga. Apakah nama kosong ditolak? Apakah antrean tetap utuh setelah JSON rusak?
4. Bekukan tujuh transkrip sebagai kontrak
Fase observer memakai tujuh skenario terdefinisi di suite.py. Setiap skenario menjalankan proses legacy baru. Di dalam satu skenario, beberapa permintaan bisa berbagi state. Suite memastikan observasi legacy cocok dengan fixture yang ditinjau, lalu menyimpan stdout, stderr, exit code, dan SHA-256 legacy ke kontrak.
observer=$(mktemp -d /tmp/rea-observer.XXXXXXXX)
bash scripts/guides/rea-clean-room-lab/run-lab.sh observe "$observer"
python3 -m json.tool "$observer/contract.json"
sha256sum "$observer/contract.json"Catat hash terakhir bersama keputusan menerima spec. Jangan ubah expected output untuk membuat pengganti lulus. Perubahan kontrak memerlukan observasi baru dan peninjauan ulang.
| ID | Perilaku yang diuji | Alasan penting bagi operator |
|---|---|---|
| 1 | peek pada antrean awal menghasilkan daftar kosong |
Loket mulai tanpa pelanggan |
| 2 | enqueue memangkas spasi dan mengembalikan jumlah |
Nama tampil bersih dan penambahan terkonfirmasi |
| 3 | Dua nama, serve, lalu peek mempertahankan FIFO |
Pelanggan tidak tertukar |
| 4 | serve saat kosong memberi error empty tanpa mutasi |
Operator bisa melanjutkan sesi |
| 5 | Nama kosong dan angka memberi error name, state bertahan |
Input salah tidak menghilangkan pelanggan |
| 6 | Operasi reset memberi error op, state bertahan |
Perintah asing tidak diam-diam menghapus antrean |
| 7 | JSON rusak dan array memberi error, lalu serve pulih |
Satu permintaan buruk tidak mematikan alur |
Kontrak membandingkan teks stdout yang didekode sebagai UTF-8 secara persis setelah normalisasi newline oleh mode teks Python, termasuk newline, urutan kunci, dan format JSON ringkas. Ini bukan perbandingan byte biner. stderr harus kosong dan exit code harus 0 pada setiap skenario. Error aplikasi dilaporkan sebagai JSON di stdout, bukan crash. EOF mengakhiri sesi. State hanya berlaku di proses tersebut.
Inferensi: trace nomor 3 mendukung aturan FIFO pada urutan yang diuji. Ia bukan pembuktian semua kemungkinan antrean.
Unknown: persistensi lintas proses, konkurensi, kapasitas maksimum, nama duplikat, normalisasi Unicode, dan kinerja pada input besar belum diuji. Tidak ada klaim kompatibilitas untuk bagian itu. Jangan menambah database atau deduplikasi berdasarkan asumsi.
5. Serahkan spec, bukan source
Siapkan folder implementer dari sesi observer. Salin hanya kontraknya. Perintah cp -n tidak menimpa berkas yang sudah ada.
implementer=$(mktemp -d /tmp/rea-implementer.XXXXXXXX)
cp -n "$observer/contract.json" "$implementer/contract.json"
printf 'Folder sesi implementasi: %s\n' "$implementer"
sha256sum "$implementer/contract.json"Hash salinan harus sama dengan hash yang kamu bekukan. Buka sesi baru dengan folder tersebut sebagai konteks. Jangan beri akses ke folder observer atau repository ini. Sampaikan instruksi berikut:
Bangun replacement.py hanya dari contract.json di folder ini.
Python stdlib saja. Baca JSON per baris stdin, tulis satu JSON ringkas
per baris stdout. State berlaku selama satu proses. EOF mengakhiri sesi.
Cocokkan stdout, stderr, dan exit code setiap trace.
Jangan membuka source legacy atau mencari implementasi aslinya.
Laporkan perilaku yang belum ditentukan. Jangan mengisi unknown
dengan fitur baru. Jangan mengubah contract.json.Pengganti contoh memakai daftar dan pengambilan elemen pertama. Legacy memakai deque. Perbedaan struktur internal bukan target uji. Targetnya adalah kontrak operator. Ini penjelasan contoh setelah implementasi, bukan bahan handoff ke implementer.
6. Periksa pengganti tanpa menjalankan legacy lagi
Untuk contoh pengganti yang sudah tersedia, fase berikut hanya membaca kontrak dan menjalankan replacement.py. Ia tidak membaca atau menjalankan legacy:
bash scripts/guides/rea-clean-room-lab/run-lab.sh verify "$observer"Untuk hasil sesi implementasimu sendiri, bawa suite ke folder implementer setelah implementasi selesai. Mode verify tidak memakai fixture pengamatan di suite; expected output dibaca dari kontrak beku. Source legacy tidak ikut disalin.
cp -n scripts/guides/rea-clean-room-lab/suite.py "$implementer/suite.py"
python3 "$implementer/suite.py" verify "$implementer"Suite mencari replacement.py di folder yang sama dengan suite.py. Kontrak harus berisi tepat tujuh record dengan ID 1 sampai 7. Kegagalan kompatibilitas menghasilkan FAIL, rincian actual/expected, dan exit code 1. Timeout atau kegagalan runner juga tidak dianggap lulus.
Saat terjadi FAIL, cocokkan permintaan terakhir, respons, dan state sesudahnya. Misalnya, bila error nama kosong membuat pelanggan sebelumnya hilang, perbaiki jalur validasi sebelum mutasi. Jangan melonggarkan spec hanya karena implementasi baru lebih nyaman.
Dijalankan: pengganti contoh lulus tujuh skenario. Unknown: itu tidak membuktikan kompatibilitas penuh di luar tujuh trace. Untuk migrasi nyata, pisahkan kasus tambahan ke rencana pengujian lanjutan. Jangan menyebutnya telah diuji di lab ini.
7. Di mana REA bisa masuk, jika diizinkan?
Lab ini sengaja cukup dengan observasi proses lokal. Tidak perlu dekompiler untuk menjawab tujuh pertanyaan tadi. Jika artefak lain membuat jalur perilaku sulit dipahami, peran observer dapat mempertimbangkan analisis REA yang diizinkan. Jangan kirim pseudocode atau source hasil analisis ke implementer.
Dokumentasi resmi, bukan hasil lab: dokumen reconstruction readiness pada commit a0317cf732b3addefad5ac3b234db1e044e3351d menyatakan status fail, unknown, unsupported, truncated, dan skipped tidak digabung menjadi pass. Pakai prinsip itu untuk menjaga batas bukti. Dokumen tersebut bukan sertifikat legal clean-room dan bukan bukti bahwa lab ini menjalankan REA.
Tidak ada video yang disisipkan. Riset video pendukung bersifat independen, bukan sumber resmi REA. Lab ini membutuhkan transkrip lokal yang bisa kamu ulang, bukan demonstrasi setup lain.
8. Selesai ketika bukti bisa diserahkan
Pegang empat artefak: identitas legacy, kontrak yang dibekukan, pengganti, dan output tujuh pemeriksaan. Sertakan batasnya. Orang berikutnya harus bisa menjalankan ulang suite tanpa membaca source legacy.
Hasilnya bukan salinan implementasi. Hasilnya pengganti yang cocok dengan perilaku teramati dalam cakupan kecil, disertai daftar hal yang belum diketahui. Itu titik awal yang lebih jujur untuk rekonstruksi aplikasi.