msime-engine-capi 0.1.0

//! 会话句柄与会话上的函数：建与释放、设置、按键、状态与候选、选择与逐候选学习。
//!
//! 一个句柄里是一把互斥锁护着的会话。同一会话的调用由调用方串行，锁只用 `try_lock`：拿不到就是两个线程同时在调，返回 `MSIME_ENGINE_BUSY`，不等待。核心 `Session` 是 `Send`，所以会话可以在任何线程上用，只是不能并发。会话里的 panic 挡在边界内并作废会话，之后的调用都返回 `MSIME_ENGINE_PANIC`。

use std::ffi::c_char;
use std::sync::{Mutex, TryLockError};

use msime_engine::{
    CandidateEdge, Command, DictionaryAccess, FirstPageRows, KeyResult, LocalInputMode, SchemeType,
    Session, SessionSnapshot,
};
use serde_json::{json, Value};

use crate::abi::{
    check_output, guard, input_str, msime_engine_candidate, msime_engine_result,
    msime_engine_state, msime_engine_str, panic_message, write_owned, write_sized, Failure,
    Outcome,
};
use crate::{
    MSIME_ENGINE_BUSY, MSIME_ENGINE_CANDIDATE_ANSWERS_KEY, MSIME_ENGINE_CANDIDATE_FUZZY,
    MSIME_ENGINE_CANDIDATE_SENTENCE, MSIME_ENGINE_EDGE_FIRST_HAN, MSIME_ENGINE_EDGE_LAST_HAN,
    MSIME_ENGINE_KEY_SHIFT_ONLY, MSIME_ENGINE_OPTION_CHINESE_PUNCT,
    MSIME_ENGINE_OPTION_DEDICATED_ENGLISH, MSIME_ENGINE_OPTION_FIRST_PAGE_ROWS,
    MSIME_ENGINE_OPTION_HELPCODE_ENABLED, MSIME_ENGINE_OPTION_HELPCODE_SCHEMA,
    MSIME_ENGINE_OPTION_PAIRED_PUNCT, MSIME_ENGINE_OPTION_PERSONAL_CONTEXT,
    MSIME_ENGINE_OPTION_PREDICTION_ALLOWED, MSIME_ENGINE_OPTION_PUNCT_LOCK,
    MSIME_ENGINE_OPTION_RESCORING_CONTEXT, MSIME_ENGINE_PANIC, MSIME_ENGINE_STALE,
    MSIME_ENGINE_STATE_CANDIDATE_LIST_OPEN, MSIME_ENGINE_STATE_DEDICATED_ENGLISH,
    MSIME_ENGINE_STATE_PREDICTION, MSIME_ENGINE_STATE_TAKES_SEPARATOR, MSIME_ENGINE_UNSUPPORTED,
};

/// 不透明的会话句柄，由 `msime_engine_session_new` 建、`msime_engine_session_free` 释放。
pub struct msime_engine_session {
    state: Mutex<SessionState>,
}

// 句柄会被交给任意线程：锁里的东西必须能在线程间移动。
const _: fn() = || {
    fn shared_between_threads<T: Send + Sync>() {}
    shared_between_threads::<msime_engine_session>();
};

/// 字段按声明顺序析构：会话先结束（写下学习、交还日志连接），之后才放掉词库租约，维护在会话写完之前拿不到锁。
struct SessionState {
    session: Session,
    _access: DictionaryAccess,
    /// 之前的调用在库里 panic 过，会话状态不可信。
    poisoned: bool,
    /// 当前修订号下的快照；每次改变状态的调用都清掉，`msime_engine_state_get` 和 `msime_engine_candidate_get` 借出的字符串指向它。
    snapshot: Option<SessionSnapshot>,
    /// 上一次改变状态的调用的结果，`msime_engine_result` 借出的 `commit` 和 `diagnostic` 指向它。
    result: KeyResult,
}

impl SessionState {
    /// 改变状态之前：之前借出的字符串到此作废。
    fn begin_change(&mut self) {
        self.snapshot = None;
    }

    /// 宿主看的快照：全拼的 `preedit` 按音节分开，与 msime 自己的宿主一致。
    fn snapshot(&mut self) -> &SessionSnapshot {
        self.snapshot
            .get_or_insert_with(|| self.session.display_snapshot())
    }

    fn check_revision(&self, revision: u64) -> Outcome {
        let current = self.session.candidate_revision();
        if revision != current {
            return Err(Failure::new(
                MSIME_ENGINE_STALE,
                format!("revision {revision} is stale; the candidates are at revision {current}"),
            ));
        }
        Ok(())
    }

