fix(video): contain a timestamp leap that escapes the timeline rebase (#369)

[tschuegy]

Fixes #369. Companion to #368's rebase: defense in depth for a timestamp leap that escapes it (corrupt stream, a jump inside one chunk, future regressions). Today such a leap turns the session into a multi-minute zombie; with these three containments it either keeps playing sanely or fails cleanly within seconds onto the designed onVODSourceFailed surface.

The three containments

1. resolveVideoSampleDuration gets a cap. The look-behind delta across a 2^33 wrap IS the wrap (device: 8226410192 ticks ≈ 91404 s), which movenc rejects — and the write rc was dropped on the floor, so the packet vanished silently. The inferred delta now falls back (existing duration, then fallback) when it exceeds the discontinuity threshold: a sample longer than a discontinuity is definitionally invalid, and reusing discontinuityThresholdSeconds keeps one shared definition. The first rejected muxer write is now logged.

2. SegmentCache.noteFolded counts wide runs. The maxFoldRunLength guard dropped runs wider than 64 indices as "a restart or a seek" — but the field case was a discontinuity-scale cut leap (312 indices), and dropping it left every fold counter at 0, which is exactly what disarmed both VOD keyframe-aligned plan: the playlist advertises segment indices the producer never muxes, and the wedge recovery rebuilds the same hole #358 recovery arms for the folds most certain to trigger them. Wide runs now count (one Int per folded index, bounded by plan size); the constant survives as a log-classification threshold, and the fold site emits a distinct discontinuity-scale line. On a sequential origin the armed escalation reaches requestRestart → the sequential refusal → onVODSourceFailed within seconds (the client's shifted-window re-request is the designed recovery); on seekable VOD the reanchor genuinely works.

3. The advance park cannot wait on an unadvertisable index. The park releases on a consumer fetch of head − bufferAheadSegments, but a sequential append playlist advertises only what this pump's OWN finalize reports have fed it — a release target beyond that frontier is waiting for oneself (field: parked at target=364 while the playlist ended at seg61, freezing it for good). The park is skipped while the target lies beyond the frontier (sequentialParkWouldSelfDeadlock, pure); the disk budget stays the resource bound, normal parking resumes as the frontier catches up, and negative startup targets are exempt (they release instantly and are no deadlock).

Deliberately out of scope

OutputTimestampSanitizer keeps latching after a huge jump. movenc latches monotonicity on its own once a wrapped packet is accepted, so a sanitizer re-latch would only convert garbage timestamps into rejected writes until the next muxer rotation — no better — and it would weaken the SSAI seam protection the class exists for. With #368 the sanitizer never sees the leap; without it, containment 2 fails the session cleanly.

Tests

• VideoSampleDurationTests: the cap pinned with the exact wrap values; existing Native DV Profile 8.1 (HEVC) shows transient video glitches on the loopback-HLS path; not reproducible on replay #92 telescoping semantics unchanged under a production-scale cap; at-cap delta still telescopes.
• SegmentCacheFoldRunTests (new): the 312-index field run counts, repeats across a producer restart increment (the VOD keyframe-aligned plan: the playlist advertises segment indices the producer never muxes, and the wedge recovery rebuilds the same hole #358 signal), stored indices stay exempt, narrow runs unchanged.
• SequentialParkFrontierTests (new): the field deadlock (target=364 vs frontier=61), at/below-frontier parks normally, negative startup target exempt.
• Full suite green on macOS: 1835 Swift Testing + 504 XCTest, 0 failures.

Test plan

• macOS: swift test (full suite, counts above).
• Device: Apple TV 4K, tvOS 26.6, SRF Xtream timeshift (H.264 720p50 AC-3, field-coded, open-GOP) — the trace this containment is written against; verified through the Syravo client after the next release is pinned.

Applies cleanly with or without the #368 PR; the combination is integration-tested locally (full suite green on the merged tree).

[superuser404notfound]

Merged, thanks for the trace-anchored writeup, the three containments sit where the field log points and the pinned wrap values made the duration cap reviewable in one read. Full suite green on the merge result (1838 Swift Testing tests in 268 suites, 0 failures); the CHANGELOG conflict against the #368 follow-up was resolved by keeping both Unreleased entries.

Two follow-ups pushed on top (71b27b1, merged in 833e152), both in the same spirit as the PR:

The cap now also covers the duration the container DECLARES. resolveVideoSampleDuration capped the inferred delta only, and fell through to existingDuration > 0 ? existingDuration : fallback untouched. That branch is not a rare path here: it is exactly what runs when no forward delta exists, which is the EOF tail of the same wrapped stream, and movenc rejects a sample on the number, not on where the number came from. Pinned with the same 8226410192 ticks arriving as a declared duration.

The skipped park now hands its wedge detection to the disk park. This one is worth a note on the reasoning in section 3. The advance park is what catches a consumer that stopped advancing, and the #207 disk park documents in so many words that it needs no wedge breaker because "the extras eviction that follows the advancing playhead releases it". Skipping the advance park moves the pump straight into that assumption with the consumer possibly frozen: it races to the retention budget (2 GiB, so ~an hour of a 5 Mbps timeshift) and then holds in an unbreakable park for good. The skip is right, so the fix is to carry the detector across rather than to park: awaitPrefetchDiskBudgetRelease(detectWedge:) arms the same BackpressureWedgeDetector when the advance park was skipped, and its one-second poll matches the cadence the detector counts in. A trip ends the pump onto the existing re-anchor surface, which a sequential origin refuses into onVODSourceFailed, i.e. the failure the PR wants, in seconds instead of never.

One correction to the rationale, measured rather than argued, because it changes which path does the work:

• On a sequential origin the fold counters cannot reach the VOD keyframe-aligned plan: the playlist advertises segment indices the producer never muxes, and the wedge recovery rebuilds the same hole #358 arms. HLSLocalServer skips zero-duration entries on an EVENT playlist (if provider.playlistType == .event, dur <= 0 { continue }), so a folded index never gets a URI and AVPlayer never requests it, which is the trigger handleTargetChange's arm needs. The other arm (handleBackpressureWedge reading consumerTargetFold) runs only after a Presented frame drifts ~6 s ahead of currentTime/sourceTime after a rapid bidirectional seek burst (loopback-HLS native path) — frameAhead/producerShift/hostShift all report 0 #65 wedge break, and section 3 now skips that park on exactly this path. So the "escalation reaches requestRestart within seconds" is not what runs on a sequential origin today; the follow-up above is what puts a clean failure back there.
• Counting wide runs is still right, and the win lands on plain VOD, where the playlist is the static plan and every folded index IS advertised. That is the source shape VOD keyframe-aligned plan: the playlist advertises segment indices the producer never muxes, and the wedge recovery rebuilds the same hole #358 was written against (40 s GOP), and the 64-index guard silently disarmed the recovery for the widest folds there. Also worth recording: the guard's stated premise ("a jump this wide is a restart or a seek") could not happen anyway, because advanceMuxer only ever fires inside one pump; a restart builds a new muxer at its own base and records no fold run at all.

The issue stays open for the device retest; the release will bundle this with #368 and, if it lands, #370.