btn-recognizer 0.2.0

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
# Button framework testing strategy

This document defines the verification contract for the publishable `std`
button framework. Tests should verify externally visible behavior rather than
the current internal decomposition. The generic Mealy engine may be used by a
stage, but integration tests must not depend on private FSM states.

The strategy intentionally uses only the Rust standard library. Deterministic
exhaustive and pseudo-random tests provide broad sequence coverage without
adding property-testing dependencies to the crate.

## Normative conventions

The following rules are test requirements, not implementation suggestions.

- One engine update consumes a complete GPIO snapshot. Every level in that
  snapshot has the same `Timestamp` and must be considered atomically.
- Update timestamps are monotonically non-decreasing. Equal timestamps are
  valid; a regression returns an error and leaves all observable state
  unchanged.
- `EventBatch::processed_at` equals the timestamp of the update which returned
  the batch.
- Every physical or domain event satisfies:

  ```text
  occurred_at <= recognized_at <= EventBatch::processed_at
  ```

- A derived event uses the maximum of its own logical decision deadline and
  every causal input's `recognized_at` as its `recognized_at`. This rule is
  important when an old edge is replayed after chord arbitration.
- Debounce confirmation uses `elapsed >= duration`. The confirming sample is
  processed before the candidate deadline, so an opposite sample exactly at
  the deadline cancels the candidate instead of creating a transient edge.
- Tap and chord windows are inclusive. A qualifying `Down` exactly at the
  deadline participates in the pending tap or chord.
- A release exactly at a hold, milestone, or repeat deadline does not erase
  that deadline. The due hold/repeat event is emitted before `HoldEnd`.
- Chord recognition is eager. As soon as all members are down within the
  window, the chord is claimed; the recognizer does not wait until the window
  expires to search for a larger chord.
- Strict-subset chord configurations, such as both `A+B` and `A+B+C`, are
  invalid. Rejecting them makes eager recognition deterministic.
- A key which cannot start any configured chord is never delayed by chord
  arbitration.
- Failed chord candidates replay edges once, in original occurrence order,
  with original `occurred_at` values. Replay may therefore make occurrence
  timestamps appear older than events returned by an earlier update.
- Repeats are coalesced. One update emits at most one repeat event per logical
  control, with `Repeat { count }` describing all newly due intervals.
- The physical stream in `EventBatch::physical` is diagnostic and is not
  suppressed by chord recognition. Chord suppression applies to logical state
  and gesture events in `EventBatch::events`.

Use a one-nanosecond epsilon in boundary tests unless a test is specifically
exercising a lower-resolution clock:

```rust
const EPSILON: Duration = Duration::from_nanos(1);
```

## Test organization

The intended layout is:

```text
src/fsm_engine.rs          # private-state Mealy engine unit tests
src/key/config.rs          # configuration validation unit tests
src/key/debounce.rs        # debouncer and bank unit tests
src/key/chord.rs           # chord ledger and arbitration unit tests
src/key/gesture.rs         # per-control gesture unit tests
src/key/engine.rs          # coordinator unit tests
tests/support/mod.rs       # public-API harness, event builders, reference models
tests/debounce.rs          # public debounce behavior
tests/time.rs              # timestamps, deadlines, rollover adapter
tests/tap.rs               # tap and multi-tap behavior
tests/hold_repeat.rs       # hold, milestones, and repeat behavior
tests/chord.rs             # multi-key arbitration and suppression
tests/pipeline.rs          # end-to-end physical-to-domain output
tests/input_source.rs      # downstream queue and fallible sink adapter
tests/config_errors.rs     # errors through the public API
tests/randomized.rs        # deterministic exhaustive/model tests
tests/public_api.rs        # examples and stable public surface
```

Module unit tests may inspect candidate state, pending ledgers, and FSM state.
Files under `tests/` must use only public API and outputs.

### Shared harness

`tests/support/mod.rs` should provide a small harness with these operations:

```text
Harness::new(config, initial_levels)
snapshot(at, [(key, raw_level), ...]) -> Result<EventBatch, UpdateError>
advance_to(at) -> Result<EventBatch, UpdateError>
drain_physical() -> Vec<ButtonEdge>
drain_events() -> Vec<ButtonEvent>
```

