btn-recognizer 0.2.1

Timestamp-driven button debouncing with multi-tap, hold, repeat, and multi-key chord gesture recognition
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
---
title: 按键消抖与多手势识别方案 — 软件架构设计
tags: [embedded, button, debounce, gesture, chord, fsm, rust]
desc: 基于时间戳驱动的按键消抖、多键和弦仲裁、点按/长按/重复手势识别的完整软件架构设计文档
update: 2026-07-18
---

```mermaid
mindmap
  root((按键手势识别))
    系统概述
      设计目标
      核心能力
    数据流架构
      四层管线
      事件批次
    时间模型
      Timestamp 设计
      因果关系约束
      截止时间语义
    去抖动模块
      DebounceBank
      Debouncer FSM
      非对称时长
    和弦仲裁模块
      ChordResolver
      急切匹配算法
      释放策略
      重叠消解
    手势识别模块
      GestureRecognizer
      点按检测
      长按与里程碑
      合并重复
      虚拟控制和弦
    输入适配层
      EventMapper
      QueuedInputSource
      BindingMapper
    通用Mealy引擎
      哈希表驱动
      声明式构建
      转移弧完整性
    配置与验证
      FrameworkConfig
      验证规则
      错误类型
    关键设计决策
      EFSM 模式
      所有权事件批次
      包容性窗口边界
      确定性排序
```

> [!note]
> **Ref:** [docs/ARCHITECTURE.md]ARCHITECTURE.md | [src/fsm_engine.rs]../src/fsm_engine.rs | [src/key/engine.rs]../src/key/engine.rs

---

# 按键消抖与多手势识别方案

## 一、系统概述

### 设计目标

本方案为嵌入式输入子系统提供一套**完整、可组合、时间戳驱动**的按键信号处理管线,覆盖从原始 GPIO 电平到语义化手势事件的全链路识别。核心设计原则:

- **时间确定性**:不依赖固定轮询间隔,所有计时基于调用者提供的单调时间戳
- **阶段分离**:去抖、和弦仲裁、手势识别各自拥有严格的所有权边界,互不耦合内部状态
- **可组合性**:每层可独立使用,也可通过 `ButtonEngine` 一键串联
- **零拷贝输出**:事件批次以所有权转移方式交付,识别状态机不会在返回后再持有事件引用
- **可测试性**:所有时间值由外部注入,可在确定性测试中精确控制时序

### 核心能力矩阵

| 能力 | 描述 | 配置项 |
|------|------|--------|
| 非对称去抖 | press/release 独立去抖时长,支持零去抖 | `DebounceConfig { press, release }` |
| 多点按 | 单次、双次及更高阶点按,统一 `Tap {count}` 表示 | `tap_max`, `multi_tap_window`, `max_taps` |
| 长按与里程碑 | 严格递增的多级长按阈值,每级独立事件 | `hold_thresholds: Vec<Duration>` |
| 合并重复 | 多个重复间隔合并为单次事件,避免追赶爆发 | `RepeatConfig { starts_after, interval }` |
| 多键和弦 | 急切匹配 + 优先级消解 + 可配置释放策略 | `ChordConfig { window, priority, release }` |
| 虚拟控制和弦 | 和弦作为独立 `ControlId` 重用全部手势识别逻辑 | 无需额外配置 |
| 有损适配 | 域事件 → 应用事件的映射、序列号、可重试 FIFO 队列 | `BindingMapper`, `QueuedInputSource` |

## 二、数据流架构

### 四层识别管线

```mermaid
flowchart LR
    A["GPIO 快照\nButtonSnapshot"] --> B["去抖层\nDebounceBank"]
    B -->|"ButtonEdge\n{key, phase, occurred_at, recognized_at}"| C["和弦仲裁层\nChordResolver"]
    C -->|"ControlEdge\n{Key|Chord, phase, ...}"| D["手势识别层\nGestureBank"]
    D -->|"ButtonEvent\n{State|Gesture, ...}"| E["输入适配层\nQueuedInputSource"]
    E -->|"InputEvent\n{source, sequence, code, value}"| F[应用层]
```

### 管线编排

`ButtonEngine::finish_update()` 内部严格按以下顺序调用各层:

