docs: 收口阶段 1 输入系统实现与验证记录

开发记录/模块/Module-20261001-0001-通用输入焦点与键盘路由系统设计.md

@@ -7,7 +7,7 @@
 
 - 模块 ID：Module-20261001-0001
 - 模块名称：通用输入采集、焦点与键盘路由系统
-- 状态：设计中（v0.13；0C 当前可用环境基线通过，0B 阶段 1 前置基线已关闭；微软拼音 Forward/Consume 有效，搜狗 Consume 请求按 `ime_condition_not_met` fail-open 并形成 `MustForward`；阶段 1 尚未开始）
+- 状态：实现中（v0.14；0C/0B 前置基线已关闭；阶段 1 输入采集、规范化与观察队列已落地并通过自动回归，待真实 IME/KEY1–6 人工回归；焦点与键盘路由尚未开始）
 - 类型：新增模块 / 架构演进
 - 所属系统 / 子系统：StellarX Core / Window / Control / Input / Focus / TextBox
 - 版本 / 分支：`master`，阶段 0A 实现基线 `c218c25`
@@ -37,7 +37,7 @@
   - v1 不自绘 IME 拼音组合串和候选列表，继续使用系统 IME UI。
   - v1 不重写现有全部鼠标采集链；现有 EasyX 鼠标消息只在框架入口规范化为 `PointerEvent`。
   - v1 不承诺完整 Unicode grapheme cluster 编辑，只保证不拆分 UTF-16 代理对。
-  - 本设计稿不代表框架代码已经实现，也不构成运行验证结果。
+  - 本稿中的阶段 1 已有实现记录和自动验证证据；阶段 2 至阶段 6 仍是设计目标，不应被误读为已经实现。
 
 ## 模块边界
 
@@ -162,8 +162,10 @@ Button / TextBox / Table / TabControl / Dialog
 
 ### 3. 关键不变量
 
-1. NativeInputQueue 是键盘、文本和 IME 的唯一业务输入源。
-2. EasyX `EX_KEY` 只排空和观察，不得再次触发业务路由。
+以下是阶段 3 换轨后的完成态不变量；阶段 1–2 的兼容过渡例外仅限“旧 EX_KEY 继续业务下发、新队列只观察”，不得被扩展成长期双业务源：
+
+1. 阶段 3 启用后，NativeInputQueue 是键盘、文本和 IME 的唯一业务输入源。
+2. 阶段 3 启用后，EasyX `EX_KEY` 只排空和观察，不得再次触发业务路由。
 3. 同步窗口协议不得进入异步输入队列。
 4. 异步路由只能阻止框架默认动作，不能倒过来改变已经结束的 WndProc 返回值。
 5. 队列、焦点、Tab 顺序、路由路径和待删除列表长期只保存 `ControlHandle`。
@@ -1034,13 +1036,15 @@ struct ProbeConsumeRule
 
 #### 阶段 1：InputCollector
 
-- 输入事件结构和 NativeInputQueue。
-- 按已确认双线程模型实现 SPSC 语义的跨线程发布；正确性版本先用短临界区互斥队列。
-- `sequence` 使用 atomic 分配，队列同步独立提供 happens-before。
-- KeyEvent 完整解析。
-- Unicode/ANSI 解码。
-- IME 状态机。
-- EasyX `EX_KEY` 排空但不业务路由。
+- 已实现 `NativeInputEvent / KeyEvent / TextInputEvent / CompositionEvent / WindowActivationEvent` 和每 Window 的 `NativeInputContext`。
+- 按已确认双线程模型使用 `mutex + deque` 实现跨线程 SPSC 语义；`sequence` 由 atomic 分配，队列互斥独立提供 happens-before。
+- 已实现 Key lParam 完整解析、左右修饰键快照、Unicode/ANSI/CP936 状态解码、IME 生命周期、`compositionId` 与结果回声去重。
+- WndProc 捕获时同时快照原始 VK 和 `imeComposingAtCapture`；二者是正交轴，只有原始 `VK_PROCESSKEY` 表示当前单键归 IME。
+- 阶段 1 采用行为保持过渡：新队列只在宿主安全点观测排空，旧 `EX_KEY -> Control::handleEvent()` 暂时保留；阶段 3 才把 `EX_KEY` 改为纯排空，并让 NativeInputQueue 成为唯一键盘业务源。
+- `Control::handleEvent()` 的 `EX_MOUSE` 永久保留；仅 `EX_KEY` 旧入口进入弃用期，派生控件不得新增对该路径的依赖。
+- 队列分配失败或内部异常由无分配 POD 故障快照发布，WndProc 不抛异常；宿主安全点显式 fail-stop 并以 `-2` 退出，不允许静默丢输入后继续运行。
+- 非法 UTF-16/ANSI 序列、IMM 查询失败和被边界清理的半截解码状态使用无原文累计计数，并在宿主安全点按变化输出警告。
+- 阶段 1 不实现 FocusManager、KeyboardRouter、生产消费白名单、Button/TextBox 键盘行为或 TextBox 自绘。
 
 #### 阶段 2：FocusManager
 