    /// 记下结果并写给调用方（`output` 可以是 NULL）。
    ///
    /// # Safety
    /// 同 [`write_sized`]。
    unsafe fn finish(&mut self, result: KeyResult, output: *mut msime_engine_result) -> Outcome {
        self.result = result;
        if output.is_null() {
            return Ok(());
        }
        let result = &self.result;
        let value = msime_engine_result {
            struct_size: 0,
            handled: u32::from(result.handled),
            has_commit: u32::from(result.commit.is_some()),
            diagnostic_code: result
                .diagnostic_code()
                .map_or(0, |code| u32::from(code.value())),
            revision: self.session.candidate_revision(),
            commit: msime_engine_str::borrow(result.commit.as_deref().unwrap_or_default()),
            diagnostic: msime_engine_str::borrow(result.diagnostic.as_deref().unwrap_or_default()),
        };
        // SAFETY: 调用方的前提。
        unsafe { write_sized(output, value, "result") }
    }
}

/// 在会话上执行一次调用：空句柄、并发调用、已作废的会话各自报错；`body` 里的 panic 作废会话。
fn with_session(
    handle: *const msime_engine_session,
    body: impl FnOnce(&mut SessionState) -> Outcome,
) -> i32 {
    guard(|| {
        // SAFETY: 非空的句柄来自 `msime_engine_session_new`，调用方保证它还没被释放。
        let Some(handle) = (unsafe { handle.as_ref() }) else {
            return Err(Failure::null("session"));
        };
        let mut state = match handle.state.try_lock() {
            Ok(state) => state,
            Err(TryLockError::WouldBlock) => return Err(Failure::new(
                MSIME_ENGINE_BUSY,
                "another thread is calling this session; calls into one session must not overlap",
            )),
            // `body` 的 panic 在下面就被接住，锁不会因此中毒；真中毒了也只能当作废处理。
            Err(TryLockError::Poisoned(_)) => {
                return Err(Failure::new(
                    MSIME_ENGINE_PANIC,
                    "session is unusable after a panic; free it",
                ))
            }
        };
        if state.poisoned {
            return Err(Failure::new(
                MSIME_ENGINE_PANIC,
                "session is unusable after a panic; free it",
            ));
        }
        let state = &mut *state;
        match std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| body(state))) {
            Ok(outcome) => outcome,
            Err(payload) => {
                state.poisoned = true;
                Err(Failure::new(
                    MSIME_ENGINE_PANIC,
                    panic_message(payload.as_ref()),
                ))
            }
        }
    })
}

/// 下标转成引擎的 `usize`。
fn index(value: u32) -> usize {
    value as usize
}

fn local_mode_value(mode: LocalInputMode) -> u32 {
    match mode {
        LocalInputMode::None => crate::MSIME_ENGINE_LOCAL_MODE_NONE,
        LocalInputMode::Unicode => crate::MSIME_ENGINE_LOCAL_MODE_UNICODE,
        LocalInputMode::DateTime => crate::MSIME_ENGINE_LOCAL_MODE_DATE_TIME,
        LocalInputMode::QuickPhrase => crate::MSIME_ENGINE_LOCAL_MODE_QUICK_PHRASE,
        LocalInputMode::Emoji => crate::MSIME_ENGINE_LOCAL_MODE_EMOJI,
        LocalInputMode::Kaomoji => crate::MSIME_ENGINE_LOCAL_MODE_KAOMOJI,
        LocalInputMode::SuperJianpin => crate::MSIME_ENGINE_LOCAL_MODE_SUPER_JIANPIN,
        LocalInputMode::TemporaryEnglish => crate::MSIME_ENGINE_LOCAL_MODE_TEMPORARY_ENGLISH,
        LocalInputMode::TemporaryJapanese => crate::MSIME_ENGINE_LOCAL_MODE_TEMPORARY_JAPANESE,
        LocalInputMode::Expression => crate::MSIME_ENGINE_LOCAL_MODE_EXPRESSION,
        LocalInputMode::Command => crate::MSIME_ENGINE_LOCAL_MODE_COMMAND,
        LocalInputMode::Mention => crate::MSIME_ENGINE_LOCAL_MODE_MENTION,
        LocalInputMode::Url => crate::MSIME_ENGINE_LOCAL_MODE_URL,
        LocalInputMode::Chaizi => crate::MSIME_ENGINE_LOCAL_MODE_CHAIZI,
        LocalInputMode::Symbol => crate::MSIME_ENGINE_LOCAL_MODE_SYMBOL,
    }
}

