msime-engine 0.2.0

//! 五笔码表的 provider（`R/providers/wubi_candidate_provider.cpp`，含 wubi_prefix_learning overlay）：按 `WubiProfileKind` 读 `wubi86` 或 `wubi98`。Exact code first, then weight, no value dedup, at most 50 rows. The provider only reads: learning and removal of a wubi row go through `session`, which journals them with the wubi kind and then resets this cache.

use std::num::NonZeroUsize;
use std::path::{Path, PathBuf};

use lru::LruCache;
use rusqlite::types::ValueRef;
use rusqlite::{Connection, OpenFlags, OptionalExtension};

use super::frequency::WubiFrequency;
use crate::dictionary::pinyin::BUSY_TIMEOUT;
use crate::types::{CandidateSource, QueryRequest, SchemeType, WordItem, WubiProfileKind};

const QUERY_LIMIT: i64 = 50;
const REVERSE_CACHE_CAPACITY: usize = 1024;
const REVERSE_QUERY_SQL_86: &str = "SELECT \"key\" FROM wubi86 WHERE \"value\" = ?1 ORDER BY length(\"key\") DESC, \"weight\" DESC, \"key\" ASC, rowid ASC LIMIT 1";
const REVERSE_QUERY_SQL_98: &str = "SELECT \"key\" FROM wubi98 WHERE \"value\" = ?1 ORDER BY length(\"key\") DESC, \"weight\" DESC, \"key\" ASC, rowid ASC LIMIT 1";

/// A prefix query: the typed code's own rows lead, then every longer code it prefixes by weight. The same word reached through several codes (工 at a, aaa and aaaa) is kept once per code, because ranking and removal act on the code the row arrived with.
const QUERY_SQL_86: &str = "SELECT \"key\", \"value\", \"weight\" FROM wubi86 WHERE \"key\" >= ?1 AND \"key\" < ?2 ORDER BY (\"key\" = ?1) DESC, \"weight\" DESC, \"key\" ASC, rowid ASC LIMIT ?3";
/// 与 `QUERY_SQL_86` 相同，只是读 `wubi98`。
const QUERY_SQL_98: &str = "SELECT \"key\", \"value\", \"weight\" FROM wubi98 WHERE \"key\" >= ?1 AND \"key\" < ?2 ORDER BY (\"key\" = ?1) DESC, \"weight\" DESC, \"key\" ASC, rowid ASC LIMIT ?3";

/// 通配查询：码里的 `z` 换成 GLOB 的单字符 `?`，其余部分按字面匹配，末尾接 `*` 收下所有更长编码的前缀行。
///
/// 用 GLOB 而不是 LIKE：码是小写 ASCII、`key` 列是 BINARY，字面前缀照样收窄索引扫描（`a?*` 扫 a–b），
/// LIKE 要达到同样效果得打开 `case_sensitive_like`。首位就是 `z` 时（`?bc*`）整表扫描，按权重排序，
/// 正好是「不知道首码」的用户想要的顺序。
const WILDCARD_SQL_86: &str = "SELECT \"key\", \"value\", \"weight\" FROM wubi86 WHERE \"key\" GLOB ?1 ORDER BY \"weight\" DESC, \"key\" ASC, rowid ASC LIMIT ?2";
/// 与 `WILDCARD_SQL_86` 相同，只是读 `wubi98`。
const WILDCARD_SQL_98: &str = "SELECT \"key\", \"value\", \"weight\" FROM wubi98 WHERE \"key\" GLOB ?1 ORDER BY \"weight\" DESC, \"key\" ASC, rowid ASC LIMIT ?2";

/// 14 键查询的完整编码行：组码展开后的每个编码各查一次，同一编码里按码表权重排。
const GRID_EXACT_SQL_86: &str = "SELECT \"key\", \"value\", \"weight\" FROM wubi86 WHERE \"key\" = ?1 ORDER BY \"weight\" DESC, rowid ASC LIMIT ?2";
/// 与 `GRID_EXACT_SQL_86` 相同，只是读 `wubi98`。
const GRID_EXACT_SQL_98: &str = "SELECT \"key\", \"value\", \"weight\" FROM wubi98 WHERE \"key\" = ?1 ORDER BY \"weight\" DESC, rowid ASC LIMIT ?2";
/// 14 键查询的补全行：比这个编码更长、以它开头的编码，按权重取前若干行。
const GRID_LONGER_SQL_86: &str = "SELECT \"key\", \"value\", \"weight\" FROM wubi86 WHERE \"key\" > ?1 AND \"key\" < ?2 ORDER BY \"weight\" DESC, \"key\" ASC, rowid ASC LIMIT ?3";
/// 与 `GRID_LONGER_SQL_86` 相同，只是读 `wubi98`。
const GRID_LONGER_SQL_98: &str = "SELECT \"key\", \"value\", \"weight\" FROM wubi98 WHERE \"key\" > ?1 AND \"key\" < ?2 ORDER BY \"weight\" DESC, \"key\" ASC, rowid ASC LIMIT ?3";

/// 反查按 `"value"` 找行，而发布词库只有 `("key","value")` 的唯一约束和 `("key","weight")` 索引，没有索引时每次反查都要扫整张表。每张五笔表配一个只按词条建的索引，由 [`ensure_reverse_indexes`] 在可写的代次副本里补上。
const REVERSE_INDEXES: [(&str, &str, &str); 2] = [
    (
        "wubi86",
        "idx_wubi86_value",
        "CREATE INDEX IF NOT EXISTS idx_wubi86_value ON wubi86(\"value\")",
    ),
    (
        "wubi98",
        "idx_wubi98_value",
        "CREATE INDEX IF NOT EXISTS idx_wubi98_value ON wubi98(\"value\")",
    ),
];

