[qoli]

Summary

Closes #864.

A whole audio-tap segment can legitimately decode beyond the preferred lead. Treating that lead as a backward seek makes loopback and remote-HLS VOD readers repeatedly decode the same segments, breaking continuous PCM analysis. Track actual playhead movement and wait when a complete segment merely runs ahead.

Add installAudioTap(lossless: Bool = false) so continuous-analysis consumers can retain queued PCM without eviction while existing no-argument calls keep the newest-64 policy.

Relation to #863

This is the standalone downstream implementation described in #864, submitted against main as an alternative to #863. Both address long-segment re-decoding. #863 infers a backward seek from the previous segment's start and raises the default bounded queue to 256. This change observes the previous playhead directly, preserves the existing default queue, and provides opt-in non-dropping delivery.

What changed

• Loopback and remote-HLS VOD readers retain the previous playhead. Whole-segment overshoot sleeps; actual backward movement beyond the existing tolerance and forward seeks still re-anchor with a discontinuity.
• The lossless queue never evicts pending PCM or blocks the producer. Its consumer must keep draining or cancel/remove the tap when it stops consuming. Source gaps and the existing monotonic filter/session lifetime remain explicit.
• Preserve the default delivery policy and add regressions for long segments, forward/backward movement, teardown and delivery. The non-dropping burst test uses 512 buffers, exceeding both the default window and the 256-buffer alternative.
• Update the public API, architecture and changelog. No playback transport, source selection, PCM format or recognition thresholds change.

Test plan

Apple Silicon Mac14,14, macOS 27.0.1 (26A434), Xcode 27.1 (27A9275), Swift 6.4. Based on upstream 370b0e4dcc6fb49fca1b6999b075616d3442cb04. All five production files match the existing downstream 0009 implementation; the submission strengthens the burst regression and adds upstream documentation.

• swift build: passed.
• Focused audio-tap, public API and documented-constant checks: 57 XCTest cases passed.
• LIBDISPATCH_COOPERATIVE_POOL_STRICT=1 focused audio-tap checks: 30 XCTest cases passed.
• python3 Scripts/check-doc-links.py and diff whitespace checks: passed.
• Full default-traits run: 813 XCTest cases completed with zero failures and one skip; 5,009 Swift Testing tests in 694 suites completed with two issues:
  • Issue220SoftwareDecoderDrainTests.decodesFixtureFrames: counter.value >= packets - 16 failed.
  • HLSLocalServerSlowPeerTests.lanPeersLeaveLoopbackSlots: exceeded its existing 120-second time limit.

The two failing tests and their production implementations are outside this diff. Their cause is not established by this run, so this PR remains a draft rather than claiming a green full suite.

The focused regressions use synthetic segments/PCM and injected loopback/remote-HLS VOD dependencies. Dependency versions and commit SHAs match upstream's checked-in Package.resolved; official local Git mirrors avoided repeated downloads. The historical physical tvOS 26.6 observations are recorded in #864; this submission does not claim a new device playback run. Platform/all-traits coverage remains for upstream CI.

Checklist

• CHANGELOG.md updated
• Conventional Commit
• The fix lives in the engine
• Public API changes are intentional and documented