1. **`gestures.advance_before(now, &pending_before)`** — 推进手势时钟至 `now` 之前(不含),排除被和弦挂起的按键
2. **`chords.process_batch(now, &physical)`** — 输入去抖后的物理边缘,输出仲裁后的控制边缘
3. **`gestures.resolve_suspensions(&claimed, now)`** — 解冻刚被和弦认领的按键的手势时钟
4. **`gestures.process_edges(control_edges)`** — 将控制边缘喂入手势识别器
5. **`gestures.advance_through(now, &pending_after)`** — 推进所有非挂起手势时钟至 `now`(含)

此顺序保证了因果正确性:已过期的截止时间在边缘处理之前触发,新产生的截止时间在边缘处理之后评估。

### 事件批次

```rust
pub struct EventBatch {
    pub processed_at: Timestamp,          // 本批次处理的逻辑时间
    pub physical: Vec<ButtonEdge>,        // 去抖后的物理边缘(诊断用)
    pub events: Vec<ButtonEvent>,         // 逻辑状态和手势事件
    pub next_wakeup: Option<Timestamp>,   // 最近的下一个截止时间
}
```

- `physical` 独立于和弦抑制——即使按键被和弦认领,其物理边缘仍出现在此流中
- `events` 包含经和弦仲裁后的逻辑状态事件和手势识别事件
- `next_wakeup` 告知调用者下一次需要在什么时间调用 `advance_to()`

## 三、时间模型

### Timestamp 设计

```rust
pub struct Timestamp(Duration);
```

- **单调时钟抽象**:`Timestamp` 包装 `std::time::Duration`,表示从应用定义的纪元开始的单调时间
- **框架不读取系统时钟**:调用者可使用硬件定时器、事件循环时钟或测试中的确定性值
- **仅支持加法**:提供 `checked_add` / `saturating_add` / `checked_duration_since`,不支持减法(防止时间倒退)

### 因果关系约束

框架内部和输出严格执行:

```text
occurred_at ≤ recognized_at ≤ processed_at
```

- `occurred_at`:逻辑边缘或截止时间发生的时刻
- `recognized_at`:框架能够确认并发布该事件的时刻
- `processed_at`:产生该批次的 `update()` 或 `advance_to()` 调用的时间戳

对于被和弦仲裁延迟的边缘,`occurred_at` 保持原始值,`recognized_at` 取原始识别时间和延迟释放时间的最大值,确保时间次序不会倒流。

### 截止时间语义

| 边界条件 | 行为 |
|----------|------|
| 点按窗口终点的第二个 Down | 计入点按组 |
| 和弦窗口终点的第二个成员 Down | 匹配成功 |
| 长按阈值处的释放 | 先发出长按事件,再处理释放 |
| 去抖候选期确认 | `elapsed >= duration`(相反采样在截止点取消候选) |

## 四、去抖动模块

### DebounceBank

```rust
pub struct DebounceBank {
    channels: Vec<DebounceChannel>,  // 配置顺序,一一对应 GPIO 快照
    last_update: Option<Timestamp>,
}
```

- 每次 `update()` 消费一个完整 GPIO 快照,`levels` 切片必须与配置的按钮顺序一致
- 内部对每个通道调用 `active_level.is_pressed(level)` 将原始电平归一化为 `bool`
- 返回的 `ButtonEdge` 中 `occurred_at == recognized_at == now`

### Debouncer FSM

```mermaid
stateDiagram-v2
    direction LR
    [*] --> Released
    Released --> PressCandidate : SamplePressed / ArmCandidate
    PressCandidate --> PressCandidate : SamplePressed / None
    PressCandidate --> Released : SampleReleased / CancelCandidate
    PressCandidate --> Pressed : CandidateStable / Confirm(Down)
    Pressed --> Pressed : SamplePressed / None
    Pressed --> ReleaseCandidate : SampleReleased / ArmCandidate
    ReleaseCandidate --> ReleaseCandidate : SampleReleased / None
    ReleaseCandidate --> Pressed : SamplePressed / CancelCandidate
    ReleaseCandidate --> Released : CandidateStable / Confirm(Up)
```

- 4 种状态:`Released` → `PressCandidate` → `Pressed` → `ReleaseCandidate` → `Released`
- 候选状态 (`PressCandidate` / `ReleaseCandidate`) 记录 `candidate_since` 时间戳,用于判断 `elapsed >= duration`
- 计时逻辑位于 `Debouncer` 外部(EFSM 模式),FSM 表只负责状态转移和 motion 生成
- 支持非对称时长:`DebounceConfig { press: Duration, release: Duration }`

### 关键设计决策