fn saturating_u32(value: usize) -> u32 {
    u32::try_from(value).unwrap_or(u32::MAX)
}

fn bool_option(value: i64) -> Outcome<bool> {
    match value {
        0 => Ok(false),
        1 => Ok(true),
        _ => Err(Failure::invalid("a switch option takes 0 or 1")),
    }
}

// ---- 会话 ----

/// 按选项 JSON（版本 1，键表见 README）建一个会话，成功时把句柄写进 `*session`，失败时写 NULL。会话持有这两个目录上的共享词库租约，直到释放：租约在维护（`msime_engine_user_dict_edit`、`msime_engine_reset_learning`）进行时拿不到，这时返回 `MSIME_ENGINE_BUSY`。
///
/// # Safety
/// `options_json` 指向 `options_len` 个可读字节；`session` 可写一个指针。
#[no_mangle]
pub unsafe extern "C" fn msime_engine_session_new(
    options_json: *const c_char,
    options_len: usize,
    session: *mut *mut msime_engine_session,
) -> i32 {
    guard(|| {
        if session.is_null() {
            return Err(Failure::null("session"));
        }
        // SAFETY: 上面检查过非空，调用方保证可写。
        unsafe { session.write(std::ptr::null_mut()) };
        // SAFETY: 调用方保证 `options_json` 的长度。
        let json = unsafe { input_str(options_json, options_len, "options_json") }?;
        let options = crate::options::parse(json)?;
        options.paths.validate()?;
        let access =
            DictionaryAccess::try_session(&options.paths.user_data, &options.paths.dictionaries)
                .map_err(|error| {
                    Failure::new(
                        crate::MSIME_ENGINE_STORAGE,
                        format!("dictionary lease: {error}"),
                    )
                })?
                .ok_or_else(|| {
                    Failure::new(
                        MSIME_ENGINE_BUSY,
                        msime_engine::diagnostics::DICTIONARY_MAINTENANCE_BUSY,
                    )
                })?;
        let engine = Session::new(options)?;
        let handle = Box::new(msime_engine_session {
            state: Mutex::new(SessionState {
                session: engine,
                _access: access,
                poisoned: false,
                snapshot: None,
                result: KeyResult::default(),
            }),
        });
        // SAFETY: 同上。
        unsafe { session.write(Box::into_raw(handle)) };
        Ok(())
    })
}

/// 结束并释放会话：写下最近的学习，交还日志连接和词库租约。NULL 什么也不做。另一个线程正在调这个会话时返回 `MSIME_ENGINE_BUSY`、不释放；已作废的会话照样可以释放。释放之后句柄不能再用。
///
/// # Safety
/// `session` 是 NULL 或 `msime_engine_session_new` 交出、还没释放过的句柄。
#[no_mangle]
pub unsafe extern "C" fn msime_engine_session_free(session: *mut msime_engine_session) -> i32 {
    guard(|| {
        if session.is_null() {
            return Ok(());
        }
        // SAFETY: 调用方保证句柄有效。
        let busy = match unsafe { &*session }.state.try_lock() {
            Ok(_) | Err(TryLockError::Poisoned(_)) => false,
            Err(TryLockError::WouldBlock) => true,
        };
        if busy {
            return Err(Failure::new(
                MSIME_ENGINE_BUSY,
                "another thread is calling this session; free it after that call returns",
            ));
        }
        // SAFETY: 句柄来自 `Box::into_raw`，调用方保证只释放一次。析构里的 panic 由 `guard` 接住。
        drop(unsafe { Box::from_raw(session) });
        Ok(())
    })
}

/// 换方案（`MSIME_ENGINE_SCHEME_*`），丢弃组字。方案必须在选项的 `enabled_schemes` 里；新方案的词库打不开时失败，留在原方案、组字不动。
///
/// # Safety
/// `session` 是有效的句柄。
#[no_mangle]
pub unsafe extern "C" fn msime_engine_switch_scheme(
    session: *mut msime_engine_session,
    scheme: u32,
) -> i32 {
    with_session(session, |state| {
        let scheme = u8::try_from(scheme)
            .ok()
            .and_then(SchemeType::from_u8)
            .ok_or_else(|| Failure::invalid(format!("unknown scheme {scheme}")))?;
        state.begin_change();
        state.session.switch_scheme(scheme)?;
        Ok(())
    })
}

