prpm-dbp 0.16.0 → 0.18.1

package/SKILL.md

@@ -9,6 +9,83 @@ Sumber kebenaran tunggal untuk ejaan BM dan Jawi ialah PRPM DBP, bukan ingatan m
 
 Model boleh hasilkan Jawi yang nampak betul tetapi salah, dan pembaca tidak dapat kesan. Skill ini tukar tekaan jadi semakan.
 
+## Sebelum menghantar apa-apa
+
+Jalankan `npx prpm-dbp gate <fail> --luar-talian` ke atas **keseluruhan teks**. Bukan sebahagian. Bukan perkataan yang anda rasa berisiko.
+
+Ejaan yang salah ialah tepat ejaan yang anda **tidak** syak. Kalau anda syak, anda sudah menyemaknya.
+
+Ini termasuk ejaan yang anda tulis dalam **kod, ujian dan dokumentasi**, bukan hanya dalam teks untuk pengguna. Semasa membina pakej ini sendiri, satu nilai Jawi ditulis ke dalam ujian daripada ingatan tanpa disemak. Nilainya kebetulan betul. Kebetulan bukan proses.
+
+**Apa yang berlaku apabila langkah ini dilangkau:**
+
+Satu agen menggunakan skill ini sepanjang sesi penuh untuk menukar Jawi ke Rumi, kemudian menghantar 549 kad RPH Pendidikan Islam ke pangkalan data produksi dengan **273 ejaan yang salah**.
+
+```
+pusingan 1   sunnah x206, hadith x16, fardhu x2        -> masuk produksi
+pusingan 2   tayammum, dhuha, qadha, redha, iddah x90  -> masuk produksi
+```
+
+Semuanya kata lazim dalam bahan Pendidikan Islam. Setiap satu ada jawapan tegas dalam PRPM: `sunnah` ialah rujukan silang ke `sunah`, `hadith` sepatutnya `hadis`, `fardhu` sepatutnya `fardu`, `tayammum` sepatutnya `tayamum`, `dhuha` sepatutnya `duha`, `qadha` sepatutnya `qada`.
+
+Alat untuk menangkap kesemuanya ada di tangan agen itu sepanjang masa. Ia tidak pernah dijalankan ke atas teks Rumi keluarannya sendiri. Kedua-dua pusingan ditemui kerana **pengguna bertanya**, bukan kerana proses menangkapnya.
+
+`gate` keluar dengan kod 1 apabila ada ralat, jadi ia boleh dipasang sebagai hook atau langkah CI. Peraturan yang bergantung pada agen ingat sendiri akan gagal, dan gagal secara senyap.
+
+## Kuatkuasa automatik
+
+```bash
+npx prpm-dbp install --hook
+```
+
+Memasang hook PostToolUse yang menjalankan `gate --luar-talian` ke atas setiap fail `.md`, `.txt` atau `.json` yang ditulis atau disunting. Ia **melaporkan** ralat kepada agen tanpa menyekat tulisan: menyekat atas kamus yang tidak lengkap akan menghalang kerja yang sah, manakala melaporkan sudah memadai kerana agen membaca output hook.
+
+Untuk menampal sendiri: `npx prpm-dbp hook-json`.
+
+Panaskan cache **sekali** semasa pemasangan, bukan semasa gate berjalan:
+
+```bash
+npx prpm-dbp warm kosa-kata-projek.txt
+```
+
+Gate atas cache panas mengambil 0.19 saat bagi 406 perkataan. Itu cukup pantas untuk setiap penyuntingan. Gate yang perlahan akan dimatikan orang.
+
+## Tiga keadaan gate, bukan dua
+
+| Medan | Maksud | Kesan |
+|---|---|---|
+| `lulusDbp` | ada dalam PRPM, ejaan padan | — |
+| `ralat` | ada dalam PRPM dengan ejaan lain, entri rujukan silang `®`, atau tiada dalam PRPM mahupun dataset | **exit 1** |
+| `tidakDapatDisahkan` | tiada dalam cache, nama khas, akronim, atau tiada entri PRPM tetapi wujud dalam dataset | dilapor; exit 1 jika melebihi `--ambang` |
+
+`tidakDapatDisahkan` **tidak pernah lulus senyap**. Gate yang lulus atas cache sejuk memberi jaminan palsu, dan itu lebih bahaya daripada tiada gate. Gunakan `--ambang 10` supaya cache sejuk menggagalkan gate.
+
+PRPM tiada entri untuk kata tugas paling asas: `dan`, `di`, `ke`, `yang`, `atau`. Menandakannya sebagai ralat menjadikan gate mustahil dipakai. Pembezanya bersumber, bukan senarai putih: kata tugas itu **semua** wujud dalam dataset, manakala `hadith`, `fardhu`, `tayammum`, `dhuha`, `qadha`, `redha` dan `iddah` **tiada satu pun**.
+
+## Prosedur wajib
+
+Ikut ini setiap kali, jangan langkau langkah.
+
+**Menulis Jawi daripada Rumi:**
+
+1. `npx prpm-dbp jawi <fail> --luar-talian --homograf --json`
+2. Baca `belumDisahkan` dan `namaKhas`. Jangan reka ejaan untuknya. Sahkan dengan `lookup`, atau tanya pengguna, atau tandakan dalam hasil akhir.
+3. Baca `mencurigakan`. Setiap satu bermakna PRPM sendiri mungkin tersilap. Semak di pautan yang diberi sebelum menggunakannya.
+4. Baca `homograf`. Beritahu pengguna perkataan mana yang akan taksa apabila dibaca.
+5. Laporkan `semuanyaDbp`. Jika `false`, nyatakan bahagian mana bukan daripada sumber rasmi.
+
+**Merumikan daripada Jawi:**
+
+1. `npx prpm-dbp rumi <fail> --pilih --konteks --json`
+2. Untuk **setiap** item dalam `kabur`: baca ayat yang mengandunginya, baca makna setiap calon, tentukan yang mana sesuai.
+3. Jika `dipilih` salah bagi ayat itu, **gantikan** dalam hasil akhir. Kekerapan kalah kepada konteks.
+4. Nyatakan kepada pengguna berapa banyak kekaburan wujud dan mana yang anda ubah.
+5. `tidakDikenali` bermakna perkataan itu tiada dalam cache. Jalankan `warm` di luar talian, bukan tinggalkan bertanda.
+
+**Berhenti dan tanya pengguna apabila:** ejaan `mencurigakan` mengubah makna, nama khas tiada rujukan bertulis, atau dua calon sama-sama munasabah dalam ayat itu.
+
+Semua perintah menyokong `--json`, jadi langkah di atas boleh dibuat secara berulang tanpa menghurai teks.
+
 ## Peraturan
 
 0. **Semak ejaan ikut DBP, bukan ikut ingatan.** Ini peraturan pertama kerana ia yang paling kerap dilanggar. Perkataan yang anda "tahu" ejaannya masih perlu disemak. Contoh sebenar daripada penggunaan: `sunah` ialah `سنة` tetapi `sunat` ialah `سونت`; `bena` langsung tiada ejaan Jawi dalam PRPM walaupun ia perkataan yang sah; `salat` hanyalah rujukan silang kepada `solat`. Tiada satu pun daripada perbezaan ini boleh diteka daripada bentuk Rumi. Jalankan `lookup` atau `jawi`, jangan tulis daripada ingatan.