The harness should retain the current complete level vector and change only
the named keys before submitting a snapshot. Event assertion helpers should
compare complete values, including control ID, phase or gesture, occurrence
time, recognition time, processed time, and order. Tests must not use
`contains` when exact output and ordering are part of the contract.

Use short symbols only in local test comments:

```text
U/P           normalized released/pressed sample
A.down@t      debounced physical Down for A at t
Wc            chord window
Wt            multi-tap window
Dp/Dr         press/release debounce duration
H1/H2         first and second hold thresholds
R0/Ri         first-repeat time and repeat interval
```

## Generic Mealy engine

The button framework still uses the hash-table-driven generic engine. Its
builder and runtime need their own release/debug-equivalent contract.

| Test | Input | Required result |
| --- | --- | --- |
| `basic_transition_returns_motion` | Register `Idle + Start -> Running + Emit`; step `Start` | State and motion match the transition. |
| `no_transition_preserves_state` | Step an unregistered event | Exact `NoTransition` error; state is unchanged. |
| `duplicate_on_is_build_error` | Register the same `(state,event)` twice | Exact `DuplicateTransition`; no debug-only panic or release-only overwrite. |
| `duplicate_inside_on_many_is_build_error` | Duplicate one key inside a batch | Same deterministic build error. |
| `missing_initial_state_is_build_error` | Build without initial state | Exact missing-initial-state variant. |
| `reset_restores_initial_state` | Traverse several states, then reset | Current state equals the configured initial state. |
| `clone_is_independent` | Clone a built machine, step only one clone | The other clone remains unchanged. |
| `errors_implement_std_error` | Pass errors to a helper requiring `std::error::Error` | Compile-time success and correct `source()`. |

Run the duplicate and overflow-sensitive tests in both debug and release
profiles. `debug_assert!` is not an acceptable public validation mechanism.

## Configuration validation

Each invalid configuration test must compare the complete `ConfigError`
variant and associated IDs. At minimum cover:

| Test | Configuration | Required result |
| --- | --- | --- |
| `empty_framework_is_valid_and_quiet` | No buttons, chords, or overrides | Validation succeeds; updates return empty batches. |
| `duplicate_key_is_rejected` | Two buttons share a `KeyId` | `DuplicateKey`. |
| `duplicate_chord_id_is_rejected` | Two chords share a `ChordId` | `DuplicateChord`. |
| `chord_requires_two_distinct_members` | Zero/one member, then repeated member | `ChordTooSmall` / `DuplicateChordMember`. |
| `unknown_chord_member_is_rejected` | Chord references an absent key | `UnknownChordMember`. |
| `duplicate_member_sets_are_rejected` | Same set in different member order | `DuplicateChordMembers`. |
| `strict_subset_chords_are_rejected_both_orders` | `A+B` with `A+B+C`, reverse config order too | `SubsetChords` in both cases. |
| `overlap_without_subset_is_valid` | `A+B` and `A+C` | Validation succeeds; runtime priority resolves simultaneous completion. |
| `unknown_override_control_is_rejected` | Override absent key or chord | `UnknownKey` / `UnknownChord`. |
| `zero_max_taps_is_rejected` | `max_taps = 0` | `ZeroMaxTaps`. |
| `hold_thresholds_must_be_strictly_increasing` | Duplicate and descending thresholds | `UnorderedHoldThresholds`. |
| `repeat_interval_must_be_nonzero` | `interval = 0` | `ZeroRepeatInterval`. |
| `repeat_requires_a_hold_threshold` | Repeat with no thresholds | `RepeatWithoutHold`. |
| `repeat_cannot_precede_hold` | `starts_after < H1` | `RepeatBeforeHold`. |
| `repeat_may_start_at_hold` | `starts_after == H1` | Validation succeeds; runtime order is HoldStart then Repeat. |
| `zero_debounce_and_windows_are_valid` | Zero debounce/tap/chord windows | Validation succeeds and boundary behavior remains deterministic. |

Repeat the gesture-validation cases for the default configuration and for a
per-control override so the error identifies the correct optional control.