@@ -1108,17 +1112,23 @@ struct ProbeConsumeRule
 28. IME 位置必须在焦点/caret/anchor 变化时立即预设，并在组合生命周期消息到达时再次校准；不得假定候选 UI 出现前一定会收到 `WM_IME_STARTCOMPOSITION/WM_IME_COMPOSITION`。
 29. 原始 `VK_PROCESSKEY` 一律视为 IME 所有：WndProc 层采集并转发，阶段 1 不向 Button、Dialog、快捷键和焦点导航路由；不得依赖 `imeComposingAtCapture` 单独判断搜狗候选态。
 30. 0B 没有建立跨 IME 生产消费白名单；阶段 1 从默认转发基线开始，后续任何窄消费规则都必须有独立逐键证据。
+31. 阶段 1 只建输入地基、不切换业务轨道：旧 `EX_KEY` 继续进入 `Control::handleEvent()`，新队列只观测排空；阶段 3 一次性切换，`EX_MOUSE` 不受影响。
+32. 单键 IME 所有权只由采集时的原始 `VK_PROCESSKEY` 表达；`imeComposingAtCapture` 只记录标准生命周期，两者不得合并为一个持久“组合中”状态。
+33. `mutex + deque` 在正常资源条件下不得丢输入；分配失败或队列异常必须 fail-stop，不能捕获后假装成功。
+34. `WM_IME_ENDCOMPOSITION` 不得在转发旧窗口过程之前清空结果回声；END 处理中嵌套或紧随其后的匹配 `WM_IME_CHAR/WM_CHAR` 仍须抑制重复入队。
+35. 无效文本序列、IMM 查询失败和残留半截解码状态必须以不含原文的计数显式诊断，不得写入替代文本或静默记为成功。
 
 ## 实现与影响
 
 - 关键实现点:
-  - 阶段 0A 探测器已经进入框架；0C 独立视觉探测工程已实现；FocusManager、生产 NativeInputQueue 和 TextBox 改造尚未开始。
-  - 独立 EasyX 探测已经推翻 v0.4 的单线程假设，v0.5 据此补入跨线程队列约束；v0.6 根据微软拼音/搜狗真实日志锁定结果串与回声关系，并补入输入布局 request/change 分层；v0.7 根据专用短测区分 TSF 配置文件切换与跨语言 HKL，并增加重新获焦快照约束；v0.8 根据 0C 自动证据锁定宽字符绘制、批次进入顺序与当前 DPI 坐标规则；v0.9 根据搜狗真实失败与修复复验锁定 IME 位置双时机规则；v0.13 根据 0B 微软拼音 Consume 与搜狗运行时 fail-open 证据锁定默认转发、`VK_PROCESSKEY` 路由抑制和无生产消费白名单基线。
+  - 阶段 0A 探测器和 0C 独立视觉探测已进入仓库；阶段 1 的生产 NativeInputQueue、输入事件结构、采集规范化、IME 状态与观察排空已实现。FocusManager、KeyboardRouter 和 TextBox 改造尚未开始。
+  - 独立 EasyX 探测已经推翻 v0.4 的单线程假设，v0.5 据此补入跨线程队列约束；v0.6 根据微软拼音/搜狗真实日志锁定结果串与回声关系，并补入输入布局 request/change 分层；v0.7 根据专用短测区分 TSF 配置文件切换与跨语言 HKL，并增加重新获焦快照约束；v0.8 根据 0C 自动证据锁定宽字符绘制、批次进入顺序与当前 DPI 坐标规则；v0.9 根据搜狗真实失败与修复复验锁定 IME 位置双时机规则；v0.13 根据 0B 证据锁定默认转发与无生产消费白名单；v0.14 根据阶段 1 实现审查锁定 EX_KEY 兼容过渡、两轴快照、fail-stop、END 回声边界和显式异常计数。
 - 涉及文件 / 类 / 函数:
   - 预计涉及 `Window`、`Control`、`Canvas`、`Button`、`TextBox`、`Table`、`TabControl`、`Dialog`。
   - 实际文件和接口必须在阶段 0 与实现前只读检查后确定。
 - 兼容性影响:
   - 设计目标是保留现有鼠标行为和公共文本 API 的兼容入口。