@@ -160,6 +237,83 @@ Ejaan yang disimpan begini ditandakan datang daripada pengguna, bukan daripada D
 
 Bagi nama berasal Arab, ejaan Jawinya memang ejaan Arab asal, jadi ia nampak seperti dikekalkan. Bagi nama bukan Arab ia ditransliterasi penuh: `Kuala Lumpur` menjadi `کوالا لومڤور`.
 
+## Sebelum menghantar apa-apa
+
+Jalankan `npx prpm-dbp gate <fail> --luar-talian` ke atas **keseluruhan teks**. Bukan sebahagian. Bukan perkataan yang anda rasa berisiko.
+
+Ejaan yang salah ialah tepat ejaan yang anda **tidak** syak. Kalau anda syak, anda sudah menyemaknya.
+
+Ini termasuk ejaan yang anda tulis dalam **kod, ujian dan dokumentasi**, bukan hanya dalam teks untuk pengguna. Semasa membina pakej ini sendiri, satu nilai Jawi ditulis ke dalam ujian daripada ingatan tanpa disemak. Nilainya kebetulan betul. Kebetulan bukan proses.
+
+**Apa yang berlaku apabila langkah ini dilangkau:**
+
+Satu agen menggunakan skill ini sepanjang sesi penuh untuk menukar Jawi ke Rumi, kemudian menghantar 549 kad RPH Pendidikan Islam ke pangkalan data produksi dengan **273 ejaan yang salah**.
+
+```
+pusingan 1   sunnah x206, hadith x16, fardhu x2        -> masuk produksi
+pusingan 2   tayammum, dhuha, qadha, redha, iddah x90  -> masuk produksi
+```
+
+Semuanya kata lazim dalam bahan Pendidikan Islam. Setiap satu ada jawapan tegas dalam PRPM: `sunnah` ialah rujukan silang ke `sunah`, `hadith` sepatutnya `hadis`, `fardhu` sepatutnya `fardu`, `tayammum` sepatutnya `tayamum`, `dhuha` sepatutnya `duha`, `qadha` sepatutnya `qada`.
+
+Alat untuk menangkap kesemuanya ada di tangan agen itu sepanjang masa. Ia tidak pernah dijalankan ke atas teks Rumi keluarannya sendiri. Kedua-dua pusingan ditemui kerana **pengguna bertanya**, bukan kerana proses menangkapnya.
+
+`gate` keluar dengan kod 1 apabila ada ralat, jadi ia boleh dipasang sebagai hook atau langkah CI. Peraturan yang bergantung pada agen ingat sendiri akan gagal, dan gagal secara senyap.
+
+## Kuatkuasa automatik
+
+```bash
+npx prpm-dbp install --hook
+```
+
+Memasang hook PostToolUse yang menjalankan `gate --luar-talian` ke atas setiap fail `.md`, `.txt` atau `.json` yang ditulis atau disunting. Ia **melaporkan** ralat kepada agen tanpa menyekat tulisan: menyekat atas kamus yang tidak lengkap akan menghalang kerja yang sah, manakala melaporkan sudah memadai kerana agen membaca output hook.
+
+Untuk menampal sendiri: `npx prpm-dbp hook-json`.
+
+Panaskan cache **sekali** semasa pemasangan, bukan semasa gate berjalan:
+
+```bash
+npx prpm-dbp warm kosa-kata-projek.txt
+```
+
+Gate atas cache panas mengambil 0.19 saat bagi 406 perkataan. Itu cukup pantas untuk setiap penyuntingan. Gate yang perlahan akan dimatikan orang.
+
+## Tiga keadaan gate, bukan dua
+
+| Medan | Maksud | Kesan |
+|---|---|---|
+| `lulusDbp` | ada dalam PRPM, ejaan padan | — |
+| `ralat` | ada dalam PRPM dengan ejaan lain, entri rujukan silang `®`, atau tiada dalam PRPM mahupun dataset | **exit 1** |
+| `tidakDapatDisahkan` | tiada dalam cache, nama khas, akronim, atau tiada entri PRPM tetapi wujud dalam dataset | dilapor; exit 1 jika melebihi `--ambang` |
+
+`tidakDapatDisahkan` **tidak pernah lulus senyap**. Gate yang lulus atas cache sejuk memberi jaminan palsu, dan itu lebih bahaya daripada tiada gate. Gunakan `--ambang 10` supaya cache sejuk menggagalkan gate.
+
+PRPM tiada entri untuk kata tugas paling asas: `dan`, `di`, `ke`, `yang`, `atau`. Menandakannya sebagai ralat menjadikan gate mustahil dipakai. Pembezanya bersumber, bukan senarai putih: kata tugas itu **semua** wujud dalam dataset, manakala `hadith`, `fardhu`, `tayammum`, `dhuha`, `qadha`, `redha` dan `iddah` **tiada satu pun**.
+
+## Prosedur wajib
+
+Ikut ini setiap kali, jangan langkau langkah.
+
+**Menulis Jawi daripada Rumi:**
+
+1. `npx prpm-dbp jawi <fail> --luar-talian --homograf --json`
+2. Baca `belumDisahkan` dan `namaKhas`. Jangan reka ejaan untuknya. Sahkan dengan `lookup`, atau tanya pengguna, atau tandakan dalam hasil akhir.
+3. Baca `mencurigakan`. Setiap satu bermakna PRPM sendiri mungkin tersilap. Semak di pautan yang diberi sebelum menggunakannya.
+4. Baca `homograf`. Beritahu pengguna perkataan mana yang akan taksa apabila dibaca.
+5. Laporkan `semuanyaDbp`. Jika `false`, nyatakan bahagian mana bukan daripada sumber rasmi.
+
+**Merumikan daripada Jawi:**
+
+1. `npx prpm-dbp rumi <fail> --pilih --konteks --json`
+2. Untuk **setiap** item dalam `kabur`: baca ayat yang mengandunginya, baca makna setiap calon, tentukan yang mana sesuai.
+3. Jika `dipilih` salah bagi ayat itu, **gantikan** dalam hasil akhir. Kekerapan kalah kepada konteks.
+4. Nyatakan kepada pengguna berapa banyak kekaburan wujud dan mana yang anda ubah.
+5. `tidakDikenali` bermakna perkataan itu tiada dalam cache. Jalankan `warm` di luar talian, bukan tinggalkan bertanda.
+
+**Berhenti dan tanya pengguna apabila:** ejaan `mencurigakan` mengubah makna, nama khas tiada rujukan bertulis, atau dua calon sama-sama munasabah dalam ayat itu.
+
+Semua perintah menyokong `--json`, jadi langkah di atas boleh dibuat secara berulang tanpa menghurai teks.
+
 ## Peraturan Pedoman DBP
 
 Satu fail sahaja dalam pakej ini **menjana** ejaan dan bukan mencarinya: `src/pedoman.js`. Ia dibenarkan kerana setiap peraturan di dalamnya datang daripada *Pedoman Umum Ejaan Jawi Bahasa Melayu* terbitan DBP, dan dirujuk pada seksyennya.