## Debounce matrix

For the examples below, start released unless explicitly stated otherwise.

| Test | Input sequence | Required result |
| --- | --- | --- |
| `press_confirms_at_exact_deadline` | U@0, P@10, P@(10+Dp-EPSILON), P@(10+Dp) | Only the final sample emits one `Down`. |
| `late_confirmation_uses_sample_time` | P@10, next P sample at `10+Dp+20` | `occurred_at == recognized_at ==` the confirming sample time. |
| `opposite_sample_at_deadline_cancels_candidate` | P@10, U@(10+Dp) | No edge; stable state remains released and candidate is cleared. |
| `press_bounce_restarts_candidate_duration` | P@10, U@12, P@15 | No `Down` before `15+Dp`; exactly one at the deadline. |
| `release_confirms_at_exact_deadline` | Establish pressed, U@t, U@(t+Dr) | Exactly one `Up` at `t+Dr`. |
| `release_bounce_restarts_candidate_duration` | U@t, P@(t+2), U@(t+5) | Release duration restarts at `t+5`. |
| `asymmetric_debounce_uses_correct_duration` | `Dp != Dr`, one press/release cycle | Each phase uses its configured duration. |
| `zero_duration_confirms_immediately` | `Dp=Dr=0`, change sample | Edge is emitted by the same update. |
| `equal_timestamp_does_not_advance_candidate` | P@10 repeatedly, then P@(10+Dp) | Equal timestamps do not accumulate elapsed time. |
| `stable_samples_do_not_duplicate_edges` | Long runs of P then U | One Down and one Up only. |
| `initially_pressed_matches_config` | Construct with `initially_pressed=true` | Released sample starts release debounce; no synthetic initial Down. |
| `active_low_and_high_are_equivalent` | Mirror raw traces under both polarities | Normalized edge streams are identical. |
| `bank_preserves_configured_channel_order` | Several keys confirm in one snapshot | Physical edges use documented configuration order. |
| `snapshot_length_error_is_transactional` | Wrong-length snapshot at t, correct snapshot at t-1 | First error does not advance time or mutate any channel. |
| `bank_time_regression_is_transactional` | Valid t, invalid t-1, valid t again | The retry matches a fresh bank given only valid updates. |
| `two_candidates_do_not_interfere` | Bounce A while B confirms | B confirms on time; A remains independent. |

The `opposite_sample_at_deadline` case is a permanent regression test for the
old implementation's edge/timeout overwrite bug.

### Debounce reference model

Implement a test-only reference debouncer without using production FSM or
helpers. It needs only:

```text
stable: bool
candidate: Option<(bool, Timestamp)>
press_duration: Duration
release_duration: Duration
```

Enumerate all Boolean traces up to length 12 for timestamp steps chosen from
`{0, 1ns, D-EPSILON, D, D+EPSILON}` and compare exact output with the real
debouncer. This is small enough for ordinary `cargo test` and covers all
candidate cancellation/restart shapes.

## Timestamp and deadline tests

| Test | Input | Required result |
| --- | --- | --- |
| `equal_engine_timestamp_is_valid` | Two snapshots at t | No time error; only genuine zero-duration transitions occur. |
| `engine_time_regression_is_transactional` | Valid t, invalid t-1, then retry t | Exact error and output/state equality with a fresh engine. |
| `time_translation_preserves_behavior` | Run one trace, then run it with every time offset by C | Same event kinds/order; all three timestamp fields shift by C. |
| `all_events_obey_causal_timestamp_order` | Mixed bounce, replay, tap, hold, repeat trace | `occurred <= recognized <= processed` for every event. |
| `event_never_claims_future_processing` | Advance irregularly across many deadlines | No event timestamp exceeds batch `processed_at`. |
| `delayed_replay_preserves_causal_recognition_time` | Chord buffers Down until after its hold deadline, then replays | Hold occurrence uses its logical threshold; recognition is no earlier than replay recognition. |
| `deadline_addition_overflow_is_reported` | Timestamp near maximum plus a duration that cannot be represented | Typed error; no panic, saturation, or partial state change. |