/// 给库里已有的五笔表补上反查索引；按表名判断而不是按文件名，所以词库无论拆成几个文件都能调用。表不存在就跳过，索引已在时只读一次 schema、不开写事务，可以每次准备代次都调用。
pub(crate) fn ensure_reverse_indexes(connection: &Connection) -> rusqlite::Result<()> {
    for (table, index, create) in REVERSE_INDEXES {
        let (has_table, has_index): (bool, bool) = connection.query_row(
            "SELECT EXISTS(SELECT 1 FROM sqlite_master WHERE type='table' AND name=?1), EXISTS(SELECT 1 FROM sqlite_master WHERE type='index' AND name=?2)",
            (table, index),
            |row| Ok((row.get(0)?, row.get(1)?)),
        )?;
        if has_table && !has_index {
            connection.execute_batch(create)?;
        }
    }
    Ok(())
}

fn query_sql(profile: WubiProfileKind) -> &'static str {
    match profile {
        WubiProfileKind::Wubi86 => QUERY_SQL_86,
        WubiProfileKind::Wubi98 => QUERY_SQL_98,
    }
}

fn grid_sql(profile: WubiProfileKind) -> (&'static str, &'static str) {
    match profile {
        WubiProfileKind::Wubi86 => (GRID_EXACT_SQL_86, GRID_LONGER_SQL_86),
        WubiProfileKind::Wubi98 => (GRID_EXACT_SQL_98, GRID_LONGER_SQL_98),
    }
}

fn wildcard_sql(profile: WubiProfileKind) -> &'static str {
    match profile {
        WubiProfileKind::Wubi86 => WILDCARD_SQL_86,
        WubiProfileKind::Wubi98 => WILDCARD_SQL_98,
    }
}

/// 把通配码转成 GLOB 模式：`z` → `?`，GLOB 自己的元字符（`*` `?` `[` `]`）按字面转义，末尾接 `*`。
///
/// 五笔码只有 `a..=y`，`z` 之外不该出现元字符，但宿主编辑过的文本仍可能带进来；转义保证它们匹配自己
/// 而不是被当成模式。
fn wildcard_pattern_into(code: &str, pattern: &mut String) {
    pattern.clear();
    pattern.reserve(code.len() + 1);
    for character in code.chars() {
        match character {
            'z' => pattern.push('?'),
            '*' | '?' | '[' | ']' => {
                pattern.push('[');
                pattern.push(character);
                pattern.push(']');
            }
            other => pattern.push(other),
        }
    }
    pattern.push('*');
}

pub struct WubiProvider {
    main_db: PathBuf,
    profile: WubiProfileKind,
    connection: Option<Connection>,
    query_upper_bound: String,
    /// 通配查询的 GLOB 模式，逐键复用容量。
    wildcard_pattern: String,
    /// 14 键组码展开出的编码，逐键复用。
    grid_expansions: Vec<String>,
    /// 14 键跨编码排序用的词频，读拼音主词库。
    frequency: WubiFrequency,
    reverse_cache: LruCache<String, Option<String>>,
}

impl WubiProvider {
    /// 测试用：码表与拼音主词库是同一个文件，与代次工作副本的布局相同。
    #[cfg(test)]
    pub fn new(main_db: &Path) -> Self {
        Self::with_pinyin_dictionary(main_db, main_db)
    }

    /// Opens lazily, read-only, on the first query. `pinyin_db` 是 14 键排序读词频的拼音主词库，可以与码表是同一个文件（代次工作副本），也可以是另一个文件（只读布局下码表单独是 `msime-wubi.db`）。
    pub fn with_pinyin_dictionary(main_db: &Path, pinyin_db: &Path) -> Self {
        Self {
            main_db: main_db.to_path_buf(),
            profile: WubiProfileKind::Wubi86,
            connection: None,
            query_upper_bound: String::new(),
            wildcard_pattern: String::new(),
            grid_expansions: Vec::new(),
            frequency: WubiFrequency::new(pinyin_db),
            reverse_cache: LruCache::new(NonZeroUsize::new(REVERSE_CACHE_CAPACITY).unwrap()),
        }
    }

    /// 切换码表版本；下一次查询起读新表。
    pub fn set_profile(&mut self, profile: WubiProfileKind) {
        self.profile = profile;
        self.reverse_cache.clear();
    }

    /// `SELECT "key","value","weight" FROM wubi86 WHERE "key" >= ?1 AND "key" < ?2 ORDER BY ("key" = ?1) DESC, "weight" DESC, "key" ASC, rowid ASC LIMIT ?3`, `?2` = the code with its last letter incremented and `?3` = 50. Rows carry `scheme = Wubi`. Any SQLite failure is an empty answer, as in the reference.
    pub fn query(&mut self, request: &QueryRequest) -> Vec<WordItem> {
        if !request.valid
            || request.scheme != SchemeType::Wubi
            || request.normalized_input.is_empty()
        {
            return Vec::new();
        }
        let profile = self.profile;
        if self.connection.is_none() {
            self.connection = open_read_only(&self.main_db);
        }
        let Some(connection) = self.connection.as_ref() else {
            return Vec::new();
        };
        let rows = if request.wubi_grid {
            super::grid::expand_into(&request.normalized_input, &mut self.grid_expansions);
            query_grid_rows(
                connection,
                profile,
                &self.grid_expansions,
                &mut self.query_upper_bound,
                &mut self.frequency,
            )
        } else if request.wubi_z_wildcard {
            wildcard_pattern_into(&request.normalized_input, &mut self.wildcard_pattern);
            query_wildcard_rows(connection, profile, &self.wildcard_pattern)
        } else {
            query_rows(
                connection,
                profile,
                &request.normalized_input,
                &mut self.query_upper_bound,
            )
        };
        match rows {
            Ok(rows) => rows,
            Err(_) => {
                // The reference dropped a statement that failed and prepared it again on the next key; closing gives the same retry.
                self.connection = None;
                Vec::new()
            }
        }
    }