@@ -271,6 +425,83 @@ Dua puluh dua kes kabur yang tinggal itu sah: `قلقله` boleh dibaca `qalqala
 
 **Sifar perkataan hilang atau rosak.**
 
+## Sebelum menghantar apa-apa
+
+Jalankan `npx prpm-dbp gate <fail> --luar-talian` ke atas **keseluruhan teks**. Bukan sebahagian. Bukan perkataan yang anda rasa berisiko.
+
+Ejaan yang salah ialah tepat ejaan yang anda **tidak** syak. Kalau anda syak, anda sudah menyemaknya.
+
+Ini termasuk ejaan yang anda tulis dalam **kod, ujian dan dokumentasi**, bukan hanya dalam teks untuk pengguna. Semasa membina pakej ini sendiri, satu nilai Jawi ditulis ke dalam ujian daripada ingatan tanpa disemak. Nilainya kebetulan betul. Kebetulan bukan proses.
+
+**Apa yang berlaku apabila langkah ini dilangkau:**
+
+Satu agen menggunakan skill ini sepanjang sesi penuh untuk menukar Jawi ke Rumi, kemudian menghantar 549 kad RPH Pendidikan Islam ke pangkalan data produksi dengan **273 ejaan yang salah**.
+
+```
+pusingan 1   sunnah x206, hadith x16, fardhu x2        -> masuk produksi
+pusingan 2   tayammum, dhuha, qadha, redha, iddah x90  -> masuk produksi
+```
+
+Semuanya kata lazim dalam bahan Pendidikan Islam. Setiap satu ada jawapan tegas dalam PRPM: `sunnah` ialah rujukan silang ke `sunah`, `hadith` sepatutnya `hadis`, `fardhu` sepatutnya `fardu`, `tayammum` sepatutnya `tayamum`, `dhuha` sepatutnya `duha`, `qadha` sepatutnya `qada`.
+
+Alat untuk menangkap kesemuanya ada di tangan agen itu sepanjang masa. Ia tidak pernah dijalankan ke atas teks Rumi keluarannya sendiri. Kedua-dua pusingan ditemui kerana **pengguna bertanya**, bukan kerana proses menangkapnya.
+
+`gate` keluar dengan kod 1 apabila ada ralat, jadi ia boleh dipasang sebagai hook atau langkah CI. Peraturan yang bergantung pada agen ingat sendiri akan gagal, dan gagal secara senyap.
+
+## Kuatkuasa automatik
+
+```bash
+npx prpm-dbp install --hook
+```
+
+Memasang hook PostToolUse yang menjalankan `gate --luar-talian` ke atas setiap fail `.md`, `.txt` atau `.json` yang ditulis atau disunting. Ia **melaporkan** ralat kepada agen tanpa menyekat tulisan: menyekat atas kamus yang tidak lengkap akan menghalang kerja yang sah, manakala melaporkan sudah memadai kerana agen membaca output hook.
+
+Untuk menampal sendiri: `npx prpm-dbp hook-json`.
+
+Panaskan cache **sekali** semasa pemasangan, bukan semasa gate berjalan:
+
+```bash
+npx prpm-dbp warm kosa-kata-projek.txt
+```
+
+Gate atas cache panas mengambil 0.19 saat bagi 406 perkataan. Itu cukup pantas untuk setiap penyuntingan. Gate yang perlahan akan dimatikan orang.
+
+## Tiga keadaan gate, bukan dua
+
+| Medan | Maksud | Kesan |
+|---|---|---|
+| `lulusDbp` | ada dalam PRPM, ejaan padan | — |
+| `ralat` | ada dalam PRPM dengan ejaan lain, entri rujukan silang `®`, atau tiada dalam PRPM mahupun dataset | **exit 1** |
+| `tidakDapatDisahkan` | tiada dalam cache, nama khas, akronim, atau tiada entri PRPM tetapi wujud dalam dataset | dilapor; exit 1 jika melebihi `--ambang` |
+
+`tidakDapatDisahkan` **tidak pernah lulus senyap**. Gate yang lulus atas cache sejuk memberi jaminan palsu, dan itu lebih bahaya daripada tiada gate. Gunakan `--ambang 10` supaya cache sejuk menggagalkan gate.
+
+PRPM tiada entri untuk kata tugas paling asas: `dan`, `di`, `ke`, `yang`, `atau`. Menandakannya sebagai ralat menjadikan gate mustahil dipakai. Pembezanya bersumber, bukan senarai putih: kata tugas itu **semua** wujud dalam dataset, manakala `hadith`, `fardhu`, `tayammum`, `dhuha`, `qadha`, `redha` dan `iddah` **tiada satu pun**.
+
+## Prosedur wajib
+
+Ikut ini setiap kali, jangan langkau langkah.
+
+**Menulis Jawi daripada Rumi:**
+
+1. `npx prpm-dbp jawi <fail> --luar-talian --homograf --json`
+2. Baca `belumDisahkan` dan `namaKhas`. Jangan reka ejaan untuknya. Sahkan dengan `lookup`, atau tanya pengguna, atau tandakan dalam hasil akhir.
+3. Baca `mencurigakan`. Setiap satu bermakna PRPM sendiri mungkin tersilap. Semak di pautan yang diberi sebelum menggunakannya.
+4. Baca `homograf`. Beritahu pengguna perkataan mana yang akan taksa apabila dibaca.
+5. Laporkan `semuanyaDbp`. Jika `false`, nyatakan bahagian mana bukan daripada sumber rasmi.
+
+**Merumikan daripada Jawi:**
+
+1. `npx prpm-dbp rumi <fail> --pilih --konteks --json`
+2. Untuk **setiap** item dalam `kabur`: baca ayat yang mengandunginya, baca makna setiap calon, tentukan yang mana sesuai.
+3. Jika `dipilih` salah bagi ayat itu, **gantikan** dalam hasil akhir. Kekerapan kalah kepada konteks.
+4. Nyatakan kepada pengguna berapa banyak kekaburan wujud dan mana yang anda ubah.
+5. `tidakDikenali` bermakna perkataan itu tiada dalam cache. Jalankan `warm` di luar talian, bukan tinggalkan bertanda.
+
+**Berhenti dan tanya pengguna apabila:** ejaan `mencurigakan` mengubah makna, nama khas tiada rujukan bertulis, atau dua calon sama-sama munasabah dalam ayat itu.
+
+Semua perintah menyokong `--json`, jadi langkah di atas boleh dibuat secara berulang tanpa menghurai teks.
+
 ## Peraturan yang sengaja TIDAK dilaksanakan
 
 | Seksyen | Sebab |
@@ -357,6 +588,61 @@ Empat kelas berasingan, kerana menggabungkannya menenggelamkan yang penting:
 
 Penambahan huruf vokal **tidak** dikira ejaan lama. Kalau kehadiran `ي` diabaikan, `بينا` (bina) dan `بنا` (bena) akan kelihatan sama, sedangkan itu dua perkataan berlainan.
 
+## Ejaan bukan piawai DBP
+
+Dokumen kurikulum Malaysia kerap menggunakan ortografi Jawi yang berbeza daripada piawai DBP. Pasangan yang disahkan daripada DSKP Pendidikan Islam KPM sebenar:
+
+| Rumi | DBP | DSKP | Beza |
+|---|---|---|---|
+| surah | `سورة` | `سوره` | ta marbutah jadi ha |
+| iktibar | `اعتبار` | `اعتبر` | alif digugurkan |
+| bersifat | `برصيفت` | `برصفة` | ya digugurkan, ta marbutah |
+| dalil | `دليل` | `داليل` | alif ditambah |
+| syirik | `شيريک` | `شرك` | ya digugurkan, kaf Arab |
+
+Kesemuanya berbeza hanya pada huruf vokal dan bentuk huruf, bukan pada rangka konsonan. `--rangka` memadan rangka itu:
+
+```
+$ npx prpm-dbp rumi dskp.txt --luar-talian --rangka
+ejaan bukan piawai DBP (209):
+  اعتبر -> iktibar  [DBP eja: اعتبار]
+  سوره  -> surah    [DBP eja: سورة]
+  کتب   -> kitab|katib|kutub  (rangka sama, PILIH ikut konteks)
+```
+
+Diukur pada 168 baris DSKP sebenar: token yang langsung tidak dikenali turun daripada 100 kepada 47.
+
+**Ini lapisan terakhir dan ia LOSSY.** 29% rangka dikongsi lebih daripada satu perkataan, purata 4.1 calon. Ia hanya digunakan selepas padanan tepat gagal, hasilnya sentiasa berlabel `ejaanBukanPiawai` berserta ejaan DBP untuk perbandingan, dan ia **tidak pernah memilih sendiri** apabila calon berbilang.
+
+Kegunaannya bukan menjadikan alat lebih longgar. Ia membezakan **"ini surah, cuma dieja lain"** daripada **"saya tidak kenal benda ini"** — dua keadaan yang dahulu keluar sama sebagai `«...»`.
+
+## Kekaburan dalam teks domain
+
+`--pilih` menggunakan kekerapan korpus. Dalam teks am ia betul hampir sentiasa. Dalam **teks domain ia gagal tepat di tempat paling penting**: setiap istilah khusus kalah kepada kata lazim yang berkongsi rangka konsonan.
+
+Diukur pada DSKP KKQ/PQS: salah untuk 5 daripada 16 pasangan taksa, dan kelima-limanya ialah inti pelajaran.
+
+```
+اسم  -> asam    patut isim      "hamzah wasal pada kalimah asam dan faal"
+فعل  -> faal    patut fiil
+رسم  -> rasam   patut Rasm (Uthmani)
+سنة  -> sanat   patut sunah
+```
+
+Gunakan glosari domain. Ia **mengatasi segalanya**, termasuk lapisan 1:
+
+```bash
+npx prpm-dbp rumi dskp.txt --pilih --glosari istilah-kkq.json
+```
+
+```json
+{ "اسم": "isim", "فعل": "fiil", "رسم": "rasm", "سنة": "sunah" }
+```
+
+Setiap penggunaan direkod dalam medan `dariGlosari`, jadi ia boleh diaudit. Bina glosari itu sekali untuk domain anda; ia lebih murah daripada membetulkan output berulang kali, dan ia menjadi rekod: siapa membenarkan istilah apa.
+
+Kekerapan kekal sebagai pemecah seri sahaja, dan setiap keputusan tetap dilapor dalam `kabur` untuk semakan.
+
 ## Rantai kepercayaan
 
 Setiap ejaan Jawi yang dikeluarkan membawa asal-usulnya. Jangan runtuhkan lapisan ini.

package/bin/cli.js

@@ -2,11 +2,12 @@
 import { readFile } from 'node:fs/promises'
 import process from 'node:process'
 
-import { pasangSkill } from '../src/install.js'
+import { HOOK, pasangHook, pasangSkill } from '../src/install.js'
 import { banding, cariKamus } from '../src/kamus.js'
 import { keJawi, keRumi, semakJawi } from '../src/tukar.js'
 import { huraiTsv, muatDataset, simpanDataset } from '../src/dataset.js'
 import { NAMA_PATH, muatNama, tambahNama } from '../src/nama.js'
+import { gate, kodKeluar } from '../src/gate.js'
 import {
   CACHE_PATH,
   auditJawi,
@@ -29,15 +30,23 @@ const BANTUAN = `prpm-dbp — semak Bahasa Melayu dan Jawi terhadap PRPM DBP
   npx prpm-dbp import-tsv <fail.tsv>     import dataset rumi<TAB>jawi (dilabel bukan DBP)
   npx prpm-dbp nama <rumi> <jawi>        sahkan satu nama khas (tokoh, surah, tempat)
   npx prpm-dbp nama                      senaraikan nama khas yang disahkan