/// 设一个整数选项（`MSIME_ENGINE_OPTION_*` 里标着「整数」的）。不认识的编号是 `MSIME_ENGINE_UNSUPPORTED`，字符串选项或越界的值是 `MSIME_ENGINE_INVALID_ARGUMENT`。
///
/// # Safety
/// `session` 是有效的句柄。
#[no_mangle]
pub unsafe extern "C" fn msime_engine_set_int(
    session: *mut msime_engine_session,
    option: u32,
    value: i64,
) -> i32 {
    with_session(session, |state| {
        match option {
            MSIME_ENGINE_OPTION_CHINESE_PUNCT => {
                let enabled = bool_option(value)?;
                state.begin_change();
                state.session.set_chinese_punctuation_enabled(enabled);
            }
            MSIME_ENGINE_OPTION_PAIRED_PUNCT => {
                let enabled = bool_option(value)?;
                state.begin_change();
                state.session.set_paired_punctuation_enabled(enabled);
            }
            MSIME_ENGINE_OPTION_PUNCT_LOCK => {
                let lock = i32::try_from(value)
                    .map_err(|_| Failure::invalid("punctuation lock must be 0..=2"))?;
                state.begin_change();
                state.session.set_punctuation_lock(lock)?;
            }
            MSIME_ENGINE_OPTION_DEDICATED_ENGLISH => {
                let enabled = bool_option(value)?;
                state.begin_change();
                state.session.set_dedicated_english(enabled);
            }
            MSIME_ENGINE_OPTION_HELPCODE_ENABLED => {
                let enabled = bool_option(value)?;
                state.begin_change();
                state.session.set_helpcode_enabled(enabled);
            }
            MSIME_ENGINE_OPTION_PERSONAL_CONTEXT => {
                let enabled = bool_option(value)?;
                state.begin_change();
                state.session.set_personal_context_enabled(enabled);
            }
            MSIME_ENGINE_OPTION_PREDICTION_ALLOWED => {
                let allowed = bool_option(value)?;
                state.begin_change();
                state.session.set_prediction_allowed(allowed);
            }
            MSIME_ENGINE_OPTION_FIRST_PAGE_ROWS => {
                if !(1..=255).contains(&value) {
                    return Err(Failure::invalid("first page rows must be 1..=255"));
                }
                state.begin_change();
                state
                    .session
                    .set_first_page_rows(FirstPageRows::new(value as usize));
            }
            MSIME_ENGINE_OPTION_HELPCODE_SCHEMA | MSIME_ENGINE_OPTION_RESCORING_CONTEXT => {
                return Err(Failure::invalid(format!("option {option} takes a string")));
            }
            _ => {
                return Err(Failure::new(
                    MSIME_ENGINE_UNSUPPORTED,
                    format!("unknown option {option}"),
                ))
            }
        }
        Ok(())
    })
}

/// 设一个字符串选项（`MSIME_ENGINE_OPTION_*` 里标着「字符串」的），`value` 是 `value_len` 个字节的 UTF-8。不认识的编号是 `MSIME_ENGINE_UNSUPPORTED`，整数选项是 `MSIME_ENGINE_INVALID_ARGUMENT`。
///
/// # Safety
/// `session` 是有效的句柄；`value` 指向 `value_len` 个可读字节。
#[no_mangle]
pub unsafe extern "C" fn msime_engine_set_string(
    session: *mut msime_engine_session,
    option: u32,
    value: *const c_char,
    value_len: usize,
) -> i32 {
    with_session(session, |state| {
        // SAFETY: 调用方保证长度。
        let value = unsafe { input_str(value, value_len, "value") }?;
        match option {
            MSIME_ENGINE_OPTION_HELPCODE_SCHEMA => {
                if !Session::is_supported_helpcode_schema(value) {
                    return Err(Failure::invalid(format!(
                        "unknown helpcode schema {value:?}"
                    )));
                }
                state.begin_change();
                if !state.session.set_helpcode_schema(value) {
                    return Err(Failure::new(
                        crate::MSIME_ENGINE_FAILED,
                        format!("helpcode table {value:?} could not be loaded"),
                    ));
                }
            }
            MSIME_ENGINE_OPTION_RESCORING_CONTEXT => {
                state.begin_change();
                state.session.set_rescoring_context(value);
            }
            MSIME_ENGINE_OPTION_CHINESE_PUNCT
            | MSIME_ENGINE_OPTION_PAIRED_PUNCT
            | MSIME_ENGINE_OPTION_PUNCT_LOCK
            | MSIME_ENGINE_OPTION_DEDICATED_ENGLISH
            | MSIME_ENGINE_OPTION_HELPCODE_ENABLED
            | MSIME_ENGINE_OPTION_PERSONAL_CONTEXT
            | MSIME_ENGINE_OPTION_PREDICTION_ALLOWED
            | MSIME_ENGINE_OPTION_FIRST_PAGE_ROWS => {
                return Err(Failure::invalid(format!(
                    "option {option} takes an integer"
                )));
            }
            _ => {
                return Err(Failure::new(
                    MSIME_ENGINE_UNSUPPORTED,
                    format!("unknown option {option}"),
                ))
            }
        }
        Ok(())
    })
}

