Q-W0 code-review remediation: pitch_shift follower self-heal, T3-03 rate bail, doc/comment riders

tests/test_pitch_shift.cpp

@@ -501,7 +501,19 @@ static void testFreezeTailContinuousTone() {
 //        mono-sum-combing mechanism). The divergence witness: an INDEPENDENT shifter fed the
 //        follower's content picks a different lag on the same schedule, proving the mirror
 //        assertion is not vacuous (the two channels' contents genuinely disagree on the best
-//        alignment). ---
+//        alignment). A third shifter (`mirror`), primed with the SAME content as the master
+//        and driven via processLinked() with the master's own decisions, must reproduce the
+//        master's output BIT-IDENTICALLY every frame — this is the review-rider strengthening:
+//        the `ef == em` mirror check above only proves lastSplice_ was copied verbatim (which
+//        applySplice() always does), not that applySplice() actually reproduces splice()'s
+//        effect on posA_/fadeLen_/audio output; a same-content bit-identical check catches a
+//        real divergence there (e.g. an asymmetry between applySplice()'s unconditional
+//        `max(1, ev.fadeLen)` and splice()'s own fadeLen_ assignment). This driven-every-frame
+//        setup keeps both master and follower in lockstep the whole run (posA_/writePos_ stay
+//        identical since jumps are geometric, not content-dependent), so it exercises
+//        applySplice() on every splice — never the Q-W0 remediation self-healing fallback
+//        (own-search splice on a stale follower), which only fires when a follower has been
+//        skipped a block relative to the master (mono-render-block starvation). ---
 static void testStereoLinkedLagSharedSchedule() {
     const std::int64_t w = 2205;                 // the product window
     const std::size_t n = 40000;                 // ~17 splice cycles at ratio 2
@@ -515,28 +527,34 @@ static void testStereoLinkedLagSharedSchedule() {
         srcL[i] = static_cast<AudioSample>(std::sin(2.0 * kPi * fL * static_cast<double>(i)));
         srcR[i] = static_cast<AudioSample>(std::sin(2.0 * kPi * fR * static_cast<double>(i)));
     }
-    PitchShifter master, follower, independent;
+    PitchShifter master, follower, independent, mirror;
     master.configure(w);
     follower.configure(w);
     independent.configure(w);
+    mirror.configure(w);
     master.prime(srcL.data(), w);
     follower.prime(srcR.data(), w);        // linked: R content, master's decisions
     independent.prime(srcR.data(), w);     // control: R content, OWN search (pre-fix behavior)
+    mirror.prime(srcL.data(), w);          // SAME content as master: bit-identical witness
     master.setShiftRatio(2.0);
     follower.setShiftRatio(2.0);
     independent.setShiftRatio(2.0);
+    mirror.setShiftRatio(2.0);
 
     int spliceCount = 0;
     bool followerDiverged = false;
     bool independentDiverged = false;
+    bool mirrorDiverged = false;
     for (std::size_t i = 0; i < n; ++i) {
         const std::size_t si = i + static_cast<std::size_t>(w);
-        (void)master.process(srcL[si]);
+        const AudioSample oM = master.process(srcL[si]);
         const SpliceEvent& em = master.lastSplice();
         const AudioSample oR = follower.processLinked(srcR[si], em);
         CHECK(std::isfinite(oR));
         // The follower mirrors the master's decision EXACTLY, every frame (fired == false
-        // frames included — a follower must never splice on its own).
+        // frames included). In this driven-every-frame lockstep run the follower never falls
+        // behind, so it never reaches the Q-W0 self-healing fallback — every splice here goes
+        // through applySplice(), same as the mirror check below.
         const SpliceEvent& ef = follower.lastSplice();
         if (ef.fired != em.fired || ef.jump != em.jump || ef.lag != em.lag ||
             ef.frac != em.frac || ef.fadeLen != em.fadeLen) {
@@ -550,10 +568,16 @@ static void testStereoLinkedLagSharedSchedule() {
         if (ei.fired != em.fired || ei.lag != em.lag || ei.frac != em.frac) {
             independentDiverged = true;
         }
+        // The bit-identical witness: same content as the master, master's decisions applied
+        // via applySplice() instead of computed via splice() — the two code paths must produce
+        // the exact same sample stream.
+        const AudioSample oMirror = mirror.processLinked(srcL[si], em);
+        if (oMirror != oM) mirrorDiverged = true;
     }
     CHECK(spliceCount >= 3);        // the run actually exercised several splices
     CHECK(!followerDiverged);       // linked lag: one decision, one schedule, both channels
     CHECK(independentDiverged);     // non-tautology witness: unlinked channels DO disagree
+    CHECK(!mirrorDiverged);         // applySplice() reproduces splice() bit-identically
 }
 
 int main() {