# 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.
| `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:
| `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.
| `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
| `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.
| `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.
| `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
| `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.
| `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.