    /// Closes the connection, so the next query sees what learning or removal wrote since.
    pub fn reset_cache(&mut self) {
        self.connection = None;
        self.reverse_cache.clear();
        self.frequency.reset_cache();
    }

    /// 返回词条的完整五笔 86 编码。反查只服务于候选展示，不改变候选排序或选择身份；同一词条的多个编码优先取完整编码、再取词库权重最高的一条。
    #[cfg(test)]
    pub fn reverse_code(&mut self, word: &str) -> Option<String> {
        self.reverse_code_ref(word).map(str::to_owned)
    }

    /// 把词条的完整五笔编码写入已有字符串，命中缓存时不复制新的字符串存储。
    pub fn reverse_code_into(&mut self, word: &str, destination: &mut String) -> bool {
        let Some(code) = self.reverse_code_ref(word) else {
            destination.clear();
            return false;
        };
        destination.clear();
        destination.push_str(code);
        true
    }

    fn reverse_code_ref(&mut self, word: &str) -> Option<&str> {
        if word.is_empty() {
            return None;
        }
        if self.reverse_cache.peek(word).is_none() {
            let profile = self.profile;
            let code = self
                .connection()
                .and_then(|connection| reverse_code(connection, profile, word).ok().flatten());
            self.reverse_cache.put(word.to_owned(), code);
        }
        self.reverse_cache
            .get(word)
            .and_then(|code| code.as_deref())
    }

    fn connection(&mut self) -> Option<&Connection> {
        if self.connection.is_none() {
            self.connection = open_read_only(&self.main_db);
        }
        self.connection.as_ref()
    }
}

pub(crate) fn open_read_only(path: &Path) -> Option<Connection> {
    // An empty path is how `RuntimePaths` spells a missing file; SQLite would open a private temporary database for it instead.
    if path.as_os_str().is_empty() {
        return None;
    }
    let path = crate::paths::sqlite_read_only_path_no_follow(path).ok()?;
    let connection = Connection::open_with_flags(
        &path,
        OpenFlags::SQLITE_OPEN_READ_ONLY
            | OpenFlags::SQLITE_OPEN_NOFOLLOW
            | OpenFlags::SQLITE_OPEN_NO_MUTEX,
    )
    .ok()?;
    // Another session's learning write briefly holds the commit lock; waiting keeps a keystroke that lands in that window from showing an empty list.
    connection.busy_timeout(BUSY_TIMEOUT).ok()?;
    Some(connection)
}

/// The exclusive upper bound of every code `code` prefixes: its last letter incremented, so `ab` gives `ac` and `az` gives `a{`. Codes are ASCII letters, where that is the reference's last-byte increment.
fn prefix_upper_bound_into(code: &str, upper: &mut String) {
    upper.clear();
    upper.push_str(code);
    if let Some(last) = upper.pop() {
        upper.push(char::from_u32(u32::from(last) + 1).unwrap_or(char::MAX));
    }
}

fn query_rows(
    connection: &Connection,
    profile: WubiProfileKind,
    code: &str,
    upper: &mut String,
) -> rusqlite::Result<Vec<WordItem>> {
    let mut statement = connection.prepare_cached(query_sql(profile))?;
    prefix_upper_bound_into(code, upper);
    let mut rows = statement.query((code, upper.as_str(), QUERY_LIMIT))?;
    collect_rows(&mut rows)
}

/// 读出行集：与 [`query_rows`] 相同的读法，前缀和通配两条语句共用。
fn collect_rows(rows: &mut rusqlite::Rows<'_>) -> rusqlite::Result<Vec<WordItem>> {
    let mut candidates = Vec::new();
    while let Some(row) = rows.next()? {
        // The reference skipped rows whose key or value read back as NULL.
        let (ValueRef::Text(key), ValueRef::Text(value)) = (row.get_ref(0)?, row.get_ref(1)?)
        else {
            continue;
        };
        let key = String::from_utf8_lossy(key).into_owned();
        let value = String::from_utf8_lossy(value).into_owned();
        let weight = match row.get_ref(2)? {
            ValueRef::Integer(weight) => weight,
            ValueRef::Real(weight) => weight as i64,
            ValueRef::Null | ValueRef::Text(_) | ValueRef::Blob(_) => 0,
        };
        if candidates.is_empty() {
            candidates.reserve_exact(QUERY_LIMIT as usize);
        }
        let mut item = WordItem::new(key, value, weight, CandidateSource::Database, "");
        item.scheme = SchemeType::Wubi;
        candidates.push(item);
    }
    Ok(candidates)
}