- **采样优先于截止时间处理**:`update()` 先执行采样(step SamplePressed/SampleReleased),再检查是否需要确认候选。这确保了在截止时间精确到达时的相反采样取消候选,而非产生短暂的错误稳定状态
- **`CandidateStable` 事件由宿主逻辑驱动**:FSM 表不感知时间流逝,计时完全在 `Debouncer::update()` 中管理

## 五、和弦仲裁模块

### ChordResolver

```rust
pub struct ChordResolver {
    rules: Vec<ChordRule>,                  // 和弦定义(成员集合 + 配置)
    rules_by_key: HashMap<KeyId, Vec<usize>>, // 按键 → 可能参与的和弦规则索引
    pending: HashMap<KeyId, PendingDown>,    // 等待匹配的按键 Down
    active: Vec<ActiveChord>,                // 已激活的和弦
    next_order: u64,                         // 全局输入顺序计数器
}
```

- **延迟策略**:只有属于至少一个配置和弦的按键才会被缓冲;不参与任何和弦的按键直接透传
- **急切匹配**:在同一批次中,一旦检测到某个和弦的所有成员都 Down 且在窗口内,立即认领
- **两阶段截止时间处理**:`process_batch` 先在 `< now` 处过期截止时间,处理新边缘后再在 `≤ now` 处过期,确保同一批次到达的成员能在截止时间之前被匹配

### 匹配算法

`process_batch()` 的核心流程:

1. **过期 `(< now)`**:移除所有在 `now` 之前过期的候选资格
2. **处理活跃和弦**:将输入边缘路由到已激活和弦,处理成员按压/释放
3. **检查新候选**:对每个新 Down 计算候选资格(`occurred_at + window`)
4. **激活完整和弦**:找出所有成员已齐备的候选和弦,按优先级→成员数→ChordId 排序,贪心选择不相交的集合
5. **移除被阻塞资格**:被选中和弦的成员键从其他候选和弦的资格中移除
6. **过期 `(≤ now)`**:移除所有在 `now` 处到期的剩余资格

### 重叠消解

当多个完整和弦候选共享成员时,按以下优先级贪心选择:

```rust
fn compare_rules(left: &ChordRule, right: &ChordRule) -> Ordering {
    right.priority.cmp(&left.priority)               // 1. 优先级降序
        .then_with(|| right.members.len().cmp(&left.members.len()))  // 2. 成员数降序
        .then_with(|| left.id.cmp(&right.id))        // 3. ChordId 升序(确定性打破平局)
}
```

无法匹配的按键以原始发生时间重放为独立按键边缘。

### 释放策略

| 策略 | 行为 | 成员抑制 |
|------|------|----------|
| `AnyMember` | 任意成员释放即发出和弦 Up | 所有成员必须物理释放后才解除捕获 |
| `AllMembers` | 所有成员释放后才发出和弦 Up | 所有成员必须物理释放后才解除捕获 |

成员抑制防止部分和弦释放泄露虚假的单键点击:即使和弦已发出 Up,成员按键在全部物理释放前仍被捕获,其边缘被激活和弦吸收而不产生独立的按键事件。

### 严格子集检查

配置验证阶段拒绝子集关系和弦(如同时配置 `A+B` 和 `A+B+C`),因为急切匹配无法在不引入额外延迟的情况下区分一个较短和弦的完成和更长和弦的前缀。

## 六、手势识别模块

### GestureRecognizer

```rust
pub struct GestureRecognizer {
    control: ControlId,
    config: GestureConfig,
    fsm: Fsm<State, Event, Motion>,
    processed_to: Timestamp,
    // 按压上下文
    down_at: Option<Timestamp>,
    press_recognized_at: Option<Timestamp>,
    // 点按上下文
    tap_count: u8,
    last_tap_up: Option<Timestamp>,
    tap_causal_recognized_at: Option<Timestamp>,
    tap_deadline: Option<Timestamp>,
    // 长按/重复上下文
    next_hold_index: usize,
    next_repeat_at: Option<Timestamp>,
}
```

每个逻辑控制(物理按键或虚拟和弦)拥有独立的识别器实例。

### 手势 FSM

```mermaid
stateDiagram-v2
    direction LR
    [*] --> Idle
    Idle --> Pressed : Down / StartPress
    AwaitNextTap --> Pressed : Down / StartPress
    Pressed --> AwaitNextTap : UpTapWait / RecordTap
    Pressed --> Idle : UpTapComplete / CompleteTap
    Pressed --> Idle : UpInvalid / AbortPress
    Pressed --> Holding : HoldReached / StartHold
    Holding --> Holding : HoldMilestoneReached / EmitHoldMilestone
    Holding --> Holding : RepeatDue / EmitRepeat
    Holding --> Idle : HeldUp / CompleteHold
    AwaitNextTap --> Idle : TapWindowExpired / CompleteTap
```