/// 忘掉上屏的上下文（焦点或应用变了、宿主自己插入了文字），清掉上屏后联想。
///
/// # Safety
/// `session` 是有效的句柄。
#[no_mangle]
pub unsafe extern "C" fn msime_engine_reset_context(session: *mut msime_engine_session) -> i32 {
    with_session(session, |state| {
        state.begin_change();
        state.session.reset_context();
        Ok(())
    })
}

// ---- 输入 ----

/// 一个 ASCII 字符（0x20 到 0x7E，另收 Tab 0x09）：字母、拼写用的数字，以及 `spelling_symbols` 里列出的符号。`flags` 是 `MSIME_ENGINE_KEY_*`。结果写进 `result`（可以是 NULL）。按键路由见 README。
///
/// # Safety
/// `session` 是有效的句柄；`result` 是 NULL 或按 `struct_size` 约定可写。
#[no_mangle]
pub unsafe extern "C" fn msime_engine_key_char(
    session: *mut msime_engine_session,
    character: u8,
    flags: u32,
    result: *mut msime_engine_result,
) -> i32 {
    with_session(session, |state| {
        if !(character == b'\t' || (0x20..=0x7e).contains(&character)) {
            return Err(Failure::invalid(
                "key_char takes one printable ASCII character or Tab",
            ));
        }
        if flags & !MSIME_ENGINE_KEY_SHIFT_ONLY != 0 {
            return Err(Failure::new(
                MSIME_ENGINE_UNSUPPORTED,
                format!("unknown key flags {flags:#x}"),
            ));
        }
        // SAFETY: 调用方的前提。
        unsafe { check_output(result, "result") }?;
        state.begin_change();
        let outcome = state
            .session
            .character(character, flags & MSIME_ENGINE_KEY_SHIFT_ONLY != 0);
        // SAFETY: 调用方的前提。
        unsafe { state.finish(outcome, result) }
    })
}

/// 一个 ASCII 标点：有组字时以首选结束组字，再接上中文标点；中文标点关着、锁成 ASCII 或这个键没有中文标点时不处理（`handled` 为 0），宿主自己输出这个键。宿主高亮了首选以外的行时，先用 `msime_engine_finish` 以那一行结束，再调这个函数。
///
/// # Safety
/// 同 `msime_engine_key_char`。
#[no_mangle]
pub unsafe extern "C" fn msime_engine_key_punct(
    session: *mut msime_engine_session,
    character: u8,
    result: *mut msime_engine_result,
) -> i32 {
    with_session(session, |state| {
        if !character.is_ascii_punctuation() {
            return Err(Failure::invalid(
                "key_punct takes one ASCII punctuation character",
            ));
        }
        // SAFETY: 调用方的前提。
        unsafe { check_output(result, "result") }?;
        state.begin_change();
        let outcome = state.session.punctuation(character);
        // SAFETY: 调用方的前提。
        unsafe { state.finish(outcome, result) }
    })
}

/// 一个编辑命令（`MSIME_ENGINE_COMMAND_*`）。
///
/// # Safety
/// 同 `msime_engine_key_char`。
#[no_mangle]
pub unsafe extern "C" fn msime_engine_command(
    session: *mut msime_engine_session,
    command: u32,
    result: *mut msime_engine_result,
) -> i32 {
    with_session(session, |state| {
        let command = u8::try_from(command)
            .ok()
            .and_then(Command::from_u8)
            .ok_or_else(|| {
                Failure::new(
                    MSIME_ENGINE_UNSUPPORTED,
                    format!("unknown command {command}"),
                )
            })?;
        // SAFETY: 调用方的前提。
        unsafe { check_output(result, "result") }?;
        state.begin_change();
        let outcome = state.session.command(command);
        // SAFETY: 调用方的前提。
        unsafe { state.finish(outcome, result) }
    })
}