/// 14 键查询：`expansions` 是组码展开出的全部编码（[`super::grid::expand_into`]）。
///
/// 完整编码的行在前。它们来自不同的编码，码表权重只排同一编码里的先后，跨编码比的是词频（[`WubiFrequency`]）。同一编码里码表的先后（包括用户调频后的先后）保持不变：每行的分数取它和同一编码里排在它后面的行的最大词频，于是一个编码的首行带着这个编码最常用的那个词去和别的编码比，后面的行不会越过前面的行。分数相同时按码表权重，再按编码。
///
/// 补全行（更长的编码）在后，与 26 键一样按码表权重。总数同样最多 `QUERY_LIMIT` 行。
fn query_grid_rows(
    connection: &Connection,
    profile: WubiProfileKind,
    expansions: &[String],
    upper: &mut String,
    frequency: &mut WubiFrequency,
) -> rusqlite::Result<Vec<WordItem>> {
    let (exact_sql, longer_sql) = grid_sql(profile);
    let mut scored: Vec<(i64, WordItem)> = Vec::new();
    {
        let mut statement = connection.prepare_cached(exact_sql)?;
        for code in expansions {
            let mut rows = statement.query((code.as_str(), QUERY_LIMIT))?;
            let rows = collect_rows(&mut rows)?;
            let start = scored.len();
            scored.extend(rows.into_iter().map(|item| (0, item)));
            let mut best = 0;
            for (score, item) in scored[start..].iter_mut().rev() {
                best = best.max(frequency.weight(&item.word));
                *score = best;
            }
        }
    }
    scored.sort_by(|(left_score, left), (right_score, right)| {
        right_score
            .cmp(left_score)
            .then(right.weight.cmp(&left.weight))
            .then(left.pinyin.cmp(&right.pinyin))
    });
    let mut candidates: Vec<WordItem> = scored.into_iter().map(|(_, item)| item).collect();
    let limit = QUERY_LIMIT as usize;
    if candidates.len() < limit {
        let mut longer = Vec::new();
        let mut statement = connection.prepare_cached(longer_sql)?;
        for code in expansions {
            prefix_upper_bound_into(code, upper);
            let mut rows = statement.query((code.as_str(), upper.as_str(), QUERY_LIMIT))?;
            longer.extend(collect_rows(&mut rows)?);
        }
        longer.sort_by(|left, right| {
            right
                .weight
                .cmp(&left.weight)
                .then(left.pinyin.cmp(&right.pinyin))
        });
        longer.truncate(limit - candidates.len());
        candidates.extend(longer);
    }
    candidates.truncate(limit);
    Ok(candidates)
}

/// 通配查询的行收集：与 [`query_rows`] 同一个读法，只是绑定模式而不是范围。
fn query_wildcard_rows(
    connection: &Connection,
    profile: WubiProfileKind,
    pattern: &str,
) -> rusqlite::Result<Vec<WordItem>> {
    let mut statement = connection.prepare_cached(wildcard_sql(profile))?;
    let mut rows = statement.query((pattern, QUERY_LIMIT))?;
    collect_rows(&mut rows)
}

fn reverse_code(
    connection: &Connection,
    profile: WubiProfileKind,
    word: &str,
) -> rusqlite::Result<Option<String>> {
    // 每次刷新会对几十到几百个候选逐个反查；有了索引后单次查询只要几微秒，重复解析 SQL 反而成了大头，所以复用已准备的语句。
    connection
        .prepare_cached(match profile {
            WubiProfileKind::Wubi86 => REVERSE_QUERY_SQL_86,
            WubiProfileKind::Wubi98 => REVERSE_QUERY_SQL_98,
        })?
        .query_row([word], |row| row.get(0))
        .optional()
}

#[cfg(test)]
mod tests {
    use super::*;

    struct Fixture {
        _root: tempfile::TempDir,
        provider: WubiProvider,
    }

    fn fixture(sql: &str) -> Fixture {
        let root = tempfile::tempdir().expect("temporary directory");
        let main_db = root.path().join("msime-pinyin.db");
        Connection::open(&main_db)
            .expect("fixture database")
            .execute_batch(sql)
            .expect("fixture SQL");
        let provider = WubiProvider::new(&main_db);
        Fixture {
            _root: root,
            provider,
        }
    }

    fn request(code: &str) -> QueryRequest {
        QueryRequest {
            scheme: SchemeType::Wubi,
            raw_input: code.to_owned(),
            raw_input_with_cases: code.to_owned(),
            normalized_input: code.to_owned(),
            valid: !code.is_empty(),
            ..QueryRequest::default()
        }
    }

    fn rows(provider: &mut WubiProvider, code: &str) -> Vec<(String, String, i64)> {
        provider
            .query(&request(code))
            .into_iter()
            .map(|item| {
                (
                    item.pinyin.into_string(),
                    item.word.into_string(),
                    item.weight,
                )
            })
            .collect()
    }

    fn wildcard_request(code: &str) -> QueryRequest {
        QueryRequest {
            wubi_z_wildcard: true,
            ..request(code)
        }
    }

    fn wildcard_rows(provider: &mut WubiProvider, code: &str) -> Vec<(String, String, i64)> {
        provider
            .query(&wildcard_request(code))
            .into_iter()
            .map(|item| {
                (
                    item.pinyin.into_string(),
                    item.word.into_string(),
                    item.weight,
                )
            })
            .collect()
    }

    fn row(code: &str, word: &str, weight: i64) -> (String, String, i64) {
        (code.to_owned(), word.to_owned(), weight)
    }

    /// 五笔 14 键：组码 `q` 是 QW 键，`x` 是 ZX 键。
    const GRID_WUBI_FIXTURE: &str = "CREATE TABLE wubi86(key TEXT,value TEXT,weight INTEGER);\
        INSERT INTO wubi86 VALUES('q','我',20),('q','金',10),('w','人',20),('w','八',10),\
        ('qq','多',20),('qw','欠',10),('wq','你',10),('ww','从',10),\
        ('wqiy','你',20),('qqiy','铄',20),('wwiy','人流',30),\
        ('x','经',20),('xx','弱',20),('vb','好',10);";

    fn grid_words(provider: &mut WubiProvider, code: &str) -> Vec<(String, String)> {
        provider
            .query(&QueryRequest {
                wubi_grid: true,
                ..request(code)
            })
            .into_iter()
            .map(|item| (item.pinyin.into_string(), item.word.into_string()))
            .collect()
    }

    fn pairs(expected: &[(&str, &str)]) -> Vec<(String, String)> {
        expected
            .iter()
            .map(|(code, word)| ((*code).to_owned(), (*word).to_owned()))
            .collect()
    }