+  npx prpm-dbp gate <fail...>            semakan boleh GAGAL untuk hook dan CI
+                                        exit 0 bersih, exit 1 ada ralat
   npx prpm-dbp banding <kata...>         silang semak PRPM lawan KamusDBP
   npx prpm-dbp cache [--buang <kata>]    status cache
   npx prpm-dbp install [--link]          pasang sebagai Claude Code skill
+  npx prpm-dbp install --hook            pasang hook PostToolUse yang jalankan gate
+  npx prpm-dbp hook-json                 papar blok settings.json untuk ditampal sendiri
 
 Pilihan: --refresh  --had <n>  --delay <ms>  --json  --cepat
          --pedoman       jana imbuhan ikut peraturan DBP (88-98% tepat, hasil ditanda)
          --luar-talian   jangan sentuh rangkaian langsung (wajib untuk laluan permintaan app)
          --homograf      tandakan perkataan yang ejaan Jawinya dikongsi perkataan lain
          --konteks       papar ayat dan makna setiap calon bagi kekaburan (rumi)
+         --rangka        padan ejaan bukan piawai melalui rangka konsonan (berlabel)
+         --glosari <fail> rumi: glosari domain {jawi: rumi} yang mengatasi segalanya
+         --ambang <n>    gate: exit 1 jika tidakDapatDisahkan melebihi n peratus
+         --abai <fail>   gate: senarai nama khas/istilah yang sudah diisytihar
          --pilih         pilih calon paling lazim supaya teks boleh terus dibaca;
                          setiap pilihan disenaraikan untuk disemak ikut konteks
 
