madi 0.2.0

//! madi(마디) 라이브러리 진입점 (10.6, KWord 요청 1·3).
//!
//! ```no_run
//! let cfg = madi::EngineConfig { knlm: Some("dict/knlm.bin".into()), ..madi::EngineConfig::new("dict/madi.dict") };
//! let engine = madi::Engine::load(&cfg)?;
//! println!("{}", engine.version());
//! let mut w = engine.worker(); // 스레드마다 하나
//! for s in w.analyze_doc("기사 본문 첫 줄.\n둘째 줄이다.") {
//!     for t in &s.tokens {
//!         print!("{}/{} ", t.form, t.tag.code());
//!     }
//! }
//! # Ok::<(), anyhow::Error>(())
//! ```
//!
//! * `analyze_doc` 은 `madi corpus` 와 같은 단계(정제 → 문장 분리 → 보일러플레이트 문장 버리기 →
//!   짧은 문장 버리기 → 분석)를 거친다. `madi corpus` 도 이 함수를 쓴다.
//! * 분석은 문장마다 독립이라 스레드 수와 관계없이 결과가 같다.
//! * 토큰: `form`, `tag`(`tag.code()` = "NNG", `tag.ko()` = "일반명"), `space_before`(어절 시작; 문장 첫 토큰은 false),
//!   `unknown`, `start`/`end`(문장 안 char 오프셋), `surface`.

pub mod split;
pub mod text;

pub use madi_core::{Options, Tag, TagStyle, Token};
pub use madi_lm::precise::PreciseOpt;
pub use madi_news as news;

use anyhow::{bail, Context, Result};
use madi_core::{Analyzer, Dict, LangModel, Worker};
use madi_lm::tlm::TlmState;
use madi_lm::{KnLm, Tlm};
#[cfg(feature = "nlm")]
use madi_lm::{Mixed, Nlm};
use std::io::Read;
use std::path::{Path, PathBuf};
use text::SkipRules;

/// 보일러플레이트 규칙을 어디서 가져올까
#[derive(Debug, Clone, PartialEq)]
pub enum Skip {
    /// 빌드 때 넣은 `tools/boilerplate.txt` (기본)
    Builtin,
    /// 파일에서
    File(PathBuf),
    /// 정제·문장 버리기를 하지 않는다
    Off,
}

#[derive(Debug, Clone)]
pub struct EngineConfig {
    /// `dict/madi.dict`
    pub dict: PathBuf,
    /// `dict/knlm.bin` (없으면 ko-dic 연접표)
    pub knlm: Option<PathBuf>,
    /// 신경망 LM (feature `nlm`). `madi nlm-pack` 으로 묶은 파일(권장) 또는 `model.i8`(어휘는 같은 디렉터리의 vocab.tsv).
    /// 어느 쪽이든 로드 때 모델·어휘의 짝을 확인하고, 어긋나면 오류로 멈춘다
    pub nlm: Option<PathBuf>,
    /// KnLM·NLM 가중치 (CLI `--lm-weight`, `--nlm-weight`). NLM 을 함께 쓸 때는 0.7 / 0.3 (`NLM_MIX_WEIGHTS`, 운영 기본 —
    /// 버전 문자열의 `.w` 도 이 값을 기준으로 본다). KnLM 만 쓸 때는 `lm_weight` 1.0 (`EngineConfig::new` 기본)
    pub lm_weight: f32,
    pub nlm_weight: f32,
    /// KnLM 미등록어 클래스 강도 (CLI `--unk-scale`)
    pub unk_scale: f32,
    /// 분석 옵션. `options.merge_nouns` 는 기본 false (KWord 는 false)
    pub options: Options,
    /// 보일러플레이트 규칙
    pub skip: Skip,
    /// 이 글자 수보다 짧은 문장은 버린다 (`madi corpus` 는 5)
    pub min_len: usize,
    /// 한자 독음 자료 디렉터리 (`refs/hanja`)
    pub hanja: Option<PathBuf>,
    /// 사용자 사전 파일들
    pub user: Vec<PathBuf>,
    /// 정밀 모드 교사 (`dict/precise.tlm`; CLI `--precise --tlm`). 있으면 τ 안쪽 어절만 교사로 다시 고른다 (10.13)
    pub precise: Option<PathBuf>,
    /// 정밀 모드 설정 (CLI `--precise-tau` 등; 기본 τ 2.5)
    pub precise_opt: PreciseOpt,
    /// 교사를 분석(정밀 모드)에는 쓰지 않고 `EngineWorker::set_teacher_score` 재채점에만 쓴다 (맞춤법 gate, 10.14)
    pub teacher_only: bool,
}

impl EngineConfig {
    pub fn new(dict: impl Into<PathBuf>) -> Self {
        Self {
            dict: dict.into(),
            knlm: None,
            nlm: None,
            lm_weight: 1.0,
            nlm_weight: 1.0,
            unk_scale: 0.0,
            options: Options::default(),
            skip: Skip::Builtin,
            min_len: 5,
            hanja: None,
            user: Vec::new(),
            precise: None,
            precise_opt: PreciseOpt::default(),
            teacher_only: false,
        }
    }
}