If a public `WrappingTickExtender<u32>` is shipped, test it separately:

- ordinary increments and repeated raw ticks;
- `u32::MAX-2 -> 1` extends by four ticks;
- a wrapping delta below `2^31` is accepted;
- a delta greater than or equal to `2^31` is rejected as ambiguous;
- rejection leaves the extender retryable;
- the documentation states that callers must sample often enough that two
  wraps cannot occur between observations.

## Eager chord recognition

Chord tests should normally use zero debounce so they isolate arbitration.
Separate end-to-end tests must repeat representative cases with nonzero,
asymmetric debounce.

| Test | Input sequence | Required result |
| --- | --- | --- |
| `non_member_key_passes_without_delay` | X Down where X belongs to no chord | Immediate `Key(X) Down`; no pending candidate. |
| `first_member_is_buffered` | A Down for configured A+B | Physical Down is visible; no logical key event yet. |
| `completes_eagerly_in_forward_order` | A Down, B Down within Wc | Chord Down is emitted on B Down, without waiting for Wc. |
| `completes_eagerly_in_reverse_order` | B then A within Wc | Same chord and timestamps derived from the last member. |
| `simultaneous_members_are_atomic` | A and B confirm in one snapshot | One chord Down, no member logical Down; independent of channel iteration. |
| `member_at_exact_window_is_accepted` | A@0, B@Wc | Chord succeeds. |
| `member_after_window_is_rejected` | A@0, B@(Wc+EPSILON) | A is replayed before B is handled as a new candidate/input. |
| `release_at_window_while_other_member_down_does_not_match` | At Wc one pending member becomes Up while the other becomes Down | Final snapshot cannot form the chord; buffered edges replay in order. |
| `timeout_replays_original_down_once` | A Down, advance to Wc without B | One `Key(A) Down`, original occurrence time, recognition at arbitration decision. |
| `early_release_replays_down_then_up` | A Down then A Up before B | `Key(A) Down`, then `Key(A) Up`, exact original occurrence order. |
| `replay_does_not_duplicate_physical_stream` | Any failed candidate | Physical contains original edges once; logical replay contains them once. |
| `overlapping_complete_chords_use_priority` | Valid A+B and A+C complete in one atomic snapshot | Higher priority chord claims; loser members not claimed by it are replayed/continued correctly. |
| `equal_priority_overlap_uses_member_count_then_id` | Non-subset overlapping chords complete together | Documented deterministic tie-break applies. |
| `disjoint_chords_progress_independently` | Interleave A+B and C+D | Each candidate has its own deadline and can resolve independently. |
| `configuration_order_does_not_change_winner` | Permute chord declarations | Same recognized events and order. |
| `any_member_release_emits_chord_up_once` | Match chord, release one member | Chord Up at first member Up. |
| `all_members_release_waits_for_last_member` | `AllMembers`, release members separately | Chord remains down until final member Up. |
| `members_remain_suppressed_until_all_are_up` | End chord, keep another member held | No leaked member Down/Up/tap. |
| `repress_during_suppression_stays_captured` | A Up, A Down while B remains held, then releases | No member gesture until a state with all members physically Up is observed. |
| `member_behavior_recovers_after_full_release` | Finish suppression, then tap A | Normal key gesture is recognized. |
| `chord_is_a_normal_gesture_control` | Tap, hold, and repeat matched A+B | Events use `ControlId::Chord` and the same gesture semantics as a key. |

For a successful eager match:

- chord `Down.occurred_at` is the last member Down occurrence;
- chord `Down.recognized_at` is at least every member edge's recognition time;
- no successful member edge is replayed to the logical key stream;
- all member physical edges remain present in `EventBatch::physical`.

Do not add a test which expects `A+B` to wait for a possible `A+B+C` match.
That configuration must fail validation as `SubsetChords`.

## Tap and multi-tap matrix

Gesture unit tests should feed logical `ControlEdge` values directly.