    fn grid_fixture() -> Fixture {
        fixture(&format!(
            "{}{GRID_WUBI_FIXTURE}",
            crate::wubi::frequency::tests::PINYIN_FIXTURE
        ))
    }

    #[test]
    fn a_grid_code_ranks_the_codes_of_its_keys_by_word_frequency() {
        let mut fixture = grid_fixture();
        // QW QW 展开成 qq、qw、wq、ww：完整编码的行按词频排（你 > 多 > 从 > 欠），补全行在后，照码表权重。
        assert_eq!(
            grid_words(&mut fixture.provider, "qq"),
            pairs(&[
                ("wq", "你"),
                ("qq", "多"),
                ("ww", "从"),
                ("qw", "欠"),
                ("wwiy", "人流"),
                ("qqiy", "铄"),
                ("wqiy", "你"),
            ])
        );
        // ZX 只代表 x。
        assert_eq!(
            grid_words(&mut fixture.provider, "x"),
            pairs(&[("x", "经"), ("xx", "弱")])
        );
        assert!(grid_words(&mut fixture.provider, "cb")
            .iter()
            .any(|(code, _)| code == "vb"));
    }

    #[test]
    fn a_grid_code_keeps_the_order_inside_each_code() {
        let mut fixture = grid_fixture();
        // 金、人、八 在拼音词库里没有词频：q 的首行「我」带着它的词频领先，同一编码里「金」仍在「我」后面，没有词频的几行按码表权重。
        assert_eq!(
            grid_words(&mut fixture.provider, "q")[..4],
            pairs(&[("q", "我"), ("w", "人"), ("q", "金"), ("w", "八")])
        );
        // 用户把「金」调到「我」前面以后，金继承这一编码最高的词频，仍排在整组最前，同一编码里的先后跟着码表。
        Connection::open(&fixture.provider.main_db)
            .unwrap()
            .execute_batch("UPDATE wubi86 SET weight=30 WHERE key='q' AND value='金';")
            .unwrap();
        fixture.provider.reset_cache();
        assert_eq!(
            grid_words(&mut fixture.provider, "q")[..4],
            pairs(&[("q", "金"), ("q", "我"), ("w", "人"), ("w", "八")])
        );
    }

    #[test]
    fn a_grid_code_falls_back_to_table_weights_without_the_pinyin_dictionary() {
        let mut fixture = fixture(GRID_WUBI_FIXTURE);
        assert_eq!(
            grid_words(&mut fixture.provider, "qq")[..4],
            pairs(&[("qq", "多"), ("qw", "欠"), ("wq", "你"), ("ww", "从")])
        );
    }

    /// 在真实的 86 码表和拼音主词库上量 14 键：每个单字和词按自己的每个编码逐键打，记下每一键的查询耗时，以及打满编码时目标在第几位（按词频加权）。
    ///
    /// 需要一份代次工作副本那样的主词库（拼音各表加 `wubi86` 和索引），路径放在 `MSIME_WUBI_GRID_DB`：
    /// `MSIME_WUBI_GRID_DB=… cargo test -p msime-engine --release --lib wubi_grid_real_table -- --ignored --nocapture`。
    #[test]
    #[ignore = "需要真实词库，见文档注释"]
    fn wubi_grid_real_table_latency_and_rank() {
        use std::time::{Duration, Instant};
        let path = std::path::PathBuf::from(
            std::env::var_os("MSIME_WUBI_GRID_DB").expect("MSIME_WUBI_GRID_DB"),
        );
        let connection = Connection::open(&path).unwrap();
        let rows: Vec<(String, String)> = connection
            .prepare("SELECT key, value FROM wubi86 ORDER BY rowid")
            .unwrap()
            .query_map((), |row| {
                Ok((row.get::<_, String>(0)?, row.get::<_, String>(1)?))
            })
            .unwrap()
            .filter_map(std::result::Result::ok)
            .filter(|(code, _)| {
                (1..=4).contains(&code.len())
                    && code.bytes().all(|letter| (b'a'..=b'y').contains(&letter))
            })
            .collect();
        let mut provider = WubiProvider::new(&path);
        let cold = Instant::now();
        provider.query(&QueryRequest {
            wubi_grid: true,
            ..request("q")
        });
        let cold = cold.elapsed();
        let mut frequency = WubiFrequency::new(&path);
        let mut latencies: [Vec<Duration>; 4] = Default::default();
        // 同一批编码按 26 键逐字母打的耗时，作对照。
        let mut baseline: [Vec<Duration>; 4] = Default::default();
        // (词频加权的总数, 首位, 前三, 前五)，单字和词分开。
        let mut ranks = [[0f64; 4]; 2];
        let mut unranked = 0usize;
        for (index, (code, word)) in rows.iter().enumerate() {
            let groups: String = code
                .bytes()
                .map(|letter| char::from(super::super::grid::representative_of(letter).unwrap()))
                .collect();
            // 逐键的耗时只抽样量，排名每行都算。
            if index % 16 == 0 {
                for length in 1..=groups.len() {
                    let started = Instant::now();
                    provider.query(&QueryRequest {
                        wubi_grid: true,
                        ..request(&groups[..length])
                    });
                    latencies[length - 1].push(started.elapsed());
                    let started = Instant::now();
                    provider.query(&request(&code[..length]));
                    baseline[length - 1].push(started.elapsed());
                }
            }
            let weight = frequency.weight(word) as f64;
            if weight <= 0.0 {
                unranked += 1;
                continue;
            }
            let answer = provider.query(&QueryRequest {
                wubi_grid: true,
                ..request(&groups)
            });
            let position = answer
                .iter()
                .position(|item| item.pinyin.as_str() == code && item.word.as_str() == word)
                .unwrap_or(usize::MAX);
            let kind = usize::from(word.chars().count() > 1);
            ranks[kind][0] += weight;
            ranks[kind][1] += weight * f64::from(u8::from(position < 1));
            ranks[kind][2] += weight * f64::from(u8::from(position < 3));
            ranks[kind][3] += weight * f64::from(u8::from(position < 5));
        }
        eprintln!(
            "rows {} (no frequency {unranked}), cold first query {cold:?}",
            rows.len()
        );
        for (length, samples) in latencies.iter_mut().chain(baseline.iter_mut()).enumerate() {
            samples.sort_unstable();
            let at = |quantile: f64| samples[((samples.len() - 1) as f64 * quantile) as usize];
            eprintln!(
                "{} {} key(s): n={} p50={:?} p95={:?} p99={:?} max={:?}",
                if length < 4 { "grid" } else { "26-key" },
                length % 4 + 1,
                samples.len(),
                at(0.5),
                at(0.95),
                at(0.99),
                samples.last().unwrap()
            );
        }
        for (kind, [total, top1, top3, top5]) in ["characters", "words"].iter().zip(ranks) {
            eprintln!(
                "{kind}: weighted top-1 {:.3} top-3 {:.3} top-5 {:.3}",
                top1 / total,
                top3 / total,
                top5 / total
            );
        }
        let p95 = |samples: &[Duration]| samples[(samples.len() - 1) * 95 / 100];
        assert!(latencies
            .iter()
            .all(|samples| p95(samples) < Duration::from_millis(20)));
    }