/// 把组字光标放到 `editing_text` 的第 `caret_byte` 个字节前；负数（`MSIME_ENGINE_CARET_END`）回到末尾。位置限制在可编辑的范围内，九键组码时什么也不做。
///
/// # Safety
/// `session` 是有效的句柄。
#[no_mangle]
pub unsafe extern "C" fn msime_engine_set_caret(
    session: *mut msime_engine_session,
    caret_byte: i64,
) -> i32 {
    with_session(session, |state| {
        let caret = usize::try_from(caret_byte).ok();
        state.begin_change();
        state.session.set_caret(caret);
        Ok(())
    })
}

// ---- 状态 ----

/// 读组字状态。只读：不改变会话，之前借出的字符串照样有效。
///
/// # Safety
/// `session` 是有效的句柄；`state` 按 `struct_size` 约定可写。
#[no_mangle]
pub unsafe extern "C" fn msime_engine_state_get(
    session: *mut msime_engine_session,
    state: *mut msime_engine_state,
) -> i32 {
    with_session(session, |inner| {
        if state.is_null() {
            return Err(Failure::null("state"));
        }
        let revision = inner.session.candidate_revision();
        let takes_separator = inner.session.takes_local_separator();
        let snapshot = inner.snapshot();
        let mut flags = 0;
        if snapshot.prediction {
            flags |= MSIME_ENGINE_STATE_PREDICTION;
        }
        if snapshot.dedicated_english {
            flags |= MSIME_ENGINE_STATE_DEDICATED_ENGLISH;
        }
        if snapshot.candidate_list_open {
            flags |= MSIME_ENGINE_STATE_CANDIDATE_LIST_OPEN;
        }
        if takes_separator {
            flags |= MSIME_ENGINE_STATE_TAKES_SEPARATOR;
        }
        let value = msime_engine_state {
            struct_size: 0,
            scheme: u32::from(snapshot.scheme as u8),
            revision,
            candidate_count: saturating_u32(snapshot.candidates.len()),
            flags,
            local_mode: local_mode_value(snapshot.local_mode),
            caret_byte: saturating_u32(snapshot.caret_position),
            conversion_focus_start_scalar: saturating_u32(snapshot.conversion_focus.0),
            conversion_focus_end_scalar: saturating_u32(snapshot.conversion_focus.1),
            preedit: msime_engine_str::borrow(&snapshot.preedit),
            editing_text: msime_engine_str::borrow(&snapshot.editing_text),
            conversion: msime_engine_str::borrow(&snapshot.conversion),
            spelling_symbols: msime_engine_str::borrow(&snapshot.spelling_symbols),
        };
        // SAFETY: 调用方的前提。
        unsafe { write_sized(state, value, "state") }
    })
}

/// 读第 `index` 行候选。`revision` 必须是当前的候选修订号，否则 `MSIME_ENGINE_STALE`；越界是 `MSIME_ENGINE_INVALID_ARGUMENT`。只读，可以先取状态再逐个取一页候选。
///
/// # Safety
/// `session` 是有效的句柄；`candidate` 按 `struct_size` 约定可写。
#[no_mangle]
pub unsafe extern "C" fn msime_engine_candidate_get(
    session: *mut msime_engine_session,
    revision: u64,
    index: u32,
    candidate: *mut msime_engine_candidate,
) -> i32 {
    with_session(session, |state| {
        if candidate.is_null() {
            return Err(Failure::null("candidate"));
        }
        state.check_revision(revision)?;
        let snapshot = state.snapshot();
        let row = index as usize;
        let Some(item) = snapshot.candidates.get(row) else {
            return Err(Failure::invalid(format!(
                "candidate {index} is out of range ({} candidates)",
                snapshot.candidates.len()
            )));
        };
        let mut flags = 0;
        if item.fuzzy {
            flags |= MSIME_ENGINE_CANDIDATE_FUZZY;
        }
        if snapshot
            .candidate_answers_key
            .get(row)
            .copied()
            .unwrap_or(false)
        {
            flags |= MSIME_ENGINE_CANDIDATE_ANSWERS_KEY;
        }
        if item.sentence_association {
            flags |= MSIME_ENGINE_CANDIDATE_SENTENCE;
        }
        let value = msime_engine_candidate {
            struct_size: 0,
            index,
            source: u32::from(item.source as u8),
            scheme: u32::from(item.scheme as u8),
            flags,
            fixed_position: item.fixed_position,
            word: msime_engine_str::borrow(&item.word),
            code: msime_engine_str::borrow(&item.pinyin),
            annotation: msime_engine_str::borrow(
                snapshot
                    .candidate_annotations
                    .get(row)
                    .map_or("", String::as_str),
            ),
            corrected_from: msime_engine_str::borrow(&item.corrected_from),
        };
        // SAFETY: 调用方的前提。
        unsafe { write_sized(candidate, value, "candidate") }
    })
}