### 点按检测

1. `Down` → 进入 `Pressed`,记录 `down_at`
2. `Up` 在 `tap_max` 内:`held_for ≤ tap_max`
   - 若 `tap_count + 1 < max_taps`:进入 `AwaitNextTap`,设置 `tap_deadline = now + multi_tap_window`
   - 若 `tap_count + 1 ≥ max_taps`:立即完成点按,发出 `Tap {count}`,进入 `Idle`
3. `AwaitNextTap` 状态下 `multi_tap_window` 过期:发出当前累积的 `Tap {count}`,进入 `Idle`
4. 新 `Down` 在 `multi_tap_window` 内:回到 `Pressed`,继续累积

### 长按与里程碑

- `hold_thresholds` 为严格递增的 `Vec<Duration>`,第一个阈值将按压从 `Pressed` 转为 `Holding`
- 进入 `Holding` 后根据 `HoldAfterTapPolicy` 处理待定中的点按:
  - `CancelPendingTaps`:清空点按上下文
  - `CommitPendingTaps`:先发出已完成的点按事件
- 后续阈值在当前状态为 `Holding` 时依次触发,每个发出 `HoldMilestone {threshold}` 事件
- 释放时发出 `HoldEnd {held_for}`,其中 `held_for = occurred_at - down_at`

### 合并重复

`process_due_repeats()` 将多个已过去的重复间隔合并为一次事件:

```rust
let due_count = elapsed / interval + 1;          // 应触发次数
let occurred_at = next_repeat_at + interval * (due_count - 1);  // 最后一次重复的逻辑时间
// 发出 Repeat { count: due_count }
// 更新 next_repeat_at = next_repeat_at + interval * due_count
```

- 一次 update 最多发出一个 `Repeat` 事件
- `count` 值告知应用层发生了多少次重复,应用可自行决定是否展开处理
- 长时未调用导致的巨大 `due_count` 通过 `u64::MAX` 饱和,时间戳通过 `saturating_add` 保护

### 虚拟控制和弦

和弦激活后产生的 `ControlId::Chord(chord_id)` 作为独立控制 ID 进入 `GestureBank` 查找对应的识别器。和弦的 Down/Up 控制边缘驱动与物理按键完全相同的手势状态机,使得和弦支持点按、长按、里程碑和重复。

### GestureBank

```rust
pub struct GestureBank {
    recognizers: HashMap<ControlId, GestureRecognizer>,
}
```

- `advance_impl()` 对 `recognizers` 按键进行 `sort_unstable()` 后迭代,保证确定性输出
- `next_deadline_excluding()` 接收被和弦挂起的按键 ID 集合,跳过它们计算最早截止时间
- `resolve_suspensions()` 处理刚被和弦认领的按键,将其手势时钟推进至当前时间

## 七、输入适配层

### 架构原则

识别管线与事件消费**刻意分离**。识别核心返回 owned `EventBatch`,输入适配器将其映射为应用层事件。这种设计保证了:即使下游 sink 失败,识别状态不会因为外部错误而回滚或丢失。

### EventMapper

```rust
pub trait EventMapper {
    type Output;
    type Error;

    fn map_event(&mut self, event: &ButtonEvent, output: &mut Vec<Self::Output>) -> Result<(), Self::Error>;
    fn map_batch(&mut self, events: &[ButtonEvent], output: &mut Vec<Self::Output>) -> Result<(), Self::Error>;
}
```

- `map_event`:映射单个域事件,默认 `map_batch` 的 fallback
- `map_batch`:映射整个批次,有状态映射器应覆写此方法实现事务性预检

### QueuedInputSource

```rust
pub struct QueuedInputSource<M: EventMapper> {
    mapper: M,
    pending: VecDeque<M::Output>,
}
```

- 映射在临时 `Vec` 中进行,成功后才 `extend` 到 `pending` 队列——批次原子性
- `flush_to()` 逐个交付给 `TryEventSink`,被拒绝的事件通过 `push_front` 放回队首,保证 FIFO 顺序
- `drain()` 一次性取出所有待处理事件

### BindingMapper

