# 完整用户词库状态接口

公共头文件为 `<metasequoia/dictionary_state.h>`。接口覆盖四类词条的最终覆盖、删除标记、用户新增标记、英文显示形式、固定位置及调频选择计数，供各平台接入完整云同步。

`stream_dictionary_state` 在同一个 SQLite 读事务中顺序导出三类类型化记录，调用方逐条编码即可。使用 WAL 时允许创建协调文件，同时通过 `query_only` 禁止该连接修改用户表。导出回调返回 `false` 会中止并抛出异常。IPC 操作回执、账号标识、凭据及平台设置不进入这些记录。

`stage_dictionary_state` 只向独占新建的绝对路径目录写入数据。目录内包含 `user`、用户日志、从只读资源重新生成的词库及 `cache`。记录数上限默认为 500,000；调用方可根据已校验文件的记录数显式设置 `maximum_records`，从而完整接收服务端允许的大快照，以 SQLite 主键和唯一约束拒绝重复条目或固定位置，校验容量、文本编码、权重及计数边界。输入回调返回 `false` 表示完整且已验证的文件结束；解析错误、摘要不符、截断或取消必须抛出异常。失败时删除本次新目录，已有目录不会被覆盖。协议解析、下载完整性和用户确认由调用方负责。

平台完成准备后，需等待会话空闲，检查本机状态是否仍是用户确认时的版本，然后原子更新自己持有的活动代际指针并重建输入会话。恢复进程时仍通过这一指针选择日志和词库。旧代际在新代际成功启用前须保留；若准备期间用户继续学习或编辑，必须重新确认，不能静默覆盖。此接口本身不切换当前会话，也不会自动上传输入记录。

根 CMake 测试包含 `dictionary_state` 和 `dictionary_state_capacity`。覆盖完整状态往返、实际候选的固定位置/删除效果、并发导出的一致性、清空替换恢复基础词库、重复记录/槽位拒绝、取消清理、已有目录保护，以及十万条记录的流式准备和完整回读。