refactor(transport): suppress_physical を PhysicalKeyDisposition に分離

cuzic · claude · cuzic · commit 8a045bbb327e · 2026-06-21T04:57:00.000-05:00
Decision（意味論）を不可侵にし、物理 KANJI キーを OS に届けるかの配送判断を
新設 PhysicalKeyDisposition（Allow/Suppress）に移す。kp_stage_execute は
Decision を Consume に書き換えるのをやめ、配送判断を executor に渡す。

- runtime/transport.rs 新規: PhysicalKeyDisposition::plan / to_callback
- execute_filter: 各 Decision アームで physical.to_callback を使う
- execute_relay: PassThrough Suppress は handle_passthrough を呼ばず Consumed、
  PassThroughWith は Allow のときだけ ReinjectKey を積む

Co-Authored-By: Claude Sonnet 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/crates/awase-windows/src/runtime/executor.rs b/crates/awase-windows/src/runtime/executor.rs
@@ -17,6 +17,7 @@ use awase::types::{RawKeyEvent, VkCode};
 
 use crate::hook::CallbackResult;
 use crate::platform::WindowsPlatform;
+use crate::runtime::PhysicalKeyDisposition;
 use crate::state::platform_state::ImeStateHub;
 use crate::vk::VkCodeExt;
 use crate::RawKeyEventExt as _;
@@ -93,11 +94,12 @@ impl DecisionExecutor {
         ime: &ImeStateHub,
         decision: Decision,
         raw_event: &RawKeyEvent,
+        physical: PhysicalKeyDisposition,
     ) -> BatchResult {
         self.applied_snapshot = ime.model().applied;
         match self.hook_mode {
-            HookMode::Filter => self.execute_filter(platform, decision),
-            HookMode::Relay => self.execute_relay(platform, decision, raw_event),
+            HookMode::Filter => self.execute_filter(platform, decision, physical),
+            HookMode::Relay => self.execute_relay(platform, decision, raw_event, physical),
         }
     }
 