```rust
pub struct BindingMapper<Code> {
    source: SourceId,
    next_sequence: Option<u64>,
    bindings: HashMap<(ControlId, EventSelector), Vec<Binding<Code>>>,
}
```

- 将 `(ControlId, EventSelector)` 映射为应用层 `InputEvent<Code>`
- 每个绑定通过 `BindingValue::Fixed(value)` 指定固定值,或 `BindingValue::Auto` 从域事件中提取(如点按计数、长按时长)
- 序列号预检:在映射前计算所需序列号数量,确认不溢出后才开始产出事件,保证批次事务性
- 未映射的事件被显式忽略,不消耗序列号

## 八、通用 Mealy 状态机引擎

### 设计

```rust
pub struct Fsm<S, E, M> {
    transitions: HashMap<(S, E), Transition<S, M>>,
    state: S,
    initial_state: S,
}
```

- **哈希表驱动**:转移表为 `HashMap<(CurrentState, Event), (NextState, Motion)>`
- **Mealy 机模型**:输出(motion)绑定在转移弧上,而非状态节点上
- **零分配运行时**:`step()` 仅执行一次 HashMap 查找,无堆分配
- **重复转移检测**:`FsmBuilder` 在注册阶段惰性记录重复键,`build()` 时返回 `BuildError::DuplicateTransition`
- **克隆语义**:`Fsm` 派生 `Clone`,深拷贝转移表和当前状态

### 声明式构建

```rust
let fsm = Fsm::builder()
    .initial_state(State::Idle)
    .on(State::Idle, Event::Start, State::Running, Motion::Log("started"))
    .on(State::Running, Event::Stop, State::Idle, Motion::Alert)
    .build()?;
```

构建器支持 `.on_many(iter)` 从任意迭代器批量注册转移弧。重复转移报错使用惰性检测策略:保留第一条转移,记录第一个重复键,`build()` 时返回错误。

### 在本框架中的角色

通用引擎仅包含有限控制状态。时间戳、计数器、候选集、输出队列等扩展状态全部留在宿主识别器中(EFSM 模式),避免状态爆炸和业务逻辑回到单体解析器中。

## 九、配置与验证

### FrameworkConfig

```rust
pub struct FrameworkConfig {
    pub buttons: Vec<ButtonConfig>,                          // 物理按钮定义
    pub chords: Vec<ChordConfig>,                            // 和弦定义
    pub default_gestures: GestureConfig,                     // 默认手势配置
    pub gesture_overrides: HashMap<ControlId, GestureConfig>, // 按控制覆盖
}
```

`GestureConfig` 按 `ControlId` 查找:先查 `gesture_overrides`,fallback 到 `default_gestures`。这允许不同和弦使用不同的手势参数。

### 验证规则

`FrameworkConfig::validate()` 执行以下检查:

| 检查项 | 错误变体 |
|--------|----------|
| 按钮 ID 唯一 | `DuplicateKey` |
| 和弦 ID 唯一 | `DuplicateChord` |
| 和弦成员数 ≥ 2 | `ChordTooSmall` |
| 和弦成员不重复 | `DuplicateChordMember` |
| 和弦成员引用已知按钮 | `UnknownChordMember` |
| 和弦成员集合不重复 | `DuplicateChordMembers` |
| 无子集和弦关系 | `SubsetChords` |
| `max_taps > 0` | `ZeroMaxTaps` |
| `hold_thresholds` 严格递增 | `UnorderedHoldThresholds` |
| `repeat.interval > 0` | `ZeroRepeatInterval` |
| repeat 需配合 hold | `RepeatWithoutHold` |
| `repeat.starts_after ≥ 首个 hold_threshold` | `RepeatBeforeHold` |
| 手势覆盖引用已知控制 | `UnknownKey` / `UnknownChord` |

所有 `ConfigError` 变体实现 `Display` + `Error` trait,提供可读的错误消息。

### 前向跨度预检

`ButtonEngine` 在构造时计算 `max_future_span`——所有和弦窗口和手势截止时间的最大值。每次 `update()` / `advance_to()` 调用前通过 `preflight()` 检查 `now + max_future_span` 不会溢出 `Timestamp`,确保所有内部截止时间计算都在安全范围内。

## 十、错误处理

### 错误类型层次