/// 单字母全拼只先给出一部分候选；宿主翻过第一页时调它要回其余的。`*grew` 写 1 表示列表变长了（修订号随之改变），否则写 0。会改变状态。
///
/// # Safety
/// `session` 是有效的句柄；`grew` 是 NULL 或可写。
#[no_mangle]
pub unsafe extern "C" fn msime_engine_expand_candidates(
    session: *mut msime_engine_session,
    grew: *mut u32,
) -> i32 {
    with_session(session, |state| {
        state.begin_change();
        let expanded = state.session.expand_initial_candidates();
        if !grew.is_null() {
            // SAFETY: 调用方保证可写。
            unsafe { grew.write(u32::from(expanded)) };
        }
        Ok(())
    })
}

/// 整个状态和全部候选的 JSON，给调试和日志用；格式不属于 ABI，随版本变化。返回的字符串用 `msime_engine_string_free` 释放。只读。
///
/// # Safety
/// `session` 是有效的句柄；`json` 可写一个指针。
#[no_mangle]
pub unsafe extern "C" fn msime_engine_state_json(
    session: *mut msime_engine_session,
    json: *mut *mut c_char,
) -> i32 {
    with_session(session, |state| {
        if json.is_null() {
            return Err(Failure::null("json"));
        }
        let revision = state.session.candidate_revision();
        let text = debug_json(revision, state.snapshot()).to_string();
        // SAFETY: 上面检查过非空。
        unsafe { write_owned(json, text) };
        Ok(())
    })
}

fn debug_json(revision: u64, snapshot: &SessionSnapshot) -> Value {
    let candidates: Vec<Value> = snapshot
        .candidates
        .iter()
        .enumerate()
        .map(|(index, item)| {
            json!({
                "word": item.word.as_str(),
                "code": item.pinyin.as_str(),
                "canonical_code": item.canonical_pinyin.as_str(),
                "source": item.source as u8,
                "scheme": item.scheme.name(),
                "weight": item.weight,
                "fixed_position": item.fixed_position,
                "fuzzy": item.fuzzy,
                "corrected_from": item.corrected_from.as_str(),
                "sentence": item.sentence_association,
                "annotation": snapshot.candidate_annotations.get(index).map_or("", String::as_str),
                "answers_key": snapshot.candidate_answers_key.get(index).copied().unwrap_or(false),
            })
        })
        .collect();
    json!({
        "revision": revision,
        "scheme": snapshot.scheme.name(),
        "local_mode": snapshot.local_mode.name(),
        "prediction": snapshot.prediction,
        "dedicated_english": snapshot.dedicated_english,
        "preedit": snapshot.preedit,
        "editing_text": snapshot.editing_text,
        "caret_byte": snapshot.caret_position,
        "raw_segmentation": snapshot.raw_segmentation,
        "normalized_segmentation": snapshot.normalized_segmentation,
        "spelling_symbols": snapshot.spelling_symbols,
        "shuangpin_profile": snapshot.shuangpin_profile,
        "conversion": snapshot.conversion,
        "conversion_focus_scalar": [snapshot.conversion_focus.0, snapshot.conversion_focus.1],
        "candidate_list_open": snapshot.candidate_list_open,
        "nine_key_spellings": snapshot.nine_key_spellings,
        "candidates": candidates,
    })
}

// ---- 选择与逐候选学习 ----
//
// 都带 `revision`：不是当前修订号时 `MSIME_ENGINE_STALE`，什么也不做。下标是引擎顺序里的行号，与 `msime_engine_candidate_get` 相同。

/// 在核对修订号和输出结构体之后执行一次选择类调用；被拒绝的调用不碰会话。
fn with_candidate(
    session: *mut msime_engine_session,
    revision: u64,
    result: *mut msime_engine_result,
    action: impl FnOnce(&mut Session) -> KeyResult,
) -> i32 {
    with_session(session, |state| {
        state.check_revision(revision)?;
        // SAFETY: 调用方的前提（每个公开函数的 Safety 段）。
        unsafe { check_output(result, "result") }?;
        state.begin_change();
        let outcome = action(&mut state.session);
        // SAFETY: 调用方的前提（每个公开函数的 Safety 段）。
        unsafe { state.finish(outcome, result) }
    })
}