| Test | Input sequence | Required result |
| --- | --- | --- |
| `single_tap_waits_for_window` | Down@0, Up@d where d<=tap_max | No Tap before `d+Wt`; `Tap{1}` at the deadline. |
| `tap_max_boundary_is_inclusive` | Up at `Down+tap_max` | Counts as a tap; `+EPSILON` does not. |
| `second_down_at_window_is_included` | First Up@u, second Down@(u+Wt) | Joins the pending group; no prior `Tap{1}`. |
| `second_down_after_window_starts_new_group` | Second Down@(u+Wt+EPSILON) | First `Tap{1}` resolves before the new press. |
| `max_taps_commits_immediately` | Complete exactly `max_taps` taps | One Tap event on final Up; no later duplicate. |
| `partial_group_commits_on_timeout` | Complete fewer than `max_taps` taps | One Tap with exact count at the final window deadline. |
| `three_taps_share_one_event_type` | Configure max=3 and complete three taps | `Tap { count: 3 }`, not separate gesture variants. |
| `controls_have_independent_tap_windows` | Interleave taps on A and B | Counts/deadlines do not interfere. |
| `late_advance_keeps_logical_tap_time` | Advance well beyond tap deadline | Occurrence remains final Up; recognition obeys logical deadline and causal floor. |
| `tap_event_is_emitted_once` | Continue idle updates after resolution | No duplicates. |
| `overlong_followup_does_not_count_as_tap` | Pending first tap, second press duration > tap_max but below hold | Second press is excluded; behavior of the completed prior group is explicitly asserted. |

The last case must be documented consistently by the public API; a completed
prior tap must not disappear merely because a later press is neither a tap nor
a hold.

### Hold after pending taps

Test both policies with a first completed tap followed by a second Down inside
the multi-tap window that reaches H1:

- `hold_after_tap_cancel_policy`: `CancelPendingTaps` emits only HoldStart and
  later HoldEnd; the pending tap group is discarded.
- `hold_after_tap_commit_policy`: `CommitPendingTaps` emits the previous Tap
  before HoldStart. The currently held press is not counted as a tap.

Exact event ordering and all timestamps must be asserted.

## Hold, milestones, and repeat

| Test | Input sequence | Required result |
| --- | --- | --- |
| `release_before_h1_is_not_hold` | Up at H1-EPSILON | No HoldStart/End; tap rules decide the press. |
| `release_at_h1_emits_start_then_end` | Up exactly at H1 | HoldStart followed by HoldEnd in one batch. |
| `late_update_emits_hold_once` | Down, next update after H1 | One HoldStart with logical threshold occurrence and causal recognition. |
| `milestones_are_strictly_ordered` | Hold through H1,H2,H3 | Start(H1), Milestone(H2), Milestone(H3), each once. |
| `release_at_milestone_emits_milestone_first` | Up exactly at H2 | H2 event precedes HoldEnd. |
| `hold_end_reports_total_duration` | Up after H1 | `held_for == Up.occurred_at - Down.occurred_at`. |
| `no_thresholds_means_no_hold` | Hold arbitrarily with empty threshold list | No hold/milestone/repeat events. |
| `repeat_starts_at_r0` | Hold to R0-EPSILON, then R0 | No repeat then `Repeat{count:1}`. |
| `repeat_equal_to_h1_follows_hold_start` | R0==H1 | HoldStart precedes Repeat{1}. |
| `repeat_jump_is_coalesced` | After last repeat, jump across N intervals | Exactly one `Repeat{count:N}` at the last newly due repeat deadline. |
| `same_time_update_does_not_repeat_again` | Update again without advancing | No duplicate repeat. |
| `release_at_repeat_deadline_repeats_first` | Up exactly at a due repeat | Coalesced Repeat precedes HoldEnd. |
| `release_between_repeats_does_not_round_up` | Up strictly before next repeat | Count includes only deadlines <= Up. |
| `repeat_stops_after_hold_end` | Advance many intervals after Up | No additional repeat. |
| `new_press_resets_repeat_accounting` | End hold and start another | New session begins at count one. |
| `huge_jump_has_bounded_output` | Jump across millions of intervals | One repeat event; runtime/output size does not scale with interval count. |

The large-jump test should check output cardinality rather than wall-clock
timing. A unit test may additionally assert that repeat count is calculated
arithmetically instead of by pushing one event per elapsed interval.