```text
UpdateError (引擎层)
├── SnapshotLength    — GPIO 快照长度不匹配
├── TimeRegression    — 时间戳倒退
├── TimestampExhausted — 时间戳溢出风险
├── Debounce(DebounceBankError)
│   ├── SnapshotLength
│   ├── TimeRegression
│   └── Channel(DebounceError)
│       ├── TimeRegression
│       └── InvalidTransition
├── Chord(ChordError)
│   ├── TimeRegression
│   ├── InvalidEdgeCausality
│   ├── EdgeAfterBatch
│   ├── DuplicateKeyInBatch
│   ├── DuplicatePendingDown
│   ├── DeadlineOverflow
│   └── OrderOverflow
├── Gesture(GestureError)
│   ├── UnknownControl
│   ├── TimeRegression
│   ├── InvalidCausality
│   ├── UnexpectedEdge
│   ├── EventBeforePress
│   ├── MissingPressContext
│   ├── DeadlineOverflow
│   └── InvalidTransition
└── InvalidOutputCausality  — 输出事件违反因果关系
```

### 错误传播策略

- **FSM 转移错误**(`InvalidTransition`):表示转移表存在空洞。在配置静止的情况下不应发生,但通过错误传播而非 panic 保证鲁棒性
- **时间回归错误**:每层独立检查,最早检测到的一层返回错误
- **配置错误**(`ConfigError`):在 `ButtonEngine::new()` 阶段即被捕获,阻止无效引擎的创建
- **输入适配层错误**:`FlushError` 携带已成功交付的数量和拒绝原因,调用者可据此决定重试或放弃策略

## 十一、关键设计决策

### 1. EFSM 模式(扩展有限状态机)

**决策**:有限控制状态(按钮、手势阶段)放入通用 FSM,扩展状态(时间戳、计数器、集合)留在宿主识别器中。

**理由**:
- 将时间信息编码进 FSM 状态会导致状态爆炸(`Pressed × 1000ms × 1000ms` 种组合)
- 保持 FSM 表小而可验证(去抖 4 状态 9 转移,手势 4 状态 10 转移)
- 宿主代码(`Debouncer`、`GestureRecognizer`)负责计时和策略决策,FSM 只负责阶段转换

### 2. 所有权事件批次

**决策**:识别管线返回 owned `EventBatch`,而非通过回调或 channel 推送。

**理由**:
- 防止外部 fallible sink 导致识别状态不一致("先更新状态再通知失败"的反模式)
- 调用者可以检查、过滤、缓存批次后再交付下游
- 物理边缘和逻辑事件分离在同一批次中,消费者按需获取

### 3. 包容性窗口边界

**决策**:点按和弦窗口包含终点(`≤` 而非 `<`)。

**理由**:
- 物理上同时发生的按键事件可能在相邻采样帧中到达
- 包容性窗口确保精确截止时间处的第二个 Down 被计入,避免因微小的帧对齐差异产生错误行为
- 释放/截止时间的交互通过 `advance_impl` 的两阶段处理(`before` / `through`)精细控制

### 4. 时钟挂起机制

**决策**:在等待和弦仲裁期间,挂起成员按键的手势时钟。

**理由**:
- 和弦仲裁可能需要延迟交付按键 Down 事件(窗口等待期)
- 在此期间按键的时钟不应推进,否则事件发生时间和识别时间会产生不合理的偏差
- `GestureBank` 通过 `suspended_keys` 参数显式控制哪些按键的时钟暂停

### 5. 确定性排序

**决策**:所有基于 `HashMap` 的迭代在输出前进行显式排序。

**理由**:
- Rust `HashMap` 的迭代顺序在不同运行之间不确定
- 手势识别器之间相互独立,但输出事件的顺序应可重现
- `GestureBank::advance_impl()` 和 `ChordResolver::sort_ordered_output()` 均执行显式排序

### 6. 去抖时间决定和弦时序粒度

**决策**:去抖后的边缘以确认时间(而非物理转换时间)作为 `occurred_at`。

**理由**:
- 物理按键的精确转换时刻在去抖窗口内是不确定的
- 以去抖确认时间为准简化了跨层时序推理
- 代价:去抖时长成为和弦匹配的有效时序分辨率——需要短和弦窗口时应相应缩短去抖时长

### 7. `#![forbid(unsafe_code)]`

**决策**:整个 crate 禁止 unsafe 代码。

**理由**:
- 所有核心逻辑可安全地用 Rust 标准库表达
- 适合在安全关键的嵌入式上下文中审查和部署
- 不依赖外部 FFI 或硬件访问(由调用者提供 GPIO 快照和时间戳)