enum Inner {
    Conn(Analyzer<madi_core::ConnCost>),
    Kn(Analyzer<KnLm>),
    #[cfg(feature = "nlm")]
    Nl(Analyzer<Nlm>),
    #[cfg(feature = "nlm")]
    KnNl(Analyzer<Mixed<KnLm, Nlm>>),
}

/// 공유 분석기 (`Send + Sync`). 스레드마다 `worker()` 하나씩
pub struct Engine {
    inner: Inner,
    skip: Option<SkipRules>,
    min_len: usize,
    options: Options,
    version: String,
    /// 정밀 모드 교사 (읽기 전용 — 상태는 worker 마다)
    precise: Option<(Tlm, PreciseOpt)>,
    /// 교사는 재채점용으로만 (분석은 보통 경로)
    teacher_only: bool,
    /// 사용자 사전·한자 자료의 해시 (판본 문자열 `.u`; 실행 중 사용자 단어를 더하면 갱신, 0.2.0)
    user_h: Option<u64>,
}

enum WInner<'a> {
    Conn(Worker<'a, madi_core::ConnCost>),
    Kn(Worker<'a, KnLm>),
    #[cfg(feature = "nlm")]
    Nl(Worker<'a, Nlm>),
    #[cfg(feature = "nlm")]
    KnNl(Worker<'a, Mixed<KnLm, Nlm>>),
}

/// 스레드 하나의 작업 버퍼
pub struct EngineWorker<'a> {
    w: WInner<'a>,
    e: &'a Engine,
    /// `analyze_query_nbest` 에만 쓰는 옵션 (`None` 이면 엔진 옵션). 맞춤법 검사기가 재채점 점수차를 예전 눈금(`legacy_score`)으로 재려고 쓴다 (10.13)
    nbest_opt: Option<Options>,
    /// 정밀 모드 교사 상태 (엔진에 교사가 있을 때만)
    tst: Option<TlmState>,
    /// `analyze_query_nbest` 의 점수를 교사 로그 확률로 (맞춤법 gate Teacher)
    teacher_score: bool,
}

/// 문서 안의 문장 하나
#[derive(Debug, Clone)]
pub struct Sentence {
    pub text: String,
    pub tokens: Vec<Token>,
}

/// 위치가 붙은 형태소 (0.2.0). `token.start`/`end` 는 **입력 전체** 기준 char 위치, `word` 는 문장 안 어절 번호(0부터),
/// `sent` 는 입력 안 문장 번호(0부터)
#[derive(Debug, Clone)]
pub struct Morph {
    pub token: Token,
    pub word: u32,
    pub sent: u32,
}

/// 문장 하나의 구간과 형태소 (0.2.0). `start`/`end` 는 입력 전체 기준 char 위치 [start, end)
#[derive(Debug, Clone)]
pub struct SentSpan {
    pub start: usize,
    pub end: usize,
    pub text: String,
    pub tokens: Vec<Morph>,
}

/// 미리 정한 구간 (0.2.0, Kiwi 의 `pretokenized`): 입력 char 구간 [start, end) 를 `form`(없으면 그 구간 원문)·`tag`
/// (없으면 아무 태그; 태그 코드는 접두 일치 — "NN" 이면 NNG·NNP·NNB) 인 형태소로 분석하게 한다. 격자 제약이라
/// 사전에 그 (형태, 태그) 후보가 없으면 지키지 못할 수 있다(돌려주는 `bool` 이 false)
#[derive(Debug, Clone)]
pub struct Pretoken {
    pub start: usize,
    pub end: usize,
    pub form: Option<String>,
    pub tag: Option<String>,
}

/// 원형(lemma): 용언(VV·VA·VX·VCP·VCN)은 어간 + "다", 그 밖은 형태 그대로 (0.2.0)
pub fn lemma(t: &Token) -> String {
    match t.tag {
        Tag::VV | Tag::VA | Tag::VX | Tag::VCP | Tag::VCN => format!("{}다", t.form),
        _ => t.form.clone(),
    }
}

/// 파일 내용의 64비트 해시 (FNV 식, 8바이트 단위). 버전 문자열용
pub fn hash_bytes(h: u64, b: &[u8]) -> u64 {
    let mut h = h;
    let mut ch = b.chunks_exact(8);
    for c in &mut ch {
        h = (h ^ u64::from_le_bytes(c.try_into().unwrap())).wrapping_mul(0x100000001b3).rotate_left(23);
    }
    for &x in ch.remainder() {
        h = (h ^ x as u64).wrapping_mul(0x100000001b3);
    }
    h
}

/// 텍스트 해시: 줄끝을 LF 로 맞춘 뒤 (Windows git 이 CRLF 로 풀어도 같은 값; KWord 알림 10.6)
pub fn hash_text(t: &str) -> u64 {
    let t = t.strip_prefix('\u{feff}').unwrap_or(t);
    if t.contains('\r') {
        hash_bytes(0xcbf29ce484222325, t.replace("\r\n", "\n").as_bytes())
    } else {
        hash_bytes(0xcbf29ce484222325, t.as_bytes())
    }
}

pub fn hash_file(path: &Path) -> Result<u64> {
    let mut f = std::fs::File::open(path).with_context(|| path.display().to_string())?;
    let mut buf = vec![0u8; 1 << 20];
    let mut h = 0xcbf29ce484222325u64;
    let mut carry: Vec<u8> = Vec::new();
    loop {
        let n = f.read(&mut buf)?;
        if n == 0 {
            break;
        }
        // 8바이트 정렬을 유지하려고 남은 조각을 다음 읽기와 잇는다
        carry.extend_from_slice(&buf[..n]);
        let k = carry.len() / 8 * 8;
        h = hash_bytes(h, &carry[..k]);
        carry.drain(..k);
    }
    Ok(hash_bytes(h, &carry))
}

/// `hash_file` 과 같은 값을 메모리 버퍼(8바이트 단위 `words`, 실제 `len` 바이트)에서 (WASM, 10.14). 리틀 엔디언 가정(x86·wasm32)
pub fn hash_words(words: &[u64], len: usize) -> u64 {
    let full = len / 8;
    let mut h = 0xcbf29ce484222325u64;
    for &w in &words[..full] {
        h = (h ^ u64::from_le(w)).wrapping_mul(0x100000001b3).rotate_left(23);
    }
    if len % 8 != 0 {
        let b = words[full].to_le_bytes();
        for &x in &b[..len % 8] {
            h = (h ^ x as u64).wrapping_mul(0x100000001b3);
        }
    }
    h
}

fn short(h: u64) -> String {
    format!("{:04x}", (h ^ (h >> 16) ^ (h >> 32) ^ (h >> 48)) & 0xffff)
}

#[cfg(feature = "nlm")]
fn load_nlm(p: &Path, weight: f32, dict: &Dict) -> Result<Nlm> {
    let mut n = madi_lm::nlm::load_checked(p).with_context(|| format!("load {}", p.display()))?;
    n.weight = weight;
    n.attach(dict);
    Ok(n)
}

/// `Inner` 의 분석기에 같은 일을 한다 (변형 넷)
macro_rules! with_an {
    ($inner:expr, $an:ident => $body:expr) => {
        match &mut $inner {
            Inner::Conn($an) => $body,
            Inner::Kn($an) => $body,
            #[cfg(feature = "nlm")]
            Inner::Nl($an) => $body,
            #[cfg(feature = "nlm")]
            Inner::KnNl($an) => $body,
        }
    };
}

/// 사용자 사전·한자 자료 파일의 해시 (판본 문자열 `.u`). 둘 다 없으면 None
fn user_hash(cfg: &EngineConfig) -> Result<Option<u64>> {
    if cfg.hanja.is_none() && cfg.user.is_empty() {
        return Ok(None);
    }
    let mut h = 0u64;
    if let Some(d) = &cfg.hanja {
        for f in ["hanja_char.csv", "dueum.csv", "hanja_word.csv"] {
            let t = std::fs::read_to_string(d.join(f)).with_context(|| d.join(f).display().to_string())?;
            h = h.rotate_left(5) ^ hash_text(&t);
        }
    }
    for p in &cfg.user {
        let t = std::fs::read_to_string(p).with_context(|| p.display().to_string())?;
        h = h.rotate_left(5) ^ hash_text(&t);
    }
    Ok(Some(h))
}

fn prepare<L: LangModel>(mut an: Analyzer<L>, cfg: &EngineConfig) -> Result<Analyzer<L>> {
    if let Some(dir) = &cfg.hanja {
        an.load_hanja(dir).with_context(|| format!("load hanja from {}", dir.display()))?;
    }
    for p in &cfg.user {
        let bad = an.load_user_dict(p).with_context(|| format!("read {}", p.display()))?;
        if let Some((ln, line)) = bad.first() {
            bail!("{}:{}: 사용자 사전 줄 형식 오류: {}", p.display(), ln, line);
        }
    }
    Ok(an)
}

impl Engine {
    /// 사전과 LM 을 연다
    pub fn load(cfg: &EngineConfig) -> Result<Self> {
        let dict = Dict::open(&cfg.dict).with_context(|| format!("open {}", cfg.dict.display()))?;
        Self::from_dict(dict, cfg)
    }

    /// 이미 연 사전으로 (CLI 가 공백 자질 표를 바꾼 사전을 넘길 때). 버전의 사전 해시는 `cfg.dict` 파일로 낸다
    pub fn from_dict(dict: Dict, cfg: &EngineConfig) -> Result<Self> {
        #[cfg(not(feature = "nlm"))]
        if cfg.nlm.is_some() {
            bail!("this madi was built without feature \"nlm\"");
        }
        let knlm = match &cfg.knlm {
            Some(p) => {
                let mut lm = KnLm::load(p).with_context(|| format!("load {}", p.display()))?;
                lm.weight = cfg.lm_weight;
                lm.unk_scale = cfg.unk_scale;
                lm.attach(&dict);
                Some(lm)
            }
            None => None,
        };
        let inner = match (knlm, &cfg.nlm) {
            (None, None) => Inner::Conn(prepare(Analyzer::with_lm(dict, madi_core::ConnCost), cfg)?),
            (Some(lm), None) => Inner::Kn(prepare(Analyzer::with_lm(dict, lm), cfg)?),
            #[cfg(feature = "nlm")]
            (None, Some(np)) => {
                let nlm = load_nlm(np, cfg.nlm_weight, &dict)?;
                Inner::Nl(prepare(Analyzer::with_lm(dict, nlm), cfg)?)
            }
            #[cfg(feature = "nlm")]
            (Some(lm), Some(np)) => {
                let mut nlm = load_nlm(np, cfg.nlm_weight, &dict)?;
                nlm.weight *= cfg.options.search.nlm_scale; // 10.12 기본 가중의 NLM 몫 (보간일 때만)
                Inner::KnNl(prepare(Analyzer::with_lm(dict, Mixed { a: lm, b: nlm }), cfg)?)
            }
            #[cfg(not(feature = "nlm"))]
            (_, Some(_)) => unreachable!(),
        };
        let (skip, skip_text) = match &cfg.skip {
            Skip::Builtin => (Some(SkipRules::builtin()), Some(text::BUILTIN_SKIP.to_string())),
            Skip::File(p) => {
                let t = std::fs::read_to_string(p).with_context(|| p.display().to_string())?;
                (Some(SkipRules::parse(&t, &p.display().to_string())?), Some(t))
            }
            Skip::Off => (None, None),
        };
        let version = Self::make_version(cfg, skip_text.as_deref())?;
        let precise = match &cfg.precise {
            Some(p) => Some((Tlm::load(p).with_context(|| format!("load {} (정밀 모드 교사)", p.display()))?, cfg.precise_opt)),
            None => None,
        };
        Ok(Self { inner, skip, min_len: cfg.min_len, options: cfg.options.clone(), version, precise, teacher_only: cfg.teacher_only, user_h: user_hash(cfg)? })
    }

    /// 메모리에 있는 사전·KnLM 으로 (WASM, 10.14). 파일 경로 항목(`dict`·`knlm`·`nlm`·`precise`·`user`·`hanja`)은 쓰지 않는다 —
    /// 사전·KnLM 은 인자로, 나머지(가중치·옵션·skip·min_len)는 `cfg` 에서. 버전 문자열은 같은 파일을 경로로 열 때와 같다
    pub fn from_memory(dict_words: Vec<u64>, dict_len: usize, knlm: Option<(Vec<u64>, usize)>, cfg: &EngineConfig) -> Result<Self> {
        if cfg.nlm.is_some() || cfg.precise.is_some() || !cfg.user.is_empty() || cfg.hanja.is_some() {
            bail!("from_memory: NLM·정밀 모드·사용자 사전·한자 자료는 아직 지원하지 않는다");
        }
        let mut v = format!("{}+d{}", env!("CARGO_PKG_VERSION"), short(hash_words(&dict_words, dict_len)));
        v += &rev_tag(cfg);
        let kh = knlm.as_ref().map(|(w, n)| hash_words(w, *n));
        let dict = Dict::from_words(dict_words, dict_len).context("사전")?;
        let lm = match knlm {
            Some((w, n)) => {
                let mut lm = KnLm::from_raw(madi_core::dict::RawSections::from_words(w, n).context("KnLM")?)?;
                lm.weight = cfg.lm_weight;
                lm.unk_scale = cfg.unk_scale;
                lm.attach(&dict);
                Some(lm)
            }
            None => None,
        };
        match kh {
            Some(h) => v += &format!(".k{}", short(h)),
            None => v += ".k-",
        }
        v += ".n-";
        let skip = match &cfg.skip {
            Skip::Builtin => {
                v += &format!(".s{}", short(hash_text(text::BUILTIN_SKIP)));
                Some(SkipRules::builtin())
            }
            Skip::File(_) => bail!("from_memory: Skip::File 은 쓸 수 없다 (Builtin 또는 Off)"),
            Skip::Off => {
                v += ".s-";
                None
            }
        };
        v += &knob_tag(cfg);
        let inner = match lm {
            None => Inner::Conn(Analyzer::with_lm(dict, madi_core::ConnCost)),
            Some(lm) => Inner::Kn(Analyzer::with_lm(dict, lm)),
        };
        Ok(Self { inner, skip, min_len: cfg.min_len, options: cfg.options.clone(), version: v, precise: None, teacher_only: false, user_h: None })
    }

    /// `0.1.0-kword1+d3f2a.k91c0.n-.s7e1b[.u…][.w…]`: 크레이트 버전 + 사전·KnLM·NLM·보일러플레이트 규칙 해시 앞 4자리.
    /// 사용자 사전·한자 자료를 쓰면 `u`, 기본이 아닌 가중치·옵션이면 `w` 가 붙는다
    fn make_version(cfg: &EngineConfig, skip_text: Option<&str>) -> Result<String> {
        let mut v = format!("{}+d{}", env!("CARGO_PKG_VERSION"), short(hash_file(&cfg.dict)?));
        // 기본 점수 가중 판본 (10.12): 기본값 자체가 바뀐 것은 아래 `.w` 로 드러나지 않으므로
        v += &rev_tag(cfg);
        match &cfg.knlm {
            Some(p) => v += &format!(".k{}", short(hash_file(p)?)),
            None => v += ".k-",
        }
        match &cfg.nlm {
            Some(p) => {
                // 묶음 파일이면 그 파일만, 아니면 같은 디렉터리의 vocab.tsv 도
                #[allow(unused_mut)]
                let mut h = hash_file(p)?;
                #[cfg(feature = "nlm")]
                if !Nlm::is_packed(p) {
                    h ^= hash_file(&p.parent().unwrap_or(Path::new(".")).join("vocab.tsv"))?.rotate_left(7);
                }
                v += &format!(".n{}", short(h));
            }
            None => v += ".n-",
        }
        match skip_text {
            Some(t) => v += &format!(".s{}", short(hash_text(t))),
            None => v += ".s-",
        }
        if let Some(h) = user_hash(cfg)? {
            v += &format!(".u{}", short(h));
        }
        // 가중치·옵션이 기본과 다르면 그 차이도 버전에 (같은 파일이라도 결과가 달라지므로)
        v += &knob_tag(cfg);
        // 정밀 모드 (없으면 아무것도 붙지 않아 예전 버전 문자열 그대로)
        if let Some(p) = &cfg.precise {
            let mut h = hash_file(p)?;
            let po = cfg.precise_opt.diff_default();
            if !po.is_empty() {
                h ^= hash_bytes(11, po.join(" ").as_bytes());
            }
            v += &format!(".p{}", short(h));
        }
        Ok(v)
    }

    /// 버전 문자열 (KWord DB 이름·meta 용)
    pub fn version(&self) -> &str {
        &self.version
    }

    /// 사용자 단어를 더한다 (`형태 ⇥ 태그 [⇥ 보너스]` 줄과 같음; 보너스 기본 3.0). 다음 분석부터 쓰인다. 판본 문자열 `.u` 가 바뀐다 (0.2.0)
    pub fn add_user_word(&mut self, form: &str, tag: Tag, score: Option<f32>) {
        with_an!(self.inner, an => an.add_user_word(form, tag, score));
        self.bump_user(&format!("{form}\t{}\t{score:?}", tag.code()));
    }

    /// 기분석 항목을 더한다 (`표면형 ⇥ = ⇥ 형태/태그 …` 줄과 같음; 보너스 기본 6.0) (0.2.0)
    pub fn add_pre_analyzed_word(&mut self, surface: &str, morphs: &[(String, Tag)], score: Option<f32>) {
        with_an!(self.inner, an => an.add_preanalysis(surface, morphs, score));
        let ms: Vec<String> = morphs.iter().map(|(f, t)| format!("{f}/{}", t.code())).collect();
        self.bump_user(&format!("{surface}\t=\t{}\t{score:?}", ms.join(" ")));
    }

    /// 사용자 사전 파일을 더한다 (형식은 `docs/user_dict.md`). 잘못된 줄이 있으면 오류 (0.2.0)
    pub fn load_user_dictionary(&mut self, path: &Path) -> Result<()> {
        let t = std::fs::read_to_string(path).with_context(|| path.display().to_string())?;
        let bad = with_an!(self.inner, an => an.load_user_dict(path)).with_context(|| format!("read {}", path.display()))?;
        if let Some((ln, line)) = bad.first() {
            bail!("{}:{}: 사용자 사전 줄 형식 오류: {}", path.display(), ln, line);
        }
        self.bump_user(&t);
        Ok(())
    }

    /// 판본 문자열의 `.u` 를 갱신 (`…s0968[.uXXXX][.w…][.p…]`)
    fn bump_user(&mut self, text: &str) {
        let h = self.user_h.unwrap_or(0).rotate_left(5) ^ hash_text(text);
        self.user_h = Some(h);
        let (head, rest) = self.version.split_once('+').map(|(a, b)| (a.to_string(), b.to_string())).unwrap_or_default();
        let mut segs: Vec<String> = rest.split('.').filter(|x| !x.starts_with('u')).map(String::from).collect();
        let at = segs.iter().position(|x| x.starts_with('s')).map(|i| i + 1).unwrap_or(segs.len());
        segs.insert(at, format!("u{}", short(h)));
        self.version = format!("{head}+{}", segs.join("."));
    }

    pub fn options(&self) -> &Options {
        &self.options
    }

    /// 정밀 모드 교사를 실었나
    pub fn is_precise(&self) -> bool {
        self.precise.is_some()
    }

    /// LM 구성 이름: "conn" | "knlm" | "nlm" | "knlm+nlm"
    pub fn lm_name(&self) -> &'static str {
        match &self.inner {
            Inner::Conn(_) => "conn",
            Inner::Kn(_) => "knlm",
            #[cfg(feature = "nlm")]
            Inner::Nl(_) => "nlm",
            #[cfg(feature = "nlm")]
            Inner::KnNl(_) => "knlm+nlm",
        }
    }

    pub fn dict(&self) -> &Dict {
        match &self.inner {
            Inner::Conn(a) => &a.dict,
            Inner::Kn(a) => &a.dict,
            #[cfg(feature = "nlm")]
            Inner::Nl(a) => &a.dict,
            #[cfg(feature = "nlm")]
            Inner::KnNl(a) => &a.dict,
        }
    }

    /// 보일러플레이트 규칙 수 (끄면 0)
    pub fn n_skip_rules(&self) -> usize {
        self.skip.as_ref().map(|r| r.len()).unwrap_or(0)
    }

    /// 스레드마다 하나
    pub fn worker(&self) -> EngineWorker<'_> {
        let w = match &self.inner {
            Inner::Conn(a) => WInner::Conn(a.worker()),
            Inner::Kn(a) => WInner::Kn(a.worker()),
            #[cfg(feature = "nlm")]
            Inner::Nl(a) => WInner::Nl(a.worker()),
            #[cfg(feature = "nlm")]
            Inner::KnNl(a) => WInner::KnNl(a.worker()),
        };
        let tst = self.precise.as_ref().map(|(t, _)| t.new_state());
        EngineWorker { w, e: self, nbest_opt: None, tst, teacher_score: false }
    }
}