    #[test]
    fn a_grid_code_answers_at_most_the_query_limit() {
        let mut sql = String::from("CREATE TABLE wubi86(key TEXT,value TEXT,weight INTEGER);");
        for index in 0..40 {
            sql.push_str(&format!(
                "INSERT INTO wubi86 VALUES('q','甲{index}',{index}),('wqiy','乙{index}',{index});"
            ));
        }
        let mut fixture = fixture(&sql);
        let words = grid_words(&mut fixture.provider, "q");
        assert_eq!(words.len(), QUERY_LIMIT as usize);
        // 四十行完整编码全部排在补全行前面。
        assert!(words[..40].iter().all(|(code, _)| code == "q"));
        assert!(words[40..].iter().all(|(code, _)| code == "wqiy"));
    }

    // test_wubi_input_session.cpp:68-73. The pinned assertions there are stale (tests-inventory §2.1); these follow the overlay order the golden `wubi_prefix_codes` records.
    const SESSION_FIXTURE: &str = "CREATE TABLE wubi86(key TEXT,value TEXT,weight INTEGER);\
        INSERT INTO wubi86 VALUES('w','人',20);\
        INSERT INTO wubi86 VALUES('wq','你',10);\
        INSERT INTO wubi86 VALUES('wqb','爷',20);\
        INSERT INTO wubi86 VALUES('wqi','你',10);\
        INSERT INTO wubi86 VALUES('wqbb','父子',30);";

    #[test]
    fn the_profile_picks_the_table() {
        let mut fixture = fixture(
            "CREATE TABLE wubi86(key TEXT,value TEXT,weight INTEGER);\
             INSERT INTO wubi86 VALUES('kl','号',10);\
             CREATE TABLE wubi98(key TEXT,value TEXT,weight INTEGER);\
             INSERT INTO wubi98 VALUES('kg','号',10);",
        );
        let provider = &mut fixture.provider;
        assert_eq!(rows(provider, "kl"), vec![row("kl", "号", 10)]);
        assert!(rows(provider, "kg").is_empty());
        provider.set_profile(WubiProfileKind::Wubi98);
        assert_eq!(rows(provider, "kg"), vec![row("kg", "号", 10)]);
        assert!(rows(provider, "kl").is_empty());
    }

    #[test]
    fn exact_code_leads_then_weight_without_word_dedup() {
        let mut fixture = fixture(SESSION_FIXTURE);
        let provider = &mut fixture.provider;
        assert_eq!(
            rows(provider, "wq"),
            vec![
                row("wq", "你", 10),
                row("wqbb", "父子", 30),
                row("wqb", "爷", 20),
                row("wqi", "你", 10),
            ]
        );
        assert_eq!(
            rows(provider, "w"),
            vec![
                row("w", "人", 20),
                row("wqbb", "父子", 30),
                row("wqb", "爷", 20),
                row("wq", "你", 10),
                row("wqi", "你", 10),
            ]
        );
        assert_eq!(rows(provider, "wqbb"), vec![row("wqbb", "父子", 30)]);
        assert!(rows(provider, "wx").is_empty());
    }

    #[test]
    fn rows_are_tagged_wubi_with_an_empty_canonical_key() {
        let mut fixture = fixture(SESSION_FIXTURE);
        let items = fixture.provider.query(&request("w"));
        assert!(items.iter().all(|item| item.scheme == SchemeType::Wubi
            && item.source == CandidateSource::Database
            && item.canonical_pinyin.is_empty()));
    }

    // engine-bridge tests.rs:191: 55 `b..` rows reach the host as exactly 50.
    #[test]
    fn prefix_query_is_bounded() {
        let mut sql = String::from("CREATE TABLE wubi86(key TEXT,value TEXT,weight INTEGER);");
        for index in 0..55 {
            sql.push_str(&format!(
                "INSERT INTO wubi86 VALUES('b{}','合成{index:02}',{});",
                char::from(b'a' + (index % 25) as u8),
                1_000 - index
            ));
        }
        let mut fixture = fixture(&sql);
        let words: Vec<String> = fixture
            .provider
            .query(&request("b"))
            .into_iter()
            .map(|item| item.word.into_string())
            .collect();
        let expected: Vec<String> = (0..QUERY_LIMIT)
            .map(|index| format!("合成{index:02}"))
            .collect();
        assert_eq!(words, expected);
    }