/// 选第 `index` 行上屏（或消耗它覆盖的那段编码，剩下的接着组字），并照常学习。
///
/// # Safety
/// `session` 是有效的句柄；`result` 是 NULL 或按 `struct_size` 约定可写。
#[no_mangle]
pub unsafe extern "C" fn msime_engine_select(
    session: *mut msime_engine_session,
    revision: u64,
    index: u32,
    result: *mut msime_engine_result,
) -> i32 {
    with_candidate(session, revision, result, |engine| {
        engine.select(self::index(index))
    })
}

/// 以词定字：上屏第 `index` 行的第一个或最后一个汉字（`MSIME_ENGINE_EDGE_*`），丢掉其余组字。
///
/// # Safety
/// 同 `msime_engine_select`。
#[no_mangle]
pub unsafe extern "C" fn msime_engine_select_edge(
    session: *mut msime_engine_session,
    revision: u64,
    index: u32,
    edge: u32,
    result: *mut msime_engine_result,
) -> i32 {
    let edge = match edge {
        MSIME_ENGINE_EDGE_FIRST_HAN => CandidateEdge::FirstHan,
        MSIME_ENGINE_EDGE_LAST_HAN => CandidateEdge::LastHan,
        _ => {
            return guard(|| Err(Failure::invalid(format!("unknown edge {edge}"))));
        }
    };
    with_candidate(session, revision, result, |engine| {
        engine.select_edge(self::index(index), edge)
    })
}

/// 结束组字：从第 `first_index` 行（宿主高亮的那一行）起上屏，用于失焦、标点前或宿主自己的结束键。
///
/// # Safety
/// 同 `msime_engine_select`。
#[no_mangle]
pub unsafe extern "C" fn msime_engine_finish(
    session: *mut msime_engine_session,
    revision: u64,
    first_index: u32,
    result: *mut msime_engine_result,
) -> i32 {
    with_candidate(session, revision, result, |engine| {
        engine.finish(self::index(first_index))
    })
}

/// 把第 `index` 行（词库里的词）提到前面，不上屏。不支持的行不处理（`handled` 为 0）。
///
/// # Safety
/// 同 `msime_engine_select`。
#[no_mangle]
pub unsafe extern "C" fn msime_engine_pin(
    session: *mut msime_engine_session,
    revision: u64,
    index: u32,
    result: *mut msime_engine_result,
) -> i32 {
    with_candidate(session, revision, result, |engine| {
        engine.pin(self::index(index))
    })
}

/// 删掉第 `index` 行：用户自己的词从个人词典删除，随包的词不再出现。
///
/// # Safety
/// 同 `msime_engine_select`。
#[no_mangle]
pub unsafe extern "C" fn msime_engine_remove(
    session: *mut msime_engine_session,
    revision: u64,
    index: u32,
    result: *mut msime_engine_result,
) -> i32 {
    with_candidate(session, revision, result, |engine| {
        engine.remove(self::index(index))
    })
}

/// 把第 `index` 行固定在第 `position` 位（1..=5）。
///
/// # Safety
/// 同 `msime_engine_select`。
#[no_mangle]
pub unsafe extern "C" fn msime_engine_fix_position(
    session: *mut msime_engine_session,
    revision: u64,
    index: u32,
    position: i32,
    result: *mut msime_engine_result,
) -> i32 {
    with_candidate(session, revision, result, |engine| {
        engine.fix_position(self::index(index), position)
    })
}

/// 取消第 `index` 行的固定位置。
///
/// # Safety
/// 同 `msime_engine_select`。
#[no_mangle]
pub unsafe extern "C" fn msime_engine_clear_position(
    session: *mut msime_engine_session,
    revision: u64,
    index: u32,
    result: *mut msime_engine_result,
) -> i32 {
    with_candidate(session, revision, result, |engine| {
        engine.clear_position(self::index(index))
    })
}

#[cfg(test)]
pub(crate) fn lock_for_test(
    session: *mut msime_engine_session,
) -> std::sync::MutexGuard<'static, impl Sized> {
    // SAFETY: 测试里句柄一直有效，直到测试释放它。
    unsafe { &*session }.state.lock().expect("session lock")
}

#[cfg(test)]
pub(crate) fn run_for_test(
    session: *mut msime_engine_session,
    body: impl FnOnce() -> Outcome,
) -> i32 {
    with_session(session, |_| body())
}