/// 문서 하나를 처리한 결과와 버린 문장 수
pub struct DocResult {
    pub sentences: Vec<Sentence>,
    /// 보일러플레이트 규칙으로 버린 문장 수
    pub skipped: usize,
    /// `min_len` 보다 짧아 버린 문장 수
    pub short: usize,
}

impl EngineWorker<'_> {
    fn run(&mut self, text: &str) -> Vec<Token> {
        let opt = &self.e.options;
        if let (Some((tlm, po)), Some(st), false) = (&self.e.precise, &mut self.tst, self.e.teacher_only) {
            // 정밀 모드 (CLI `best_tokens` 와 같음): 국소 대안(τ 문턱) → 교사로 다시 고르기
            let r = match &mut self.w {
                WInner::Conn(w) => w.analyze_alts_local_gated(text, opt, po.cand_margin, po.max_alts, Some(po.tau)),
                WInner::Kn(w) => w.analyze_alts_local_gated(text, opt, po.cand_margin, po.max_alts, Some(po.tau)),
                #[cfg(feature = "nlm")]
                WInner::Nl(w) => w.analyze_alts_local_gated(text, opt, po.cand_margin, po.max_alts, Some(po.tau)),
                #[cfg(feature = "nlm")]
                WInner::KnNl(w) => w.analyze_alts_local_gated(text, opt, po.cand_margin, po.max_alts, Some(po.tau)),
            };
            let mut stats = Default::default();
            return madi_lm::precise::apply(tlm, st, &r, po, &mut stats);
        }
        match &mut self.w {
            WInner::Conn(w) => w.analyze(text, opt),
            WInner::Kn(w) => w.analyze(text, opt),
            #[cfg(feature = "nlm")]
            WInner::Nl(w) => w.analyze(text, opt),
            #[cfg(feature = "nlm")]
            WInner::KnNl(w) => w.analyze(text, opt),
        }
    }

    /// 기사 본문(여러 줄) → 문장들. `madi corpus` 와 같은 정제·문장 분리·버리기를 거친다
    pub fn analyze_doc(&mut self, text: &str) -> Vec<Sentence> {
        self.analyze_doc_full(text).sentences
    }

    /// `analyze_doc` + 버린 문장 수
    pub fn analyze_doc_full(&mut self, text: &str) -> DocResult {
        let e = self.e;
        let cleaned;
        let text = match &e.skip {
            Some(r) => {
                cleaned = r.clean(text);
                cleaned.as_str()
            }
            None => text,
        };
        let mut ss = text::split_sentences(text);
        let mut skipped = 0;
        if let Some(r) = &e.skip {
            let before = ss.len();
            ss.retain(|s| !r.skip(s));
            skipped = before - ss.len();
        }
        let mut short = 0;
        let mut sentences = Vec::with_capacity(ss.len());
        for s in ss {
            if s.chars().count() < e.min_len {
                short += 1;
                continue;
            }
            let tokens = self.run(&s);
            sentences.push(Sentence { text: s, tokens });
        }
        DocResult { sentences, skipped, short }
    }

    /// 형태소 분석을 쓰는 문장 분리 (`split::split_line`; 줄마다 분석해 종결 부호·종결 어미 뒤에서 끊는다). 10.13
    pub fn split_sentences(&mut self, text: &str) -> Vec<String> {
        let mut out = Vec::new();
        for line in text.lines() {
            if line.trim().is_empty() {
                continue;
            }
            let toks = self.run(line);
            let chars: Vec<char> = line.chars().collect();
            for (s, e) in split::split_line(line, &toks) {
                out.push(chars[s..e].iter().collect());
            }
        }
        out
    }

    /// 입력(여러 줄 가능)을 문장으로 나누고 문장마다 위치가 붙은 형태소 (0.2.0). 정제·버리기 없이 줄마다 분석하고
    /// (`split_sentences` 와 같은 경계) 형태소의 위치는 입력 전체 기준이다. 빈 줄은 건너뛴다
    pub fn sentences(&mut self, text: &str) -> Vec<SentSpan> {
        let mut out = Vec::new();
        let mut off = 0usize; // 줄 시작의 char 위치
        for raw in text.split('\n') {
            let line = raw.strip_suffix('\r').unwrap_or(raw);
            let n_line = raw.chars().count() + 1;
            if !line.trim().is_empty() {
                let toks = self.run(line);
                let chars: Vec<char> = line.chars().collect();
                for (s, e) in split::split_line(line, &toks) {
                    let sent = out.len() as u32;
                    let mut word = 0u32;
                    let mut ms = Vec::new();
                    for t in toks.iter().filter(|t| t.start >= s && t.end <= e) {
                        if !ms.is_empty() && t.space_before {
                            word += 1;
                        }
                        let mut t = t.clone();
                        t.start += off;
                        t.end += off;
                        ms.push(Morph { token: t, word, sent });
                    }
                    out.push(SentSpan { start: off + s, end: off + e, text: chars[s..e].iter().collect(), tokens: ms });
                }
            }
            off += n_line;
        }
        out
    }

    /// `sentences` 의 형태소를 이어 붙인 것 (0.2.0)
    pub fn tokenize(&mut self, text: &str) -> Vec<Morph> {
        self.sentences(text).into_iter().flat_map(|s| s.tokens).collect()
    }

    /// 여러 후보 (0.2.0): (점수, 형태소들), 점수가 큰 것(좋은 것)부터. 점수는 탐색의 로그 확률 합이라 설정(KnLM·NLM)마다 눈금이 다르다.
    /// 1번 후보는 늘 `analyze_sentence` 와 같다(정밀 모드면 교사가 고른 것; 그때 점수는 격자 1위의 것)
    pub fn analyze_nbest(&mut self, text: &str, n: usize) -> Vec<(f32, Vec<Token>)> {
        let n = n.max(1);
        // 2단 채점 문턱(nlm_gate)은 노드마다 1위 근처 경로만 남겨 2위 이하 후보를 지운다 → 후보가 여럿일 때는 끈다.
        // 1번 후보는 아래에서 늘 `run`(문턱 켬) 결과로 맞추므로 1-best 출력은 바뀌지 않는다
        let mut o2 = self.e.options.clone();
        if n > 1 {
            o2.search.nlm_gate = 0.0;
        }
        let opt = &o2;
        let mut r = match &mut self.w {
            WInner::Conn(w) => w.analyze_nbest(text, n, opt),
            WInner::Kn(w) => w.analyze_nbest(text, n, opt),
            #[cfg(feature = "nlm")]
            WInner::Nl(w) => w.analyze_nbest(text, n, opt),
            #[cfg(feature = "nlm")]
            WInner::KnNl(w) => w.analyze_nbest(text, n, opt),
        };
        let best = self.run(text);
        let same = |a: &[Token], b: &[Token]| a.len() == b.len() && a.iter().zip(b).all(|(x, y)| x.form == y.form && x.tag == y.tag && x.start == y.start && x.end == y.end);
        if r.first().map_or(true, |(_, t)| !same(t, &best)) {
            let sc = r.first().map_or(0.0, |x| x.0);
            r.retain(|(_, t)| !same(t, &best));
            r.insert(0, (sc, best));
            r.truncate(n);
        }
        r
    }

    /// 미리 정한 구간을 지키는 분석 (0.2.0). (형태소들, 구간마다 지켰는가)
    pub fn analyze_pretokenized(&mut self, text: &str, pre: &[Pretoken]) -> (Vec<Token>, Vec<bool>) {
        let chars: Vec<char> = text.chars().collect();
        let cons: Vec<madi_core::lattice::Boost> = pre
            .iter()
            .map(|p| {
                let e = p.end.min(chars.len());
                let s = p.start.min(e);
                madi_core::lattice::Boost {
                    c0: s as u32,
                    c1: e as u32,
                    form: p.form.clone().unwrap_or_else(|| chars[s..e].iter().collect()),
                    tag: p.tag.clone().unwrap_or_default(),
                    bonus: 30.0,
                }
            })
            .collect();
        let opt = &self.e.options;
        match &mut self.w {
            WInner::Conn(w) => w.analyze_constrained(text, opt, &cons),
            WInner::Kn(w) => w.analyze_constrained(text, opt, &cons),
            #[cfg(feature = "nlm")]
            WInner::Nl(w) => w.analyze_constrained(text, opt, &cons),
            #[cfg(feature = "nlm")]
            WInner::KnNl(w) => w.analyze_constrained(text, opt, &cons),
        }
    }

    /// 문장 하나(정제·버리기 없이) → 형태소들
    pub fn analyze_sentence(&mut self, text: &str) -> Vec<Token> {
        self.run(text)
    }

    /// 검색어용: 짧은 입력 하나(정제·버리기 없이) → 형태소들
    pub fn analyze_query(&mut self, text: &str) -> Vec<Token> {
        self.run(text.trim())
    }

    /// 검색어용 n-best: (점수, 형태소들), 점수 오름차순(작을수록 좋음)
    /// `analyze_query_nbest` 가 쓸 옵션을 따로 정한다 (분석 결과는 그대로 엔진 옵션; 점수 눈금만 바꿀 때). 10.13
    pub fn set_nbest_options(&mut self, opt: Option<Options>) {
        self.nbest_opt = opt;
    }
    pub fn analyze_query_nbest(&mut self, text: &str, n: usize) -> Vec<(f32, Vec<Token>)> {
        let opt = self.nbest_opt.as_ref().unwrap_or(&self.e.options);
        let text = text.trim();
        let mut r = match &mut self.w {
            WInner::Conn(w) => w.analyze_nbest(text, n, opt),
            WInner::Kn(w) => w.analyze_nbest(text, n, opt),
            #[cfg(feature = "nlm")]
            WInner::Nl(w) => w.analyze_nbest(text, n, opt),
            #[cfg(feature = "nlm")]
            WInner::KnNl(w) => w.analyze_nbest(text, n, opt),
        };
        if self.teacher_score {
            if let (Some((tlm, _)), Some(st)) = (&self.e.precise, &mut self.tst) {
                for (sc, toks) in r.iter_mut() {
                    *sc = teacher_logprob(tlm, st, toks);
                }
            }
        }
        r
    }

    /// 켜면 `analyze_query_nbest` 의 점수가 정밀 모드 교사의 문장 로그 확률(클수록 좋음)이 된다. 엔진에 교사가 없으면 무시 (맞춤법 gate, 10.14)
    pub fn set_teacher_score(&mut self, on: bool) {
        self.teacher_score = on;
    }
}