    #[test]
    fn last_letter_bound_covers_z_codes() {
        let mut fixture = fixture(
            "CREATE TABLE wubi86(key TEXT,value TEXT,weight INTEGER);\
             INSERT INTO wubi86 VALUES('yz','甲',1);\
             INSERT INTO wubi86 VALUES('yzz','乙',2);\
             INSERT INTO wubi86 VALUES('z','丙',3);",
        );
        let mut upper = String::new();
        prefix_upper_bound_into("az", &mut upper);
        assert_eq!(upper, "a{");
        assert_eq!(
            rows(&mut fixture.provider, "yz"),
            vec![row("yz", "甲", 1), row("yzz", "乙", 2)]
        );
    }

    #[test]
    fn a_z_in_the_code_matches_any_one_letter_when_the_wildcard_is_on() {
        let mut fixture = fixture(
            "CREATE TABLE wubi86(key TEXT,value TEXT,weight INTEGER);\
             INSERT INTO wubi86 VALUES('wqiy','你',100);\
             INSERT INTO wubi86 VALUES('wqiy','伱',10);\
             INSERT INTO wubi86 VALUES('wqvb','你好',300);\
             INSERT INTO wubi86 VALUES('abcd','合成',200);",
        );
        let provider = &mut fixture.provider;
        // `wqzy` 只有 `wqiy` 一列对得上：`z` 匹配该位置的任意一个字母，其余按字面。
        assert_eq!(
            wildcard_rows(provider, "wqzy"),
            vec![row("wqiy", "你", 100), row("wqiy", "伱", 10)]
        );
        // 首位是 `z` 时整表扫描，按权重降序：`zqiy` → `?qiy*` 匹配 `wqiy`。
        assert_eq!(
            wildcard_rows(provider, "zqiy"),
            vec![row("wqiy", "你", 100), row("wqiy", "伱", 10)]
        );
        // 位置对不上就没有行：`zvbb` → `?vbb*`，而码表里四个字母的第 2 位是 `q`。
        assert!(wildcard_rows(provider, "zvbb").is_empty());
    }

    #[test]
    fn a_wildcard_query_does_not_leak_glob_metacharacters() {
        let mut fixture = fixture(
            "CREATE TABLE wubi86(key TEXT,value TEXT,weight INTEGER);\
             INSERT INTO wubi86 VALUES('a[b','甲',100);\
             INSERT INTO wubi86 VALUES('a*b','乙',90);\
             INSERT INTO wubi86 VALUES('axb','丙',80);",
        );
        let provider = &mut fixture.provider;
        // 宿主编辑进来的 `[` 与 `*` 匹配它们自己，不被当成模式。
        assert_eq!(wildcard_rows(provider, "a[b"), vec![row("a[b", "甲", 100)]);
        assert_eq!(wildcard_rows(provider, "a*b"), vec![row("a*b", "乙", 90)]);
        // `z` 仍是「任意一个字母」，所以 `azb` 三行都对得上，按权重降序。
        assert_eq!(
            wildcard_rows(provider, "azb"),
            vec![
                row("a[b", "甲", 100),
                row("a*b", "乙", 90),
                row("axb", "丙", 80),
            ]
        );
    }

    #[test]
    fn the_wildcard_only_takes_the_pattern_path_when_the_code_holds_z() {
        // 混输单独打开时 `z` 是普通拼音字母，查询不能被当成通配：`wubi_z_wildcard` 是方案按「码里有 z」算出来的。
        let mut fixture = fixture(SESSION_FIXTURE);
        let provider = &mut fixture.provider;
        let plain = request("wq");
        assert!(!plain.wubi_z_wildcard);
        assert_eq!(
            rows(provider, "wq"),
            vec![
                row("wq", "你", 10),
                row("wqbb", "父子", 30),
                row("wqb", "爷", 20),
                row("wqi", "你", 10),
            ]
        );
    }

    #[test]
    fn prefix_upper_bound_reuses_destination_capacity() {
        let mut upper = String::with_capacity(16);
        prefix_upper_bound_into("az", &mut upper);
        assert_eq!(upper, "a{");
        assert!(upper.capacity() >= 16);

        prefix_upper_bound_into("a", &mut upper);
        assert_eq!(upper, "b");
    }

    #[test]
    fn null_rows_are_skipped_and_null_weight_reads_zero() {
        let mut fixture = fixture(
            "CREATE TABLE wubi86(key TEXT,value TEXT,weight INTEGER);\
             INSERT INTO wubi86 VALUES('a',NULL,5);\
             INSERT INTO wubi86 VALUES('a','工',NULL);",
        );
        assert_eq!(rows(&mut fixture.provider, "a"), vec![row("a", "工", 0)]);
    }

    #[test]
    fn empty_prefix_query_does_not_reserve_candidate_page() {
        let mut fixture = fixture(
            "CREATE TABLE wubi86(key TEXT,value TEXT,weight INTEGER);\
             INSERT INTO wubi86 VALUES('a',NULL,5);",
        );
        let candidates = fixture.provider.query(&request("a"));
        assert!(candidates.is_empty());
        assert_eq!(candidates.capacity(), 0);
    }

    #[test]
    fn missing_table_or_invalid_request_is_empty() {
        let mut other = fixture("CREATE TABLE other(x);");
        assert!(rows(&mut other.provider, "a").is_empty());

        let mut wubi = fixture(SESSION_FIXTURE);
        assert!(rows(&mut wubi.provider, "").is_empty());
        let mut quanpin = request("w");
        quanpin.scheme = SchemeType::Quanpin;
        assert!(wubi.provider.query(&quanpin).is_empty());
    }

