crabidy/quality/queue-order.md

# Quality gates: queue de-duplication and sorting

Criteria an implementation of `architecture/queue-order.md` must satisfy.
Automatic tests cover the behaviour (see "Tests" at the end); the gates here
are the things a reader has to check by reading the code. Each is pass/fail.

## Correctness of the operations

- [ ] **G1 — Dedup never removes the playing entry.** In every group of
  duplicates the survivor is the entry at the current position when it is in
  the group, otherwise the earliest one (D4). Check the survivor selection
  directly, not only through a test: a "keep the first" shortcut is a silent
  playback stop the moment the playing copy is a later one.
- [ ] **G2 — The default duplicate identity is provider-scoped.** The key is
  `(first path segment, provider_item_id)` when the id is non-empty and the
  whole path otherwise (D3). Artist/title matching exists **only** under the
  opt-in `by_title` identity (D3a), never on the default path, and the flag is
  never defaulted to true anywhere between key and wire.
- [ ] **G2a — `by_title` keeps the longest take** and still yields to the
  playing entry (D3a), and every client surface that reaches it is distinct
  from the safe one (its own key, its own flag) — a user cannot get it by
  mistyping.
- [ ] **G3 — Sort is stable and total.** `sort_permutation` returns a
  permutation of `0..len` for every strategy and direction, equal keys keep
  their queue order, and blanks/unknown durations sort last in *both*
  directions (D7, D8). No comparator may panic (no `unwrap` on a partial
  comparison, no float keys).
- [ ] **G4 — Sort keys are computed once per track.** Decorate–sort–undecorate,
  not a comparator that lowercases inside the comparison (A5). A ten-thousand
  entry queue must not allocate per comparison.
- [ ] **G5 — Reverse ignores the direction flag** (D6), and
  `QueueSort::Unspecified` reaching `QueueManager::sort` is a no-op rather
  than an arbitrary default.
- [ ] **G6 — The play-order invariant holds after both operations.**
  `play_order` indexes every track exactly once and `current_offset` points
  into it (the invariant `shuffle_insert_keeps_order_unique` guards for
  inserts). Shuffle off ⇒ rebuilt from the new order; shuffle on ⇒ remapped
  through the permutation, so the remaining play sequence is unchanged (D10).
- [ ] **G7 — Dedup goes through `remove_tracks`.** There is exactly one place
  that removes queue entries (D5). A second removal implementation that
  maintains `play_order` itself is a fail even if its tests pass.

## Server discipline

- [ ] **G8 — Both operations run on the playback loop and nowhere else.** No
  queue mutation outside a `PlaybackCommand` arm; the queue lock is never held
  across an `await` (the pattern every existing arm follows).
- [ ] **G9 — One broadcast site.** Both go out through `broadcast_queue`, so
  the persister and the update stream cannot drift (D12). A dedup that removed
  nothing broadcasts nothing.
- [ ] **G10 — No panics on client input.** `SortQueue` with an unset or
  unknown enum value answers `InvalidArgument`; `DedupQueue` with a dropped
  result receiver logs and continues; an empty queue is a no-op for both. No
  `unwrap`/`expect`/indexing that a client can reach.
- [ ] **G11 — Both RPCs are in the rights matrix as `QueueOwner`** (D1), and
  the pinned method-list test in `auth.rs` includes them. A new RPC must not
  be able to reach the wire unmapped.
- [ ] **G12 — The dedup count crosses the boundary as a number.** No
  server-formatted human string on the wire or in a `MessageToUi` (D2, D15);
  wording belongs to each client.
- [ ] **G13 — Nothing is logged that could carry a credential.** Sort logs the
  strategy, dedup logs a count. No track paths, no URLs — a queue entry's path
  can be a `/rss` item whose URL is a per-subscriber token.

## Clients

- [ ] **G14 — No client computes an order.** No comparators, no
  duplicate-finding, and no `Remove`-derived dedup in `cbd-tui`, `cbd-web` or
  `cbd-cli` (A1, Option A rejected). Clients send the verb and render what
  comes back.
- [ ] **G15 — The sort menu is strictly modal.** While it is open the bindings
  table is unreachable and an unclaimed key leaves it open rather than falling
  through — a stray `c` must not clear the queue while the user thinks they are
  picking a sort (D14).
- [ ] **G16 — Both operations are reachable without a keyboard in the web
  client** (D16): toolbar buttons dispatching the same actions as `u` and `S`,
  and the strategy list exists once (`SORT_CHOICES`), driving both the overlay
  and the button.
- [ ] **G17 — The TUI and web keymaps agree**: `u` = dedup, `S` = sort menu,
  and the same five menu letters with the same uppercase-is-descending rule.
  Where they differ, the difference is deliberate and documented.
- [ ] **G18 — Feedback exists for both outcomes of a dedup.** `0` renders as
  plainly as `7` (D2/D15) — a dedup that found nothing must not look like a
  dropped keypress.
- [ ] **G19 — The CLI strategy is a `ValueEnum`** (D17), so a typo is a parse
  error, the shell completes it, and the printed confirmation names the
  strategy in the same spelling the user typed.
- [ ] **G20 — Every new binding is documented where the others are**: the TUI
  help modal (derived from `BINDINGS`, so automatic), the web help overlay
  table, `docs/src/clients/tui.md`, `docs/src/clients/cli.md`, and
  `docs/src/queue.md`'s queue-operation list.

## Documentation and honesty

- [ ] **G21 — The proto documents the semantics at the wire.** What a
  duplicate is, which copy survives, that unknowns sort last, that `Reverse`
  ignores `descending`, and that `UNSPECIFIED` is refused.
- [ ] **G22 — The known gaps are written down, not left to be discovered**: a
  captured copy and its streaming source are not duplicates (D3), a sort with
  shuffle on does not change what plays next (D10), and tracks still resolving
  land unsorted after the fact (D11).
- [ ] **G23 — Public items have doc comments** stating intent and edge
  behaviour, in the register the surrounding code uses (why, not what).

## Tests

Behaviour is pinned by these, all of which must pass:

| Area | Test home | Pins |
| --- | --- | --- |
| Identity, survivors, permutations | `queue_order.rs` | D3, D4, D6–D9 |
| Play-order invariants | `lib.rs` (`QueueManager`) | D5, D10, empty queues |
| Wiring, broadcast, persistence | `playback.rs` | D2, D9, D12 |
| Argument validation | `rpc.rs` | D6, the count |
| Rights matrix | `auth.rs` (existing pinned test) | D1 |
| Keys and modality | `cbd-tui/src/app/{bindings,sort,mod}.rs` | D14 |
| Pane feedback | `cbd-tui/src/app/queue.rs` | D15 |
| Command parsing | `cbd-cli/src/lib.rs` | D17 |
| Keymap parity | `cbd-web/src/keymap.rs` | D16, D17 |

The server rows live under `crabidy-server/src/`.

Plus the repository's standing gates: `cargo clippy` clean, `cargo fmt`,
no new `unwrap` on client-reachable paths, and the book building.