## Pipeline and `EventBatch`

End-to-end tests use raw GPIO snapshots and assert both output vectors.

| Test | Scenario | Required result |
| --- | --- | --- |
| `empty_update_has_processed_time` | No edges or deadlines at t | Empty vectors and `processed_at=t`. |
| `physical_edge_precedes_logical_key_state` | Non-chord key confirms | Physical edge and corresponding state event have exact IDs/times. |
| `pending_chord_keeps_physical_but_delays_logical` | First chord member confirms | Physical Down now; no logical member Down until resolve/replay. |
| `successful_chord_suppresses_member_domain_events` | Complete A+B | Chord state/gestures only; member physical edges still present. |
| `failed_chord_replay_enters_gesture_once` | Timeout then release A | Exactly one key press session and one resulting tap/hold classification. |
| `simultaneous_keys_are_deterministic` | Multiple independent edges/deadlines at t | Stable documented order, independent of hash iteration. |
| `gesture_override_applies_to_exact_control` | Different key/chord overrides | Each recognizer uses only its selected config. |
| `motion_prototype_receives_runtime_context` | Same FSM motion for A then B | Events contain correct control and current timestamps, with no stale context. |
| `one_bad_update_has_no_partial_outputs` | Length/time/overflow error midway | Error only; retry matches a fresh engine. |
| `batches_are_owned_and_independent` | Retain an old batch across more updates | Old values do not alias or change. |

HashMap iteration order must never determine simultaneous event order. Use a
documented order such as configured key order for physical edges and stable
`ControlId`/deadline order for domain events, then test it exactly.

## Input subsystem adapter

The recognition core returns `EventBatch`; it must not call a fallible external
sink while committing recognition state. If the crate ships an adapter backed
by `VecDeque`, use a scripted test sink whose calls are configured as
`Ok, Ok, Err, ...`.

Required adapter tests:

- `mapping_adds_source_code_sequence_and_times`: all downstream fields come
  from the current domain event and binding.
- `fifo_flush_sends_every_event_once`: successful flush preserves order.
- `failed_send_returns_event_ownership`: the sink error contains the exact
  unaccepted event and external error.
- `partial_flush_retains_failed_and_tail`: after failure at item k, items before
  k are gone; k and the untouched tail remain in original order.
- `retry_preserves_sequence_and_timestamp`: a recovered sink receives the same
  already-assigned event, not a newly numbered copy.
- `old_pending_precedes_new_engine_output`: new mapped events append behind
  previously blocked events.
- `repeated_failure_never_drops_or_duplicates`: queue contents remain exact
  across several retries.
- `empty_flush_does_not_call_sink`: no spurious sink interaction.
- `unmapped_event_follows_documented_policy`: explicit ignore or typed mapping
  error, never accidental silent loss.
- `one_domain_event_mapping_to_many_inputs_is_ordered`: partial downstream
  acceptance remains recoverable.

Use an unbounded `VecDeque` for the default `std` adapter if that is the public
choice, and document that memory growth is then application-controlled. If a
bounded adapter is added later, add full-capacity transactional tests before
publishing that feature.

## Deterministic randomized and exhaustive tests

No external crate is needed. Use a fixed LCG in test support:

```rust
fn next(state: &mut u64) -> u64 {
    *state = state
        .wrapping_mul(6_364_136_223_846_793_005)
        .wrapping_add(1_442_695_040_888_963_407);
    *state
}
```

The normal test suite should run at least 256 seeds with 4,096 updates per
seed for a three- or four-key framework. Generate:

- zero and positive timestamp increments;
- increments immediately below, at, and above configured deadlines;
- raw level flips and stable runs;
- overlapping but non-subset chords, plus independent chords;
- both release policies and hold-after-tap policies;
- occasional large time jumps to exercise repeat coalescing;
- a final all-released snapshot and advance beyond every pending deadline.

Validate these invariants after every successful update:

1. No valid monotonic input sequence panics.
2. Running the same config and trace twice produces byte-for-byte-equivalent
   logical values and ordering.