+  - 阶段 1 不改变现有 `EX_KEY` 业务交付；阶段 3 停止向 `Control::handleEvent()` 下发 `EX_KEY` 时属于明确的派生控件迁移点，`EX_MOUSE` 永久保留。
   - 输入链路和 TextBox 内部模型将发生架构级变化，必须分阶段接入。
 - 性能影响:
   - 输入事件会增加规范化和句柄解析开销，但不允许在 WndProc 中执行阻塞 I/O。
@@ -1126,13 +1136,13 @@ struct ProbeConsumeRule
 - 风险点:
   - EasyX 双线程、ANSI 窗口和当前微软拼音/搜狗回声顺序已确认，但其他 IME、窗口 A/W 属性和系统版本仍可能产生不同顺序。
   - 模态重入和控件删除若破坏单 drainer/句柄不变量，可能产生难复现的顺序或生命周期问题。
-  - 该文档是设计基线，不应被误读为已实现或已验证能力。
+  - 阶段 1 的自动验证与人工回归必须分开记账；尚未执行的真实 IME/KEY1–6 人工操作不能由单元测试替代。
 
 ## 测试与验证
 
 - 测试范围:
   - 设计评审覆盖输入采集、同步消息、Unicode、IME、焦点、复合控件、按键归属、TextBox 和模态重入。
-  - 独立线程归属探测、0A 构建、固定消息 smoke、微软拼音/搜狗真实输入链路测试、当前可用环境的 0C 基线，以及 0B 的 F24 KeyDown/KeyUp 自动 A/B、baseline fail-open、微软拼音 Forward/Consume 和搜狗运行时 fail-open 门槛均已完成；生产输入队列和焦点系统尚未开始。
+  - 独立线程归属探测、0A、0C、0B 门槛均已完成；阶段 1 已加入逻辑测试与真实 EasyX `input-shadow` 场景，焦点系统尚未开始。
 - 验证步骤:
 
 1. 先按关联规格实现阶段 0A 被动探测并取得消息链路证据。
@@ -1161,6 +1171,7 @@ struct ProbeConsumeRule
   - 2026-10-07：微软拼音 Forward/Consume 有效复验均通过；Forward 对应 EasyX 键出现一次，Consume 后 EasyX 键消失，位置链分别为 18/18 与 7/7，均零丢失、无孤立定位记录。
   - 2026-10-07：搜狗候选态没有向目标 HWND 暴露 START/COMPOSITION/END 生命周期；最终 Consume 请求以 `ime_condition_not_met` 正确 fail-open 为 Forward，规则零命中、零消费、EasyX 键出现一次，结构 verdict 为 `MustForward`。
   - 2026-10-07：最终 Debug x64 单元测试 15/15、UI fixture 1 轮、F24 KeyDown A/B 新运行通过；既有 KeyUp 与 baseline mismatch 证据经当前分析器回放保持有效。阶段 1 以默认转发且无消费白名单为起点。
+  - 2026-10-07：阶段 1 自动回归通过：Debug x64、x64 ASan、Release x64、Debug Win32 均为 27/27，KEY1–6 全部编译/链接成功；完整 UI fixture 曾一轮通过，最终源码的独立 `input-shadow` 再次通过，旧 EX_KEY 与新队列均完整观察 4000/4000 条事件，新队列最终深度 0、顺序严格、内存增长 0、无 fault/规范化异常；PowerShell 5.1/7 AST、工程 XML 和 `git diff --check` 通过。最终完整 UI 的两次追加复跑分别在 `geometry/ownership` 鼠标点击检查点超时，均未进入输入场景，按既有桌面焦点抖动保留失败证据，不冒充最终全套连续通过。真实 IME 与 KEY1–6 交互仍待人工确认。
 - 已知限制 / 遗留问题:
   - §5.3 当前明确不建立生产消费白名单；若后续需要窄消费规则，仍必须补对应消息、虚拟键、IME 和环境的独立 0B 证据。
   - §7.3 的微软拼音/搜狗回声状态机已有 0A 证据，其他 IME 仍需保持可诊断回退。