    #[test]
    fn missing_database_is_empty() {
        let root = tempfile::tempdir().expect("temporary directory");
        let mut provider = WubiProvider::new(&root.path().join("absent.db"));
        assert!(provider.query(&request("a")).is_empty());
        assert!(!root.path().join("absent.db").exists());
    }

    #[test]
    fn reset_cache_sees_rows_written_since() {
        let mut fixture = fixture(SESSION_FIXTURE);
        assert_eq!(rows(&mut fixture.provider, "wqbb").len(), 1);
        Connection::open(&fixture.provider.main_db)
            .expect("writer")
            .execute("UPDATE wubi86 SET weight=99 WHERE key='wqbb'", ())
            .expect("update");
        fixture.provider.reset_cache();
        assert_eq!(
            rows(&mut fixture.provider, "wqbb"),
            vec![row("wqbb", "父子", 99)]
        );
    }

    fn reverse_plan(connection: &Connection, profile: WubiProfileKind) -> String {
        let sql = match profile {
            WubiProfileKind::Wubi86 => REVERSE_QUERY_SQL_86,
            WubiProfileKind::Wubi98 => REVERSE_QUERY_SQL_98,
        };
        let mut statement = connection
            .prepare(&format!("EXPLAIN QUERY PLAN {sql}"))
            .unwrap();
        let details: Vec<String> = statement
            .query_map(["你好"], |row| row.get(3))
            .unwrap()
            .map(Result::unwrap)
            .collect();
        details.join("; ")
    }

    #[test]
    fn reverse_indexes_are_created_once_for_the_tables_present() {
        let both = fixture(
            "CREATE TABLE wubi86(key TEXT,value TEXT,weight INTEGER,UNIQUE(key,value));\
             CREATE TABLE wubi98(key TEXT,value TEXT,weight INTEGER,UNIQUE(key,value));",
        );
        let connection = Connection::open(&both.provider.main_db).unwrap();
        assert!(reverse_plan(&connection, WubiProfileKind::Wubi86).contains("SCAN wubi86"));
        ensure_reverse_indexes(&connection).unwrap();
        ensure_reverse_indexes(&connection).unwrap();
        let indexes: i64 = connection
            .query_row(
                "SELECT count(*) FROM sqlite_master WHERE type='index' AND name IN ('idx_wubi86_value','idx_wubi98_value')",
                [],
                |row| row.get(0),
            )
            .unwrap();
        assert_eq!(indexes, 2);
        assert!(reverse_plan(&connection, WubiProfileKind::Wubi86)
            .contains("USING INDEX idx_wubi86_value"));
        assert!(reverse_plan(&connection, WubiProfileKind::Wubi98)
            .contains("USING INDEX idx_wubi98_value"));

        // 没有五笔表的库（例如 english.db）原样不动。
        let other = fixture("CREATE TABLE english_words(word TEXT);");
        let connection = Connection::open(&other.provider.main_db).unwrap();
        ensure_reverse_indexes(&connection).unwrap();
        let tables: i64 = connection
            .query_row("SELECT count(*) FROM sqlite_master", [], |row| row.get(0))
            .unwrap();
        assert_eq!(tables, 1);
    }

    #[test]
    fn the_reverse_index_does_not_change_which_code_is_shown() {
        // 同一词条的多个编码：完整编码优先，同长度按权重，再按编码；索引只改变查法，不改变答案。
        let sql = "CREATE TABLE wubi86(key TEXT,value TEXT,weight INTEGER,UNIQUE(key,value));\
             INSERT INTO wubi86 VALUES('a','工',900);\
             INSERT INTO wubi86 VALUES('aaaa','工',10);\
             INSERT INTO wubi86 VALUES('aaab','工',20);\
             INSERT INTO wubi86 VALUES('wqvb','你好',300);\
             INSERT INTO wubi86 VALUES('wqvc','你好',300);\
             INSERT INTO wubi86 VALUES('wq','你',10);";
        let words = ["工", "你好", "你", "缺"];
        let mut plain = fixture(sql);
        let before: Vec<Option<String>> = words
            .iter()
            .map(|word| plain.provider.reverse_code(word))
            .collect();
        assert_eq!(
            before,
            [
                Some("aaab".to_owned()),
                Some("wqvb".to_owned()),
                Some("wq".to_owned()),
                None
            ]
        );
        let mut indexed = fixture(sql);
        ensure_reverse_indexes(&Connection::open(&indexed.provider.main_db).unwrap()).unwrap();
        let after: Vec<Option<String>> = words
            .iter()
            .map(|word| indexed.provider.reverse_code(word))
            .collect();
        assert_eq!(after, before);
    }

    #[test]
    fn reverse_cache_does_not_grow_without_bound() {
        let mut fixture = fixture("CREATE TABLE wubi86(key TEXT,value TEXT,weight INTEGER);");
        for index in 0..=1024 {
            let word = format!("合成{index:04}");
            assert_eq!(fixture.provider.reverse_code(&word), None);
        }
        assert!(fixture.provider.reverse_cache.len() <= 1024);
    }

    #[test]
    fn cached_reverse_code_fills_existing_storage() {
        let mut fixture = fixture(
            "CREATE TABLE wubi86(key TEXT,value TEXT,weight INTEGER);\
             INSERT INTO wubi86 VALUES('aaab','你',10);",
        );
        assert_eq!(fixture.provider.reverse_code("你").as_deref(), Some("aaab"));
        let mut destination = String::with_capacity(8);
        destination.push_str("old");
        let pointer = destination.as_ptr();

        let ((), allocations) = crate::ime::personal_rerank::allocations::count(|| {
            assert!(fixture.provider.reverse_code_into("你", &mut destination));
        });

        assert_eq!(allocations, 0);
        assert_eq!(destination, "aaab");
        assert_eq!(destination.as_ptr(), pointer);
    }
}