3. Every event satisfies the causal timestamp invariant.
4. Per physical key, confirmed Down and Up alternate from configured initial
   state; stable samples never duplicate an edge.
5. Per logical control, state Down and Up alternate.
6. No two active chords claim the same physical key.
7. Every buffered physical edge is eventually replayed exactly once or
   consumed by exactly one successful chord. It is never both or neither after
   final quiescence.
8. A successful chord never leaks member gestures while its capture set is
   active.
9. HoldStart occurs at most once per press; HoldEnd requires a prior HoldStart;
   milestones are ordered and unique.
10. Repeat occurs only after HoldStart and before HoldEnd, with nonzero count.
11. Tap count is in `1..=max_taps` and a held press is not also counted as a
    tap unless an explicitly documented prior-tap commit is emitted.
12. Advancing after final release beyond all windows leaves no pending event;
    further identical updates are empty.
13. Output cardinality for a single update is bounded by keys, active controls,
    and configured thresholds, not by elapsed repeat intervals.

Also exhaust all permutations of Down/Up edges for three keys at offsets
`Wc-EPSILON`, `Wc`, and `Wc+EPSILON`. This directly covers chord ordering and
inclusive-window mistakes that uniform random traces rarely hit.

Keep a slower stress variant behind `#[ignore]`, for example 4,096 seeds with
65,536 updates. CI may run it on a schedule, but the ordinary suite must remain
fast enough for every change.

## Documentation and public API tests

- README and crate-level quick starts are compiling doctests. Larger chord,
  multi-tap, hold, repeat, and input-mapping workflows may instead live in
  compiled examples and public-API integration tests when that keeps the
  documentation readable.
- Public errors are matched through documented variants and implement
  `std::error::Error`.
- Public event/config value types intended for comparison implement and test
  `Debug`, `Clone`, `PartialEq`, and `Eq`; IDs and timestamps also test `Hash`
  and ordering where promised.
- Examples use only exported module paths. No doctest may rely on private
  helpers or a fixed 10 ms polling interval.
- Rustdoc must state event ordering, all inclusive boundaries, initial-state
  behavior, chord suppression, replay timestamp behavior, and sink backpressure
  policy.

## Publish gates

The following commands are required on the release commit:

```bash
cargo fmt --all -- --check
cargo test --locked --all-targets --all-features
cargo test --release --locked --all-targets --all-features
cargo test --locked --doc --all-features
cargo clippy --locked --all-targets --all-features -- -D warnings
RUSTDOCFLAGS="-D warnings" cargo doc --locked --all-features --no-deps
cargo package --list
cargo package --locked
cargo publish --dry-run --locked
```

If features are introduced, also run the supported feature matrix, including
`--no-default-features` when it is meaningful. This crate is intentionally a
`std` crate; there is no `no_std` build gate.

Before `cargo package`, verify:

- package name, description, license, documentation, README, keywords, and
  categories describe the button framework accurately;
- repository/homepage metadata is included when the project has an
  authoritative public URL; a release must not invent one;
- the packaged file list contains no editor files, generated logs, local test
  artifacts, or obsolete demos;
- README and rustdoc links resolve;
- the staged package builds without relying on untracked workspace files;
- the declared MSRV, if any, passes the same public tests;
- debug and release tests have identical behavior;
- there are no runtime dependencies unless deliberately introduced and
  documented.

`cargo publish --dry-run` requires registry access and belongs in a networked
release job. All other behavioral tests remain locally executable with the
standard Rust toolchain and no third-party test dependencies.

## Completion criteria

The crate is not publish-ready merely because unit tests are green. Completion
requires all of the following evidence:

1. Every behavioral class above is covered by automated tests; one focused
   test may cover several adjacent matrix rows when it asserts all boundaries
   and exact output.
2. The exhaustive debounce oracle and randomized pipeline invariants pass in
   debug and release profiles.
3. Chord tests demonstrate eager success, strict-subset rejection, replay
   conservation, both release policies, and member suppression.
4. End-to-end tests prove the complete timestamp and `EventBatch` contract.
5. Sink failure tests prove ownership-preserving retry with no silent loss.
6. Every publish command succeeds from the packaged release state.