Γ-W1-T7: make Preserve's splices pitch-synchronous — the jump is a whole number of the source's own period, detected once at load

30 Hz out-of-band energy 15.45% -> 0.00%; the 29 Hz rate-2.0 detune -133 -> +0 cents.
An unknown period keeps the fixed-window geometry bit for bit. The detector cannot
reach process(): sampler_core does not link it.

src/core/instrument/engine/pitch_shift.cpp

@@ -4,8 +4,9 @@
 // frame the caller feeds; the active read tap advances by the shift `ratio_` per OUTPUT frame,
 // so its delay behind the writer drifts at (feedRate - ratio) per frame — one frame in, one
 // frame out (`feedRate == 1`) preserves duration, and any other feed cadence stretches it. When
-// that delay leaves the safe band [dLow, dHigh], the tap is relocated by a nominal jump of
-// one window — clamped to the filled span so it never lands in unwritten silence — refined
+// that delay leaves the safe band [dLow, dHigh], the tap is relocated by a nominal jump (one
+// window, or the nearest whole number of source periods to it once setSourcePeriod names one)
+// — clamped to the filled span so it never lands in unwritten silence — refined
 // by a cross-correlation search over +/- maxLag plus a parabolic peak interpolation for a
 // sub-sample lag (an integer-only lag left +/-0.5-sample errors: a sideband comb at the
 // splice cadence on a repitched pure sine). Old and new taps then crossfade over fadeFrames
@@ -26,6 +27,23 @@ constexpr double kPi = 3.14159265358979323846;
 
 }  // namespace
 
+std::int64_t periodAlignedJump(std::int64_t windowFrames, std::int64_t maxJumpFrames,
+                               double periodFrames) {
+    if (windowFrames <= 1 || maxJumpFrames < 1) return windowFrames;
+    if (!(periodFrames > 0.0)) return windowFrames;
+    if (periodFrames > static_cast<double>(maxJumpFrames)) return windowFrames;
+    std::int64_t n = static_cast<std::int64_t>(
+        static_cast<double>(windowFrames) / periodFrames + 0.5);
+    if (n < 1) n = 1;
+    std::int64_t jump = static_cast<std::int64_t>(periodFrames * static_cast<double>(n) + 0.5);
+    while (jump > maxJumpFrames && n > 1) {
+        --n;
+        jump = static_cast<std::int64_t>(periodFrames * static_cast<double>(n) + 0.5);
+    }
+    if (jump < 1 || jump > maxJumpFrames) return windowFrames;
+    return jump;
+}
+
 void PitchShifter::configure(std::int64_t windowFrames) {
     window_ = windowFrames;
     if (window_ <= 1) {
@@ -37,6 +55,8 @@ void PitchShifter::configure(std::int64_t windowFrames) {
         fading_ = false;
         fadePos_ = 0;
         fadeFrames_ = fadeLen_ = maxLag_ = corrFrames_ = dLow_ = dHigh_ = 0;
+        period_ = 0.0;
+        jump_ = jumpMax_ = 0;
         filled_ = 0;
         ratio_ = 1.0;
         feedRate_ = 1.0;
@@ -62,6 +82,9 @@ void PitchShifter::configure(std::int64_t windowFrames) {
     dLow_ = window_ / 4;
     dHigh_ = ringLen_ - window_ / 4;
     corrFrames_ = std::max<std::int64_t>(1, std::min<std::int64_t>(dLow_ - 1, 512));
+    // The delay band is (dHigh_ - dLow_) wide and the search can add up to maxLag_ on either
+    // side; one frame more than that and a jump could land exactly ON a trigger boundary.
+    jumpMax_ = std::max<std::int64_t>(1, dHigh_ - dLow_ - maxLag_ - 1);
     fadeLen_ = 0;
     reset();
 }
@@ -88,10 +111,17 @@ void PitchShifter::reset() {
     filled_ = 0;
     ratio_ = 1.0;
     feedRate_ = 1.0;
+    period_ = 0.0;
+    jump_ = window_ > 1 ? window_ : 0;
     tailFrozen_ = false;
     lastSplice_ = SpliceEvent{};
 }
 
+void PitchShifter::setSourcePeriod(double periodFrames) {
+    period_ = periodFrames > 0.0 ? periodFrames : 0.0;
+    jump_ = window_ > 1 ? periodAlignedJump(window_, jumpMax_, period_) : 0;
+}
+
 void PitchShifter::freezeTail() {
     if (window_ <= 1 || tailFrozen_) return;
     tailFrozen_ = true;
@@ -199,7 +229,10 @@ void PitchShifter::splice(std::int64_t nominalJump, double delay) {
     std::int64_t jump = nominalJump;
     if (jump > 0) {
         const std::int64_t maxJump = filled_ - d - maxLag_ - 1;
-        if (jump > maxJump) jump = maxJump;
+        // Shortening a period-aligned jump to fit must land on a SHORTER MULTIPLE, not on the
+        // raw bound — a clamped jump is an unaligned one, which is the whole failure this
+        // module now avoids. With no period known (or none fitting) this is the bare clamp.
+        if (jump > maxJump) jump = periodAlignedJump(maxJump, maxJump, period_);
         if (jump < 1) jump = 1;
     }
     // The correlation reference reads FORWARD from the tap; keep it strictly behind the
@@ -379,9 +412,9 @@ AudioSample PitchShifter::processImpl(AudioSample in, const SpliceEvent* linked,
             while (d < 0.0) d += len;
             while (d >= len) d -= len;
             if (d <= static_cast<double>(dLow_)) {
-                splice(+window_, d);
+                splice(+jump_, d);
             } else if (d >= static_cast<double>(dHigh_)) {
-                splice(-window_, d);
+                splice(-jump_, d);
             }
         }
     } else {
@@ -394,9 +427,9 @@ AudioSample PitchShifter::processImpl(AudioSample in, const SpliceEvent* linked,
         while (d < 0.0) d += len;
         while (d >= len) d -= len;
         if (d <= static_cast<double>(dLow_)) {
-            splice(+window_, d);
+            splice(+jump_, d);
         } else if (d >= static_cast<double>(dHigh_)) {
-            splice(-window_, d);
+            splice(-jump_, d);
         }
     }