@@ -52,12 +61,17 @@ function huraiArgs(argv) {
     if (a === '--refresh') pilihan.refresh = true
     else if (a === '--json') pilihan.json = true
     else if (a === '--link') pilihan.link = true
+    else if (a === '--hook') pilihan.hook = true
     else if (a === '--cepat') pilihan.cepat = true
     else if (a === '--pedoman') pilihan.pedoman = true
     else if (a === '--luar-talian') pilihan.luarTalian = true
     else if (a === '--homograf') pilihan.homograf = true
     else if (a === '--konteks') pilihan.konteks = true
     else if (a === '--pilih') pilihan.pilih = true
+    else if (a === '--rangka') pilihan.rangka = true
+    else if (a === '--ambang') pilihan.ambang = Number(argv[++i])
+    else if (a === '--abai') pilihan.abai = argv[++i]
+    else if (a === '--glosari') pilihan.glosari = argv[++i]
     else if (a === '--jenis') pilihan.jenis = argv[++i]
     else if (a === '--had') pilihan.had = Number(argv[++i])
     else if (a === '--delay') pilihan.delay = Number(argv[++i])
@@ -83,10 +97,20 @@ async function main() {
   }
 
   if (perintah === 'install') {
+    if (pilihan.hook) {
+      keluar(await pasangHook())
+      return
+    }
     keluar(await pasangSkill({ link: pilihan.link }))
     return
   }
 
+  if (perintah === 'hook-json') {
+    // Blok siap salin untuk pengguna yang mahu menampal sendiri.
+    keluar({ hooks: { PostToolUse: [HOOK] } })
+    return
+  }
+
   const cache = await loadCache()
   const opts = {
     refresh: pilihan.refresh,
@@ -226,6 +250,8 @@ async function main() {
       const h = keRumi(teks, cache, {
         dataset: await muatDataset(),
         pilihLazim: pilihan.pilih,
+        padanRangka: pilihan.rangka,
+        glosari: pilihan.glosari ? JSON.parse(await readFile(pilihan.glosari, 'utf8')) : null,
       })
       if (pilihan.json) { keluar(h); break }
       console.log(h.teks)
@@ -255,6 +281,17 @@ async function main() {
           }
         }
       }
+      if (h.ejaanBukanPiawai?.length) {
+        const tunggal = h.ejaanBukanPiawai.filter((x) => x.calon.length === 1)
+        const banyak = h.ejaanBukanPiawai.filter((x) => x.calon.length > 1)
+        console.error(`\nejaan bukan piawai DBP (${h.ejaanBukanPiawai.length}):`)
+        for (const x of tunggal.slice(0, 20)) {
+          console.error(`  ${x.jawi} -> ${x.calon[0].rumi}  [DBP eja: ${x.calon[0].jawiDbp}]`)
+        }
+        for (const x of banyak.slice(0, 10)) {
+          console.error(`  ${x.jawi} -> ${x.calon.map((c) => c.rumi).join('|')}  (rangka sama, PILIH ikut konteks)`)
+        }
+      }
       if (h.arab.length) console.error(`teks Arab dibiarkan (${h.arab.length}): ${h.arab.join(' ')}`)
       for (const k of h.kabur) {
         console.error(
@@ -266,6 +303,52 @@ async function main() {
       break
     }
 
+    case 'gate': {
+      if (!baki.length) throw new Error('perlu sekurang-kurangnya satu fail')
+      const abai = new Set()
+      if (pilihan.abai) {
+        const senarai = await readFile(pilihan.abai, 'utf8')
+        for (const b of senarai.split('\n')) {
+          const k = b.trim().toLowerCase()
+          if (k && !k.startsWith('#')) abai.add(k)
+        }
+      }
+
+      const gabungan = { jumlahKataUnik: 0, lulusDbp: 0, ralat: [], tidakDapatDisahkan: [] }
+      for (const fail of baki) {
+        const laporan = await gate(await readFile(fail, 'utf8'), cache, {
+          ...opts,
+          luarTalian: pilihan.luarTalian !== false,
+          abai,
+        })
+        gabungan.jumlahKataUnik += laporan.jumlahKataUnik
+        gabungan.lulusDbp += laporan.lulusDbp
+        gabungan.ralat.push(...laporan.ralat.map((r) => ({ ...r, fail })))
+        gabungan.tidakDapatDisahkan.push(...laporan.tidakDapatDisahkan.map((r) => ({ ...r, fail })))
+      }
+      gabungan.peratusTidakDapatDisahkan = gabungan.jumlahKataUnik
+        ? Math.round((gabungan.tidakDapatDisahkan.length / gabungan.jumlahKataUnik) * 100)
+        : 0
+
+      const kod = kodKeluar(gabungan, pilihan.ambang)
+      if (pilihan.json) keluar({ ...gabungan, kodKeluar: kod })
+      else {
+        console.error(
+          `gate: ${gabungan.lulusDbp}/${gabungan.jumlahKataUnik} disahkan DBP, ` +
+            `${gabungan.ralat.length} ralat, ` +
+            `${gabungan.tidakDapatDisahkan.length} tidak dapat disahkan (${gabungan.peratusTidakDapatDisahkan}%)`,
+        )
+        for (const r of gabungan.ralat.slice(0, 30)) {
+          console.error(
+            `  RALAT ${r.kata}: ${r.sebab}` + (r.sepatutnya ? ` -> guna "${r.sepatutnya}"` : ''),
+          )
+        }
+        if (gabungan.ralat.length > 30) console.error(`  ... ${gabungan.ralat.length - 30} lagi`)
+      }
+      process.exitCode = kod
+      break
+    }
+
     case 'nama': {
       if (baki.length >= 2) {
         const rec = await tambahNama(baki[0], baki[1], { jenis: pilihan.jenis ?? null })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prpm-dbp",
-  "version": "0.16.0",
+  "version": "0.18.1",
   "description": "Semak ejaan Bahasa Melayu dan Jawi terhadap PRPM Dewan Bahasa dan Pustaka. CLI dan skill untuk AI agent.",
   "keywords": [
     "bahasa-melayu",

package/src/gate.js

@@ -0,0 +1,138 @@
+/**
+ * Gate: semakan yang boleh GAGAL, untuk hook dan CI.
+ *
+ * Dibina selepas satu agen menggunakan skill ini sepanjang sesi penuh dan
+ * tetap menghantar 273 ejaan salah ke pangkalan data produksi. Alat untuk
+ * menangkapnya ada di tangannya sepanjang masa; ia tidak pernah dijalankan.
+ * Kedua-dua pusingan ditemui kerana pengguna bertanya, bukan kerana proses
+ * menangkapnya.
+ *
+ * Kesimpulannya: skill yang bergantung pada agen ingat sendiri akan gagal,
+ * dan gagal secara senyap. Gate wujud supaya kepatuhan tidak bergantung
+ * pada ingatan.
+ *
+ * TIGA keadaan, bukan dua. `tidakDapatDisahkan` TIDAK PERNAH lulus senyap:
+ * gate yang lulus atas cache sejuk memberi jaminan palsu, dan itu lebih
+ * bahaya daripada tiada gate.
+ */
+
+import { lookup } from './prpm.js'
+import { mungkinAkronim, mungkinNamaKhas } from './nama.js'
+import { cariDataset } from './dataset.js'
+
+const TOKEN_RUMI = /([A-Za-zÀ-ÿ][A-Za-zÀ-ÿ'-]*)/g
+
+/**
+ * Semak teks Rumi. Setiap perkataan jatuh ke dalam SATU daripada tiga baldi.
+ */
+export async function gate(teks, cache, opts = {}) {
+  // Dataset boleh disuntik supaya ujian tidak bergantung pada fail yang
+  // diimport ke mesin tertentu. Ujian yang bergantung pada keadaan mesin
+  // lulus di sini dan gagal di CI, atau lebih teruk, sebaliknya.
+  const { luarTalian = true, abai = new Set(), cariDalamDataset = cariDataset } = opts
+
+  const lulusDbp = []
+  const ralat = []
+  const tidakDapatDisahkan = []
+  const dilihat = new Set()
+
+  const bahagian = teks.split(TOKEN_RUMI)
+  for (const [i, cebis] of bahagian.entries()) {
+    if (i % 2 === 0) continue
+    const kata = cebis.toLowerCase()
+    if (kata.length < 2 || dilihat.has(kata)) continue
+    dilihat.add(kata)
+
+    if (abai.has(kata)) continue
+
+    // Akronim dan nama khas tidak boleh disahkan oleh kamus. Ia BUKAN lulus;
+    // ia keadaan ketiga, supaya pengguna tahu apa yang tidak disemak.
+    if (mungkinAkronim(cebis) || mungkinNamaKhas(cebis, bahagian[i - 1])) {
+      tidakDapatDisahkan.push({ kata: cebis, sebab: 'nama khas atau akronim' })
+      continue
+    }
+
+    const rec = await lookup(kata, cache, { ...opts, luarTalian })
+
+    if (rec?.ralat) {
+      tidakDapatDisahkan.push({ kata, sebab: `gagal semak: ${rec.ralat}` })
+      continue
+    }
+
+    if (!rec?.dijumpai) {
+      // Dalam mod luar talian, "tiada dalam cache" berbeza daripada "tiada
+      // dalam PRPM". Yang pertama tidak dapat disahkan; yang kedua ralat.
+      if (luarTalian && /luar talian/.test(rec?.nota ?? '')) {
+        tidakDapatDisahkan.push({ kata, sebab: 'tiada dalam cache' })
+        continue
+      }
+
+      // PRPM menyatakan sendiri perkataan ini tiada dalam kamus TERKINI
+      // tetapi ada dalam tesaurus. Itu bukan ejaan salah; ia perkataan sah
+      // yang bahagian kamusnya tidak diliputi. Menandakannya ralat
+      // menghasilkan negatif palsu pada perkataan paling biasa.
+      if (rec?.adaTesaurus) {
+        tidakDapatDisahkan.push({
+          kata,
+          sebab: 'tiada dalam kamus terkini PRPM, tetapi ada dalam tesaurus',
+        })
+        continue
+      }
+
+      // PRPM tiada entri untuk kata tugas paling asas: dan, di, ke, yang,
+      // atau. Menandakannya sebagai ralat menjadikan gate mustahil dipakai.
+      // Pembezanya bersumber, bukan senarai putih dari ingatan: kata tugas
+      // itu SEMUA wujud dalam dataset, manakala hadith, fardhu, tayammum,
+      // dhuha, qadha, redha dan iddah TIADA satu pun.
+      const ds = await cariDalamDataset(kata)
+      if (ds?.jawi) {
+        tidakDapatDisahkan.push({
+          kata,
+          sebab: 'tiada entri PRPM, tetapi wujud dalam dataset',
+        })
+        continue
+      }
+
+      ralat.push({ kata, sebab: 'tiada entri dalam PRPM', url: rec?.url })
+      continue
+    }
+
+    // Entri rujukan silang bermakna DBP mengalihkan bentuk ini ke bentuk lain.
+    // sunnah -> ®sunah. Menggunakannya adalah ejaan yang salah.
+    const def = (rec.entri?.[0]?.definisi ?? '').trim()
+    const silang = /^®\s*(.+?)\.?$/.exec(def)
+    if (silang) {
+      ralat.push({
+        kata,
+        sebab: 'rujukan silang, DBP mengalihkan ke bentuk lain',
+        sepatutnya: silang[1].trim(),
+        url: rec.url,
+      })
+      continue
+    }
+
+    lulusDbp.push(kata)
+  }
+
+  const jumlah = lulusDbp.length + ralat.length + tidakDapatDisahkan.length
+  const peratusTidakSah = jumlah ? Math.round((tidakDapatDisahkan.length / jumlah) * 100) : 0
+
+  return {
+    jumlahKataUnik: jumlah,
+    lulusDbp: lulusDbp.length,
+    ralat,
+    tidakDapatDisahkan,
+    peratusTidakDapatDisahkan: peratusTidakSah,
+  }
+}
+
+/**
+ * Tentukan kod keluar. Ralat sentiasa menggagalkan. `tidakDapatDisahkan`
+ * menggagalkan apabila melebihi ambang, kerana cache sejuk bermakna gate
+ * tidak menyemak apa-apa.
+ */
+export function kodKeluar(laporan, ambang = null) {
+  if (laporan.ralat.length) return 1
+  if (ambang != null && laporan.peratusTidakDapatDisahkan > ambang) return 1
+  return 0
+}

package/src/install.js

@@ -3,7 +3,7 @@
  * Mod salin (default) untuk pengguna npx, mod --link untuk pembangun.
  */
 
-import { cp, mkdir, rm, symlink } from 'node:fs/promises'
+import { cp, mkdir, readFile, rm, symlink, writeFile } from 'node:fs/promises'
 import { homedir } from 'node:os'
 import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
@@ -26,3 +26,50 @@ export async function pasangSkill({ link = false } = {}) {
   }
   return { dipasang: SASARAN, mod: 'salin', sumber: AKAR }
 }
+
+/**
+ * Pasang hook PostToolUse Claude Code yang menjalankan gate ke atas fail
+ * yang baru ditulis atau disunting.
+ *
+ * Ini satu-satunya lapisan yang benar-benar memaksa. Peraturan dalam
+ * SKILL.md bergantung pada agen memilih untuk patuh, dan satu agen sudah
+ * membuktikan itu tidak mencukupi: 273 ejaan salah masuk produksi walaupun
+ * alat menangkapnya ada di tangan sepanjang masa.
+ *
+ * Hook gagal LEMBUT: ia melaporkan ralat kepada agen tanpa menyekat tulisan.
+ * Menyekat tulisan atas kamus yang tidak lengkap akan menghalang kerja yang
+ * sah; melaporkan sudah memadai kerana agen membaca output hook.
+ */
+export const HOOK = {
+  matcher: 'Write|Edit',
+  hooks: [
+    {
+      type: 'command',
+      command:
+        'f=$(echo "$CLAUDE_TOOL_INPUT" | grep -oE \'"file_path"[^,]*\' | cut -d\'"\' -f4); ' +
+        'case "$f" in *.md|*.txt|*.json) npx -y prpm-dbp gate "$f" --luar-talian 2>&1 | head -20 ;; esac; exit 0',
+    },
+  ],
+}
+
+export async function pasangHook({ fail = join(homedir(), '.claude', 'settings.json') } = {}) {
+  let tetapan = {}
+  try {
+    tetapan = JSON.parse(await readFile(fail, 'utf8'))
+  } catch {
+    tetapan = {}
+  }
+
+  tetapan.hooks ??= {}
+  tetapan.hooks.PostToolUse ??= []
+
+  const sedia = tetapan.hooks.PostToolUse.some((h) =>
+    JSON.stringify(h).includes('prpm-dbp gate'),
+  )
+  if (sedia) return { fail, status: 'sudah dipasang' }
+
+  tetapan.hooks.PostToolUse.push(HOOK)
+  await mkdir(dirname(fail), { recursive: true })
+  await writeFile(fail, JSON.stringify(tetapan, null, 2), 'utf8')
+  return { fail, status: 'dipasang', matcher: HOOK.matcher }
+}

package/src/prpm.js

@@ -34,6 +34,17 @@ const DEFINISI = /<b>Definisi\s*:\s*<\/b>([\s\S]*?)(?=<b>\(|$)/
 const SUMBER = /<b>\(([^)]+)\)<\/b>/
 const TIADA_TESAURUS = /Tiada maklumat tesaurus untuk kata/
 
+// PRPM mengisytiharkan keadaan ketiga dengan ayatnya sendiri. Perkataan
+// seperti orang, itu dan sumber memulangkan halaman 35-42KB tanpa satu pun
+// div.tab-pane, tetapi ia BUKAN "tiada entri": PRPM menyatakan perkataan itu
+// tiada dalam kamus TERKINI, dan memaparkan Tesaurus sebagai gantinya.
+//
+// Menyamakan dua keadaan ini menghasilkan negatif palsu pada perkataan yang
+// paling biasa, dan negatif palsu di situ merosakkan kepercayaan kepada
+// seluruh laporan.
+const BUKAN_KAMUS_TERKINI = /Carian kata tiada di dalam kamus terkini/
+const ADA_TESAURUS = /Bersinonim dengan/
+
 // Panel "Juga ditemukan dalam" menyenaraikan bilangan rujukan perkataan itu
 // dalam setiap korpus DBP. Jumlahnya ialah isyarat kekerapan yang BERSUMBER,
 // bukan tekaan: mengikut 2439 rujukan berbanding mengekot 6.
@@ -89,11 +100,16 @@ export function parse(kata, page) {
     jawiVarian: unik.slice(1),
     entri,
     url: `${BASE_URL}?keyword=${encodeURIComponent(kata)}`,
+    // Tiga keadaan berbeza, bukan dua.
+    dalamKamusTerkini: entri.length > 0 ? true : !BUKAN_KAMUS_TERKINI.test(page),
+    adaTesaurus: ADA_TESAURUS.test(page),
     nota: entri.length
       ? null
-      : TIADA_TESAURUS.test(page)
-        ? 'tiada entri dalam PRPM'
-        : 'halaman tidak dikenali, semak manual',
+      : BUKAN_KAMUS_TERKINI.test(page)
+        ? 'tiada dalam kamus terkini PRPM; ada dalam tesaurus'
+        : TIADA_TESAURUS.test(page)
+          ? 'tiada entri dalam PRPM'
+          : 'halaman tidak dikenali, semak manual',
   }
 }
 
@@ -127,10 +143,43 @@ export async function loadCache() {
   }
 }
 
+/**
+ * Simpan cache dengan MENGGABUNGKAN keadaan di cakera terlebih dahulu.
+ *
+ * Menulis ganti secara membuta memusnahkan kerja proses lain. Dua sesi yang
+ * berjalan serentak akan memuat keadaan yang sama, masing-masing menambah
+ * perkataannya, dan yang menyimpan kemudian memadam tambahan yang awal.
+ * Ia diperhatikan secara langsung: entri yang baru dipanaskan hilang selepas
+ * sesi lain menyimpan.
+ *
+ * Rekod di cakera menang bagi kunci yang sama, kerana ia mungkin lebih baharu.
+ * Rekod benih (`ringkas`) tidak pernah menewaskan rekod penuh.
+ */
 export async function saveCache(cache) {
   await mkdir(dirname(CACHE_PATH), { recursive: true })
+
+  let diCakera = {}
+  try {
+    diCakera = JSON.parse(await readFile(CACHE_PATH, 'utf8'))
+  } catch {
+    diCakera = {}
+  }
+
+  const gabung = { ...cache }
+  for (const [kata, rec] of Object.entries(diCakera)) {
+    const sedia = gabung[kata]
+    // Rekod penuh mengatasi rekod ringkas; selain itu cakera menang.
+    if (sedia && !sedia.ringkas && rec.ringkas) continue
+    gabung[kata] = rec
+  }
+
+  // Rekod benih tidak ditulis ke cache pengguna: ia sudah ada dalam pakej.
+  for (const [kata, rec] of Object.entries(gabung)) {
+    if (rec?.benih) delete gabung[kata]
+  }
+
   const tmp = `${CACHE_PATH}.tmp`
-  await writeFile(tmp, JSON.stringify(cache, null, 1), 'utf8')
+  await writeFile(tmp, JSON.stringify(gabung, null, 1), 'utf8')
   await rename(tmp, CACHE_PATH)
 }
 

package/src/semak.js

@@ -102,3 +102,53 @@ export function ejaanLamaSahaja(a, b) {
   if (!a || !b || a === b) return false
   return samakanLama(a) === samakanLama(b)
 }
+
+/**
+ * Rangka konsonan: buang huruf vokal pilihan dan samakan varian bentuk.
+ *
+ * Dokumen kurikulum Malaysia kerap menggunakan ejaan Jawi yang berbeza
+ * daripada piawai DBP. Corak yang disahkan pada pasangan sebenar DSKP:
+ *
+ *   surah     DBP سورة   DSKP سوره    ta marbutah jadi ha
+ *   iktibar   DBP اعتبار DSKP اعتبر   alif digugurkan
+ *   bersifat  DBP برصيفت DSKP برصفة   ya digugurkan, ta marbutah
+ *   dalil     DBP دليل   DSKP داليل   alif ditambah
+ *   syirik    DBP شيريک  DSKP شرك     ya digugurkan, kaf Arab
+ *
+ * Kesemuanya berbeza hanya pada huruf vokal dan bentuk huruf, bukan pada
+ * rangka konsonan. Membuang vokal menjadikan kedua-dua ejaan sepadan.
+ *
+ * INI LOSSY dan MESTI kekal di bawah lapisan 1 dan 2. Banyak perkataan
+ * berkongsi rangka yang sama, jadi padanan begini adalah inferens, bukan
+ * rekod DBP, dan hasilnya mesti berlabel.
+ */
+const VOKAL_PILIHAN = /[اويى]/g
+
+const SAMA_BENTUK = new Map([
+  ['ة', 'ه'],
+  ['ك', 'ک'],
+  ['ڬ', 'ݢ'],
+  ['ف', 'ڤ'],
+  ['ج', 'چ'],
+  ['أ', 'ا'],
+  ['إ', 'ا'],
+  ['ء', ''],
+])
+
+// Pedoman §6.4: ta marbutah melambangkan [t] ATAU [h] sebagai kelainan
+// sebutan pada kata serapan Arab (akibat/akibah, hidayat/hidayah). Ketiga-tiga
+// huruf itu boleh bertukar di HUJUNG kata sahaja. Di tengah kata ia huruf
+// berlainan dan tidak boleh dilipat.
+const HUJUNG_SETARA = new Set(['ة', 'ه', 'ت'])
+
+export function rangkaKonsonan(jawi) {
+  if (!jawi) return ''
+  let keluar = ''
+  for (const huruf of String(jawi).normalize('NFC')) {
+    const ganti = SAMA_BENTUK.has(huruf) ? SAMA_BENTUK.get(huruf) : huruf
+    keluar += ganti
+  }
+  keluar = keluar.replace(VOKAL_PILIHAN, '').replace(/\s+/g, '')
+  if (keluar && HUJUNG_SETARA.has(keluar.slice(-1))) keluar = keluar.slice(0, -1) + 'ه'
+  return keluar
+}

package/src/tukar.js

@@ -12,7 +12,7 @@ import { lookup } from './prpm.js'
 import { normalisasiJawi } from './kamus.js'
 import { cariDataset, muatDataset } from './dataset.js'
 import { cariNama, mungkinAkronim, mungkinNamaKhas } from './nama.js'
-import { semakHurufAkhir } from './semak.js'
+import { rangkaKonsonan, semakHurufAkhir } from './semak.js'
 import {
   imbuhAkhiranAn,
   imbuhAkhiranKan,
@@ -162,6 +162,63 @@ export async function cariDasar(kata, cache, opts = {}) {
  * bilangan perkataan terpanjang supaya pembacaan songsang boleh memadan
  * jujukan, bukan token tunggal sahaja.
  */
+/**
+ * Jarak suntingan antara dua ejaan.
+ *
+ * MESTI menghormati susunan huruf. Ukuran berasaskan set huruf gagal dengan
+ * teruk: سروه (seruh) ialah anagram sempurna bagi سوره, jadi jaraknya sifar
+ * dan ia mengalahkan سورة (surah) yang sebenarnya betul. Susunan huruf itulah
+ * maklumat yang membezakannya.
+ */
+function jarakHuruf(a, b) {
+  const m = a.length
+  const n = b.length
+  if (!m) return n
+  if (!n) return m
+  let baris = Array.from({ length: n + 1 }, (_, i) => i)
+  for (let i = 1; i <= m; i++) {
+    let sebelum = baris[0]
+    baris[0] = i
+    for (let j = 1; j <= n; j++) {
+      const simpan = baris[j]
+      baris[j] = Math.min(
+        baris[j] + 1,
+        baris[j - 1] + 1,
+        sebelum + (a[i - 1] === b[j - 1] ? 0 : 1),
+      )
+      sebelum = simpan
+    }
+  }
+  return baris[n]
+}
+
+/**
+ * Indeks rangka konsonan, untuk memadan ejaan bukan piawai.
+ *
+ * Dokumen kurikulum Malaysia kerap menggunakan ortografi yang berbeza
+ * daripada DBP: vokal digugur atau ditambah, ta marbutah bertukar ha, bentuk
+ * Arab menggantikan bentuk Jawi Melayu. Indeks ini memadan rangka konsonan
+ * supaya `سوره` masih dikenali sebagai `surah`.
+ *
+ * LOSSY: 29% rangka dikongsi lebih daripada satu perkataan, purata 4.1 calon.
+ * Kerana itu ia hanya digunakan selepas padanan tepat gagal, hasilnya sentiasa
+ * berlabel, dan ia TIDAK PERNAH memilih sendiri apabila calon berbilang.
+ */
+export function petaRangka(cache, dataset = null) {
+  const peta = new Map()
+  const tambah = (jawi, rumi) => {
+    const kunci = rangkaKonsonan(jawi)
+    if (!kunci) return
+    if (!peta.has(kunci)) peta.set(kunci, new Map())
+    if (!peta.get(kunci).has(rumi)) peta.get(kunci).set(rumi, jawi)
+  }
+  for (const rec of Object.values(cache)) if (rec?.jawi) tambah(rec.jawi, rec.kata)
+  for (const [rumi, ejaan] of Object.entries(dataset?.peta ?? {})) {
+    for (const j of ejaan) tambah(j, rumi)
+  }
+  return peta
+}
+
 export function petaSongsang(cache, dataset = null) {
   const peta = new Map()
   let maxKata = 1
@@ -428,19 +485,42 @@ export async function keJawi(teks, cache, opts = {}) {
 export function keRumi(
   teksJawi,
   cache,
-  { penanda = ['«', '»'], dataset = null, pilihLazim = false } = {},
+  {
+    penanda = ['«', '»'],
+    dataset = null,
+    pilihLazim = false,
+    padanRangka = false,
+    glosari = null,
+  } = {},
 ) {
   const peta = petaSongsang(cache, dataset)
   const tidakDikenali = []
   const kabur = []
   const arab = []
   const sendiDipisah = []
+  const bukanPiawai = []
+  const dariGlosari = []
+  const rangka = padanRangka ? petaRangka(cache, dataset) : null
   const bahagian = teksJawi.split(PECAH_JAWI)
   const keluar = []
 
   for (let i = 0; i < bahagian.length; i++) {
     if (i % 2 === 0) { keluar.push(bahagian[i]); continue }
 
+    // Glosari domain yang dibekalkan pemanggil MENGATASI segalanya.
+    // Kekerapan global gagal tepat di tempat paling penting: dalam teks
+    // domain, setiap istilah khusus kalah kepada kata lazim yang berkongsi
+    // rangka. اسم menjadi asam, فعل menjadi faal, رسم menjadi rasam.
+    // Hanya pengetahuan domain boleh membetulkannya, dan pemanggil ada.
+    if (glosari) {
+      const paksa = glosari[bahagian[i]] ?? glosari[normalisasiJawi(bahagian[i])]
+      if (paksa) {
+        dariGlosari.push({ jawi: bahagian[i], rumi: paksa })
+        keluar.push(paksa)
+        continue
+      }
+    }
+
     // Teks Arab bertanda baris dibiarkan seadanya. Cuba menukarnya akan
     // merosakkan petikan al-Quran dan hadis dalam dokumen Melayu.
     if (HARAKAT.test(bahagian[i])) {
@@ -491,6 +571,43 @@ export function keRumi(
       }
       if (dipisah) { keluar.push(dipisah); sendiDipisah.push(bahagian[i]); continue }
 
+      // Lapisan terakhir: ejaan bukan piawai. Berlabel, di bawah lapisan
+      // 1 dan 2, dan tidak pernah memilih sendiri apabila calon berbilang.
+      if (rangka) {
+        const padananRangka = rangka.get(rangkaKonsonan(bahagian[i]))
+        if (padananRangka?.size) {
+          // Rangka pendek berlanggar teruk: رواية memberi 20+ calon. Isih
+          // ikut kedekatan huruf sebenar dahulu, kemudian kekerapan korpus,
+          // dan hadkan senarai supaya teks kekal boleh dibaca.
+          const asal = bahagian[i]
+          const senarai = [...padananRangka.entries()]
+            .map(([rumi, jawiDbp]) => ({
+              rumi,
+              jawiDbp,
+              jarak: jarakHuruf(asal, jawiDbp),
+              kerap: cache[rumi]?.rujukanKorpus ?? 0,
+            }))
+            .sort((a, b) => a.jarak - b.jarak || b.kerap - a.kerap)
+            .slice(0, 6)
+
+          bukanPiawai.push({ jawi: asal, calon: senarai })
+
+          if (senarai.length === 1) {
+            keluar.push(senarai[0].rumi)
+            continue
+          }
+          // --pilih mesti meleraikan ini juga, jika tidak seluruh senarai
+          // calon dibuang ke dalam teks dan ayat menjadi tidak boleh dibaca.
+          if (pilihLazim) {
+            bukanPiawai[bukanPiawai.length - 1].dipilih = senarai[0].rumi
+            keluar.push(senarai[0].rumi)
+            continue
+          }
+          keluar.push(penanda[0] + senarai.map((x) => x.rumi).join('|') + penanda[1])
+          continue
+        }
+      }
+
       tidakDikenali.push(bahagian[i])
       keluar.push(penanda[0] + bahagian[i] + penanda[1])
       continue
@@ -521,6 +638,8 @@ export function keRumi(
     kabur,
     arab: [...new Set(arab)],
     sendiDipisah,
+    ejaanBukanPiawai: bukanPiawai,
+    dariGlosari,
     saizPeta: peta.size,
     lengkap: tidakDikenali.length === 0,
   }