From 70e161bc08d85e71856004aeb29bf60a19982d4b Mon Sep 17 00:00:00 2001
From: vicrodh <103399283+vicrodh@users.noreply.github.com>
Date: Thu, 30 Jul 2026 08:29:08 -0600
Subject: [PATCH] docs(qt): playback_qt's header lists OWED PORTS, not
 "deliberate cuts"
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

It still advertised the gapless gap after the fix landed — the exact failure
the parity inventory was built to stop. A comment that outlives its gap is
worse than no comment: it reads as tracked.

Three corrections. The gapless entry is gone (it is wired). The blacklist entry
claimed "store not open", which is false — artist_blacklist is bound in
auth_qt's three session paths, so the store was open the whole time and only
the consumption was missing. And the framing: these are debt with an owed port
(TRACK-RULES rule 8), not scope decisions, so each now carries its
PARITY-DEBT.md row and its severity.

New cuts go in that file, not in this header.

cc
---
 crates/qbz-qt/src/playback_qt.rs | 40 +++++++++++++++++++++++---------
 1 file changed, 29 insertions(+), 11 deletions(-)

diff --git a/crates/qbz-qt/src/playback_qt.rs b/crates/qbz-qt/src/playback_qt.rs
index 333a1e94d..beda67cc8 100644
--- a/crates/qbz-qt/src/playback_qt.rs
+++ b/crates/qbz-qt/src/playback_qt.rs
@@ -5,18 +5,36 @@
 //! and the poll loop (PlaybackEvent -> UI state, track-change meta refresh,
 //! end-of-track advance).
 //!
-//! POC-NOTEs (deliberate cuts vs playback.rs, named for the effort report):
+//! OWED PORTS vs playback.rs. These are DEBT, not scope decisions: a fix that
+//! lived in the frontend is not inherited and has to be replicated (TRACK-RULES
+//! rule 8, whose title is "los fixes de backend deben llegar al Qt"). Each one
+//! is tracked in `qbz-nix-docs/qt-frontend/2026-07-30-parity-debt/PARITY-DEBT.md`
+//! — add there, not here, so a note cannot outlive its gap unnoticed. That is
+//! exactly how gapless stayed broken: this header advertised it for weeks.
+//!
+//! - Blacklist filtering of the QUEUE (PARITY-DEBT #1, AUDIBLE): the old note
+//!   here said "store not open", which is FALSE — `artist_blacklist` is bound
+//!   at `auth_qt.rs`. The Slint drops blacklisted tracks at ~18 play/enqueue
+//!   entry points (`filter_blacklisted_queue`, playback.rs:2624-2651); this
+//!   module has none, so a blocked artist still plays.
+//! - `advance_to_playable`, the bounded skip-unavailable walk
+//!   (playback.rs:455-511) (PARITY-DEBT #2, AUDIBLE): the advance here takes
+//!   the core queue's next directly and a failed play logs and returns, so one
+//!   unavailable track wedges the queue — and the early return skips the
+//!   refresh, leaving the bar on the previous track.
+//! - Volume persistence (PARITY-DEBT #3, AUDIBLE): never written or restored.
+//! - Session persist / resume-position: both prefs are persisted by settings
+//!   and read by nobody.
 //! - Streaming quality: seeded from ui_prefs ("streaming_quality") and
-//!   live-updated by Settings > Audio (settings_qt). The #638 device-cap
-//!   clamp lives in the Slint glue and is NOT ported.
-//! - Blacklist filtering of album tracks: skipped (store not open).
-//! - Offline-cache tier (offline bytes), gapless prefetch (`play_next`),
-//!   prefetch warming, stop-after, infinite refill, session persist,
-//!   QConnect/cast branches, recently-played recording: all out of scope.
-//!   Auto-advance therefore plays each successor at fetch time (audible
-//!   gap between tracks) — the engine's gapless path is NOT wired.
-//! - `advance_to_playable` (skip-unavailable walk): the POC advance takes
-//!   the core queue's next directly; a failed play logs and stops.
+//!   live-updated by Settings > Audio (settings_qt). The #638 device-cap clamp
+//!   lives in the Slint glue and is NOT ported.
+//! - Offline-cache tier (offline bytes), prefetch warming, stop-after,
+//!   infinite refill, QConnect branches, recently-played recording.
+//!
+//! DONE, previously listed here: gapless prefetch — the engine raises
+//! `gapless_ready` ~10s out and this module now answers it with `play_next`
+//! (both the streaming and the local/DSD arms), so transitions are
+//! sample-accurate again.
 
 use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
 use std::sync::{Arc, RwLock};