/// 교사로 본 형태소열 로그 확률: BOS×3 + 토큰 + EOS. 교사 문맥(ctx)보다 길면 64 토큰씩 앞 문맥을 이어 가며 더한다
fn teacher_logprob(tlm: &Tlm, st: &mut TlmState, toks: &[Token]) -> f32 {
    use madi_lm::precise::{BOS, EOS};
    let mut seq: Vec<u16> = toks.iter().map(|t| tlm.id_of(&t.form, t.tag)).collect();
    seq.push(EOS);
    let mut prefix: Vec<u16> = vec![BOS, BOS, BOS];
    let mut total = 0.0;
    for chunk in seq.chunks(64) {
        total += tlm.score(st, &prefix, &[chunk])[0];
        prefix.extend_from_slice(chunk);
    }
    total
}

/// 토큰들 → `form/TAG form/TAG | …` (어절 경계 `|`; `madi corpus --tokens` 의 둘째 열)
pub fn format_tokens(toks: &[Token]) -> String {
    text::format_tokens(toks)
}

/// 판본 문자열의 점수 가중·탐색 판 (10.17 A2): `.r3p`(기본, 논문 판 3p) 또는 `.r3`(옛 운영 가중 `--score-preset rev3`),
/// 그 뒤 전후향 가지치기 문턱 `.fN`(기본 `.f11`, 끄면 `.f0`). 가중이 두 프리셋 어느 쪽도 아니면 `.r3p` 로 두고 차이는 `.w` 에 든다
fn rev_tag(cfg: &EngineConfig) -> String {
    let s = &cfg.options.search;
    let r = if s.is_rev3() && !s.is_rev3p() { format!(".r{}", madi_core::lattice::SCORE_REV) } else { format!(".r{}p", madi_core::lattice::SCORE_REV) };
    let f = s.fb_cutoff;
    let f = if f == f.trunc() { format!("{}", f as i64) } else { format!("{}", f) };
    format!("{r}.f{f}")
}