@@ -255,17 +257,18 @@ impl DecisionExecutor {
         &mut self,
         platform: &mut WindowsPlatform,
         decision: Decision,
+        physical: PhysicalKeyDisposition,
     ) -> BatchResult {
-        let (consumed, effects) = match decision {
+        let (callback, effects) = match decision {
             Decision::PassThrough => {
                 return BatchResult {
-                    callback: CallbackResult::PassThrough,
+                    callback: physical.to_callback(false),
                     has_pending: self.has_pending(),
                     sync_outcomes: Vec::new(),
                 }
             }
-            Decision::PassThroughWith { effects } => (false, effects),
-            Decision::Consume { effects } => (true, effects),
+            Decision::PassThroughWith { effects } => (physical.to_callback(false), effects),
+            Decision::Consume { effects } => (physical.to_callback(true), effects),
         };
 
         let mut sync_outcomes = Vec::new();
@@ -281,11 +284,7 @@ impl DecisionExecutor {
         }
 
         BatchResult {
-            callback: if consumed {
-                CallbackResult::Consumed
-            } else {
-                CallbackResult::PassThrough
-            },
+            callback,
             has_pending: self.has_pending(),
             sync_outcomes,
         }
@@ -306,9 +305,19 @@ impl DecisionExecutor {
         platform: &mut WindowsPlatform,
         decision: Decision,
         raw_event: &RawKeyEvent,
+        physical: PhysicalKeyDisposition,
     ) -> BatchResult {
         match decision {
             Decision::PassThrough => {
+                // physical=Suppress（KANJI 物理キー抑止）の場合は OS に届けず Consume する。
+                // handle_passthrough の reinject/warmup 後処理も走らせない。
+                if physical == PhysicalKeyDisposition::Suppress {
+                    return BatchResult {
+                        has_pending: self.has_pending(),
+                        callback: CallbackResult::Consumed,
+                        sync_outcomes: Vec::new(),
+                    };
+                }
                 let callback = self.handle_passthrough(platform, raw_event);
                 BatchResult {
                     has_pending: self.has_pending(),
@@ -317,17 +326,22 @@ impl DecisionExecutor {
                 }
             }
             Decision::PassThroughWith { mut effects } => {
-                // flush 出力あり → Consume して flush + キー再注入を FIFO でキュー
+                // flush 出力あり → Consume して flush + キー再注入を FIFO でキュー。
+                // physical=Suppress（KANJI 物理キー抑止）の場合は reinject を積まない。
+                let reinject = physical == PhysicalKeyDisposition::Allow;
                 log::debug!(
-                    "[relay-flush] PassThroughWith: queue {} effect(s) + reinject(vk={:#04x} {})",
+                    "[relay-flush] PassThroughWith: queue {} effect(s){} (vk={:#04x} {})",
                     effects.len(),
+                    if reinject { " + reinject" } else { " (no reinject, suppressed)" },
                     raw_event.vk_code,
                     match raw_event.event_type {
                         awase::types::KeyEventType::KeyDown => "down",
                         awase::types::KeyEventType::KeyUp => "up",
                     },
                 );
-                effects.push(Effect::Input(InputEffect::ReinjectKey(*raw_event)));
+                if reinject {
+                    effects.push(Effect::Input(InputEffect::ReinjectKey(*raw_event)));
+                }
                 self.queue.extend(effects);
                 BatchResult {
                     callback: CallbackResult::Consumed,
diff --git a/crates/awase-windows/src/runtime/key_pipeline.rs b/crates/awase-windows/src/runtime/key_pipeline.rs
@@ -440,66 +440,38 @@ impl Runtime {
         event: &RawKeyEvent,
         shadow_toggled: bool,
     ) -> CallbackResult {
-        // 物理 IME キー（VK_KANJI / VK_F3 / VK_F4 等）の Consume 条件:
-        // - Imm32Unavailable (Chrome/Edge): KeyDown のみ。VK_KANJI を SendInput 済みなので
-        //   物理キーをそのまま届けると二重制御になる。
-        // - ImmCross (LINE/Qt): KeyDown も KeyUp も Consume。set_ime_open_cross_process で
-        //   IME 制御済みのため、物理キーや IMM 注入の KeyUp をアプリに渡すと内部 IME ハンドラが
-        //   反応して spurious VK_F3/F4 を生成し shadow_toggle が反転する
-        //   (IME ON Engine-OFF バグの根本原因)。Ctrl+無変換 と同じ「awase が完全所有」モデル。
+        // 物理 IME キー（VK_KANJI / VK_F3 / VK_F4 等）を OS に届けるかは Decision（意味論）
+        // とは独立した「配送機構」の判断であり、Decision を書き換えずに
+        // PhysicalKeyDisposition で表現する。
+        // - Imm32Unavailable (Chrome/Edge): KeyDown は shadow_toggle 発火時のみ、KeyUp は常に
+        //   Suppress。VK_KANJI を SendInput 済みなので物理キーを届けると二重制御になり、
+        //   0xF3 KeyUp は OS が 0xF4 KeyDown を生成して shadow_toggle が反転する。
+        // - ImmCross (LINE/Qt): Down/Up 共に Suppress。set_ime_open_cross_process で IME 制御済み。
+        //   物理キー / IMM 注入の KeyUp をアプリに渡すと内部 IME ハンドラが spurious VK_F3/F4 を
+        //   生成し shadow_toggle が反転する（IME ON Engine-OFF バグの根本原因）。
         // - TsfNative (WezTerm): TSF が KANJI を正しく処理するため物理キーを通す（従来通り）。
         let profile = self.platform.current_app_profile();
-        let is_kanji_event = event.ime_relevance.shadow_action.is_some();
-        let suppress_physical = if profile.can_use_imm32_cross_process() {
-            // ImmCross: KANJI 関連 VK は Down/Up 共に Consume（spurious 連鎖を構造的に遮断）
-            is_kanji_event
-        } else {
-            // Imm32Unavailable: KeyDown は shadow_toggle 発火時のみ Consume。
-            // KeyUp は KANJI 関連なら常に Consume。
-            // 理由: 0xF3 KeyUp を OS に通すと OS IME が 0xF4 KeyDown を生成し、
-            // shadow_toggle が OFF→ON に反転する（Ctrl+無変換後の IME ON 戻り現象）。
-            is_kanji_event
-                && !profile.should_pass_physical_key()
-                && (shadow_toggled || matches!(event.event_type, awase::types::KeyEventType::KeyUp))
-        };
-        let decision = if suppress_physical {
+        let physical =
+            crate::runtime::PhysicalKeyDisposition::plan(event, profile, shadow_toggled);
+        if physical == crate::runtime::PhysicalKeyDisposition::Suppress {
             let reason = if profile.can_use_imm32_cross_process() {
                 "imm-cross"
             } else {
                 "imm32-off"
             };
-            match decision {
-                awase::engine::Decision::PassThrough => {
-                    log::debug!(
-                        "[{reason}] KANJI key consume vk={:#04x} {:?} (was PassThrough)",
-                        event.vk_code,
-                        event.event_type
-                    );
-                    awase::engine::Decision::Consume {
-                        effects: vec![].into(),
-                    }
-                }
-                awase::engine::Decision::PassThroughWith { effects } => {
-                    log::debug!(
-                        "[{reason}] KANJI key consume vk={:#04x} {:?} (was PassThroughWith)",
-                        event.vk_code,
-                        event.event_type
-                    );
-                    awase::engine::Decision::Consume { effects }
-                }
-                awase::engine::Decision::Consume { effects } => {
-                    awase::engine::Decision::Consume { effects }
-                }
-            }
-        } else {
-            decision
-        };
+            log::debug!(
+                "[{reason}] KANJI key suppress vk={:#04x} {:?} (physical disposition)",
+                event.vk_code,
+                event.event_type
+            );
+        }
 
         let result = self.executor.execute_from_hook(
             &mut self.platform,
             &self.platform_state.ime,
             decision,
             event,
+            physical,
         );
         // sync path の outcome を on_ime_apply_complete（B+C+D+E）に渡す。
         // Filter mode では IME effects がキューへ委譲されるため通常は空。
diff --git a/crates/awase-windows/src/runtime/mod.rs b/crates/awase-windows/src/runtime/mod.rs
@@ -3,6 +3,9 @@ mod focus_tracking;
 mod ime_refresh;
 mod key_pipeline;
 pub(crate) mod message_handlers;
+mod transport;
+
+pub(crate) use transport::PhysicalKeyDisposition;
 
 use awase::config::ValidatedConfig;
 use awase::engine::{Engine, EngineCommand, InputContext, SpecialKeyCombos};
diff --git a/crates/awase-windows/src/runtime/transport.rs b/crates/awase-windows/src/runtime/transport.rs
@@ -0,0 +1,59 @@
+use awase::types::{KeyEventType, RawKeyEvent};
+
+use crate::focus::class_names::AppImeProfile;
+use crate::hook::CallbackResult;
+
+/// 元の物理キーイベントを OS に届けるかどうかの配送判断。
+/// `Decision`（意味論）とは独立した配送機構上の判断。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum PhysicalKeyDisposition {
+    /// 元の物理キーイベントをそのまま OS に通す
+    Allow,
+    /// 元の物理キーイベントを消費（OS に届けない）
+    Suppress,
+}
+
+impl PhysicalKeyDisposition {
+    /// Decision と PhysicalKeyDisposition から CallbackResult を導出する。
+    pub(crate) const fn to_callback(self, engine_consumed: bool) -> CallbackResult {
+        match self {
+            Self::Suppress => CallbackResult::Consumed,
+            Self::Allow => {
+                if engine_consumed {
+                    CallbackResult::Consumed
+                } else {
+                    CallbackResult::PassThrough
+                }
+            }
+        }
+    }
+
+    /// KANJI 関連キーの物理配送判断を計算する純粋関数。
+    ///
+    /// - ImmCross プロファイル: Down/Up 共に Suppress（spurious 連鎖を構造的に遮断）
+    /// - Imm32Unavailable: shadow_toggle 発火時 KeyDown と全 KeyUp を Suppress
+    /// - TsfNative: 物理キーを通す（従来通り）
+    pub(crate) fn plan(
+        event: &RawKeyEvent,
+        profile: AppImeProfile,
+        shadow_toggled: bool,
+    ) -> Self {
+        let is_kanji_event = event.ime_relevance.shadow_action.is_some();
+        if !is_kanji_event {
+            return Self::Allow;
+        }
+        let suppress = if profile.can_use_imm32_cross_process() {
+            // ImmCross: KANJI 関連 VK は Down/Up 共に Suppress
+            true
+        } else {
+            // Imm32Unavailable: shadow_toggle 発火時 KeyDown + 全 KeyUp を Suppress
+            !profile.should_pass_physical_key()
+                && (shadow_toggled || matches!(event.event_type, KeyEventType::KeyUp))
+        };
+        if suppress {
+            Self::Suppress
+        } else {
+            Self::Allow
+        }
+    }
+}