/// 판본 문자열의 `.w`: 가중치·옵션 가운데 **기본값과 다른 칸만** `이름=값` 로 모아 해시한다 (10.17 A2). 옵션 구조에 칸이 늘어도
/// 그 칸이 기본값이면 해시가 바뀌지 않는다(§20 의 `w21b0` → `wff87` 같은 일이 없게). 점수 가중 프리셋(`.r3`/`.r3p`)과
/// `fb_cutoff`(`.fN`)는 앞 태그로 나타내므로 뺀다. 아무것도 다르지 않으면 빈 문자열
/// 신경망 LM 을 함께 쓸 때의 운영 가중 (KnLM, NLM) — 10.17 A2. CLI 는 `--nlm` 만 주면 이 값을 쓴다
pub const NLM_MIX_WEIGHTS: (f32, f32) = (0.7, 0.3);

fn knob_tag(cfg: &EngineConfig) -> String {
    let d = knob_diff(cfg);
    if d.is_empty() { String::new() } else { format!(".w{}", short(hash_bytes(7, d.join(" ").as_bytes()))) }
}

/// `knob_tag` 가 해시하는 문자열 (확인용: `madi version --knobs`)
pub fn knob_diff(cfg: &EngineConfig) -> Vec<String> {
    let def = EngineConfig::new("");
    let mut d: Vec<String> = Vec::new();
    // 가중 기준: NLM 을 쓰면 0.7 / 0.3, 아니면 KnLM 1.0 (NLM 가중은 쓰이지 않으므로 보지 않는다)
    if cfg.nlm.is_some() {
        if cfg.lm_weight != NLM_MIX_WEIGHTS.0 { d.push(format!("lm_weight={}", cfg.lm_weight)); }
        if cfg.nlm_weight != NLM_MIX_WEIGHTS.1 { d.push(format!("nlm_weight={}", cfg.nlm_weight)); }
    } else if cfg.lm_weight != def.lm_weight {
        d.push(format!("lm_weight={}", cfg.lm_weight));
    }
    if cfg.unk_scale != def.unk_scale { d.push(format!("unk_scale={}", cfg.unk_scale)); }
    // 짧은 문장 버리기는 `.s` 와 짝으로 본다: 규칙을 쓰면 5, 규칙을 끄면(`.s-`) 0 이 기본 (Python·WASM·맞춤법은 끄고 0)
    let min_def = if cfg.skip == Skip::Off { 0 } else { def.min_len };
    if cfg.min_len != min_def { d.push(format!("min_len={}", cfg.min_len)); }
    let s = &cfg.options.search;
    let preset = s.is_rev3() || s.is_rev3p();
    d.extend(s.diff_default(!preset, false));
    let o = &cfg.options;
    let od = &def.options;
    madi_core::diff_fields!(d, o, od; split_compound, split_unknown_compound, fine_tags, merge_nouns, std_2025);
    d
}