From f921a582ca533be8138fd706281e844c21925990 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sat, 19 Sep 2026 18:39:36 +0200
Subject: [PATCH 001/359] feat(aetherctl): measure the WebVTT a receiver would
 get, not the selection (Sodalite#156)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The harness asked `currentMediaSelection` and called a run green when it read
back the language the host picked. On the device that same transition produces a
caption box with no text in it: the selection is held and the payload behind it
is empty. AVKit fetches the whole forward window in one burst at selection and
never re-fetches a segment it already has, so the payload at that instant is the
only thing that decides what the viewer sees, and the harness was not looking at
it. Same mistake as the 6 MB fixture earlier today, one level up: the right
question was there, the measured quantity was not.

`VTT <label>: rendition=… segments=N nonEmpty=M cues=K` now fetches the way a
receiver does, master -> the selected rendition's media playlist -> the segments
covering the playhead, and counts cue text rather than segments. It names the
empty case in words, because `nonEmpty=0` is exactly the reported box.

Does NOT yet reproduce the report. Both transitions read
`segments=8 nonEmpty=8 cues=8` on the 30 min fixture, so the motive is still
missing the failure. The lead is in the reporter's log and not in mine: after
the off, his readers restart at `startAt=0.00s` (with `seek to 0.00s timed out
or failed; byte-estimate fallback applied`) while mine restart at the playhead,
and a store refilled from the head of a 1.9 GB file cannot serve the segments
around 1580 s that the burst is asking for. `startNativeSubtitleReaders` takes
`startAtSeconds: Double? = nil` and the lazy path passes nil; what nil resolves
to at that moment is the next thing to read.

Full suite, both runners: swift-testing 3104 in 423 suites, XCTest 17, 0 failures.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015PM3xUJB6ZQyqnmGK1fp6F
---
 Sources/aetherctl/PlaybackCmd.swift | 83 ++++++++++++++++++++++++++++-
 1 file changed, 81 insertions(+), 2 deletions(-)

diff --git a/Sources/aetherctl/PlaybackCmd.swift b/Sources/aetherctl/PlaybackCmd.swift
index 48ab09ec0..7209151fd 100644
--- a/Sources/aetherctl/PlaybackCmd.swift
+++ b/Sources/aetherctl/PlaybackCmd.swift
@@ -1180,7 +1180,10 @@ private func playSmokeTest(url: URL, seconds: Double, live: Bool, forceSoftware:
             print("  HOSTCALL setNativeSubtitleRendering(true)")
             engine.setNativeSubtitleRendering(true)
         }
-        if let t = nativeRenderTick, tick == t + 2 { await reportLegibleSelection(engine, "after render on") }
+        if let t = nativeRenderTick, tick == t + 2 {
+            await reportLegibleSelection(engine, "after render on")
+            await reportServedVTT(engine, "after render on", around: engine.currentTime)
+        }
         if let subsOffTick, tick == subsOffTick {
             print("  HOSTCALL subtitles off")
             engine.clearSubtitle()
@@ -1198,7 +1201,10 @@ private func playSmokeTest(url: URL, seconds: Double, live: Bool, forceSoftware:
         // seconds rather than a runloop turn. Reading at +1 caught the off correctly and reported
         // every on as a failure, which is the harness lying in the more expensive direction.
         if let t = subsOffTick, tick == t + 1 { await reportLegibleSelection(engine, "after off") }
-        if let t = subsOnTick, tick == t + 4 { await reportLegibleSelection(engine, "after on") }
+        if let t = subsOnTick, tick == t + 4 {
+            await reportLegibleSelection(engine, "after on")
+            await reportServedVTT(engine, "after on", around: engine.currentTime)
+        }
     }
 
     let finalTime = engine.currentTime
@@ -1382,3 +1388,76 @@ private func reportLegibleSelection(_ engine: AetherEngine, _ label: String) asy
     print("  LEGIBLE \(label): selected=\(name) options=\(group.options.count) "
           + "engineActive=\(engine.activeSubtitleTrackIndex.map(String.init) ?? "nil")")
 }
+
+/// Sodalite#156 round 2: what the RECEIVER would actually get, which is not the same question as
+/// whether a selection is held.
+///
+/// The first version of this harness asked `currentMediaSelection` and called a run green when it
+/// read back the language the host picked. On the device the same transition produced a caption box
+/// with no text in it, so the selection was held and the payload behind it was empty. AVKit fetches
+/// the whole forward window in one burst at selection and never re-fetches a segment it already has,
+/// which makes the payload at that instant the only thing that matters.
+///
+/// So this fetches the served WebVTT the way a receiver does: master -> the selected rendition's
+/// media playlist -> the segments covering the playhead, and counts CUE TEXT, not segments.
+@MainActor
+private func reportServedVTT(_ engine: AetherEngine, _ label: String, around playhead: Double) async {
+    guard let item = engine.currentAVPlayerItem,
+          let asset = item.asset as? AVURLAsset else {
+        print("  VTT \(label): no item")
+        return
+    }
+    let master = asset.url
+    func get(_ url: URL) async -> String? {
+        guard let (data, _) = try? await URLSession.shared.data(from: url) else { return nil }
+        return String(data: data, encoding: .utf8)
+    }
+    guard let masterBody = await get(master) else {
+        print("  VTT \(label): master unreachable at \(master.absoluteString)")
+        return
+    }
+    // The rendition AVPlayer is on, named by the legible selection so the harness follows the same
+    // pick the receiver does rather than guessing an ordinal.
+    var wantedName: String?
+    if let group = try? await item.asset.loadMediaSelectionGroup(for: .legible) {
+        wantedName = item.currentMediaSelection.selectedMediaOption(in: group)?.displayName
+    }
+    let renditions: [(name: String, uri: String)] = masterBody
+        .split(separator: "\n")
+        .filter { $0.hasPrefix("#EXT-X-MEDIA:TYPE=SUBTITLES") }
+        .compactMap { line in
+            func field(_ key: String) -> String? {
+                guard let r = line.range(of: "\(key)=\"") else { return nil }
+                let rest = line[r.upperBound...]
+                guard let end = rest.firstIndex(of: "\"") else { return nil }
+                return String(rest[..<end])
+            }
+            guard let name = field("NAME"), let uri = field("URI") else { return nil }
+            return (name, uri)
+        }
+    guard let pick = renditions.first(where: { $0.name == wantedName }) ?? renditions.first else {
+        print("  VTT \(label): no SUBTITLES rendition in the master")
+        return
+    }
+    guard let media = await get(master.deletingLastPathComponent().appendingPathComponent(pick.uri)) else {
+        print("  VTT \(label): \(pick.uri) unreachable")
+        return
+    }
+    let segments = media.split(separator: "\n").filter { $0.hasSuffix(".vtt") }.map(String.init)
+    // Segment index from the playhead: the playlist is uniform 4 s here, and the burst AVKit takes
+    // starts at the playhead, so this is the stretch whose emptiness the viewer would see.
+    let first = max(0, Int(playhead / 4.0) - Int(media.contains("EXT-X-MEDIA-SEQUENCE") ? 0 : 0))
+    var checked = 0, nonEmpty = 0, cues = 0
+    for name in segments where checked < 8 {
+        guard let n = Int(name.split(separator: "_").last?.split(separator: ".").first ?? ""),
+              n >= first, n < first + 12 else { continue }
+        checked += 1
+        guard let body = await get(master.deletingLastPathComponent().appendingPathComponent(name)) else { continue }
+        // A cue is a timestamp line plus text under it; counting "-->" counts cues without parsing.
+        let c = body.components(separatedBy: "-->").count - 1
+        cues += c
+        if c > 0 { nonEmpty += 1 }
+    }
+    print("  VTT \(label): rendition=\(pick.name) segments=\(checked) nonEmpty=\(nonEmpty) cues=\(cues)"
+          + (checked > 0 && nonEmpty == 0 ? "   <- a caption box with nothing in it" : ""))
+}

From cdaa235ec578df8912b3e41cda21a9c08ed41a1d Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sat, 19 Sep 2026 18:57:17 +0200
Subject: [PATCH 002/359] diag(subtitles): print the reader anchor next to the
 playhead it should mean (Sodalite#156)

`startNativeSubtitleReaders` anchors on `startAtSeconds ?? sourceTime`, and the
lazy restart passes nil. On the native path `sourceTime` is written only by the
render sink and by seek landings, never by the clock tick (#49), and while an
external screen holds the picture nothing renders locally. The reporter's log
shows the consequence and the harness cannot: after a subtitles-off his readers
restart at `startAt=0.00s`, mine at the playhead, and a store refilled from the
head of a 1.9 GB file serves empty .vtt for the window the receiver is asking
for. That is a caption box with nothing in it, from the first segment, only
after an off, and never when AirPlay starts with subtitles already on, which is
exactly the shape reported.

The two numbers disagreeing is that defect. Them agreeing means the reader has
simply not caught up yet, which is a different problem with a different fix, and
without the line they look identical.

Diagnostics only. Full suite, both runners: swift-testing 3104 in 423 suites,
XCTest 17, 0 failures.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015PM3xUJB6ZQyqnmGK1fp6F
---
 Sources/AetherEngine/AetherEngine+Subtitles.swift | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/Sources/AetherEngine/AetherEngine+Subtitles.swift b/Sources/AetherEngine/AetherEngine+Subtitles.swift
index e8d669be5..2059d4c54 100644
--- a/Sources/AetherEngine/AetherEngine+Subtitles.swift
+++ b/Sources/AetherEngine/AetherEngine+Subtitles.swift
@@ -1661,6 +1661,18 @@ extension AetherEngine {
         let w = sourceVideoWidth > 0 ? sourceVideoWidth : 1920
         let h = sourceVideoHeight > 0 ? sourceVideoHeight : 1080
         let startAt = startAtSeconds ?? sourceTime
+        // Sodalite#156: the anchor next to the playhead it is supposed to mean. `sourceTime` is
+        // written on the native path only by the render sink and by seek landings, never by the clock
+        // tick (#49), and while an external screen holds the picture nothing renders locally. A
+        // reader anchored on a stale or zero source time refills from the head of the file and then
+        // serves empty .vtt for the window the receiver is actually asking for, which is a caption
+        // box with nothing in it. These two numbers disagreeing is that defect; them agreeing means
+        // the reader simply has not caught up yet, which is a different problem with a different fix.
+        EngineLog.emit("[AetherEngine] #156 reader anchor: startAt=\(String(format: "%.2f", startAt))s "
+                       + "sourceTime=\(String(format: "%.2f", sourceTime))s "
+                       + "clock=\(String(format: "%.2f", currentTime))s "
+                       + "explicit=\(startAtSeconds.map { String(format: "%.2f", $0) } ?? "nil")",
+                       category: .engine)
         let reader = customClone
         // #76: same bounded-probe + active-title open as the inline reader.
         let probesize = loadedOptions.probesize

From d5757f8a1fb514daa1e340569990577188a8f013 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sun, 20 Sep 2026 05:16:49 +0200
Subject: [PATCH 003/359] fix(aetherctl): pick the segments at the playhead,
 and surface an empty served .vtt (Sodalite#156)

Two harness corrections and one diagnostic, all from the same lesson: a harness
that checks the wrong thing fails exactly the way it would succeed.

1. The segment picker divided the playhead by a nominal 4 s. On a source with
   irregular keyframes (scene cuts, i.e. most real content) segments are not
   uniform, so it matched nothing and the run printed `segments=0`, which reads
   as a clean pass. The reporter's log shows that shape directly: `planSource`
   and `sourceStart` 1.96 s apart on every segment.

2. Walking EXTINF instead, the first attempt read the playhead against the
   session's mount position. The media playlist is the WHOLE VOD from segment 0,
   not a window, so that picked `subs_0_2.vtt`, eight seconds into the film, and
   reported it empty. True, and worthless. Caught because the uniform control
   flipped from `nonEmpty=8` to `nonEmpty=0` at the same time: a control that
   changes with the harness rather than with the defect is the tell.

   Both fixtures now read `nonEmpty=8` with the picked names printed next to the
   playhead, so the irregular-keyframe hypothesis is disproven too, and it cost
   ten minutes here instead of a device round.

3. `HLSLocalServer` already logged every served .vtt, at `.verbose`, which
   `EngineLog` routes to OSLog only and never to `LogTap`. That is why no capture
   ever showed it. An EMPTY segment is now a visible line and a populated one
   stays verbose: AVKit takes ~45 segments in one burst and never re-fetches, so
   logging all of them visibly would push the surrounding evidence out of the
   300-line ring, and the surrounding evidence is what says WHY one came out
   empty.

Full suite, both runners: swift-testing 3104 in 423 suites, XCTest 17, 0 failures.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015PM3xUJB6ZQyqnmGK1fp6F
---
 .../AetherEngine/Network/HLSLocalServer.swift | 15 ++++++-
 Sources/aetherctl/PlaybackCmd.swift           | 39 ++++++++++++++-----
 2 files changed, 43 insertions(+), 11 deletions(-)

diff --git a/Sources/AetherEngine/Network/HLSLocalServer.swift b/Sources/AetherEngine/Network/HLSLocalServer.swift
index 474b163a0..957980141 100644
--- a/Sources/AetherEngine/Network/HLSLocalServer.swift
+++ b/Sources/AetherEngine/Network/HLSLocalServer.swift
@@ -912,7 +912,20 @@ final class HLSLocalServer: @unchecked Sendable {
                   let vtt = provider?.nativeSubtitleVTT(ordinal: parsed.ordinal, segmentIndex: seg) else {
                 return send404(fd: fd, path: normalizedPath, reason: "no subtitle segment for \(normalizedPath)")
             }
-            EngineLog.emit("[HLSLocalServer] served subtitle .vtt ord=\(parsed.ordinal) seg=\(seg) bytes=\(vtt.utf8.count)", category: .hlsServer, level: .verbose)
+            // Sodalite#156: an EMPTY segment is the reported defect and a populated one is routine, so
+            // only the empty case is worth a line a reporter will see. AVKit takes the whole forward
+            // window in one burst (~45 segments) and never re-fetches, so logging every one of them at
+            // a visible level would push the surrounding evidence out of the 300-line ring, and it is
+            // exactly the surrounding evidence that says WHY a segment came out empty.
+            let cues = vtt.components(separatedBy: "-->").count - 1
+            if cues == 0 {
+                EngineLog.emit("[HLSLocalServer] served an EMPTY subtitle .vtt ord=\(parsed.ordinal) "
+                               + "seg=\(seg) bytes=\(vtt.utf8.count); the receiver caches this segment "
+                               + "as it is and never asks again", category: .hlsServer)
+            } else {
+                EngineLog.emit("[HLSLocalServer] served subtitle .vtt ord=\(parsed.ordinal) seg=\(seg) "
+                               + "bytes=\(vtt.utf8.count) cues=\(cues)", category: .hlsServer, level: .verbose)
+            }
             return send200(fd: fd, path: normalizedPath,
                            data: Data(vtt.utf8),
                            contentType: "text/vtt")
diff --git a/Sources/aetherctl/PlaybackCmd.swift b/Sources/aetherctl/PlaybackCmd.swift
index 7209151fd..22d057ce8 100644
--- a/Sources/aetherctl/PlaybackCmd.swift
+++ b/Sources/aetherctl/PlaybackCmd.swift
@@ -1182,7 +1182,7 @@ private func playSmokeTest(url: URL, seconds: Double, live: Bool, forceSoftware:
         }
         if let t = nativeRenderTick, tick == t + 2 {
             await reportLegibleSelection(engine, "after render on")
-            await reportServedVTT(engine, "after render on", around: engine.currentTime)
+            await reportServedVTT(engine, "after render on", around: engine.currentTime, sessionStart: startPosition ?? 0)
         }
         if let subsOffTick, tick == subsOffTick {
             print("  HOSTCALL subtitles off")
@@ -1203,7 +1203,7 @@ private func playSmokeTest(url: URL, seconds: Double, live: Bool, forceSoftware:
         if let t = subsOffTick, tick == t + 1 { await reportLegibleSelection(engine, "after off") }
         if let t = subsOnTick, tick == t + 4 {
             await reportLegibleSelection(engine, "after on")
-            await reportServedVTT(engine, "after on", around: engine.currentTime)
+            await reportServedVTT(engine, "after on", around: engine.currentTime, sessionStart: startPosition ?? 0)
         }
     }
 
@@ -1401,7 +1401,8 @@ private func reportLegibleSelection(_ engine: AetherEngine, _ label: String) asy
 /// So this fetches the served WebVTT the way a receiver does: master -> the selected rendition's
 /// media playlist -> the segments covering the playhead, and counts CUE TEXT, not segments.
 @MainActor
-private func reportServedVTT(_ engine: AetherEngine, _ label: String, around playhead: Double) async {
+private func reportServedVTT(_ engine: AetherEngine, _ label: String, around playhead: Double,
+                             sessionStart: Double) async {
     guard let item = engine.currentAVPlayerItem,
           let asset = item.asset as? AVURLAsset else {
         print("  VTT \(label): no item")
@@ -1443,14 +1444,30 @@ private func reportServedVTT(_ engine: AetherEngine, _ label: String, around pla
         print("  VTT \(label): \(pick.uri) unreachable")
         return
     }
-    let segments = media.split(separator: "\n").filter { $0.hasSuffix(".vtt") }.map(String.init)
-    // Segment index from the playhead: the playlist is uniform 4 s here, and the burst AVKit takes
-    // starts at the playhead, so this is the stretch whose emptiness the viewer would see.
-    let first = max(0, Int(playhead / 4.0) - Int(media.contains("EXT-X-MEDIA-SEQUENCE") ? 0 : 0))
+    // Walk EXTINF rather than assuming a uniform grid. A source with irregular keyframes (scene cuts,
+    // which is most real content) has segments of unequal length, and the reporter's log shows exactly
+    // that: `planSource` and `sourceStart` 1.96 s apart on every segment. Dividing the playhead by a
+    // nominal 4 s picked nothing there, and a harness that checks zero segments reports a clean run.
+    var offsets: [(name: String, start: Double)] = []
+    var acc = 0.0
+    var pending: Double?
+    for line in media.split(separator: "\n", omittingEmptySubsequences: false) {
+        if line.hasPrefix("#EXTINF:") {
+            pending = Double(line.dropFirst(8).split(separator: ",").first ?? "") ?? 0
+        } else if line.hasSuffix(".vtt") {
+            offsets.append((String(line), acc))
+            acc += pending ?? 0
+            pending = nil
+        }
+    }
+    // The playlist is the WHOLE VOD from segment 0, not a window around the mount, so the accumulated
+    // EXTINF is absolute item time and the playhead is read directly. Subtracting the session start
+    // here picked `subs_0_2.vtt`, eight seconds into the film, and reported it empty, which is true
+    // and says nothing: a harness that checks the wrong segments fails the same way it would succeed.
+    let relative = max(0, playhead)
+    let startIndex = offsets.lastIndex(where: { $0.start <= relative }) ?? 0
     var checked = 0, nonEmpty = 0, cues = 0
-    for name in segments where checked < 8 {
-        guard let n = Int(name.split(separator: "_").last?.split(separator: ".").first ?? ""),
-              n >= first, n < first + 12 else { continue }
+    for (name, _) in offsets[startIndex...] where checked < 8 {
         checked += 1
         guard let body = await get(master.deletingLastPathComponent().appendingPathComponent(name)) else { continue }
         // A cue is a timestamp line plus text under it; counting "-->" counts cues without parsing.
@@ -1459,5 +1476,7 @@ private func reportServedVTT(_ engine: AetherEngine, _ label: String, around pla
         if c > 0 { nonEmpty += 1 }
     }
     print("  VTT \(label): rendition=\(pick.name) segments=\(checked) nonEmpty=\(nonEmpty) cues=\(cues)"
+          + " picked=\(offsets[startIndex...].prefix(2).map(\.name).joined(separator: ",")) "
+          + "of=\(offsets.count) relative=\(String(format: "%.1f", relative)) playhead=\(String(format: "%.1f", playhead))"
           + (checked > 0 && nonEmpty == 0 ? "   <- a caption box with nothing in it" : ""))
 }

From 69063eb314ad298c5bce0f928a3f3e2f40db898b Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sun, 20 Sep 2026 05:33:40 +0200
Subject: [PATCH 004/359] feat(aetherctl): compare a served .vtt against the
 window its playlist declares (Sodalite#156)

A populated segment whose cues sit outside the window the playlist declares for
it is as invisible as an empty one, and it read identically in every count the
harness had. That mattered once the device capture closed the empty case: 22
segments fetched, not one served empty, still a blank caption box.

Reports `MISPLACED=N` with the first offender spelled out. On the reporter's
shape (irregular keyframes, segments as much as 7.5 s against a nominal 4) it
finds four, all of them a cue about 2 s before its segment's declared start,
which is a boundary-spanning cue and not the defect. Uniform segments find none.
So this rules the mapping out rather than confirming it, which is the point.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015PM3xUJB6ZQyqnmGK1fp6F
---
 Sources/aetherctl/PlaybackCmd.swift | 37 +++++++++++++++++++++++++++--
 1 file changed, 35 insertions(+), 2 deletions(-)

diff --git a/Sources/aetherctl/PlaybackCmd.swift b/Sources/aetherctl/PlaybackCmd.swift
index 22d057ce8..3815b64b9 100644
--- a/Sources/aetherctl/PlaybackCmd.swift
+++ b/Sources/aetherctl/PlaybackCmd.swift
@@ -1400,6 +1400,19 @@ private func reportLegibleSelection(_ engine: AetherEngine, _ label: String) asy
 ///
 /// So this fetches the served WebVTT the way a receiver does: master -> the selected rendition's
 /// media playlist -> the segments covering the playhead, and counts CUE TEXT, not segments.
+private enum Self_VTT {}
+extension AetherEngine {
+    /// `HH:MM:SS.mmm` or `MM:SS.mmm` as seconds.
+    static func vttSeconds(_ s: String) -> Double? {
+        let parts = s.split(separator: ":").map(String.init)
+        guard !parts.isEmpty, let last = Double(parts.last!) else { return nil }
+        var total = last
+        if parts.count >= 2 { total += (Double(parts[parts.count - 2]) ?? 0) * 60 }
+        if parts.count >= 3 { total += (Double(parts[parts.count - 3]) ?? 0) * 3600 }
+        return total
+    }
+}
+
 @MainActor
 private func reportServedVTT(_ engine: AetherEngine, _ label: String, around playhead: Double,
                              sessionStart: Double) async {
@@ -1466,16 +1479,36 @@ private func reportServedVTT(_ engine: AetherEngine, _ label: String, around pla
     // and says nothing: a harness that checks the wrong segments fails the same way it would succeed.
     let relative = max(0, playhead)
     let startIndex = offsets.lastIndex(where: { $0.start <= relative }) ?? 0
-    var checked = 0, nonEmpty = 0, cues = 0
-    for (name, _) in offsets[startIndex...] where checked < 8 {
+    var checked = 0, nonEmpty = 0, cues = 0, misplaced = 0
+    var firstMismatch: String?
+    for (name, start) in offsets[startIndex...] where checked < 8 {
         checked += 1
         guard let body = await get(master.deletingLastPathComponent().appendingPathComponent(name)) else { continue }
         // A cue is a timestamp line plus text under it; counting "-->" counts cues without parsing.
         let c = body.components(separatedBy: "-->").count - 1
         cues += c
         if c > 0 { nonEmpty += 1 }
+        // Sodalite#156: a POPULATED segment whose cues sit outside the window the playlist declares for
+        // it is as invisible as an empty one, and it reads identically in every count above. The device
+        // capture ruled the empty case out (nothing served empty, 22 segments fetched, still a blank
+        // box), and irregular keyframes make segments as much as 7.5 s long against a nominal 4, so the
+        // declared window and the cue times are exactly the pair worth comparing.
+        let end = offsets.first(where: { $0.start > start })?.start ?? (start + 4)
+        for line in body.split(separator: "\n") where line.contains("-->") {
+            let parts = line.split(separator: " ")
+            guard let t = parts.first.map(String.init), let cueStart = AetherEngine.vttSeconds(t) else { continue }
+            if cueStart < start - 1 || cueStart > end + 1 {
+                misplaced += 1
+                if firstMismatch == nil {
+                    firstMismatch = String(format: "%@ declares [%.1f,%.1f) but carries a cue at %.1f",
+                                           name, start, end, cueStart)
+                }
+            }
+            break
+        }
     }
     print("  VTT \(label): rendition=\(pick.name) segments=\(checked) nonEmpty=\(nonEmpty) cues=\(cues)"
+          + (misplaced > 0 ? " MISPLACED=\(misplaced) \(firstMismatch ?? "")" : "")
           + " picked=\(offsets[startIndex...].prefix(2).map(\.name).joined(separator: ",")) "
           + "of=\(offsets.count) relative=\(String(format: "%.1f", relative)) playhead=\(String(format: "%.1f", playhead))"
           + (checked > 0 && nonEmpty == 0 ? "   <- a caption box with nothing in it" : ""))

From 616c4e7d6f920dcc2153fc48f1b70bab3261d7b0 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Tue, 22 Sep 2026 19:11:44 +0200
Subject: [PATCH 005/359] chore(deps): bump FFmpegBuild to 3.5.0 (FFmpeg
 n8.1.3)

268 upstream commits over n8.1.2, six of them on code this engine ships.
The one that matters most here is VP9: `vp9_decode_flush()` left
`next_refs[]` referenced, and a worker seeds its references from another
worker's `next_refs[]`, so the pre-flush set survived and the first inter
frame after a seek could decode against released buffers. This engine
opens VP9 with frame and slice threading and flushes on every
reposition, which is exactly that shape.

Also: the Dolby Vision RPU parser trims trailing zero padding again
(n8.1.2 stopped, so a padded RPU could lose its dynamic metadata) and
bounds its partition counts, a VC-1 picture keeps a last macroblock that
costs one bit, the `dca_core` bsf clears the profile it strips, and a
container channel layout survives a failed decoder open.

swift test: 3347 swift-testing tests in 452 suites and 629 XCTest tests
pass, real exit code 0.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 Package.resolved | 6 +++---
 Package.swift    | 2 +-
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/Package.resolved b/Package.resolved
index 5f59aa543..a1d7314dc 100644
--- a/Package.resolved
+++ b/Package.resolved
@@ -1,13 +1,13 @@
 {
-  "originHash" : "43b1111cdbc7f385ee9cadbc2fd271c5628d74bdd29d478d1a8594670811fddc",
+  "originHash" : "e94fafbbd57b5e0ee24b958be3a6afe9445a45324b3568a74666e25dd9342513",
   "pins" : [
     {
       "identity" : "ffmpegbuild",
       "kind" : "remoteSourceControl",
       "location" : "https://github.com/superuser404notfound/FFmpegBuild",
       "state" : {
-        "revision" : "9ee46ba4fb533e35efa6492eb1a903ca4f8058fc",
-        "version" : "3.4.0"
+        "revision" : "dcc8041eeeb08aedceb1b053f2a03a27fd12020a",
+        "version" : "3.5.0"
       }
     },
     {
diff --git a/Package.swift b/Package.swift
index 2b34109a1..4e2e0f2a1 100644
--- a/Package.swift
+++ b/Package.swift
@@ -38,7 +38,7 @@ let package = Package(
         // rebuilds still reach existing tags, which is where a pure rebuild
         // belongs; anything that adds slices or enables a component is a minor
         // and reaches consumers through an engine release.
-        .package(url: "https://github.com/superuser404notfound/FFmpegBuild", .upToNextMinor(from: "3.4.0")),  // 3.4.0: FFmpeg learns the `dav1` sample entry in both directions, the AV1 variant of `av01` that signals Dolby Vision, so a Profile 10.0 source can be read at all and can be remuxed with the tag its packaging requires; stock FFmpeg has it in neither of its two mp4 tag tables, so the read probes as "unknown codec" and the write fails EINVAL (#547); same n8.1.2 binaries as 3.3.0 otherwise, compiled against the Xcode 27 SDKs with unchanged deployment targets; 3.3.0: every slice a shipped app can embed carries its dSYM inside the xcframework, so Xcode copies it into `.xcarchive/dSYMs` and a crash inside FFmpeg symbolicates instead of staying a list of addresses (FFmpegBuild#4); same n8.1.2 binaries as 3.2.1 apart from their UUID, the libraries just compile with `-gline-tables-only` now and the debug map is harvested before the shipped binary is stripped; 3.2.1: vc1_parser seeds its parse context from extradata, so a seek landing on an entry point alone keeps its picture size instead of falling back to 0x0 or to a size read out of the following payload (#490, FFmpeg PR 24458); 3.2.0: the legacy Flash tail, video and audio together (flv1 / vp6 / vp6f / vp6a, nellymoser, adpcm_swf, speex, and FLV's pcm_s16be / pcm_u8 / pcm_alaw / pcm_mulaw), so a pre-2008 .flv plays with sound where before only H.264-in-FLV did; flashsv stays out, it needs zlib and would have been dropped silently; 3.1.0: native .wmv / .asf, the asf demuxer plus every WMA decoder (Standard, Pro, Lossless, Voice), which is the container half of the legacy Microsoft support 2.4.3 started (FFmpegBuild#3); 3.0.0: every target, product, framework bundle and install name carries an `Aether` prefix, so this build can sit in an app that already has an FFmpeg (FFmpegKit, MobileVLCKit, mpv); same n8.1.2 binaries as 2.5.0, only names changed; 2.5.0: libzvbi 0.2.45 for GHSA-86rm-g7qf-j2fh (OOB read/write + integer underflow, reachable through the libzvbi_teletext decoder), dav1d 1.5.4, zimg 3.0.6, and the concat demuxer removed (a script demuxer selectable by probing alone, which made any stream a potential file-open primitive); 2.4.3: the legacy Microsoft video decoders (msmpeg4v1/v2/v3, wmv1/wmv2/wmv3; FFmpegBuild#3); 2.4.2: pgssubdec missing-palette recovery, replaces the 2.1.1 Epoch-Continue retain (#142); 2.4.1: qtrle decoder; 2.4.0: visionOS (xros) device + simulator slices; 2.3.0: webvtt demuxer (standalone .vtt sidecars, plus the cue settings as packet side data); 2.2.0: matroska TTS warn-only per RFC 9559 (#145 rework); 2.1.3: sup demuxer (raw PGS sidecars); 2.1.2: matroska TrackTimestampScale clamp (#145, dropped in 2.2.0); 2.1.1: pgssubdec Epoch-Continue retain (#142); 2.1.0: yadif_videotoolbox + hwupload (Metal GPU deinterlace); 2.0.0: dynamic frameworks (LGPL), zvbi GPL excision
+        .package(url: "https://github.com/superuser404notfound/FFmpegBuild", .upToNextMinor(from: "3.5.0")),  // 3.5.0: FFmpeg n8.1.3, 268 upstream commits over n8.1.2, of which six touch code this engine ships: VP9 kept `next_refs[]` referenced across `avcodec_flush_buffers()`, so a worker could reseed its references from the pre-flush set and the first inter frame after a seek decoded against released buffers (heap OOB read and write, and this engine decodes VP9 with frame threading and flushes on every reposition); the Dolby Vision RPU parser trims trailing zero padding again, which n8.1.2 had stopped doing, so a padded RPU no longer fails the ext-block size check and loses its dynamic metadata, and the RPU partition counts are bounded; a VC-1 picture ending on a one-bit skipped macroblock keeps that macroblock instead of falling into error concealment; the `dca_core` bsf clears the profile it has just stripped; and a container channel layout survives a failed decoder open during probing. Same dav1d 1.5.4, zimg 3.0.6 and libzvbi 0.2.45 (all current upstream), same component set, same six local patches, unchanged soname majors; 3.4.0: FFmpeg learns the `dav1` sample entry in both directions, the AV1 variant of `av01` that signals Dolby Vision, so a Profile 10.0 source can be read at all and can be remuxed with the tag its packaging requires; stock FFmpeg has it in neither of its two mp4 tag tables, so the read probes as "unknown codec" and the write fails EINVAL (#547); same n8.1.2 binaries as 3.3.0 otherwise, compiled against the Xcode 27 SDKs with unchanged deployment targets; 3.3.0: every slice a shipped app can embed carries its dSYM inside the xcframework, so Xcode copies it into `.xcarchive/dSYMs` and a crash inside FFmpeg symbolicates instead of staying a list of addresses (FFmpegBuild#4); same n8.1.2 binaries as 3.2.1 apart from their UUID, the libraries just compile with `-gline-tables-only` now and the debug map is harvested before the shipped binary is stripped; 3.2.1: vc1_parser seeds its parse context from extradata, so a seek landing on an entry point alone keeps its picture size instead of falling back to 0x0 or to a size read out of the following payload (#490, FFmpeg PR 24458); 3.2.0: the legacy Flash tail, video and audio together (flv1 / vp6 / vp6f / vp6a, nellymoser, adpcm_swf, speex, and FLV's pcm_s16be / pcm_u8 / pcm_alaw / pcm_mulaw), so a pre-2008 .flv plays with sound where before only H.264-in-FLV did; flashsv stays out, it needs zlib and would have been dropped silently; 3.1.0: native .wmv / .asf, the asf demuxer plus every WMA decoder (Standard, Pro, Lossless, Voice), which is the container half of the legacy Microsoft support 2.4.3 started (FFmpegBuild#3); 3.0.0: every target, product, framework bundle and install name carries an `Aether` prefix, so this build can sit in an app that already has an FFmpeg (FFmpegKit, MobileVLCKit, mpv); same n8.1.2 binaries as 2.5.0, only names changed; 2.5.0: libzvbi 0.2.45 for GHSA-86rm-g7qf-j2fh (OOB read/write + integer underflow, reachable through the libzvbi_teletext decoder), dav1d 1.5.4, zimg 3.0.6, and the concat demuxer removed (a script demuxer selectable by probing alone, which made any stream a potential file-open primitive); 2.4.3: the legacy Microsoft video decoders (msmpeg4v1/v2/v3, wmv1/wmv2/wmv3; FFmpegBuild#3); 2.4.2: pgssubdec missing-palette recovery, replaces the 2.1.1 Epoch-Continue retain (#142); 2.4.1: qtrle decoder; 2.4.0: visionOS (xros) device + simulator slices; 2.3.0: webvtt demuxer (standalone .vtt sidecars, plus the cue settings as packet side data); 2.2.0: matroska TTS warn-only per RFC 9559 (#145 rework); 2.1.3: sup demuxer (raw PGS sidecars); 2.1.2: matroska TrackTimestampScale clamp (#145, dropped in 2.2.0); 2.1.1: pgssubdec Epoch-Continue retain (#142); 2.1.0: yadif_videotoolbox + hwupload (Metal GPU deinterlace); 2.0.0: dynamic frameworks (LGPL), zvbi GPL excision
         // Pure-Swift SMB2 client (MIT) that speaks the protocol over
         // NWConnection. Replaces AMSMB2/libsmb2, which EPERMs on tvOS/iOS.
         // Pinned to the 0.3.x minor: SMBClient is pre-1.0 with an actively

From 1fcbe1eaf113161bc85194197f5fd098158cd5ae Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Tue, 22 Sep 2026 19:11:44 +0200
Subject: [PATCH 006/359] chore(release): prep 7.14.0 - the install snippets
 pin the published tag

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 CHANGELOG.md                                  | 39 +++++++++++++++++++
 Examples/README.md                            |  2 +-
 README.md                                     |  6 +--
 .../AetherEngine/AetherEngine+Version.swift   |  2 +-
 4 files changed, 44 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 821f37178..effa67da2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,45 @@ the public-API contract.
 
 _Nothing yet._
 
+## [7.14.0] - 2026-09-22
+
+### Fixed
+
+- **A seek could leave the software VP9 decoder pointing at frames it had already released
+  (FFmpegBuild 3.5.0, FFmpeg n8.1.3).** `SoftwareVideoDecoder` opens VP9 with frame and slice
+  threading and flushes the codec context on every reposition, which is exactly the shape upstream's
+  `vp9_decode_flush()` mishandled: it released `frames[]`, `refs[]` and `ref_frames[]` but left
+  `next_refs[]` referenced, and a worker seeds its own references from another worker's `next_refs[]`,
+  so the pre-flush set survived and the first inter frame after a seek could decode against buffers
+  that were gone. A heap out-of-bounds read and write, found by Mozilla's bugmon automation.
+
+- **A Dolby Vision RPU with trailing zero padding keeps its dynamic metadata.** The RPU parser
+  stopped trimming zero padding in `ef167512ab`, which shipped in n8.1.2, so a heavily padded RPU
+  could fail the extension block size check and the file played without its dynamic metadata. Both
+  the HEVC and the AV1 decoder pull in the RPU parser, so this was on the path of every Dolby Vision
+  source, and a second fix bounds the RPU partition counts that were read without one.
+
+- **A VC-1 picture no longer loses its last macroblock.** The per-macroblock guards upstream added
+  in n8.1.2 bail out to error concealment when one bit is left, but a skipped P or B macroblock can
+  legitimately cost exactly one bit, and a Simple or Main profile picture is byte-aligned with no
+  stop bit, so a picture ending on such a macroblock lost it.
+
+- **The DTS core bitstream filter no longer passes on a profile it has just stripped.** It removes
+  the extension substreams, so a declared DTS-HD MA profile no longer described the bitstream that
+  came out of it.
+
+- **A channel layout read from the container survives a decoder that fails to open.** Probing copies
+  codec parameters back from the decoder context even after a failed `avcodec_open2()`, and the
+  failure zeroes the layout, so what the demuxer had read from the container was overwritten with
+  nothing.
+
+### Changed
+
+- **FFmpegBuild 3.5.0, built on FFmpeg n8.1.3.** 268 upstream commits over n8.1.2, of which the five
+  above touch code this engine ships. dav1d 1.5.4, zimg 3.0.6 and libzvbi 0.2.45 are unchanged (they
+  are the newest upstream releases), the component set and the six local FFmpeg patches are
+  unchanged, and the soname majors are the same, so nothing in the public API moves.
+
 ## [7.13.0] - 2026-09-22
 
 ### Performance
diff --git a/Examples/README.md b/Examples/README.md
index d8bfc6dad..aa8654e18 100644
--- a/Examples/README.md
+++ b/Examples/README.md
@@ -18,7 +18,7 @@ Three samples covering different audiences:
    ```
    https://github.com/superuser404notfound/AetherEngine
    ```
-   Dependency Rule: Up to Next Major Version, starting from `7.13.0`. Add the `AetherEngine` library product to your app target.
+   Dependency Rule: Up to Next Major Version, starting from `7.14.0`. Add the `AetherEngine` library product to your app target.
 
 3. **Drop the file in.** Replace the Xcode template's default `App.swift` (or whatever the generated `@main` file is called) with the contents of [`MinimalPlayerApp.swift`](MinimalPlayer/MinimalPlayerApp.swift). The file is self-contained: it defines both the `@main App` struct and the `ContentView`.
 
diff --git a/README.md b/README.md
index f927ec788..707c9ec8a 100644
--- a/README.md
+++ b/README.md
@@ -342,7 +342,7 @@ Subtitle cues land in raw source PTS; render the overlay against `player.sourceT
 Install via Swift Package Manager:
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.13.0")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.14.0")
 ```
 
 Three samples ship in `Examples/`:
@@ -589,10 +589,10 @@ Browse all of this as a searchable site at **[aetherengine.superuser404.de](http
 AetherEngine uses [Semantic Versioning](https://semver.org). The public API surface, every `public` declaration in `Sources/AetherEngine/`, is the stability contract. **Major** removes / renames public symbols or breaks adopters; **Minor** adds public API or codec / format support; **Patch** fixes bugs with no public API change. `internal` types are not part of the contract.
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.13.0")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.14.0")
 ```
 
-Pin to `.upToNextMinor(from: "7.13.0")` for stricter teams that prefer to opt into minor bumps explicitly.
+Pin to `.upToNextMinor(from: "7.14.0")` for stricter teams that prefer to opt into minor bumps explicitly.
 
 ## Requirements
 
diff --git a/Sources/AetherEngine/AetherEngine+Version.swift b/Sources/AetherEngine/AetherEngine+Version.swift
index 843682801..513bfb9eb 100644
--- a/Sources/AetherEngine/AetherEngine+Version.swift
+++ b/Sources/AetherEngine/AetherEngine+Version.swift
@@ -11,5 +11,5 @@ extension AetherEngine {
     ///
     /// Between releases, and in a consumer that pins an unreleased commit for a device test, this
     /// names the last PUBLISHED version the checkout descends from, not every patch in it.
-    public nonisolated static let version = "7.13.0"
+    public nonisolated static let version = "7.14.0"
 }

From e66d57e8b59ad7aedb12ed3f042e6512858aff39 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Tue, 22 Sep 2026 22:27:10 +0200
Subject: [PATCH 007/359] feat(stills): scrub stills on the software VOD path
 from the packet cache (AE#605)

A VOD session the device cannot hardware-decode already spools its packets to a
disk cache with keyframe cursors, and its seeks land in that cache, but
scrubThumbnail had no arm for it and supportsCacheBackedStills was keyed on the
native segment cache alone. On a source that refuses a second request (an IPTV
account capped at one connection, a debrid link) the FrameExtractor fallback
cannot open either, so every such session scrubbed blind.

The still now comes out of that cache. SoftwarePacketDiskFIFO gains a history
walk from a cursor on handles of its own, so the consumer's reader never moves;
SoftwarePacketReadAhead plans the run (newest keyframe at or before the target,
video only, through the target plus a reorder tail) under the cached seek's own
eligibility rule; SoftwareStillExtractor replays the stored packets with their
full envelope. It runs on the #544 still queue with the same newest-wins ticket
and the same lazily built extractor. A target past what is retained answers nil
rather than the frame before it.

supportsCacheBackedStills is now true for a software VOD session reading a
remote source and for a software live session, which already served stills but
reported false. A local file keeps no cache and stays false.

aetherctl play --sw --host-calls still gains a VOD arm. On a 300 s H.264 fixture
over HTTP: before 0 of 3, after 2 of 3 (4.37 s shows 4, 24.37 s shows 24, in
53 and 41 ms, no network), and the aim 600 s past the frontier misses as it must.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 CHANGELOG.md                                  |  12 +-
 .../AetherEngine+ScrubThumbnail.swift         |  25 +-
 .../Native/SoftwarePacketDiskFIFO.swift       |  54 +++++
 .../Native/SoftwarePacketReadAhead.swift      |  48 ++++
 .../Native/SoftwarePlaybackHost.swift         |  34 +++
 .../Native/SoftwareStillExtractor.swift       |  32 ++-
 Sources/aetherctl/PlaybackCmd.swift           |  28 ++-
 .../Issue605SoftwareVODStillTests.swift       | 218 ++++++++++++++++++
 docs/api.md                                   |   6 +-
 docs/cli.md                                   |   2 +-
 10 files changed, 441 insertions(+), 18 deletions(-)
 create mode 100644 Tests/AetherEngineTests/Issue605SoftwareVODStillTests.swift

diff --git a/CHANGELOG.md b/CHANGELOG.md
index effa67da2..04c042da8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,7 +10,17 @@ the public-API contract.
 
 ## [Unreleased]
 
-_Nothing yet._
+### Added
+
+- **Scrub stills on the software VOD path, with no second connection (AE#605).** A VOD session the
+  device cannot hardware-decode (MPEG-4 Part 2, MPEG-2, interlaced H.264, everything on the iOS
+  Simulator) already spools its packets to a disk cache its seeks land in, but `scrubThumbnail`
+  had no arm for it, so every such session scrubbed blind on a source that refuses a second
+  request. It now decodes the still out of that cache, keyframe to target, through the same
+  extractor, queue and newest-wins ticket the live software path uses (#544), and the consumer
+  cursor is never moved, so playback reads on undisturbed. A target past what is retained answers
+  nil rather than the frame before it. `supportsCacheBackedStills` is true for such a session, and
+  now also for a software live session, which already served stills but reported false.
 
 ## [7.14.0] - 2026-09-22
 
diff --git a/Sources/AetherEngine/AetherEngine+ScrubThumbnail.swift b/Sources/AetherEngine/AetherEngine+ScrubThumbnail.swift
index ddc1f2741..feb8af635 100644
--- a/Sources/AetherEngine/AetherEngine+ScrubThumbnail.swift
+++ b/Sources/AetherEngine/AetherEngine+ScrubThumbnail.swift
@@ -30,8 +30,17 @@ extension AetherEngine {
     /// to 0: thumbnail mode returns the first frame after the seek, so 0 lands on that segment's
     /// first keyframe whether its fMP4 tfdt is absolute or zero-based (post-restart). This makes
     /// the decode axis-independent and correct by construction. Per-segment granularity.
+    ///
+    /// A software session (AE#605) has no segments; it decodes the still out of the packet cache
+    /// its seeks already land in, keyframe to target, on the same session axis `seek(to:)` takes.
     public func vodScrubThumbnail(atSeconds seconds: Double, maxWidth: Int = 320) async -> CGImage? {
-        guard !isLive, let session = nativeVideoSession else { return nil }
+        guard !isLive else { return nil }
+        guard let session = nativeVideoSession else {
+            guard let host = softwareHost else { return nil }
+            let gen = loadGeneration
+            let image = await host.vodScrubStill(atSessionSeconds: seconds, maxWidth: maxWidth)
+            return loadGeneration == gen ? image : nil
+        }
         let gen = loadGeneration
         let source = await Task.detached(priority: .userInitiated) { [session] in
             session.scrubThumbnailSource(atSeconds: seconds)
@@ -61,12 +70,18 @@ extension AetherEngine {
         }
     }
 
-    /// True when a native session (live or VOD) is active, so `scrubThumbnail` can serve
-    /// cache-backed stills with no second connection. False on the software path (no
-    /// SegmentCache) and before load. Hosts on a single-connection source should gate the
+    /// True when the active session can serve cache-backed stills from `scrubThumbnail` with no
+    /// second connection: any native session (live or VOD, SegmentCache), a software live session
+    /// (DVR packet ring, #544) and a software VOD session reading a remote source (packet cache,
+    /// AE#605). False before load and on a software session that plays a local file, which keeps no
+    /// cache because re-reading the file is free; `makeFrameExtractor()` serves that case. Hosts on a single-connection source should gate the
     /// scrub-preview affordance on this: true means use `scrubThumbnail`; false means hide
     /// the preview rather than show blank frames from a refused second-connection
     /// FrameExtractor (#106). It reports capability, not per-frame availability: transient
     /// nils from `scrubThumbnail` while a segment is still being produced are expected.
-    public var supportsCacheBackedStills: Bool { nativeVideoSession != nil }
+    public var supportsCacheBackedStills: Bool {
+        if nativeVideoSession != nil { return true }
+        guard let softwareHost else { return false }
+        return isLive || softwareHost.servesPacketCacheStills
+    }
 }
diff --git a/Sources/AetherEngine/Native/SoftwarePacketDiskFIFO.swift b/Sources/AetherEngine/Native/SoftwarePacketDiskFIFO.swift
index 26bb7b548..ae4dd092e 100644
--- a/Sources/AetherEngine/Native/SoftwarePacketDiskFIFO.swift
+++ b/Sources/AetherEngine/Native/SoftwarePacketDiskFIFO.swift
@@ -242,6 +242,60 @@ final class SoftwarePacketDiskFIFO: @unchecked Sendable {
         }
     }
 
+    /// AE#605: walks retained records from `cursor` on without touching the consumer's reader, so a
+    /// scrub still can decode out of history while playback keeps reading its own position.
+    ///
+    /// The lock is held only to validate the cursor and to snapshot the tail. The disk reads run
+    /// outside it on handles of their own, because a GOP is megabytes and the producer and the
+    /// consumer both serialize on this lock. That is safe for two reasons: an unlinked chunk stays
+    /// readable through a handle opened before the unlink, and the tail is read only up to the
+    /// length snapshotted here, never into a record still being written. What it cannot see is a
+    /// reset recreating the same chunk names underneath it, so the generation is checked again
+    /// once the walk ends, and a walk that raced a reset throws `invalidCursor` AFTER visiting: the
+    /// caller discards whatever it collected. `visit` returns false to stop early. Failures never
+    /// poison the store: a still is optional, playback is not.
+    func readHistory(from cursor: Cursor, visit: (Data) throws -> Bool) throws {
+        lock.lock()
+        do { try requireUsable() } catch { lock.unlock(); throw error }
+        guard retainConsumed else { lock.unlock(); throw Failure.retentionDisabled }
+        guard cursor.generation == generation, chunks > 0,
+              cursor.chunkID >= oldestChunkID, cursor.chunkID <= tailID,
+              cursor.recordIndex >= 0, cursor.recordIndex < writtenRecordCount else {
+            lock.unlock()
+            throw Failure.invalidCursor
+        }
+        let lastChunk = tailID
+        let lastChunkBytes = tailBytes
+        lock.unlock()
+
+        var chunkID = cursor.chunkID
+        var offset = cursor.offset
+        walk: while chunkID <= lastChunk {
+            guard let handle = try? FileHandle(forReadingFrom: chunkURL(chunkID)) else {
+                throw Failure.invalidCursor
+            }
+            defer { try? handle.close() }
+            let limit = chunkID == lastChunk ? lastChunkBytes : try handle.seekToEnd()
+            try handle.seek(toOffset: offset)
+            while offset < limit {
+                guard limit - offset >= 8 else { throw Failure.corruptRecord }
+                let header = try readExactly(8, from: handle)
+                let length = header.reduce(UInt64(0)) { ($0 << 8) | UInt64($1) }
+                guard length <= limit - offset - 8 else { throw Failure.corruptRecord }
+                let record = try readExactly(Int(length), from: handle)
+                offset += 8 + length
+                if try !visit(record) { break walk }
+            }
+            chunkID += 1
+            offset = 0
+        }
+
+        lock.lock()
+        let stillValid = cursor.generation == generation && !isClosed
+        lock.unlock()
+        guard stillValid else { throw Failure.invalidCursor }
+    }
+
     /// Evict only complete history chunks strictly before the reader, oldest first. A budget is
     /// not permission to discard unread packets or the current reader/writer chunk; the resident
     /// count can therefore remain above budget until the consumer advances. No packet/chunk index
diff --git a/Sources/AetherEngine/Native/SoftwarePacketReadAhead.swift b/Sources/AetherEngine/Native/SoftwarePacketReadAhead.swift
index 135c579f2..4a0a350d0 100644
--- a/Sources/AetherEngine/Native/SoftwarePacketReadAhead.swift
+++ b/Sources/AetherEngine/Native/SoftwarePacketReadAhead.swift
@@ -216,6 +216,54 @@ final class SoftwarePacketReadAhead: @unchecked Sendable {
         return false
     }
 
+    /// AE#605: the retained video packets a scrub still at `seconds` needs, keyframe first, or nil
+    /// when the store cannot answer it. Any thread except main: it reads the disk.
+    ///
+    /// Eligibility is the cached seek's own rule, coverage past the target plus a retained keyframe
+    /// at or before it, so a still is offered exactly where a commit to that position would be a
+    /// cache hit, and the card never shows a picture the seek then has to fetch. Unlike the live
+    /// ring there is no clamp at the end: a VOD target past the frontier has a real frame the store
+    /// does not hold yet, and the frame before it is the wrong answer. The consumer cursor is not
+    /// touched, so playback reads on from where it stood.
+    func stillRun(atSeconds seconds: Double, maxPackets: Int, maxSpanSeconds: Double,
+                  reorderTail: Int) -> [SoftwareStoredPacket]? {
+        guard seconds.isFinite, maxPackets > 0 else { return nil }
+        condition.lock()
+        let eligible = !closed && !sourceRepositioning && !resetPending && failure == nil
+            && (frontierLocked(at: seconds).map { $0 > seconds } ?? false)
+        let anchor = eligible
+            ? keyframes.filter { $0.seconds <= seconds }.max { $0.seconds < $1.seconds } : nil
+        condition.unlock()
+        guard let anchor, seconds - anchor.seconds <= maxSpanSeconds else { return nil }
+
+        var run: [SoftwareStoredPacket] = []
+        var reached = false
+        var tail = reorderTail
+        var overflow = false
+        do {
+            try fifo.readHistory(from: anchor.cursor) { data in
+                let packet = try SoftwareStoredPacket.decode(data)
+                guard packet.streamIndex == video.index else { return true }
+                if run.isEmpty, packet.flags & 1 == 0 { overflow = true; return false }
+                run.append(packet)
+                if run.count > maxPackets { overflow = true; return false }
+                if reached {
+                    tail -= 1
+                    return tail > 0
+                }
+                if let pts = videoSeconds(pts: packet.pts), pts >= seconds {
+                    reached = true
+                    return tail > 0
+                }
+                return true
+            }
+        } catch {
+            return nil
+        }
+        guard reached, !overflow else { return nil }
+        return run
+    }
+
     func endSeek(_ token: UInt64, sourceClock: Double) {
         condition.lock(); defer { condition.unlock() }
         guard token == generation, !closed else { return }
diff --git a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
index 04d412ccf..5592fb111 100644
--- a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
+++ b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
@@ -1433,6 +1433,40 @@ final class SoftwarePlaybackHost {
         }
     }
 
+    /// AE#605: true when this VOD session keeps a packet cache a still can be decoded from. A local
+    /// file has none (it is read directly, see the spool's setup), and neither does a session whose
+    /// cache could not be built.
+    var servesPacketCacheStills: Bool { !isLive && vodPacketReadAhead != nil }
+
+    /// AE#605: the VOD twin of `liveScrubStill`, decoded out of the retained packet cache.
+    ///
+    /// Same queue, same newest-wins ticket and same extractor as the live still, and the same session
+    /// axis conversion `seek` uses, so the card and the commit name one moment. The disk read runs on
+    /// the still queue too, never on the demux or feed loop.
+    func vodScrubStill(atSessionSeconds seconds: Double, maxWidth: Int) async -> CGImage? {
+        guard !isLive, let cache = vodPacketReadAhead, let extractor = resolveStillExtractor() else {
+            return nil
+        }
+        let targetSource = sourceSeconds(forSession: seconds)
+        let limits = SoftwareStillExtractor.Limits.vod
+        let requests = stillRequests
+        let ticket = requests.next()
+        return await withCheckedContinuation { continuation in
+            stillQueue.async {
+                guard ticket == requests.latest,
+                      let run = cache.stillRun(atSeconds: targetSource,
+                                               maxPackets: limits.maxPackets,
+                                               maxSpanSeconds: limits.maxSpanSeconds,
+                                               reorderTail: limits.reorderTail) else {
+                    continuation.resume(returning: nil)
+                    return
+                }
+                continuation.resume(
+                    returning: extractor.still(from: run, targetPts: targetSource, maxWidth: maxWidth))
+            }
+        }
+    }
+
     /// Live DVR rewind: reseeds decoder from the ring (source PTS axis; maps via sessionStartPts) without touching the live demuxer. After return, the loop reads new packets forward and plays back to live.
     private func seekLiveDVR(to targetSession: Double, ring: PacketRingBuffer, wasPlaying: Bool) async {
         let targetSource = sourceSeconds(forSession: targetSession)
diff --git a/Sources/AetherEngine/Native/SoftwareStillExtractor.swift b/Sources/AetherEngine/Native/SoftwareStillExtractor.swift
index 2234cc82d..609f15e17 100644
--- a/Sources/AetherEngine/Native/SoftwareStillExtractor.swift
+++ b/Sources/AetherEngine/Native/SoftwareStillExtractor.swift
@@ -28,6 +28,10 @@ final class SoftwareStillExtractor: @unchecked Sendable {
         /// Packets are stored in decode order, so the frame at the target can sit behind the first
         /// packet that reaches it. Two B-frames is the common broadcast shape; four covers the rest.
         var reorderTail: Int = 4
+
+        /// AE#605: a file's GOP is not a broadcast one. x264's default keyint is 250 pictures,
+        /// ten seconds at 25 fps and four at 60, and B-pyramids reorder deeper than two B-frames.
+        static let vod = Limits(maxPackets: 900, maxSpanSeconds: 12, reorderTail: 16)
     }
 
     private let decoder = SoftwareVideoDecoder()
@@ -72,6 +76,30 @@ final class SoftwareStillExtractor: @unchecked Sendable {
                                       reorderTail: limits.reorderTail),
               !run.isEmpty else { return nil }
 
+        return decodeRun(targetPts: targetPts, maxWidth: maxWidth) {
+            for packet in run { feed(packet) }
+        }
+    }
+
+    /// AE#605: the same still out of a software VOD session's retained packets. They arrive as the
+    /// demuxer produced them, envelope and all, so they are replayed as is: a VOD stream carries real
+    /// decode timestamps and side data that the ring's pts-only shape has no room for.
+    func still(from run: [SoftwareStoredPacket], targetPts: Double, maxWidth: Int) -> CGImage? {
+        guard isOpen, maxWidth > 0, let first = run.first, first.flags & AV_PKT_FLAG_KEY != 0 else {
+            return nil
+        }
+        return decodeRun(targetPts: targetPts, maxWidth: maxWidth) {
+            for stored in run {
+                guard let p = try? stored.makeAVPacket() else { continue }
+                var packet: UnsafeMutablePointer<AVPacket>? = p
+                defer { trackedPacketFree(&packet) }
+                p.pointee.stream_index = videoStreamIndex
+                decoder.decode(packet: p, epoch: nil)
+            }
+        }
+    }
+
+    private func decodeRun(targetPts: Double, maxWidth: Int, feedRun: () -> Void) -> CGImage? {
         let collector = FrameCollector(target: targetPts)
         decoder.onFrame = { pixelBuffer, pts, _ in
             collector.append(pixelBuffer: pixelBuffer, seconds: pts.seconds)
@@ -79,9 +107,7 @@ final class SoftwareStillExtractor: @unchecked Sendable {
         decoder.flush(resetFilterGraph: false)
         defer { decoder.onFrame = nil }
 
-        for packet in run {
-            feed(packet)
-        }
+        feedRun()
 
         guard let best = collector.best else { return nil }
         return Self.image(from: best, maxWidth: maxWidth)
diff --git a/Sources/aetherctl/PlaybackCmd.swift b/Sources/aetherctl/PlaybackCmd.swift
index 0eae838cb..68e301068 100644
--- a/Sources/aetherctl/PlaybackCmd.swift
+++ b/Sources/aetherctl/PlaybackCmd.swift
@@ -990,21 +990,39 @@ private func playSmokeTest(url: URL, seconds: Double, live: Bool, forceSoftware:
         if hostCalls.contains("still"), [15, 20, 25].contains(tick) {
             // The third aim is the live EDGE itself, not the playhead: a target a fraction past the
             // newest packet is the clamp case, and it is where a live viewer sits most.
+            // AE#605: a VOD session aims behind the playhead (retained history), ahead of it (the
+            // forward buffer) and far past what is retained, where the right answer is a MISS: the
+            // frame there exists, the cache just does not hold it, and the one before it is wrong.
+            let isLive = engine.isLive
             let target: Double
             let label: String
-            switch tick {
-            case 15:
+            switch (tick, isLive) {
+            case (15, true):
                 target = max(0, engine.currentTime - 20)
                 label = "playhead-20"
-            case 20:
+            case (20, true):
                 target = max(0, engine.currentTime - 5)
                 label = "playhead-5"
-            default:
+            case (_, true):
                 target = engine.seekableLiveRange?.upperBound ?? engine.currentTime
                 label = "edge"
+            case (15, false):
+                target = max(0, engine.currentTime - 10.5)
+                label = "playhead-10.5"
+            case (20, false):
+                target = engine.currentTime + 4.5
+                label = "playhead+4.5"
+            default:
+                target = min(engine.currentTime + 600, max(0, engine.duration - 1))
+                label = "past-frontier"
+            }
+            if tick == 15 {
+                print("  HOSTCALL supportsCacheBackedStills -> \(engine.supportsCacheBackedStills)")
             }
             let started = Date()
-            let image = await engine.liveScrubThumbnail(atSessionSeconds: target, maxWidth: 320)
+            let image = isLive
+                ? await engine.liveScrubThumbnail(atSessionSeconds: target, maxWidth: 320)
+                : await engine.scrubThumbnail(atSeconds: target, maxWidth: 320)
             let ms = Int(Date().timeIntervalSince(started) * 1000)
             stillAttempts += 1
             if let image {
diff --git a/Tests/AetherEngineTests/Issue605SoftwareVODStillTests.swift b/Tests/AetherEngineTests/Issue605SoftwareVODStillTests.swift
new file mode 100644
index 000000000..dbc01f84d
--- /dev/null
+++ b/Tests/AetherEngineTests/Issue605SoftwareVODStillTests.swift
@@ -0,0 +1,218 @@
+import Foundation
+import Testing
+@testable import AetherEngine
+
+/// AE#605: a software VOD session decodes scrub stills out of the packet cache its seeks already
+/// land in, instead of opening a second connection a single-slot origin refuses.
+///
+/// Two properties carry the feature. The run a still needs has to be read from HISTORY without
+/// moving the consumer, or every preview would rewind playback. And the run is offered exactly where
+/// a commit would be a cache hit: a target past the retained frontier has a real frame the store
+/// does not hold yet, so the frame before it is the wrong answer rather than a close one.
+@Suite("Software VOD scrub stills from the packet cache (AE#605)")
+struct Issue605SoftwareVODStillTests {
+
+    // MARK: - FIFO history walk
+
+    private static func makeRoot() throws -> URL {
+        let root = FileManager.default.temporaryDirectory
+            .appendingPathComponent("issue605-\(UUID().uuidString)", isDirectory: true)
+        try FileManager.default.createDirectory(at: root, withIntermediateDirectories: true)
+        return root
+    }
+
+    private static func record(_ value: UInt8) -> Data { Data(repeating: value, count: 20) }
+
+    @Test("A history walk crosses chunks and leaves the consumer where it stood")
+    func historyWalkDoesNotMoveConsumer() throws {
+        let root = try Self.makeRoot()
+        defer { try? FileManager.default.removeItem(at: root) }
+        // 64-byte chunks hold two 28-byte records, so ten records span five chunks.
+        let fifo = try SoftwarePacketDiskFIFO(chunkTargetBytes: 64, retainConsumed: true,
+                                              parentDirectory: root)
+        var cursors: [SoftwarePacketDiskFIFO.Cursor] = []
+        for value in UInt8(0)..<10 { cursors.append(try fifo.append(Self.record(value))) }
+
+        var seen: [UInt8] = []
+        try fifo.readHistory(from: cursors[3]) { data in
+            seen.append(data.first ?? 255)
+            return true
+        }
+        #expect(seen == Array(3..<10))
+        #expect(try fifo.pop() == Self.record(0))
+        #expect(fifo.snapshot.count == 9)
+    }
+
+    @Test("A history walk stops when the visitor says so")
+    func historyWalkStopsEarly() throws {
+        let root = try Self.makeRoot()
+        defer { try? FileManager.default.removeItem(at: root) }
+        let fifo = try SoftwarePacketDiskFIFO(chunkTargetBytes: 64, retainConsumed: true,
+                                              parentDirectory: root)
+        var cursors: [SoftwarePacketDiskFIFO.Cursor] = []
+        for value in UInt8(0)..<10 { cursors.append(try fifo.append(Self.record(value))) }
+
+        var seen: [UInt8] = []
+        try fifo.readHistory(from: cursors[1]) { data in
+            seen.append(data.first ?? 255)
+            return seen.count < 3
+        }
+        #expect(seen == [1, 2, 3])
+    }
+
+    @Test("A cursor from before a reset is refused, and the store stays usable")
+    func historyWalkRefusesStaleCursor() throws {
+        let root = try Self.makeRoot()
+        defer { try? FileManager.default.removeItem(at: root) }
+        let fifo = try SoftwarePacketDiskFIFO(chunkTargetBytes: 64, retainConsumed: true,
+                                              parentDirectory: root)
+        let stale = try fifo.append(Self.record(1))
+        try fifo.reset()
+        try fifo.append(Self.record(2))
+
+        #expect(throws: SoftwarePacketDiskFIFO.Failure.invalidCursor) {
+            try fifo.readHistory(from: stale) { _ in true }
+        }
+        #expect(!fifo.snapshot.hasFailure)
+        #expect(try fifo.pop() == Self.record(2))
+    }
+
+    @Test("A cursor whose chunk was evicted is refused")
+    func historyWalkRefusesEvictedCursor() throws {
+        let root = try Self.makeRoot()
+        defer { try? FileManager.default.removeItem(at: root) }
+        let fifo = try SoftwarePacketDiskFIFO(chunkTargetBytes: 64, retainConsumed: true,
+                                              parentDirectory: root)
+        var cursors: [SoftwarePacketDiskFIFO.Cursor] = []
+        for value in UInt8(0)..<10 { cursors.append(try fifo.append(Self.record(value))) }
+        for _ in 0..<6 { _ = try fifo.pop() }
+        try fifo.trimConsumed(toByteBudget: 0)
+
+        #expect(throws: SoftwarePacketDiskFIFO.Failure.invalidCursor) {
+            try fifo.readHistory(from: cursors[0]) { _ in true }
+        }
+        var seen: [UInt8] = []
+        try fifo.readHistory(from: cursors[6]) { seen.append($0.first ?? 255); return true }
+        #expect(seen == Array(6..<10))
+    }
+
+    // MARK: - Still run planning
+
+    /// 25 pictures a second on a 1/1000 time base, a keyframe every second, and a non-video packet
+    /// after every picture so the run has something to filter out.
+    private static let tickRate: Int32 = 1000
+    private static let holdTicks: Int64 = 40
+    private static let pictureRate = 25
+
+    private final class Counter: @unchecked Sendable {
+        private let lock = NSLock()
+        private var count = 0
+        func next() -> Int { lock.lock(); defer { lock.unlock() }; count += 1; return count }
+        var value: Int { lock.lock(); defer { lock.unlock() }; return count }
+    }
+
+    private static func sourcePacket(index: Int, keyframeEvery: Int) -> SoftwareStoredPacket {
+        let picture = (index - 1) / 2
+        let pts = Int64(picture) * holdTicks
+        let isVideo = (index - 1) % 2 == 0
+        let isKey = isVideo && picture % keyframeEvery == 0
+        return SoftwareStoredPacket(pts: pts, dts: pts, duration: holdTicks, position: 0,
+                                    streamIndex: isVideo ? 0 : 5, flags: isKey ? 0x1 : 0,
+                                    timeBaseNumerator: 1, timeBaseDenominator: tickRate,
+                                    bytes: Data(repeating: 7, count: 100), sideData: [])
+    }
+
+    /// A producer that has filled its forward window and parked, with no consumer yet.
+    private static func parkedCache(root: URL, forwardSeconds: Double,
+                                    keyframeEvery: Int = pictureRate) throws -> SoftwarePacketReadAhead {
+        let counter = Counter()
+        let fifo = try SoftwarePacketDiskFIFO(chunkTargetBytes: 64 * 1024, retainConsumed: true,
+                                              parentDirectory: root)
+        let cache = SoftwarePacketReadAhead(
+            video: .init(index: 0, numerator: 1, denominator: tickRate), audio: nil,
+            byteBudget: 50_000_000, forwardSeconds: forwardSeconds, initialSourceClock: 0,
+            fifo: fifo
+        ) { _ in Self.sourcePacket(index: counter.next(), keyframeEvery: keyframeEvery) }
+        cache.start()
+        let deadline = Date().addingTimeInterval(10)
+        var previous = -1
+        while Date() < deadline {
+            Thread.sleep(forTimeInterval: 0.15)
+            let now = counter.value
+            if now == previous, now > 0 { break }
+            previous = now
+        }
+        return cache
+    }
+
+    private static func seconds(_ packet: SoftwareStoredPacket) -> Double {
+        Double(packet.pts) / Double(tickRate)
+    }
+
+    @Test("A run opens on the keyframe before the target and reaches past it, video only")
+    func runOpensOnKeyframeAndReachesTarget() throws {
+        let root = try Self.makeRoot()
+        defer { try? FileManager.default.removeItem(at: root) }
+        let cache = try Self.parkedCache(root: root, forwardSeconds: 10)
+        defer { cache.close() }
+
+        let run = try #require(cache.stillRun(atSeconds: 3.5, maxPackets: 900,
+                                              maxSpanSeconds: 12, reorderTail: 4))
+        #expect(run.first.map(Self.seconds) == 3.0)
+        #expect(run.first.map { $0.flags & 1 != 0 } == true)
+        #expect(run.allSatisfy { $0.streamIndex == 0 })
+        // 3.00 through 3.52 is fourteen pictures (the first at or past 3.5), plus the tail of four.
+        #expect(run.count == 18)
+        #expect(run.contains { Self.seconds($0) >= 3.5 })
+    }
+
+    @Test("A still leaves the consumer at the packet it would have read next")
+    func runDoesNotMoveConsumer() throws {
+        let root = try Self.makeRoot()
+        defer { try? FileManager.default.removeItem(at: root) }
+        let cache = try Self.parkedCache(root: root, forwardSeconds: 10)
+        defer { cache.close() }
+
+        #expect(cache.stillRun(atSeconds: 6.2, maxPackets: 900, maxSpanSeconds: 12,
+                               reorderTail: 4) != nil)
+        let next = try #require(try cache.read())
+        #expect(next.pts == 0)
+        #expect(next.streamIndex == 0)
+    }
+
+    @Test("A target past the retained frontier gets no still, not the frame before it")
+    func runRefusesPastFrontier() throws {
+        let root = try Self.makeRoot()
+        defer { try? FileManager.default.removeItem(at: root) }
+        let cache = try Self.parkedCache(root: root, forwardSeconds: 10)
+        defer { cache.close() }
+
+        #expect(cache.stillRun(atSeconds: 60, maxPackets: 900, maxSpanSeconds: 12,
+                               reorderTail: 4) == nil)
+    }
+
+    @Test("A keyframe further back than the span bound gets no still")
+    func runRefusesWideSpan() throws {
+        let root = try Self.makeRoot()
+        defer { try? FileManager.default.removeItem(at: root) }
+        // One keyframe every eight seconds.
+        let cache = try Self.parkedCache(root: root, forwardSeconds: 10, keyframeEvery: 200)
+        defer { cache.close() }
+
+        #expect(cache.stillRun(atSeconds: 5, maxPackets: 900, maxSpanSeconds: 2,
+                               reorderTail: 4) == nil)
+        #expect(cache.stillRun(atSeconds: 5, maxPackets: 900, maxSpanSeconds: 12,
+                               reorderTail: 4) != nil)
+    }
+
+    @Test("A run longer than the packet bound gets no still")
+    func runRefusesPacketOverflow() throws {
+        let root = try Self.makeRoot()
+        defer { try? FileManager.default.removeItem(at: root) }
+        let cache = try Self.parkedCache(root: root, forwardSeconds: 10)
+        defer { cache.close() }
+
+        #expect(cache.stillRun(atSeconds: 0.9, maxPackets: 10, maxSpanSeconds: 12,
+                               reorderTail: 4) == nil)
+    }
+}
diff --git a/docs/api.md b/docs/api.md
index 208e495a9..705ff000c 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -833,9 +833,9 @@ say so on the tracker rather than working around it.
 
 | Symbol | Notes |
 | --- | --- |
-| `scrubThumbnail(atSeconds:maxWidth:)` | Cache-backed still for the active native session, live or VOD. Decodes bytes already produced, so it opens no second connection and works on single-connection sources (debrid / torrent links) where a second demuxer is refused. |
-| `vodScrubThumbnail(atSeconds:maxWidth:)`, `liveScrubThumbnail(atSessionSeconds:maxWidth:)` | The two arms, for callers that know which axis they hold. The live arm also serves software sessions, out of the DVR packet ring rather than a segment cache (#544). |
-| `supportsCacheBackedStills` | True while a native session exists, which is what the SEGMENT CACHE needs. Gate the scrub-preview affordance on it: it reports capability, not per-frame availability, so a transient nil from `scrubThumbnail` while a segment is still being produced is expected and means "time only, no image". It stays false on a software session, and a live one nonetheless serves stills from its packet ring, so a live caller asks `liveScrubThumbnail` rather than this flag. |
+| `scrubThumbnail(atSeconds:maxWidth:)` | Cache-backed still for the active session, live or VOD. Decodes bytes the session already holds, so it opens no second connection and works on single-connection sources (debrid / torrent links, IPTV accounts capped at one request) where a second demuxer is refused. A native session decodes from its segment cache, a software session from its packet cache (VOD, AE#605) or its DVR packet ring (live, #544). A VOD target outside what is retained returns nil rather than the nearest retained frame. |
+| `vodScrubThumbnail(atSeconds:maxWidth:)`, `liveScrubThumbnail(atSessionSeconds:maxWidth:)` | The two arms, for callers that know which axis they hold. Both arms also serve software sessions: the live arm out of the DVR packet ring (#544), the VOD arm out of the packet cache its seeks land in (AE#605), keyframe to target, on the same axis `seek(to:)` takes. |
+| `supportsCacheBackedStills` | True while the session can serve `scrubThumbnail` without a second connection: any native session, a software live session, and a software VOD session reading a remote source. Gate the scrub-preview affordance on it: it reports capability, not per-frame availability, so a transient nil from `scrubThumbnail` while a segment is still being produced, or for a position the cache does not hold, is expected and means "time only, no image". False on a software session playing a local file, which keeps no cache because re-reading the file is free; `makeFrameExtractor()` serves that case. Before AE#605 this was false on every software session, live included. |
 
 ## Certificate trust
 
diff --git a/docs/cli.md b/docs/cli.md
index 8af49846b..55d5484a7 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -140,7 +140,7 @@ the same clock as `FIRSTFRAME`. The 1 Hz tick samples the phase, which is far to
 signal apart from the moment the rate rolls; a healthy native join is exactly two edges, `loading` at the
 load and `playing` at the roll (AE#440).
 
-`--subs <codec-or-lang>` matches against the track's libavcodec name or language and logs every overlay cue and cue trim as it lands. `--host-calls` replays host post-load behavior against the fresh session: `play`, `extractor` (`makeFrameExtractor`), `setrate` (`setRate(1.0)`), `pausestart` (Sodalite#104 round 4: `pause()` the instant load returns, before any frame exists, and `play()` at t=8; the shape of a host that holds a fresh load paused, and a software session used to answer it with eight ticks of `enq=+0 status=unknown r4d=n`, a black picture under a paused clock; now the `[SWHost] #104` lines show the first frame presented at a stopped clock and `startup 8/8 presenting` arrives while paused), `ratehold` (set 1.5, pause at tick 3, resume at tick 5, then read the rate back off the transport itself: the #436 drill, and it fails the run if the resume came back at 1.0), `reloadlive` (reload the URL on the live path when the probe flags it live, the AetherPlayer Open URL flow), `seekback` (rewind 20 s into the DVR window at t=15, return to the live edge at t=30), `overlapseek` (the #292 seek-window drills below), `pausehold` (Sodalite#104: pause at t=10 and HOLD until ten seconds before the end, printing the playhead, the edge and the resident depth every second, which is how a session paused for longer than its own DVR window is measured without waiting out a real one: pair it with `--dvr-window 30` and `--seconds 90` and the ninety minute question becomes a ninety second run), `still` (#544: asks for a scrub still at three aims, 20 s behind the playhead at t=15, 5 s behind at t=20 and at the edge at t=25, writing each to `/tmp/aetherctl-still-<tick>.png` and reporting hit or MISS with the decode time; pair it with `--sw --dvr-window N`, where the picture comes out of the DVR packet ring rather than a segment cache, and read the FILE as well as the count, because the bundled seed burns its own second into the frame so a still asked for 14.85 s showing `14` is the verdict that it decoded the right moment and not merely an image; exit 6 when nothing hit, 5 when the session ended before the first aim), `stallclock` (AE#549: stop the master clock at t=4 behind the host's back, the way an interrupted audio session does, then call a plain `play()` at t=7 and read whether the playhead moves again; the interruption itself cannot be staged on macOS, its outcome can, and without the `RendererClockResume` branch the run ends with the clock standing exactly where the stall left it, which is the field log's shape), and `pauseseek` (pause at t=12, seek at t=15 while paused, resume at t=20; with `--sw` the five paused ticks between landing and resume show what the `[SWDiag]` line reports while the pump is parked and has not heard of the seek, the AE#479 shape); this is how the pre-arming `setRate` wedge was isolated.
+`--subs <codec-or-lang>` matches against the track's libavcodec name or language and logs every overlay cue and cue trim as it lands. `--host-calls` replays host post-load behavior against the fresh session: `play`, `extractor` (`makeFrameExtractor`), `setrate` (`setRate(1.0)`), `pausestart` (Sodalite#104 round 4: `pause()` the instant load returns, before any frame exists, and `play()` at t=8; the shape of a host that holds a fresh load paused, and a software session used to answer it with eight ticks of `enq=+0 status=unknown r4d=n`, a black picture under a paused clock; now the `[SWHost] #104` lines show the first frame presented at a stopped clock and `startup 8/8 presenting` arrives while paused), `ratehold` (set 1.5, pause at tick 3, resume at tick 5, then read the rate back off the transport itself: the #436 drill, and it fails the run if the resume came back at 1.0), `reloadlive` (reload the URL on the live path when the probe flags it live, the AetherPlayer Open URL flow), `seekback` (rewind 20 s into the DVR window at t=15, return to the live edge at t=30), `overlapseek` (the #292 seek-window drills below), `pausehold` (Sodalite#104: pause at t=10 and HOLD until ten seconds before the end, printing the playhead, the edge and the resident depth every second, which is how a session paused for longer than its own DVR window is measured without waiting out a real one: pair it with `--dvr-window 30` and `--seconds 90` and the ninety minute question becomes a ninety second run), `still` (#544: asks for a scrub still at three aims, 20 s behind the playhead at t=15, 5 s behind at t=20 and at the edge at t=25, writing each to `/tmp/aetherctl-still-<tick>.png` and reporting hit or MISS with the decode time; pair it with `--sw --dvr-window N`, where the picture comes out of the DVR packet ring rather than a segment cache, and read the FILE as well as the count, because the bundled seed burns its own second into the frame so a still asked for 14.85 s showing `14` is the verdict that it decoded the right moment and not merely an image; exit 6 when nothing hit, 5 when the session ended before the first aim; on a VOD session (AE#605) the three aims are 10.5 s behind the playhead, 4.5 s ahead of it and 600 s past it, through `scrubThumbnail`, and the third is EXPECTED to miss, because a frame the cache does not hold yet must not be answered with the one before it: `--sw` against an HTTP source is the software packet-cache case, and the testsrc fixture's counter in the PNG is the verdict that the still decoded to the target rather than snapping to its keyframe), `stallclock` (AE#549: stop the master clock at t=4 behind the host's back, the way an interrupted audio session does, then call a plain `play()` at t=7 and read whether the playhead moves again; the interruption itself cannot be staged on macOS, its outcome can, and without the `RendererClockResume` branch the run ends with the clock standing exactly where the stall left it, which is the field log's shape), and `pauseseek` (pause at t=12, seek at t=15 while paused, resume at t=20; with `--sw` the five paused ticks between landing and resume show what the `[SWDiag]` line reports while the pump is parked and has not heard of the seek, the AE#479 shape); this is how the pre-arming `setRate` wedge was isolated.
 
 `--seek-every N` seeks once every N ticks past tick 10, walking `--seek-pattern <abs,abs,...>` if one is given (a short backward hop otherwise), and `--seek-count K` stops after K seeks so a run can be a BURST and then play. Both halves are needed for anything about what a seek sequence leaves behind: the burst puts the store in the state under test, and only the playing half shows what the overlay carries through it. That pairing is what made AE#362's second mechanism reproducible (a hole between a restarted pump and the island the previous run left ahead of it, decoded across and then never re-read).
 

From 1cb881af89a81b182ec57d20b27c53e48bcfb234 Mon Sep 17 00:00:00 2001
From: superuser404notfound
 <264232962+superuser404notfound@users.noreply.github.com>
Date: Wed, 23 Sep 2026 04:34:03 +0000
Subject: [PATCH 008/359] docs(used-by): add stashy

---
 README.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/README.md b/README.md
index 707c9ec8a..871b7189b 100644
--- a/README.md
+++ b/README.md
@@ -46,6 +46,7 @@ You provide the transport bar. You provide the dropdowns. You provide the pretty
 - [Moonfin](https://github.com/Moonfin-Client/Moonfin-Core): A multi-platform third party Jellyfin client.
 - [Vivid](https://github.com/blurbery/vivid): open-source media app for iPhone, iPad and Apple TV.
 - [Snappier IPTV](https://apps.apple.com/gb/app/snappier-iptv/id1579702567): IPTV App for iOS/iPadOS and tvOS.
+- [stashy](https://stashy.shelf.am/): iOS/tvOS native player for stash.
 <!-- used-by:end -->
 
 Shipping something on AetherEngine? [Submit it](https://github.com/superuser404notfound/AetherEngine/issues/new?template=used-by-submission.yml) to get listed here and on [aetherengine.superuser404.de](https://aetherengine.superuser404.de).

From a8f790cf23d9f4f003bb2820f1a87fba566ceb0d Mon Sep 17 00:00:00 2001
From: Vincent <superuser404@mailbox.org>
Date: Wed, 23 Sep 2026 06:36:37 +0200
Subject: [PATCH 009/359] README.md aktualisieren

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 871b7189b..2533231d2 100644
--- a/README.md
+++ b/README.md
@@ -42,7 +42,7 @@ You provide the transport bar. You provide the dropdowns. You provide the pretty
 - [Syravo](https://syravo.app): Xtream Codes, Jellyfin and radio client for iPhone, iPad and Apple TV.
 - [KIPTV](https://kiptv.app): Premium, cross-platform IPTV Player.
 - [Silo](https://github.com/Silo-Server/silo-apple): native iOS, tvOS and macOS client for the Silo self-hosted media server.
-- [File Box](https://apps.apple.com/app/id6765818194): File Box is a simple and practical local file manager that makes it easy to manage, view, organize, and process your files on iPhone and iPad.
+- [File Box](https://apps.apple.com/app/id6765818194): File Box is a simple and practical local file manager on iPhone and iPad.
 - [Moonfin](https://github.com/Moonfin-Client/Moonfin-Core): A multi-platform third party Jellyfin client.
 - [Vivid](https://github.com/blurbery/vivid): open-source media app for iPhone, iPad and Apple TV.
 - [Snappier IPTV](https://apps.apple.com/gb/app/snappier-iptv/id1579702567): IPTV App for iOS/iPadOS and tvOS.

From 654d0f2c4411397cf629a9d1eb760aef842e171a Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 23 Sep 2026 07:06:13 +0200
Subject: [PATCH 010/359] chore(release): prep 7.15.0 - scrub stills on the
 software VOD path

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 CHANGELOG.md                                    | 4 ++++
 Examples/README.md                              | 2 +-
 README.md                                       | 6 +++---
 Sources/AetherEngine/AetherEngine+Version.swift | 2 +-
 4 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 04c042da8..330d6fac0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,10 @@ the public-API contract.
 
 ## [Unreleased]
 
+_Nothing yet._
+
+## [7.15.0] - 2026-09-23
+
 ### Added
 
 - **Scrub stills on the software VOD path, with no second connection (AE#605).** A VOD session the
diff --git a/Examples/README.md b/Examples/README.md
index aa8654e18..0b96226d3 100644
--- a/Examples/README.md
+++ b/Examples/README.md
@@ -18,7 +18,7 @@ Three samples covering different audiences:
    ```
    https://github.com/superuser404notfound/AetherEngine
    ```
-   Dependency Rule: Up to Next Major Version, starting from `7.14.0`. Add the `AetherEngine` library product to your app target.
+   Dependency Rule: Up to Next Major Version, starting from `7.15.0`. Add the `AetherEngine` library product to your app target.
 
 3. **Drop the file in.** Replace the Xcode template's default `App.swift` (or whatever the generated `@main` file is called) with the contents of [`MinimalPlayerApp.swift`](MinimalPlayer/MinimalPlayerApp.swift). The file is self-contained: it defines both the `@main App` struct and the `ContentView`.
 
diff --git a/README.md b/README.md
index 2533231d2..1b9cc0a1b 100644
--- a/README.md
+++ b/README.md
@@ -343,7 +343,7 @@ Subtitle cues land in raw source PTS; render the overlay against `player.sourceT
 Install via Swift Package Manager:
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.14.0")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.15.0")
 ```
 
 Three samples ship in `Examples/`:
@@ -590,10 +590,10 @@ Browse all of this as a searchable site at **[aetherengine.superuser404.de](http
 AetherEngine uses [Semantic Versioning](https://semver.org). The public API surface, every `public` declaration in `Sources/AetherEngine/`, is the stability contract. **Major** removes / renames public symbols or breaks adopters; **Minor** adds public API or codec / format support; **Patch** fixes bugs with no public API change. `internal` types are not part of the contract.
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.14.0")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.15.0")
 ```
 
-Pin to `.upToNextMinor(from: "7.14.0")` for stricter teams that prefer to opt into minor bumps explicitly.
+Pin to `.upToNextMinor(from: "7.15.0")` for stricter teams that prefer to opt into minor bumps explicitly.
 
 ## Requirements
 
diff --git a/Sources/AetherEngine/AetherEngine+Version.swift b/Sources/AetherEngine/AetherEngine+Version.swift
index 513bfb9eb..c41a0ccb4 100644
--- a/Sources/AetherEngine/AetherEngine+Version.swift
+++ b/Sources/AetherEngine/AetherEngine+Version.swift
@@ -11,5 +11,5 @@ extension AetherEngine {
     ///
     /// Between releases, and in a consumer that pins an unreleased commit for a device test, this
     /// names the last PUBLISHED version the checkout descends from, not every patch in it.
-    public nonisolated static let version = "7.14.0"
+    public nonisolated static let version = "7.15.0"
 }

From b9358b07ba0ad1db684e49bad3810ee0c7ad6a70 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 23 Sep 2026 11:27:37 +0200
Subject: [PATCH 011/359] fix(audio-delay): a rebuild raised the moment one
 returned keeps the playhead (AE#464 round 5)

`rebuildPosition` honoured the parked position only while `state == .loading`,
but the autostart at the tail of `load()` writes `.playing` before the new host
has published a position. For the next ~50 ms the clock still reads the zero
`load()` wrote, so a correction raised the moment a rebuild returned rebuilt the
session at its head. `setAudioDelay`'s own catch-up pass sits exactly in that
window, and so does a second stepper press 50-90 ms after the first on
`.loopback`.

A playable session whose clock reads exactly the reset zero now answers with the
parked position. An accepted seek retires the parked value, so a genuine seek to
0 is never overridden.

Measured with aetherctl (300 s H.264 + AAC, two presses 50-90 ms apart):
before `#3 mount seek: item axis 0.00s` / `cutting seg0+` on every run, after
`14.90s` / `seg3+` on every run. Control: load at 100 s, seek to 0, correct:
the rebuild mounts at 0.00s.

Reported by cmcpherson274 as E8-F4 (information, not filed).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 .../AetherEngine+AudioDelay.swift             |  7 ++++-
 Sources/AetherEngine/AetherEngine.swift       | 29 ++++++++++++++-----
 .../Issue464ReloadPreservesSessionTests.swift | 18 ++++++++++++
 docs/api.md                                   |  2 +-
 docs/cli.md                                   | 10 +++++++
 5 files changed, 56 insertions(+), 10 deletions(-)

diff --git a/Sources/AetherEngine/AetherEngine+AudioDelay.swift b/Sources/AetherEngine/AetherEngine+AudioDelay.swift
index d843520ca..6c6d993e5 100644
--- a/Sources/AetherEngine/AetherEngine+AudioDelay.swift
+++ b/Sources/AetherEngine/AetherEngine+AudioDelay.swift
@@ -180,7 +180,12 @@ extension AetherEngine {
     /// offset from there when they rebuild, so a re-anchor that has not reached its rebuild yet
     /// already carries the newest value. Only a press that lands after the rebuild has read it needs
     /// anything more, and that is one catch-up pass: the loop ends as soon as what was delivered is
-    /// what is in force, so a stepper held down converges instead of queueing a rebuild per press.
+    /// what is in force. Round 5 (cmcpherson274, measured): the pass is reached only by a press that
+    /// lands INSIDE a re-anchor, a band as wide as the re-anchor itself (54-65 ms on the simulator,
+    /// 87-88 ms on an Apple TV). Presses at a human cadence arrive after it and are each their own
+    /// complete re-anchor; a burst in one runloop turn arrives before the Task reads the value and
+    /// costs one. The pass starts the moment the first re-anchor returns, which on `.loopback` is
+    /// before the rebuilt host has published a position; `rebuildPosition` covers that window.
     private func reanchorForAudioDelay(_ reanchor: @escaping (_ position: Double, _ delay: Double) async -> Void) {
         guard Self.audioDelayRecutIsPossible(state: state, isLive: isLive, liveWindow: liveWindow) else {
             EngineLog.emit(
diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index 718bb6ac0..7769317ac 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -2551,12 +2551,21 @@ public final class AetherEngine: ObservableObject {
     /// survived cut `seg0+` on a title 15 s in. While a load is in flight the position that describes
     /// the session is the one THAT load was handed, which it received before the clock was cleared.
     ///
-    /// `.loading` is the whole of that window and nothing else: the only other writer of it holds it
-    /// through startup before the first roll (`host.$timeControlStatus`, which cannot reach it once
-    /// the session has played), so the parked value can never be read after the load it belongs to.
+    /// Round 5 (cmcpherson274, E8-F4): `.loading` was NOT the whole window. The autostart at the tail
+    /// of `load()` writes `.playing` before the new host has published a position, so for the next
+    /// ~50 ms the clock still reads the zero `load()` wrote, and a correction raised the moment a
+    /// rebuild returned rebuilt at the head. `setAudioDelay`'s own catch-up pass sits exactly there,
+    /// and so did a second stepper press 50-90 ms after the first on `.loopback` (measured on the CLI:
+    /// `#3 mount seek: item axis 0.00s`, `cutting seg0+`). A playable session whose clock reads exactly
+    /// the reset zero has not published yet, and the parked value is what it is mounted at. A seek
+    /// retires the parked value (`seek(to:origin:)`), so a genuine seek to 0 is never overridden.
     nonisolated static func rebuildPosition(state: PlaybackState, clock: Double, underReconstruction: Double?) -> Double {
-        guard state == .loading, let parked = underReconstruction else { return clock }
-        return parked
+        guard let parked = underReconstruction else { return clock }
+        switch state {
+        case .loading: return parked
+        case .playing, .paused: return clock == 0 ? parked : clock
+        case .idle, .seeking, .ended, .error: return clock
+        }
     }
 
     /// #227 round 2: whether a finishing session-preserving rebuild is the one that owns the held
@@ -3231,9 +3240,10 @@ public final class AetherEngine: ObservableObject {
 
     /// AE#464 round 2: the position the load currently in flight was handed, parked across the window
     /// in which `load` has already zeroed the clock but the rebuilt session has not reached it yet.
-    /// Written at the two sites that raise `state = .loading` for a load; read only through
-    /// `positionForSessionRebuild`, which is what makes a reload stacked behind another one rebuild at
-    /// the playhead instead of at the head.
+    /// Written at the two sites that raise `state = .loading` for a load, retired by an accepted seek;
+    /// read only through `positionForSessionRebuild`, which is what makes a reload stacked behind
+    /// another one, or raised the moment one returned (round 5), rebuild at the playhead instead of at
+    /// the head.
     var positionUnderReconstruction: Double?
 
     /// AE#464 round 3: the transport intent the load in flight was handed, parked across the same
@@ -5072,6 +5082,9 @@ public final class AetherEngine: ObservableObject {
                 + (held ? ", the place it held" : ", which is as close to it as the cache still reaches"),
                 category: .engine)
         }
+        // AE#464 round 5: from here the seek target describes the session, not the load before it,
+        // so a landing at exactly 0 is never read as a clock that has not published yet.
+        positionUnderReconstruction = nil
         state = .seeking
         // Span isSeeking across the real landing, not just the optimistic .playing flip (#38).
         // Generation guard at each finalize point prevents a superseded seek from clearing it.
diff --git a/Tests/AetherEngineTests/Issue464ReloadPreservesSessionTests.swift b/Tests/AetherEngineTests/Issue464ReloadPreservesSessionTests.swift
index 887ff29cb..90b0297d6 100644
--- a/Tests/AetherEngineTests/Issue464ReloadPreservesSessionTests.swift
+++ b/Tests/AetherEngineTests/Issue464ReloadPreservesSessionTests.swift
@@ -74,6 +74,24 @@ struct Issue464RebuildPositionTests {
         // what a reload stacked onto it must read: the previous session's playhead is gone.
         #expect(AetherEngine.rebuildPosition(state: .loading, clock: 0, underReconstruction: 0) == 0)
     }
+
+    @Test("a load that has returned but not yet published a playhead still answers with its parked position")
+    func returnedLoadBeforeFirstPublishKeepsThePosition() {
+        // Round 5 (cmcpherson274, E8-F4): the autostart at the tail of `load()` writes `.playing`
+        // before the new host has published a position, so a correction raised the moment a rebuild
+        // returned read the zeroed clock and rebuilt at the head. Measured on the CLI with two
+        // `setAudioDelay` presses 50-90 ms apart on `.loopback`: `#3 mount seek: item axis 0.00s`.
+        #expect(AetherEngine.rebuildPosition(state: .playing, clock: 0, underReconstruction: 312.8) == 312.8)
+        #expect(AetherEngine.rebuildPosition(state: .paused, clock: 0, underReconstruction: 312.8) == 312.8)
+    }
+
+    @Test("once the session has published a playhead, or has none, the clock answers again")
+    func publishedOrTerminalReadsTheClock() {
+        #expect(AetherEngine.rebuildPosition(state: .playing, clock: 312.9, underReconstruction: 312.8) == 312.9)
+        #expect(AetherEngine.rebuildPosition(state: .seeking, clock: 0, underReconstruction: 312.8) == 0)
+        #expect(AetherEngine.rebuildPosition(state: .idle, clock: 0, underReconstruction: 312.8) == 0)
+        #expect(AetherEngine.rebuildPosition(state: .ended, clock: 0, underReconstruction: 312.8) == 0)
+    }
 }
 
 /// AE#464 round 3 (measured on the CLI while building the in-flight latch): the window round 2
diff --git a/docs/api.md b/docs/api.md
index 705ff000c..fb113b0c8 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -521,7 +521,7 @@ Warms are serialised, one at a time across the process. A second `prewarm` while
 | `seek(to:)` | `async`. Source-axis seconds. Rejected when idle, errored, ended, or live without a DVR window. |
 | `seek(toSourceTime:)` | Deprecated alias for `seek(to:)`. The clock is unified onto source PTS, so the two are the same call. |
 | `setRate(_:)` | Clamped to `maxSupportedRate`; `0` pauses. The speed holds across pause and resume and across the host rebuilds a session makes on its own (reload at position, audio-track switch, AirPlay LAN swap, background return), and it belongs to the item: loading a different source, or `stop()`, returns to 1.0. Pitch-preserving on both decode routes: `audioTimePitchAlgorithm` is pinned to TimeDomain on the native player item and on the software path's audio renderer, so a speed control never has to be gated on which route a title took. |
-| `audioDelaySeconds`, `setAudioDelay(_:)` | Lip-sync correction for the viewer's chain, in seconds; positive presents audio later than video. Clamped to +/-2 s and, like `setRate`, it holds across the rebuilds a session makes on its own and belongs to the session. Applied where the engine still holds the timestamps: the stamped sample PTS on `.software`, the audio track of the fMP4 segments on `.loopback`. AVFoundation exposes no equivalent on either surface a host can reach, so on `.remoteBypass` and on audio-only sessions the value is kept for the next load and the no-op is logged rather than faked. Not free the way `setRate` is: the audio already decoded or already fetched is committed to the previous value and cannot be re-timed in place, so a change re-anchors at the playhead. On `.software` that is a seek to the current position; on `.loopback` it is the session-preserving reload, because seeking to the position AVPlayer already holds is a buffer hit and plays the old-offset segments out anyway. Measured on a 30 fps H.264 fixture: about 0.3 s of held picture on the loopback route, position preserved. A live session without a DVR window has no position to return to and takes the new value at the next seam it makes on its own. Presses arriving while a re-anchor is running are folded into it rather than stacking one re-anchor per press (AE#464 round 3), so a stepper held down converges on one rebuild instead of queueing a rebuild per press; the value does not ride the call, so the rebuild in flight delivers the newest one. A call landing while the session is being rebuilt at all is neither applied nor refused: it is kept in the options the load in flight reads, and says so. |
+| `audioDelaySeconds`, `setAudioDelay(_:)` | Lip-sync correction for the viewer's chain, in seconds; positive presents audio later than video. Clamped to +/-2 s and, like `setRate`, it holds across the rebuilds a session makes on its own and belongs to the session. Applied where the engine still holds the timestamps: the stamped sample PTS on `.software`, the audio track of the fMP4 segments on `.loopback`. AVFoundation exposes no equivalent on either surface a host can reach, so on `.remoteBypass` and on audio-only sessions the value is kept for the next load and the no-op is logged rather than faked. Not free the way `setRate` is: the audio already decoded or already fetched is committed to the previous value and cannot be re-timed in place, so a change re-anchors at the playhead. On `.software` that is a seek to the current position; on `.loopback` it is the session-preserving reload, because seeking to the position AVPlayer already holds is a buffer hit and plays the old-offset segments out anyway. Measured on a 30 fps H.264 fixture: about 0.3 s of held picture on the loopback route, position preserved. A live session without a DVR window has no position to return to and takes the new value at the next seam it makes on its own. Presses arriving while a re-anchor is running are folded into it rather than stacking one re-anchor per press (AE#464 round 3), and a press that lands after the in-flight re-anchor read the value gets exactly one catch-up pass; the value does not ride the call, so the rebuild in flight delivers the newest one. Presses at a human cadence arrive after a re-anchor has finished and are each their own. A re-anchor or a `reloadAtCurrentPosition(applying:)` raised the moment a previous rebuild returned, before the new host has published a position, rebuilds at the position that rebuild was mounted at, not at the head (round 5). A call landing while the session is being rebuilt at all is neither applied nor refused: it is kept in the options the load in flight reads, and says so. |
 | `maxSupportedRate` | 2.0 for video, 3.0 audio-only. Query after load; returns 2.0 while idle. Size a speed picker against it. |
 | `volume` | 0.0 to 1.0. A write before a session exists is remembered and applied at load. |
 | `selectTitle(id:)`, `selectChapter(id:)` | Disc titles and chapters. |
diff --git a/docs/cli.md b/docs/cli.md
index 55d5484a7..2e5f58548 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -226,6 +226,16 @@ rebuild window, where `videoRoute` is `.none` because there is no route to ask:
 cutting with the value, and now answers `set while the session is being rebuilt; the load in flight
 reads it from the options and delivers it`.
 
+Round 5 is two presses a re-anchor apart rather than inside one (`--switch-audio-delay 50@15000
+--switch-audio-delay 100@15060`, the band is 50 to 90 ms on an M1 against a 300 s H.264 + AAC fixture).
+The second press arrives after the first rebuild has returned and written `.playing` but before the new
+host has published a position, so before the fix it read the zero `load()` had written and rebuilt at
+the head: `#3 mount seek: item axis 0.00s`, `cutting seg0+`, on every run from 15050 to 15090. After
+it, `#3 mount seek: item axis 14.90s` and `cutting seg3+` on every run. The control is
+`--start-position 100 --seek-every 12 --seek-count 1 --seek-pattern 0 --switch-audio-delay 50@12450`:
+a seek retires the parked position, so the rebuild after a genuine seek to 0 still mounts at `0.00s`
+and not at the 100 s the load was handed.
+
 `play --live` without `--dvr-window` is the live-only shape, and it is the one that shows the re-anchor
 gate: `AE#464: audio delay = +150 ms stands, but this session cannot re-anchor at the playhead
 (state=playing, live=true); it arrives at the next seam`. With `--dvr-window 1800` the same run takes the

From d6db97cd5b6023e057608ac93962e577f43dc809 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 23 Sep 2026 11:58:50 +0200
Subject: [PATCH 012/359] fix(display): a master refused while the display is
 ineligible for HDR does not latch (AE#535)

An audio route death right after a display mode switch opens a window in which
the criteria readout reads matching=off hdrEligible=no. A session-preserving
reload that lands in it gets -11868 from AVPlayer, which is explained by the
window and says nothing about whether the output configuration accepts an HDR
master. The engine latched it anyway, so every later HDR title in the session
went media-direct, and in a process that never backgrounds the AE#588 clear
never came. Measured by cmcpherson274 on an Apple TV 4K (tvOS 26.6): three of
four such reloads latched, two in processes that never backgrounded.

The latch now also needs AVPlayer.eligibleForHDRPlayback to read true at the
refusal. The item still takes its media fallback either way, and the refusal
that is not latched says so in the log. This also makes the premise the AE#588
doc comment already stated ("the latch can only be set while eligible") true.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 Sources/AetherEngine/AetherEngine.swift       | 27 ++++++---
 .../Native/MasterFallbackDecision.swift       | 14 +++++
 ...Issue535RefusalNeedsEligibilityTests.swift | 56 +++++++++++++++++++
 3 files changed, 89 insertions(+), 8 deletions(-)
 create mode 100644 Tests/AetherEngineTests/Issue535RefusalNeedsEligibilityTests.swift

diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index 7769317ac..dc972cdc4 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -1418,9 +1418,10 @@ public final class AetherEngine: ObservableObject {
     /// where the per-title repetition it was built to prevent would have happened.
     ///
     /// Deliberately not keyed to a fingerprint of the display configuration, which would be more
-    /// precise: the latch can only be set while `eligibleForHDRPlayback` is true, so the capability
-    /// table at refusal time may be identical to the table afterwards, and a fingerprint built on that
-    /// assumption would hold the stale latch silently. The return needs no such assumption.
+    /// precise: the latch is only set while `eligibleForHDRPlayback` reads true (enforced since AE#535,
+    /// see `MasterFallbackDecision.shouldLatchPanelRefusal`), so the capability table at refusal time
+    /// may be identical to the table afterwards, and a fingerprint built on that would hold the stale
+    /// latch silently. The return needs no such assumption.
     nonisolated static func clearPanelRefusalOnForegroundReturn() {
         guard panelRefusedHDRMaster else { return }
         panelRefusedHDRMaster = false
@@ -2456,12 +2457,22 @@ public final class AetherEngine: ObservableObject {
         }
         masterFallbackUsed = true
         // AE#459: the display answered. Display-rejection codes only, never the -1002 parse failure.
+        // AE#535: and only while the display is eligible for HDR, or the answer is about the window.
         if MasterFallbackDecision.isDisplayRejectionCode(rejection.code), !Self.panelRefusedHDRMaster {
-            Self.panelRefusedHDRMaster = true
-            EngineLog.emit(
-                "[DisplayCriteria] panel refused an HDR master (code=\(rejection.code)); this process "
-                + "routes HDR sources media-direct until it restarts",
-                category: .engine)
+            let eligibleNow = AVPlayer.eligibleForHDRPlayback
+            if MasterFallbackDecision.shouldLatchPanelRefusal(
+                code: rejection.code, displayEligibleForHDRNow: eligibleNow) {
+                Self.panelRefusedHDRMaster = true
+                EngineLog.emit(
+                    "[DisplayCriteria] panel refused an HDR master (code=\(rejection.code)); this process "
+                    + "routes HDR sources media-direct until it returns from the background (#588)",
+                    category: .engine)
+            } else {
+                EngineLog.emit(
+                    "[DisplayCriteria] AE#535 HDR master refused (code=\(rejection.code)) while the display "
+                    + "reads hdrEligible=no; this item falls back, the process does not latch the refusal",
+                    category: .engine)
+            }
         }
         session.markServingMediaAfterFallback()
         nativeSubtitleRenditionsServed = false
diff --git a/Sources/AetherEngine/Native/MasterFallbackDecision.swift b/Sources/AetherEngine/Native/MasterFallbackDecision.swift
index 96a0246cd..0bb3ef810 100644
--- a/Sources/AetherEngine/Native/MasterFallbackDecision.swift
+++ b/Sources/AetherEngine/Native/MasterFallbackDecision.swift
@@ -29,6 +29,20 @@ enum MasterFallbackDecision {
         code == -11868 || code == -11848
     }
 
+    /// AE#535: whether a refusal teaches the process something about the panel.
+    ///
+    /// A display rejection answers "does this output configuration accept an HDR master" only while
+    /// the display is eligible for HDR at all. Measured on an Apple TV 4K on tvOS 26.6: an audio route
+    /// death right after a display mode switch opens a window in which the criteria readout reads
+    /// `matching=off hdrEligible=no`, a session-preserving reload lands in it, and AVPlayer fails the
+    /// master with -11868 because nothing HDR is compatible WITH AN INELIGIBLE DISPLAY. That refusal is
+    /// fully explained by the window, so it earns this item its media fallback and nothing more.
+    /// Latching it cost the rest of the viewing session its master, and in a process that never
+    /// backgrounds the AE#588 clear never came.
+    static func shouldLatchPanelRefusal(code: Int, displayEligibleForHDRNow: Bool) -> Bool {
+        isDisplayRejectionCode(code) && displayEligibleForHDRNow
+    }
+
     /// Any code that means "AVPlayer rejected the served master itself": the display-rejection pair
     /// plus NSURLErrorDomain -1002 "unsupported URL", which AVPlayer surfaces when it filters EVERY
     /// EXT-X-STREAM-INF out of the master at parse time and is left with no variant URL to load
diff --git a/Tests/AetherEngineTests/Issue535RefusalNeedsEligibilityTests.swift b/Tests/AetherEngineTests/Issue535RefusalNeedsEligibilityTests.swift
new file mode 100644
index 000000000..688ea64d1
--- /dev/null
+++ b/Tests/AetherEngineTests/Issue535RefusalNeedsEligibilityTests.swift
@@ -0,0 +1,56 @@
+import Foundation
+import Testing
+@testable import AetherEngine
+
+/// AE#535: a master refusal taken while the display is not eligible for HDR is not a fact about the panel.
+///
+/// Measured by cmcpherson274 on an Apple TV 4K (tvOS 26.6): an audio route death right after a display
+/// mode switch, a session-preserving reload landing 45 ms later with the readout at
+/// `matching=off hdrEligible=no`, and AVPlayer failing the master with -11868. Three of four such reloads
+/// latched `panelRefusedHDRMaster`, two of them in processes that never backgrounded, so the AE#588 clear
+/// never came and every later HDR title in the session played media-direct.
+struct Issue535RefusalNeedsEligibilityTests {
+
+    @Test("A display rejection while the display is ineligible for HDR does not latch")
+    func ineligibleWindowDoesNotLatch() {
+        #expect(!MasterFallbackDecision.shouldLatchPanelRefusal(code: -11868, displayEligibleForHDRNow: false))
+        #expect(!MasterFallbackDecision.shouldLatchPanelRefusal(code: -11848, displayEligibleForHDRNow: false))
+    }
+
+    @Test("A display rejection on an eligible display still latches")
+    func eligibleRefusalStillLatches() {
+        #expect(MasterFallbackDecision.shouldLatchPanelRefusal(code: -11868, displayEligibleForHDRNow: true))
+        #expect(MasterFallbackDecision.shouldLatchPanelRefusal(code: -11848, displayEligibleForHDRNow: true))
+    }
+
+    /// -1002 is a manifest filtered at parse time (#130), a statement about the playlist, never the display.
+    @Test("The parse-time rejection never latches, eligible or not")
+    func parseRejectionNeverLatches() {
+        #expect(!MasterFallbackDecision.shouldLatchPanelRefusal(code: -1002, displayEligibleForHDRNow: true))
+        #expect(!MasterFallbackDecision.shouldLatchPanelRefusal(code: -1002, displayEligibleForHDRNow: false))
+    }
+
+    /// The fallback itself is unaffected: the item still reloads the media playlist whatever the latch does.
+    @Test("An ineligible-window refusal still earns the item its media fallback")
+    func fallbackIsIndependentOfTheLatch() {
+        #expect(MasterFallbackDecision.shouldFallBackToMediaPlaylist(
+            errorCode: -11868, servingMasterPlaylist: true, alreadyFellBack: false))
+    }
+
+    /// A policy test cannot see the call site, so this one reads it: the latch is set only behind the gate.
+    @Test("The latch site asks the eligibility gate before setting the latch")
+    func latchSiteUsesTheGate() throws {
+        let source = URL(fileURLWithPath: #filePath)
+            .deletingLastPathComponent()
+            .deletingLastPathComponent()
+            .deletingLastPathComponent()
+            .appendingPathComponent("Sources/AetherEngine/AetherEngine.swift")
+        let text = try #require(try? String(contentsOf: source, encoding: .utf8))
+        let fn = try #require(text.range(of: "func fallBackToMediaPlaylist("))
+        let body = String(text[fn.lowerBound...].prefix(2500))
+        let gate = try #require(body.range(of: "shouldLatchPanelRefusal("))
+        let set = try #require(body.range(of: "Self.panelRefusedHDRMaster = true"))
+        #expect(gate.lowerBound < set.lowerBound)
+        #expect(body.contains("AVPlayer.eligibleForHDRPlayback"))
+    }
+}

From 51eb95fb174d2f75aabb7dd5384ccbdd25e57200 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 23 Sep 2026 13:06:14 +0200
Subject: [PATCH 013/359] fix(sw): HEVC packet coverage follows successors, and
 a full one forgets history (AE#613)

HEVC kept the strict pts + duration coverage, which tolerates no gap. A
Matroska file muxed with 41 ms durations against 41/42 ms deltas at 23.976
fps left a one-tick hole at every 42 ms step: 0.70 islands a frame, so the
frontier, bufferedPosition and the cached-seek eligibility all ended at the
next rounding hole. HEVC now takes the successor-timestamp model H.264
already used. Its reorder bound is FFmpeg's own: hevc/ps.c rejects
sps_max_num_reorder_pics above 15, inside the 32-timestamp queue.

Coverage keeps its history behind the playhead for backward cached seeks,
capped at 4096 ranges. A full coverage used to stop describing new packets
(duration model, insert returned false and nobody read it) or invalidate
itself (successor model), so every frontier after the cap was nil. It now
forgets the ranges wholly behind the playhead first; a backward cached seek
into forgotten history goes cold, which is correct.

Measured on a 4K HEVC Matroska fixture over an HTTP origin, aetherctl
--sw: buf 0.4 s ahead of the playhead before, 39.8 s after (the forward
window). Tests fail without each half and pass with it.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 CHANGELOG.md                                  |  11 +-
 .../Native/SoftwarePacketCoverage.swift       |   1 +
 .../Native/SoftwarePacketReadAhead.swift      |  36 +++-
 .../Native/SoftwarePlaybackHost.swift         |  14 +-
 .../Native/SoftwareVideoPacketCoverage.swift  |  22 ++-
 .../Issue613PacketCoverageTests.swift         | 160 ++++++++++++++++++
 docs/architecture.md                          |  15 +-
 7 files changed, 240 insertions(+), 19 deletions(-)
 create mode 100644 Tests/AetherEngineTests/Issue613PacketCoverageTests.swift

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 330d6fac0..2ed342fc5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,7 +10,16 @@ the public-API contract.
 
 ## [Unreleased]
 
-_Nothing yet._
+### Fixed
+
+- **The software VOD buffer frontier on HEVC, and after a long session (AE#613).** HEVC kept the
+  strict `pts + duration` packet coverage, so a Matroska file muxed with 41 ms durations against
+  41/42 ms deltas split it at every 42 ms step: `bufferedPosition` read about half a second ahead
+  of the playhead over a twenty-second reservoir, and cached seeks saw the same short frontier.
+  HEVC now takes the successor-timestamp model H.264 already used, under FFmpeg's own reorder
+  bound. Separately, a coverage that reached its 4096-range cap stopped describing new packets
+  (or, on the successor model, invalidated itself), so every frontier after the cap was nil; it
+  now forgets the ranges behind the playhead instead.
 
 ## [7.15.0] - 2026-09-23
 
diff --git a/Sources/AetherEngine/Native/SoftwarePacketCoverage.swift b/Sources/AetherEngine/Native/SoftwarePacketCoverage.swift
index 3c9b23ad2..bd1e2998c 100644
--- a/Sources/AetherEngine/Native/SoftwarePacketCoverage.swift
+++ b/Sources/AetherEngine/Native/SoftwarePacketCoverage.swift
@@ -20,6 +20,7 @@ struct SoftwarePacketCoverage: Sendable {
     }
 
     var rangeCount: Int { ranges.count }
+    var isFull: Bool { ranges.count >= maximumRangeCount }
 
     /// Adds [pts, pts + duration). Invalid or capacity-exceeding input leaves existing coverage
     /// unchanged. Rejecting a sparse extension is conservative: it never claims a missing packet.
diff --git a/Sources/AetherEngine/Native/SoftwarePacketReadAhead.swift b/Sources/AetherEngine/Native/SoftwarePacketReadAhead.swift
index 4a0a350d0..fa7a6ad8a 100644
--- a/Sources/AetherEngine/Native/SoftwarePacketReadAhead.swift
+++ b/Sources/AetherEngine/Native/SoftwarePacketReadAhead.swift
@@ -65,8 +65,8 @@ final class SoftwarePacketReadAhead: @unchecked Sendable {
     /// limit in force on material the coverage model cannot describe.
     private var storedVideoSeconds: Double?
     private var consumedVideoSeconds: Double?
-    private var videoCoverage = SoftwarePacketCoverage()
-    private var audioCoverage = SoftwarePacketCoverage()
+    private var videoCoverage: SoftwarePacketCoverage
+    private var audioCoverage: SoftwarePacketCoverage
     private var presentationCoverage: SoftwareVideoPacketCoverage?
     private struct Keyframe {
         let seconds: Double
@@ -79,6 +79,7 @@ final class SoftwarePacketReadAhead: @unchecked Sendable {
     init(video: Stream, audio: Stream?, byteBudget: Int, forwardSeconds: Double,
          initialSourceClock: Double, fifo: SoftwarePacketDiskFIFO,
          videoReorderDepth: Int? = nil,
+         coverageRangeCap: Int = 4096,
          beforeConsumerOperation: (@Sendable () -> Void)? = nil,
          readSource: @escaping @Sendable (@Sendable () -> Bool) throws -> SoftwareStoredPacket?) {
         self.video = video
@@ -87,9 +88,12 @@ final class SoftwarePacketReadAhead: @unchecked Sendable {
         self.forwardSeconds = max(1, forwardSeconds)
         self.sourceClock = initialSourceClock
         self.fifo = fifo
+        self.videoCoverage = SoftwarePacketCoverage(maximumRangeCount: coverageRangeCap)
+        self.audioCoverage = SoftwarePacketCoverage(maximumRangeCount: coverageRangeCap)
         self.presentationCoverage = videoReorderDepth.map {
             SoftwareVideoPacketCoverage(timeBaseNumerator: video.numerator,
-                timeBaseDenominator: video.denominator, reorderDepth: $0)
+                timeBaseDenominator: video.denominator, reorderDepth: $0,
+                maximumRangeCount: coverageRangeCap)
         }
         self.beforeConsumerOperation = beforeConsumerOperation
         self.readSource = readSource
@@ -368,6 +372,21 @@ final class SoftwarePacketReadAhead: @unchecked Sendable {
             video: videoEnd, audio: audioEnd, requiresAudio: audio != nil)
     }
 
+    /// The playhead in a stream's ticks, rounded down so a prune never reaches past it.
+    ///
+    /// #613: coverage keeps its history behind the playhead for backward cached seeks, so a long
+    /// session fills the range cap. A full coverage used to stop describing new packets (duration
+    /// model) or invalidate itself (successor model), which left every frontier after the cap nil.
+    /// Forgetting what lies wholly behind the playhead instead costs a backward cached seek into that
+    /// history, which then goes cold.
+    private func playheadTick(_ stream: Stream) -> Int64? {
+        guard stream.numerator > 0, stream.denominator > 0 else { return nil }
+        let ticks = (sourceClock * Double(stream.denominator) / Double(stream.numerator))
+            .rounded(.down)
+        guard ticks.isFinite, ticks > -9.0e18, ticks < 9.0e18 else { return nil }
+        return Int64(ticks)
+    }
+
     private func clearSourceMetadataLocked() {
         count = 0; bytes = 0; residentBytes = 0
         ended = false; failure = nil
@@ -466,8 +485,14 @@ final class SoftwarePacketReadAhead: @unchecked Sendable {
                         copyDiskStateLocked(state)
                         if packet.streamIndex == video.index {
                             if presentationCoverage != nil {
+                                if presentationCoverage?.isFull == true, let tick = playheadTick(video) {
+                                    presentationCoverage?.prune(before: tick)
+                                }
                                 presentationCoverage?.insert(pts: packet.pts)
                             } else {
+                                if videoCoverage.isFull, let tick = playheadTick(video) {
+                                    videoCoverage.prune(before: tick)
+                                }
                                 videoCoverage.insert(pts: packet.pts, duration: packet.duration)
                             }
                             if let seconds = videoSeconds(pts: packet.pts) { storedVideoSeconds = seconds }
@@ -477,7 +502,10 @@ final class SoftwarePacketReadAhead: @unchecked Sendable {
                                     keyframes.removeFirst(min(1024, keyframes.count))
                                 }
                             }
-                        } else if packet.streamIndex == audio?.index {
+                        } else if let audio, packet.streamIndex == audio.index {
+                            if audioCoverage.isFull, let tick = playheadTick(audio) {
+                                audioCoverage.prune(before: tick)
+                            }
                             audioCoverage.insert(pts: packet.pts, duration: packet.duration)
                         }
                     }
diff --git a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
index 5592fb111..d4553fff9 100644
--- a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
+++ b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
@@ -11,6 +11,18 @@ import AetherLibavutil
 /// Intentionally skips EAC3+JOC and DV HDMI handshake (AV1 sources rarely carry Atmos or DV).
 @MainActor
 final class SoftwarePlaybackHost {
+    /// Codecs whose presentation reordering has an established bound get the read-ahead's
+    /// successor-PTS coverage; every other codec keeps strict packet-duration coverage. HEVC's bound
+    /// is FFmpeg's own: `sps_max_num_reorder_pics > HEVC_MAX_DPB_SIZE - 1` (15) is rejected
+    /// (n8.1.2 hevc/ps.c:1397-1403), inside the 32-timestamp queue. On the duration model a Matroska
+    /// file muxed with 41 ms durations against 41/42 ms deltas split at every 42 ms step (#613).
+    nonisolated static func presentationReorderDepth(codecID: UInt32) -> Int? {
+        switch codecID {
+        case AV_CODEC_ID_H264.rawValue, AV_CODEC_ID_HEVC.rawValue: return 32
+        default: return nil
+        }
+    }
+
 
     // MARK: - Published state (mirrors NativeAVPlayerHost surface)
 
@@ -945,7 +957,7 @@ final class SoftwarePlaybackHost {
                           denominator: $0.pointee.time_base.den)
                 } : nil
             let initialSourceClock = initialClockTime.seconds
-            let videoReorderDepth: Int? = vCodecID == AV_CODEC_ID_H264.rawValue ? 32 : nil
+            let videoReorderDepth = Self.presentationReorderDepth(codecID: vCodecID)
             let cacheResult = await Task.detached(priority: .utility) { () throws -> SoftwarePacketReadAhead? in
                 let temp = URL(fileURLWithPath: NSTemporaryDirectory(), isDirectory: true)
                 let available = (try? temp.resourceValues(forKeys: [.volumeAvailableCapacityKey]))?
diff --git a/Sources/AetherEngine/Native/SoftwareVideoPacketCoverage.swift b/Sources/AetherEngine/Native/SoftwareVideoPacketCoverage.swift
index b09b9fa59..136b77b1a 100644
--- a/Sources/AetherEngine/Native/SoftwareVideoPacketCoverage.swift
+++ b/Sources/AetherEngine/Native/SoftwareVideoPacketCoverage.swift
@@ -1,24 +1,27 @@
 import Foundation
 
-/// H.264 compressed-packet presentation coverage matching the renderer's successor-PTS duration.
+/// H.264 and HEVC compressed-packet presentation coverage matching the renderer's successor-PTS
+/// duration.
 ///
 /// AVPacket.duration may describe decode cadence rather than how long a variable-rate picture is
 /// displayed. The renderer holds a picture until its presentation-order successor (positive gaps
 /// up to one second). This model publishes only those successor intervals, without rewriting any
 /// packet timestamp or duration. A larger gap remains a discontinuity, not a tolerance to bridge.
 ///
-/// H.264-only caller contract: complete selected-stream packets, with valid presentation timestamps,
+/// H.264/HEVC caller contract: complete selected-stream packets, with valid presentation timestamps,
 /// enter in demux/decode order after they are retained in the packet store. FFmpeg n8.1.2 h264_ps.c
-/// rejects num_reorder_frames > 16; the default holds 32 distinct timestamps as a conservative
-/// field-picture margin. That codec picture bound does NOT prove arbitrary container PTS obey the
-/// bound. A timestamp behind the emitted watermark therefore invalidates all coverage until reset.
-/// Source: https://github.com/FFmpeg/FFmpeg/blob/n8.1.2/libavcodec/h264_ps.c#L174-L180
+/// rejects num_reorder_frames > 16 and hevc/ps.c rejects sps_max_num_reorder_pics > 15; the default
+/// holds 32 distinct timestamps as a conservative field-picture margin. That codec picture bound
+/// does NOT prove arbitrary container PTS obey the bound. A timestamp behind the emitted watermark
+/// therefore invalidates all coverage until reset.
+/// Sources: https://github.com/FFmpeg/FFmpeg/blob/n8.1.2/libavcodec/h264_ps.c#L174-L180
+/// https://github.com/FFmpeg/FFmpeg/blob/n8.1.2/libavcodec/hevc/ps.c#L1397-L1403
 ///
 /// This metadata-only value neither owns packets nor synchronizes access. The owner must reset it
 /// together with its packet store on seek/flush/discard. Other codecs must keep their strict packet
 /// duration coverage unless their presentation reordering has a separately established bound.
 struct SoftwareVideoPacketCoverage: Sendable {
-    private var coverage = SoftwarePacketCoverage()
+    private var coverage: SoftwarePacketCoverage
     private var pending: [Int64] = []
     private var emittedPTS: Int64?
     private let timeBaseNumerator: Int32
@@ -30,7 +33,9 @@ struct SoftwareVideoPacketCoverage: Sendable {
     private(set) var lateTimestampCount = 0
     private(set) var isFinished = false
 
-    init(timeBaseNumerator: Int32, timeBaseDenominator: Int32, reorderDepth: Int = 32) {
+    init(timeBaseNumerator: Int32, timeBaseDenominator: Int32, reorderDepth: Int = 32,
+         maximumRangeCount: Int = 4096) {
+        coverage = SoftwarePacketCoverage(maximumRangeCount: maximumRangeCount)
         self.timeBaseNumerator = timeBaseNumerator
         self.timeBaseDenominator = timeBaseDenominator
         self.reorderDepth = min(32, max(1, reorderDepth))
@@ -41,6 +46,7 @@ struct SoftwareVideoPacketCoverage: Sendable {
 
     var pendingCount: Int { pending.count }
     var rangeCount: Int { coverage.rangeCount }
+    var isFull: Bool { coverage.isFull }
 
     /// Duration/DTS are deliberately not inputs. Duplicate pending PTS do not advance the reorder
     /// watermark. At most depth + 1 timestamps are held transiently, then the minimum is emitted.
diff --git a/Tests/AetherEngineTests/Issue613PacketCoverageTests.swift b/Tests/AetherEngineTests/Issue613PacketCoverageTests.swift
new file mode 100644
index 000000000..21b440d98
--- /dev/null
+++ b/Tests/AetherEngineTests/Issue613PacketCoverageTests.swift
@@ -0,0 +1,160 @@
+import Foundation
+import AetherLibavcodec
+import Testing
+@testable import AetherEngine
+
+/// #613, found while answering #592: the software VOD read-ahead's packet coverage broke in two
+/// ways that both leave the frontier describing less than the store holds.
+///
+/// HEVC kept the strict `pts + duration` model, and a Matroska file muxed with 41 ms durations
+/// against 41/42 ms deltas opens a one-tick hole at every 42 ms step: 0.70 islands a frame,
+/// `bufferedPosition` stuck at the end of the current island. And a coverage that reached its range
+/// cap stopped describing new packets (plain) or invalidated itself (successor model) instead of
+/// forgetting the history behind the playhead.
+@Suite("Software VOD packet coverage (#613)")
+struct Issue613PacketCoverageTests {
+
+    private static let tickRate: Int32 = 1000
+
+    /// 23.976 fps on a 1/1000 time base, the fixture's own timestamps: PTS rounded to the
+    /// millisecond, every duration 41, so each 42 ms delta leaves a one-tick hole.
+    private static func fragmentedPTS(_ index: Int) -> Int64 {
+        Int64((Double(index) * 1000 * 1001 / 24000).rounded())
+    }
+
+    private static func packet(pts: Int64, duration: Int64 = 41) -> SoftwareStoredPacket {
+        SoftwareStoredPacket(pts: pts, dts: pts, duration: duration, position: 0,
+                             streamIndex: 0, flags: 0x1, timeBaseNumerator: 1,
+                             timeBaseDenominator: Self.tickRate,
+                             bytes: Data(repeating: 7, count: 100), sideData: [])
+    }
+
+    private final class Counter: @unchecked Sendable {
+        private let lock = NSLock()
+        private var count = 0
+        func next() -> Int { lock.lock(); defer { lock.unlock() }; count += 1; return count }
+    }
+
+    private func makeReadAhead(
+        root: URL, reorderDepth: Int?, forwardSeconds: Double, rangeCap: Int = 4096,
+        pts: @escaping @Sendable (Int) -> Int64
+    ) throws -> SoftwarePacketReadAhead {
+        let counter = Counter()
+        let fifo = try SoftwarePacketDiskFIFO(chunkTargetBytes: 64 * 1024, retainConsumed: true,
+                                              parentDirectory: root)
+        return SoftwarePacketReadAhead(
+            video: .init(index: 0, numerator: 1, denominator: Self.tickRate), audio: nil,
+            byteBudget: 50_000_000, forwardSeconds: forwardSeconds, initialSourceClock: 0,
+            fifo: fifo, videoReorderDepth: reorderDepth, coverageRangeCap: rangeCap
+        ) { _ in Self.packet(pts: pts(counter.next() - 1)) }
+    }
+
+    private func withRoot<T>(_ body: (URL) throws -> T) throws -> T {
+        let root = FileManager.default.temporaryDirectory
+            .appendingPathComponent("issue613-\(UUID().uuidString)", isDirectory: true)
+        try FileManager.default.createDirectory(at: root, withIntermediateDirectories: true)
+        defer { try? FileManager.default.removeItem(at: root) }
+        return try body(root)
+    }
+
+    /// Waits for the producer to park, read as a packet count that stops moving.
+    private func waitForPark(_ source: SoftwarePacketReadAhead) {
+        let deadline = Date().addingTimeInterval(10)
+        var previous = -1
+        while Date() < deadline {
+            Thread.sleep(forTimeInterval: 0.15)
+            let now = source.snapshot.packetCount
+            if now == previous, now > 0 { return }
+            previous = now
+        }
+    }
+
+    // MARK: - 1. HEVC gets the successor model
+
+    /// The bound that lets HEVC in: FFmpeg rejects more than 15 reorder pictures, inside the
+    /// 32-timestamp queue. Codecs without an established bound keep the strict model.
+    @Test("H.264 and HEVC take the successor model, other codecs keep the duration model")
+    func reorderDepthByCodec() {
+        #expect(SoftwarePlaybackHost.presentationReorderDepth(
+            codecID: AV_CODEC_ID_H264.rawValue) == 32)
+        #expect(SoftwarePlaybackHost.presentationReorderDepth(
+            codecID: AV_CODEC_ID_HEVC.rawValue) == 32)
+        for other in [AV_CODEC_ID_AV1, AV_CODEC_ID_VP9, AV_CODEC_ID_MPEG2VIDEO, AV_CODEC_ID_VC1] {
+            #expect(SoftwarePlaybackHost.presentationReorderDepth(codecID: other.rawValue) == nil)
+        }
+    }
+
+    /// The reported shape. On the duration model the frontier ends at the first rounding hole, 41 ms
+    /// in; on the successor model it reaches what the producer stored before it parked.
+    @Test("Rounded durations do not fragment the successor model")
+    func roundedDurationsStayOneIsland() throws {
+        try withRoot { root in
+            let strict = try makeReadAhead(root: root, reorderDepth: nil, forwardSeconds: 10,
+                                           pts: Self.fragmentedPTS)
+            strict.start()
+            waitForPark(strict)
+            let strictFrontier = strict.snapshot.frontier
+            strict.close()
+
+            let successor = try makeReadAhead(root: root, reorderDepth: 32, forwardSeconds: 10,
+                                              pts: Self.fragmentedPTS)
+            successor.start()
+            waitForPark(successor)
+            let successorFrontier = successor.snapshot.frontier
+            successor.close()
+
+            #expect((strictFrontier ?? 0) < 0.05, "the premise: the duration model splits at 41 ms")
+            // Ten seconds stored, less the 32 timestamps the reorder queue holds back (1.33 s).
+            #expect((successorFrontier ?? 0) > 8, "the frontier must reach the store, not the first hole")
+        }
+    }
+
+    // MARK: - 2. A full coverage forgets history instead of freezing
+
+    /// Consumes `count` packets, moving the playhead onto each, and answers the frontier at the end.
+    /// Every read waits for 40 stored packets first, the way a real consumer trails the producer:
+    /// the successor model describes a picture only once 32 later timestamps have arrived, so a
+    /// consumer that drains the store as fast as it fills sees no coverage at all.
+    private func frontierAfterConsuming(_ count: Int, source: SoftwarePacketReadAhead) throws -> Double? {
+        source.start()
+        for _ in 0..<count {
+            let deadline = Date().addingTimeInterval(5)
+            while source.snapshot.packetCount < 40, Date() < deadline {
+                Thread.sleep(forTimeInterval: 0.001)
+            }
+            guard let packet = try source.read() else { break }
+            source.updatePlayhead(Double(packet.pts) / Double(Self.tickRate))
+        }
+        return source.snapshot.frontier
+    }
+
+    /// Duration model at a cap of 64 ranges: 400 fragmented packets are about 280 islands. Before
+    /// the fix the coverage stopped at the sixty-fourth and the playhead left it behind. The cap has
+    /// to hold what lies AHEAD of the playhead, about 34 islands in a two-second window here, as
+    /// 4096 holds a forty-second one in a session.
+    @Test("A full duration-model coverage keeps describing new packets")
+    func fullDurationCoverageKeepsUp() throws {
+        try withRoot { root in
+            let source = try makeReadAhead(root: root, reorderDepth: nil, forwardSeconds: 2,
+                                           rangeCap: 64, pts: Self.fragmentedPTS)
+            defer { source.close() }
+            #expect(try frontierAfterConsuming(400, source: source) != nil)
+        }
+    }
+
+    /// Successor model at a cap of 16: a two-second jump every fifth picture is a real
+    /// discontinuity and opens an island each time. Before the fix the seventeenth one invalidated
+    /// the whole model until the next seek. 403 packets leave the playhead on the third picture of
+    /// a group: the fifth one's hold ends at the jump and is deliberately uncovered.
+    @Test("A full successor-model coverage keeps describing new packets")
+    func fullSuccessorCoverageKeepsUp() throws {
+        try withRoot { root in
+            let source = try makeReadAhead(root: root, reorderDepth: 32, forwardSeconds: 30,
+                                           rangeCap: 16) { index in
+                Int64(index) * 40 + Int64(index / 5) * 2000
+            }
+            defer { source.close() }
+            #expect(try frontierAfterConsuming(403, source: source) != nil)
+        }
+    }
+}
diff --git a/docs/architecture.md b/docs/architecture.md
index 6c6ee1d7c..9a79f1afe 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -190,12 +190,17 @@ Runtime cache corruption is a reported playback failure, not silently skipped da
 
 The cache frontier is the intersection of selected audio and video presentation
 coverage containing the playhead. Unknown intervals remain unknown; byte counts
-are not converted to guessed seconds. H.264 uses a bounded presentation reorder
-queue and confirmed successor timestamps, because a VFR packet's decode duration
-can be shorter than the picture's actual display hold. Larger discontinuities,
+are not converted to guessed seconds. H.264 and HEVC use a bounded presentation
+reorder queue and confirmed successor timestamps, because a VFR packet's decode
+duration can be shorter than the picture's actual display hold, and a container
+that rounds durations down (41 ms against 41/42 ms deltas at 23.976 fps) would
+otherwise split the coverage at every frame (#613). Larger discontinuities,
 invalid or unexpectedly late timestamps invalidate or split coverage. Other
-codecs retain strict packet-duration coverage. Without a proven compressed
-frontier, the existing decoded-cushion fallback still applies.
+codecs retain strict packet-duration coverage. Coverage keeps its history behind
+the playhead for backward cached seeks, up to 4096 ranges per stream; a full
+coverage forgets the ranges wholly behind the playhead rather than stop
+describing new packets. Without a proven compressed frontier, the existing
+decoded-cushion fallback still applies.
 
 A cached seek restores a retained keyframe cursor, including an earlier keyframe
 for available preroll, and keeps the producer at its existing source frontier.

From 4782d39e3b1b0862358deac15fc1d88e84e3dfd8 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 23 Sep 2026 13:51:03 +0200
Subject: [PATCH 014/359] fix(aetherctl): Release builds again, the stallclock
 drill is DEBUG-only (AE#610)

The AE#549 stallclock drill called stallRendererClockForTesting() and
rendererClockRateForTesting unguarded, and both live inside #if DEBUG, so
`swift build -c release` failed at every tag from 7.6.0 to 7.14.0. The
library products were never affected and aetherctl is not a product.

Guard both call sites; a Release binary prints that the drill needs a
DEBUG build and ends with the existing inconclusive verdict. CI builds
aetherctl in Release so the gap cannot reopen unnoticed.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 .github/workflows/ci.yml            |  6 ++++++
 Sources/aetherctl/PlaybackCmd.swift | 12 +++++++++++-
 docs/cli.md                         |  2 +-
 3 files changed, 18 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index a71db99b9..6a554ddbc 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -31,6 +31,12 @@ jobs:
       - name: swift build
         run: swift build
 
+      # Every other Swift step here is Debug, and aetherctl is not a product, so no consumer compiles
+      # it either: a DEBUG-only engine hook called without a guard kept Release broken from 7.6.0 to
+      # 7.14.0 without anything noticing (AE#610).
+      - name: swift build -c release (aetherctl)
+        run: swift build -c release --product aetherctl
+
       # A test process that dies mid-run reads as exit 1 with no ✘, no backtrace and no swift-testing
       # summary: `swift test` collapses every abnormal child exit to a plain 1, and a signal takes the
       # buffered tail of the event stream with it. What was in flight is whatever the log still lists
diff --git a/Sources/aetherctl/PlaybackCmd.swift b/Sources/aetherctl/PlaybackCmd.swift
index 68e301068..5b0461fcb 100644
--- a/Sources/aetherctl/PlaybackCmd.swift
+++ b/Sources/aetherctl/PlaybackCmd.swift
@@ -1098,16 +1098,26 @@ private func playSmokeTest(url: URL, seconds: Double, live: Bool, forceSoftware:
         // staged on macOS; its outcome can.
         if hostCalls.contains("stallclock") {
             if tick == 4 {
+                #if DEBUG
                 stallClockStalled = engine.stallRendererClockForTesting()
                 stallClockAtStall = engine.currentTime
                 print(String(format: "  HOSTCALL AE#549 stopped the master clock behind the host's back at %.2f%@",
                              engine.currentTime,
                              stallClockStalled ? "" : " -- NO renderer clock on this backend"))
+                #else
+                print("  HOSTCALL stallclock needs a DEBUG build (its engine hooks are compiled out of Release): "
+                      + "swift build --product aetherctl")
+                #endif
             }
             if tick == 6 { stallClockBeforeResume = engine.currentTime }
             if tick == 7 {
+                #if DEBUG
+                let stalledRate = engine.rendererClockRateForTesting ?? -1
+                #else
+                let stalledRate: Float = -1
+                #endif
                 print(String(format: "  HOSTCALL play() on the stalled clock (playhead %.2f, rate %.2f)",
-                             engine.currentTime, engine.rendererClockRateForTesting ?? -1))
+                             engine.currentTime, stalledRate))
                 engine.play()
             }
             if tick >= 9 { stallClockAtEnd = engine.currentTime }
diff --git a/docs/cli.md b/docs/cli.md
index 2e5f58548..820eab224 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -140,7 +140,7 @@ the same clock as `FIRSTFRAME`. The 1 Hz tick samples the phase, which is far to
 signal apart from the moment the rate rolls; a healthy native join is exactly two edges, `loading` at the
 load and `playing` at the roll (AE#440).
 
-`--subs <codec-or-lang>` matches against the track's libavcodec name or language and logs every overlay cue and cue trim as it lands. `--host-calls` replays host post-load behavior against the fresh session: `play`, `extractor` (`makeFrameExtractor`), `setrate` (`setRate(1.0)`), `pausestart` (Sodalite#104 round 4: `pause()` the instant load returns, before any frame exists, and `play()` at t=8; the shape of a host that holds a fresh load paused, and a software session used to answer it with eight ticks of `enq=+0 status=unknown r4d=n`, a black picture under a paused clock; now the `[SWHost] #104` lines show the first frame presented at a stopped clock and `startup 8/8 presenting` arrives while paused), `ratehold` (set 1.5, pause at tick 3, resume at tick 5, then read the rate back off the transport itself: the #436 drill, and it fails the run if the resume came back at 1.0), `reloadlive` (reload the URL on the live path when the probe flags it live, the AetherPlayer Open URL flow), `seekback` (rewind 20 s into the DVR window at t=15, return to the live edge at t=30), `overlapseek` (the #292 seek-window drills below), `pausehold` (Sodalite#104: pause at t=10 and HOLD until ten seconds before the end, printing the playhead, the edge and the resident depth every second, which is how a session paused for longer than its own DVR window is measured without waiting out a real one: pair it with `--dvr-window 30` and `--seconds 90` and the ninety minute question becomes a ninety second run), `still` (#544: asks for a scrub still at three aims, 20 s behind the playhead at t=15, 5 s behind at t=20 and at the edge at t=25, writing each to `/tmp/aetherctl-still-<tick>.png` and reporting hit or MISS with the decode time; pair it with `--sw --dvr-window N`, where the picture comes out of the DVR packet ring rather than a segment cache, and read the FILE as well as the count, because the bundled seed burns its own second into the frame so a still asked for 14.85 s showing `14` is the verdict that it decoded the right moment and not merely an image; exit 6 when nothing hit, 5 when the session ended before the first aim; on a VOD session (AE#605) the three aims are 10.5 s behind the playhead, 4.5 s ahead of it and 600 s past it, through `scrubThumbnail`, and the third is EXPECTED to miss, because a frame the cache does not hold yet must not be answered with the one before it: `--sw` against an HTTP source is the software packet-cache case, and the testsrc fixture's counter in the PNG is the verdict that the still decoded to the target rather than snapping to its keyframe), `stallclock` (AE#549: stop the master clock at t=4 behind the host's back, the way an interrupted audio session does, then call a plain `play()` at t=7 and read whether the playhead moves again; the interruption itself cannot be staged on macOS, its outcome can, and without the `RendererClockResume` branch the run ends with the clock standing exactly where the stall left it, which is the field log's shape), and `pauseseek` (pause at t=12, seek at t=15 while paused, resume at t=20; with `--sw` the five paused ticks between landing and resume show what the `[SWDiag]` line reports while the pump is parked and has not heard of the seek, the AE#479 shape); this is how the pre-arming `setRate` wedge was isolated.
+`--subs <codec-or-lang>` matches against the track's libavcodec name or language and logs every overlay cue and cue trim as it lands. `--host-calls` replays host post-load behavior against the fresh session: `play`, `extractor` (`makeFrameExtractor`), `setrate` (`setRate(1.0)`), `pausestart` (Sodalite#104 round 4: `pause()` the instant load returns, before any frame exists, and `play()` at t=8; the shape of a host that holds a fresh load paused, and a software session used to answer it with eight ticks of `enq=+0 status=unknown r4d=n`, a black picture under a paused clock; now the `[SWHost] #104` lines show the first frame presented at a stopped clock and `startup 8/8 presenting` arrives while paused), `ratehold` (set 1.5, pause at tick 3, resume at tick 5, then read the rate back off the transport itself: the #436 drill, and it fails the run if the resume came back at 1.0), `reloadlive` (reload the URL on the live path when the probe flags it live, the AetherPlayer Open URL flow), `seekback` (rewind 20 s into the DVR window at t=15, return to the live edge at t=30), `overlapseek` (the #292 seek-window drills below), `pausehold` (Sodalite#104: pause at t=10 and HOLD until ten seconds before the end, printing the playhead, the edge and the resident depth every second, which is how a session paused for longer than its own DVR window is measured without waiting out a real one: pair it with `--dvr-window 30` and `--seconds 90` and the ninety minute question becomes a ninety second run), `still` (#544: asks for a scrub still at three aims, 20 s behind the playhead at t=15, 5 s behind at t=20 and at the edge at t=25, writing each to `/tmp/aetherctl-still-<tick>.png` and reporting hit or MISS with the decode time; pair it with `--sw --dvr-window N`, where the picture comes out of the DVR packet ring rather than a segment cache, and read the FILE as well as the count, because the bundled seed burns its own second into the frame so a still asked for 14.85 s showing `14` is the verdict that it decoded the right moment and not merely an image; exit 6 when nothing hit, 5 when the session ended before the first aim; on a VOD session (AE#605) the three aims are 10.5 s behind the playhead, 4.5 s ahead of it and 600 s past it, through `scrubThumbnail`, and the third is EXPECTED to miss, because a frame the cache does not hold yet must not be answered with the one before it: `--sw` against an HTTP source is the software packet-cache case, and the testsrc fixture's counter in the PNG is the verdict that the still decoded to the target rather than snapping to its keyframe), `stallclock` (AE#549: stop the master clock at t=4 behind the host's back, the way an interrupted audio session does, then call a plain `play()` at t=7 and read whether the playhead moves again; the interruption itself cannot be staged on macOS, its outcome can, and without the `RendererClockResume` branch the run ends with the clock standing exactly where the stall left it, which is the field log's shape; the drill drives DEBUG-only engine hooks, so a Release `aetherctl` prints a notice and ends inconclusive, build it with `swift build --product aetherctl`), and `pauseseek` (pause at t=12, seek at t=15 while paused, resume at t=20; with `--sw` the five paused ticks between landing and resume show what the `[SWDiag]` line reports while the pump is parked and has not heard of the seek, the AE#479 shape); this is how the pre-arming `setRate` wedge was isolated.
 
 `--seek-every N` seeks once every N ticks past tick 10, walking `--seek-pattern <abs,abs,...>` if one is given (a short backward hop otherwise), and `--seek-count K` stops after K seeks so a run can be a BURST and then play. Both halves are needed for anything about what a seek sequence leaves behind: the burst puts the store in the state under test, and only the playing half shows what the overlay carries through it. That pairing is what made AE#362's second mechanism reproducible (a hole between a restarted pump and the island the previous run left ahead of it, decoded across and then never re-read).
 

From b93f9c4b9937874dc12fee2824ea3327a05b84e3 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 23 Sep 2026 14:47:00 +0200
Subject: [PATCH 015/359] chore(release): prep 7.15.1 - HEVC frontier,
 eligibility-gated latch, rebuild playhead, Release aetherctl

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 CHANGELOG.md                                  | 20 +++++++++++++++++++
 Examples/README.md                            |  2 +-
 README.md                                     |  6 +++---
 .../AetherEngine/AetherEngine+Version.swift   |  2 +-
 4 files changed, 25 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2ed342fc5..781f6df36 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,10 @@ the public-API contract.
 
 ## [Unreleased]
 
+_Nothing yet._
+
+## [7.15.1] - 2026-09-23
+
 ### Fixed
 
 - **The software VOD buffer frontier on HEVC, and after a long session (AE#613).** HEVC kept the
@@ -20,6 +24,22 @@ the public-API contract.
   bound. Separately, a coverage that reached its 4096-range cap stopped describing new packets
   (or, on the successor model, invalidated itself), so every frontier after the cap was nil; it
   now forgets the ranges behind the playhead instead.
+- **A master refused while the display is ineligible for HDR no longer latches (AE#535).** An
+  audio route death right after a display mode switch opens a window in which the criteria readout
+  reads `hdrEligible=no`. A session-preserving reload that landed in it got -11868 from AVPlayer
+  and latched `panelRefusedHDRMaster`, so every later HDR title in the session went media-direct.
+  The latch now also needs `AVPlayer.eligibleForHDRPlayback` to read true at the refusal; the item
+  still takes its media fallback either way, and a refusal that is not latched says so in the log.
+- **An audio-delay rebuild raised the moment one returned keeps the playhead (AE#464).**
+  `rebuildPosition` honoured the parked position only while `state == .loading`, but `load()`'s
+  autostart writes `.playing` before the new host publishes a position, so for about 50 ms the
+  clock still read zero and a correction in that window rebuilt the session at its head. A
+  playable session whose clock reads exactly the reset zero now answers with the parked position;
+  an accepted seek retires it, so a genuine seek to 0 is never overridden.
+- **`aetherctl` builds in Release again (AE#610).** The stallclock drill called two DEBUG-only test
+  hooks unguarded, so `swift build -c release` failed from 7.6.0 through 7.15.0. The library
+  products were never affected. A Release binary now reports that the drill needs a DEBUG build,
+  and CI builds `aetherctl` in Release.
 
 ## [7.15.0] - 2026-09-23
 
diff --git a/Examples/README.md b/Examples/README.md
index 0b96226d3..641e7853b 100644
--- a/Examples/README.md
+++ b/Examples/README.md
@@ -18,7 +18,7 @@ Three samples covering different audiences:
    ```
    https://github.com/superuser404notfound/AetherEngine
    ```
-   Dependency Rule: Up to Next Major Version, starting from `7.15.0`. Add the `AetherEngine` library product to your app target.
+   Dependency Rule: Up to Next Major Version, starting from `7.15.1`. Add the `AetherEngine` library product to your app target.
 
 3. **Drop the file in.** Replace the Xcode template's default `App.swift` (or whatever the generated `@main` file is called) with the contents of [`MinimalPlayerApp.swift`](MinimalPlayer/MinimalPlayerApp.swift). The file is self-contained: it defines both the `@main App` struct and the `ContentView`.
 
diff --git a/README.md b/README.md
index 1b9cc0a1b..e94916fa1 100644
--- a/README.md
+++ b/README.md
@@ -343,7 +343,7 @@ Subtitle cues land in raw source PTS; render the overlay against `player.sourceT
 Install via Swift Package Manager:
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.15.0")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.15.1")
 ```
 
 Three samples ship in `Examples/`:
@@ -590,10 +590,10 @@ Browse all of this as a searchable site at **[aetherengine.superuser404.de](http
 AetherEngine uses [Semantic Versioning](https://semver.org). The public API surface, every `public` declaration in `Sources/AetherEngine/`, is the stability contract. **Major** removes / renames public symbols or breaks adopters; **Minor** adds public API or codec / format support; **Patch** fixes bugs with no public API change. `internal` types are not part of the contract.
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.15.0")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.15.1")
 ```
 
-Pin to `.upToNextMinor(from: "7.15.0")` for stricter teams that prefer to opt into minor bumps explicitly.
+Pin to `.upToNextMinor(from: "7.15.1")` for stricter teams that prefer to opt into minor bumps explicitly.
 
 ## Requirements
 
diff --git a/Sources/AetherEngine/AetherEngine+Version.swift b/Sources/AetherEngine/AetherEngine+Version.swift
index c41a0ccb4..46843df9c 100644
--- a/Sources/AetherEngine/AetherEngine+Version.swift
+++ b/Sources/AetherEngine/AetherEngine+Version.swift
@@ -11,5 +11,5 @@ extension AetherEngine {
     ///
     /// Between releases, and in a consumer that pins an unreleased commit for a device test, this
     /// names the last PUBLISHED version the checkout descends from, not every patch in it.
-    public nonisolated static let version = "7.15.0"
+    public nonisolated static let version = "7.15.1"
 }

From 19a222fea07bcabcc9096e9e9a576a5332f29a1f Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 24 Sep 2026 05:47:04 +0200
Subject: [PATCH 016/359] fix(remote-hls): sourceTime follows the presented
 frame, measured off the injected renditions (AE#616)

On the nativeRemoteHLS bypass sourceTime was AVPlayer's item time. An origin
whose playlist places a segment at its slot while the segment starts at the
keyframe before it (a Jellyfin transcode restarted with -noaccurate_seek
-copyts) makes item time lead the picture, 1.1 to 8.3 s in the report.

The #316 WebVTT renditions are placed by media timestamp, so each line reaches
a legible output at cue start plus that lead. A non-suppressing legible output
on the bypass item matches presented lines back to the cues the engine wrote
and publishes sourceTime as item time less the measured lead. currentTime and
seek(to:) stay on item time. Without an injected rendition selected nothing is
measured and sourceTime stays item time, which the docs now say.

Verified with aetherctl --picture-probe on a local fMP4 HLS whose playlist sits
1.5 s after its tfdt: capErr -1.46 s before the first line, one frame after it,
and through a seek.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 .../AetherEngine/AetherEngine+Loading.swift   |  35 +++++-
 Sources/AetherEngine/AetherEngine.swift       |  11 ++
 .../Native/NativeAVPlayerHost.swift           |   2 +
 .../Native/RemoteHLSCueClock.swift            |  95 ++++++++++++++++
 .../Native/RemoteHLSCueClockObserver.swift    |  72 +++++++++++++
 .../Native/RemoteHLSSubtitleProvider.swift    |  13 ++-
 Sources/AetherEngine/PlaybackClock.swift      |   6 ++
 Sources/AetherEngine/PlayerState.swift        |  12 ++-
 .../RemoteHLSCueClockTests.swift              | 101 ++++++++++++++++++
 docs/api.md                                   |  19 +++-
 10 files changed, 358 insertions(+), 8 deletions(-)
 create mode 100644 Sources/AetherEngine/Native/RemoteHLSCueClock.swift
 create mode 100644 Sources/AetherEngine/Native/RemoteHLSCueClockObserver.swift
 create mode 100644 Tests/AetherEngineTests/RemoteHLSCueClockTests.swift

diff --git a/Sources/AetherEngine/AetherEngine+Loading.swift b/Sources/AetherEngine/AetherEngine+Loading.swift
index 4aa0dc7a8..387113274 100644
--- a/Sources/AetherEngine/AetherEngine+Loading.swift
+++ b/Sources/AetherEngine/AetherEngine+Loading.swift
@@ -90,7 +90,8 @@ extension AetherEngine {
     /// hold-vs-settle decision is unit-testable without driving a live AVPlayer.
     func applySeekFinalizeSourceTime(target: Double, bufferingTowardTarget: Bool) {
         if Self.seekLandingSettlesToTarget(bufferingTowardTarget: bufferingTowardTarget) {
-            clock.sourceTime = target
+            // AE#616: zero except on a remote-HLS bypass whose item time leads its frames.
+            clock.sourceTime = max(0, target - remoteHLSItemOffset)
         }
     }
 
@@ -362,6 +363,7 @@ extension AetherEngine {
         applyDesiredRate(to: host)
         // No loopback producer; playhead is the raw AVPlayer clock. Shift stays 0.
         self.playlistShiftSeconds = 0
+        detachRemoteHLSCueClock()
         self.setPresentationAxis(PresentationAxisMap())
         if currentAVPlayer !== host.avPlayer {
             self.currentAVPlayer = host.avPlayer
@@ -381,10 +383,12 @@ extension AetherEngine {
             .store(in: &nativeCancellables)
         host.$renderedTime
             .sink { [weak self] value in
-                self?.clock.sourceTime = value
+                guard let self else { return }
+                // AE#616: item time, less what the injected renditions measured it leads the picture by.
+                self.clock.sourceTime = max(0, value - self.remoteHLSItemOffset)
                 // Feed the playhead mirror the remote-HLS audio tap (#95) reads off its ingest task;
                 // shift 0 on this path, so the rendered position is the source-PTS playhead.
-                self?.renderedPositionMirror.set(value)
+                self.renderedPositionMirror.set(value)
             }
             .store(in: &nativeCancellables)
         // #168: mirror the item's parsed dynamic range into the published format AND program the panel.
@@ -539,6 +543,8 @@ extension AetherEngine {
                       // AVFoundation builds no track, where nothing terminal is ever published.
                       readinessDeadline: RemoteHLSReadinessDeadline.defaultBudgetSeconds))
 
+        attachRemoteHLSCueClock(host: host, expectedGeneration: bypassGeneration)
+
         // AE#154: surface the item's legible AVMediaSelectionGroup as `subtitleTracks` so hosts with
         // their own picker see the external WebVTT renditions AVPlayer renders on this bypass.
         // Selection routes back through `selectSubtitleTrack(index:)` / `clearSubtitle()`.
@@ -554,6 +560,29 @@ extension AetherEngine {
         // No startLiveTelemetrySampler: all sampler counters read the loopback pipeline (demuxer / producer / cache / server), none of which exists on this bypass.
     }
 
+    /// AE#616: on this bypass `sourceTime` would otherwise be item time, which an origin that restarts
+    /// its transcode at the keyframe before a slot puts ahead of the picture. The engine wrote the
+    /// injected renditions, so it can match what AVPlayer presents back to the cue and read the offset.
+    /// Without injected renditions nothing is measurable and `sourceTime` stays item time.
+    private func attachRemoteHLSCueClock(host: NativeAVPlayerHost, expectedGeneration: UInt64) {
+        detachRemoteHLSCueClock()
+        guard let provider = remoteHLSSubtitleProxy?.provider,
+              let item = host.currentPlayerItem else { return }
+        remoteHLSCueClock = RemoteHLSCueClockObserver(item: item, provider: provider) { [weak self] offset in
+            guard let self, self.loadGeneration == expectedGeneration else { return }
+            self.remoteHLSItemOffset = offset
+            if let rendered = self.nativeHost?.renderedTime {
+                self.clock.sourceTime = max(0, rendered - offset)
+            }
+        }
+    }
+
+    func detachRemoteHLSCueClock() {
+        remoteHLSCueClock?.detach()
+        remoteHLSCueClock = nil
+        remoteHLSItemOffset = 0
+    }
+
     /// Stand a loopback origin in front of the remote master and return the URL AVPlayer should open.
     /// Nil means "play the origin directly", which is the answer for a live source, and for a session
     /// with neither text sidecars to inject (#316) nor a trust evaluator to honor (AE#495).
diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index dc972cdc4..b514a18d8 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -2165,6 +2165,14 @@ public final class AetherEngine: ObservableObject {
     /// every live source, every source without declared sidecars, and every refused rewrite.
     var remoteHLSSubtitleProxy: RemoteHLSSubtitleProxy.Prepared?
 
+    /// AE#616: measures how far AVPlayer's item time leads the presented frame on the bypass, off the
+    /// injected renditions. Nil whenever `remoteHLSSubtitleProxy` serves none.
+    var remoteHLSCueClock: RemoteHLSCueClockObserver?
+
+    /// AE#616: the last offset `remoteHLSCueClock` measured, subtracted from item time to publish
+    /// `sourceTime`. Zero on every other path and until the first injected line is presented.
+    var remoteHLSItemOffset: Double = 0
+
     /// #316: external track id -> the NAME its injected rendition carries in the served master. Selecting
     /// one of these must drive AVMediaSelection, not the sidecar overlay, or the two draw on top of
     /// each other. Empty when no proxy is standing.
@@ -3737,6 +3745,7 @@ public final class AetherEngine: ObservableObject {
         remoteHLSSubtitleProxy?.tearDown()   // #316
         remoteHLSSubtitleProxy = nil
         injectedSubtitleRenditionNames = [:]
+        detachRemoteHLSCueClock()   // AE#616
         stallRecoveryWindowUntil = .distantPast
         stallRecoveryReasserts = 0
         stallReengageTask?.cancel()
@@ -5789,6 +5798,7 @@ public final class AetherEngine: ObservableObject {
         remoteHLSSubtitleProxy?.tearDown()
         remoteHLSSubtitleProxy = nil
         injectedSubtitleRenditionNames = [:]
+        detachRemoteHLSCueClock()   // AE#616
         // Font attachments are session-scoped but must survive stopInternal (audio-track-switch skips the probe;
         // clearing in stopInternal would leave the session with an empty font list after any audio switch).
         fontAttachments = []
@@ -7066,6 +7076,7 @@ public final class AetherEngine: ObservableObject {
         remoteHLSSubtitleProxy?.tearDown()
         remoteHLSSubtitleProxy = nil
         injectedSubtitleRenditionNames = [:]
+        detachRemoteHLSCueClock()   // AE#616
         EngineLog.emit(
             "[AetherEngine] #597 background teardown: remote-HLS subtitle proxy released",
             category: .engine)
diff --git a/Sources/AetherEngine/Native/NativeAVPlayerHost.swift b/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
index cb4bb23b8..192125bc1 100644
--- a/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
+++ b/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
@@ -222,6 +222,8 @@ final class NativeAVPlayerHost {
     // MARK: - Private state
 
     private var playerItem: AVPlayerItem?
+    /// AE#616: the item the latest `load` attached, for an output the engine hangs on it.
+    var currentPlayerItem: AVPlayerItem? { playerItem }
     /// Applied immediately and replayed onto fresh items across internal reloads so Now Playing title/artwork survives audio-switch/background-reopen seams.
     private var pendingExternalMetadata: [AVMetadataItem] = []
     private var timeObserver: Any?
diff --git a/Sources/AetherEngine/Native/RemoteHLSCueClock.swift b/Sources/AetherEngine/Native/RemoteHLSCueClock.swift
new file mode 100644
index 000000000..33accd549
--- /dev/null
+++ b/Sources/AetherEngine/Native/RemoteHLSCueClock.swift
@@ -0,0 +1,95 @@
+import Foundation
+
+/// AE#616: the offset between AVPlayer's item time and the media timestamps of what it presents, on the
+/// `nativeRemoteHLS` bypass, measured off the #316 renditions the engine injected itself.
+///
+/// A server that restarts a transcode at the keyframe before a segment's slot (Jellyfin: `-ss <slot>
+/// -noaccurate_seek -copyts`) serves a first segment whose `tfdt` lies before the slot its playlist
+/// promises. AVPlayer anchors its item timeline to the first segment it loads after a seek, so item
+/// time then leads the displayed frame by that gap, 1 to 8 s measured, different on every seek, and
+/// the anchor survives later job restarts. Nothing on the bypass sees a segment, so the gap cannot be
+/// read where it arises.
+///
+/// The injected WebVTT is placed by media timestamp, so each cue reaches the legible output at
+/// `item = cue.start + offset`. Matching the presented text back to the cue the engine wrote gives the
+/// offset, and it re-measures on every line. Pure so the matching is testable without an item.
+struct RemoteHLSCueClock {
+
+    /// Offsets outside this band are a different line with the same text, not a measurement. The gap
+    /// is at most one keyframe interval in the seek direction; the band is wide on purpose.
+    static let plausibleOffsets: ClosedRange<Double> = -2.0...30.0
+
+    /// Item seconds minus media seconds of the presented frame. Nil until the first line is matched.
+    private(set) var offset: Double?
+
+    private var startsByText: [String: [Double]] = [:]
+    private var presented: Set<String> = []
+    /// The first delivery after a time jump reports whatever is active at the landing, stamped with
+    /// the landing time rather than the cue's start, so it teaches nothing.
+    private var skipNextDelivery = true
+
+    var hasCues: Bool { !startsByText.isEmpty }
+
+    mutating func setCues(_ cues: [(start: Double, text: String)]) {
+        var index: [String: [Double]] = [:]
+        for cue in cues {
+            let key = Self.normalize(cue.text)
+            guard !key.isEmpty else { continue }
+            index[key, default: []].append(cue.start)
+        }
+        startsByText = index
+    }
+
+    /// A seek or an item change: the anchor may move, and the next delivery is a landing.
+    mutating func noteTimeJump() {
+        presented = []
+        skipNextDelivery = true
+    }
+
+    /// Feed one legible-output delivery. Returns the new offset when this delivery measured one.
+    mutating func observe(strings: [String], itemTime: Double) -> Double? {
+        let now = Set(strings.map(Self.normalize).filter { !$0.isEmpty })
+        let appeared = now.subtracting(presented)
+        presented = now
+        if skipNextDelivery {
+            skipNextDelivery = false
+            return nil
+        }
+        // A cue ending changes the set without starting anything; only an appearing line is stamped
+        // with its own start.
+        guard !appeared.isEmpty else { return nil }
+
+        var unique: Double?
+        var ambiguous: [Double] = []
+        for text in appeared {
+            let candidates = (startsByText[text] ?? [])
+                .map { itemTime - $0 }
+                .filter { Self.plausibleOffsets.contains($0) }
+            if candidates.count == 1 {
+                unique = candidates[0]
+                break
+            }
+            ambiguous.append(contentsOf: candidates)
+        }
+        let reference = offset ?? 0
+        guard let measured = unique ?? ambiguous.min(by: { abs($0 - reference) < abs($1 - reference) })
+        else { return nil }
+        offset = measured
+        return measured
+    }
+
+    /// What the legible output hands back, reduced to what the served `.vtt` said: the rendition's
+    /// text went through `MovTextSampleBuilder.sanitize`, and AVPlayer drops the WebVTT markup and may
+    /// re-break lines.
+    static func normalize(_ text: String) -> String {
+        var s = MovTextSampleBuilder.sanitize(text)
+        while let open = s.firstIndex(of: "<"), let close = s[open...].firstIndex(of: ">") {
+            s.removeSubrange(open...close)
+        }
+        s = s.replacingOccurrences(of: "&lt;", with: "<")
+            .replacingOccurrences(of: "&gt;", with: ">")
+            .replacingOccurrences(of: "&nbsp;", with: " ")
+            .replacingOccurrences(of: "&amp;", with: "&")
+        return s.split(whereSeparator: { $0.isWhitespace || $0.isNewline }).joined(separator: " ")
+    }
+}
diff --git a/Sources/AetherEngine/Native/RemoteHLSCueClockObserver.swift b/Sources/AetherEngine/Native/RemoteHLSCueClockObserver.swift
new file mode 100644
index 000000000..ce88a58ae
--- /dev/null
+++ b/Sources/AetherEngine/Native/RemoteHLSCueClockObserver.swift
@@ -0,0 +1,72 @@
+import AVFoundation
+
+/// AE#616: feeds `RemoteHLSCueClock` from a legible output on the bypass item.
+///
+/// The output never suppresses player rendering. A host that draws AVPlayer's renditions keeps them, a
+/// host with its own suppressing output keeps that, and the frozen-line trap (an output that starts
+/// suppressing while a line is on screen leaves it there for good) cannot be triggered from here.
+/// AVPlayer only delivers the selected legible option, so this measures exactly while one of the
+/// injected renditions is selected and is silent otherwise.
+@MainActor
+final class RemoteHLSCueClockObserver: NSObject, AVPlayerItemLegibleOutputPushDelegate {
+
+    private let output = AVPlayerItemLegibleOutput()
+    private weak var item: AVPlayerItem?
+    private let provider: RemoteHLSSubtitleProvider
+    private var clock = RemoteHLSCueClock()
+    private var jumpObserver: NSObjectProtocol?
+    private let onOffset: @MainActor (Double) -> Void
+
+    init(item: AVPlayerItem, provider: RemoteHLSSubtitleProvider, onOffset: @escaping @MainActor (Double) -> Void) {
+        self.item = item
+        self.provider = provider
+        self.onOffset = onOffset
+        super.init()
+        output.suppressesPlayerRendering = false
+        output.advanceIntervalForDelegateInvocation = 0
+        output.setDelegate(self, queue: .main)
+        item.add(output)
+        jumpObserver = NotificationCenter.default.addObserver(
+            forName: AVPlayerItem.timeJumpedNotification, object: item, queue: .main
+        ) { [weak self] _ in
+            MainActor.assumeIsolated { self?.clock.noteTimeJump() }
+        }
+    }
+
+    func detach() {
+        if let jumpObserver { NotificationCenter.default.removeObserver(jumpObserver) }
+        jumpObserver = nil
+        output.setDelegate(nil, queue: nil)
+        item?.remove(output)
+        item = nil
+    }
+
+    nonisolated func legibleOutput(_ output: AVPlayerItemLegibleOutput,
+                                   didOutputAttributedStrings strings: [NSAttributedString],
+                                   nativeSampleBuffers nativeSamples: [Any],
+                                   forItemTime itemTime: CMTime) {
+        let texts = strings.map(\.string)
+        let seconds = itemTime.seconds
+        guard seconds.isFinite else { return }
+        MainActor.assumeIsolated { self.deliver(texts: texts, itemTime: seconds) }
+    }
+
+    private func deliver(texts: [String], itemTime: Double) {
+        // The fill runs from mount; a line can be presented before it finished. Index once it has.
+        if !clock.hasCues, provider.isFillFinished {
+            clock.setCues(provider.allCueStarts())
+        }
+        guard clock.hasCues else { return }
+        let previous = clock.offset
+        guard let offset = clock.observe(strings: texts, itemTime: itemTime) else { return }
+        if previous == nil || abs(offset - (previous ?? 0)) >= 0.05 {
+            EngineLog.emit(
+                "[AetherEngine] AE#616: item time leads the presented frame by "
+                + "\(String(format: "%.3f", offset))s (was "
+                + (previous.map { String(format: "%.3f", $0) } ?? "unmeasured")
+                + "), measured at item \(String(format: "%.3f", itemTime))s",
+                category: .engine)
+        }
+        onOffset(offset)
+    }
+}
diff --git a/Sources/AetherEngine/Native/RemoteHLSSubtitleProvider.swift b/Sources/AetherEngine/Native/RemoteHLSSubtitleProvider.swift
index e504451ac..b61daf988 100644
--- a/Sources/AetherEngine/Native/RemoteHLSSubtitleProvider.swift
+++ b/Sources/AetherEngine/Native/RemoteHLSSubtitleProvider.swift
@@ -102,6 +102,14 @@ final class RemoteHLSSubtitleProvider: HLSSegmentProvider, @unchecked Sendable {
         await currentFillTask()?.value
     }
 
+    /// AE#616: every sidecar's decode has finished, so `allCueStarts()` is the whole program.
+    var isFillFinished: Bool { stores.allSatisfy(\.isFinished) }
+
+    /// AE#616: cue starts and texts across every injected rendition, on the axis the `.vtt` serves.
+    func allCueStarts() -> [(start: Double, text: String)] {
+        stores.flatMap { $0.allCues().map { (start: $0.start, text: $0.text) } }
+    }
+
     /// Reading the handle stays synchronous: `NSLock` is unavailable from an async context.
     private func currentFillTask() -> Task<Void, Never>? {
         fillLock.lock()
@@ -159,8 +167,9 @@ final class RemoteHLSSubtitleProvider: HLSSegmentProvider, @unchecked Sendable {
     var nativeSubtitleRenditions: [(ordinal: Int, language: String?, name: String, isForced: Bool)] { [] }
 
     /// Whole-program WebVTT for one sidecar. Cue times are used verbatim: this bypass has no loopback
-    /// producer and therefore no playlist shift, and the origin's VOD timeline starts at zero, so the
-    /// sidecar's own absolute seconds already are the item axis.
+    /// producer and therefore no playlist shift, and AVPlayer places the cues by media timestamp, so
+    /// the sidecar's own absolute seconds line up with the frames. They do NOT line up with item time
+    /// where an origin's segments start before their playlist slot; AE#616 measures that gap off them.
     func nativeSubtitleVTT(ordinal: Int, segmentIndex: Int) -> String? {
         guard ordinal >= 0, ordinal < stores.count else { return nil }
         let store = stores[ordinal]
diff --git a/Sources/AetherEngine/PlaybackClock.swift b/Sources/AetherEngine/PlaybackClock.swift
index b40ff7b1e..5b1b6feea 100644
--- a/Sources/AetherEngine/PlaybackClock.swift
+++ b/Sources/AetherEngine/PlaybackClock.swift
@@ -11,6 +11,12 @@ public final class PlaybackClock: ObservableObject {
     @Published public internal(set) var currentTime: Double = 0
 
     /// Source PTS of the currently displayed frame. On native: rides AVPlayer's rendered position -- equals `currentTime` in steady play, but holds the on-screen frame during a seek or rebuffer, not the scrub target (issue #49). SW/audio: always equals `currentTime`.
+    ///
+    /// `nativeRemoteHLS` (AE#616): item time, less the lead over the picture the engine measured on its
+    /// own injected subtitle renditions (#316). The lead exists where an origin restarts a transcode at the
+    /// keyframe before a segment's slot, and is re-measured on every presented line, so it differs from
+    /// `currentTime` by that lead. With no injected rendition selected there is nothing to measure it
+    /// against, and this is item time, which can run ahead of the frame after a seek on such an origin.
     @Published public internal(set) var sourceTime: Double = 0
 
     @Published public internal(set) var progress: Float = 0
diff --git a/Sources/AetherEngine/PlayerState.swift b/Sources/AetherEngine/PlayerState.swift
index 85da59183..97f87772b 100644
--- a/Sources/AetherEngine/PlayerState.swift
+++ b/Sources/AetherEngine/PlayerState.swift
@@ -605,7 +605,17 @@ public struct LoadOptions: Sendable, Equatable {
     /// from wherever the source can still serve, so a host that turns this off owns the eviction case too.
     public var clampsLiveResumeToWindow: Bool = true
 
-    /// AVPlayer item from the remote URL directly (Jellyfin live `master.m3u8`): no demuxer probe, no loopback. AVPlayer manages live edge / reconnect. Pair with `isLive: true`. Default `false`.
+    /// AVPlayer item from the remote URL directly: no demuxer probe, no loopback. AVPlayer manages live
+    /// edge / reconnect. Built for live (`isLive: true`, Jellyfin live `master.m3u8`); a remote HLS VOD
+    /// URL lands here too, whatever this says, because the loopback path reroutes it (AE#154). Default
+    /// `false`.
+    ///
+    /// On this route the clock is AVPlayer's item time, and that is not always the media time of the
+    /// frame on screen (AE#616). An origin whose playlist places a segment at its slot while the segment
+    /// starts at the keyframe before it (a Jellyfin transcode restarted by a seek) makes item time lead
+    /// the picture by that gap. `clock.sourceTime` subtracts the gap while one of the renditions the
+    /// engine injects for `LoadOptions.externalSubtitles` (#316) is selected and presenting; without one
+    /// it is item time. `clock.currentTime` and `seek(to:)` stay on item time either way.
     public var nativeRemoteHLS: Bool
 
     /// Reroute a live `nativeRemoteHLS` session onto the loopback live-ingest path when AVPlayer reaches
diff --git a/Tests/AetherEngineTests/RemoteHLSCueClockTests.swift b/Tests/AetherEngineTests/RemoteHLSCueClockTests.swift
new file mode 100644
index 000000000..5bace755f
--- /dev/null
+++ b/Tests/AetherEngineTests/RemoteHLSCueClockTests.swift
@@ -0,0 +1,101 @@
+import Testing
+import Foundation
+@testable import AetherEngine
+
+/// AE#616: on `nativeRemoteHLS`, a Jellyfin transcode restarted at the keyframe before a slot makes
+/// AVPlayer's item time lead the picture. The injected #316 renditions are placed by media timestamp,
+/// so a line presented at item time T whose cue starts at S measures the lead T - S. Values are the
+/// reporter's measurements (seg 494: slot 1483.482, keyframe 1482.272, lead 1.209).
+struct RemoteHLSCueClockTests {
+
+    private func clock(_ cues: [(Double, String)]) -> RemoteHLSCueClock {
+        var clock = RemoteHLSCueClock()
+        clock.setCues(cues.map { (start: $0.0, text: $0.1) })
+        clock.noteTimeJump()
+        // The landing delivery after the jump teaches nothing by design.
+        _ = clock.observe(strings: [], itemTime: 0)
+        return clock
+    }
+
+    @Test("A presented line measures item time minus its cue start")
+    func measuresLead() throws {
+        var c = clock([(1490.0, "Where were you?"), (1493.5, "Out.")])
+        let measured = c.observe(strings: ["Where were you?"], itemTime: 1491.209)
+        let lead = try #require(measured)
+        #expect(abs(lead - 1.209) < 1e-9)
+        #expect(c.offset == lead)
+    }
+
+    @Test("Each new line re-measures, so a seek that moved the anchor is corrected on the next line")
+    func remeasuresAfterSeek() throws {
+        var c = clock([(1490.0, "Where were you?"), (1800.0, "Run.")])
+        _ = c.observe(strings: ["Where were you?"], itemTime: 1491.209)
+        c.noteTimeJump()
+        _ = c.observe(strings: [], itemTime: 1790.0)
+        let measured = c.observe(strings: ["Run."], itemTime: 1803.086)
+        let lead = try #require(measured)
+        #expect(abs(lead - 3.086) < 1e-9)
+    }
+
+    @Test("The delivery at a seek landing is skipped: a line active there is stamped with the landing, not its start")
+    func skipsLandingDelivery() {
+        var c = RemoteHLSCueClock()
+        c.setCues([(start: 100.0, text: "Long line")])
+        c.noteTimeJump()
+        let measured = c.observe(strings: ["Long line"], itemTime: 103.5)
+        #expect(measured == nil)
+        #expect(c.offset == nil)
+    }
+
+    @Test("A line ending measures nothing; the survivor was stamped when it appeared")
+    func endingLineMeasuresNothing() {
+        var c = clock([(10.0, "A"), (11.0, "B")])
+        _ = c.observe(strings: ["A"], itemTime: 12.0)
+        _ = c.observe(strings: ["A", "B"], itemTime: 13.0)
+        let measured = c.observe(strings: ["B"], itemTime: 14.0)
+        #expect(measured == nil)
+        #expect(c.offset == 2.0)
+    }
+
+    @Test("Repeated text resolves to the start nearest the current lead")
+    func repeatedTextPicksNearestToCurrentLead() throws {
+        var c = clock([(20.0, "First"), (100.0, "Yeah."), (104.0, "Yeah.")])
+        _ = c.observe(strings: ["First"], itemTime: 23.0)   // lead 3
+        _ = c.observe(strings: [], itemTime: 24.0)
+        // Candidates 107 - 100 = 7 and 107 - 104 = 3; the current lead is 3.
+        let measured = c.observe(strings: ["Yeah."], itemTime: 107.0)
+        let lead = try #require(measured)
+        #expect(lead == 3.0)
+    }
+
+    @Test("A text with one plausible start wins over an ambiguous sibling in the same delivery")
+    func uniqueCandidateWins() throws {
+        var c = clock([(50.0, "Yeah."), (56.5, "Yeah."), (52.0, "Only once")])
+        let measured = c.observe(strings: ["Yeah.", "Only once"], itemTime: 57.5)
+        let lead = try #require(measured)
+        #expect(lead == 5.5)
+    }
+
+    @Test("A match outside the plausible band is a different line, not a measurement")
+    func implausibleMatchIgnored() {
+        var c = clock([(10.0, "Hello")])
+        let measured = c.observe(strings: ["Hello"], itemTime: 500.0)
+        #expect(measured == nil)
+        #expect(c.offset == nil)
+    }
+
+    @Test("Text AVPlayer hands back matches the sanitized cue the .vtt carried")
+    func normalizationMatchesServedText() throws {
+        var c = clock([(30.0, "{\\an8}Line one\\Nline  two")])
+        let measured = c.observe(strings: ["<i>Line one</i>\nline two"], itemTime: 31.25)
+        let lead = try #require(measured)
+        #expect(lead == 1.25)
+    }
+
+    @Test("Unknown text measures nothing")
+    func unknownText() {
+        var c = clock([(30.0, "Known")])
+        let measured = c.observe(strings: ["Origin's own rendition"], itemTime: 31.0)
+        #expect(measured == nil)
+    }
+}
diff --git a/docs/api.md b/docs/api.md
index fb113b0c8..58b832dc5 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -533,7 +533,7 @@ Time lives on `player.clock`, a separate `ObservableObject`, so ~10 Hz ticks nev
 | Symbol | Axis |
 | --- | --- |
 | `clock.$currentTime` | playback clock, the scrubber axis |
-| `clock.$sourceTime` | source PTS of the displayed frame; render subtitle overlays against this |
+| `clock.$sourceTime` | source PTS of the displayed frame; render subtitle overlays against this. On `nativeRemoteHLS` it is item time, corrected by the lead over the picture the engine measures on its injected #316 renditions while one is selected (AE#616); see below the table. |
 | `clock.$progress` | `currentTime / duration` |
 | `clock.$bufferedPosition` | source-axis position buffered ahead |
 | `clock.$liveEdgeTime`, `clock.$seekableLiveRange`, `clock.$behindLiveSeconds`, `clock.$isAtLiveEdge` | live-window surfaces. `seekableLiveRange` is the intersection of the DVR window (policy) and what the segment cache actually holds and can play forward from (fact), so it is honest to scale a rewind strip on and `seek(to:)` clamps to the same floor (AE#441). The two diverge for the whole first `dvrWindowSeconds` of a session and again whenever retention evicts faster than the window slides. Software live sessions have no such cache and keep the arithmetic bound. |
@@ -541,6 +541,21 @@ Time lives on `player.clock`, a separate `ObservableObject`, so ~10 Hz ticks nev
 | `player.currentTime`, `sourceTime`, `progress`, `bufferedPosition`, `liveEdgeTime`, `seekableLiveRange`, `behindLiveSeconds`, `isAtLiveEdge` | non-published mirrors of the same values for one-shot reads |
 | `$duration` | seconds; a `LoadOptions.declaredDurationSeconds` outranks the container's |
 
+**`sourceTime` on `nativeRemoteHLS` (AE#616).** The engine sees no segment on that route, so the clock is
+AVPlayer's item time. An origin whose playlist places a segment at its slot while the segment starts at
+the keyframe before it (a Jellyfin transcode restarted by `-ss <slot> -noaccurate_seek -copyts`) makes
+item time lead the frame on screen, by a different amount after every seek: 1.1 s to 8.3 s measured, and
+AVPlayer keeps the anchor of the first segment it loaded after the seek. The WebVTT renditions the
+engine injects for `LoadOptions.externalSubtitles` are placed by media timestamp, so each line reaches
+AVPlayer's legible output at its cue start plus that lead. The engine watches its own renditions with a
+non-suppressing legible output, matches each presented line back to the cue it wrote, and publishes
+`sourceTime` as item time less the measured lead (log line `AE#616: item time leads the presented
+frame by ...`). It re-measures on every line; between a seek and the next line it keeps the previous
+value. Without an injected rendition selected nothing is measured and `sourceTime` is item time.
+`currentTime`, `seek(to:)` and the scrubber stay on item time throughout, so a seek round-trips. A host
+drawing its own overlay from `sourceTime` (libass) can keep the rendition selected behind its own
+suppressing `AVPlayerItemLegibleOutput` to keep the measurement running.
+
 ## What the session is doing
 
 | Symbol | Reading |
@@ -899,7 +914,7 @@ All flags default to safe values; the table is the full set. Depth for the media
 | `clampsLiveResumeToWindow` | true | Whether `play()` may move a behind-live playhead by itself (edge snap on a live-only source more than 45 s behind, or a landing above the retained floor when a DVR window has slid past it). `false` hands the whole decision to the host, which then also owns the eviction case. |
 | `liveJoinStartsImmediately` | true | Cuts AVPlayer's stall-avoidance wait short once at the live join, over a buffer that is non-empty and at least 1.5 s deep. The join tail no host can otherwise reach; default since 6.55.0 on a device A/B, see the live-join section. |
 | `liveBlockingReload` | nil (auto) | LL-HLS blocking-reload override for loopback live sessions. Auto derives eligibility from observed upstream cadence, which is what keeps a bursty relay off a `-15410` loop. |
-| `nativeRemoteHLS` | false | Hand a remote `master.m3u8` straight to AVPlayer: no demuxer probe, no loopback. Pair with `isLive: true`. |
+| `nativeRemoteHLS` | false | Hand a remote `master.m3u8` straight to AVPlayer: no demuxer probe, no loopback. Built for `isLive: true`; a remote HLS VOD URL reaches this route regardless (AE#154). The clock here is item time, see `clock.$sourceTime` (AE#616). |
 | `nativeRemoteHLSIngestFallback` | true | The #168 / #293 carriage recovery and the #363 401/403 bypass refusal recovery. Setting it false turns both off. |
 | `audioOnly` | false | Lean audio pipeline, no video machinery. Also set automatically when the probe finds no video stream. |
 | `audioBridgeMode` | `.surroundCompat` | Bridge encoder for codecs that cannot stream-copy into fMP4. `.surroundCompat` uses EAC3 for a source with more than two channels and FLAC for one with two or fewer (no surround to carry). `.lossless` uses FLAC up to 7.1 throughout and needs a sink that accepts multichannel LPCM. |

From 6887a2b7d34778238c3b05f129b6de5934ddcfdf Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 24 Sep 2026 08:45:10 +0200
Subject: [PATCH 017/359] perf(sw): the stored packet envelope is a header and
 the bytes, not a property list (AE#592)

Every compressed packet on the software VOD route is encoded into the
read-ahead spool. PropertyListEncoder's binary format uniques every object
through a Set, so each packet's whole payload went through Hasher.combine
on the way in. In a release profile of a 91.6 Mbit/s 4K HEVC session that
was the largest active frame outside the decoder: 204 of 1583 active
samples inside SoftwareStoredPacket.encoded(), 203 of them in the hasher.

The envelope is now a fixed little-endian header (version, the eight
scalars, side data count, payload count), the payload, and each side data
entry as type, count and bytes. The spool lives only for its session, so
the version byte carries no compatibility promise. decode throws on an
unknown version, on truncation and on trailing bytes, and a slice decodes
like the whole buffer.

Measured on an M1 Air against Scripts/slowrange.py (1 Gbit/s, 20 ms), one
FFmpeg-muxed 4K HEVC + AC-3 5.1 fixture at 91.6 Mbit/s, process CPU over
seconds 20 to 110 of a 120 s --sw session, release aetherctl, arms
alternated:

  7.15.1   0.220 / 0.223 / 0.222 cores
  this     0.205 / 0.207 / 0.208 cores   (-0.015, -6.8 %)

No rebuffer and aLead >= 3.98 s on every run of both arms. The encode
subtree fell from 204 to 2 samples and Hasher from 203 to 0. The envelope
benchmark in Issue592PacketEnvelopeTests reads 375 -> 43 us per 425 KB
packet to encode and 22 -> 18 us to decode.

New tests pin the exact envelope size, truncation, a foreign version,
trailing bytes and slice decoding. The standalone AVPacket check asserted
the bplist00 magic and now asserts the version byte and the exact size.
3380 swift-testing and 629 XCTest tests green, the three software packet
scripts PASS.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 .../SoftwareStoredPacketStandalone.swift      |   4 +-
 .../Native/SoftwareStoredPacket.swift         | 101 ++++++++++++++++--
 .../Issue592PacketEnvelopeTests.swift         |  37 +++++++
 3 files changed, 135 insertions(+), 7 deletions(-)

diff --git a/Scripts/tests/SoftwareStoredPacketStandalone.swift b/Scripts/tests/SoftwareStoredPacketStandalone.swift
index 8dba719a0..5a9b93c53 100644
--- a/Scripts/tests/SoftwareStoredPacketStandalone.swift
+++ b/Scripts/tests/SoftwareStoredPacketStandalone.swift
@@ -85,7 +85,9 @@ struct SoftwareStoredPacketTests {
             )
             precondition(stored == expected)
             let encoded = try stored.encoded()
-            precondition(encoded.starts(with: Data("bplist00".utf8)))
+            precondition(encoded.first == SoftwareStoredPacket.version)
+            precondition(encoded.count == SoftwareStoredPacket.headerBytes + bytes.count
+                + sideData.reduce(0) { $0 + SoftwareStoredPacket.sideDataHeaderBytes + $1.1.count })
             let decoded = try SoftwareStoredPacket.decode(encoded)
             precondition(decoded == expected)
             let restored = try decoded.makeAVPacket()
diff --git a/Sources/AetherEngine/Native/SoftwareStoredPacket.swift b/Sources/AetherEngine/Native/SoftwareStoredPacket.swift
index 0a8c57a7d..4b5bc4a8a 100644
--- a/Sources/AetherEngine/Native/SoftwareStoredPacket.swift
+++ b/Sources/AetherEngine/Native/SoftwareStoredPacket.swift
@@ -2,8 +2,8 @@ import Foundation
 
 /// Lossless packet envelope for the software VOD read-ahead store. No decoded pixels or
 /// source URL is retained. In particular DTS, duration and side data must survive a cache hit.
-struct SoftwareStoredPacket: Codable, Sendable, Equatable {
-    struct SideData: Codable, Sendable, Equatable {
+struct SoftwareStoredPacket: Sendable, Equatable {
+    struct SideData: Sendable, Equatable {
         let type: UInt32
         let bytes: Data
     }
@@ -18,13 +18,102 @@ struct SoftwareStoredPacket: Codable, Sendable, Equatable {
     let bytes: Data
     let sideData: [SideData]
 
+    enum EnvelopeError: Error {
+        case unknownVersion(UInt8)
+        case truncated
+        case trailingBytes(Int)
+    }
+
+    // AE#592: a fixed little-endian header followed by the raw bytes. The binary property list
+    // this replaced uniqued every object through a Set, hashing the whole payload of every packet,
+    // and that was the largest single cost of the software route's producer. The spool lives only
+    // for its session, so the layout carries a version byte and no compatibility promise.
+    //
+    //   u8 version | i64 pts, dts, duration, position | i32 streamIndex, flags, tbNum, tbDen
+    //   | u32 sideDataCount | u64 payloadCount | payload | per side data: u32 type, u64 count, bytes
+    static let version: UInt8 = 1
+    static let headerBytes = 1 + 4 * 8 + 4 * 4 + 4 + 8
+    static let sideDataHeaderBytes = 4 + 8
+
     func encoded() throws -> Data {
-        let encoder = PropertyListEncoder()
-        encoder.outputFormat = .binary
-        return try encoder.encode(self)
+        let total = sideData.reduce(Self.headerBytes + bytes.count) {
+            $0 + Self.sideDataHeaderBytes + $1.bytes.count
+        }
+        var out = Data(capacity: total)
+        out.append(Self.version)
+        for value in [pts, dts, duration, position] { Self.append(value, to: &out) }
+        for value in [streamIndex, flags, timeBaseNumerator, timeBaseDenominator] { Self.append(value, to: &out) }
+        Self.append(UInt32(sideData.count), to: &out)
+        Self.append(UInt64(bytes.count), to: &out)
+        out.append(bytes)
+        for entry in sideData {
+            Self.append(entry.type, to: &out)
+            Self.append(UInt64(entry.bytes.count), to: &out)
+            out.append(entry.bytes)
+        }
+        return out
     }
 
     static func decode(_ data: Data) throws -> Self {
-        try PropertyListDecoder().decode(Self.self, from: data)
+        var reader = Reader(data: data)
+        let version: UInt8 = try reader.read()
+        guard version == Self.version else { throw EnvelopeError.unknownVersion(version) }
+        let pts: Int64 = try reader.read()
+        let dts: Int64 = try reader.read()
+        let duration: Int64 = try reader.read()
+        let position: Int64 = try reader.read()
+        let streamIndex: Int32 = try reader.read()
+        let flags: Int32 = try reader.read()
+        let timeBaseNumerator: Int32 = try reader.read()
+        let timeBaseDenominator: Int32 = try reader.read()
+        let sideDataCount: UInt32 = try reader.read()
+        let payload = try reader.bytes(count: try reader.read() as UInt64)
+        var sideData: [SideData] = []
+        sideData.reserveCapacity(Int(min(sideDataCount, 64)))
+        for _ in 0..<sideDataCount {
+            let type: UInt32 = try reader.read()
+            sideData.append(SideData(type: type, bytes: try reader.bytes(count: try reader.read() as UInt64)))
+        }
+        guard reader.remaining == 0 else { throw EnvelopeError.trailingBytes(reader.remaining) }
+        return SoftwareStoredPacket(
+            pts: pts, dts: dts, duration: duration, position: position,
+            streamIndex: streamIndex, flags: flags,
+            timeBaseNumerator: timeBaseNumerator, timeBaseDenominator: timeBaseDenominator,
+            bytes: payload, sideData: sideData)
+    }
+
+    private static func append<T: FixedWidthInteger>(_ value: T, to out: inout Data) {
+        withUnsafeBytes(of: value.littleEndian) { out.append(contentsOf: $0) }
+    }
+
+    private struct Reader {
+        let data: Data
+        var offset: Int
+
+        init(data: Data) {
+            self.data = data
+            self.offset = data.startIndex
+        }
+
+        var remaining: Int { data.endIndex - offset }
+
+        mutating func read<T: FixedWidthInteger>() throws -> T {
+            let size = MemoryLayout<T>.size
+            guard remaining >= size else { throw EnvelopeError.truncated }
+            var value: T = 0
+            withUnsafeMutableBytes(of: &value) { raw in
+                data.copyBytes(to: raw.bindMemory(to: UInt8.self), from: offset..<offset + size)
+            }
+            offset += size
+            return T(littleEndian: value)
+        }
+
+        mutating func bytes(count: UInt64) throws -> Data {
+            guard count <= UInt64(remaining) else { throw EnvelopeError.truncated }
+            let end = offset + Int(count)
+            let slice = Data(data[offset..<end])
+            offset = end
+            return slice
+        }
     }
 }
diff --git a/Tests/AetherEngineTests/Issue592PacketEnvelopeTests.swift b/Tests/AetherEngineTests/Issue592PacketEnvelopeTests.swift
index 839fb861c..441533680 100644
--- a/Tests/AetherEngineTests/Issue592PacketEnvelopeTests.swift
+++ b/Tests/AetherEngineTests/Issue592PacketEnvelopeTests.swift
@@ -48,6 +48,43 @@ struct Issue592PacketEnvelopeTests {
         #expect(try SoftwareStoredPacket.decode(p.encoded()) == p)
     }
 
+    /// The binary property list encoder uniqued every object through a `Set`, which hashed the
+    /// whole payload on every packet: 92 % of the envelope's encode time in a release profile of a
+    /// 91 Mbit/s HEVC session. The envelope is now the payload plus a fixed header, so its size
+    /// says whether anything else crept back in.
+    @Test("the envelope is a fixed header, the payload and the side data, nothing else")
+    func envelopeSizeIsExact() throws {
+        let p = packet(payload: 425_000, sideData: 3)
+        let side = p.sideData.reduce(0) { $0 + SoftwareStoredPacket.sideDataHeaderBytes + $1.bytes.count }
+        #expect(try p.encoded().count == SoftwareStoredPacket.headerBytes + 425_000 + side)
+    }
+
+    @Test("a truncated envelope throws instead of reading past its end")
+    func truncatedEnvelopeThrows() throws {
+        let data = try packet(payload: 4_096, sideData: 2).encoded()
+        for cut in [0, 1, SoftwareStoredPacket.headerBytes - 1, SoftwareStoredPacket.headerBytes + 10, data.count - 1] {
+            #expect(throws: (any Error).self) { try SoftwareStoredPacket.decode(data.prefix(cut)) }
+        }
+    }
+
+    @Test("an envelope of another version or with trailing bytes throws")
+    func foreignEnvelopeThrows() throws {
+        var data = try packet(payload: 16).encoded()
+        var trailing = data
+        trailing.append(0)
+        #expect(throws: (any Error).self) { try SoftwareStoredPacket.decode(trailing) }
+        data[data.startIndex] = 0xFF
+        #expect(throws: (any Error).self) { try SoftwareStoredPacket.decode(data) }
+    }
+
+    @Test("a slice decodes like the whole buffer")
+    func sliceDecodes() throws {
+        let p = packet(payload: 777, sideData: 1)
+        var framed = Data([1, 2, 3])
+        framed.append(try p.encoded())
+        #expect(try SoftwareStoredPacket.decode(framed.dropFirst(3)) == p)
+    }
+
     /// Reported, not asserted: a throughput floor pinned here would be a CI coin toss. The number is
     /// the deliverable, read off the run. Each round gets its own payload, so nothing is reused
     /// across iterations and a copy the encoder makes is a copy this measures.

From a8506c04bf22fefb43835fba3e85f107fdc70c6f Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 24 Sep 2026 09:47:39 +0200
Subject: [PATCH 018/359] perf(avio): the persistent window holds the delivered
 chunks, so a trim copies nothing (AE#619)

trimWindowLocked dropped the consumed head with window.subdata(in:), which
copied everything still ahead of the cut into a fresh buffer: up to ~18 MB
once per 4 MB consumed, and each append after it grew that fresh buffer by
reallocation. The window is now a ChunkedByteWindow that keeps the Data
chunks as the connection delivered them. A trim advances an offset and
releases the chunks it passed. A truncate for a reconnect slices one
chunk. Reads copy out of the chunks into the AVIO buffer, which they did
before as well. winStart, the lookback and every count the reader reports
are unchanged.

Measured with release aetherctl on an M1 Air, one FFmpeg-muxed 4K HEVC +
AC-3 5.1 fixture at 91.6 Mbit/s over Scripts/slowrange.py (1 Gbit/s,
20 ms), process CPU over seconds 20 to 110 of 120 s sessions, arms
alternated:

  software  8710a245 0.208 / 0.203 / 0.207   this 0.202 / 0.203 / 0.205
  native    8710a245 0.167 / 0.165 / 0.167   this 0.160 / 0.166 / 0.164

About -0.003 cores on both routes, inside the spread of the arms: the
change is not separable from noise in process CPU. What it removes is
visible in a 20 s sample of the software route: trimWindowLocked 35 -> 0
samples, appendPersistentData 13 -> 1, _platform_memmove 205 -> 140. No
rebuffer on any run.

Tests: ChunkedByteWindow against a contiguous Data reference over 5000
random appends, reads, drops and truncates, plus edge cases and a pin that
a drop keeps the storage of what remains. A reader-level test reads 12 MB
forward and 256 KB back inside the lookback from a patterned origin and
checks every byte and that the backward read made no request.
ThrottledOriginServer gains an opt-in patterned body for it. 3388
swift-testing and 629 XCTest tests green.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 Sources/AetherEngine/Demuxer/AVIOReader.swift |  32 +--
 .../Demuxer/ChunkedByteWindow.swift           | 125 +++++++++++
 .../Issue619ChunkedByteWindowTests.swift      | 198 ++++++++++++++++++
 .../ThrottledOriginServer.swift               |  17 +-
 4 files changed, 350 insertions(+), 22 deletions(-)
 create mode 100644 Sources/AetherEngine/Demuxer/ChunkedByteWindow.swift
 create mode 100644 Tests/AetherEngineTests/Issue619ChunkedByteWindowTests.swift

diff --git a/Sources/AetherEngine/Demuxer/AVIOReader.swift b/Sources/AetherEngine/Demuxer/AVIOReader.swift
index 522c46eaa..c0df3a1bb 100644
--- a/Sources/AetherEngine/Demuxer/AVIOReader.swift
+++ b/Sources/AetherEngine/Demuxer/AVIOReader.swift
@@ -722,8 +722,9 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
     /// edge-triggered condition variable for read waits and backpressure.
     private let winCond = NSCondition()
     /// Sliding window of bytes from the live connection, starting at `winStart`.
-    /// `position - winStart` is the read offset within `window`.
-    private var window = Data()
+    /// `position - winStart` is the read offset within `window`. Held as the delivered chunks
+    /// (AE#619), so trimming the consumed head copies nothing.
+    private var window = ChunkedByteWindow()
     private var winStart: Int64 = 0
     // Connection state.
     private var connEnded = false
@@ -1356,7 +1357,7 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
         winCond.lock()
         defer { winCond.unlock() }
         let n = Swift.min(max, window.count)
-        return n > 0 ? Array(window.prefix(n)) : []
+        return window.prefix(n)
     }
 
     /// True when a body's leading bytes are the HLS playlist tag `#EXTM3U`, tolerating a UTF-8 BOM and
@@ -1391,7 +1392,7 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
         connGeneration &+= 1
         let transfer = activeTransfer
         activeTransfer = nil
-        window = Data()
+        window.removeAll()
         connEnded = true
         winCond.broadcast()
         return (false, transfer, status)
@@ -1545,7 +1546,7 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
         connEnded = true
         let transfer = activeTransfer
         activeTransfer = nil
-        window = Data()
+        window.removeAll()
         // #281: both spans hold real bytes (up to headSpanMaxBytes + tailPrefetchBytes), so they
         // are released with the window rather than living until the reader is deallocated.
         headSpan = Data()
@@ -2047,11 +2048,7 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
             let available = window.count - posInWindow
             if available > 0 {
                 let copyNow = min(available, requestSize - totalRead)
-                window.withUnsafeBytes { raw in
-                    let src = raw.baseAddress!.advanced(by: posInWindow)
-                        .assumingMemoryBound(to: UInt8.self)
-                    buf.advanced(by: totalRead).update(from: src, count: copyNow)
-                }
+                window.copyBytes(to: buf.advanced(by: totalRead), from: posInWindow, count: copyNow)
                 position = curPosition + Int64(copyNow)
                 totalRead += copyNow
                 trimWindowLocked()
@@ -2242,7 +2239,7 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
         let dropThreshold = Self.winLookback + Self.winTrimBatch
         if behind > dropThreshold {
             let drop = behind - Self.winLookback
-            window = window.subdata(in: drop..<window.count)
+            window.dropFirst(drop)
             winStart += Int64(drop)
         }
     }
@@ -2859,10 +2856,10 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
         // new range, which is correct if slightly wasteful, and never leaves a hole.
         if offset >= winStart, offset <= winStart + Int64(window.count) {
             let keep = Int(offset - winStart)
-            if keep < window.count { window = window.subdata(in: 0..<keep) }
+            if keep < window.count { window.truncate(to: keep) }
         } else {
             winStart = offset
-            window = Data()
+            window.removeAll()
         }
         connRequestedOffset = offset
         let askAsJoin = isLive && liveOffsetsUnsatisfiable
@@ -3149,14 +3146,7 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
             }
         }
         let base = window.count
-        window.count = base + count
-        window.withUnsafeMutableBytes { dst in
-            data.withUnsafeBytes { src in
-                if let d = dst.baseAddress, let s = src.baseAddress {
-                    (d + base).copyMemory(from: s, byteCount: count)
-                }
-            }
-        }
+        window.append(data)
         // #281 retest: retain the head of the file for the open phase, as it arrives. It cannot be
         // copied later out of the window, because `trimWindowLocked` drops it as the parse reads
         // forward, which is why the seek-time park misses on every layout whose parse reads more
diff --git a/Sources/AetherEngine/Demuxer/ChunkedByteWindow.swift b/Sources/AetherEngine/Demuxer/ChunkedByteWindow.swift
new file mode 100644
index 000000000..9e9bcaafb
--- /dev/null
+++ b/Sources/AetherEngine/Demuxer/ChunkedByteWindow.swift
@@ -0,0 +1,125 @@
+import Foundation
+
+/// AE#619: the persistent reader's byte window, held as the chunks the connection delivered.
+///
+/// The reader used to keep one contiguous `Data` and drop its consumed head with `subdata(in:)`,
+/// which copied everything still ahead of the cut: up to ~18 MB once per 4 MB consumed, several
+/// times the stream's own rate in `memmove`, and each append after it reallocated the fresh buffer.
+/// Here a drop advances an offset and releases the chunks it passed, and nothing ahead of it moves.
+/// Callers see one contiguous run of `count` bytes; the chunking is invisible to them.
+///
+/// Not thread-safe. The reader guards it with `winCond` like the `Data` it replaces.
+struct ChunkedByteWindow {
+    private var chunks: [Data] = []
+    /// Storage offset one past the end of `chunks[i]`. Storage offsets only grow until
+    /// `removeAll`, so a drop never rewrites them.
+    private var ends: [Int] = []
+    /// Index of the first chunk still holding live bytes.
+    private var first = 0
+    /// Storage offset of logical byte 0.
+    private var head = 0
+    /// Storage offset one past the last byte.
+    private var tail = 0
+
+    var count: Int { tail - head }
+    var isEmpty: Bool { tail == head }
+
+    mutating func append(_ data: Data) {
+        guard !data.isEmpty else { return }
+        chunks.append(data)
+        tail += data.count
+        ends.append(tail)
+    }
+
+    /// Drops the first `n` bytes. `n` is clamped to `count`.
+    mutating func dropFirst(_ n: Int) {
+        head += min(max(0, n), count)
+        while first < chunks.count, ends[first] <= head {
+            chunks[first] = Data()
+            first += 1
+        }
+        if first == chunks.count {
+            removeAll()
+        } else if first >= 64, first * 2 >= chunks.count {
+            chunks.removeFirst(first)
+            ends.removeFirst(first)
+            first = 0
+        }
+    }
+
+    /// Keeps the first `keep` bytes and drops the rest. `keep` is clamped to `0...count`.
+    mutating func truncate(to keep: Int) {
+        let newTail = head + min(max(0, keep), count)
+        guard newTail < tail else { return }
+        if newTail == head {
+            removeAll()
+            return
+        }
+        let i = chunkIndex(containing: newTail - 1)
+        let start = ends[i] - chunks[i].count
+        let c = chunks[i]
+        chunks[i] = c[c.startIndex..<c.startIndex + (newTail - start)]
+        ends[i] = newTail
+        chunks.removeSubrange(i + 1..<chunks.count)
+        ends.removeSubrange(i + 1..<ends.count)
+        tail = newTail
+    }
+
+    mutating func removeAll() {
+        chunks = []
+        ends = []
+        first = 0
+        head = 0
+        tail = 0
+    }
+
+    /// Copies `count` bytes starting at logical `offset` into `destination`.
+    /// `offset + count` must not exceed `self.count`.
+    func copyBytes(to destination: UnsafeMutablePointer<UInt8>, from offset: Int, count n: Int) {
+        precondition(offset >= 0 && n >= 0 && offset + n <= count, "ChunkedByteWindow read out of range")
+        guard n > 0 else { return }
+        var position = head + offset
+        var written = 0
+        var i = chunkIndex(containing: position)
+        while written < n {
+            let c = chunks[i]
+            let start = ends[i] - c.count
+            let local = position - start
+            let take = min(c.count - local, n - written)
+            let from = c.startIndex + local
+            c.copyBytes(to: UnsafeMutableBufferPointer(start: destination + written, count: take),
+                        from: from..<from + take)
+            written += take
+            position += take
+            i += 1
+        }
+    }
+
+    /// The first `n` bytes, or all of them when fewer are held.
+    func prefix(_ n: Int) -> [UInt8] {
+        let take = min(max(0, n), count)
+        var out = [UInt8](repeating: 0, count: take)
+        out.withUnsafeMutableBufferPointer { buffer in
+            if let base = buffer.baseAddress { copyBytes(to: base, from: 0, count: take) }
+        }
+        return out
+    }
+
+    /// Index of the chunk holding storage offset `position`, which must be in `head..<tail`.
+    private func chunkIndex(containing position: Int) -> Int {
+        var lower = first
+        var upper = ends.count - 1
+        while lower < upper {
+            let middle = lower + (upper - lower) / 2
+            if ends[middle] <= position { lower = middle + 1 } else { upper = middle }
+        }
+        return lower
+    }
+
+    #if DEBUG
+    /// Test hook: the storage address of every live chunk, first to last.
+    func chunkStorageAddresses() -> [UnsafeRawPointer?] {
+        chunks[first...].map { $0.withUnsafeBytes { UnsafeRawPointer($0.baseAddress) } }
+    }
+    #endif
+}
diff --git a/Tests/AetherEngineTests/Issue619ChunkedByteWindowTests.swift b/Tests/AetherEngineTests/Issue619ChunkedByteWindowTests.swift
new file mode 100644
index 000000000..32f8bfabf
--- /dev/null
+++ b/Tests/AetherEngineTests/Issue619ChunkedByteWindowTests.swift
@@ -0,0 +1,198 @@
+import Foundation
+import Testing
+@testable import AetherEngine
+
+/// AE#619: the persistent reader's window used to drop its consumed head with
+/// `window.subdata(in:)`, which copied everything still ahead of the cut, up to ~18 MB once per
+/// 4 MB consumed. The window now holds the delivered chunks as they arrived. These cases pin that
+/// it still behaves exactly like one contiguous buffer, byte for byte, under every operation the
+/// reader performs.
+@Suite("AE#619: the chunked read window")
+struct Issue619ChunkedByteWindowTests {
+
+    private func bytes(_ window: ChunkedByteWindow, from offset: Int = 0, count: Int? = nil) -> [UInt8] {
+        let n = count ?? window.count - offset
+        var out = [UInt8](repeating: 0, count: n)
+        out.withUnsafeMutableBufferPointer { window.copyBytes(to: $0.baseAddress!, from: offset, count: n) }
+        return out
+    }
+
+    private func chunk(_ start: Int, _ count: Int) -> Data {
+        Data((0..<count).map { UInt8(truncatingIfNeeded: start &+ $0 &* 7) })
+    }
+
+    @Test("an empty window reads as empty")
+    func emptyWindow() {
+        var window = ChunkedByteWindow()
+        #expect(window.isEmpty && window.count == 0)
+        window.append(Data())
+        #expect(window.isEmpty)
+        #expect(window.prefix(16).isEmpty)
+    }
+
+    @Test("a read across chunk boundaries returns the bytes in order")
+    func readAcrossChunks() {
+        var window = ChunkedByteWindow()
+        var reference = Data()
+        for (i, size) in [3, 1, 4096, 17, 1].enumerated() {
+            let c = chunk(i * 100, size)
+            window.append(c)
+            reference.append(c)
+        }
+        #expect(window.count == reference.count)
+        #expect(bytes(window) == [UInt8](reference))
+        #expect(bytes(window, from: 2, count: 3) == [UInt8](reference[2..<5]))
+        #expect(window.prefix(6) == [UInt8](reference.prefix(6)))
+    }
+
+    @Test("dropping the head keeps the rest, including a partly consumed chunk")
+    func dropHead() {
+        var window = ChunkedByteWindow()
+        var reference = Data()
+        for i in 0..<8 {
+            let c = chunk(i, 1000)
+            window.append(c)
+            reference.append(c)
+        }
+        for drop in [0, 1, 999, 1000, 2500] {
+            window.dropFirst(drop)
+            reference = reference.subdata(in: drop..<reference.count)
+            #expect(bytes(window) == [UInt8](reference))
+        }
+        window.dropFirst(window.count)
+        #expect(window.isEmpty)
+        window.append(chunk(9, 5))
+        #expect(bytes(window) == [UInt8](chunk(9, 5)))
+    }
+
+    @Test("truncating keeps exactly the leading bytes, inside a chunk and on its edge")
+    func truncate() {
+        for keep in [0, 1, 999, 1000, 1001, 2999, 3000] {
+            var window = ChunkedByteWindow()
+            var reference = Data()
+            for i in 0..<3 {
+                let c = chunk(i, 1000)
+                window.append(c)
+                reference.append(c)
+            }
+            window.dropFirst(0)
+            window.truncate(to: keep)
+            #expect(bytes(window) == [UInt8](reference.prefix(keep)))
+            window.append(chunk(7, 10))
+            #expect(bytes(window) == [UInt8](reference.prefix(keep) + chunk(7, 10)))
+        }
+    }
+
+    @Test("a slice of a larger buffer is held by its own indices")
+    func sliceChunk() {
+        let backing = chunk(0, 64)
+        var window = ChunkedByteWindow()
+        window.append(backing[10..<20])
+        window.append(backing[40..<44])
+        #expect(bytes(window) == [UInt8](backing[10..<20] + backing[40..<44]))
+    }
+
+    /// The reader's own mix, many times over: append what arrives, read near the head, drop the
+    /// consumed head, and now and then cut the tail for a reconnect. Checked against a contiguous
+    /// `Data` doing the same thing the old way.
+    @Test("a long random run matches a contiguous buffer")
+    func randomRunMatchesReference() {
+        var rng = SystemRandomNumberGenerator()
+        var window = ChunkedByteWindow()
+        var reference = Data()
+        var serial = 0
+        for _ in 0..<5_000 {
+            switch Int.random(in: 0..<10, using: &rng) {
+            case 0..<5:
+                let c = chunk(serial, Int.random(in: 0..<3000, using: &rng))
+                serial += 1
+                window.append(c)
+                reference.append(c)
+            case 5..<8 where !reference.isEmpty:
+                let offset = Int.random(in: 0..<reference.count, using: &rng)
+                let n = Int.random(in: 0...(reference.count - offset), using: &rng)
+                #expect(bytes(window, from: offset, count: n) == [UInt8](reference[offset..<offset + n]))
+            case 8:
+                let n = Int.random(in: 0...reference.count, using: &rng)
+                window.dropFirst(n)
+                reference = reference.subdata(in: n..<reference.count)
+            default:
+                let keep = Int.random(in: 0...reference.count, using: &rng)
+                window.truncate(to: keep)
+                reference = reference.prefix(keep)
+            }
+            #expect(window.count == reference.count)
+        }
+        #expect(bytes(window) == [UInt8](reference))
+    }
+
+    /// The point of the change, pinned without a clock: dropping the head of a long window must
+    /// not touch the bytes still ahead of it. A chunk that is still referenced elsewhere keeps its
+    /// storage identity through a drop, which a copy would not.
+    @Test("dropping the head does not copy what remains")
+    func dropDoesNotCopy() {
+        var window = ChunkedByteWindow()
+        for i in 0..<16 { window.append(Data(repeating: UInt8(i), count: 1 << 20)) }
+        let before = window.chunkStorageAddresses()
+        window.dropFirst(4 << 20)
+        let after = window.chunkStorageAddresses()
+        #expect(Array(before.suffix(12)) == after)
+    }
+}
+
+/// The same window behind the real reader: bytes read forward and bytes read back inside the
+/// lookback after several trims are the origin's bytes at those offsets, and the backward read is
+/// served from the window rather than from a new request.
+@Suite("AE#619: the reader's window over a live connection")
+struct Issue619ReaderWindowTests {
+
+    private func readExactly(_ reader: AVIOReader, _ count: Int, at offset: Int64) -> [UInt8]? {
+        var out = [UInt8](repeating: 0, count: count)
+        var got = 0
+        let ok = out.withUnsafeMutableBufferPointer { buffer -> Bool in
+            while got < count {
+                let n = reader.read(into: buffer.baseAddress! + got, size: Int32(min(64 * 1024, count - got)))
+                if n <= 0 { return false }
+                got += Int(n)
+            }
+            return true
+        }
+        return ok ? out : nil
+    }
+
+    private func expected(_ count: Int, at offset: Int64) -> [UInt8] {
+        (0..<count).map { ThrottledOriginServer.patternByte(at: offset + Int64($0)) }
+    }
+
+    @Test("forward reads and a backward read inside the lookback return the origin's bytes")
+    func backwardReadAfterTrimsHitsTheWindow() throws {
+        let server = try #require(ThrottledOriginServer(totalSize: 256 * 1024 * 1024, throttleUs: 0,
+                                                         patternedBody: true))
+        defer { server.stop() }
+        let reader = AVIOReader(url: URL(string: "http://127.0.0.1:\(server.port)/movie.bin")!)
+        defer { reader.markClosed(); reader.close() }
+        try reader.open()
+
+        // 12 MB forward in 1 MB steps: past `winLookback + winTrimBatch` (6 MB), so the head has
+        // been trimmed at least once by the time the backward read lands.
+        var offset: Int64 = 0
+        for _ in 0..<12 {
+            let got = try #require(readExactly(reader, 1 << 20, at: offset))
+            #expect(got == expected(1 << 20, at: offset), "forward read at \(offset)")
+            offset += 1 << 20
+        }
+
+        let requestsBefore = server.requestedRanges.count
+        let back = offset - 1_500_000
+        #expect(reader.seek(offset: back, whence: SEEK_SET) == back)
+        let got = try #require(readExactly(reader, 256 * 1024, at: back))
+        #expect(got == expected(256 * 1024, at: back), "backward read at \(back)")
+        #expect(!server.requestedRanges.dropFirst(requestsBefore).contains { $0.start == back },
+                "a read inside the lookback went to the network: \(server.requestedRanges)")
+
+        // And forward again past where the first pass stopped.
+        let resume = back + 256 * 1024
+        let tail = try #require(readExactly(reader, 4 << 20, at: resume))
+        #expect(tail == expected(4 << 20, at: resume), "forward read after the backward one")
+    }
+}
diff --git a/Tests/AetherEngineTests/ThrottledOriginServer.swift b/Tests/AetherEngineTests/ThrottledOriginServer.swift
index d2735fedf..e37d9b3aa 100644
--- a/Tests/AetherEngineTests/ThrottledOriginServer.swift
+++ b/Tests/AetherEngineTests/ThrottledOriginServer.swift
@@ -43,6 +43,16 @@ final class ThrottledOriginServer: @unchecked Sendable {
     /// its own chunk boundary does this. Default off keeps every existing test on the historical
     /// behaviour.
     private let ignoreRangeEnd: Bool
+    /// AE#619: serve `patternByte(at:)` instead of a constant, so a test can check that the bytes
+    /// the reader returns are the bytes at the offset it claims. Default off keeps every existing
+    /// test on the historical constant body.
+    private let patternedBody: Bool
+
+    /// The byte a `patternedBody` origin serves at `offset`. Varies within every 256-byte run and
+    /// between runs, so a shifted or reordered read cannot match by accident.
+    static func patternByte(at offset: Int64) -> UInt8 {
+        UInt8(truncatingIfNeeded: offset ^ (offset >> 8) ^ (offset >> 16) ^ (offset >> 24))
+    }
     private let chunkBytes: Int
     private let throttleUs: useconds_t
     private let firstByteDelayUs: @Sendable (_ isSuffix: Bool) -> useconds_t
@@ -133,10 +143,12 @@ final class ThrottledOriginServer: @unchecked Sendable {
     init?(totalSize: Int64, chunkBytes: Int = 256 * 1024, throttleUs: useconds_t = 5000,
           refuseAboveConcurrency: Int? = nil,
           ignoreRangeEnd: Bool = false,
+          patternedBody: Bool = false,
           firstByteDelayUs: @escaping @Sendable (_ isSuffix: Bool) -> useconds_t = { _ in 0 },
           respond: @escaping @Sendable (_ requestIndex: Int, _ offset: Int64, _ path: String) -> Directive = { _, _, _ in .serve206 }) {
         self.totalSize = totalSize
         self.ignoreRangeEnd = ignoreRangeEnd
+        self.patternedBody = patternedBody
         self.chunkBytes = chunkBytes
         self.throttleUs = throttleUs
         self.refuseAboveConcurrency = refuseAboveConcurrency
@@ -370,7 +382,10 @@ final class ThrottledOriginServer: @unchecked Sendable {
             var n = Int(min(Int64(chunkBytes), remaining - served))
             if let silentAfter { n = Int(min(Int64(n), silentAfter - served)) }
             if let dropAfter { n = Int(min(Int64(n), dropAfter - served)) }
-            guard writeBody(fd, Array(chunk[0..<n])) else { return false }
+            let body = patternedBody
+                ? (0..<n).map { Self.patternByte(at: offset + served + Int64($0)) }
+                : Array(chunk[0..<n])
+            guard writeBody(fd, body) else { return false }
             served += Int64(n)
             if throttleUs > 0 { usleep(throttleUs) }
         }

From 079d74b9fad2e878afb892a4c771efd7c7ecfd58 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 24 Sep 2026 11:01:34 +0200
Subject: [PATCH 019/359] chore(release): prep 7.15.2 - a picture-timed
 sourceTime on remote HLS, a spool without a plist, a window without a copy

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 CHANGELOG.md                                  | 30 +++++++++++++++++++
 Examples/README.md                            |  2 +-
 README.md                                     |  6 ++--
 .../AetherEngine/AetherEngine+Version.swift   |  2 +-
 4 files changed, 35 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 781f6df36..a8358760c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,36 @@ the public-API contract.
 
 _Nothing yet._
 
+## [7.15.2] - 2026-09-24
+
+### Fixed
+
+- **`sourceTime` on the `nativeRemoteHLS` bypass follows the presented frame (AE#616).** It was
+  AVPlayer's item time. An origin whose playlist places a segment at its slot while the segment
+  starts at the keyframe before it (a Jellyfin transcode restarted with `-noaccurate_seek -copyts`)
+  makes item time lead the picture, by 1.1 to 8.3 s in the report. A legible output on the bypass
+  item now matches presented lines of the injected #316 WebVTT renditions back to the cues the
+  engine wrote, and `sourceTime` is item time less that measured lead. `currentTime` and
+  `seek(to:)` stay on item time. With no injected rendition selected nothing is measured and
+  `sourceTime` stays item time, which the API docs now say.
+
+### Performance
+
+- **The persistent HTTP reader no longer copies its read window on every trim (AE#619).**
+  `AVIOReader` dropped the consumed head of its window with `subdata(in:)`, copying up to ~18 MB
+  once per 4 MB read, and grew the fresh buffer again on every append. The window now keeps the
+  chunks as delivered and a trim only advances an offset. CPU is unchanged within noise. Peak
+  memory footprint on a 91.6 Mbit/s 4K HEVC session over HTTP fell from 828 to 911 MB to 551 to
+  553 MB on the native route and from 604 to 651 MB to 193 to 197 MB on the software route
+  (M1, `/usr/bin/time -l`, three runs per arm). Local files are read by `FileIOReader` and are
+  not affected.
+- **The software VOD packet spool no longer serializes through a property list (AE#592).** The
+  binary plist encoder uniqued every object through a `Set`, hashing the whole payload of every
+  packet written to the read-ahead spool. The envelope is now a fixed little-endian header and the
+  raw bytes. Encode fell from 375 to 43 us per 425 KB packet, and process CPU on the same session
+  from 0.220 to 0.223 to 0.205 to 0.208 cores. The spool is per session, so there is no format
+  compatibility to keep.
+
 ## [7.15.1] - 2026-09-23
 
 ### Fixed
diff --git a/Examples/README.md b/Examples/README.md
index 641e7853b..0a047dcd4 100644
--- a/Examples/README.md
+++ b/Examples/README.md
@@ -18,7 +18,7 @@ Three samples covering different audiences:
    ```
    https://github.com/superuser404notfound/AetherEngine
    ```
-   Dependency Rule: Up to Next Major Version, starting from `7.15.1`. Add the `AetherEngine` library product to your app target.
+   Dependency Rule: Up to Next Major Version, starting from `7.15.2`. Add the `AetherEngine` library product to your app target.
 
 3. **Drop the file in.** Replace the Xcode template's default `App.swift` (or whatever the generated `@main` file is called) with the contents of [`MinimalPlayerApp.swift`](MinimalPlayer/MinimalPlayerApp.swift). The file is self-contained: it defines both the `@main App` struct and the `ContentView`.
 
diff --git a/README.md b/README.md
index e94916fa1..5650b45fb 100644
--- a/README.md
+++ b/README.md
@@ -343,7 +343,7 @@ Subtitle cues land in raw source PTS; render the overlay against `player.sourceT
 Install via Swift Package Manager:
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.15.1")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.15.2")
 ```
 
 Three samples ship in `Examples/`:
@@ -590,10 +590,10 @@ Browse all of this as a searchable site at **[aetherengine.superuser404.de](http
 AetherEngine uses [Semantic Versioning](https://semver.org). The public API surface, every `public` declaration in `Sources/AetherEngine/`, is the stability contract. **Major** removes / renames public symbols or breaks adopters; **Minor** adds public API or codec / format support; **Patch** fixes bugs with no public API change. `internal` types are not part of the contract.
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.15.1")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.15.2")
 ```
 
-Pin to `.upToNextMinor(from: "7.15.1")` for stricter teams that prefer to opt into minor bumps explicitly.
+Pin to `.upToNextMinor(from: "7.15.2")` for stricter teams that prefer to opt into minor bumps explicitly.
 
 ## Requirements
 
diff --git a/Sources/AetherEngine/AetherEngine+Version.swift b/Sources/AetherEngine/AetherEngine+Version.swift
index 46843df9c..7531c70f4 100644
--- a/Sources/AetherEngine/AetherEngine+Version.swift
+++ b/Sources/AetherEngine/AetherEngine+Version.swift
@@ -11,5 +11,5 @@ extension AetherEngine {
     ///
     /// Between releases, and in a consumer that pins an unreleased commit for a device test, this
     /// names the last PUBLISHED version the checkout descends from, not every patch in it.
-    public nonisolated static let version = "7.15.1"
+    public nonisolated static let version = "7.15.2"
 }

From f36fe40f0a4c6db45acb4d982d281e8938448424 Mon Sep 17 00:00:00 2001
From: Brandon Moore <16313090+thatcube@users.noreply.github.com>
Date: Thu, 24 Sep 2026 03:23:09 -0400
Subject: [PATCH 020/359] fix(native): the media fallback comes back where the
 refused item was placed (#98)

The #98 media fallback replayed the start position of the session's first
mount. The #93/#65 stage-2 recovery swaps a fresh item in at the position
playback held, so when that recovery item was refused at startup, the
fallback rewound the session to wherever it had first been loaded.

Field log, Apple TV 4K 3rd gen, tvOS 27.0, HDR10+ HEVC Matroska opened with
a resume at 1844 s: paused at 2099.69 s, the item died behind the
screensaver, the recovery item was refused with -11868, and playback
resumed at 1834.79 s. A title started from its beginning resumes at its
first frame.

NativeAVPlayerHost now records where each mount places its item, in-place
swaps included, and the fallback reads that instead of the engine's
first-mount copy. The first mount records the same value as before, so a
fallback of a first mount is unchanged.
---
 CHANGELOG.md                                  | 13 +++-
 .../AetherEngine/AetherEngine+Loading.swift   |  1 -
 Sources/AetherEngine/AetherEngine.swift       | 10 ++-
 .../Native/NativeAVPlayerHost.swift           |  8 +++
 .../MasterFallbackDecisionTests.swift         | 63 +++++++++++++++++++
 docs/formats.md                               |  2 +-
 6 files changed, 88 insertions(+), 9 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index a8358760c..486eeec2b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,7 +10,18 @@ the public-API contract.
 
 ## [Unreleased]
 
-_Nothing yet._
+### Fixed
+
+- **The media fallback comes back where the rejected item was placed, not where the session
+  started (#98).** The fallback replayed the start position of the session's first mount. The
+  #93/#65 stage-2 recovery swaps a fresh item in at the position playback held, so when THAT item
+  was refused at startup (-11868), the session rewound to wherever it had first been loaded. Field
+  log, Apple TV 4K 3rd gen, tvOS 27.0, HDR10+ HEVC Matroska opened with a resume at 1844 s:
+  paused at 2099.69 s, the item died behind the screensaver, the recovery item was refused, and
+  playback resumed at 1834.79 s, the keyframe before the session's first mount and four minutes
+  behind the pause. A title started from its beginning resumes at its first frame. `NativeAVPlayerHost`
+  now records where every mount places its item, in-place swaps included, and the fallback reads
+  that.
 
 ## [7.15.2] - 2026-09-24
 
diff --git a/Sources/AetherEngine/AetherEngine+Loading.swift b/Sources/AetherEngine/AetherEngine+Loading.swift
index 387113274..a514a18db 100644
--- a/Sources/AetherEngine/AetherEngine+Loading.swift
+++ b/Sources/AetherEngine/AetherEngine+Loading.swift
@@ -1639,7 +1639,6 @@ extension AetherEngine {
         // appliesPerFrameHDRDisplayMetadata unconditionally true: DV P5 has no HDR10 base layer, so the per-frame RPU is what AVPlayer's tone-mapper needs on a non-DV panel (DrHurt #4 2026-05-26). Prior servingMasterPlaylist gate broke P5. Apple's default is also true; explicit write surfaces the live value in diagnostics.
         // forwardBufferDuration default (4 s): deep buffer lets AVPlayer race to the live edge and hit the transcode warm-up gap head-on (-12888); 4 s PACES consumption. Verified: 8 s worsened startup pause (8-10 s vs ~1 s).
         // Live REJOIN: skip initial seek so AVPlayer picks edge-minus-holdback instead; seek-to-0 against the re-served backlog wedged the reloaded item in waitingToPlay (device repro: tvOS 26, Jellyfin stream.ts). See LiveReloadPolicy.
-        lastNativeVideoStartPosition = startPosition ?? 0
         // Sequential append playlist: AVPlayer treats the growing playlist as an EVENT and
         // defaults to edge-minus-holdback (~6 s in on a fresh session, more once the producer
         // has raced ahead). The load-time seek to 0 fires before readyToPlay and the item
diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index b514a18d8..15fbc825a 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -2298,10 +2298,6 @@ public final class AetherEngine: ObservableObject {
     /// session so a media reload that also fails cannot loop. Reset on each load.
     var masterFallbackUsed = false
 
-    /// Start position of the current loopback video load, replayed if the master is rejected and we
-    /// reload the media playlist (a startup-failed item has no reliable renderedTime).
-    var lastNativeVideoStartPosition: Double = 0
-
     /// #93 PiP skips: AVKit-side seeks (PiP +-15s buttons) bypass the engine seek API, so a far
     /// playhead jump is detected on $renderedTime and, once settled, the native subtitle readers
     /// re-anchor and the remembered rendition selection replays (its deselect/reselect busts
@@ -2491,8 +2487,10 @@ public final class AetherEngine: ObservableObject {
         // #130: a live fallback is a REJOIN of the running ingest (the window may have slid since
         // the failed master attempt); a stale explicit position can wedge AVPlayer against the
         // backlog, so skip the initial seek and let it pick edge-minus-holdback (LiveReloadPolicy).
-        // VOD keeps the explicit pre-failure position.
-        let position = lastNativeVideoStartPosition
+        // VOD reloads where the rejected item was placed. That is not always where the session
+        // started: the #93/#65 stage-2 recovery swaps a fresh item in at the position it held, and a
+        // rejection of THAT item has to come back there, not rewind to the first mount.
+        let position = host.mountedStartPosition ?? 0
         EngineLog.emit(
             "[AetherEngine] AVPlayer rejected the master (code=\(rejection.code)); falling back to "
             + "media playlist (no CC/subtitle renditions) at "
diff --git a/Sources/AetherEngine/Native/NativeAVPlayerHost.swift b/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
index 192125bc1..616889af3 100644
--- a/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
+++ b/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
@@ -67,6 +67,13 @@ final class NativeAVPlayerHost {
     /// `SessionLoadContract` and `swapItem`.
     private(set) var sessionContract = SessionLoadContract()
 
+    /// Where the current item was placed when it was mounted: the explicit start seek `load` makes,
+    /// or nil when it joined without one (a live rejoin). Recorded on every mount, the in-place swaps
+    /// included, so a recovery that has to replace this item puts the next one where THIS one was,
+    /// not where the session first started (#98). A startup-failed item has no reliable
+    /// `renderedTime`, which is why the fallback reads the placement rather than the clock.
+    private(set) var mountedStartPosition: Double?
+
     /// Set per load; gates the AE#287 premature-end recovery, which only makes sense for a fixed-length
     /// presentation. A live session has no advertised end to fall short of.
     private var isLiveSession: Bool = false
@@ -433,6 +440,7 @@ final class NativeAVPlayerHost {
         unloadCurrentItem(inPlaceSwap: inPlaceSwap)
 
         self.sessionContract = contract
+        mountedStartPosition = skipInitialSeek ? nil : (startPosition ?? 0)
         let forwardBufferDuration = contract.forwardBufferDuration
         let httpHeaders = contract.httpHeaders
         let armIngestFallback = contract.armIngestFallback
diff --git a/Tests/AetherEngineTests/MasterFallbackDecisionTests.swift b/Tests/AetherEngineTests/MasterFallbackDecisionTests.swift
index e7fda8a50..069769e4c 100644
--- a/Tests/AetherEngineTests/MasterFallbackDecisionTests.swift
+++ b/Tests/AetherEngineTests/MasterFallbackDecisionTests.swift
@@ -1,3 +1,4 @@
+import Foundation
 import Testing
 @testable import AetherEngine
 
@@ -51,3 +52,65 @@ struct MasterFallbackDecisionTests {
             errorCode: -11868, servingMasterPlaylist: true, alreadyFellBack: true))
     }
 }
+
+/// #98: the media fallback reloads where the REJECTED item was placed. A recovery swaps a fresh item in
+/// under a session that stays whole, so that is not always where the session first started.
+///
+/// Field log, Apple TV 4K 3rd gen, tvOS 27.0, HDR10+ HEVC Matroska opened with a resume at 1844 s:
+/// paused at 2099.69 s, the item died behind the screensaver, the #93 stage-2 recovery swapped a
+/// fresh item in at 2099.69 s, that item was refused at startup with -11868, and the fallback
+/// reloaded at the first mount's 1844 s (landing on the keyframe at 1834.79 s). The viewer pressed
+/// play four minutes behind the pause; a session started from the beginning of a title is put back
+/// to its first frame.
+@Suite("#98: the media fallback comes back where the rejected item was placed")
+@MainActor
+struct MasterFallbackPositionTests {
+
+    private let url = URL(fileURLWithPath: "/nonexistent-master-fallback-position-test.m3u8")
+
+    @Test("An in-place recovery swap moves the placement the fallback reads")
+    func recoverySwapMovesThePlacement() {
+        let host = NativeAVPlayerHost()
+        defer { host.tearDown() }
+
+        host.load(url: url, startPosition: 1844, contract: .init())
+        #expect(host.mountedStartPosition == 1844)
+
+        // The #93/#65 stage-2 recovery: same session, fresh item, placed where playback stood.
+        host.swapItem(url: url, startPosition: 2099.69)
+        #expect(host.mountedStartPosition == 2099.69)
+    }
+
+    @Test("A mount with no start position is placed at the head, as its seek is")
+    func nilStartIsTheHead() {
+        let host = NativeAVPlayerHost()
+        defer { host.tearDown() }
+
+        host.load(url: url, startPosition: nil, contract: .init())
+        #expect(host.mountedStartPosition == 0)
+    }
+
+    @Test("A live rejoin makes no start seek, so it records no placement")
+    func liveRejoinRecordsNoPlacement() {
+        let host = NativeAVPlayerHost()
+        defer { host.tearDown() }
+
+        host.load(url: url, startPosition: 30, contract: .init(isLive: true))
+        host.swapItem(url: url, startPosition: nil, skipInitialSeek: true)
+        #expect(host.mountedStartPosition == nil)
+    }
+
+    /// A host-level test cannot see the call site, so this one reads it, as the #535 latch test does.
+    @Test("The fallback reads the placement of the item it replaces")
+    func fallbackReadsThePlacement() throws {
+        let source = URL(fileURLWithPath: #filePath)
+            .deletingLastPathComponent()
+            .deletingLastPathComponent()
+            .deletingLastPathComponent()
+            .appendingPathComponent("Sources/AetherEngine/AetherEngine.swift")
+        let text = try #require(try? String(contentsOf: source, encoding: .utf8))
+        let fn = try #require(text.range(of: "func fallBackToMediaPlaylist("))
+        let body = String(text[fn.lowerBound...].prefix(4000))
+        #expect(body.contains("host.mountedStartPosition"))
+    }
+}
diff --git a/docs/formats.md b/docs/formats.md
index b929a658a..3f4861a80 100644
--- a/docs/formats.md
+++ b/docs/formats.md
@@ -357,7 +357,7 @@ Whether an HDR or Dolby Vision master is accepted is the receiver's decision, an
 
 The refusal is silent, so it has to be caught by watching progress: no `-11868`, no failed item, the rate flickers to `playing` for a single tick so even `hasEverPlayed` latches, and the picture never starts while AVKit shows its "not playable on this display" sign. Five seconds without a segment fetched on a master handed to a receiver reloads the LAN media playlist, which every receiver takes, and that receiver is remembered by route UID for the rest of the process so it goes straight to media from then on. A second master attempt, to exploit the output switch the first one triggers, was tried on device and only doubled the wait. For subtitles on HDR content over AirPlay the answer is the receiver's setting: fix its video format to HDR or Dolby Vision. `$nativeSubtitleRenditionsServed` reports which playlist is actually in use, so a host can tell the user their subtitles will not travel to this route rather than dropping them silently. A wired HDMI external display is a different route and keeps the loopback plus its master.
 
-**Master-rejection fallback (#98, #130).** When AVPlayer rejects the served master (`-11868` AVErrorNoCompatibleAlternatesForExternalDisplay, `-11848` for an SDR-parked panel, or `-1002` when every variant was filtered at master parse time), the engine reloads the bare media playlist in place; a live session rejoins at the edge instead of replaying its stale start position. HDR / DV on an SDR external display is therefore media-playlist-driven (an AVKit limitation: forcing `VIDEO-RANGE=SDR` does not fool the external-display compatibility gate, which checks the real `colr` / codec rather than the manifest string), so the `SUBTITLES` renditions do not travel there. The separate `#35` cold-DV-start readiness gate, whose scenario is an HDR TV, first tries an HDR-preserving reduced master (`SUPPLEMENTAL-CODECS` dropped so it is plain HDR10, source range and `SUBTITLES` group kept) before the bare media playlist, so a cold DV start keeps HDR10 plus subtitles instead of dropping straight to subtitle-less media.
+**Master-rejection fallback (#98, #130).** When AVPlayer rejects the served master (`-11868` AVErrorNoCompatibleAlternatesForExternalDisplay, `-11848` for an SDR-parked panel, or `-1002` when every variant was filtered at master parse time), the engine reloads the bare media playlist in place; a VOD session comes back where the refused item was placed (after a stage-2 recovery reload, that is the recovered position, not the session's first start), and a live session rejoins at the edge instead of replaying its stale start position. HDR / DV on an SDR external display is therefore media-playlist-driven (an AVKit limitation: forcing `VIDEO-RANGE=SDR` does not fool the external-display compatibility gate, which checks the real `colr` / codec rather than the manifest string), so the `SUBTITLES` renditions do not travel there. The separate `#35` cold-DV-start readiness gate, whose scenario is an HDR TV, first tries an HDR-preserving reduced master (`SUPPLEMENTAL-CODECS` dropped so it is plain HDR10, source range and `SUBTITLES` group kept) before the bare media playlist, so a cold DV start keeps HDR10 plus subtitles instead of dropping straight to subtitle-less media.
 
 **Rich ASS styling.** With `LoadOptions.preserveASSMarkup` the tap keeps raw ASS event lines so the host overlay renders full styling (positions, colours); the WebVTT renditions strip the markup at serve time, so PiP shows plain text in the system caption style.
 

From 1630b23c6f3f7954413c939b0c81dfa6c51ae89a Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 24 Sep 2026 19:14:58 +0200
Subject: [PATCH 021/359] docs(readme): the measured block gains an HTTP arm, a
 90 Mbit/s fixture and peak footprint

Regenerated from aetherengine-bench's 2026-09-24 session on 7.15.2. Every
engine now plays each file from disk and over HTTP from a range origin at
1000 Mbit/s and 20 ms, at 38 and 90 Mbit/s, with a peak footprint column.
The previous block was measured with 6.26.0, from disk only, and could not
show what #620 changed in the HTTP reader.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 README.md | 77 +++++++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 58 insertions(+), 19 deletions(-)

diff --git a/README.md b/README.md
index 5650b45fb..5eb9654db 100644
--- a/README.md
+++ b/README.md
@@ -99,33 +99,72 @@ The engine leans on the platform where the platform is best (hardware decode, Do
 
 ### Measured
 
-The table above is qualitative. The numbers below are measured, on a 4K HDR HEVC file in Matroska, the container media servers actually serve. They are produced by [aetherengine-bench](https://github.com/superuser404notfound/aetherengine-bench), which is run by this project's author, so its method, its raw data and the cases where AetherEngine does not win are all in that repository.
+The table above is qualitative. The numbers below are measured on 4K HDR HEVC in Matroska, the container media servers actually serve, at 38 Mbit/s and at 90 Mbit/s, the rate of a UHD remux. Every engine plays each file twice: from local disk, and over HTTP from a local range origin with a fixed latency and a shared link rate, because media servers deliver over HTTP and an engine's network reader is not its file reader. They are produced by [aetherengine-bench](https://github.com/superuser404notfound/aetherengine-bench), which is run by this project's author, so its method, its raw data and the cases where AetherEngine does not win are all in that repository. AVPlayer does not open Matroska at all; on MP4, the one container it plays, it uses less than every engine here, see that repository's README.
 
-Measured on Apple-M1 (MacBookAir10,1), macOS 26.5.2, hevc-4k-hdr10.mkv, windowed, 3840x2160 px rendered, 60 s, median of 2.
+Measured on Apple-M1 (MacBookAir10,1), macOS 27.0, hevc-4k-hdr10.mkv (38 Mbit/s), hevc-4k-hdr10-90m.mkv (90 Mbit/s), each from local disk and over HTTP from a local range origin at 1000 Mbit/s shared, 20 ms latency per request, windowed, 3840x2160 px rendered, 60 s, median of 2.
 MacBookAir10,1 is fanless: sustained decode can reach thermal pressure, which is why the protocol has cooldowns between runs and discards throttled windows.
 
-| | GPU power | CPU load | RSS | Plays |
-| --- | --- | --- | --- | --- |
-| **AetherEngine** | 63 mW | 5.2% of a core | 325 MB | Yes |
-| **KSPlayer** | 149 mW | 6.6% of a core | 331 MB | Yes |
-| **AVPlayer** | | | | n/a (refuses hevc-4k-hdr10.mkv: This media format is not supported.) |
-| **VLCKit** | 362 mW | 14.3% of a core | 102 MB | Yes |
-| **libmpv** | 887 mW | 18.1% of a core | 373 MB | Yes |
-
-Launch failures on hevc-4k-hdr10.mkv (crashes that were retried, not refusals, see the README): KSPlayer 1.
+**hevc-4k-hdr10.mkv (38 Mbit/s)**
+
+| | Source | GPU power | CPU load | RSS | Peak footprint | Plays |
+| --- | --- | --- | --- | --- | --- | --- |
+| **AetherEngine** | disk | 41 mW | 4.4% of a core | 342 MB | 323 MB | Yes |
+| | HTTP | 40 mW | 5.4% of a core | 336 MB | 350 MB | Yes |
+| **KSPlayer** | disk | 43 mW | 5.8% of a core | 333 MB | 772 MB | Yes |
+| | HTTP | 41 mW | 6.4% of a core | 357 MB | 496 MB | Yes |
+| **AVPlayer** | disk | | | | | n/a (refuses hevc-4k-hdr10.mkv: This media format is not supported.) |
+| | HTTP | | | | | n/a (refuses hevc-4k-hdr10.mkv: This media format is not supported.) |
+| **VLCKit** | disk | 266 mW | 15.0% of a core | 111 MB | 281 MB | Yes |
+| | HTTP | 244 mW | 17.0% of a core | 122 MB | 300 MB | Yes |
+| **libmpv** | disk | 887 mW | 20.7% of a core | 475 MB | 933 MB | Yes |
+| | HTTP | 892 mW | 21.5% of a core | 629 MB | 1191 MB | Yes |
+
+Launch failures on hevc-4k-hdr10.mkv (crashes that were retried, not refusals, see the README): KSPlayer 1 (HTTP).
+
+**hevc-4k-hdr10-90m.mkv (90 Mbit/s)**
+
+| | Source | GPU power | CPU load | RSS | Peak footprint | Plays |
+| --- | --- | --- | --- | --- | --- | --- |
+| **AetherEngine** | disk | 40 mW | 6.6% of a core | 577 MB | 681 MB | Yes |
+| | HTTP | 40 mW | 9.3% of a core | 557 MB | 700 MB | Yes |
+| **KSPlayer** | disk | 41 mW | 6.7% of a core | 589 MB | 1040 MB | Yes |
+| | HTTP | 41 mW | 7.6% of a core | 578 MB | 703 MB | Yes |
+| **AVPlayer** | disk | | | | | n/a (refuses hevc-4k-hdr10-90m.mkv: This media format is not supported.) |
+| | HTTP | | | | | n/a (refuses hevc-4k-hdr10-90m.mkv: This media format is not supported.) |
+| **VLCKit** | disk | 235 mW | 16.2% of a core | 117 MB | 314 MB | Yes |
+| | HTTP | 235 mW | 18.4% of a core | 135 MB | 325 MB | Yes |
+| **libmpv** | disk | 953 mW | 21.5% of a core | 501 MB | 980 MB | Yes |
+| | HTTP | 962 mW | 22.3% of a core | 684 MB | 1188 MB | Yes |
+
+Launch failures on hevc-4k-hdr10-90m.mkv (crashes that were retried, not refusals, see the README): KSPlayer 4 (disk).
 
 Frame delivery and output (median; resolution, bit depth and HDR transfer are informational per engine only, shown as 'varies across repeats' when they disagree, see the README):
-- **AetherEngine**: 1440/1438 delivered/expected, dropped 0, 3840x1714, 10-bit, hdr10, rendered into 3840x2160.
-- **KSPlayer**: 1440/1440 delivered/expected, dropped 0, 3840x1714, 10-bit, SMPTE_ST_2084_PQ, rendered into 3840x2160. Served via **KSMEPlayer**.
-- **VLCKit**: 1442/1440 delivered/expected, dropped 0, 3840x1714, bit depth and color transfer not reported by this engine, rendered into 3840x2160.
-- **libmpv**: 1442/1440 delivered/expected, dropped 0, 3840x1714, 10-bit, pq, rendered into 3840x2160.
-
-Versions: AetherEngine 6.26.0, KSPlayer 2.3.4, AVPlayer macOS 26.5.2, VLCKit 4.0.0-alpha.21, libmpv mpv v0.41.0.
+*hevc-4k-hdr10.mkv*
+- **AetherEngine, disk**: 1438/1438 delivered/expected, dropped 0, 3840x1714, 10-bit, hdr10, rendered into 3840x2160.
+- **AetherEngine, HTTP**: 1441/1438 delivered/expected, dropped 0, 3840x1714, 10-bit, hdr10, rendered into 3840x2160.
+- **KSPlayer, disk**: 1440/1440 delivered/expected, dropped 0, 3840x1714, 10-bit, SMPTE_ST_2084_PQ, rendered into 3840x2160. Served via **KSMEPlayer**.
+- **KSPlayer, HTTP**: 1440/1440 delivered/expected, dropped 0, 3840x1714, 10-bit, SMPTE_ST_2084_PQ, rendered into 3840x2160. Served via **KSMEPlayer**.
+- **VLCKit, disk**: 1451/1440 delivered/expected, dropped 0, 3840x1714, bit depth and color transfer not reported by this engine, rendered into 3840x2160.
+- **VLCKit, HTTP**: 1454/1440 delivered/expected, dropped 0, 3840x1714, bit depth and color transfer not reported by this engine, rendered into 3840x2160.
+- **libmpv, disk**: 1443/1440 delivered/expected, dropped 0, 3840x1714, 10-bit, pq, rendered into 3840x2160.
+- **libmpv, HTTP**: 1443/1440 delivered/expected, dropped 0, 3840x1714, 10-bit, pq, rendered into 3840x2160.
+*hevc-4k-hdr10-90m.mkv*
+- **AetherEngine, disk**: 1436/1438 delivered/expected, dropped 0, 3840x1714, 10-bit, hdr10, rendered into 3840x2160.
+- **AetherEngine, HTTP**: 1439/1438 delivered/expected, dropped 0, 3840x1714, 10-bit, hdr10, rendered into 3840x2160.
+- **KSPlayer, disk**: 1440/1440 delivered/expected, dropped 0, 3840x1714, 10-bit, SMPTE_ST_2084_PQ, rendered into 3840x2160. Served via **KSMEPlayer**.
+- **KSPlayer, HTTP**: 1440/1440 delivered/expected, dropped 0, 3840x1714, 10-bit, SMPTE_ST_2084_PQ, rendered into 3840x2160. Served via **KSMEPlayer**.
+- **VLCKit, disk**: 1454/1440 delivered/expected, dropped 0, 3840x1714, bit depth and color transfer not reported by this engine, rendered into 3840x2160.
+- **VLCKit, HTTP**: 1452/1440 delivered/expected, dropped 0, 3840x1714, bit depth and color transfer not reported by this engine, rendered into 3840x2160.
+- **libmpv, disk**: 1442/1440 delivered/expected, dropped 0, 3840x1714, 10-bit, pq, rendered into 3840x2160.
+- **libmpv, HTTP**: 1443/1440 delivered/expected, dropped 0, 3840x1714, 10-bit, pq, rendered into 3840x2160.
+
+Versions: AetherEngine 7.15.2, KSPlayer 2.3.4, AVPlayer macOS 27.0, VLCKit 4.0.0-alpha.21, libmpv mpv v0.41.0.
 
 Power figures are package power with an idle baseline subtracted, so they are attributable to the run and not to the machine.
-CPU package power was measured for every run but is not published above: the idle baseline drifts with load enough that one engine's own repeats can disagree more than the column would be used to show between engines. For example, on hevc-4k-hdr10.mkv libmpv measured 100 to 372 mW of CPU package power across its own repeats, a 3.7x range. Recorded for every run in Results/; see "Known gaps" in the README for the full reasoning.
+CPU package power was measured for every run but is not published above: the idle baseline drifts with load enough that one engine's own repeats can disagree more than the column would be used to show between engines. For example, on hevc-4k-hdr10.mkv KSPlayer measured 76 to 267 mW of CPU package power across its own repeats, a 3.5x range. Recorded for every run in Results/; see "Known gaps" in the README for the full reasoning.
 libmpv is measured with --hwdec=auto-safe (hardware decode), not mpv's own software-decode default, see "Fairness decisions" in the README.
-libmpv's rows come from a separate run of the same protocol on the same day and the same machine. Its rows in the main run were lost to a defect in the mpv report writer (a missing import), not to anything about mpv itself. The GPU idle baseline on this machine is under 1 mW, and CPU load and RSS are not baseline-subtracted at all, so a separate baseline does not move the three published columns.
+Peak footprint is the kernel's lifetime maximum of the player process's physical footprint (what the system's memory limit acts on), load phase included; RSS is the mean over the measured window. Decoding that happens in a system service (VideoToolbox) is in neither.
+The hevc-4k-hdr10-90m.mkv rows come from a second run of the same protocol, build and origin on the same day and machine. A tvOS Simulator had been left running in the background for the first half of the main run, which raised idle package power to 188 to 214 mW (19 to 26 mW once it was shut down). Both hevc-4k-hdr10-90m.mkv baselines failed validation under it, so that fixture was measured again. The hevc-4k-hdr10.mkv baselines were taken under it too and passed; the GPU idle baseline stayed under 0.05 mW throughout, and CPU load, RSS and footprint are not baseline-subtracted, so none of the published columns moved with it.
 Method and raw results: https://github.com/superuser404notfound/aetherengine-bench
 
 ## Quick start

From e13c23265c84f01c3b3075c758328c68db1af1f7 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 24 Sep 2026 19:58:48 +0200
Subject: [PATCH 022/359] feat(clock): sourceTimeFollowsPicture says when the
 remote-HLS lead is only a guess

On nativeRemoteHLS a time jump keeps the previous lead until the next injected line re-measures it,
so for those first seconds sourceTime is off by however far the new anchor moved (imbenjamin measured
-1.50 s to -1.79 s on the lines right after a landing). The clock now says so: false from a time
jump, or for a whole session without an injected rendition, true once a line matched. Every other
route stays true. Hosts can hold their overlay on it instead of detecting seeks themselves.

Refs #616

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 CHANGELOG.md                                  |  3 ++-
 .../AetherEngine/AetherEngine+Loading.swift   | 24 +++++++++++++------
 Sources/AetherEngine/AetherEngine.swift       |  4 ++++
 .../Native/RemoteHLSCueClock.swift            |  6 +++++
 .../Native/RemoteHLSCueClockObserver.swift    | 12 ++++++++--
 Sources/AetherEngine/PlaybackClock.swift      |  8 +++++++
 .../RemoteHLSCueClockTests.swift              | 15 ++++++++++++
 docs/api.md                                   |  7 ++++--
 8 files changed, 67 insertions(+), 12 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index a8358760c..cb7657e83 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,7 +10,8 @@ the public-API contract.
 
 ## [Unreleased]
 
-_Nothing yet._
+### Added
+- `clock.sourceTimeFollowsPicture` (and the `sourceTimeFollowsPicture` mirror): false on `nativeRemoteHLS` from a time jump until an injected rendition line has re-measured the lead, so a host can hold its overlay across that window instead of detecting seeks itself (AE#616 follow-up).
 
 ## [7.15.2] - 2026-09-24
 
diff --git a/Sources/AetherEngine/AetherEngine+Loading.swift b/Sources/AetherEngine/AetherEngine+Loading.swift
index 387113274..1552b14e7 100644
--- a/Sources/AetherEngine/AetherEngine+Loading.swift
+++ b/Sources/AetherEngine/AetherEngine+Loading.swift
@@ -566,21 +566,31 @@ extension AetherEngine {
     /// Without injected renditions nothing is measurable and `sourceTime` stays item time.
     private func attachRemoteHLSCueClock(host: NativeAVPlayerHost, expectedGeneration: UInt64) {
         detachRemoteHLSCueClock()
+        // Item time until a line says otherwise, and for the whole session without injected renditions.
+        clock.sourceTimeFollowsPicture = false
         guard let provider = remoteHLSSubtitleProxy?.provider,
               let item = host.currentPlayerItem else { return }
-        remoteHLSCueClock = RemoteHLSCueClockObserver(item: item, provider: provider) { [weak self] offset in
-            guard let self, self.loadGeneration == expectedGeneration else { return }
-            self.remoteHLSItemOffset = offset
-            if let rendered = self.nativeHost?.renderedTime {
-                self.clock.sourceTime = max(0, rendered - offset)
-            }
-        }
+        remoteHLSCueClock = RemoteHLSCueClockObserver(
+            item: item, provider: provider,
+            onOffset: { [weak self] offset in
+                guard let self, self.loadGeneration == expectedGeneration else { return }
+                self.remoteHLSItemOffset = offset
+                if let rendered = self.nativeHost?.renderedTime {
+                    self.clock.sourceTime = max(0, rendered - offset)
+                }
+                self.clock.sourceTimeFollowsPicture = true
+            },
+            onTimeJump: { [weak self] in
+                guard let self, self.loadGeneration == expectedGeneration else { return }
+                self.clock.sourceTimeFollowsPicture = false
+            })
     }
 
     func detachRemoteHLSCueClock() {
         remoteHLSCueClock?.detach()
         remoteHLSCueClock = nil
         remoteHLSItemOffset = 0
+        clock.sourceTimeFollowsPicture = true
     }
 
     /// Stand a loopback origin in front of the remote master and return the URL AVPlayer should open.
diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index b514a18d8..43132b0c9 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -1981,6 +1981,10 @@ public final class AetherEngine: ObservableObject {
     /// offset by the session zero on live / mid-stream-joined sources (#107). Forwarder; subscribe to `clock.$sourceTime`.
     public var sourceTime: Double { clock.sourceTime }
 
+    /// Whether `sourceTime` is known to follow the displayed frame (AE#616). Forwarder; subscribe to
+    /// `clock.$sourceTimeFollowsPicture`.
+    public var sourceTimeFollowsPicture: Bool { clock.sourceTimeFollowsPicture }
+
     /// Source-axis buffer frontier ahead of the playhead (AetherEngine#54). Forwarder; subscribe to `clock.$bufferedPosition`.
     public var bufferedPosition: Double { clock.bufferedPosition }
 
diff --git a/Sources/AetherEngine/Native/RemoteHLSCueClock.swift b/Sources/AetherEngine/Native/RemoteHLSCueClock.swift
index 33accd549..af423f917 100644
--- a/Sources/AetherEngine/Native/RemoteHLSCueClock.swift
+++ b/Sources/AetherEngine/Native/RemoteHLSCueClock.swift
@@ -22,6 +22,10 @@ struct RemoteHLSCueClock {
     /// Item seconds minus media seconds of the presented frame. Nil until the first line is matched.
     private(set) var offset: Double?
 
+    /// Whether `offset` was measured since the last time jump. A jump keeps the previous offset as the
+    /// best guess, but the anchor may have moved, so until the next matched line it is only a guess.
+    private(set) var isMeasuredSinceJump = false
+
     private var startsByText: [String: [Double]] = [:]
     private var presented: Set<String> = []
     /// The first delivery after a time jump reports whatever is active at the landing, stamped with
@@ -44,6 +48,7 @@ struct RemoteHLSCueClock {
     mutating func noteTimeJump() {
         presented = []
         skipNextDelivery = true
+        isMeasuredSinceJump = false
     }
 
     /// Feed one legible-output delivery. Returns the new offset when this delivery measured one.
@@ -75,6 +80,7 @@ struct RemoteHLSCueClock {
         guard let measured = unique ?? ambiguous.min(by: { abs($0 - reference) < abs($1 - reference) })
         else { return nil }
         offset = measured
+        isMeasuredSinceJump = true
         return measured
     }
 
diff --git a/Sources/AetherEngine/Native/RemoteHLSCueClockObserver.swift b/Sources/AetherEngine/Native/RemoteHLSCueClockObserver.swift
index ce88a58ae..e2cbacf84 100644
--- a/Sources/AetherEngine/Native/RemoteHLSCueClockObserver.swift
+++ b/Sources/AetherEngine/Native/RemoteHLSCueClockObserver.swift
@@ -16,11 +16,15 @@ final class RemoteHLSCueClockObserver: NSObject, AVPlayerItemLegibleOutputPushDe
     private var clock = RemoteHLSCueClock()
     private var jumpObserver: NSObjectProtocol?
     private let onOffset: @MainActor (Double) -> Void
+    private let onTimeJump: @MainActor () -> Void
 
-    init(item: AVPlayerItem, provider: RemoteHLSSubtitleProvider, onOffset: @escaping @MainActor (Double) -> Void) {
+    init(item: AVPlayerItem, provider: RemoteHLSSubtitleProvider,
+         onOffset: @escaping @MainActor (Double) -> Void,
+         onTimeJump: @escaping @MainActor () -> Void) {
         self.item = item
         self.provider = provider
         self.onOffset = onOffset
+        self.onTimeJump = onTimeJump
         super.init()
         output.suppressesPlayerRendering = false
         output.advanceIntervalForDelegateInvocation = 0
@@ -29,7 +33,11 @@ final class RemoteHLSCueClockObserver: NSObject, AVPlayerItemLegibleOutputPushDe
         jumpObserver = NotificationCenter.default.addObserver(
             forName: AVPlayerItem.timeJumpedNotification, object: item, queue: .main
         ) { [weak self] _ in
-            MainActor.assumeIsolated { self?.clock.noteTimeJump() }
+            MainActor.assumeIsolated {
+                guard let self else { return }
+                self.clock.noteTimeJump()
+                self.onTimeJump()
+            }
         }
     }
 
diff --git a/Sources/AetherEngine/PlaybackClock.swift b/Sources/AetherEngine/PlaybackClock.swift
index 5b1b6feea..dee6e843a 100644
--- a/Sources/AetherEngine/PlaybackClock.swift
+++ b/Sources/AetherEngine/PlaybackClock.swift
@@ -19,6 +19,14 @@ public final class PlaybackClock: ObservableObject {
     /// against, and this is item time, which can run ahead of the frame after a seek on such an origin.
     @Published public internal(set) var sourceTime: Double = 0
 
+    /// Whether `sourceTime` is known to follow the displayed frame. True on every route but
+    /// `nativeRemoteHLS`. There (AE#616) it turns true when a presented line of an injected rendition
+    /// measured the lead, and false again at every time jump (seek, item change): until the next line,
+    /// `sourceTime` carries the previous lead, which is off by however far the new anchor moved. False
+    /// for the whole session without an injected rendition selected. A host timing its own overlay off
+    /// `sourceTime` can hold it while this is false instead of detecting seeks itself.
+    @Published public internal(set) var sourceTimeFollowsPicture: Bool = true
+
     @Published public internal(set) var progress: Float = 0
 
     /// Largest session-relative time reached on a live source. 0 when not live.
diff --git a/Tests/AetherEngineTests/RemoteHLSCueClockTests.swift b/Tests/AetherEngineTests/RemoteHLSCueClockTests.swift
index 5bace755f..5cd5d1224 100644
--- a/Tests/AetherEngineTests/RemoteHLSCueClockTests.swift
+++ b/Tests/AetherEngineTests/RemoteHLSCueClockTests.swift
@@ -98,4 +98,19 @@ struct RemoteHLSCueClockTests {
         let measured = c.observe(strings: ["Origin's own rendition"], itemTime: 31.0)
         #expect(measured == nil)
     }
+
+    @Test("A time jump marks the kept offset as unmeasured until the next matched line")
+    func timeJumpClearsMeasuredUntilNextLine() {
+        var c = clock([(1490.0, "Where were you?"), (1800.0, "Run.")])
+        #expect(!c.isMeasuredSinceJump)
+        _ = c.observe(strings: ["Where were you?"], itemTime: 1491.209)
+        #expect(c.isMeasuredSinceJump)
+        c.noteTimeJump()
+        #expect(!c.isMeasuredSinceJump)
+        #expect(c.offset.map { abs($0 - 1.209) < 1e-9 } == true)
+        _ = c.observe(strings: [], itemTime: 1790.0)
+        #expect(!c.isMeasuredSinceJump)
+        _ = c.observe(strings: ["Run."], itemTime: 1803.086)
+        #expect(c.isMeasuredSinceJump)
+    }
 }
diff --git a/docs/api.md b/docs/api.md
index 58b832dc5..9130ef259 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -534,11 +534,12 @@ Time lives on `player.clock`, a separate `ObservableObject`, so ~10 Hz ticks nev
 | --- | --- |
 | `clock.$currentTime` | playback clock, the scrubber axis |
 | `clock.$sourceTime` | source PTS of the displayed frame; render subtitle overlays against this. On `nativeRemoteHLS` it is item time, corrected by the lead over the picture the engine measures on its injected #316 renditions while one is selected (AE#616); see below the table. |
+| `clock.$sourceTimeFollowsPicture` | whether `sourceTime` is known to follow the displayed frame. Always true except on `nativeRemoteHLS`, where it is true only while the lead is measured since the last time jump (AE#616); see below the table. |
 | `clock.$progress` | `currentTime / duration` |
 | `clock.$bufferedPosition` | source-axis position buffered ahead |
 | `clock.$liveEdgeTime`, `clock.$seekableLiveRange`, `clock.$behindLiveSeconds`, `clock.$isAtLiveEdge` | live-window surfaces. `seekableLiveRange` is the intersection of the DVR window (policy) and what the segment cache actually holds and can play forward from (fact), so it is honest to scale a rewind strip on and `seek(to:)` clamps to the same floor (AE#441). The two diverge for the whole first `dvrWindowSeconds` of a session and again whenever retention evicts faster than the window slides. Software live sessions have no such cache and keep the arithmetic bound. |
 | `$residentRanges` | where the loopback segment cache holds picture right now, as disjoint ascending spans on the `currentTime` axis. This is the cache's own truth, not AVPlayer's `loadedTimeRanges`: a measured session held 64 segments over four minutes across several islands while AVPlayer exposed roughly twelve seconds around the playhead and forgot a seeked-ahead island as soon as the playhead left it. Empty is the nil-equivalent, and a live session publishes empty always (its rewind depth is `seekableLiveRange`, which answers a different question). Residency is not a promise that a seek inside a span is instant: the player may still re-anchor and decode at the target, and a segment can start mid-GOP (AE#412). Coalesced to at most four updates a second, cleared on `load()` and teardown. |
-| `player.currentTime`, `sourceTime`, `progress`, `bufferedPosition`, `liveEdgeTime`, `seekableLiveRange`, `behindLiveSeconds`, `isAtLiveEdge` | non-published mirrors of the same values for one-shot reads |
+| `player.currentTime`, `sourceTime`, `sourceTimeFollowsPicture`, `progress`, `bufferedPosition`, `liveEdgeTime`, `seekableLiveRange`, `behindLiveSeconds`, `isAtLiveEdge` | non-published mirrors of the same values for one-shot reads |
 | `$duration` | seconds; a `LoadOptions.declaredDurationSeconds` outranks the container's |
 
 **`sourceTime` on `nativeRemoteHLS` (AE#616).** The engine sees no segment on that route, so the clock is
@@ -551,7 +552,9 @@ AVPlayer's legible output at its cue start plus that lead. The engine watches it
 non-suppressing legible output, matches each presented line back to the cue it wrote, and publishes
 `sourceTime` as item time less the measured lead (log line `AE#616: item time leads the presented
 frame by ...`). It re-measures on every line; between a seek and the next line it keeps the previous
-value. Without an injected rendition selected nothing is measured and `sourceTime` is item time.
+value, and `clock.sourceTimeFollowsPicture` is false from the time jump until that line, so a host can
+hold its overlay instead of detecting seeks itself. Without an injected rendition selected nothing is
+measured, `sourceTime` is item time and `sourceTimeFollowsPicture` stays false.
 `currentTime`, `seek(to:)` and the scrubber stay on item time throughout, so a seek round-trips. A host
 drawing its own overlay from `sourceTime` (libass) can keep the rendition selected behind its own
 suppressing `AVPlayerItemLegibleOutput` to keep the measurement running.

From 8f8533d48369713d9b0f213522fda92705d279f6 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 24 Sep 2026 20:59:18 +0200
Subject: [PATCH 023/359] fix(diag): an IPTV password in a bare path segment is
 still a credential

The Xtream Codes stream layout puts the account password in the path of
every stream URL (/live/{user}/{password}/{id}.ts, likewise /movie/,
/series/, /timeshift/, and the /hls/ and /hlsr/ redirect targets), with
no name, no userinfo and no encoding, so none of LogRedaction's three
matchers saw it and `load url=` lines carried it in clear text into
os_log and the host handler.

The layout is now matched: the credential segment goes, the user name
stays, and a candidate segment only counts when another path segment
follows it, which is what keeps /live/master.m3u8 and
/live/channel1/index.m3u8 whole.

The short form (/{user}/{password}/{id}) has no layout to go by, nor does
a provider shape nobody has seen yet, so EngineLog.registerSecret(_:)
lets a host name the value itself; it is matched literally, raw and
percent-encoded, anywhere in the line. Values under four bytes are
refused, they would black out ordinary text.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 .../AetherEngine/Diagnostics/EngineLog.swift  |  17 +++
 .../Diagnostics/LogRedaction.swift            | 134 +++++++++++++++++-
 .../AetherEngineTests/LogRedactionTests.swift |  42 ++++++
 docs/api.md                                   |   1 +
 4 files changed, 191 insertions(+), 3 deletions(-)

diff --git a/Sources/AetherEngine/Diagnostics/EngineLog.swift b/Sources/AetherEngine/Diagnostics/EngineLog.swift
index 2d39341fa..3f1d91ac9 100644
--- a/Sources/AetherEngine/Diagnostics/EngineLog.swift
+++ b/Sources/AetherEngine/Diagnostics/EngineLog.swift
@@ -28,6 +28,23 @@ public enum EngineLog {
     private static let handlerLock = NSLock()
     nonisolated(unsafe) private static var _handler: ((String) -> Void)?
 
+    /// Names a value that must never appear in a log line, such as an IPTV account password the host
+    /// holds. Every line then has that exact value (and its percent-encoded form) replaced before it
+    /// reaches OSLog or `handler`, wherever it sits. The engine already strips the credential shapes it
+    /// can recognise (named parameters, userinfo, encoded payloads, the Xtream Codes path layout); this
+    /// is for the ones only the host knows, such as a provider URL that carries the password as a bare
+    /// path segment. Returns false, and registers nothing, for a value shorter than four bytes, which
+    /// would black out ordinary text. Thread-safe.
+    @discardableResult
+    public static func registerSecret(_ value: String) -> Bool {
+        LogRedaction.register(value)
+    }
+
+    /// Stops redacting a value passed to `registerSecret(_:)`, for example on logout.
+    public static func unregisterSecret(_ value: String) {
+        LogRedaction.unregister(value)
+    }
+
     public static let subsystem: String = "de.superuser404.AetherEngine"
 
     private static let loggers: [Category: Logger] = {
diff --git a/Sources/AetherEngine/Diagnostics/LogRedaction.swift b/Sources/AetherEngine/Diagnostics/LogRedaction.swift
index d967f7086..5aff5db1c 100644
--- a/Sources/AetherEngine/Diagnostics/LogRedaction.swift
+++ b/Sources/AetherEngine/Diagnostics/LogRedaction.swift
@@ -13,6 +13,12 @@ import Foundation
 /// nothing in the URL names it. The list of names cannot be extended to reach that one, because the
 /// names live inside the payload, so the encoding itself has to be the signal (`encodedPayloadRange`).
 ///
+/// IPTV panels speaking the Xtream Codes API put the account's password in the path with no name and
+/// no encoding at all (`/live/{user}/{password}/{id}.ts`), so the layout is the only signal there
+/// (`xtreamPathSecretRange`). Its short form (`/{user}/{password}/{id}`) has no layout to go by, and
+/// neither does a provider shape nobody has reported yet; for those the host names the value itself
+/// through `EngineLog.registerSecret(_:)`, which is matched literally (`registeredSecretRange`).
+///
 /// That makes it the engine's problem rather than each host's: the engine composes the line, it reaches
 /// three sinks a host does not control, and a host-side scrub only ever covers the one sink it owns.
 ///
@@ -42,6 +48,7 @@ enum LogRedaction {
     /// segment producer, so anything per-line here is per-line everywhere.
     static func redact(_ line: String) -> String {
         let bytes = Array(line.utf8)
+        let secrets = registeredSecrets
         var out: [UInt8]?
         var copiedUpTo = 0
         var i = 0
@@ -50,11 +57,14 @@ enum LogRedaction {
             // Three shapes, because a credential does not always arrive next to a name. The key
             // matcher covers `api_key=…`, `X-Emby-Token: …` and the cookie; the payload matcher covers
             // an encoded blob that no name points at, which is how a path segment carries one; the
-            // userinfo matcher covers `smb://user:secret@host`, where it sits in the authority.
-            guard let value = matchedKeyLength(in: bytes, at: i)
+            // userinfo matcher covers `smb://user:secret@host`, where it sits in the authority; the
+            // path matcher covers the Xtream layout; a registered secret is found wherever it sits.
+            guard let value = registeredSecretRange(in: bytes, at: i, secrets: secrets)
+                    ?? matchedKeyLength(in: bytes, at: i)
                     .flatMap({ valueRange(in: bytes, after: i + $0) })
                     ?? encodedPayloadRange(in: bytes, at: i)
-                    ?? userInfoSecretRange(in: bytes, at: i) else {
+                    ?? userInfoSecretRange(in: bytes, at: i)
+                    ?? xtreamPathSecretRange(in: bytes, at: i) else {
                 i += 1
                 continue
             }
@@ -151,6 +161,124 @@ enum LogRedaction {
         return secretStart < i ? secretStart ..< i : nil
     }
 
+    // MARK: Registered secrets
+
+    /// Shortest value `register` accepts. A literal match has no context to go by, so a one- or
+    /// two-byte value would black out every occurrence of that text in every line.
+    static let minimumSecretLength = 4
+
+    private static let secretsLock = NSLock()
+    nonisolated(unsafe) private static var _secrets: [String: [UInt8]] = [:]
+
+    /// Snapshot taken once per line, so a register racing a redact sees the old set or the new one,
+    /// never half of it. Sorted longest first, so a secret that contains another goes whole.
+    private static var registeredSecrets: [[UInt8]] {
+        secretsLock.lock(); defer { secretsLock.unlock() }
+        return _secrets.isEmpty ? [] : _secrets.values.sorted { $0.count > $1.count }
+    }
+
+    /// Registers the value and its percent-encoded form, which is how it appears inside a URL path or
+    /// query when it holds a character a URL cannot carry raw. Returns false for a value too short to
+    /// match literally.
+    @discardableResult
+    static func register(_ secret: String) -> Bool {
+        let forms = literalForms(of: secret)
+        guard !forms.isEmpty else { return false }
+        secretsLock.lock(); defer { secretsLock.unlock() }
+        for form in forms { _secrets[form] = Array(form.utf8) }
+        return true
+    }
+
+    static func unregister(_ secret: String) {
+        let forms = literalForms(of: secret)
+        secretsLock.lock(); defer { secretsLock.unlock() }
+        for form in forms { _secrets[form] = nil }
+    }
+
+    static func unregisterAll() {
+        secretsLock.lock(); defer { secretsLock.unlock() }
+        _secrets.removeAll()
+    }
+
+    private static func literalForms(of secret: String) -> Set<String> {
+        guard secret.utf8.count >= minimumSecretLength else { return [] }
+        var forms: Set<String> = [secret]
+        if let encoded = secret.addingPercentEncoding(withAllowedCharacters: .urlPathAllowed) { forms.insert(encoded) }
+        if let encoded = secret.addingPercentEncoding(withAllowedCharacters: .alphanumerics) { forms.insert(encoded) }
+        return forms
+    }
+
+    /// The span of a registered secret starting here, or nil. Exact bytes, no boundary rule: the host
+    /// said this value must never be logged, so it goes even inside a longer word.
+    private static func registeredSecretRange(in bytes: [UInt8], at index: Int, secrets: [[UInt8]]) -> Range<Int>? {
+        for secret in secrets where index + secret.count <= bytes.count && bytes[index] == secret[0] {
+            var matched = true
+            for offset in 1 ..< secret.count where bytes[index + offset] != secret[offset] {
+                matched = false
+                break
+            }
+            if matched { return index ..< index + secret.count }
+        }
+        return nil
+    }
+
+    // MARK: Xtream Codes paths
+
+    /// Path prefixes of the Xtream Codes stream layout, each paired with the zero-based positions of
+    /// the segments after it that hold a credential. `/live/`, `/movie/`, `/series/` and `/timeshift/`
+    /// carry `{user}/{password}/...`; the HLS redirect targets carry a session token first, and
+    /// `/hlsr/` then repeats `{user}/{password}` behind it.
+    private static let xtreamLayouts: [(prefix: [UInt8], secretSegments: [Int])] = [
+        ("/live/", [1]), ("/movie/", [1]), ("/series/", [1]), ("/timeshift/", [1]),
+        ("/hls/", [0]), ("/hlsr/", [0, 2]),
+    ].map { (Array($0.0.utf8), $0.1) }
+
+    /// The span from the first credential segment through the last one, given an index that may
+    /// start one of `xtreamLayouts`' prefixes, or nil. The user name in front of the password is left
+    /// readable for the same reason as in `userInfoSecretRange`; on `/hlsr/` it sits between the token
+    /// and the password and goes with them, since one line yields one span.
+    ///
+    /// A credential segment only counts when a further path segment follows it, because that is what
+    /// the layout guarantees and what an ordinary HLS path lacks: `/live/master.m3u8` and
+    /// `/live/channel1/index.m3u8` stay whole. Over-redacting some other three-deep `/live/` path is
+    /// the accepted cost.
+    private static func xtreamPathSecretRange(in bytes: [UInt8], at index: Int) -> Range<Int>? {
+        guard bytes[index] == UInt8(ascii: "/") else { return nil }
+        for layout in xtreamLayouts where hasPrefix(layout.prefix, in: bytes, at: index) {
+            var segments: [Range<Int>] = []
+            var i = index + layout.prefix.count
+            let needed = layout.secretSegments.max()! + 2
+            while segments.count < needed {
+                let start = i
+                while i < bytes.count, bytes[i] != UInt8(ascii: "/"), !isPathTerminator(bytes[i]) { i += 1 }
+                guard i > start else { break }
+                segments.append(start ..< i)
+                guard i < bytes.count, bytes[i] == UInt8(ascii: "/") else { break }
+                i += 1
+            }
+            guard segments.count >= needed else { continue }
+            return segments[layout.secretSegments.min()!].lowerBound ..< segments[layout.secretSegments.max()!].upperBound
+        }
+        return nil
+    }
+
+    private static func hasPrefix(_ prefix: [UInt8], in bytes: [UInt8], at index: Int) -> Bool {
+        guard index + prefix.count <= bytes.count else { return false }
+        for offset in 0 ..< prefix.count where bytes[index + offset] != prefix[offset] { return false }
+        return true
+    }
+
+    /// Ends a URL path: the query, the fragment, or whatever the log line puts after the URL.
+    private static func isPathTerminator(_ b: UInt8) -> Bool {
+        switch b {
+        case UInt8(ascii: "?"), UInt8(ascii: "#"), UInt8(ascii: "\""), UInt8(ascii: "'"),
+             UInt8(ascii: ","), UInt8(ascii: ")"), UInt8(ascii: ">"), UInt8(ascii: " "), 0x09, 0x0A, 0x0D:
+            return true
+        default:
+            return false
+        }
+    }
+
     /// Ends an authority component. `@` is deliberately absent: it is what the scan is looking for.
     private static func isAuthorityTerminator(_ b: UInt8) -> Bool {
         switch b {
diff --git a/Tests/AetherEngineTests/LogRedactionTests.swift b/Tests/AetherEngineTests/LogRedactionTests.swift
index 2ef55888a..243023f7c 100644
--- a/Tests/AetherEngineTests/LogRedactionTests.swift
+++ b/Tests/AetherEngineTests/LogRedactionTests.swift
@@ -170,6 +170,48 @@ struct LogRedactionTests {
         #expect(LogRedaction.redact(line) == line)
     }
 
+    @Test("an Xtream Codes path loses its password and keeps the account name", arguments: [
+        ("http://h:8080/live/john/S3cretPass/12345.m3u8", "http://h:8080/live/john/<redacted>/12345.m3u8"),
+        ("http://h:8080/movie/john/S3cretPass/678.mkv", "http://h:8080/movie/john/<redacted>/678.mkv"),
+        ("http://h:8080/series/john/S3cretPass/901.mkv", "http://h:8080/series/john/<redacted>/901.mkv"),
+        ("http://h:8080/timeshift/john/S3cretPass/60/2026-09-24:20-00/12345.ts",
+         "http://h:8080/timeshift/john/<redacted>/60/2026-09-24:20-00/12345.ts"),
+        ("http://h:8080/hls/a1b2c3d4e5/12345_3.ts", "http://h:8080/hls/<redacted>/12345_3.ts"),
+        ("http://h:8080/hlsr/a1b2c3d4e5/john/S3cretPass/12345/1/7.ts", "http://h:8080/hlsr/<redacted>/12345/1/7.ts"),
+    ])
+    func xtreamPath(url: String, expected: String) {
+        let line = LogRedaction.redact("[AetherEngine] load url=\(url) source-format=hls")
+        #expect(line == "[AetherEngine] load url=\(expected) source-format=hls")
+    }
+
+    @Test("an ordinary path under the same prefixes is left alone", arguments: [
+        "https://origin.example/live/master.m3u8",
+        "https://origin.example/live/channel1/index.m3u8",
+        "https://origin.example/movie/trailer.mp4",
+        "https://origin.example/live/ch1/index.m3u8?x=1",
+        "https://jellyfin.example/LiveTv/LiveStreamFiles/abc/stream.ts",
+    ])
+    func ordinaryPrefixedPathsSurvive(url: String) {
+        #expect(LogRedaction.redact("[x] url=\(url) ok") == "[x] url=\(url) ok")
+    }
+
+    @Test("a registered secret goes wherever it sits, raw or percent-encoded, until unregistered")
+    func registeredSecret() {
+        defer { LogRedaction.unregisterAll() }
+        #expect(EngineLog.registerSecret("p@ss w0rd"))
+        let raw = LogRedaction.redact("[x] http://h:8080/john/p%40ss%20w0rd/123 alt=p@ss w0rd.")
+        #expect(raw == "[x] http://h:8080/john/<redacted>/123 alt=<redacted>.")
+        EngineLog.unregisterSecret("p@ss w0rd")
+        #expect(LogRedaction.redact("[x] alt=p@ss w0rd") == "[x] alt=p@ss w0rd")
+    }
+
+    @Test("a value too short to match literally is refused")
+    func shortSecretRefused() {
+        defer { LogRedaction.unregisterAll() }
+        #expect(!EngineLog.registerSecret("abc"))
+        #expect(LogRedaction.redact("[x] abc") == "[x] abc")
+    }
+
     /// The point of putting this in EngineLog rather than in each host: the handler a host installs
     /// must never see the raw token, whether or not that host scrubs its own log.
     @Test("the host handler receives the redacted line")
diff --git a/docs/api.md b/docs/api.md
index 9130ef259..c12e71dfd 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -899,6 +899,7 @@ as well.
 | `EngineLog.handler` | Mirror every info-level line into a host capture path. Fires from whatever thread emitted it, so it must be thread-safe and non-blocking. |
 | `EngineLog.subsystem`, `EngineLog.Category` | `de.superuser404.AetherEngine`, one category per subsystem: `engine`, `ffmpeg`, `session`, `muxer`, `demux`, `hls.server`, `audio.bridge`, `sw.playback`, `scrub`. |
 | `EngineLog.Level` | `.info` reaches os_log and the host handler; `.verbose` is per-segment trace and reaches os_log's debug level **only**, never the handler, which is what keeps a mirrored stream readable. Read the verbose ones with `log stream --level debug`. |
+| `EngineLog.registerSecret(_:)`, `EngineLog.unregisterSecret(_:)` | Name a value that must never be logged, such as an IPTV password the host holds. Every line reaching os_log or the handler has it replaced, raw or percent-encoded, wherever it sits. The engine already strips named parameters, userinfo, encoded payloads and the Xtream Codes path layout on its own; this covers what only the host can know, such as a provider URL carrying the password as a bare path segment. Returns false for a value under four bytes. |
 | `EngineLog.emit(_:category:level:)` | Emit a host line into the same stream, for a host that wants its own events interleaved with the engine's. |
 | `segmentCacheDiskBytes`, `softwareHostFramesEnqueued` | Point reads for a stats overlay. |
 | `activeProducerShiftSeconds`, `frameAhead`, `clockLeadSeconds` | Divergence diagnostics for tracing a clock that disagrees with the picture. Not for production playback logic. |

From a3730c07d7d4fd0450170732f2abf4438dd46f8c Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 24 Sep 2026 21:00:23 +0200
Subject: [PATCH 024/359] chore(release): prep 7.16.0 - a host-registered
 secret, and an IPTV path that keeps its password to itself

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 CHANGELOG.md                                    | 8 ++++++++
 Examples/README.md                              | 2 +-
 README.md                                       | 6 +++---
 Sources/AetherEngine/AetherEngine+Version.swift | 2 +-
 4 files changed, 13 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index cb7657e83..294ebbc99 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,8 +10,16 @@ the public-API contract.
 
 ## [Unreleased]
 
+_Nothing yet._
+
+## [7.16.0] - 2026-09-24
+
 ### Added
 - `clock.sourceTimeFollowsPicture` (and the `sourceTimeFollowsPicture` mirror): false on `nativeRemoteHLS` from a time jump until an injected rendition line has re-measured the lead, so a host can hold its overlay across that window instead of detecting seeks itself (AE#616 follow-up).
+- `EngineLog.registerSecret(_:)` / `unregisterSecret(_:)`: a host names a value that must never be logged, and every line has it replaced, raw or percent-encoded, before it reaches os_log or the handler.
+
+### Security
+- **Log redaction covers credentials carried as plain path segments.** IPTV panels speaking the Xtream Codes API put the account password in the path of every stream URL (`/live/{user}/{password}/{id}.ts`, likewise `/movie/`, `/series/`, `/timeshift/`, and the `/hls/` and `/hlsr/` redirect targets), where no named parameter, userinfo or encoded payload points at it, so `load url=` lines carried it in clear text. The layout is now matched, the user name stays readable, and ordinary paths such as `/live/master.m3u8` are untouched. The short form without a prefix has no layout to match, which is what `registerSecret(_:)` is for.
 
 ## [7.15.2] - 2026-09-24
 
diff --git a/Examples/README.md b/Examples/README.md
index 0a047dcd4..ad27387b5 100644
--- a/Examples/README.md
+++ b/Examples/README.md
@@ -18,7 +18,7 @@ Three samples covering different audiences:
    ```
    https://github.com/superuser404notfound/AetherEngine
    ```
-   Dependency Rule: Up to Next Major Version, starting from `7.15.2`. Add the `AetherEngine` library product to your app target.
+   Dependency Rule: Up to Next Major Version, starting from `7.16.0`. Add the `AetherEngine` library product to your app target.
 
 3. **Drop the file in.** Replace the Xcode template's default `App.swift` (or whatever the generated `@main` file is called) with the contents of [`MinimalPlayerApp.swift`](MinimalPlayer/MinimalPlayerApp.swift). The file is self-contained: it defines both the `@main App` struct and the `ContentView`.
 
diff --git a/README.md b/README.md
index 5eb9654db..8623f8bd6 100644
--- a/README.md
+++ b/README.md
@@ -382,7 +382,7 @@ Subtitle cues land in raw source PTS; render the overlay against `player.sourceT
 Install via Swift Package Manager:
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.15.2")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.16.0")
 ```
 
 Three samples ship in `Examples/`:
@@ -629,10 +629,10 @@ Browse all of this as a searchable site at **[aetherengine.superuser404.de](http
 AetherEngine uses [Semantic Versioning](https://semver.org). The public API surface, every `public` declaration in `Sources/AetherEngine/`, is the stability contract. **Major** removes / renames public symbols or breaks adopters; **Minor** adds public API or codec / format support; **Patch** fixes bugs with no public API change. `internal` types are not part of the contract.
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.15.2")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.16.0")
 ```
 
-Pin to `.upToNextMinor(from: "7.15.2")` for stricter teams that prefer to opt into minor bumps explicitly.
+Pin to `.upToNextMinor(from: "7.16.0")` for stricter teams that prefer to opt into minor bumps explicitly.
 
 ## Requirements
 
diff --git a/Sources/AetherEngine/AetherEngine+Version.swift b/Sources/AetherEngine/AetherEngine+Version.swift
index 7531c70f4..a9165c2b2 100644
--- a/Sources/AetherEngine/AetherEngine+Version.swift
+++ b/Sources/AetherEngine/AetherEngine+Version.swift
@@ -11,5 +11,5 @@ extension AetherEngine {
     ///
     /// Between releases, and in a consumer that pins an unreleased commit for a device test, this
     /// names the last PUBLISHED version the checkout descends from, not every patch in it.
-    public nonisolated static let version = "7.15.2"
+    public nonisolated static let version = "7.16.0"
 }

From 9b8e4ee5535ca9734e97042715c6ce9ae874b526 Mon Sep 17 00:00:00 2001
From: Brandon Moore <16313090+thatcube@users.noreply.github.com>
Date: Thu, 24 Sep 2026 13:35:38 -0400
Subject: [PATCH 025/359] fix(native): a recovery reload leaves a paused viewer
 paused (#93)

Item death parks AVPlayer at .paused whatever the viewer wanted, so the
fallback then called play() on the fresh item unconditionally.

Field log, Apple TV 4K 3rd gen, tvOS 27.0, HDR10+ HEVC Matroska: paused,
the tvOS screensaver took the display two minutes later, the item died
with -11868, and the recovery started the title and dismissed the
screensaver.

Both now resume only when the host's durable play intent (#122), which
the in-place swap keeps, says the viewer was playing. A playing viewer is
resumed exactly as before.
---
 CHANGELOG.md                                  |  7 ++
 Sources/AetherEngine/AetherEngine.swift       | 10 ++-
 .../Issue93ItemDeathReviveTests.swift         | 65 +++++++++++++++++++
 docs/architecture.md                          |  2 +-
 4 files changed, 81 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index de24daa51..62ffa39bc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -22,6 +22,13 @@ the public-API contract.
   behind the pause. A title started from its beginning resumes at its first frame. `NativeAVPlayerHost`
   now records where every mount places its item, in-place swaps included, and the fallback reads
   that.
+- **A recovery reload leaves a paused viewer paused (#93, #98).** Item death parks AVPlayer at
+  `.paused` whatever the viewer wanted, so the #93/#65 stage-2 reload runs for a paused consumer
+  too, and it and the #98 media fallback then called `play()` on the fresh item unconditionally.
+  Field log, Apple TV 4K 3rd gen, tvOS 27.0, HDR10+ HEVC Matroska: paused, the tvOS screensaver
+  took the display two minutes later, the item died with -11868, and the recovery started the
+  title and dismissed the screensaver. Both now resume only when the host's durable intent (#122),
+  which the in-place swap keeps, says the viewer was playing; a playing viewer is resumed as before.
 
 ## [7.16.0] - 2026-09-24
 
diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index 46753bfd4..e23751429 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -2503,7 +2503,9 @@ public final class AetherEngine: ObservableObject {
         host.swapItem(url: fallbackURL,
                       startPosition: isLive ? nil : position,
                       skipInitialSeek: LiveReloadPolicy.skipInitialSeek(isLive: isLive, isRejoin: true))
-        host.play()
+        // Resume only a viewer who was playing; the host's intent (#122) survives the in-place swap.
+        // A paused title refused behind the tvOS screensaver used to start itself and wake it.
+        if host.transportIntentIsPlaying { host.play() }
     }
 
     /// #35 readiness-gate settle windows. Generous enough that a slow-but-healthy cold start reads as
@@ -2936,7 +2938,11 @@ public final class AetherEngine: ObservableObject {
         // AE#454 round 2: the item that is about to load is the one the placement was armed for, and
         // the only one whose axis the playlist will state.
         if didArmPlacement { liveRejoinPlacementGeneration = host.itemGeneration }
-        host.play()
+        // Item death parks AVPlayer at .paused whatever the viewer wanted, which is why this reload may
+        // run for a paused consumer at all; resuming is still the viewer's call, read from the host's
+        // intent (#122), which the in-place swap keeps. Playing a paused title here woke the tvOS
+        // screensaver its item had died behind.
+        if host.transportIntentIsPlaying { host.play() }
         if let rejoinPosition {
             // Stashed rather than seeked: the pre-readiness seek IS the wedge LiveReloadPolicy exists
             // to avoid, and a live seek does not defer itself (`shouldDeferHostSeek` excludes live), so
diff --git a/Tests/AetherEngineTests/Issue93ItemDeathReviveTests.swift b/Tests/AetherEngineTests/Issue93ItemDeathReviveTests.swift
index aaa1d744c..3a49a6298 100644
--- a/Tests/AetherEngineTests/Issue93ItemDeathReviveTests.swift
+++ b/Tests/AetherEngineTests/Issue93ItemDeathReviveTests.swift
@@ -98,3 +98,68 @@ struct Issue93ItemDeathReviveTests {
             surfaceEndFailures: false, hasEverPlayed: false))
     }
 }
+
+/// #93: item death parks AVPlayer at `.paused` whatever the viewer wanted, so the stage-2 reload runs
+/// for a paused consumer too. Whether the fresh item then PLAYS is the viewer's call, read from the
+/// host's durable intent (#122), which the in-place swap keeps.
+///
+/// Field log, Apple TV 4K 3rd gen, tvOS 27.0, HDR10+ HEVC Matroska: paused at 2605.23 s, the item died
+/// with -11868 two minutes later as the tvOS screensaver took the display, and the recovery called
+/// `play()` on the fresh item. The title started itself and the screensaver was dismissed.
+@Suite("#93: the stage-2 reload resumes only a viewer who was playing")
+@MainActor
+struct ItemDeathRecoveryTransportTests {
+
+    private let url = URL(fileURLWithPath: "/nonexistent-item-death-recovery-transport-test.m3u8")
+
+    /// An engine holding a native host with one mounted item, the state the recovery reloads from.
+    private func engineWithMountedItem() throws -> (AetherEngine, NativeAVPlayerHost) {
+        let engine = try AetherEngine()
+        let host = NativeAVPlayerHost()
+        engine.nativeHost = host
+        engine.currentAVPlayer = host.avPlayer
+        host.load(url: url, startPosition: 2605.23, contract: .init())
+        return (engine, host)
+    }
+
+    @Test("A paused viewer stays paused through the reload")
+    func pausedViewerStaysPaused() throws {
+        let (engine, host) = try engineWithMountedItem()
+        defer { host.tearDown() }
+        host.pause()
+
+        engine.forceStalledConsumerReloadForTesting()
+
+        #expect(!host.transportIntentIsPlaying)
+        #expect(host.avPlayer.rate == 0)
+    }
+
+    @Test("A playing viewer is resumed on the fresh item, as before")
+    func playingViewerResumes() throws {
+        let (engine, host) = try engineWithMountedItem()
+        defer { host.tearDown() }
+        host.play()
+
+        engine.forceStalledConsumerReloadForTesting()
+
+        #expect(host.transportIntentIsPlaying)
+    }
+
+    /// The #98 media fallback needs a live loopback session to run, so this reads its call site, as
+    /// the #535 latch test does.
+    @Test("The media fallback asks the same intent before it plays")
+    func fallbackAsksTheIntent() throws {
+        let source = URL(fileURLWithPath: #filePath)
+            .deletingLastPathComponent()
+            .deletingLastPathComponent()
+            .deletingLastPathComponent()
+            .appendingPathComponent("Sources/AetherEngine/AetherEngine.swift")
+        let text = try #require(try? String(contentsOf: source, encoding: .utf8))
+        let fn = try #require(text.range(of: "func fallBackToMediaPlaylist("))
+        let end = try #require(text[fn.upperBound...].range(of: "\n    }\n"))
+        let body = String(text[fn.lowerBound..<end.upperBound])
+        #expect(body.contains("if host.transportIntentIsPlaying { host.play() }"))
+        #expect(!body.contains("\n        host.play()\n"))
+    }
+}
+
diff --git a/docs/architecture.md b/docs/architecture.md
index 9a79f1afe..d25519369 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -64,7 +64,7 @@ What a host observes about a seek comes in two shapes. `isSeeking` / `seekTarget
 
 Restart latency is self-localizing (#93 follow-up): the "producer restarted" line carries a phase split (`stopWait/reopen/seek/build`), a producer's FIRST source read is timed, and any single `AVIOReader` read exceeding 2 s emits one `slow read` summary naming where the time went (detour fetches with network time, `connStallTimeout` waits, reconnects, backoff sleeps, bytes dropped by the stale-generation guard, generation span). A slow read with all-zero counters means the wait was upstream of the read loop.
 
-A restart-window request must also never leave AVPlayer waiting in silence (#93 round 3): AVPlayer's media watchdog logs `-12889 "No response for media file"` after ~3.5 s without response HEADERS (holding the connection open does not help), and three strikes fail the item. A VOD serve still running at 2 s (`SlowServeSignal` armed by `VideoSegmentProvider.mediaSegment(at:onSlow:)`) therefore emits an early `200` with `Transfer-Encoding: chunked`; the segment follows as a single chunk when it lands, and a serve that ultimately misses aborts the connection (truncated transfer, AVPlayer retries) instead of framing a cacheable empty 200. Fast serves keep the byte-identical `Content-Length` response. If the item dies anyway, `failedToPlayToEndTime` parks it at rate 0 / `timeControlStatus == .paused` (with `item.status` often still `readyToPlay`), which every pause-guarded recovery layer used to misread as user intent, making the session terminal. The host now counts loopback-path end failures (`endFailureCount`), and the engine confirms the death through the same deferred window as the `.failed` KVO, then reloads the item through the stage-2 chain with the pause guard bypassed, bounded by `ItemDeathReviveGate` (3 attempts per dead spot; playback progress or a user seek away restores the budget).
+A restart-window request must also never leave AVPlayer waiting in silence (#93 round 3): AVPlayer's media watchdog logs `-12889 "No response for media file"` after ~3.5 s without response HEADERS (holding the connection open does not help), and three strikes fail the item. A VOD serve still running at 2 s (`SlowServeSignal` armed by `VideoSegmentProvider.mediaSegment(at:onSlow:)`) therefore emits an early `200` with `Transfer-Encoding: chunked`; the segment follows as a single chunk when it lands, and a serve that ultimately misses aborts the connection (truncated transfer, AVPlayer retries) instead of framing a cacheable empty 200. Fast serves keep the byte-identical `Content-Length` response. If the item dies anyway, `failedToPlayToEndTime` parks it at rate 0 / `timeControlStatus == .paused` (with `item.status` often still `readyToPlay`), which every pause-guarded recovery layer used to misread as user intent, making the session terminal. The host now counts loopback-path end failures (`endFailureCount`), and the engine confirms the death through the same deferred window as the `.failed` KVO, then reloads the item through the stage-2 chain with the pause guard bypassed, bounded by `ItemDeathReviveGate` (3 attempts per dead spot; playback progress or a user seek away restores the budget). The fresh item resumes only if the host's play intent says the viewer was playing: a paused title whose item dies (a tvOS screensaver taking the display is one way) is reloaded and stays paused.
 
 When a restart does run, it must reproduce segments on the SAME media timeline the continuous run gave them: the loopback's contract with AVPlayer is "static VOD server", and AVPlayer anchors fMP4 segments by their `tfdt`. Each restart allocates a fresh mp4 muxer, and movenc zero-bases a new instance's timeline by default, so a restart-produced segment used to carry `tfdt=0` while the playlist placed it at its plan offset: an implicit timeline discontinuity on every restart, papered over for plain playback but fatal to ancillary consumers (AVKit's legible renderer detaches mid-PiP, Sodalite#32; playhead/loaded-range decoupling, #93). The muxer therefore sets `movflags +frag_discont` with `avoid_negative_ts=disabled` so `tfdt` carries the producer's absolute output timestamps, the restart audio gate inherits the session shift (video shift rescaled) instead of snapping audio onto the video seam, and leading head-of-stream audio that would map below 0 is dropped (the muxer no longer absorbs negative timestamps). A restarted segment is byte-identical to its continuous twin modulo the per-muxer `mfhd` sequence number (pinned by `RestartTimelineContinuityTests` on a committed A/V fixture); on matroska sources, per-sample DTS synthesis after a demuxer seek scatters the DTS decomposition and boundary-frame membership by a frame or two, but presentation timestamps and `tfdt` anchoring stay epoch-invariant. Because `tfdt` carries `unsigned int(64)`, that same setting makes a negative output axis unrepresentable rather than merely unusual, so the published first timestamp is clamped at zero (AE#509): libavformat serves an MPEG-TS whose first DTS sits within 60 s of the 33-bit PTS wrap with every timestamp `2^33` ticks low (`AV_PTS_WRAP_SUB_OFFSET`), and a live join there published `baseMediaDecodeTime = 2^64 - |dts|` against a playlist starting at 0, which AVPlayer answers by fetching the whole window and placing none of it, with no error and no stall of its own.
 

From d49516ecf0ab01f37f73ea40a627f3287c9549eb Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 24 Sep 2026 22:11:43 +0200
Subject: [PATCH 026/359] test(aetherctl): drill the stage-2 reload against a
 paused and a resumed session (#623)

`aetherctl play --host-calls pausereload,playreload,extplayreload` forces the #93/#65 stage-2
item reload at t=10 on a session paused at t=6, on one left playing, and on one paused through
the engine and resumed straight on the AVPlayer the way AVKit's transport does. The run fails
with exit 4 if the clock moves after the paused reload or stands still after a playing one.

Measured on a 90 s testsrc fixture: before #623 the paused session came back at +7.20 s,
state=playing; after it holds at +0.00 s, state=paused. The AVKit-resumed case, whose engine
intent still reads paused, comes back playing because the in-place swap keeps the player's rate,
so #623's intent check needs no second signal.

Refs #626

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 CHANGELOG.md                        |  4 +++
 Sources/aetherctl/PlaybackCmd.swift | 48 +++++++++++++++++++++++++++--
 Sources/aetherctl/main.swift        |  2 +-
 docs/cli.md                         |  2 +-
 4 files changed, 52 insertions(+), 4 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 62ffa39bc..c189f1f0f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -29,6 +29,10 @@ the public-API contract.
   took the display two minutes later, the item died with -11868, and the recovery started the
   title and dismissed the screensaver. Both now resume only when the host's durable intent (#122),
   which the in-place swap keeps, says the viewer was playing; a playing viewer is resumed as before.
+  `aetherctl play --host-calls pausereload,playreload,extplayreload` drills it headless: before,
+  a paused session came back from a forced stage-2 reload at `+7.20 s, state=playing`; after, it
+  holds at `+0.00 s, state=paused`, and a session resumed past the engine through AVKit still
+  comes back playing.
 
 ## [7.16.0] - 2026-09-24
 
diff --git a/Sources/aetherctl/PlaybackCmd.swift b/Sources/aetherctl/PlaybackCmd.swift
index 5b0461fcb..a834ca465 100644
--- a/Sources/aetherctl/PlaybackCmd.swift
+++ b/Sources/aetherctl/PlaybackCmd.swift
@@ -666,7 +666,7 @@ private func playSmokeTest(url: URL, seconds: Double, live: Bool, forceSoftware:
             // exists (the foreground retune's hold-paused policy). Resumed at tick 8.
             print("  HOSTCALL pause() right after load")
             engine.pause()
-        case "reloadlive", "seekback", "overlapseek", "ratehold-tail", "pauseseek", "pausehold", "still", "stallclock":
+        case "reloadlive", "seekback", "overlapseek", "ratehold-tail", "pauseseek", "pausehold", "still", "stallclock", "pausereload", "playreload", "extplayreload":
             break  // reloadlive handled at load time, seekback/overlapseek/pauseseek in the telemetry loop
         case "nativesubs":
             break  // Sodalite#156, read at load time into LoadOptions.prepareNativeSubtitles
@@ -674,7 +674,7 @@ private func playSmokeTest(url: URL, seconds: Double, live: Bool, forceSoftware:
             || call.hasPrefix("subson") || call.hasPrefix("nativerender"):
             break  // #433 / Sodalite#156, all in the telemetry loop; `@N` picks the tick
         default:
-            print("  HOSTCALL unknown '\(call)' (use play,extractor,setrate,ratehold,pausestart,reloadlive,seekback,seekfar,overlapseek,pauseseek,pausehold,still,stallclock,nativesubs,nativerender,subsoff,subson)")
+            print("  HOSTCALL unknown '\(call)' (use play,extractor,setrate,ratehold,pausestart,reloadlive,seekback,seekfar,overlapseek,pauseseek,pausehold,still,stallclock,pausereload,playreload,extplayreload,nativesubs,nativerender,subsoff,subson)")
         }
     }
     defer { if let frameExtractor { Task { await frameExtractor.shutdown() } } }
@@ -686,6 +686,9 @@ private func playSmokeTest(url: URL, seconds: Double, live: Bool, forceSoftware:
     var stallClockAtStall: Double?
     var stallClockBeforeResume: Double?
     var stallClockAtEnd: Double?
+    // AE#626: the clock just after the forced stage-2 reload, and at the last tick.
+    var recoveryReloadClockAfter: Double?
+    var recoveryReloadClockAtEnd: Double?
     var monitor: AudioContinuityMonitor?
     var tapTask: Task<Void, Never>?
     if audioStats {
@@ -1122,6 +1125,29 @@ private func playSmokeTest(url: URL, seconds: Double, live: Bool, forceSoftware:
             }
             if tick >= 9 { stallClockAtEnd = engine.currentTime }
         }
+        // AE#626: force the #93/#65 stage-2 reload on a session the host paused (`pausereload`) or
+        // left playing (`playreload`), and watch whether the fresh item keeps that transport.
+        let pauseReload = hostCalls.contains("pausereload")
+        let externalPlayReload = hostCalls.contains("extplayreload")
+        if pauseReload || externalPlayReload || hostCalls.contains("playreload") {
+            if pauseReload || externalPlayReload, tick == 6 {
+                print("  HOSTCALL pause()")
+                engine.pause()
+            }
+            // The resume AVKit's transport bar or a remote command makes: straight on the player,
+            // past the engine, so the engine's intent still reads paused while the player runs.
+            if externalPlayReload, tick == 8 {
+                print("  HOSTCALL play() straight on the AVPlayer, as AVKit does")
+                engine.currentAVPlayer?.play()
+            }
+            if tick == 10 {
+                print(String(format: "  HOSTCALL AE#626 forcing the stage-2 reload at %.2f (state=%@)",
+                             engine.currentTime, String(describing: engine.state)))
+                engine.forceStalledConsumerReloadForTesting()
+            }
+            if tick == 13 { recoveryReloadClockAfter = engine.currentTime }
+            if tick >= 13 { recoveryReloadClockAtEnd = engine.currentTime }
+        }
         if hostCalls.contains("pausestart"), tick == 8 {
             print(String(format: "  HOSTCALL play() after the start pause (playhead %.2f)", engine.currentTime))
             engine.play()
@@ -1340,6 +1366,24 @@ private func playSmokeTest(url: URL, seconds: Double, live: Bool, forceSoftware:
             return 4
         }
     }
+    if hostCalls.contains("pausereload") || hostCalls.contains("playreload")
+        || hostCalls.contains("extplayreload") {
+        guard let after = recoveryReloadClockAfter, let atEnd = recoveryReloadClockAtEnd else {
+            print("VERDICT: AE#626 drill inconclusive (run it for at least 20 s)")
+            return 5
+        }
+        let moved = atEnd - after
+        print(String(format: "AE#626 after the reload: %.2f, at the last tick %.2f (%+.2f s), state=%@",
+                     after, atEnd, moved, String(describing: endState)))
+        if hostCalls.contains("pausereload"), moved > 0.25 {
+            print("VERDICT: AE#626 reproduced (the reload of a paused session played it)")
+            return 4
+        }
+        if hostCalls.contains("playreload") || hostCalls.contains("extplayreload"), moved <= 0.25 {
+            print("VERDICT: AE#626 regression (the reload of a playing session came back stopped)")
+            return 4
+        }
+    }
     if hostCalls.contains("stallclock") {
         guard stallClockStalled, let atStall = stallClockAtStall,
               let beforeResume = stallClockBeforeResume, let atEnd = stallClockAtEnd else {
diff --git a/Sources/aetherctl/main.swift b/Sources/aetherctl/main.swift
index 8a9cb44a3..c29df3079 100644
--- a/Sources/aetherctl/main.swift
+++ b/Sources/aetherctl/main.swift
@@ -79,7 +79,7 @@ func printUsage() {
                  [--drop-audio]
                  [--sequential-origin] [--declared-duration S]
              [--max-concurrent-requests N]
-                     [--audio-stats] [--host-calls play,extractor,setrate,pausestart,reloadlive,seekback,seekfar,pauseseek] <url>
+                     [--audio-stats] [--host-calls play,extractor,setrate,pausestart,reloadlive,seekback,seekfar,pauseseek,pausereload,playreload,extplayreload] <url>
                      (full load+play session smoke test; --subs activates the first
                       matching embedded subtitle track and logs overlay cues;
                       --audio-stats taps decoded PCM and prints per-second audio lead
diff --git a/docs/cli.md b/docs/cli.md
index 820eab224..361220b28 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -140,7 +140,7 @@ the same clock as `FIRSTFRAME`. The 1 Hz tick samples the phase, which is far to
 signal apart from the moment the rate rolls; a healthy native join is exactly two edges, `loading` at the
 load and `playing` at the roll (AE#440).
 
-`--subs <codec-or-lang>` matches against the track's libavcodec name or language and logs every overlay cue and cue trim as it lands. `--host-calls` replays host post-load behavior against the fresh session: `play`, `extractor` (`makeFrameExtractor`), `setrate` (`setRate(1.0)`), `pausestart` (Sodalite#104 round 4: `pause()` the instant load returns, before any frame exists, and `play()` at t=8; the shape of a host that holds a fresh load paused, and a software session used to answer it with eight ticks of `enq=+0 status=unknown r4d=n`, a black picture under a paused clock; now the `[SWHost] #104` lines show the first frame presented at a stopped clock and `startup 8/8 presenting` arrives while paused), `ratehold` (set 1.5, pause at tick 3, resume at tick 5, then read the rate back off the transport itself: the #436 drill, and it fails the run if the resume came back at 1.0), `reloadlive` (reload the URL on the live path when the probe flags it live, the AetherPlayer Open URL flow), `seekback` (rewind 20 s into the DVR window at t=15, return to the live edge at t=30), `overlapseek` (the #292 seek-window drills below), `pausehold` (Sodalite#104: pause at t=10 and HOLD until ten seconds before the end, printing the playhead, the edge and the resident depth every second, which is how a session paused for longer than its own DVR window is measured without waiting out a real one: pair it with `--dvr-window 30` and `--seconds 90` and the ninety minute question becomes a ninety second run), `still` (#544: asks for a scrub still at three aims, 20 s behind the playhead at t=15, 5 s behind at t=20 and at the edge at t=25, writing each to `/tmp/aetherctl-still-<tick>.png` and reporting hit or MISS with the decode time; pair it with `--sw --dvr-window N`, where the picture comes out of the DVR packet ring rather than a segment cache, and read the FILE as well as the count, because the bundled seed burns its own second into the frame so a still asked for 14.85 s showing `14` is the verdict that it decoded the right moment and not merely an image; exit 6 when nothing hit, 5 when the session ended before the first aim; on a VOD session (AE#605) the three aims are 10.5 s behind the playhead, 4.5 s ahead of it and 600 s past it, through `scrubThumbnail`, and the third is EXPECTED to miss, because a frame the cache does not hold yet must not be answered with the one before it: `--sw` against an HTTP source is the software packet-cache case, and the testsrc fixture's counter in the PNG is the verdict that the still decoded to the target rather than snapping to its keyframe), `stallclock` (AE#549: stop the master clock at t=4 behind the host's back, the way an interrupted audio session does, then call a plain `play()` at t=7 and read whether the playhead moves again; the interruption itself cannot be staged on macOS, its outcome can, and without the `RendererClockResume` branch the run ends with the clock standing exactly where the stall left it, which is the field log's shape; the drill drives DEBUG-only engine hooks, so a Release `aetherctl` prints a notice and ends inconclusive, build it with `swift build --product aetherctl`), and `pauseseek` (pause at t=12, seek at t=15 while paused, resume at t=20; with `--sw` the five paused ticks between landing and resume show what the `[SWDiag]` line reports while the pump is parked and has not heard of the seek, the AE#479 shape); this is how the pre-arming `setRate` wedge was isolated.
+`--subs <codec-or-lang>` matches against the track's libavcodec name or language and logs every overlay cue and cue trim as it lands. `--host-calls` replays host post-load behavior against the fresh session: `play`, `extractor` (`makeFrameExtractor`), `setrate` (`setRate(1.0)`), `pausestart` (Sodalite#104 round 4: `pause()` the instant load returns, before any frame exists, and `play()` at t=8; the shape of a host that holds a fresh load paused, and a software session used to answer it with eight ticks of `enq=+0 status=unknown r4d=n`, a black picture under a paused clock; now the `[SWHost] #104` lines show the first frame presented at a stopped clock and `startup 8/8 presenting` arrives while paused), `ratehold` (set 1.5, pause at tick 3, resume at tick 5, then read the rate back off the transport itself: the #436 drill, and it fails the run if the resume came back at 1.0), `reloadlive` (reload the URL on the live path when the probe flags it live, the AetherPlayer Open URL flow), `seekback` (rewind 20 s into the DVR window at t=15, return to the live edge at t=30), `overlapseek` (the #292 seek-window drills below), `pausehold` (Sodalite#104: pause at t=10 and HOLD until ten seconds before the end, printing the playhead, the edge and the resident depth every second, which is how a session paused for longer than its own DVR window is measured without waiting out a real one: pair it with `--dvr-window 30` and `--seconds 90` and the ninety minute question becomes a ninety second run), `still` (#544: asks for a scrub still at three aims, 20 s behind the playhead at t=15, 5 s behind at t=20 and at the edge at t=25, writing each to `/tmp/aetherctl-still-<tick>.png` and reporting hit or MISS with the decode time; pair it with `--sw --dvr-window N`, where the picture comes out of the DVR packet ring rather than a segment cache, and read the FILE as well as the count, because the bundled seed burns its own second into the frame so a still asked for 14.85 s showing `14` is the verdict that it decoded the right moment and not merely an image; exit 6 when nothing hit, 5 when the session ended before the first aim; on a VOD session (AE#605) the three aims are 10.5 s behind the playhead, 4.5 s ahead of it and 600 s past it, through `scrubThumbnail`, and the third is EXPECTED to miss, because a frame the cache does not hold yet must not be answered with the one before it: `--sw` against an HTTP source is the software packet-cache case, and the testsrc fixture's counter in the PNG is the verdict that the still decoded to the target rather than snapping to its keyframe), `stallclock` (AE#549: stop the master clock at t=4 behind the host's back, the way an interrupted audio session does, then call a plain `play()` at t=7 and read whether the playhead moves again; the interruption itself cannot be staged on macOS, its outcome can, and without the `RendererClockResume` branch the run ends with the clock standing exactly where the stall left it, which is the field log's shape; the drill drives DEBUG-only engine hooks, so a Release `aetherctl` prints a notice and ends inconclusive, build it with `swift build --product aetherctl`), `pausereload`, `playreload` and `extplayreload` (#623: force the #93/#65 stage-2 item reload at t=10, on a session paused at t=6, on one left playing, and on one paused through the engine at t=6 and resumed at t=8 straight on the `AVPlayer` the way AVKit's transport does, which leaves the engine's intent reading paused while the player runs; the run fails with exit 4 if the clock moves after the paused reload or stands still after either playing one, and before #623 `pausereload` ended `+7.20 s, state=playing`), and `pauseseek` (pause at t=12, seek at t=15 while paused, resume at t=20; with `--sw` the five paused ticks between landing and resume show what the `[SWDiag]` line reports while the pump is parked and has not heard of the seek, the AE#479 shape); this is how the pre-arming `setRate` wedge was isolated.
 
 `--seek-every N` seeks once every N ticks past tick 10, walking `--seek-pattern <abs,abs,...>` if one is given (a short backward hop otherwise), and `--seek-count K` stops after K seeks so a run can be a BURST and then play. Both halves are needed for anything about what a seek sequence leaves behind: the burst puts the store in the state under test, and only the playing half shows what the overlay carries through it. That pairing is what made AE#362's second mechanism reproducible (a hole between a restarted pump and the island the previous run left ahead of it, decoded across and then never re-read).
 

From 4ef5ef95faf271cb0c0e9cc79a0bf81a54b1244b Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 24 Sep 2026 22:37:56 +0200
Subject: [PATCH 027/359] chore(release): prep 7.16.1 - a recovery reload keeps
 a paused viewer paused and comes back where it was placed

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 CHANGELOG.md                                    | 4 ++++
 Examples/README.md                              | 2 +-
 README.md                                       | 6 +++---
 Sources/AetherEngine/AetherEngine+Version.swift | 2 +-
 4 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c189f1f0f..b8a9324f2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,10 @@ the public-API contract.
 
 ## [Unreleased]
 
+_Nothing yet._
+
+## [7.16.1] - 2026-09-24
+
 ### Fixed
 
 - **The media fallback comes back where the rejected item was placed, not where the session
diff --git a/Examples/README.md b/Examples/README.md
index ad27387b5..82ae152fe 100644
--- a/Examples/README.md
+++ b/Examples/README.md
@@ -18,7 +18,7 @@ Three samples covering different audiences:
    ```
    https://github.com/superuser404notfound/AetherEngine
    ```
-   Dependency Rule: Up to Next Major Version, starting from `7.16.0`. Add the `AetherEngine` library product to your app target.
+   Dependency Rule: Up to Next Major Version, starting from `7.16.1`. Add the `AetherEngine` library product to your app target.
 
 3. **Drop the file in.** Replace the Xcode template's default `App.swift` (or whatever the generated `@main` file is called) with the contents of [`MinimalPlayerApp.swift`](MinimalPlayer/MinimalPlayerApp.swift). The file is self-contained: it defines both the `@main App` struct and the `ContentView`.
 
diff --git a/README.md b/README.md
index 8623f8bd6..7d87c0705 100644
--- a/README.md
+++ b/README.md
@@ -382,7 +382,7 @@ Subtitle cues land in raw source PTS; render the overlay against `player.sourceT
 Install via Swift Package Manager:
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.16.0")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.16.1")
 ```
 
 Three samples ship in `Examples/`:
@@ -629,10 +629,10 @@ Browse all of this as a searchable site at **[aetherengine.superuser404.de](http
 AetherEngine uses [Semantic Versioning](https://semver.org). The public API surface, every `public` declaration in `Sources/AetherEngine/`, is the stability contract. **Major** removes / renames public symbols or breaks adopters; **Minor** adds public API or codec / format support; **Patch** fixes bugs with no public API change. `internal` types are not part of the contract.
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.16.0")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.16.1")
 ```
 
-Pin to `.upToNextMinor(from: "7.16.0")` for stricter teams that prefer to opt into minor bumps explicitly.
+Pin to `.upToNextMinor(from: "7.16.1")` for stricter teams that prefer to opt into minor bumps explicitly.
 
 ## Requirements
 
diff --git a/Sources/AetherEngine/AetherEngine+Version.swift b/Sources/AetherEngine/AetherEngine+Version.swift
index a9165c2b2..8969f7437 100644
--- a/Sources/AetherEngine/AetherEngine+Version.swift
+++ b/Sources/AetherEngine/AetherEngine+Version.swift
@@ -11,5 +11,5 @@ extension AetherEngine {
     ///
     /// Between releases, and in a consumer that pins an unreleased commit for a device test, this
     /// names the last PUBLISHED version the checkout descends from, not every patch in it.
-    public nonisolated static let version = "7.16.0"
+    public nonisolated static let version = "7.16.1"
 }

From 7c9a92315cc1010983e8b63f1f295ca20553dd81 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 05:04:00 +0200
Subject: [PATCH 028/359] fix(prewarm): skip a Matroska SeekPosition that
 overflows instead of trapping (audit DMX-2)

An 8-byte SeekPosition of all 0xFF clamps to Int64.max, and adding the
Segment data start trapped the process on every warm of such an item.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 Sources/AetherEngine/Demuxer/SourcePrewarmPlan.swift | 6 ++++--
 Tests/AetherEngineTests/SourcePrewarmPlanTests.swift | 9 +++++++++
 2 files changed, 13 insertions(+), 2 deletions(-)

diff --git a/Sources/AetherEngine/Demuxer/SourcePrewarmPlan.swift b/Sources/AetherEngine/Demuxer/SourcePrewarmPlan.swift
index 45c4852f5..323f5c9b9 100644
--- a/Sources/AetherEngine/Demuxer/SourcePrewarmPlan.swift
+++ b/Sources/AetherEngine/Demuxer/SourcePrewarmPlan.swift
@@ -141,8 +141,10 @@ enum SourcePrewarmPlan {
                 let end = min(head.count, start + Int(clamping: size))
                 // A SeekHead truncated by the warm head's edge still yields the entries that fit.
                 for position in seekPositions(head, from: start, to: end) {
-                    let absolute = Int64(dataStart) + position
-                    guard absolute >= headEnd else { continue }
+                    // Audit DMX-2: an 8-byte SeekPosition reaches Int64.max; such an entry names
+                    // nothing a source can hold, so it is skipped rather than added.
+                    let (absolute, overflow) = Int64(dataStart).addingReportingOverflow(position)
+                    guard !overflow, absolute >= headEnd else { continue }
                     earliest = min(earliest ?? absolute, absolute)
                 }
             }
diff --git a/Tests/AetherEngineTests/SourcePrewarmPlanTests.swift b/Tests/AetherEngineTests/SourcePrewarmPlanTests.swift
index 93f3d7b88..07e2808bc 100644
--- a/Tests/AetherEngineTests/SourcePrewarmPlanTests.swift
+++ b/Tests/AetherEngineTests/SourcePrewarmPlanTests.swift
@@ -123,6 +123,15 @@ struct SourcePrewarmPlanTests {
                 == .range(start: cuesAbsolute))
     }
 
+    @Test("a SeekPosition at the top of the 64-bit range is skipped instead of overflowing")
+    func overflowingSeekPositionIsSkipped() {
+        let fixture = matroskaHead(entries: [(cuesID, -1)], padTo: 4096)
+        #expect(SourcePrewarmPlan.trailing(head: fixture.head, total: 63_708_627) == SourcePrewarmPlan.Trailing.none)
+        let dataStart = Int64(fixture.segmentDataStart)
+        let mixed = matroskaHead(entries: [(tagsID, Int64.max), (cuesID, 60_000 - dataStart)], padTo: 4096)
+        #expect(SourcePrewarmPlan.trailing(head: mixed.head, total: 63_000) == .range(start: 60_000))
+    }
+
     @Test("a Matroska whose objects all sit inside the warm head needs nothing more")
     func matroskaWithEverythingInTheHeadNeedsNothing() {
         let fixture = matroskaHead(entries: [(cuesID, 2048), (tagsID, 4096)], padTo: 64 * 1024)

From 7094a80cd1b75b1ea54bd6b886fba581f4d249ae Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 05:09:04 +0200
Subject: [PATCH 029/359] fix(relay): name the origin by a sealed reference,
 never by its URL (audit NET-1)

The relay put the whole origin URL, percent-encoded, into every local URL it
handed out. That URL is logged on every request (HLSLocalServer request line,
NativeAVPlayerHost load url= / asset.url=), written into every rewritten
playlist and handed to AirPlay receivers, and the redactor could not read the
encoded api_key, so a Jellyfin access token reached OSLog and the host's
diagnostic log in clear text.

The local URL now carries only `ref=<AES-GCM sealed origin>`, under keys that
live and die with the relay instance. The nonce is derived from the plaintext,
so one origin always maps to the same local URL (a live playlist refresh names
a segment the same way each time), and the state stays constant however many
URIs a VOD playlist registers, where an id table would need eviction and an
evicted id would be a 404 mid-film. A reference from an earlier session or a
tampered one opens to nothing and is answered 404.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 .../AetherEngine/Network/HLSLocalServer.swift |  2 +-
 .../AetherEngine/Network/HLSOriginRelay.swift | 81 +++++++++++++------
 .../HLSOriginRelayTests.swift                 | 72 ++++++++++++++---
 3 files changed, 120 insertions(+), 35 deletions(-)

diff --git a/Sources/AetherEngine/Network/HLSLocalServer.swift b/Sources/AetherEngine/Network/HLSLocalServer.swift
index f226bc9a9..f27dbeceb 100644
--- a/Sources/AetherEngine/Network/HLSLocalServer.swift
+++ b/Sources/AetherEngine/Network/HLSLocalServer.swift
@@ -435,7 +435,7 @@ final class HLSLocalServer: @unchecked Sendable {
         let listeningPort = port
         stateLock.unlock()
         guard listeningPort > 0 else { return nil }
-        return HLSOriginRelay.localURL(for: origin, port: listeningPort, token: pathToken)
+        return relay.localURL(for: origin, port: listeningPort, token: pathToken)
     }
 
     // MARK: - Lifecycle
diff --git a/Sources/AetherEngine/Network/HLSOriginRelay.swift b/Sources/AetherEngine/Network/HLSOriginRelay.swift
index 52e088138..ce4e31372 100644
--- a/Sources/AetherEngine/Network/HLSOriginRelay.swift
+++ b/Sources/AetherEngine/Network/HLSOriginRelay.swift
@@ -1,3 +1,4 @@
+import CryptoKit
 import Foundation
 
 /// AE#495: fetches a remote origin on the engine's behalf and sends every URI a playlist
@@ -17,9 +18,19 @@ import Foundation
 final class HLSOriginRelay: @unchecked Sendable {
 
     /// The single route the player is ever pointed at, under the server's session token.
-    /// The origin rides in the query, so one route covers playlists, keys and segments.
+    /// A sealed reference to the origin rides in the query, so one route covers playlists, keys
+    /// and segments.
     static let route = "/aether-origin-relay"
-    private static let originQueryKey = "origin"
+    private static let referenceQueryKey = "ref"
+
+    /// Audit NET-1: the origin URL carries the media server's access token, and the local URL is
+    /// logged on every request, handed to AirPlay receivers and written into rewritten playlists.
+    /// So the local URL names the origin only through a reference sealed with keys that live and
+    /// die with this relay. Sealing rather than an id table keeps the state constant: a VOD
+    /// playlist registers every segment URI at once, and an evicted table entry would be a 404
+    /// in the middle of a film.
+    private let sealingKey = SymmetricKey(size: .bits256)
+    private let nonceKey = SymmetricKey(size: .bits256)
 
     /// What a relayed request produced, for the server to write.
     struct Response {
@@ -146,47 +157,41 @@ final class HLSOriginRelay: @unchecked Sendable {
 
     // MARK: - Addressing
 
-    /// The local address standing in for `origin`.
-    static func localURL(
+    /// The local address standing in for `origin`. Does not admit it.
+    func localURL(
         for origin: URL, host: String = "127.0.0.1", port: UInt16, token: String
     ) -> URL? {
-        // Encoding everything outside the alphanumerics keeps the origin's own query, which
-        // on a Jellyfin stream carries the api key and the play session, from being read as
-        // part of this URL's query.
-        guard
-            let encoded = origin.absoluteString.addingPercentEncoding(
-                withAllowedCharacters: .alphanumerics)
-        else { return nil }
-        return URL(string: "http://\(host):\(port)/\(token)\(route)?\(originQueryKey)=\(encoded)")
+        guard let reference = seal(origin) else { return nil }
+        return URL(
+            string: "http://\(host):\(port)/\(token)\(Self.route)?\(Self.referenceQueryKey)=\(reference)")
     }
 
-    /// The origin a relay request names, or nil when the query does not carry one.
+    /// The origin a relay request names, or nil when the query carries no reference this relay
+    /// sealed.
     ///
     /// Every other field the client put on the URL is carried onto the origin's own query rather
     /// than dropped. AVPlayer appends `_HLS_msn` / `_HLS_part` / `_HLS_skip` to a playlist URL when
     /// the playlist advertises `CAN-BLOCK-RELOAD` (#441), and a reload that should have blocked
     /// until the next segment exists answers immediately without them, so the player asks again at
     /// once and the origin is polled as fast as the loopback can answer.
-    static func originURL(fromQuery query: String) -> URL? {
+    func originURL(fromQuery query: String) -> URL? {
         var origin: URL?
         var carried: [String] = []
         for field in query.split(separator: "&") {
             let pair = field.split(separator: "=", maxSplits: 1)
-            guard pair.count == 2, pair[0] == originQueryKey else {
+            guard pair.count == 2, pair[0] == Self.referenceQueryKey else {
                 carried.append(String(field))
                 continue
             }
-            guard let decoded = String(pair[1]).removingPercentEncoding, !decoded.isEmpty else {
-                return nil
-            }
-            origin = URL(string: decoded)
+            guard let opened = open(String(pair[1])) else { return nil }
+            origin = opened
         }
         guard let origin else { return nil }
         guard !carried.isEmpty,
             var components = URLComponents(url: origin, resolvingAgainstBaseURL: false)
         else { return origin }
-        // percentEncoded, because both halves are already encoded: the origin's query came out of
-        // the round trip through `localURL`, and the client's fields arrived off the wire.
+        // percentEncoded, because both halves are already encoded: the origin's query is the one
+        // it was sealed with, and the client's fields arrived off the wire.
         var fields: [String] = []
         if let existing = components.percentEncodedQuery, !existing.isEmpty { fields.append(existing) }
         fields.append(contentsOf: carried)
@@ -194,6 +199,36 @@ final class HLSOriginRelay: @unchecked Sendable {
         return components.url ?? origin
     }
 
+    /// AES-GCM under a nonce derived from the plaintext, so one origin always seals to the same
+    /// reference: a live playlist refreshed every few seconds names the same segment by the same
+    /// local URL each time. Equal plaintexts are the only nonce reuse, and they reveal nothing
+    /// beyond their equality. base64url without padding, which a query carries as it stands.
+    private func seal(_ origin: URL) -> String? {
+        let plaintext = Data(origin.absoluteString.utf8)
+        let derived = HMAC<SHA256>.authenticationCode(for: plaintext, using: nonceKey)
+        guard let nonce = try? AES.GCM.Nonce(data: Data(derived).prefix(12)),
+            let sealed = try? AES.GCM.seal(plaintext, using: sealingKey, nonce: nonce),
+            let combined = sealed.combined
+        else { return nil }
+        return combined.base64EncodedString()
+            .replacingOccurrences(of: "+", with: "-")
+            .replacingOccurrences(of: "/", with: "_")
+            .replacingOccurrences(of: "=", with: "")
+    }
+
+    private func open(_ reference: String) -> URL? {
+        var base64 = reference
+            .replacingOccurrences(of: "-", with: "+")
+            .replacingOccurrences(of: "_", with: "/")
+        base64 += String(repeating: "=", count: (4 - base64.count % 4) % 4)
+        guard let combined = Data(base64Encoded: base64),
+            let box = try? AES.GCM.SealedBox(combined: combined),
+            let plaintext = try? AES.GCM.open(box, using: sealingKey),
+            let string = String(data: plaintext, encoding: .utf8), !string.isEmpty
+        else { return nil }
+        return URL(string: string)
+    }
+
     /// The authority a rewritten playlist should point its sub-resources at: whatever the
     /// client used to reach the server, so a receiver that arrived on the LAN address keeps
     /// fetching from it rather than being sent to a loopback it resolves to itself (#86).
@@ -238,7 +273,7 @@ final class HLSOriginRelay: @unchecked Sendable {
     func respond(query: String, host: String?, range: String?, port: UInt16, token: String,
                  sink: Sink) -> Outcome?
     {
-        guard let origin = Self.originURL(fromQuery: query) else { return nil }
+        guard let origin = originURL(fromQuery: query) else { return nil }
         guard let key = Self.originKey(for: origin) else { return nil }
 
         stateLock.lock()
@@ -438,7 +473,7 @@ final class HLSOriginRelay: @unchecked Sendable {
         let rewriteOne: (String) -> String = { raw in
             if absoluteOnly, URL(string: raw)?.host == nil { return raw }
             guard let resolved = URL(string: raw, relativeTo: origin)?.absoluteURL,
-                let local = Self.localURL(
+                let local = self.localURL(
                     for: resolved, host: authority, port: port, token: token)
             else { return raw }
             if let key = Self.originKey(for: resolved) { discovered.insert(key) }
diff --git a/Tests/AetherEngineTests/HLSOriginRelayTests.swift b/Tests/AetherEngineTests/HLSOriginRelayTests.swift
index 6ebc9027e..b35f08320 100644
--- a/Tests/AetherEngineTests/HLSOriginRelayTests.swift
+++ b/Tests/AetherEngineTests/HLSOriginRelayTests.swift
@@ -13,22 +13,69 @@ struct HLSOriginRelayAddressingTests {
 
     @Test("An origin survives the round trip through a relay URL")
     func roundTrip() throws {
+        let relay = HLSOriginRelay()
         let origin = URL(
             string: "https://media.example.com:8920/videos/1/master.m3u8"
                 + "?ApiKey=abc123&PlaySessionId=x%20y&tag=a+b")!
-        let local = try #require(HLSOriginRelay.localURL(for: origin, port: 51234, token: token))
+        let local = try #require(relay.localURL(for: origin, port: 51234, token: token))
 
         #expect(local.host == "127.0.0.1")
         #expect(local.port == 51234)
         #expect(local.path == "/\(token)\(HLSOriginRelay.route)")
-        let recovered = try #require(HLSOriginRelay.originURL(fromQuery: local.query ?? ""))
+        let recovered = try #require(relay.originURL(fromQuery: local.query ?? ""))
         #expect(recovered == origin, "recovered \(recovered) from \(origin)")
     }
 
+    @Test("A relay URL names the origin by reference, never by its host, path or token (audit NET-1)")
+    func localURLCarriesNoOriginText() throws {
+        // The local URL is logged on every request, handed to AirPlay receivers and written into
+        // every rewritten playlist, so nothing of the origin may be readable in it, in any encoding.
+        let relay = HLSOriginRelay()
+        let secret = "0123456789abcdef0123456789abcdef"
+        let origin = URL(
+            string: "https://jf.example.com/Videos/abc/master.m3u8?MediaSourceId=x&api_key=\(secret)")!
+        let local = try #require(relay.localURL(for: origin, port: 51234, token: token))
+        let text = local.absoluteString
+        for fragment in [secret, "jf", "example", "Videos", "master", "api", "MediaSourceId"] {
+            #expect(!text.contains(fragment), "\(fragment) is readable in \(text)")
+        }
+        #expect(!text.contains("%"), "the reference should need no escaping: \(text)")
+    }
+
+    @Test("One origin always seals to the same local URL, so a refreshed playlist names a segment the same way")
+    func sealingIsStable() throws {
+        let relay = HLSOriginRelay()
+        let segment = URL(string: "https://media.example.com/hls/seg42.ts?api_key=k")!
+        let first = try #require(relay.localURL(for: segment, port: 51234, token: token))
+        let again = try #require(relay.localURL(for: segment, port: 51234, token: token))
+        let other = try #require(relay.localURL(
+            for: URL(string: "https://media.example.com/hls/seg43.ts?api_key=k")!, port: 51234, token: token))
+        #expect(first == again)
+        #expect(first != other)
+    }
+
+    @Test("A reference from another session, or one that was altered, opens to nothing")
+    func foreignOrTamperedReferenceIsRefused() throws {
+        let origin = URL(string: "https://media.example.com/hls/media.m3u8?ApiKey=k")!
+        let previousSession = HLSOriginRelay()
+        let stale = try #require(previousSession.localURL(for: origin, port: 51234, token: token))
+        let relay = HLSOriginRelay()
+        #expect(relay.originURL(fromQuery: stale.query ?? "") == nil)
+
+        let own = try #require(relay.localURL(for: origin, port: 51234, token: token))
+        var query = Array(own.query ?? "")
+        let flipAt = query.count - 3
+        query[flipAt] = query[flipAt] == "A" ? "B" : "A"
+        #expect(relay.originURL(fromQuery: String(query)) == nil)
+    }
+
     @Test("A query that names no origin yields none")
     func rejectsForeignQuery() {
-        #expect(HLSOriginRelay.originURL(fromQuery: "") == nil)
-        #expect(HLSOriginRelay.originURL(fromQuery: "other=https%3A%2F%2Fa.b") == nil)
+        let relay = HLSOriginRelay()
+        #expect(relay.originURL(fromQuery: "") == nil)
+        #expect(relay.originURL(fromQuery: "other=https%3A%2F%2Fa.b") == nil)
+        #expect(relay.originURL(fromQuery: "origin=https%3A%2F%2Fa.b") == nil,
+                "the pre-NET-1 plain origin form must not be honoured")
     }
 
     @Test("The origin key keeps scheme, host and port apart")
@@ -89,8 +136,10 @@ struct HLSOriginRelayAddressingTests {
         // A relative segment resolves against the playlist it came from.
         let segLine = try #require(lines.first { !$0.hasPrefix("#") && !$0.isEmpty })
         let query = try #require(URL(string: segLine)?.query)
-        let recovered = try #require(HLSOriginRelay.originURL(fromQuery: query))
+        let recovered = try #require(relay.originURL(fromQuery: query))
         #expect(recovered.absoluteString == "https://media.example.com/hls/seg0.ts")
+        #expect(!rewritten.contains("ApiKey"), "the origin's query leaked into the rewritten playlist")
+        #expect(!rewritten.contains("example.com"), "an origin host leaked into the rewritten playlist")
     }
 
     @Test("An injected rendition stays with the server that owns it")
@@ -136,7 +185,7 @@ struct HLSOriginRelayAddressingTests {
             port: server.port, token: server.pathToken)
 
         let named = try #require(server.relayURL(for: URL(string: "https://127.0.0.1:10/seg1.ts")!))
-        let stranger = try #require(HLSOriginRelay.localURL(
+        let stranger = try #require(relay.localURL(
             for: URL(string: "https://127.0.0.1:11/x.ts")!, port: server.port,
             token: server.pathToken))
 
@@ -153,7 +202,7 @@ struct HLSOriginRelayAddressingTests {
         let origin = URL(string: "https://127.0.0.1:9/hls/media.m3u8")!
         relay.admit(origin)
 
-        let stranger = try #require(HLSOriginRelay.localURL(
+        let stranger = try #require(relay.localURL(
             for: origin, port: server.port, token: String(repeating: "cd", count: 16)))
         #expect(try await status(of: stranger) == 404, "a stale or scanned token was answered")
     }
@@ -161,13 +210,14 @@ struct HLSOriginRelayAddressingTests {
     @Test("A blocking-reload request keeps the parameters that make it block")
     func blockingReloadParametersReachTheOrigin() throws {
         // AVPlayer appends _HLS_msn / _HLS_part to a playlist URL that advertises CAN-BLOCK-RELOAD
-        // (#441). The relay URL already carries a query, so they arrive alongside `origin`; dropped,
-        // the reload answers at once and the player asks again immediately.
+        // (#441). The relay URL already carries a query, so they arrive alongside the reference;
+        // dropped, the reload answers at once and the player asks again immediately.
+        let relay = HLSOriginRelay()
         let origin = URL(string: "https://media.example.com/hls/media.m3u8?ApiKey=k")!
-        let local = try #require(HLSOriginRelay.localURL(for: origin, port: 51234, token: token))
+        let local = try #require(relay.localURL(for: origin, port: 51234, token: token))
         let asAVPlayerAsks = "\(local.query ?? "")&_HLS_msn=42&_HLS_part=3"
 
-        let upstream = try #require(HLSOriginRelay.originURL(fromQuery: asAVPlayerAsks))
+        let upstream = try #require(relay.originURL(fromQuery: asAVPlayerAsks))
         #expect(upstream.path == "/hls/media.m3u8")
         let query = try #require(upstream.query)
         #expect(query.contains("ApiKey=k"), "the origin's own query was dropped: \(query)")

From aad474086d7feedd721191a26b4d425a99ec6a82 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 05:10:07 +0200
Subject: [PATCH 030/359] fix(demuxer): validate the tail prefetch span against
 its total and clamp its body (audit DMX-8, DMX-9)

A suffix Content-Range must end on the last byte of a numeric total, so a
hostile `bytes <2^63-65536>-<Int64.max>/*` can no longer install a span
whose end overflows. The body is clamped to the promised length, so a few
over-delivered bytes no longer read as a short body and latch the origin
as declining suffix ranges for the process lifetime.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 Sources/AetherEngine/Demuxer/AVIOReader.swift    | 16 ++++++++++++----
 .../Issue281ColdStartRoundTripTests.swift        |  8 ++++++++
 2 files changed, 20 insertions(+), 4 deletions(-)

diff --git a/Sources/AetherEngine/Demuxer/AVIOReader.swift b/Sources/AetherEngine/Demuxer/AVIOReader.swift
index c0df3a1bb..359ea8c8c 100644
--- a/Sources/AetherEngine/Demuxer/AVIOReader.swift
+++ b/Sources/AetherEngine/Demuxer/AVIOReader.swift
@@ -2737,16 +2737,21 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
     /// Start offset of the bytes a 206 actually carries, from `Content-Range: bytes a-b/total`.
     /// Returns nil unless the header agrees with what arrived, so a proxy that answered a suffix
     /// request with some other region cannot install bytes at the wrong offset.
+    ///
+    /// Audit DMX-8: a suffix is the END of the source, so the span has to end on the byte before a
+    /// numeric total. Without that, `bytes <2^63-65536>-<Int64.max>/*` installed a span whose `end`
+    /// overflows on the first read that reaches it.
     static func suffixRangeStart(_ http: HTTPURLResponse, expectedLength: Int) -> Int64? {
         guard let value = http.value(forHTTPHeaderField: "Content-Range") else { return nil }
         let scanner = value.replacingOccurrences(of: "bytes ", with: "")
         let parts = scanner.split(separator: "/", maxSplits: 1)
-        guard let range = parts.first else { return nil }
-        let bounds = range.split(separator: "-", maxSplits: 1)
+        guard parts.count == 2,
+              let total = Int64(parts[1].trimmingCharacters(in: .whitespaces)) else { return nil }
+        let bounds = parts[0].split(separator: "-", maxSplits: 1)
         guard bounds.count == 2,
               let start = Int64(bounds[0].trimmingCharacters(in: .whitespaces)),
               let end = Int64(bounds[1].trimmingCharacters(in: .whitespaces)),
-              start >= 0, end >= start,
+              start >= 0, end >= start, end == total - 1,
               end - start + 1 == Int64(expectedLength) else { return nil }
         return start
     }
@@ -4861,7 +4866,10 @@ private final class TailPrefetchDelegate: NSObject, URLSessionDataDelegate, @unc
 
     func urlSession(_ session: URLSession, dataTask: URLSessionDataTask, didReceive data: Data) {
         guard buffer.count < expectedLength else { return }
-        buffer.append(data)
+        // Audit DMX-9: clamped, as `RangeFetchDelegate` does. Appended whole, an origin that sends a
+        // few bytes past its own Content-Range read as a SHORT body and latched the origin as one
+        // that declines suffix ranges for the rest of the process.
+        buffer.append(data.prefix(expectedLength - buffer.count))
     }
 
     func urlSession(_ session: URLSession, task: URLSessionTask, didCompleteWithError error: Error?) {
diff --git a/Tests/AetherEngineTests/Issue281ColdStartRoundTripTests.swift b/Tests/AetherEngineTests/Issue281ColdStartRoundTripTests.swift
index 429df2046..ac63d15bf 100644
--- a/Tests/AetherEngineTests/Issue281ColdStartRoundTripTests.swift
+++ b/Tests/AetherEngineTests/Issue281ColdStartRoundTripTests.swift
@@ -395,6 +395,14 @@ struct Issue281ColdStartRoundTripTests {
         #expect(AVIOReader.suffixRangeStart(response(nil, length: 100), expectedLength: 100) == nil)
         #expect(AVIOReader.suffixRangeStart(response("bytes */1000", length: 100),
                                             expectedLength: 100) == nil)
+        // Audit DMX-8: a suffix ends on the last byte of a numeric total, or it is not a suffix.
+        #expect(AVIOReader.suffixRangeStart(response("bytes 900-999/*", length: 100),
+                                            expectedLength: 100) == nil)
+        #expect(AVIOReader.suffixRangeStart(response("bytes 900-999/2000", length: 100),
+                                            expectedLength: 100) == nil)
+        #expect(AVIOReader.suffixRangeStart(
+            response("bytes 9223372036854775708-9223372036854775807/*", length: 100),
+            expectedLength: 100) == nil)
     }
 
     /// The calibration the in-flight test above no longer carries, checked where it costs no socket

From c92ec8bbcf0dd1f3269befae3012b5c68d55658e Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 05:10:09 +0200
Subject: [PATCH 031/359] fix(engine): a software rebuild superseded by stop()
 or a new load() no longer publishes an error (audit CORE-1)

The AE#561 escalation read every throw of its rebuild as "the software path cannot serve this
session", including the CancellationError a superseded load() unwinds with, and published
`.error` onto whatever owned the engine by then. It now stays silent on cancellation, and the
load() catches that publish a failure re-check the generation first, so a host or open that
failed only because it was torn down mid-flight unwinds as a cancellation too.

stopInternal now cancels the #65 stall re-engage and #93 item-death confirm tasks with the rest
of the session, so a background teardown cannot start a software rebuild seconds later. The #93
rung also hands the escalation to its own task: the rebuild's load() cancels the confirm task it
ran in, and a load running in a cancelled task turns every `try? await Task.sleep` poll (the
panel-switch wait) into a hot spin on the main actor. No throwing cancellation-aware await exists
on the software reload path (the probe and the host load are detached), so the escalation did not
always fail, but it was not running where it should.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 .../AetherEngine/AetherEngine+Loading.swift   | 18 ++++++++-----
 .../AetherEngine+SoftwarePathEscalation.swift |  6 +++++
 Sources/AetherEngine/AetherEngine.swift       | 14 ++++++++++
 .../SoftwarePathEscalationTests.swift         | 26 +++++++++++++++++++
 4 files changed, 57 insertions(+), 7 deletions(-)

diff --git a/Sources/AetherEngine/AetherEngine+Loading.swift b/Sources/AetherEngine/AetherEngine+Loading.swift
index 0a7577fc1..7b39db5a9 100644
--- a/Sources/AetherEngine/AetherEngine+Loading.swift
+++ b/Sources/AetherEngine/AetherEngine+Loading.swift
@@ -1595,14 +1595,18 @@ extension AetherEngine {
                         // AE#561: a frozen position across three reloads is the reload answering the
                         // same bytes three times. Offer the source to the engine's own decoder before
                         // the session is left dead.
-                        await self.escalateToSoftwarePath(
-                            SoftwarePathEscalation.Request(
-                                domain: SoftwarePathEscalation.mediaErrorDomain,
-                                code: 0,
-                                message: "item death at a frozen position, revive budget exhausted",
-                                positionSeconds: position.isFinite ? max(0, position) : 0
-                            )
+                        //
+                        // Its own task (audit CORE-1): the rebuild's load() cancels THIS task in its
+                        // prologue, and a rebuild left running in a cancelled task turns every
+                        // `try? await Task.sleep` poll on its way (the panel-switch wait) into a hot
+                        // spin on the main actor. Supersession is answered by the load generation.
+                        let request = SoftwarePathEscalation.Request(
+                            domain: SoftwarePathEscalation.mediaErrorDomain,
+                            code: 0,
+                            message: "item death at a frozen position, revive budget exhausted",
+                            positionSeconds: position.isFinite ? max(0, position) : 0
                         )
+                        Task { @MainActor [weak self] in await self?.escalateToSoftwarePath(request) }
                         return
                     }
                     EngineLog.emit(
diff --git a/Sources/AetherEngine/AetherEngine+SoftwarePathEscalation.swift b/Sources/AetherEngine/AetherEngine+SoftwarePathEscalation.swift
index 1f73cba04..a11c48ece 100644
--- a/Sources/AetherEngine/AetherEngine+SoftwarePathEscalation.swift
+++ b/Sources/AetherEngine/AetherEngine+SoftwarePathEscalation.swift
@@ -42,6 +42,12 @@ extension AetherEngine {
             try await reloadAtCurrentPosition { $0.preferredDecodePath = .software }
             EngineLog.emit(
                 "[AetherEngine] #561 rebuilt on the software path", category: .engine)
+        } catch is CancellationError {
+            // Audit CORE-1: a stop() or a new load() superseded the rebuild. The session this
+            // failure belonged to is gone, and `.error` would land on whatever replaced it.
+            EngineLog.emit(
+                "[AetherEngine] #561 software rebuild superseded; nothing to surface",
+                category: .engine)
         } catch {
             // The rung is gone and the failure was never surfaced, so it has to be surfaced here or
             // the session would sit on a picture that stopped with nothing said.
diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index e23751429..bb2ff425b 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -3833,6 +3833,8 @@ public final class AetherEngine: ObservableObject {
             } catch is CancellationError {
                 throw CancellationError()
             } catch {
+                // A failure that lands after a successor took over is not this session's to publish.
+                if loadGeneration != gen { throw CancellationError() }
                 // Without this catch, a throwing loadRemoteHLS would strand state at .loading forever.
                 publishError(.sourceOpenFailed, "Failed to load: \(error.localizedDescription)", underlying: error)
                 throw error
@@ -4094,6 +4096,7 @@ public final class AetherEngine: ObservableObject {
             } catch is CancellationError {
                 throw CancellationError()
             } catch {
+                if loadGeneration != gen { throw CancellationError() }
                 publishError(.sourceOpenFailed, "Failed to load: \(error.localizedDescription)", underlying: error)
                 throw error
             }
@@ -4240,6 +4243,7 @@ public final class AetherEngine: ObservableObject {
                 // Superseded: successor owns state.
                 throw CancellationError()
             } catch {
+                if loadGeneration != gen { throw CancellationError() }
                 publishLoadFailure(error)
                 throw error
             }
@@ -4773,6 +4777,9 @@ public final class AetherEngine: ObservableObject {
             // Superseded.
             throw CancellationError()
         } catch {
+            // A host or open that failed because stop()/load() tore it down mid-flight throws its own
+            // error before the post-load generation check; the successor owns the state (audit CORE-1).
+            if loadGeneration != gen { throw CancellationError() }
             // AE#246: the load-time probe failed for a reason that was not the HLS classification, so the
             // AE#154 check above saw an inconclusive failure and this load fell through to the loopback
             // path with no preopened demuxer. The session's own open is then the first one to read the
@@ -6677,6 +6684,13 @@ public final class AetherEngine: ObservableObject {
         liveOutageSourceGivenUp = false
         liveReloadWatchdogTask?.cancel()
         liveReloadWatchdogTask = nil
+        // Audit CORE-1: the #65/#93 recovery rungs belong to the session being torn down. Left
+        // running across a background teardown, the item-death confirm could start a software
+        // rebuild seconds later with the app suspended.
+        stallReengageTask?.cancel()
+        stallReengageTask = nil
+        itemDeathConfirmTask?.cancel()
+        itemDeathConfirmTask = nil
         // #95: stop the tap reader before the session (and its SegmentCache) goes away.
         // #356: counterpart to the install line, because a session-preserving reload lands here
         // too. The host sees its stream finish and has to re-install; without this the device log
diff --git a/Tests/AetherEngineTests/SoftwarePathEscalationTests.swift b/Tests/AetherEngineTests/SoftwarePathEscalationTests.swift
index 3a9b6d2ac..9c154fcd5 100644
--- a/Tests/AetherEngineTests/SoftwarePathEscalationTests.swift
+++ b/Tests/AetherEngineTests/SoftwarePathEscalationTests.swift
@@ -71,4 +71,30 @@ struct SoftwarePathEscalationTests {
         #expect(budget.isSpent)
         #expect(!budget.take())
     }
+
+    /// Audit CORE-1: the rebuild is a full load(), and a stop() landing inside it unwinds that load
+    /// with a CancellationError. The escalation read every throw as "the software path cannot serve
+    /// this session" and published `.error` onto an engine the viewer had already left.
+    @Test("A rebuild superseded by stop() leaves the engine idle, not in error", .timeLimit(.minutes(2)))
+    @MainActor
+    func supersededRebuildIsSilent() async throws {
+        let origin = try ProbeHTTPTestOrigin(data: ProbeTestFixtures.hdr10Plus(), stage: .headers)
+        defer { origin.stop() }
+        let engine = try AetherEngine()
+        engine.loadedURL = try #require(URL(string: "http://127.0.0.1:\(origin.port)/source.mkv"))
+
+        let escalation = Task { @MainActor in
+            await engine.escalateToSoftwarePath(SoftwarePathEscalation.Request(
+                domain: SoftwarePathEscalation.mediaErrorDomain, code: 0,
+                message: "item death at a frozen position", positionSeconds: 0))
+        }
+        // The rebuild's probe is parked on the origin, so the stop lands inside the load.
+        try await waitFor { origin.blocked.entered }
+        engine.stop()
+        origin.stop()
+        await escalation.value
+
+        #expect(engine.state == .idle)
+        #expect(engine.errorInfo == nil)
+    }
 }

From bf00ec5972f02e8c7d09eaab664668e2956c1014 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 05:10:14 +0200
Subject: [PATCH 032/359] fix(demuxer): end an over-delivered range and refuse
 a misplaced 206 (audit DMX-1, DMX-5)

DMX-1: once delivery crossed the requested range end, `connEnded` latched
without a cancel, which also disarmed the high-water end, so a 200 that
ignored Range at offset 0 (or a 206 wider than asked) streamed the rest
of the file into the window. Bytes past the range end are now dropped and
the transfer is ended; the frontier refill asks for what follows. The
"bounded by construction" comments now say where the bound is enforced.

DMX-5: the persistent, chunk and detour paths placed a 206 body at the
requested offset without checking Content-Range. A 206 whose start
differs is now refused like a 200 that ignored Range.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 Sources/AetherEngine/Demuxer/AVIOReader.swift |  86 ++++++++++++--
 .../RangedResponseIntegrityTests.swift        | 110 ++++++++++++++++++
 .../ThrottledOriginServer.swift               |   5 +
 3 files changed, 194 insertions(+), 7 deletions(-)
 create mode 100644 Tests/AetherEngineTests/RangedResponseIntegrityTests.swift

diff --git a/Sources/AetherEngine/Demuxer/AVIOReader.swift b/Sources/AetherEngine/Demuxer/AVIOReader.swift
index 359ea8c8c..3b9604c49 100644
--- a/Sources/AetherEngine/Demuxer/AVIOReader.swift
+++ b/Sources/AetherEngine/Demuxer/AVIOReader.swift
@@ -567,8 +567,9 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
     private static let liveWinHighWaterDefault = 64 * 1024 * 1024
     private static let winLowWater = 8 * 1024 * 1024
     // #220: how much the persistent reader asks for at a time. Bounds a single request's
-    // exposure by construction (an origin cannot serve more than it was asked for, whatever
-    // it thinks of flow control) and keeps the request cadence modest on a healthy link:
+    // exposure: `appendPersistentData` drops anything past the requested end and ends the
+    // transfer (audit DMX-1), so an origin that ignores Range or answers wider than asked
+    // cannot grow the window past it. It also keeps the request cadence modest on a healthy link:
     // one request per range boundary while the consumer keeps up, one per
     // highWater-to-lowWater drain cycle when the origin outruns it.
     static let persistentRangeBytes: Int64 = 32 * 1024 * 1024
@@ -782,6 +783,13 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
         return activeTransfer != nil
     }
 
+    /// Bytes the persistent window holds, behind and ahead of the cursor.
+    var windowBytesForTesting: Int {
+        winCond.lock()
+        defer { winCond.unlock() }
+        return window.count
+    }
+
     /// #220/#310: set when WE ended the connection at `winHighWater` (ending is the only
     /// non-advisory flow control, and a task left suspended instead is a dormant flow — see
     /// the backpressure doc block above). The read loop re-requests at the frontier — at low
@@ -2501,6 +2509,10 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
                     EngineLog.emit("[AVIOReader] detour: server ignored Range (200 for offset \(offset)); rejecting", category: .demux, level: .verbose)
                     return .failed
                 }
+                if !isLive, let served = Self.misplacedRangeStart(http, requestedOffset: offset) {
+                    EngineLog.emit("[AVIOReader] detour: 206 starts at \(served), not \(offset); rejecting (audit DMX-5)", category: .demux)
+                    return .failed
+                }
             }
             addBytesFetched(data.count)
             return .ok(data)
@@ -2825,8 +2837,8 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
         winCond.lock()
         connGeneration &+= 1
         let generation = connGeneration
-        // #220: VOD asks for a fixed amount at a time, so the origin cannot deliver more than
-        // was requested and the window is bounded by construction rather than by reaction. Two
+        // #220: VOD asks for a fixed amount at a time, and anything an origin delivers past it is
+        // dropped at the append (audit DMX-1), so the window is bounded by the ask. Two
         // cases keep the open-ended form: live, where the material is produced in real time so
         // the origin cannot outrun media rate and the end is moving, and a source whose total
         // size is not resolved yet, where there is nothing to clamp the last range against. An
@@ -3113,15 +3125,29 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
     /// delegate callback has no flow-control contract (TLS/H2 transports keep reading at
     /// line rate into unbounded internal buffers, the #174 EXC_RESOURCE). Force-copy
     /// releases source dispatch_data per delivery (same leak control as the chunk path).
-    fileprivate func appendPersistentData(_ data: Data, generation: Int) {
+    fileprivate func appendPersistentData(_ delivered: Data, generation: Int) {
         winCond.lock()
         guard generation == connGeneration, !isFullyClosed else {
             // #93: a slow read's summary line reports how much data the stale-generation
             // guard discarded while the read waited.
-            staleGenDroppedBytes += Int64(data.count)
+            staleGenDroppedBytes += Int64(delivered.count)
             winCond.unlock()
             return
         }
+        // Audit DMX-1: the range is the bound only if bytes past its end are refused. A 200 that
+        // ignored Range at offset 0, or a 206 wider than asked, otherwise kept appending under
+        // `connEnded`, which also disarms the high-water end below, so the rest of the file
+        // streamed into the window. The excess is dropped and the transfer ended; the frontier
+        // refill asks for it properly.
+        var data = delivered
+        var overDelivered = false
+        if let end = connRangeEnd {
+            let room = end + 1 - (winStart + Int64(window.count))
+            if Int64(data.count) > room {
+                data = data.prefix(Int(max(0, room)))
+                overDelivered = true
+            }
+        }
         lastDeliveryAt = DispatchTime.now()   // #309: the delivery-gap watchdog's only input
         var firstDataMs: Double? = nil
         if !connFirstDataSeen {
@@ -3164,9 +3190,14 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
         addBytesFetched(count)
         // #220: the requested range has been delivered in full. That ends the connection on
         // purpose; the read loop re-requests at the frontier once the consumer has drawn down.
+        var overDeliveredTransfer: (any PersistentTransfer)?
         if let end = connRangeEnd, winStart + Int64(window.count) > end {
             connEndedAtRangeEnd = true
             connEnded = true
+            if overDelivered {
+                overDeliveredTransfer = activeTransfer
+                activeTransfer = nil
+            }
         }
         winCond.broadcast()
         // #310: past high water the connection is ENDED, not suspended. suspend() is
@@ -3195,6 +3226,14 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
             winCond.broadcast()
         }
         winCond.unlock()
+        if let overDeliveredTransfer {
+            EngineLog.emit(
+                "[AVIOReader] \(label) gen=\(generation) origin delivered past the requested range "
+                + "end; ending the connection (audit DMX-1)",
+                category: .demux)
+            overDeliveredTransfer.cancelTransfer()
+            overDeliveredTransfer.releaseOriginTicket()
+        }
         if let toCancel {
             EngineLog.emit(
                 "[AVIOReader] \(label) window high water: \(ahead / 1024 / 1024)MB ahead; ending the "
@@ -3323,6 +3362,17 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
             )
             isOK = false
         }
+        // Live is exempt for the same reason as above: its offset is bookkeeping, and the append
+        // anchors the bytes at the frontier whatever the origin calls them.
+        if isOK, !isLive, generation == connGeneration,
+           let served = Self.misplacedRangeStart(http, requestedOffset: requestedOffset) {
+            EngineLog.emit(
+                "[AVIOReader] \(label) gen=\(generation) 206 starts at \(served), not the requested "
+                + "\(requestedOffset); rejecting body (audit DMX-5)",
+                category: .demux
+            )
+            isOK = false
+        }
 
         if isOK {
             recordResolvedURL(respondedBy)
@@ -3359,7 +3409,7 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
         // #310: our own high-water cancel completes here as NSURLErrorCancelled. That end was
         // already logged where it was decided; reporting it as an error too would make every
         // drain cycle against a fast origin read like a transport fault.
-        let deliberateEnd = isCurrentGen && connEndedByBackpressure
+        let deliberateEnd = isCurrentGen && (connEndedByBackpressure || connEndedAtRangeEnd)
         let windowAhead = isCurrentGen ? (window.count - max(0, Int(position - winStart))) : 0
         winCond.broadcast()
         winCond.unlock()
@@ -3620,6 +3670,21 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
     /// Total size from a data-connection response: `Content-Range` total on a 206, or
     /// `Content-Length` on a from-0 2xx (origins that answer 200 ignoring Range). Nil when
     /// the origin gave no usable length (chunked, or an unknown `*` total). Issue #70.
+    /// Audit DMX-5: where a 206 says its body starts, when that is not where it was asked to.
+    /// Every ranged path here places the body at the REQUESTED offset, so a 206 aligned to an
+    /// edge's own chunk boundary would shift every later read by the difference. Nil for any other
+    /// status and for a Content-Range this cannot read (those keep the lenient historical path).
+    static func misplacedRangeStart(_ http: HTTPURLResponse, requestedOffset: Int64) -> Int64? {
+        guard http.statusCode == 206,
+              let value = http.value(forHTTPHeaderField: "Content-Range") else { return nil }
+        let trimmed = value.trimmingCharacters(in: .whitespaces)
+        guard trimmed.lowercased().hasPrefix("bytes ") else { return nil }
+        let span = trimmed.dropFirst("bytes ".count).split(separator: "/", maxSplits: 1).first ?? ""
+        guard let dash = span.firstIndex(of: "-"),
+              let start = Int64(span[..<dash].trimmingCharacters(in: .whitespaces)) else { return nil }
+        return start == requestedOffset ? nil : start
+    }
+
     static func sizeFromResponse(_ http: HTTPURLResponse, requestedOffset: Int64) -> Int64? {
         // On a 206 the total lives ONLY in Content-Range; Content-Length is the partial span,
         // so a 206 with an unknown (`*`) or unparseable range must report no size, never fall
@@ -3880,6 +3945,13 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
                         )
                         return nil
                     }
+                    if !isLive, let served = Self.misplacedRangeStart(http, requestedOffset: offset) {
+                        EngineLog.emit(
+                            "[AVIOReader] chunk fetch: 206 starts at \(served), not \(offset); rejecting (audit DMX-5)",
+                            category: .demux
+                        )
+                        return nil
+                    }
                 }
                 addBytesFetched(data.count)
                 return data
diff --git a/Tests/AetherEngineTests/RangedResponseIntegrityTests.swift b/Tests/AetherEngineTests/RangedResponseIntegrityTests.swift
new file mode 100644
index 000000000..f17a1cf6e
--- /dev/null
+++ b/Tests/AetherEngineTests/RangedResponseIntegrityTests.swift
@@ -0,0 +1,110 @@
+import Testing
+import Foundation
+@testable import AetherEngine
+
+/// A ranged answer is only trusted as far as it matches what was asked: it has to start at the
+/// requested offset (audit DMX-5), and nothing past the requested end is kept (audit DMX-1).
+@Suite("Ranged response integrity")
+struct RangedResponseIntegrityTests {
+
+    private final class FirstRequestAt: @unchecked Sendable {
+        private let lock = NSLock()
+        private var seen = false
+        func claim() -> Bool {
+            lock.lock()
+            defer { lock.unlock() }
+            if seen { return false }
+            seen = true
+            return true
+        }
+    }
+
+    private func readExact(_ reader: AVIOReader, _ size: Int) -> [UInt8]? {
+        let buf = UnsafeMutablePointer<UInt8>.allocate(capacity: size)
+        defer { buf.deallocate() }
+        var got = 0
+        while got < size {
+            let n = reader.read(into: buf.advanced(by: got), size: Int32(size - got))
+            guard n > 0 else { return nil }
+            got += Int(n)
+        }
+        return Array(UnsafeBufferPointer(start: buf, count: size))
+    }
+
+    private func expected(at offset: Int64, count: Int) -> [UInt8] {
+        (0..<count).map { ThrottledOriginServer.patternByte(at: offset + Int64($0)) }
+    }
+
+    @Test("an origin that answers wider than the range asked for is ended at the range end",
+          .timeLimit(.minutes(1)))
+    func overDeliveryIsEndedAtTheRangeEnd() async throws {
+        let server = try #require(ThrottledOriginServer(totalSize: 512 * 1024 * 1024,
+                                                        ignoreRangeEnd: true))
+        defer { server.stop() }
+        let firstRange: Int64 = 512 * 1024
+        let reader = AVIOReader(url: URL(string: "http://127.0.0.1:\(server.port)/movie.bin")!,
+                                boundedInitialFetch: firstRange)
+        defer { reader.markClosed(); reader.close() }
+        try reader.open()
+        #expect(readExact(reader, 64 * 1024) != nil)
+
+        try await waitFor { !reader.hasLiveConnectionForTesting }
+        #expect(reader.windowBytesForTesting <= Int(firstRange),
+                "the window held \(reader.windowBytesForTesting)B of a \(firstRange)B range")
+    }
+
+    @Test("a persistent 206 that starts elsewhere is refused, not placed at the requested offset",
+          .timeLimit(.minutes(1)))
+    func persistentMisplacedRangeIsRefused() async throws {
+        let target: Int64 = 64 * 1024 * 1024
+        let once = FirstRequestAt()
+        let respond: @Sendable (Int, Int64, String) -> ThrottledOriginServer.Directive = { _, offset, _ in
+            offset == target && once.claim() ? .serve206From(start: target - 4096) : .serve206
+        }
+        let origin = ThrottledOriginServer(totalSize: 512 * 1024 * 1024, patternedBody: true, respond: respond)
+        let server = try #require(origin)
+        defer { server.stop() }
+        let reader = AVIOReader(url: URL(string: "http://127.0.0.1:\(server.port)/movie.bin")!)
+        defer { reader.markClosed(); reader.close() }
+        try reader.open()
+        #expect(readExact(reader, 4096) == expected(at: 0, count: 4096))
+
+        #expect(reader.seek(offset: target, whence: SEEK_SET) == target)
+        #expect(readExact(reader, 4096) == expected(at: target, count: 4096))
+    }
+
+    @Test("a chunk fetch 206 that starts elsewhere is refused", .timeLimit(.minutes(1)))
+    func chunkMisplacedRangeIsRefused() async throws {
+        let target: Int64 = 16 * 1024 * 1024
+        let once = FirstRequestAt()
+        let respond: @Sendable (Int, Int64, String) -> ThrottledOriginServer.Directive = { _, offset, _ in
+            offset == target && once.claim() ? .serve206From(start: target - 4096) : .serve206
+        }
+        let origin = ThrottledOriginServer(totalSize: 64 * 1024 * 1024, patternedBody: true, respond: respond)
+        let server = try #require(origin)
+        defer { server.stop() }
+        let reader = AVIOReader(url: URL(string: "http://127.0.0.1:\(server.port)/movie.bin")!,
+                                chunkSize: 256 * 1024, prefetchEnabled: false)
+        defer { reader.markClosed(); reader.close() }
+        try reader.open()
+
+        #expect(reader.seek(offset: target, whence: SEEK_SET) == target)
+        let got = readExact(reader, 4096)
+        // Refused and retried is fine, failed is fine; the misplaced bytes are not.
+        if let got { #expect(got == expected(at: target, count: 4096)) }
+    }
+
+    @Test("Content-Range start is compared against the requested offset")
+    func misplacedStartIsNamed() {
+        let url = URL(string: "http://example.invalid/movie.bin")!
+        func response(_ status: Int, _ contentRange: String?) -> HTTPURLResponse {
+            HTTPURLResponse(url: url, statusCode: status, httpVersion: "HTTP/1.1",
+                            headerFields: contentRange.map { ["Content-Range": $0] } ?? [:])!
+        }
+        #expect(AVIOReader.misplacedRangeStart(response(206, "bytes 100-199/1000"), requestedOffset: 100) == nil)
+        #expect(AVIOReader.misplacedRangeStart(response(206, "bytes 64-199/1000"), requestedOffset: 100) == 64)
+        #expect(AVIOReader.misplacedRangeStart(response(206, "bytes 100-199/*"), requestedOffset: 100) == nil)
+        #expect(AVIOReader.misplacedRangeStart(response(206, nil), requestedOffset: 100) == nil)
+        #expect(AVIOReader.misplacedRangeStart(response(200, "bytes 64-199/1000"), requestedOffset: 100) == nil)
+    }
+}
diff --git a/Tests/AetherEngineTests/ThrottledOriginServer.swift b/Tests/AetherEngineTests/ThrottledOriginServer.swift
index e37d9b3aa..f83288609 100644
--- a/Tests/AetherEngineTests/ThrottledOriginServer.swift
+++ b/Tests/AetherEngineTests/ThrottledOriginServer.swift
@@ -30,6 +30,9 @@ final class ThrottledOriginServer: @unchecked Sendable {
         /// ended SHORT of its Content-Length - the observable behind the sequential reader's
         /// EIO-not-EOF distinction (a lost source must not read as end-of-media).
         case serveThenDrop(afterBytes: Int64)
+        /// Audit DMX-5: a 206 that starts `start` rather than where it was asked, the way an edge
+        /// that aligns ranges to its own chunk boundary answers. The body is that range's.
+        case serve206From(start: Int64)
     }
 
     let port: UInt16
@@ -314,6 +317,8 @@ final class ThrottledOriginServer: @unchecked Sendable {
         switch respond(requestIndex, offset, path) {
         case .serve206:
             break
+        case .serve206From(let start):
+            offset = max(0, min(start, totalSize - 1))
         case .serveThenGoSilent(let afterBytes):
             silentAfter = max(0, afterBytes)
         case .serveThenDrop(let afterBytes):

From 06f72185aa08af43e88d8fd5071a6d756591dcd9 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 05:10:54 +0200
Subject: [PATCH 033/359] fix(diag): redact credential names and values that
 sit percent-encoded inside another URL (audit NET-1)

A URL logged inside another URL's query arrives as `%26api%5Fkey%3D<token>`.
The key matcher needed a non-alphanumeric byte in front of the key and a
literal `=` or `:` after it, so none of that matched and the token went out.

Keys, separators, quotes and terminators are now read through a percent
decoder that follows `%25` for values encoded more than once. The byte in
front of a key counts as a boundary when it closes an escape that decodes to
one. A terminator only ends a value when it sits under no more encoding
layers than the `=` did, so `api_key=abc%26def` in a plain query still loses
the whole value, while in an encoded query `%26` is the `&` that ends it.
Lines without a `%` scan exactly as before.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 .../Diagnostics/LogRedaction.swift            | 127 +++++++++++++++---
 .../AetherEngineTests/LogRedactionTests.swift |  46 +++++++
 2 files changed, 151 insertions(+), 22 deletions(-)

diff --git a/Sources/AetherEngine/Diagnostics/LogRedaction.swift b/Sources/AetherEngine/Diagnostics/LogRedaction.swift
index 5aff5db1c..5767b7cba 100644
--- a/Sources/AetherEngine/Diagnostics/LogRedaction.swift
+++ b/Sources/AetherEngine/Diagnostics/LogRedaction.swift
@@ -83,58 +83,141 @@ enum LogRedaction {
         return String(decoding: out, as: UTF8.self)
     }
 
-    /// Length of the key starting here, or nil. The key must start on a boundary, else `token` would
-    /// fire inside `hasToken`. A separator such as the `-` in `X-Emby-Token` or the `_` in `api_key` is
-    /// a boundary; an ASCII letter or digit is not.
+    /// Raw length of the key starting here, or nil. The key must start on a boundary, else `token`
+    /// would fire inside `hasToken`. A separator such as the `-` in `X-Emby-Token` or the `_` in
+    /// `api_key` is a boundary; an ASCII letter or digit is not, unless it closes a percent escape
+    /// whose decoded character is a separator.
+    ///
+    /// Audit NET-1: the key is read through `logicalByte`, so a URL logged inside another URL's query
+    /// (`%26api%5Fkey%3D…`, or `%2526api%255Fkey%253D…` encoded twice) is matched like the plain form.
     private static func matchedKeyLength(in bytes: [UInt8], at index: Int) -> Int? {
-        if index > 0, isLetterOrDigit(bytes[index - 1]) { return nil }
-        for key in keys where index + key.count <= bytes.count {
+        let first = logicalByte(in: bytes, at: index)
+        guard keyInitials.contains(lowercased(first.byte)) else { return nil }
+        if precededByWordCharacter(bytes, at: index) { return nil }
+        for key in keys {
+            var j = index
             var matched = true
-            for offset in 0 ..< key.count where lowercased(bytes[index + offset]) != key[offset] {
-                matched = false
-                break
+            for keyByte in key {
+                guard j < bytes.count else { matched = false; break }
+                let char = logicalByte(in: bytes, at: j)
+                guard lowercased(char.byte) == keyByte else { matched = false; break }
+                j += char.width
             }
-            if matched { return key.count }
+            if matched { return j - index }
         }
         return nil
     }
 
+    private static let keyInitials = Set(keys.map { $0[0] })
+
     /// The span holding the secret, given the index just past the key. Covers the query form
     /// (`api_key=abc&next=1`), both header forms (`Token="abc"`, `X-Emby-Token: abc`) and the cookie
     /// form (`connect.sid=abc; Path=/`). Nil when there is no assignment or the value is empty, so
     /// `api_key=` and a bare mention in prose are left alone.
+    ///
+    /// Characters are read through `logicalByte`. A terminator ends the value only when it sits under
+    /// no more encoding layers than the `=` did: inside a plain query `%26` is part of the value, inside
+    /// an encoded one it is the `&` that ends it. With no escape in sight this is the byte scan it was.
     private static func valueRange(in bytes: [UInt8], after keyEnd: Int) -> Range<Int>? {
         var i = keyEnd
-        while i < bytes.count, bytes[i] == UInt8(ascii: " ") { i += 1 }
-        guard i < bytes.count, bytes[i] == UInt8(ascii: "=") || bytes[i] == UInt8(ascii: ":") else {
+        while i < bytes.count, case let char = logicalByte(in: bytes, at: i), char.byte == space {
+            i += char.width
+        }
+        guard i < bytes.count else { return nil }
+        let separator = logicalByte(in: bytes, at: i)
+        guard separator.byte == UInt8(ascii: "=") || separator.byte == UInt8(ascii: ":") else {
             return nil
         }
-        let isHeaderSeparator = bytes[i] == UInt8(ascii: ":")
-        i += 1
+        let isHeaderSeparator = separator.byte == UInt8(ascii: ":")
+        let depth = separator.depth
+        i += separator.width
 
         // Only a header separator may be followed by spaces. After `=` the value starts immediately:
         // a URL query and a cookie never space it out, and skipping here would let prose such as
         // "api_key= (missing)" read as a credential and swallow the rest of the line.
         var afterSpaces = i
-        while afterSpaces < bytes.count, bytes[afterSpaces] == UInt8(ascii: " ") { afterSpaces += 1 }
+        while afterSpaces < bytes.count, case let char = logicalByte(in: bytes, at: afterSpaces),
+              char.byte == space {
+            afterSpaces += char.width
+        }
         var quote: UInt8?
-        if afterSpaces < bytes.count,
-           bytes[afterSpaces] == UInt8(ascii: "\"") || bytes[afterSpaces] == UInt8(ascii: "'") {
-            quote = bytes[afterSpaces]
-            i = afterSpaces + 1
+        if afterSpaces < bytes.count, case let char = logicalByte(in: bytes, at: afterSpaces),
+           char.depth <= depth, char.byte == UInt8(ascii: "\"") || char.byte == UInt8(ascii: "'") {
+            quote = char.byte
+            i = afterSpaces + char.width
         } else if isHeaderSeparator {
             i = afterSpaces
         }
         let start = i
 
-        if let quote {
-            while i < bytes.count, bytes[i] != quote { i += 1 }
-        } else {
-            while i < bytes.count, !isValueTerminator(bytes[i]) { i += 1 }
+        while i < bytes.count {
+            let char = logicalByte(in: bytes, at: i)
+            if char.depth <= depth {
+                if let quote, char.byte == quote { break }
+                if quote == nil, isValueTerminator(char.byte) { break }
+            }
+            i += char.width
         }
         return start < i ? start ..< i : nil
     }
 
+    // MARK: Percent escapes
+
+    private static let percent = UInt8(ascii: "%")
+    private static let space = UInt8(ascii: " ")
+
+    /// A value encoded more often than this is not one a URL builder produces by accident.
+    private static let maximumEncodingDepth = 4
+
+    /// One character as a URL decoder would see it: a raw byte, or a `%XX` escape, followed through
+    /// `%25` when the value was encoded more than once. `depth` is the number of layers (0 = raw).
+    private static func logicalByte(in bytes: [UInt8], at index: Int)
+        -> (byte: UInt8, width: Int, depth: Int)
+    {
+        let raw = bytes[index]
+        guard raw == percent, index + 2 < bytes.count,
+              let hi = hexValue(bytes[index + 1]), let lo = hexValue(bytes[index + 2]) else {
+            return (raw, 1, 0)
+        }
+        var value = hi << 4 | lo
+        var width = 3
+        var depth = 1
+        while value == percent, depth < maximumEncodingDepth, index + width + 1 < bytes.count,
+              let nextHi = hexValue(bytes[index + width]), let nextLo = hexValue(bytes[index + width + 1]) {
+            value = nextHi << 4 | nextLo
+            width += 2
+            depth += 1
+        }
+        return (value, width, depth)
+    }
+
+    /// Whether the character in front of `index` is a letter or digit, reading a percent escape that
+    /// ends there (`%26`, `%2526`) as the character it decodes to.
+    private static func precededByWordCharacter(_ bytes: [UInt8], at index: Int) -> Bool {
+        guard index > 0, isLetterOrDigit(bytes[index - 1]) else { return false }
+        guard index >= 3, let hi = hexValue(bytes[index - 2]), let lo = hexValue(bytes[index - 1]) else {
+            return true
+        }
+        var k = index - 3
+        var layers = 1
+        while bytes[k] != percent {
+            guard layers < maximumEncodingDepth, k >= 2,
+                  bytes[k - 1] == UInt8(ascii: "2"), bytes[k] == UInt8(ascii: "5") else { return true }
+            k -= 2
+            layers += 1
+        }
+        return isLetterOrDigit(hi << 4 | lo)
+    }
+
+    private static func hexValue(_ b: UInt8) -> UInt8? {
+        switch b {
+        case UInt8(ascii: "0")...UInt8(ascii: "9"): return b - UInt8(ascii: "0")
+        case UInt8(ascii: "a")...UInt8(ascii: "f"): return b - UInt8(ascii: "a") + 10
+        case UInt8(ascii: "A")...UInt8(ascii: "F"): return b - UInt8(ascii: "A") + 10
+        default: return nil
+        }
+    }
+
     /// The secret inside a URL's userinfo, given an index that may start `://`. `smb://user:pw@host`
     /// and `https://user:pw@host` put the credential in the authority, where no key precedes it, so the
     /// key matcher cannot see it and `load url=` logs `absoluteString` whole. The user name is left
diff --git a/Tests/AetherEngineTests/LogRedactionTests.swift b/Tests/AetherEngineTests/LogRedactionTests.swift
index 243023f7c..c082c2fac 100644
--- a/Tests/AetherEngineTests/LogRedactionTests.swift
+++ b/Tests/AetherEngineTests/LogRedactionTests.swift
@@ -195,6 +195,52 @@ struct LogRedactionTests {
         #expect(LogRedaction.redact("[x] url=\(url) ok") == "[x] url=\(url) ok")
     }
 
+    @Test("a URL logged percent-encoded inside another URL's query loses its token (audit NET-1)")
+    func percentEncodedNestedURL() {
+        // The exact shape the pre-NET-1 origin relay logged on every request.
+        let origin = "https://jf.example.com/Videos/abc/master.m3u8?MediaSourceId=x&api_key=\(token)&Tag=7"
+        let encoded = origin.addingPercentEncoding(withAllowedCharacters: .alphanumerics)!
+        let lines = [
+            "[HLSLocalServer] GET /deadbeef/aether-origin-relay?origin=\(encoded) HTTP/1.1 fd=12",
+            "[NativeAVPlayerHost] #3 load url=http://127.0.0.1:50123/deadbeef/aether-origin-relay?origin=\(encoded)",
+        ]
+        for line in lines {
+            let out = LogRedaction.redact(line)
+            #expect(!out.contains(token), "leaked: \(out)")
+            #expect(out.contains("api%5Fkey%3D<redacted>%26Tag%3D7"), "\(out)")
+            #expect(out.contains("MediaSourceId%3Dx"), "diagnostic context went with it: \(out)")
+        }
+        let tail = LogRedaction.redact("GET /x?origin=\(encoded) HTTP/1.1 fd=12")
+        #expect(tail.hasSuffix(" HTTP/1.1 fd=12"))
+    }
+
+    @Test("a doubly encoded token is stripped too")
+    func doublyEncodedNestedURL() {
+        let once = "https://s/a?b=1&X-Emby-Token=\(token)&keep=1"
+            .addingPercentEncoding(withAllowedCharacters: .alphanumerics)!
+        let twice = once.addingPercentEncoding(withAllowedCharacters: .alphanumerics)!
+        let out = LogRedaction.redact("[x] outer?u=\(twice)&z=2")
+        #expect(!out.contains(token), "leaked: \(out)")
+        #expect(out.contains("<redacted>%2526keep%253D1&z=2"), "\(out)")
+    }
+
+    @Test("an encoded separator inside a plain query value stays part of the value")
+    func encodedAmpersandInPlainValue() {
+        // At depth 0 a `%26` is data in the value, not the `&` that ends it, so the whole value goes.
+        let out = LogRedaction.redact("[x] https://s/a?api_key=abc%26def&keep=1")
+        #expect(out == "[x] https://s/a?api_key=<redacted>&keep=1")
+    }
+
+    @Test("an escape that decodes to a letter is no boundary, and prose with percent signs is left alone")
+    func encodedBoundaryRules() {
+        // `%73` is `s`, so this reads `hasToken=` and must stay, like its plain form.
+        let letter = "[x] ha%73Token=visible"
+        #expect(LogRedaction.redact(letter) == letter)
+        let prose = "[x] buffer 100% full, 5%token budget, 12%3 left"
+        #expect(LogRedaction.redact(prose) == prose)
+        #expect(LogRedaction.redact("[x] a%2Ftoken%3Asecretvalue done") == "[x] a%2Ftoken%3A<redacted> done")
+    }
+
     @Test("a registered secret goes wherever it sits, raw or percent-encoded, until unregistered")
     func registeredSecret() {
         defer { LogRedaction.unregisterAll() }

From 465923bc5551cf2d317ad9509dc77e04b3de185c Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 05:11:03 +0200
Subject: [PATCH 034/359] fix(engine): a load resuming after the audio-session
 wait checks it is still current (audit CORE-6)

load() had no generation check after its first suspension point, the wait for the audio-session
category task started in init. Two loads issued back to back right after launch both wait there,
and on the remote-HLS bypass the older one then read `loadGeneration` itself, adopting its
successor's generation: every later guard passed and it mounted its own URL on the shared native
host. load() now re-checks after the wait, and the bypass takes the generation of the load that
routed to it instead of re-reading it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 .../AetherEngine/AetherEngine+Loading.swift   |  9 ++++--
 Sources/AetherEngine/AetherEngine.swift       |  9 ++++--
 .../StaleLoadGenerationTests.swift            | 29 +++++++++++++++++++
 3 files changed, 43 insertions(+), 4 deletions(-)
 create mode 100644 Tests/AetherEngineTests/StaleLoadGenerationTests.swift

diff --git a/Sources/AetherEngine/AetherEngine+Loading.swift b/Sources/AetherEngine/AetherEngine+Loading.swift
index 7b39db5a9..70a22b7dd 100644
--- a/Sources/AetherEngine/AetherEngine+Loading.swift
+++ b/Sources/AetherEngine/AetherEngine+Loading.swift
@@ -338,10 +338,15 @@ extension AetherEngine {
         #endif
     }
 
-    func loadRemoteHLS(url: URL, options: LoadOptions, startPosition: Double? = nil) async throws {
+    func loadRemoteHLS(
+        url: URL, options: LoadOptions, startPosition: Double? = nil, generation: UInt64? = nil
+    ) async throws {
+        // Audit CORE-6: the generation of the load() that routed here, not a fresh read of it, so a
+        // stale caller cannot adopt its successor's generation.
+        if let generation { try checkLoadCurrent(generation) }
         playbackBackend = .native
         // #168 follow-up: detect a superseding load()/stop() between the carriage verdict and the reroute.
-        let bypassGeneration = loadGeneration
+        let bypassGeneration = generation ?? loadGeneration
 
         let host: NativeAVPlayerHost
         if let existing = nativeHost {
diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index bb2ff425b..d9f204e49 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -3802,6 +3802,9 @@ public final class AetherEngine: ObservableObject {
         // below can activate the session: AVKit on the native/remote-HLS paths, activateRendererAudioSession()
         // on the SW and audio paths. The task is short and typically already complete, so this rarely suspends.
         await awaitAudioSessionCategoryConfigured()
+        // Audit CORE-6: the first suspension point. Two loads issued back to back right after init
+        // both wait on the same category task, and the older one must not resume as the current one.
+        try checkLoadCurrent(gen)
 
         // nativeRemoteHLS: skip probe + loopback; play HLS URL directly with AVPlayer (Jellyfin already serves HLS).
         // Routed before the probe because we never demux the m3u8.
@@ -3829,7 +3832,8 @@ public final class AetherEngine: ObservableObject {
                 // Live keeps the no-initial-seek contract every live caller relies on, so its anchor
                 // stays nil even when the host passes one.
                 try await loadRemoteHLS(url: url, options: options,
-                                        startPosition: options.isLive ? nil : startPosition)
+                                        startPosition: options.isLive ? nil : startPosition,
+                                        generation: gen)
             } catch is CancellationError {
                 throw CancellationError()
             } catch {
@@ -4092,7 +4096,8 @@ public final class AetherEngine: ObservableObject {
             registerDeclaredExternalSubtitles(loadedOptions)
             recordStartupCheckpoint(.routed, generation: startupGen)   // #361
             do {
-                try await loadRemoteHLS(url: hlsURL, options: loadedOptions, startPosition: startPosition)
+                try await loadRemoteHLS(url: hlsURL, options: loadedOptions, startPosition: startPosition,
+                                        generation: gen)
             } catch is CancellationError {
                 throw CancellationError()
             } catch {
diff --git a/Tests/AetherEngineTests/StaleLoadGenerationTests.swift b/Tests/AetherEngineTests/StaleLoadGenerationTests.swift
new file mode 100644
index 000000000..beac01908
--- /dev/null
+++ b/Tests/AetherEngineTests/StaleLoadGenerationTests.swift
@@ -0,0 +1,29 @@
+import Foundation
+import Testing
+@testable import AetherEngine
+
+/// A load that a stop() or a newer load() superseded while it was suspended must unwind without
+/// touching the engine: the state it would write belongs to its successor.
+@Suite("Superseded loads unwind without touching the successor")
+@MainActor
+struct StaleLoadGenerationTests {
+
+    /// Audit CORE-6: the remote-HLS bypass read `loadGeneration` itself, after load()'s first
+    /// suspension. A stale load resuming there adopted its successor's generation, so every later
+    /// guard in the bypass passed, and it mounted its own URL on the shared native host.
+    @Test("The remote-HLS bypass refuses a generation that has moved")
+    func bypassRefusesStaleGeneration() async throws {
+        let engine = try AetherEngine()
+        let stale = engine.loadGeneration
+        engine.stop()
+
+        await #expect(throws: CancellationError.self) {
+            try await engine.loadRemoteHLS(
+                url: URL(string: "http://127.0.0.1:9/vod.m3u8")!,
+                options: LoadOptions(nativeRemoteHLS: true),
+                generation: stale)
+        }
+        #expect(engine.nativeHost == nil)
+        #expect(engine.playbackBackend == .none)
+    }
+}

From 2398a2fe25dc9aa3fc37664178c947662bafadfc Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 05:16:30 +0200
Subject: [PATCH 035/359] fix(server): the stop line names the port it released
 (audit NET-12)

`port = 0` ran before `let closingPort = port`, so the AE#597 line meant to
tell two stopping servers apart always said "port 0 released". The pin is in
HLSLocalServerSlowPeerTests with the accept loop changes that follow.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 Sources/AetherEngine/Network/HLSLocalServer.swift | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Sources/AetherEngine/Network/HLSLocalServer.swift b/Sources/AetherEngine/Network/HLSLocalServer.swift
index f27dbeceb..e25e2f392 100644
--- a/Sources/AetherEngine/Network/HLSLocalServer.swift
+++ b/Sources/AetherEngine/Network/HLSLocalServer.swift
@@ -520,6 +520,7 @@ final class HLSLocalServer: @unchecked Sendable {
         shouldStop = true
         let fdToClose = listenFd
         listenFd = -1
+        let closingPort = port
         port = 0
         loggedMasterPlaylist = false
         loggedReducedMasterPlaylist = false
@@ -527,7 +528,6 @@ final class HLSLocalServer: @unchecked Sendable {
         mediaPlaylistBuildCount = 0
         let clients = clientFds
         clientFds.removeAll()
-        let closingPort = port
         stateLock.unlock()
         // AE#597: the one line that says a listener went away. Without it a log cannot tell a
         // server that was released from one that outlived its session on a port of its own.

From 1d5922044e9ee66d16abe629f18ad259fd938d32 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 05:16:55 +0200
Subject: [PATCH 036/359] fix(server): bound what a peer without the session
 token can hold, and back off a failing accept (audit NET-6, NET-13)

NET-6: the listener binds every interface because a wireless AirPlay
receiver fetches from it over the LAN (#86), and the LAN URL is also handed
to a server that is already listening (readiness-gate swaps, the held edge
after a reload), so binding loopback until AirPlay engages would break those.
It stays on 0.0.0.0, and what a stranger can hold is bounded instead:
- a connection that has not yet presented the token must deliver a whole
  request head within 10 s of accept, as a total rather than per recv;
- any request head must complete within 10 s of its first byte; the 60 s
  keep-alive idle before that byte is kept for AVPlayer;
- non-loopback peers may hold at most 24 of the 32 slots, so a LAN host
  cannot refuse the local player a connection.
An unauthenticated drop logs at verbose, and refusals are rate limited, so a
LAN scanner cannot scroll the host's log ring either.

NET-13: an accept failure other than the retry cases (EMFILE / ENFILE leave
the connection in the backlog) now sleeps 100 ms and logs at most once per
5 s with a count, instead of spinning a core and flooding the log.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 .../AetherEngine/Network/HLSLocalServer.swift | 149 ++++++++++--
 .../HLSLocalServerSlowPeerTests.swift         | 217 ++++++++++++++++++
 2 files changed, 347 insertions(+), 19 deletions(-)
 create mode 100644 Tests/AetherEngineTests/HLSLocalServerSlowPeerTests.swift

diff --git a/Sources/AetherEngine/Network/HLSLocalServer.swift b/Sources/AetherEngine/Network/HLSLocalServer.swift
index e25e2f392..1cab21b78 100644
--- a/Sources/AetherEngine/Network/HLSLocalServer.swift
+++ b/Sources/AetherEngine/Network/HLSLocalServer.swift
@@ -404,9 +404,32 @@ final class HLSLocalServer: @unchecked Sendable {
     /// that lasts: the client then reads a dead server. Measured with 192 pool workers blocked, a
     /// `DispatchQueue.global().async` block had not started after 35 s while a detached thread ran
     /// in 3 ms. Same reason the pump owns its thread since AE#286.
-    private static let maxConcurrentConnections = 32
+    static let maxConcurrentConnections = 32
     private var liveConnectionThreads = 0
 
+    /// Audit NET-6: the listener has to answer the LAN while an AirPlay receiver fetches from it
+    /// (#86), and the session token is only read once a whole request head has arrived. So a peer
+    /// that is not loopback may hold at most this many of the slots, and the rest stay free for
+    /// the local player however many connections a LAN host opens.
+    static let maxNonLoopbackConnections = 24
+    private var liveNonLoopbackConnections = 0
+
+    /// Audit NET-6: a connection that has not yet presented this session's token has this long,
+    /// from accept, to deliver a whole request head. Without it a trickling or idle LAN peer holds
+    /// its slot for as long as it keeps sending a byte inside the per-recv timeout.
+    static let unauthenticatedHeadSeconds: TimeInterval = 10
+    /// Once a request's first byte has arrived, the rest of its head must follow within this long,
+    /// on a connection that already authenticated too. The idle wait before that byte stays at
+    /// `keepAliveIdleSeconds`, which AVPlayer's keep-alive gaps need.
+    static let requestHeadSeconds: TimeInterval = 10
+    static let keepAliveIdleSeconds: TimeInterval = 60
+
+    /// Audit NET-13: one line per failed accept, when the process is out of descriptors, is a busy
+    /// loop that floods the host's log ring. Failures back off and their line is rate limited.
+    private static let acceptFailureBackoffMicroseconds: useconds_t = 100_000
+    private var acceptFailureLog = LogThrottle(interval: 5)
+    private var refusalLog = LogThrottle(interval: 5)
+
     // MARK: - Init
 
     /// When set (e.g. `aether-engine://engine/`), segment URIs in the playlist are absolute custom-scheme URLs routed through AVAssetResourceLoader. Nil emits relative URIs for the aetherctl HTTP workflow.
@@ -420,12 +443,16 @@ final class HLSLocalServer: @unchecked Sendable {
     /// A relay-only server has no provider: nothing here produces segments, every byte comes
     /// from the origin, and the master is whatever the origin served.
     init(provider: HLSSegmentProvider? = nil, subResourceBaseURL: URL? = nil,
-         relay: HLSOriginRelay? = nil) {
+         relay: HLSOriginRelay? = nil,
+         unauthenticatedHeadSeconds: TimeInterval = HLSLocalServer.unauthenticatedHeadSeconds) {
         self.provider = provider
         self.subResourceBaseURL = subResourceBaseURL
         self.relay = relay
+        self.unauthenticatedHeadDeadline = unauthenticatedHeadSeconds
     }
 
+    private let unauthenticatedHeadDeadline: TimeInterval
+
     /// Admits `origin` to the relay and returns the address standing in for it, for a player
     /// pointed at the relay rather than at a provider's playlists. Nil before `start()` or with
     /// no relay mounted.
@@ -465,6 +492,10 @@ final class HLSLocalServer: @unchecked Sendable {
         // Bind all interfaces (not just loopback) so an AirPlay receiver can reach the stream over the LAN
         // via the device's WiFi IP (#86, DrHurt). Local playback still uses 127.0.0.1; the URL host is only
         // swapped to the LAN IP while external playback is active. Ephemeral port, serves the current stream only.
+        // Audit NET-6 kept this rather than binding loopback until AirPlay engages: the wireless edge reloads
+        // onto a new server, but a readiness-gate swap (`airPlayHostSwapped`) and a held edge re-read after a
+        // reload hand the LAN URL to the server already listening. LAN exposure is bounded instead by the
+        // head deadlines and the loopback reserve in the accept loop.
         addr.sin_addr.s_addr = inet_addr("0.0.0.0")
 
         let bindResult = withUnsafePointer(to: &addr) { ptr -> Int32 in
@@ -576,38 +607,53 @@ final class HLSLocalServer: @unchecked Sendable {
                 if err == EINTR || err == EAGAIN || err == ECONNABORTED {
                     continue
                 }
-                EngineLog.emit("[HLSLocalServer] accept failed errno=\(err)",
-                               category: .hlsServer)
+                // EMFILE / ENFILE leave the connection in the backlog, so the next accept fails at
+                // once; without the pause this thread spins.
+                stateLock.lock()
+                let logLine = acceptFailureLog.admit(now: Self.uptimeSeconds())
+                stateLock.unlock()
+                if let suppressed = logLine {
+                    EngineLog.emit("[HLSLocalServer] accept failed errno=\(err)"
+                                   + (suppressed > 0 ? " (\(suppressed) more since the last line)" : "")
+                                   + ", backing off", category: .hlsServer)
+                }
+                usleep(Self.acceptFailureBackoffMicroseconds)
                 continue
             }
+            let isLoopbackPeer = clientAddr.sin_family == sa_family_t(AF_INET)
+                && (UInt32(bigEndian: clientAddr.sin_addr.s_addr) >> 24) == 127
 
             // SO_NOSIGPIPE on the accepted socket too, otherwise a
             // closed-peer send still raises SIGPIPE on iOS.
             var on: Int32 = 1
             _ = setsockopt(clientFd, SOL_SOCKET, SO_NOSIGPIPE, &on,
                            socklen_t(MemoryLayout<Int32>.size))
-            // 60s idle timeout. AVPlayer's typical inter-request gap
-            // is single-digit seconds; 60s is comfortable headroom.
-            var timeout = timeval(tv_sec: 60, tv_usec: 0)
-            _ = setsockopt(clientFd, SOL_SOCKET, SO_RCVTIMEO, &timeout,
-                           socklen_t(MemoryLayout<timeval>.size))
+            let acceptedAt = Self.uptimeSeconds()
 
             stateLock.lock()
             // A thread per connection has no ceiling of its own, where the pool's 64 workers were
             // one. AVPlayer keeps a handful open, so anything near this number is a client that
             // has stopped making sense and gets the socket closed rather than a thread.
             let atCapacity = liveConnectionThreads >= Self.maxConcurrentConnections
+                || (!isLoopbackPeer && liveNonLoopbackConnections >= Self.maxNonLoopbackConnections)
+            var refusalLine: Int?
             if !atCapacity {
                 liveConnectionThreads += 1
+                if !isLoopbackPeer { liveNonLoopbackConnections += 1 }
                 clientFds.insert(clientFd)
+            } else {
+                refusalLine = refusalLog.admit(now: acceptedAt)
             }
             stateLock.unlock()
 
             if atCapacity {
-                EngineLog.emit(
-                    "[HLSLocalServer] refusing fd=\(clientFd): "
-                    + "\(Self.maxConcurrentConnections) connections already open",
-                    category: .hlsServer)
+                if let suppressed = refusalLine {
+                    EngineLog.emit(
+                        "[HLSLocalServer] refusing fd=\(clientFd) (\(isLoopbackPeer ? "loopback" : "LAN") peer): "
+                        + "connection slots full"
+                        + (suppressed > 0 ? " (\(suppressed) more refused since the last line)" : ""),
+                        category: .hlsServer)
+                }
                 close(clientFd)
                 continue
             }
@@ -619,9 +665,10 @@ final class HLSLocalServer: @unchecked Sendable {
                 defer {
                     self?.stateLock.lock()
                     self?.liveConnectionThreads -= 1
+                    if !isLoopbackPeer { self?.liveNonLoopbackConnections -= 1 }
                     self?.stateLock.unlock()
                 }
-                self?.handleConnection(clientFd)
+                self?.handleConnection(clientFd, acceptedAt: acceptedAt)
             }
             worker.name = "com.aetherengine.hls.conn.\(clientFd)"
             worker.qualityOfService = .userInitiated
@@ -631,7 +678,7 @@ final class HLSLocalServer: @unchecked Sendable {
 
     // MARK: - Per-connection handler
 
-    private func handleConnection(_ fd: Int32) {
+    private func handleConnection(_ fd: Int32, acceptedAt: TimeInterval) {
         defer {
             stateLock.lock()
             clientFds.remove(fd)
@@ -642,23 +689,47 @@ final class HLSLocalServer: @unchecked Sendable {
         }
 
         // HTTP/1.1 keep-alive loop: AVPlayer reuses connections across segment fetches. Connection:close per-request tried 2026-05-20; Instruments showed it shifted the leak from libnetwork into a 570 MiB Malloc heap bucket instead (strictly worse; reverted).
+        // Every request that comes back true passed the session token check in `processRequest`,
+        // so after the first one the connection has shown it was handed a URL by this engine.
+        var authenticated = false
         while true {
             stateLock.lock()
             let stopping = shouldStop
             stateLock.unlock()
             if stopping { return }
-            guard let request = readHTTPRequest(fd) else { return }
+            let firstByteDeadline = authenticated
+                ? Self.uptimeSeconds() + Self.keepAliveIdleSeconds
+                : acceptedAt + unauthenticatedHeadDeadline
+            guard let request = readHTTPRequest(
+                fd, firstByteDeadline: firstByteDeadline, authenticated: authenticated) else { return }
             guard processRequest(request, on: fd) else { return }
+            authenticated = true
         }
     }
 
     /// Read until end of HTTP headers (`\r\n\r\n`). Returns the raw
     /// request bytes (headers only, no body, since we only accept
-    /// GET). Returns nil on EOF, error, or oversize.
-    private func readHTTPRequest(_ fd: Int32) -> Data? {
+    /// GET). Returns nil on EOF, error, oversize, or a missed deadline.
+    ///
+    /// The deadlines are totals rather than per-recv timeouts (audit NET-6): the first byte must
+    /// arrive by `firstByteDeadline`, and the whole head within `requestHeadSeconds` of it, and an
+    /// unauthenticated connection also by `firstByteDeadline`. A peer sending one byte a minute
+    /// used to keep a slot for as long as the head had room.
+    private func readHTTPRequest(_ fd: Int32, firstByteDeadline: TimeInterval,
+                                 authenticated: Bool) -> Data? {
         var buffer = Data()
         var chunk = [UInt8](repeating: 0, count: 4096)
+        var deadline = firstByteDeadline
         while true {
+            let remaining = deadline - Self.uptimeSeconds()
+            guard remaining > 0, Self.setReceiveTimeout(fd, seconds: remaining) else {
+                // A stranger that never finished a head is expected noise on a LAN listener, and
+                // one line each would let it scroll the host's log ring.
+                EngineLog.emit("[HLSLocalServer] request head deadline passed fd=\(fd) bytes=\(buffer.count)"
+                               + (authenticated ? "" : " (connection never authenticated)"),
+                               category: .hlsServer, level: authenticated ? .info : .verbose)
+                return nil
+            }
             let n = chunk.withUnsafeMutableBufferPointer { ptr -> Int in
                 recv(fd, ptr.baseAddress, ptr.count, 0)
             }
@@ -673,13 +744,16 @@ final class HLSLocalServer: @unchecked Sendable {
                 if err == EINTR { continue }
                 if err == EAGAIN || err == EWOULDBLOCK {
                     EngineLog.emit("[HLSLocalServer] recv timeout fd=\(fd)",
-                                   category: .hlsServer)
+                                   category: .hlsServer, level: authenticated ? .info : .verbose)
                     return nil
                 }
                 EngineLog.emit("[HLSLocalServer] recv error fd=\(fd) errno=\(err)",
                                category: .hlsServer)
                 return nil
             }
+            if buffer.isEmpty {
+                deadline = min(deadline, Self.uptimeSeconds() + Self.requestHeadSeconds)
+            }
             buffer.append(chunk, count: n)
             if let end = findHeadersTerminator(buffer) {
                 return buffer.prefix(end + 4)
@@ -692,6 +766,18 @@ final class HLSLocalServer: @unchecked Sendable {
         }
     }
 
+    private static func setReceiveTimeout(_ fd: Int32, seconds: TimeInterval) -> Bool {
+        let whole = Int(seconds)
+        var timeout = timeval(
+            tv_sec: whole, tv_usec: Int32(max(1, (seconds - Double(whole)) * 1_000_000)))
+        return setsockopt(fd, SOL_SOCKET, SO_RCVTIMEO, &timeout,
+                          socklen_t(MemoryLayout<timeval>.size)) == 0
+    }
+
+    private static func uptimeSeconds() -> TimeInterval {
+        Double(clock_gettime_nsec_np(CLOCK_UPTIME_RAW)) / 1_000_000_000
+    }
+
     private func findHeadersTerminator(_ buf: Data) -> Int? {
         guard buf.count >= 4 else { return nil }
         let needle: [UInt8] = [0x0D, 0x0A, 0x0D, 0x0A]
@@ -1736,3 +1822,28 @@ enum HLSLocalServerError: Error, CustomStringConvertible, LocalizedError {
 
     var errorDescription: String? { description }
 }
+
+/// Lets one line through per `interval` and counts the ones it held back, so a condition that
+/// repeats per connection or per accept costs the log one line with a tally instead of one each.
+/// Not thread safe; the owner serializes it.
+struct LogThrottle {
+    let interval: TimeInterval
+    private var lastEmitted: TimeInterval?
+    private var suppressed = 0
+
+    init(interval: TimeInterval) {
+        self.interval = interval
+    }
+
+    /// The number of lines suppressed since the last one that went out, when this one may go
+    /// out; nil when it is to be dropped.
+    mutating func admit(now: TimeInterval) -> Int? {
+        if let lastEmitted, now - lastEmitted < interval {
+            suppressed += 1
+            return nil
+        }
+        lastEmitted = now
+        defer { suppressed = 0 }
+        return suppressed
+    }
+}
diff --git a/Tests/AetherEngineTests/HLSLocalServerSlowPeerTests.swift b/Tests/AetherEngineTests/HLSLocalServerSlowPeerTests.swift
new file mode 100644
index 000000000..5f6452b9c
--- /dev/null
+++ b/Tests/AetherEngineTests/HLSLocalServerSlowPeerTests.swift
@@ -0,0 +1,217 @@
+import Foundation
+import Testing
+@testable import AetherEngine
+
+/// The listener answers the whole LAN while AirPlay needs it (#86), and the session token is read only
+/// after a complete request head. These pin what keeps a peer that never presents one from holding the
+/// slots the local player needs (audit NET-6), plus the two accept-loop diagnostics (NET-12, NET-13).
+@Suite("HLS local server against slow and silent peers", .serialized, .timeLimit(.minutes(2)))
+struct HLSLocalServerSlowPeerTests {
+
+    @Test("A connection that never sends a request head is dropped at the head deadline")
+    func idleStrangerIsDropped() async throws {
+        let server = HLSLocalServer(provider: StubProvider(), unauthenticatedHeadSeconds: 0.5)
+        try server.start()
+        defer { server.stop() }
+
+        let fd = try #require(Self.connect(port: server.port, host: "127.0.0.1"))
+        defer { close(fd) }
+        try await waitFor { server.activeConnectionCount == 1 }
+
+        // The old per-recv timeout was 60 s, so closing well inside that is the fix.
+        let dropped = try await waitFor(upTo: .seconds(20)) { server.activeConnectionCount == 0 }
+        #expect(dropped, "an idle unauthenticated connection kept its slot")
+    }
+
+    @Test("A peer trickling its head one byte at a time is dropped at the head deadline")
+    func tricklingStrangerIsDropped() async throws {
+        let server = HLSLocalServer(provider: StubProvider(), unauthenticatedHeadSeconds: 1)
+        try server.start()
+        defer { server.stop() }
+
+        let fd = try #require(Self.connect(port: server.port, host: "127.0.0.1"))
+        let trickle = Trickle(fd: fd)
+        defer { trickle.stop(); close(fd) }
+        try await waitFor { server.activeConnectionCount == 1 }
+
+        let dropped = try await waitFor(upTo: .seconds(20)) { server.activeConnectionCount == 0 }
+        #expect(dropped, "a byte every 200 ms kept an unauthenticated connection open")
+    }
+
+    @Test("A connection that presented the token keeps its keep-alive idle past the stranger deadline")
+    func authenticatedKeepAliveSurvives() async throws {
+        let server = HLSLocalServer(provider: StubProvider(), unauthenticatedHeadSeconds: 0.5)
+        try server.start()
+        defer { server.stop() }
+
+        let fd = try #require(Self.connect(port: server.port, host: "127.0.0.1"))
+        defer { close(fd) }
+        let path = "/\(server.pathToken)/media.m3u8"
+        #expect(await Self.onOwnThread { Self.requestStatus(fd: fd, path: path) } == 200)
+        try await Task.sleep(for: .milliseconds(1500))
+        #expect(await Self.onOwnThread { Self.requestStatus(fd: fd, path: path) } == 200,
+                "the second request on an authenticated keep-alive connection was not answered")
+    }
+
+    @Test("LAN peers cannot take the slots kept for loopback",
+          .enabled(if: HLSLocalServer.localActiveIPAddress() != nil))
+    func lanPeersLeaveLoopbackSlots() async throws {
+        let lanIP = try #require(HLSLocalServer.localActiveIPAddress())
+        let server = HLSLocalServer(provider: StubProvider(), unauthenticatedHeadSeconds: 60)
+        try server.start()
+        defer { server.stop() }
+
+        var held: [Int32] = []
+        defer { held.forEach { close($0) } }
+        for _ in 0 ..< HLSLocalServer.maxConcurrentConnections + 2 {
+            if let fd = Self.connect(port: server.port, host: lanIP) { held.append(fd) }
+        }
+        try await waitFor { server.activeConnectionCount >= HLSLocalServer.maxNonLoopbackConnections }
+        #expect(server.activeConnectionCount == HLSLocalServer.maxNonLoopbackConnections)
+
+        let fd = try #require(Self.connect(port: server.port, host: "127.0.0.1"))
+        defer { close(fd) }
+        let path = "/\(server.pathToken)/media.m3u8"
+        #expect(await Self.onOwnThread { Self.requestStatus(fd: fd, path: path) } == 200,
+                "a loopback player was refused while LAN peers held their share")
+    }
+
+    @Test("The stop line names the port that was released")
+    func stopLineNamesThePort() throws {
+        let tap = LineTap()
+        defer { tap.restore() }
+        let server = HLSLocalServer(provider: StubProvider())
+        try server.start()
+        let port = server.port
+        server.stop()
+        #expect(!tap.matching("[HLSLocalServer] stop: port \(port) released").isEmpty)
+        #expect(tap.matching("[HLSLocalServer] stop: port 0 released").isEmpty)
+    }
+
+    @Test("A repeating failure line goes out once per interval with a tally of the rest")
+    func throttleCountsWhatItHeldBack() {
+        var throttle = LogThrottle(interval: 5)
+        #expect(throttle.admit(now: 100) == 0)
+        #expect(throttle.admit(now: 100.1) == nil)
+        #expect(throttle.admit(now: 104.9) == nil)
+        #expect(throttle.admit(now: 105) == 2)
+        #expect(throttle.admit(now: 106) == nil)
+        #expect(throttle.admit(now: 200) == 1)
+    }
+
+    // MARK: - Helpers
+
+    private static func connect(port: UInt16, host: String) -> Int32? {
+        let fd = socket(AF_INET, SOCK_STREAM, IPPROTO_TCP)
+        guard fd >= 0 else { return nil }
+        var on: Int32 = 1
+        _ = setsockopt(fd, SOL_SOCKET, SO_NOSIGPIPE, &on, socklen_t(MemoryLayout<Int32>.size))
+        var addr = sockaddr_in()
+        addr.sin_len = UInt8(MemoryLayout<sockaddr_in>.size)
+        addr.sin_family = sa_family_t(AF_INET)
+        addr.sin_port = port.bigEndian
+        addr.sin_addr.s_addr = inet_addr(host)
+        let connected = withUnsafePointer(to: &addr) { ptr -> Int32 in
+            ptr.withMemoryRebound(to: sockaddr.self, capacity: 1) {
+                Darwin.connect(fd, $0, socklen_t(MemoryLayout<sockaddr_in>.size))
+            }
+        }
+        guard connected == 0 else {
+            close(fd)
+            return nil
+        }
+        return fd
+    }
+
+    /// One keep-alive GET on an open connection; the status, or 0. Reads until the declared body
+    /// has arrived so the next request on the same socket starts clean.
+    private static func requestStatus(fd: Int32, path: String) -> Int {
+        var timeout = timeval(tv_sec: 10, tv_usec: 0)
+        _ = setsockopt(fd, SOL_SOCKET, SO_RCVTIMEO, &timeout, socklen_t(MemoryLayout<timeval>.size))
+        let request = "GET \(path) HTTP/1.1\r\nHost: 127.0.0.1\r\n\r\n"
+        let sent = Array(request.utf8).withUnsafeBytes { send(fd, $0.baseAddress, $0.count, 0) }
+        guard sent > 0 else { return 0 }
+        var received = Data()
+        var chunk = [UInt8](repeating: 0, count: 4096)
+        while true {
+            let n = recv(fd, &chunk, chunk.count, 0)
+            guard n > 0 else { return 0 }
+            received.append(chunk, count: n)
+            guard let text = String(data: received, encoding: .utf8),
+                  let headEnd = text.range(of: "\r\n\r\n") else { continue }
+            let head = text[..<headEnd.lowerBound]
+            let length = head.components(separatedBy: "\r\n")
+                .first { $0.lowercased().hasPrefix("content-length:") }
+                .flatMap { Int($0.split(separator: ":")[1].trimmingCharacters(in: .whitespaces)) } ?? 0
+            let bodySoFar = received.count - text[..<headEnd.upperBound].utf8.count
+            guard bodySoFar >= length else { continue }
+            let parts = (head.components(separatedBy: "\r\n").first ?? "").split(separator: " ")
+            return parts.count >= 2 ? (Int(parts[1]) ?? 0) : 0
+        }
+    }
+
+    private static func onOwnThread<T: Sendable>(_ body: @escaping @Sendable () -> T) async -> T {
+        await withCheckedContinuation { continuation in
+            Thread.detachNewThread { continuation.resume(returning: body()) }
+        }
+    }
+}
+
+/// Sends one byte of a request head every 200 ms from its own thread until stopped or refused.
+private final class Trickle: @unchecked Sendable {
+    private let lock = NSLock()
+    private var stopped = false
+
+    init(fd: Int32) {
+        Thread.detachNewThread { [self] in
+            let head = Array("GET / HTTP/1.1\r\nHost: x\r\nX-Pad: \(String(repeating: "a", count: 400))\r\n\r\n".utf8)
+            for byte in head {
+                if isStopped { return }
+                var one = byte
+                if send(fd, &one, 1, 0) != 1 { return }
+                Thread.sleep(forTimeInterval: 0.2)
+            }
+        }
+    }
+
+    private var isStopped: Bool {
+        lock.lock(); defer { lock.unlock() }
+        return stopped
+    }
+
+    func stop() {
+        lock.lock(); stopped = true; lock.unlock()
+    }
+}
+
+/// Captures `EngineLog` lines for one test; the handler is global, so it is restored on every path.
+private final class LineTap: @unchecked Sendable {
+    private let lock = NSLock()
+    private var lines: [String] = []
+    private let previous: ((String) -> Void)?
+
+    init() {
+        previous = EngineLog.handler
+        EngineLog.handler = { [self] line in
+            lock.lock()
+            lines.append(line)
+            lock.unlock()
+        }
+    }
+
+    func restore() { EngineLog.handler = previous }
+
+    func matching(_ needle: String) -> [String] {
+        lock.lock()
+        defer { lock.unlock() }
+        return lines.filter { $0.contains(needle) }
+    }
+}
+
+private final class StubProvider: HLSSegmentProvider, @unchecked Sendable {
+    func initSegment() -> Data? { Data([0x00]) }
+    func mediaSegment(at index: Int) -> Data? { Data([0x00]) }
+    var segmentCount: Int { 1 }
+    func segmentDuration(at index: Int) -> Double { 4.0 }
+    var playlistType: HLSPlaylistType { .vod }
+}

From 42c930ab760ebce343fc3b34c3cc271b076b6fff Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 05:19:24 +0200
Subject: [PATCH 037/359] fix(demuxer): a lost source reports EIO on the
 streaming and seekable paths, and the streaming buffer gets a hard bound
 (audit DMX-6, DMX-7, DMX-10)

DMX-6: the length-less streaming reader returned EOF when its GET ended
in a transport error or stalled for 15 s; only the sequential origin got
EIO. The distinction now applies to every streaming source, keyed on the
delegate's completion error, a stall, or a body short of its advisory
Content-Length.

DMX-7: the streaming buffer's only bound was the advisory suspend(). A
transfer that keeps delivering past twice the high water is now ended,
and the read fails with EIO once the buffered bytes are drained, since
this path cannot re-request at an offset.

DMX-10: a seekable read whose chunk fetch failed short of a known size
returned EOF, so a probe on a flaky link reported a truncated duration
instead of failing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 Sources/AetherEngine/Demuxer/AVIOReader.swift | 101 +++++++++----
 .../LostSourceReadErrorTests.swift            | 140 ++++++++++++++++++
 2 files changed, 209 insertions(+), 32 deletions(-)
 create mode 100644 Tests/AetherEngineTests/LostSourceReadErrorTests.swift

diff --git a/Sources/AetherEngine/Demuxer/AVIOReader.swift b/Sources/AetherEngine/Demuxer/AVIOReader.swift
index 3b9604c49..8dd07023b 100644
--- a/Sources/AetherEngine/Demuxer/AVIOReader.swift
+++ b/Sources/AetherEngine/Demuxer/AVIOReader.swift
@@ -484,6 +484,11 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
     // Backpressure: suspend the streaming task above highWater, resume below lowWater.
     private static let streamHighWater = 64 * 1024 * 1024
     private static let streamLowWater = 32 * 1024 * 1024
+    /// Audit DMX-7: the suspend above is advisory (#220 measured 911 MB arriving after one), and
+    /// this path cannot re-request at an offset the way the persistent reader does, so a transport
+    /// that keeps delivering past twice the high water is ended and the read fails with EIO once
+    /// the buffered bytes are drained.
+    private static let streamHardCap = 2 * streamHighWater
 
     private let bufferLock = NSLock()
     private var currentBuffer = Data()
@@ -508,6 +513,10 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
     /// consumer treats EOF as "played to the end" and deliberately never retries it. Guarded by
     /// `streamLock`.
     private var streamExpectedBytes: Int64 = -1
+    /// Audit DMX-6: the streaming GET ended in a transport error, or was ended at
+    /// `streamHardCap`. Either way the bytes that did not arrive are lost, not absent, so the read
+    /// that runs out reports EIO instead of end-of-media. Guarded by `streamLock`.
+    private var streamFailed = false
     /// The status the streaming GET was answered with when it was anything but 200/206, 0 while
     /// none. A status is not media: the delegate hangs up at the header, and `open()` fails typed
     /// on it rather than handing FFmpeg an empty stream to misreport as invalid data. Written on
@@ -1665,14 +1674,21 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
 
                 if fetchSize <= 0 { break }
 
-                guard let data = fetchChunk(from: position, size: fetchSize), !data.isEmpty else {
+                let fetched = fetchChunk(from: position, size: fetchSize)
+                guard let data = fetched, !data.isEmpty else {
                     // An aborted fetch (supersede/close/deadline) must report a read
                     // error, not EOF (which would truncate the stream cleanly). issue #27.
                     if isClosed || readDeadlinePassedOrAborted {
                         if readDeadlinePassedOrAborted { readDeadlineFired = true }
                         return totalRead > 0 ? Int32(totalRead) : -1
                     }
-                    // nil = transport failure; empty = 2xx with no body (would loop forever otherwise).
+                    // Audit DMX-10: nil is a transport failure short of a known size, which is the
+                    // same loss #25 stopped reporting as EOF on the persistent path; a probe that
+                    // read it as end-of-file reported a truncated duration instead of failing.
+                    if fetched == nil, fileSize > 0 {
+                        return totalRead > 0 ? Int32(totalRead) : FFmpegErr.eio
+                    }
+                    // Empty = 2xx with no body (would loop forever otherwise).
                     break
                 }
 
@@ -1757,24 +1773,24 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
                 category: .demux)
             return FFmpegErr.eio
         }
-        if sequentialOnly {
-            streamLock.lock()
-            let ended = streamEnded
-            let received = streamBytesRead + Int64(streamBuffer.count)
-            let expected = streamExpectedBytes
-            streamLock.unlock()
-            // A sequential origin cannot be resumed at an offset, so a stalled-out wait or a
-            // body that ended short of its advisory length is a LOST source: report EIO so the
-            // pump exits on a read error the session can surface. EOF here would read as
-            // end-of-media, which the consumer deliberately never retries.
-            if !ended || (expected > 0 && received < expected) {
-                EngineLog.emit(
-                    "[AVIOReader] sequential stream \(ended ? "ended short" : "stalled out") at "
-                    + "\(received)\(expected > 0 ? "/\(expected)" : "") bytes; reporting EIO",
-                    category: .demux
-                )
-                return FFmpegErr.eio
-            }
+        streamLock.lock()
+        let ended = streamEnded
+        let failed = streamFailed
+        let received = streamBytesRead + Int64(streamBuffer.count)
+        let expected = streamExpectedBytes
+        streamLock.unlock()
+        // This path cannot be resumed at an offset, so a stalled-out wait, a transport error or a
+        // body that ended short of its advisory length is a LOST source: report EIO so the pump
+        // exits on a read error the session can surface. EOF here would read as end-of-media,
+        // which the consumer deliberately never retries. Audit DMX-6: this held for the
+        // sequential origin only, and a length-less source ended its film early on a Wi-Fi drop.
+        if !ended || failed || (expected > 0 && received < expected) {
+            EngineLog.emit(
+                "[AVIOReader] \(label) stream \(!ended ? "stalled out" : failed ? "failed" : "ended short") at "
+                + "\(received)\(expected > 0 ? "/\(expected)" : "") bytes; reporting EIO",
+                category: .demux
+            )
+            return FFmpegErr.eio
         }
         return FFmpegErr.eof
     }
@@ -3467,9 +3483,9 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
         let delegate = StreamingDelegate(
             extraHeaders: headers(for: request.url),
             onResponse: { [weak self] response in
-                // Advisory length for the sequential-origin EOF/EIO distinction; -1 (chunked /
-                // unknown) leaves the clean-end path as the only EOF source.
-                guard let self, self.sequentialOnly else { return }
+                // Advisory length for the EOF/EIO distinction; -1 (chunked / unknown) leaves the
+                // clean-end path as the only EOF source.
+                guard let self else { return }
                 let expected = response.expectedContentLength
                 guard expected > 0 else { return }
                 self.streamLock.lock()
@@ -3496,7 +3512,16 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
         ) { [weak self] data in
             guard let self, !self.isClosed else { return }
             self.streamLock.lock()
+            if self.streamFailed {
+                self.streamLock.unlock()
+                return
+            }
             self.streamBuffer.append(data)
+            var toCancel: URLSessionDataTask?
+            if self.streamBuffer.count > Self.streamHardCap {
+                self.streamFailed = true
+                toCancel = self.streamingTask
+            }
             // Backpressure: park the transfer once the retained buffer
             // exceeds the high water mark; readStreaming resumes it when
             // the consumer drains below the low water mark (and before
@@ -3508,14 +3533,26 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
                 toSuspend = self.streamingTask
             }
             self.streamLock.unlock()
-            toSuspend?.suspend()
+            if let toCancel {
+                EngineLog.emit(
+                    "[AVIOReader] \(self.label) streaming buffer passed \(Self.streamHardCap / 1024 / 1024)MB "
+                    + "with the transfer suspended; ending it (audit DMX-7)", category: .demux)
+                toCancel.cancel()
+            } else {
+                toSuspend?.suspend()
+            }
             self.addBytesFetched(data.count)
             self.streamDataReady.signal()
-        } onComplete: { [weak self] in
-            self?.streamLock.lock()
-            self?.streamEnded = true
-            self?.streamLock.unlock()
-            self?.streamDataReady.signal()
+        } onComplete: { [weak self] error in
+            guard let self else {
+                semaphore.signal()
+                return
+            }
+            self.streamLock.lock()
+            if error != nil, !self.isClosed { self.streamFailed = true }
+            self.streamEnded = true
+            self.streamLock.unlock()
+            self.streamDataReady.signal()
             semaphore.signal()
         }
 
@@ -4640,7 +4677,7 @@ private final class ChunkFetchDelegate: NSObject, URLSessionDataDelegate, @unche
 
 private final class StreamingDelegate: NSObject, URLSessionDataDelegate {
     let onData: @Sendable (Data) -> Void
-    let onComplete: @Sendable () -> Void
+    let onComplete: @Sendable (Error?) -> Void
     /// Response hook (advisory Content-Length capture on the sequential-origin path).
     let onResponse: (@Sendable (URLResponse) -> Void)?
     /// The origin answered with a status instead of media (anything but 200/206). Called at the
@@ -4658,7 +4695,7 @@ private final class StreamingDelegate: NSObject, URLSessionDataDelegate {
         onResponse: (@Sendable (URLResponse) -> Void)? = nil,
         onRefused: (@Sendable (Int, URL?) -> Void)? = nil,
         onData: @escaping @Sendable (Data) -> Void,
-        onComplete: @escaping @Sendable () -> Void
+        onComplete: @escaping @Sendable (Error?) -> Void
     ) {
         self.extraHeaders = extraHeaders
         self.onResponse = onResponse
@@ -4717,7 +4754,7 @@ private final class StreamingDelegate: NSObject, URLSessionDataDelegate {
             EngineLog.emit("[AVIOReader] Stream error: \(error.localizedDescription)", category: .demux)
         }
         #endif
-        onComplete()
+        onComplete(error)
     }
 }
 
diff --git a/Tests/AetherEngineTests/LostSourceReadErrorTests.swift b/Tests/AetherEngineTests/LostSourceReadErrorTests.swift
new file mode 100644
index 000000000..20c380bb3
--- /dev/null
+++ b/Tests/AetherEngineTests/LostSourceReadErrorTests.swift
@@ -0,0 +1,140 @@
+import Testing
+import Foundation
+@testable import AetherEngine
+
+/// A source that is lost mid-read reports a read error, never end-of-file: the consumer treats EOF
+/// as "played to the end" and never retries it (audit DMX-6, DMX-10).
+@Suite("Lost source reads report EIO")
+struct LostSourceReadErrorTests {
+
+    /// Answers every request with a length-less 200 and every GET with `bodyBytes` of a body that
+    /// never completes. The reader can resolve no size and runs the forward-only streaming path.
+    private final class LengthlessResettingOrigin: @unchecked Sendable {
+        let port: UInt16
+        private let listenFD: Int32
+        private let bodyBytes: Int
+        private let lock = NSLock()
+        private var stopped = false
+        private var isStopped: Bool {
+            lock.lock()
+            defer { lock.unlock() }
+            return stopped
+        }
+
+        init?(bodyBytes: Int) {
+            self.bodyBytes = bodyBytes
+            let fd = socket(AF_INET, SOCK_STREAM, 0)
+            guard fd >= 0 else { return nil }
+            var one: Int32 = 1
+            setsockopt(fd, SOL_SOCKET, SO_REUSEADDR, &one, socklen_t(MemoryLayout<Int32>.size))
+            var addr = sockaddr_in()
+            addr.sin_family = sa_family_t(AF_INET)
+            addr.sin_port = 0
+            addr.sin_addr.s_addr = inet_addr("127.0.0.1")
+            let bound = withUnsafePointer(to: &addr) {
+                $0.withMemoryRebound(to: sockaddr.self, capacity: 1) {
+                    bind(fd, $0, socklen_t(MemoryLayout<sockaddr_in>.size))
+                }
+            }
+            guard bound == 0, listen(fd, 16) == 0 else { Darwin.close(fd); return nil }
+            var name = sockaddr_in()
+            var len = socklen_t(MemoryLayout<sockaddr_in>.size)
+            _ = withUnsafeMutablePointer(to: &name) {
+                $0.withMemoryRebound(to: sockaddr.self, capacity: 1) { getsockname(fd, $0, &len) }
+            }
+            listenFD = fd
+            port = UInt16(bigEndian: name.sin_port)
+            Thread.detachNewThread { [self] in acceptLoop() }
+        }
+
+        func stop() {
+            lock.lock()
+            stopped = true
+            lock.unlock()
+            shutdown(listenFD, SHUT_RDWR)
+            Darwin.close(listenFD)
+        }
+
+        private func acceptLoop() {
+            while true {
+                let fd = accept(listenFD, nil, nil)
+                guard fd >= 0 else { return }
+                var one: Int32 = 1
+                setsockopt(fd, SOL_SOCKET, SO_NOSIGPIPE, &one, socklen_t(MemoryLayout<Int32>.size))
+                Thread.detachNewThread { [self] in serve(fd) }
+            }
+        }
+
+        private func serve(_ fd: Int32) {
+            var buf = [UInt8](repeating: 0, count: 16 * 1024)
+            var request = Data()
+            while request.range(of: Data("\r\n\r\n".utf8)) == nil {
+                let n = recv(fd, &buf, buf.count, 0)
+                guard n > 0 else { Darwin.close(fd); return }
+                request.append(contentsOf: buf[0..<n])
+            }
+            let isHead = request.starts(with: Data("HEAD".utf8))
+            // Chunked with no Content-Length, so no probe can size the source. The body promises
+            // one chunk of twice `bodyBytes` and stops half way with a FIN: a truncated chunked
+            // body is a transport error, where a length-less FIN would be a clean end.
+            let header = Array(("HTTP/1.1 200 OK\r\nContent-Type: video/mp2t\r\n"
+                + "Transfer-Encoding: chunked\r\nConnection: close\r\n\r\n"
+                + (isHead ? "" : String(2 * bodyBytes, radix: 16) + "\r\n")).utf8)
+            _ = header.withUnsafeBytes { send(fd, $0.baseAddress, $0.count, 0) }
+            if !isHead {
+                let chunk = [UInt8](repeating: 0x47, count: 16 * 1024)
+                var sent = 0
+                while sent < bodyBytes {
+                    let n = chunk.withUnsafeBytes { send(fd, $0.baseAddress, min($0.count, bodyBytes - sent), 0) }
+                    guard n > 0 else { break }
+                    sent += n
+                }
+            }
+            // Half-close, as `ThrottledOriginServer.serveThenDrop` does: a full close can turn into
+            // an RST that discards bytes the reader has not been handed yet.
+            shutdown(fd, SHUT_WR)
+            while !isStopped { usleep(50_000) }
+            Darwin.close(fd)
+        }
+    }
+
+    private func drain(_ reader: AVIOReader) -> Int32 {
+        let buf = UnsafeMutablePointer<UInt8>.allocate(capacity: 64 * 1024)
+        defer { buf.deallocate() }
+        while true {
+            let n = reader.read(into: buf, size: 64 * 1024)
+            if n <= 0 { return n }
+        }
+    }
+
+    @Test("a length-less stream cut off mid-body reports EIO, not EOF", .timeLimit(.minutes(1)))
+    func cutOffLengthlessStreamIsAnError() throws {
+        let origin = try #require(LengthlessResettingOrigin(bodyBytes: 256 * 1024))
+        defer { origin.stop() }
+        let reader = AVIOReader(url: URL(string: "http://127.0.0.1:\(origin.port)/live.ts")!,
+                                prefetchEnabled: false)
+        defer { reader.markClosed(); reader.close() }
+        try reader.open()
+        #expect(drain(reader) == FFmpegErr.eio)
+    }
+
+    @Test("a seekable read whose fetch fails reports EIO, not EOF", .timeLimit(.minutes(1)))
+    func failedSeekableFetchIsAnError() throws {
+        let target: Int64 = 8 * 1024 * 1024
+        let respond: @Sendable (Int, Int64, String) -> ThrottledOriginServer.Directive = { _, offset, _ in
+            offset == target ? .status(500) : .serve206
+        }
+        let origin = ThrottledOriginServer(totalSize: 32 * 1024 * 1024, throttleUs: 0, respond: respond)
+        let server = try #require(origin)
+        defer { server.stop() }
+        let reader = AVIOReader(url: URL(string: "http://127.0.0.1:\(server.port)/movie.bin")!,
+                                chunkSize: 256 * 1024, prefetchEnabled: false)
+        defer { reader.markClosed(); reader.close() }
+        try reader.open()
+
+        #expect(reader.seek(offset: target, whence: SEEK_SET) == target)
+        let buf = UnsafeMutablePointer<UInt8>.allocate(capacity: 4096)
+        defer { buf.deallocate() }
+        #expect(reader.read(into: buf, size: 4096) == FFmpegErr.eio)
+    }
+}

From beb3d6f80bdae5b7653421f7f56d3c3b9384b5d7 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 05:20:16 +0200
Subject: [PATCH 038/359] fix(hls): keep credential headers on the host's
 origin when a playlist names another host (audit NET-7)

The host's headers (Authorization, X-Emby-Token, Cookie) were set on every
fetch the relay, the live and VOD ingest readers and the carriage probe made,
whatever host and scheme the playlist named, including http:// URIs in an
https:// playlist. The relay also admitted every origin a playlist revealed,
so its allow list gave no protection against the playlist itself.

Playlist-named URIs now get the rule RedirectHeaderPolicy already applies to
redirects (#126): credentials only to the origin the host gave them for, same
host and port or an http to https upgrade, never a downgrade. Everything else
(Referer, User-Agent, custom headers) still goes everywhere, so #119 / #168
origins keep working. The anchor is the host's playlist URL; a live
companion reader inherits its parent's, and the relay judges against the
URLs the host admitted rather than the origins playlists revealed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 README.md                                     |   2 +-
 .../Demuxer/RedirectHeaderPolicy.swift        |  11 +-
 .../IO/HLSIngest/HLSCarriageProbe.swift       |  20 ++-
 .../IO/HLSIngest/HLSLiveIngestReader.swift    |  20 ++-
 .../IO/HLSIngest/HLSVODIngestReader.swift     |   8 +-
 .../Native/NativeAVPlayerHost.swift           |   2 +-
 .../AetherEngine/Network/HLSOriginRelay.swift |  19 ++-
 ...96CarriageProbeConnectionBudgetTests.swift |   2 +
 .../PlaylistNamedHostCredentialTests.swift    | 154 ++++++++++++++++++
 docs/api.md                                   |   2 +-
 10 files changed, 222 insertions(+), 18 deletions(-)
 create mode 100644 Tests/AetherEngineTests/PlaylistNamedHostCredentialTests.swift

diff --git a/README.md b/README.md
index 7d87c0705..b4533f039 100644
--- a/README.md
+++ b/README.md
@@ -491,7 +491,7 @@ For an upstream AVPlayer can play natively (a standard remote `master.m3u8`, e.g
 
 A live channel whose master advertises HEVC (or Dolby Vision / AV1) while delivering MPEG-TS segments is carriage AVFoundation builds no video track for, so the bypass would play it as audio over black. The engine recognizes that signature and reroutes the session onto the live ingest above (#168). The recognition runs alongside the mount: the playlist and the head of one segment are read while AVPlayer starts, so the reroute does not wait out a grace window, and a media playlist URL with no master to judge is covered too (#293). Only a codec the HLS Authoring Spec sanctions in fMP4 alone reaches that read, so an H.264 channel spends no extra request on it. `LoadOptions.nativeRemoteHLSIngestFallback = false` turns the whole recovery off.
 
-A LIVE remote `m3u8` handed to the default (loopback) path routes the other way, onto the live ingest above (#363). The raw live path reads bytes, not playlists, so it used to reject an `.m3u8` with a typed `hlsPlaylistOnRawLivePath` error naming the reader the host should have built. It builds that reader itself now, with `LoadOptions.httpHeaders` on the playlist, on every segment and on every AES key, which is what a tokenized IPTV origin enforces per request. A custom `IOReader` carrying the same misroute still gets the typed error: it has no playlist URL to ingest from.
+A LIVE remote `m3u8` handed to the default (loopback) path routes the other way, onto the live ingest above (#363). The raw live path reads bytes, not playlists, so it used to reject an `.m3u8` with a typed `hlsPlaylistOnRawLivePath` error naming the reader the host should have built. It builds that reader itself now, with `LoadOptions.httpHeaders` on the playlist, on every segment and on every AES key, which is what a tokenized IPTV origin enforces per request. Credential headers stay with the playlist's own origin: a segment or key on another host, or on http:// behind an https:// playlist, gets the rest of the headers but not the token. A custom `IOReader` carrying the same misroute still gets the typed error: it has no playlist URL to ingest from.
 
 If a live `nativeRemoteHLS` bypass is refused by the origin outright (HTTP 401 or 403, which reach the item as `NSURLError` -1013 / -1102), the engine hands that session to the same ingest instead of failing the load (#363). The ingest fetcher is a different client at that origin: it carries the configured headers on every request, caps itself at four concurrent fetches, and sends no AVFoundation user agent, so a UA filter or a per-token connection cap that turned AVPlayer away can still serve it. The refusal is not remembered for the next load the way a carriage verdict is; a token expires, a cap frees up. `LoadOptions.nativeRemoteHLSIngestFallback = false` turns this off along with the carriage recovery.
 
diff --git a/Sources/AetherEngine/Demuxer/RedirectHeaderPolicy.swift b/Sources/AetherEngine/Demuxer/RedirectHeaderPolicy.swift
index 1992e53ea..9a68ee751 100644
--- a/Sources/AetherEngine/Demuxer/RedirectHeaderPolicy.swift
+++ b/Sources/AetherEngine/Demuxer/RedirectHeaderPolicy.swift
@@ -28,6 +28,15 @@ enum RedirectHeaderPolicy {
         return extraHeaders.filter { !credentialHeaders.contains($0.key.lowercased()) }
     }
 
+    /// Audit NET-7: the headers a host handed over for `anchor` as they may be sent to `target`, a URI
+    /// some playlist named. A playlist can name any host and scheme, so it gets the rule a redirect
+    /// gets: credentials only to the same origin with no TLS downgrade, everything else as given.
+    static func scoped(_ headers: [String: String], grantedFor anchor: URL?, sentTo target: URL?)
+        -> [String: String]
+    {
+        headersToReplay(extraHeaders: headers, originalURL: anchor, redirectURL: target)
+    }
+
     /// Builds the request actually handed back to URLSession on redirect: re-applies the
     /// original Range (URLSession drops custom headers on cross-host redirect, and
     /// Range-dependent proxies 400 without it), replays the policy-filtered extra
@@ -59,7 +68,7 @@ enum RedirectHeaderPolicy {
     /// Same host and no TLS downgrade. Ports may differ only across an http -> https
     /// upgrade (Emby-style 8096 -> 8920); within the same scheme a port change is a
     /// different origin.
-    private static func credentialsAllowed(from original: URL?, to redirect: URL?) -> Bool {
+    static func credentialsAllowed(from original: URL?, to redirect: URL?) -> Bool {
         guard let original, let redirect,
               let fromHost = original.host?.lowercased(),
               let toHost = redirect.host?.lowercased(),
diff --git a/Sources/AetherEngine/IO/HLSIngest/HLSCarriageProbe.swift b/Sources/AetherEngine/IO/HLSIngest/HLSCarriageProbe.swift
index 3a4be1b6e..5b83af9e6 100644
--- a/Sources/AetherEngine/IO/HLSIngest/HLSCarriageProbe.swift
+++ b/Sources/AetherEngine/IO/HLSIngest/HLSCarriageProbe.swift
@@ -71,14 +71,20 @@ enum HLSCarriageProbe {
     /// AE#296: the segment stage, run apart from the playlist stage so the one media byte the probe ever
     /// spends is spent where losing it costs the verdict rather than the mount. Never throws: an origin
     /// that refuses this read leaves the source on the route it is already taking.
+    ///
+    /// `credentialOrigin` is the playlist the host gave `httpHeaders` for; the segment is a URI that
+    /// playlist named, so credentials only follow it to the same origin (audit NET-7).
     static func classifyDeferredSegmentHead(
         url: URL,
         httpHeaders: [String: String],
+        credentialOrigin: URL,
         session: URLSession? = nil
     ) async -> MPEGTransportStreamCodecProbe.Verdict {
         do {
             return try await classifySegmentHead(
-                url: url, httpHeaders: httpHeaders, session: session ?? sharedSession
+                url: url,
+                httpHeaders: RedirectHeaderPolicy.scoped(httpHeaders, grantedFor: credentialOrigin, sentTo: url),
+                session: session ?? sharedSession
             )
         } catch {
             EngineLog.emit("[HLSCarriageProbe] carriage probe inconclusive: \(error)", category: .engine)
@@ -104,7 +110,7 @@ enum HLSCarriageProbe {
             return verdict
         case .needsSegmentHead(let segmentURL):
             return await classifyDeferredSegmentHead(
-                url: segmentURL, httpHeaders: httpHeaders, session: session
+                url: segmentURL, httpHeaders: httpHeaders, credentialOrigin: playlistURL, session: session
             )
         }
     }
@@ -152,7 +158,8 @@ enum HLSCarriageProbe {
         advertisesFragmentedMP4OnlyVideo: Bool,
         session: URLSession
     ) async throws -> PlaylistEvidence {
-        let (root, rootURL) = try await fetchPlaylist(playlistURL, httpHeaders: httpHeaders, session: session)
+        let (root, rootURL) = try await fetchPlaylist(
+            playlistURL, httpHeaders: httpHeaders, credentialOrigin: playlistURL, session: session)
         let media: HLSMediaPlaylist
         let mediaURL: URL
         switch root {
@@ -165,7 +172,7 @@ enum HLSCarriageProbe {
                 return .settled(.inconclusive)
             }
             let (selected, selectedURL) = try await fetchPlaylist(
-                variantURL, httpHeaders: httpHeaders, session: session
+                variantURL, httpHeaders: httpHeaders, credentialOrigin: playlistURL, session: session
             )
             guard case .media(let value) = selected else { return .settled(.inconclusive) }
             media = value
@@ -193,9 +200,12 @@ enum HLSCarriageProbe {
     private static func fetchPlaylist(
         _ url: URL,
         httpHeaders: [String: String],
+        credentialOrigin: URL,
         session: URLSession
     ) async throws -> (HLSPlaylist, URL) {
-        let (data, response) = try await session.data(for: makeRequest(url, httpHeaders: httpHeaders))
+        let request = makeRequest(
+            url, httpHeaders: RedirectHeaderPolicy.scoped(httpHeaders, grantedFor: credentialOrigin, sentTo: url))
+        let (data, response) = try await session.data(for: request)
         let status = (response as? HTTPURLResponse)?.statusCode ?? -1
         guard (200..<300).contains(status) else {
             throw HLSIngestError.playlistUnreachable(status: status)
diff --git a/Sources/AetherEngine/IO/HLSIngest/HLSLiveIngestReader.swift b/Sources/AetherEngine/IO/HLSIngest/HLSLiveIngestReader.swift
index 4f0a216f1..cdec29d8c 100644
--- a/Sources/AetherEngine/IO/HLSIngest/HLSLiveIngestReader.swift
+++ b/Sources/AetherEngine/IO/HLSIngest/HLSLiveIngestReader.swift
@@ -18,6 +18,9 @@ public final class HLSLiveIngestReader: IOReader, LiveIngestSourceInfo, @uncheck
 
     private let playlistURL: URL
     private let httpHeaders: [String: String]
+    /// The URL the host gave `httpHeaders` for. A companion inherits its parent's, since its own
+    /// playlist URL is one the master named (audit NET-7).
+    private let credentialOrigin: URL
     private let role: Role
     private let fifo = ByteFIFO(capacity: 16 * 1024 * 1024)
     private let session: URLSession
@@ -134,7 +137,8 @@ public final class HLSLiveIngestReader: IOReader, LiveIngestSourceInfo, @uncheck
 
     /// `httpHeaders` ride on every fetch (playlist, segment, AES key) and inherit to the companion audio
     /// reader, so header-enforcing IPTV origins (Referer / User-Agent / Authorization, #119) accept the
-    /// ingest the same way they accept the AVPlayer bypass (AetherEngine#168).
+    /// ingest the same way they accept the AVPlayer bypass (AetherEngine#168). Credential headers go
+    /// only to `playlistURL`'s origin with no TLS downgrade (audit NET-7).
     public convenience init(playlistURL: URL, httpHeaders: [String: String]) {
         self.init(playlistURL: playlistURL, httpHeaders: httpHeaders, role: .mainVideo)
     }
@@ -148,9 +152,11 @@ public final class HLSLiveIngestReader: IOReader, LiveIngestSourceInfo, @uncheck
         return HLSLiveIngestReader(playlistURL: playlistURL, httpHeaders: httpHeaders, role: .mainVideo)
     }
 
-    init(playlistURL: URL, httpHeaders: [String: String] = [:], role: Role) {
+    init(playlistURL: URL, httpHeaders: [String: String] = [:], role: Role,
+         credentialOrigin: URL? = nil) {
         self.playlistURL = playlistURL
         self.httpHeaders = httpHeaders
+        self.credentialOrigin = credentialOrigin ?? playlistURL
         self.role = role
         let config = URLSessionConfiguration.ephemeral
         config.timeoutIntervalForRequest = 10
@@ -479,7 +485,9 @@ public final class HLSLiveIngestReader: IOReader, LiveIngestSourceInfo, @uncheck
                     + "starting companion reader on \(audioURL.lastPathComponent)",
                     category: .engine
                 )
-                installCompanion(HLSLiveIngestReader(playlistURL: audioURL, httpHeaders: httpHeaders, role: .companionAudio))
+                installCompanion(HLSLiveIngestReader(
+                    playlistURL: audioURL, httpHeaders: httpHeaders, role: .companionAudio,
+                    credentialOrigin: credentialOrigin))
             }
             // AE#359: the variant's SUBTITLES group, resolved to absolute playlist URLs and published as
             // metadata. Nothing is fetched here; the host decides whether a subtitle track is ever wanted.
@@ -545,10 +553,12 @@ public final class HLSLiveIngestReader: IOReader, LiveIngestSourceInfo, @uncheck
         try await Task.sleep(nanoseconds: UInt64(delay * 1_000_000_000))
     }
 
-    /// Applies the configured origin headers to every ingest fetch. Internal for the header-contract tests.
+    /// Applies the configured origin headers to every ingest fetch, credentials only where the host's
+    /// origin is (audit NET-7). Internal for the header-contract tests.
     func makeRequest(_ url: URL) -> URLRequest {
         var request = URLRequest(url: url)
-        for (field, value) in httpHeaders {
+        for (field, value) in RedirectHeaderPolicy.scoped(
+            httpHeaders, grantedFor: credentialOrigin, sentTo: url) {
             request.setValue(value, forHTTPHeaderField: field)
         }
         return request
diff --git a/Sources/AetherEngine/IO/HLSIngest/HLSVODIngestReader.swift b/Sources/AetherEngine/IO/HLSIngest/HLSVODIngestReader.swift
index aa07b9b64..7023d2854 100644
--- a/Sources/AetherEngine/IO/HLSIngest/HLSVODIngestReader.swift
+++ b/Sources/AetherEngine/IO/HLSIngest/HLSVODIngestReader.swift
@@ -499,9 +499,11 @@ final class HLSVODIngestReader: TimeSeekableIOReader, @unchecked Sendable {
         )
     }
 
-    private func makeRequest(_ url: URL) -> URLRequest {
+    /// Credentials only where the host's playlist is (audit NET-7).
+    func makeRequest(_ url: URL) -> URLRequest {
         var request = URLRequest(url: url)
-        for (field, value) in httpHeaders {
+        for (field, value) in RedirectHeaderPolicy.scoped(
+            httpHeaders, grantedFor: playlistURL, sentTo: url) {
             request.setValue(value, forHTTPHeaderField: field)
         }
         return request
@@ -534,7 +536,7 @@ final class HLSVODIngestReader: TimeSeekableIOReader, @unchecked Sendable {
     private func probeCarriage(_ url: URL) async throws -> MPEGTransportStreamCodecProbe.Verdict {
         try await HLSCarriageProbe.classifySegmentHead(
             url: url,
-            httpHeaders: httpHeaders,
+            httpHeaders: RedirectHeaderPolicy.scoped(httpHeaders, grantedFor: playlistURL, sentTo: url),
             session: session
         )
     }
diff --git a/Sources/AetherEngine/Native/NativeAVPlayerHost.swift b/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
index 616889af3..1d9599409 100644
--- a/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
+++ b/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
@@ -2216,7 +2216,7 @@ final class NativeAVPlayerHost {
                     break
                 }
                 let verdict = await HLSCarriageProbe.classifyDeferredSegmentHead(
-                    url: segmentURL, httpHeaders: httpHeaders)
+                    url: segmentURL, httpHeaders: httpHeaders, credentialOrigin: url)
                 guard !Task.isCancelled, self.sessionID == sid else { return }
                 self.publishCarriageProbeVerdict(verdict, sid: sid, from: "segment PMT")
             }
diff --git a/Sources/AetherEngine/Network/HLSOriginRelay.swift b/Sources/AetherEngine/Network/HLSOriginRelay.swift
index ce4e31372..6c1693fde 100644
--- a/Sources/AetherEngine/Network/HLSOriginRelay.swift
+++ b/Sources/AetherEngine/Network/HLSOriginRelay.swift
@@ -53,6 +53,11 @@ final class HLSOriginRelay: @unchecked Sendable {
     /// now points at the local server.
     private var upstreamHeaders: [String: String] = [:]
 
+    /// The URLs the host itself pointed the relay at. Credential headers follow a fetch only to
+    /// one of these origins with no TLS downgrade; an origin a playlist revealed gets the rest of
+    /// the headers but not the token (audit NET-7).
+    private var credentialOrigins: [URL] = []
+
     /// The NSURLError code of the last upstream handshake this relay lost to system trust, if any.
     ///
     /// 6.69.0 classifies a refused certificate off the failed item's `NSUnderlyingErrorKey` chain,
@@ -142,6 +147,7 @@ final class HLSOriginRelay: @unchecked Sendable {
         stateLock.lock()
         allowedOrigins.insert(key)
         if !httpHeaders.isEmpty { upstreamHeaders = httpHeaders }
+        if !credentialOrigins.contains(origin) { credentialOrigins.append(origin) }
         stateLock.unlock()
         return key
     }
@@ -278,7 +284,7 @@ final class HLSOriginRelay: @unchecked Sendable {
 
         stateLock.lock()
         let permitted = allowedOrigins.contains(key)
-        let headers = upstreamHeaders
+        let headers = Self.headers(upstreamHeaders, for: origin, grantedFor: credentialOrigins)
         stateLock.unlock()
         guard permitted else {
             EngineLog.emit(
@@ -321,6 +327,17 @@ final class HLSOriginRelay: @unchecked Sendable {
         }
     }
 
+    /// Everything the host sent, with the credentials only when `target` is one of the host's own
+    /// origins (same host, same port, no downgrade).
+    static func headers(_ headers: [String: String], for target: URL, grantedFor anchors: [URL])
+        -> [String: String]
+    {
+        if anchors.contains(where: { RedirectHeaderPolicy.credentialsAllowed(from: $0, to: target) }) {
+            return headers
+        }
+        return RedirectHeaderPolicy.scoped(headers, grantedFor: nil, sentTo: target)
+    }
+
     private static func looksLikePlaylist(url: URL, contentType: String?) -> Bool {
         if let type = contentType?.lowercased(), type.contains("mpegurl") || type.contains("m3u") {
             return true
diff --git a/Tests/AetherEngineTests/Issue296CarriageProbeConnectionBudgetTests.swift b/Tests/AetherEngineTests/Issue296CarriageProbeConnectionBudgetTests.swift
index e5ebf7276..b60d544f7 100644
--- a/Tests/AetherEngineTests/Issue296CarriageProbeConnectionBudgetTests.swift
+++ b/Tests/AetherEngineTests/Issue296CarriageProbeConnectionBudgetTests.swift
@@ -266,6 +266,7 @@ final class Issue296CarriageProbeConnectionBudgetTests: XCTestCase {
         let verdict = await HLSCarriageProbe.classifyDeferredSegmentHead(
             url: try XCTUnwrap(URL(string: "https://cap.test/direct0.ts")),
             httpHeaders: ["X-Fixture": "allowed"],
+            credentialOrigin: try XCTUnwrap(URL(string: "https://cap.test/live.m3u8")),
             session: session
         )
 
@@ -284,6 +285,7 @@ final class Issue296CarriageProbeConnectionBudgetTests: XCTestCase {
         let verdict = await HLSCarriageProbe.classifyDeferredSegmentHead(
             url: try XCTUnwrap(URL(string: "https://cap.test/gone.ts")),
             httpHeaders: [:],
+            credentialOrigin: try XCTUnwrap(URL(string: "https://cap.test/live.m3u8")),
             session: session
         )
 
diff --git a/Tests/AetherEngineTests/PlaylistNamedHostCredentialTests.swift b/Tests/AetherEngineTests/PlaylistNamedHostCredentialTests.swift
new file mode 100644
index 000000000..9950e7c63
--- /dev/null
+++ b/Tests/AetherEngineTests/PlaylistNamedHostCredentialTests.swift
@@ -0,0 +1,154 @@
+import Foundation
+import Testing
+@testable import AetherEngine
+
+/// A playlist can name any host and any scheme for a variant, a rendition, a segment or a key. The
+/// host's credential headers were set on every one of those fetches, including an http:// URI inside
+/// an https:// playlist. They now follow the redirect rule (audit NET-7): the token only to the origin
+/// the host gave it for, with no downgrade, and every other header wherever the playlist points.
+@Suite("Credential headers stay with the host's origin", .serialized)
+struct PlaylistNamedHostCredentialTests {
+
+    private let headers = [
+        "Authorization": "MediaBrowser Token=\"t0k3n\"",
+        "X-Emby-Token": "t0k3n",
+        "Cookie": "connect.sid=s1",
+        "Referer": "https://portal.example/",
+        "User-Agent": "UA/1",
+    ]
+    private let credentialNames = ["Authorization", "X-Emby-Token", "Cookie"]
+    private let origin = URL(string: "https://media.example/live/master.m3u8")!
+
+    @Test("The live ingest keeps the token on its own origin and drops it elsewhere", arguments: [
+        ("https://media.example/live/seg1.ts", true),
+        ("https://media.example:443/keys/k1", true),
+        ("https://cdn.other/seg1.ts", false),
+        ("http://media.example/live/seg1.ts", false),
+        ("https://media.example:8443/seg1.ts", false),
+    ])
+    func liveIngest(target: String, keepsCredentials: Bool) throws {
+        let reader = HLSLiveIngestReader(playlistURL: origin, httpHeaders: headers)
+        let request = reader.makeRequest(try #require(URL(string: target)))
+        expect(request, keepsCredentials: keepsCredentials)
+    }
+
+    @Test("A companion reader judges by its parent's origin, not by the rendition URL it was handed")
+    func companionInheritsTheHostOrigin() throws {
+        let rendition = try #require(URL(string: "https://cdn.other/audio/index.m3u8"))
+        let companion = HLSLiveIngestReader(
+            playlistURL: rendition, httpHeaders: headers, role: .companionAudio, credentialOrigin: origin)
+        expect(companion.makeRequest(try #require(URL(string: "https://cdn.other/audio/a1.aac"))),
+               keepsCredentials: false)
+        expect(companion.makeRequest(try #require(URL(string: "https://media.example/audio/a1.aac"))),
+               keepsCredentials: true)
+    }
+
+    @Test("The VOD ingest applies the same rule")
+    func vodIngest() throws {
+        let reader = HLSVODIngestReader(playlistURL: origin, httpHeaders: headers)
+        defer { reader.close() }
+        expect(reader.makeRequest(try #require(URL(string: "https://media.example/v/seg0.ts"))),
+               keepsCredentials: true)
+        expect(reader.makeRequest(try #require(URL(string: "http://media.example/v/seg0.ts"))),
+               keepsCredentials: false)
+    }
+
+    @Test("The relay sends credentials to the host's origins only, not to one a playlist revealed")
+    func relayHeaders() throws {
+        let anchors = [origin]
+        let own = HLSOriginRelay.headers(
+            headers, for: try #require(URL(string: "https://media.example/hls/seg.ts")), grantedFor: anchors)
+        #expect(own == headers)
+        let discovered = HLSOriginRelay.headers(
+            headers, for: try #require(URL(string: "http://cdn.other/seg.ts")), grantedFor: anchors)
+        for name in credentialNames { #expect(discovered[name] == nil, "\(name) reached a discovered origin") }
+        #expect(discovered["Referer"] == "https://portal.example/")
+        #expect(discovered["User-Agent"] == "UA/1")
+    }
+
+    @Test("The carriage probe does not carry the token to a variant on another host")
+    func carriageProbeVariant() async throws {
+        CredentialCaptureProtocol.reset()
+        let variant = "http://cdn.other/v/index.m3u8"
+        CredentialCaptureProtocol.bodies[origin.absoluteString] = Data("""
+            #EXTM3U
+            #EXT-X-STREAM-INF:BANDWIDTH=1000000
+            \(variant)
+            """.utf8)
+        CredentialCaptureProtocol.bodies[variant] = Data("""
+            #EXTM3U
+            #EXT-X-TARGETDURATION:6
+            #EXT-X-MAP:URI="init.mp4"
+            #EXTINF:6.0,
+            seg0.m4s
+            """.utf8)
+        let configuration = URLSessionConfiguration.ephemeral
+        configuration.protocolClasses = [CredentialCaptureProtocol.self]
+        let session = URLSession(configuration: configuration)
+        defer { session.invalidateAndCancel() }
+
+        let evidence = await HLSCarriageProbe.classifyFromPlaylists(
+            playlistURL: origin, httpHeaders: headers, advertisesFragmentedMP4OnlyVideo: false,
+            session: session)
+        #expect(evidence == .settled(.otherCarriage))
+
+        let master = try #require(CredentialCaptureProtocol.seen[origin.absoluteString])
+        let onVariant = try #require(CredentialCaptureProtocol.seen[variant])
+        #expect(master["X-Emby-Token"] == "t0k3n")
+        for name in credentialNames { #expect(onVariant[name] == nil, "\(name) reached \(variant)") }
+        #expect(onVariant["Referer"] == "https://portal.example/")
+    }
+
+    private func expect(_ request: URLRequest, keepsCredentials: Bool,
+                        sourceLocation: SourceLocation = #_sourceLocation) {
+        for name in credentialNames {
+            let value = request.value(forHTTPHeaderField: name)
+            #expect((value != nil) == keepsCredentials, "\(name) on \(request.url!)",
+                    sourceLocation: sourceLocation)
+        }
+        #expect(request.value(forHTTPHeaderField: "Referer") == "https://portal.example/",
+                sourceLocation: sourceLocation)
+        #expect(request.value(forHTTPHeaderField: "User-Agent") == "UA/1", sourceLocation: sourceLocation)
+    }
+}
+
+/// Answers from canned bodies and records the headers each URL was asked with. Its own class rather
+/// than the #119 suite's, whose statics a parallel suite would reset under this one.
+private final class CredentialCaptureProtocol: URLProtocol, @unchecked Sendable {
+    private static let lock = NSLock()
+    nonisolated(unsafe) private static var _bodies: [String: Data] = [:]
+    nonisolated(unsafe) private static var _seen: [String: [String: String]] = [:]
+
+    static var bodies: [String: Data] {
+        get { lock.withLock { _bodies } }
+        set { lock.withLock { _bodies = newValue } }
+    }
+
+    static var seen: [String: [String: String]] { lock.withLock { _seen } }
+
+    static func reset() {
+        lock.withLock { _bodies = [:]; _seen = [:] }
+    }
+
+    override class func canInit(with request: URLRequest) -> Bool { true }
+    override class func canonicalRequest(for request: URLRequest) -> URLRequest { request }
+    override func stopLoading() {}
+
+    override func startLoading() {
+        guard let url = request.url else {
+            client?.urlProtocol(self, didFailWithError: URLError(.badURL))
+            return
+        }
+        let fields = request.allHTTPHeaderFields ?? [:]
+        Self.lock.withLock { Self._seen[url.absoluteString] = fields }
+        guard let data = Self.bodies[url.absoluteString] else {
+            client?.urlProtocol(self, didFailWithError: URLError(.fileDoesNotExist))
+            return
+        }
+        let response = HTTPURLResponse(url: url, statusCode: 200, httpVersion: "HTTP/1.1",
+                                       headerFields: ["Content-Length": String(data.count)])!
+        client?.urlProtocol(self, didReceive: response, cacheStoragePolicy: .notAllowed)
+        client?.urlProtocol(self, didLoad: data)
+        client?.urlProtocolDidFinishLoading(self)
+    }
+}
diff --git a/docs/api.md b/docs/api.md
index c12e71dfd..76d815ab4 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -640,7 +640,7 @@ suppressing `AVPlayerItemLegibleOutput` to keep the measurement running.
 | `liveResumeClamped`, `LiveResumeClamp` | A resume that found the playhead outside the window and moved it; see above. |
 | `liveScrubThumbnail(atSessionSeconds:maxWidth:)` | Still on the live session axis, decoded from what the session already holds. A native session reads its DVR segment cache; a software session reads its DVR packet ring (#544), so a tuner channel the box decodes in software has a scrub preview too. |
 | `$playlistShiftSeconds` | Seconds the producer subtracted from source PTS. Published values already fold it back; exposed for hosts pairing their own samples against AVPlayer's raw clock. |
-| `HLSLiveIngestReader(playlistURL:)`, `HLSLiveIngestReader(playlistURL:httpHeaders:)` | The ready-made `IOReader` for ingesting an upstream HLS playlist directly, with AES-128 clear-key and SSAI handling. The headers ride the playlist, every segment and every AES key, which is what a tokenized IPTV origin enforces per request. Unsupported shapes surface a typed `HLSIngestError`. |
+| `HLSLiveIngestReader(playlistURL:)`, `HLSLiveIngestReader(playlistURL:httpHeaders:)` | The ready-made `IOReader` for ingesting an upstream HLS playlist directly, with AES-128 clear-key and SSAI handling. The headers ride the playlist, every segment and every AES key, which is what a tokenized IPTV origin enforces per request. Credential headers (`Authorization`, `Cookie`, `X-Emby-Token` and the like) go only to the playlist's own origin with no https to http downgrade; a URI the playlist points at another host gets the other headers without them, the rule a redirect already follows. Unsupported shapes surface a typed `HLSIngestError`. |
 
 ### Where a live start's seconds go
 

From 71c3b8d85292a845039b641ea780815d61eea950 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 05:22:19 +0200
Subject: [PATCH 039/359] fix(demuxer): the held connection applies the
 redirect header policy per hop and writes the request as the URL spells it
 (audit DMX-3, DMX-4)

DMX-3: HeldSourceConnection followed Location to any host or scheme and
wrote the source's full header set, credentials included, on every hop.
Each hop now gets `RedirectHeaderPolicy.headersToReplay`, the #126 rule
every URLSession path already applies, and the hop is reported to
`OriginRequestBudget.noteRedirect`.

DMX-4: the request line was built from the percent-decoded `URL.path`,
so `%20`/`%3F`/`%2F` changed the resource, a trailing slash was lost and
an encoded CRLF in a redirect target became a raw line break. The path
and query now go out percent-encoded, a field carrying a line break is
refused, and an IPv6 literal is bracketed in Host.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 .../Demuxer/HeldSourceConnection.swift        | 35 ++++++++--
 .../Issue377HeldConnectionTests.swift         | 69 ++++++++++++++++++-
 2 files changed, 94 insertions(+), 10 deletions(-)

diff --git a/Sources/AetherEngine/Demuxer/HeldSourceConnection.swift b/Sources/AetherEngine/Demuxer/HeldSourceConnection.swift
index b24fbf48c..e59a0e5c7 100644
--- a/Sources/AetherEngine/Demuxer/HeldSourceConnection.swift
+++ b/Sources/AetherEngine/Demuxer/HeldSourceConnection.swift
@@ -72,9 +72,11 @@ final class HeldSourceConnection: @unchecked Sendable {
         case malformedResponse(String)
         case tooManyRedirects
         case unsupportedURL(URL)
+        case invalidHeaderField(String)
 
         var errorDescription: String? {
             switch self {
+            case .invalidHeaderField(let name): return "a line break in the request field \(name)"
             case .malformedResponse(let detail): return "malformed HTTP response: \(detail)"
             case .tooManyRedirects: return "too many redirects"
             case .unsupportedURL(let url): return "unsupported URL for a held connection: \(url)"
@@ -178,17 +180,24 @@ final class HeldSourceConnection: @unchecked Sendable {
     }
 
     private func openAndPump() throws {
+        let source = respondedBy
         var target = respondedBy
         var hops = 0
         while true {
             if isCancelled { return }
-            let head = try open(target)
+            // Audit DMX-3: the headers were built for the source, so every hop gets the #126
+            // policy every URLSession path applies: credentials only to the same origin, and
+            // never down from https to http.
+            let headers = RedirectHeaderPolicy.headersToReplay(
+                extraHeaders: extraHeaders, originalURL: source, redirectURL: target)
+            let head = try open(target, headers: headers)
             if let location = Self.redirectLocation(head), hops < Self.maxRedirects {
                 guard let next = URL(string: location, relativeTo: target)?.absoluteURL else {
                     throw ConnectionError.malformedResponse("unresolvable Location: \(location)")
                 }
                 hops += 1
                 closeSocket()
+                OriginRequestBudget.shared.noteRedirect(from: source, to: next)
                 target = next
                 continue
             }
@@ -206,7 +215,7 @@ final class HeldSourceConnection: @unchecked Sendable {
     }
 
     /// Connect, write the request, and read until the head is complete.
-    private func open(_ target: URL) throws -> ResponseHead {
+    private func open(_ target: URL, headers: [String: String]) throws -> ResponseHead {
         guard let host = target.host, let scheme = target.scheme?.lowercased(),
               scheme == "http" || scheme == "https" else {
             throw ConnectionError.unsupportedURL(target)
@@ -237,7 +246,7 @@ final class HeldSourceConnection: @unchecked Sendable {
         if secure { task.startSecureConnection() }
 
         try write(Self.requestBytes(target: target, host: host, port: port, secure: secure,
-                                    offset: offset, extraHeaders: extraHeaders,
+                                    offset: offset, extraHeaders: headers,
                                     userAgent: userAgent))
         return try readHead()
     }
@@ -441,11 +450,18 @@ extension HeldSourceConnection {
                              secure: Bool,
                              offset: Int64,
                              extraHeaders: [String: String],
-                             userAgent: String?) -> Data {
-        var path = target.path.isEmpty ? "/" : target.path
-        if let query = target.query, !query.isEmpty { path += "?" + query }
+                             userAgent: String?) throws -> Data {
+        // Audit DMX-4: the path goes on the wire as the URL spells it. `URL.path` is decoded, so
+        // `%20`, `%3F` or `%2F` changed the resource asked for, a trailing slash was dropped, and a
+        // `%0D%0A` in a redirect target became a raw line break in the request.
+        let components = URLComponents(url: target, resolvingAgainstBaseURL: true)
+        let encodedPath = components?.percentEncodedPath ?? ""
+        var path = encodedPath.isEmpty ? "/" : encodedPath
+        if let query = components?.percentEncodedQuery, !query.isEmpty { path += "?" + query }
+        // An IPv6 literal is bracketed in Host, or its colons read as the port separator.
+        let hostName = host.contains(":") && !host.hasPrefix("[") ? "[\(host)]" : host
         // A non-default port belongs in Host, since the origin may route on it.
-        let hostHeader = (secure && port == 443) || (!secure && port == 80) ? host : "\(host):\(port)"
+        let hostHeader = (secure && port == 443) || (!secure && port == 80) ? hostName : "\(hostName):\(port)"
 
         var lines = ["GET \(path) HTTP/1.1",
                      "Host: \(hostHeader)",
@@ -461,6 +477,11 @@ extension HeldSourceConnection {
             lines.removeAll { $0.lowercased().hasPrefix(name.lowercased() + ":") }
             lines.append("\(name): \(value)")
         }
+        // Every field is written raw, so one carrying a line break would add lines of its own.
+        // `isNewline`, because CRLF is a single Swift Character that matches neither "\r" nor "\n".
+        if let bad = lines.first(where: { $0.contains(where: \.isNewline) }) {
+            throw ConnectionError.invalidHeaderField(String(bad.prefix(while: { $0 != ":" && $0 != " " })))
+        }
         return Data((lines.joined(separator: "\r\n") + "\r\n\r\n").utf8)
     }
 }
diff --git a/Tests/AetherEngineTests/Issue377HeldConnectionTests.swift b/Tests/AetherEngineTests/Issue377HeldConnectionTests.swift
index 4a9c63db9..5405c4b8c 100644
--- a/Tests/AetherEngineTests/Issue377HeldConnectionTests.swift
+++ b/Tests/AetherEngineTests/Issue377HeldConnectionTests.swift
@@ -81,7 +81,7 @@ struct Issue377HeldConnectionTests {
     @Test("the request carries the range, the host and the path with its query")
     func requestFraming() throws {
         let url = try #require(URL(string: "https://cdn.example.com/media/file.mkv?token=abc&x=1"))
-        let bytes = HeldSourceConnection.requestBytes(
+        let bytes = try HeldSourceConnection.requestBytes(
             target: url, host: "cdn.example.com", port: 443, secure: true,
             offset: 14_652_209_616, extraHeaders: [:], userAgent: "AetherEngine/test")
         let text = String(decoding: bytes, as: UTF8.self)
@@ -96,7 +96,7 @@ struct Issue377HeldConnectionTests {
     @Test("a non-default port rides in Host, because an origin may route on it")
     func hostCarriesNonDefaultPort() throws {
         let url = try #require(URL(string: "http://192.168.1.10:8096/Videos/1/stream"))
-        let text = String(decoding: HeldSourceConnection.requestBytes(
+        let text = String(decoding: try HeldSourceConnection.requestBytes(
             target: url, host: "192.168.1.10", port: 8096, secure: false,
             offset: 0, extraHeaders: [:], userAgent: nil), as: UTF8.self)
         #expect(text.contains("\r\nHost: 192.168.1.10:8096\r\n"))
@@ -106,7 +106,7 @@ struct Issue377HeldConnectionTests {
     @Test("a source header set wins without duplicating a header the request already sends")
     func extraHeadersDoNotDuplicate() throws {
         let url = try #require(URL(string: "https://jellyfin.example.com/Items/1/Download"))
-        let text = String(decoding: HeldSourceConnection.requestBytes(
+        let text = String(decoding: try HeldSourceConnection.requestBytes(
             target: url, host: "jellyfin.example.com", port: 443, secure: true, offset: 0,
             extraHeaders: ["X-Emby-Token": "secret", "User-Agent": "Sodalite/1.0", "Range": "bytes=99-"],
             userAgent: "AetherEngine/test"), as: UTF8.self)
@@ -120,6 +120,38 @@ struct Issue377HeldConnectionTests {
         #expect(text.contains("\r\nRange: bytes=0-\r\n"))
     }
 
+    @Test("the path and query go on the wire percent-encoded, as the URL spells them")
+    func requestKeepsThePercentEncoding() throws {
+        let url = try #require(URL(string: "http://h.example/My%20Movie%3F.mkv/?a=%20b&c=%0D%0A"))
+        let text = String(decoding: try HeldSourceConnection.requestBytes(
+            target: url, host: "h.example", port: 80, secure: false,
+            offset: 0, extraHeaders: [:], userAgent: nil), as: UTF8.self)
+        #expect(text.hasPrefix("GET /My%20Movie%3F.mkv/?a=%20b&c=%0D%0A HTTP/1.1\r\n"))
+        #expect(text.components(separatedBy: "\r\n").allSatisfy { !$0.contains("\r") && !$0.contains("\n") })
+    }
+
+    @Test("an IPv6 literal is bracketed in Host")
+    func ipv6HostIsBracketed() throws {
+        let url = try #require(URL(string: "http://[::1]:8096/Videos/1/stream"))
+        let host = try #require(url.host)
+        let text = String(decoding: try HeldSourceConnection.requestBytes(
+            target: url, host: host, port: 8096, secure: false,
+            offset: 0, extraHeaders: [:], userAgent: nil), as: UTF8.self)
+        #expect(text.contains("\r\nHost: [::1]:8096\r\n"))
+    }
+
+    @Test("a header value carrying a line break is refused rather than written")
+    func lineBreakInAHeaderIsRefused() throws {
+        let url = try #require(URL(string: "http://h.example/a.mkv"))
+        for value in ["a\r\nX-Injected: 1", "a\nX-Injected: 1", "a\rb"] {
+            #expect(throws: (any Error).self) {
+                try HeldSourceConnection.requestBytes(
+                    target: url, host: "h.example", port: 80, secure: false, offset: 0,
+                    extraHeaders: ["X-Custom": value], userAgent: nil)
+            }
+        }
+    }
+
     // MARK: - Chunked framing
 
     @Test("a chunked body decodes across arbitrary feed boundaries")
@@ -264,6 +296,37 @@ struct Issue377HeldConnectionTests {
         #expect(origin.requestLog.map(\.path) == ["/source.mkv", "/pinned.mkv"])
     }
 
+    @Test("a cross-origin redirect drops the credential headers and keeps the rest")
+    func crossOriginRedirectDropsCredentials() async throws {
+        let total: Int64 = 64 * 1024
+        final class PortBox: @unchecked Sendable { var port: UInt16 = 0 }
+        let box = PortBox()
+        let respond: @Sendable (Int, Int64, String) -> ThrottledOriginServer.Directive = { _, _, path in
+            path == "/pinned.mkv" ? .serve206 : .redirect(to: "http://localhost:\(box.port)/pinned.mkv")
+        }
+        let redirecting = ThrottledOriginServer(totalSize: total, throttleUs: 0, respond: respond)
+        let origin = try #require(redirecting)
+        defer { origin.stop() }
+        box.port = origin.port
+        let url = try #require(URL(string: "http://127.0.0.1:\(origin.port)/source.mkv"))
+
+        let delegate = RecordingHeldDelegate(defaultBudget: 64 * 1024)
+        let connection = HeldSourceConnection(
+            url: url, offset: 0,
+            extraHeaders: ["X-Emby-Token": "secret", "Authorization": "MediaBrowser Token=\"secret\"",
+                           "X-Custom": "kept"],
+            userAgent: nil, label: "test", delegate: delegate)
+        connection.start()
+        #expect(delegate.waitForEnd())
+
+        let headers = origin.requestHeaders
+        try #require(headers.count == 2)
+        #expect(headers[0]["x-emby-token"] == "secret")
+        #expect(headers[1]["x-emby-token"] == nil)
+        #expect(headers[1]["authorization"] == nil)
+        #expect(headers[1]["x-custom"] == "kept")
+    }
+
     @Test("a mid-body offset asks for exactly that offset")
     func offsetIsHonoured() async throws {
         let total: Int64 = 4 * 1024 * 1024

From fd8a13883664b9aabcd44b943dd67b5404066ba2 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 05:23:52 +0200
Subject: [PATCH 040/359] fix(hls): cap playlist and held relay bodies while
 they arrive, not after (audit NET-10)

The VOD ingest and the carriage probe tested their 2 MB playlist cap after
`session.data(for:)` had buffered the whole body, the live ingest refetched
its playlist every few seconds with no cap at all, and the relay held any
chunked, non-2xx or playlist body whole for as long as the 120 s resource
timeout let it grow.

- Playlist fetches go through `BoundedPlaylistFetch`: a declared length over
  the cap is refused before a byte is read, an undeclared one is cut off at
  the cap. The live ingest gets 8 MB, since a long DVR window is a
  legitimately long playlist.
- The relay caps a held playlist at 16 MB and any other held body at 64 MB.
  A success over the cap is a 502; an error over it keeps its status and
  drops the body.
- The carriage probe's shared session gets a 30 s resource timeout, so an
  origin trickling a byte inside the idle timeout cannot hold a probe open.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 .../IO/HLSIngest/BoundedPlaylistFetch.swift   | 34 ++++++++
 .../IO/HLSIngest/HLSCarriageProbe.swift       |  8 +-
 .../IO/HLSIngest/HLSLiveIngestReader.swift    |  6 +-
 .../IO/HLSIngest/HLSVODIngestReader.swift     |  6 +-
 .../AetherEngine/Network/HLSOriginRelay.swift | 43 ++++++++--
 .../BoundedPlaylistFetchTests.swift           | 85 +++++++++++++++++++
 .../HLSOriginRelayTests.swift                 | 35 ++++++++
 7 files changed, 202 insertions(+), 15 deletions(-)
 create mode 100644 Sources/AetherEngine/IO/HLSIngest/BoundedPlaylistFetch.swift
 create mode 100644 Tests/AetherEngineTests/BoundedPlaylistFetchTests.swift

diff --git a/Sources/AetherEngine/IO/HLSIngest/BoundedPlaylistFetch.swift b/Sources/AetherEngine/IO/HLSIngest/BoundedPlaylistFetch.swift
new file mode 100644
index 000000000..7692eb9fd
--- /dev/null
+++ b/Sources/AetherEngine/IO/HLSIngest/BoundedPlaylistFetch.swift
@@ -0,0 +1,34 @@
+import Foundation
+
+/// Reads a playlist body with its size cap enforced while it arrives (audit NET-10).
+///
+/// `session.data(for:)` buffers the whole body before a caller can look at its size, so a cap tested
+/// afterwards bounded nothing: an origin answering with an endless body kept the fetch growing until
+/// the resource timeout, or until jetsam. Here a declared length over the cap is refused before a
+/// byte is read, and an undeclared one is cut off at the cap.
+enum BoundedPlaylistFetch {
+
+    /// The body and response of `request`. A non-2xx answer comes back with an empty body: every
+    /// caller throws on the status alone, so its body is not worth reading.
+    static func data(for request: URLRequest, session: URLSession, limit: Int) async throws
+        -> (Data, URLResponse)
+    {
+        let (bytes, response) = try await session.bytes(for: request)
+        defer { bytes.task.cancel() }
+        let status = (response as? HTTPURLResponse)?.statusCode ?? -1
+        guard (200..<300).contains(status) else { return (Data(), response) }
+        let declared = response.expectedContentLength
+        guard declared <= Int64(limit) else { throw exceeded(limit) }
+        var data = Data()
+        if declared > 0 { data.reserveCapacity(Int(declared)) }
+        for try await byte in bytes {
+            guard data.count < limit else { throw exceeded(limit) }
+            data.append(byte)
+        }
+        return (data, response)
+    }
+
+    private static func exceeded(_ limit: Int) -> HLSIngestError {
+        .playlistInvalid(reason: "playlist exceeds \(limit) bytes")
+    }
+}
diff --git a/Sources/AetherEngine/IO/HLSIngest/HLSCarriageProbe.swift b/Sources/AetherEngine/IO/HLSIngest/HLSCarriageProbe.swift
index 5b83af9e6..42fb804f8 100644
--- a/Sources/AetherEngine/IO/HLSIngest/HLSCarriageProbe.swift
+++ b/Sources/AetherEngine/IO/HLSIngest/HLSCarriageProbe.swift
@@ -26,6 +26,9 @@ enum HLSCarriageProbe {
     private static let sharedSession: URLSession = {
         let configuration = URLSessionConfiguration.ephemeral
         configuration.timeoutIntervalForRequest = 10
+        // The request timeout is an idle timeout; without a resource ceiling an origin trickling a
+        // byte every few seconds kept a probe open for the 7-day default (audit NET-10).
+        configuration.timeoutIntervalForResource = 30
         return URLSession(
             configuration: configuration, delegate: EngineTLS.sessionDelegate, delegateQueue: nil)
     }()
@@ -205,12 +208,13 @@ enum HLSCarriageProbe {
     ) async throws -> (HLSPlaylist, URL) {
         let request = makeRequest(
             url, httpHeaders: RedirectHeaderPolicy.scoped(httpHeaders, grantedFor: credentialOrigin, sentTo: url))
-        let (data, response) = try await session.data(for: request)
+        let (data, response) = try await BoundedPlaylistFetch.data(
+            for: request, session: session, limit: maximumPlaylistBytes)
         let status = (response as? HTTPURLResponse)?.statusCode ?? -1
         guard (200..<300).contains(status) else {
             throw HLSIngestError.playlistUnreachable(status: status)
         }
-        guard data.count <= maximumPlaylistBytes, let text = String(data: data, encoding: .utf8) else {
+        guard let text = String(data: data, encoding: .utf8) else {
             throw HLSIngestError.playlistInvalid(reason: "playlist is not bounded UTF-8")
         }
         return (try HLSPlaylistParser.parse(text), response.url ?? url)
diff --git a/Sources/AetherEngine/IO/HLSIngest/HLSLiveIngestReader.swift b/Sources/AetherEngine/IO/HLSIngest/HLSLiveIngestReader.swift
index cdec29d8c..783269ee7 100644
--- a/Sources/AetherEngine/IO/HLSIngest/HLSLiveIngestReader.swift
+++ b/Sources/AetherEngine/IO/HLSIngest/HLSLiveIngestReader.swift
@@ -23,6 +23,9 @@ public final class HLSLiveIngestReader: IOReader, LiveIngestSourceInfo, @uncheck
     private let credentialOrigin: URL
     private let role: Role
     private let fifo = ByteFIFO(capacity: 16 * 1024 * 1024)
+    /// Wider than the VOD reader's 2 MB: a live window with hours of DVR at short segments is a
+    /// legitimately long playlist, and this one is refetched every few seconds rather than once.
+    static let maximumPlaylistBytes = 8 * 1024 * 1024
     private let session: URLSession
     private var ingestTask: Task<Void, Never>?
     private let startLock = NSLock()
@@ -566,7 +569,8 @@ public final class HLSLiveIngestReader: IOReader, LiveIngestSourceInfo, @uncheck
 
     /// Fetch + parse a playlist. Returns parsed playlist and final URL after redirects (relative segment URIs resolve against it).
     private func fetchPlaylist(_ url: URL) async throws -> (HLSPlaylist, URL) {
-        let (data, response) = try await session.data(for: makeRequest(url))
+        let (data, response) = try await BoundedPlaylistFetch.data(
+            for: makeRequest(url), session: session, limit: Self.maximumPlaylistBytes)
         let status = (response as? HTTPURLResponse)?.statusCode ?? -1
         guard (200..<300).contains(status) else {
             throw HLSIngestError.playlistUnreachable(status: status)
diff --git a/Sources/AetherEngine/IO/HLSIngest/HLSVODIngestReader.swift b/Sources/AetherEngine/IO/HLSIngest/HLSVODIngestReader.swift
index 7023d2854..86b6f8429 100644
--- a/Sources/AetherEngine/IO/HLSIngest/HLSVODIngestReader.swift
+++ b/Sources/AetherEngine/IO/HLSIngest/HLSVODIngestReader.swift
@@ -510,13 +510,13 @@ final class HLSVODIngestReader: TimeSeekableIOReader, @unchecked Sendable {
     }
 
     private func fetchPlaylist(_ url: URL) async throws -> (HLSPlaylist, URL) {
-        let (data, response) = try await session.data(for: makeRequest(url))
+        let (data, response) = try await BoundedPlaylistFetch.data(
+            for: makeRequest(url), session: session, limit: Self.maximumPlaylistBytes)
         let status = (response as? HTTPURLResponse)?.statusCode ?? -1
         guard (200..<300).contains(status) else {
             throw HLSIngestError.playlistUnreachable(status: status)
         }
-        guard data.count <= Self.maximumPlaylistBytes,
-              let text = String(data: data, encoding: .utf8) else {
+        guard let text = String(data: data, encoding: .utf8) else {
             throw HLSIngestError.playlistInvalid(reason: "playlist is not bounded UTF-8")
         }
         return (try HLSPlaylistParser.parse(text), response.url ?? url)
diff --git a/Sources/AetherEngine/Network/HLSOriginRelay.swift b/Sources/AetherEngine/Network/HLSOriginRelay.swift
index 6c1693fde..10fb27471 100644
--- a/Sources/AetherEngine/Network/HLSOriginRelay.swift
+++ b/Sources/AetherEngine/Network/HLSOriginRelay.swift
@@ -75,7 +75,10 @@ final class HLSOriginRelay: @unchecked Sendable {
     /// invalidated.
     private let session: URLSession
 
-    init() {
+    private let heldBodyLimit: Int
+
+    init(maximumHeldBodyBytes: Int = HLSOriginRelay.maximumHeldBodyBytes) {
+        heldBodyLimit = maximumHeldBodyBytes
         let config = URLSessionConfiguration.ephemeral
         config.requestCachePolicy = .reloadIgnoringLocalAndRemoteCacheData
         config.urlCache = nil
@@ -364,6 +367,13 @@ final class HLSOriginRelay: @unchecked Sendable {
         case failed
     }
 
+    /// Audit NET-10: a held body is buffered whole, and the resource timeout alone let a hostile or
+    /// broken origin grow one for two minutes at link rate. A playlist larger than this is not one a
+    /// player will get through; a held media body (a segment served without a length) gets the wider
+    /// cap, and an error body is dropped past it while its status still goes through.
+    static let maximumHeldPlaylistBytes = 16 * 1024 * 1024
+    static let maximumHeldBodyBytes = 64 * 1024 * 1024
+
     /// The answers that mean "you are asking too often", which arm the pacer for this origin.
     private static let refusalStatuses: Set<Int> = [429, 503, 509]
 
@@ -424,11 +434,20 @@ final class HLSOriginRelay: @unchecked Sendable {
         // A length the origin did not state cannot be framed for the player without buffering the
         // body to measure it, and a playlist has to be read whole to be rewritten at all.
         let declaredLength = http.expectedContentLength
-        let mustHold = declaredLength < 0
-            || !(200..<300).contains(http.statusCode)
-            || Self.looksLikePlaylist(url: origin, contentType: contentType)
+        let isPlaylist = Self.looksLikePlaylist(url: origin, contentType: contentType)
+        let isSuccess = (200..<300).contains(http.statusCode)
+        let mustHold = declaredLength < 0 || !isSuccess || isPlaylist
         guard !mustHold else {
-            let body = pump.awaitWholeBody()
+            let limit = isPlaylist ? min(Self.maximumHeldPlaylistBytes, heldBodyLimit) : heldBodyLimit
+            guard let body = pump.awaitWholeBody(limit: limit) else {
+                EngineLog.emit(
+                    "[HLSOriginRelay] \(origin.host ?? "origin") answered \(http.statusCode) with a body over "
+                        + "\(limit) bytes; not holding it", category: .hlsServer)
+                if isSuccess { return .failed }
+                return .held(
+                    Fetched(status: http.statusCode, body: Data(), contentType: contentType,
+                            contentRange: contentRange))
+            }
             if let error = pump.awaitFailure() {
                 // A playlist read halfway is not a playlist, and the framing of a held answer is its
                 // own length, so there is nothing here worth passing on.
@@ -568,14 +587,20 @@ private final class UpstreamPump: NSObject, URLSessionDataDelegate, @unchecked S
         return head
     }
 
-    /// Every byte of the body, for the answers that have to be read whole.
-    func awaitWholeBody() -> Data {
+    /// Every byte of the body, for the answers that have to be read whole, or nil once it passes
+    /// `limit`, which also stops the transfer.
+    func awaitWholeBody(limit: Int) -> Data? {
+        if let head = awaitHead(), head.expectedContentLength > Int64(limit) {
+            abandon()
+            return nil
+        }
         var body = Data()
-        _ = drain { chunk in
+        let complete = drain { chunk in
+            guard body.count + chunk.count <= limit else { return false }
             body.append(chunk)
             return true
         }
-        return body
+        return complete ? body : nil
     }
 
     /// Hands each chunk to `write` as it arrives, until the body ends or a write fails. Returns
diff --git a/Tests/AetherEngineTests/BoundedPlaylistFetchTests.swift b/Tests/AetherEngineTests/BoundedPlaylistFetchTests.swift
new file mode 100644
index 000000000..235170499
--- /dev/null
+++ b/Tests/AetherEngineTests/BoundedPlaylistFetchTests.swift
@@ -0,0 +1,85 @@
+import Foundation
+import Testing
+@testable import AetherEngine
+
+/// The playlist caps in the ingest readers and the carriage probe used to be tested after
+/// `session.data(for:)` had buffered the whole body, so they bounded nothing (audit NET-10). These
+/// pin that the cap now holds while the body arrives, with and without a declared length.
+@Suite("Playlist bodies are capped while they arrive", .serialized)
+struct BoundedPlaylistFetchTests {
+
+    private static let limit = 4096
+
+    @Test("A body within the cap arrives whole")
+    func withinCap() async throws {
+        let (data, response) = try await fetch(.init(chunks: 3, chunkBytes: 1000, declaresLength: false))
+        #expect((response as? HTTPURLResponse)?.statusCode == 200)
+        #expect(data.count == 3000)
+    }
+
+    @Test("A declared length over the cap is refused before the body is read")
+    func declaredOverCap() async {
+        await #expect(throws: HLSIngestError.playlistInvalid(reason: "playlist exceeds \(Self.limit) bytes")) {
+            _ = try await fetch(.init(chunks: 8, chunkBytes: 1000, declaresLength: true))
+        }
+    }
+
+    @Test("A body with no stated length is cut off at the cap")
+    func undeclaredOverCap() async {
+        await #expect(throws: HLSIngestError.playlistInvalid(reason: "playlist exceeds \(Self.limit) bytes")) {
+            _ = try await fetch(.init(chunks: 64, chunkBytes: 1000, declaresLength: false))
+        }
+    }
+
+    @Test("A refusal comes back with its status and no body")
+    func refusalKeepsItsStatus() async throws {
+        let (data, response) = try await fetch(.init(chunks: 64, chunkBytes: 1000, declaresLength: false, status: 404))
+        #expect((response as? HTTPURLResponse)?.statusCode == 404)
+        #expect(data.isEmpty)
+    }
+
+    private func fetch(_ shape: StreamingPlaylistProtocol.Shape) async throws -> (Data, URLResponse) {
+        StreamingPlaylistProtocol.shape = shape
+        let configuration = URLSessionConfiguration.ephemeral
+        configuration.protocolClasses = [StreamingPlaylistProtocol.self]
+        let session = URLSession(configuration: configuration)
+        defer { session.invalidateAndCancel() }
+        return try await BoundedPlaylistFetch.data(
+            for: URLRequest(url: URL(string: "https://origin.test/live.m3u8")!), session: session,
+            limit: Self.limit)
+    }
+}
+
+/// Answers every request with `shape`: a body delivered in chunks, with or without a length.
+private final class StreamingPlaylistProtocol: URLProtocol, @unchecked Sendable {
+    struct Shape {
+        var chunks: Int
+        var chunkBytes: Int
+        var declaresLength: Bool
+        var status = 200
+    }
+
+    private static let lock = NSLock()
+    nonisolated(unsafe) private static var _shape = Shape(chunks: 0, chunkBytes: 0, declaresLength: false)
+    static var shape: Shape {
+        get { lock.withLock { _shape } }
+        set { lock.withLock { _shape = newValue } }
+    }
+
+    override class func canInit(with request: URLRequest) -> Bool { true }
+    override class func canonicalRequest(for request: URLRequest) -> URLRequest { request }
+    override func stopLoading() {}
+
+    override func startLoading() {
+        let shape = Self.shape
+        var fields = ["Content-Type": "application/vnd.apple.mpegurl"]
+        if shape.declaresLength { fields["Content-Length"] = String(shape.chunks * shape.chunkBytes) }
+        let response = HTTPURLResponse(
+            url: request.url!, statusCode: shape.status, httpVersion: "HTTP/1.1", headerFields: fields)!
+        client?.urlProtocol(self, didReceive: response, cacheStoragePolicy: .notAllowed)
+        for _ in 0 ..< shape.chunks {
+            client?.urlProtocol(self, didLoad: Data(repeating: 0x23, count: shape.chunkBytes))
+        }
+        client?.urlProtocolDidFinishLoading(self)
+    }
+}
diff --git a/Tests/AetherEngineTests/HLSOriginRelayTests.swift b/Tests/AetherEngineTests/HLSOriginRelayTests.swift
index b35f08320..8c6ea1b8e 100644
--- a/Tests/AetherEngineTests/HLSOriginRelayTests.swift
+++ b/Tests/AetherEngineTests/HLSOriginRelayTests.swift
@@ -231,6 +231,41 @@ struct HLSOriginRelayAddressingTests {
     // which a macOS `swift build` never shows.
     #if os(macOS)
 
+    @Test("A held body that outgrows its cap is refused instead of buffered whole (audit NET-10)")
+    func heldBodyIsBounded() async throws {
+        // No length stated, so the relay has to hold it; eight 64 KB slices against a 256 KB cap.
+        let upstream = try #require(await TricklingOrigin(slices: 8, pauseSeconds: 0, declaresLength: false))
+        defer { upstream.stop() }
+        let relay = HLSOriginRelay(maximumHeldBodyBytes: 256 * 1024)
+        let server = HLSLocalServer(relay: relay)
+        try server.start()
+        defer { server.stop(); relay.stop() }
+
+        let entry = try #require(server.relayURL(for: URL(string: "http://127.0.0.1:\(upstream.port)/seg.ts")!))
+        var request = URLRequest(url: entry)
+        request.timeoutInterval = 30
+        let (body, response) = try await URLSession.shared.data(for: request)
+        let http = try #require(response as? HTTPURLResponse)
+        #expect(http.statusCode == 502, "an over-cap held body was relayed (\(body.count) bytes)")
+    }
+
+    @Test("A held body under its cap still arrives whole")
+    func heldBodyUnderCapArrives() async throws {
+        let upstream = try #require(await TricklingOrigin(slices: 2, pauseSeconds: 0, declaresLength: false))
+        defer { upstream.stop() }
+        let relay = HLSOriginRelay(maximumHeldBodyBytes: 256 * 1024)
+        let server = HLSLocalServer(relay: relay)
+        try server.start()
+        defer { server.stop(); relay.stop() }
+
+        let entry = try #require(server.relayURL(for: URL(string: "http://127.0.0.1:\(upstream.port)/seg.ts")!))
+        var request = URLRequest(url: entry)
+        request.timeoutInterval = 30
+        let (body, response) = try await URLSession.shared.data(for: request)
+        #expect((response as? HTTPURLResponse)?.statusCode == 200)
+        #expect(body.count == TricklingOrigin.totalBytes(slices: 2))
+    }
+
     @Test("A range is forwarded verbatim and its framing comes back")
     func rangesPassThroughUntouched() async throws {
         let upstream = try #require(await RangeEchoOrigin())

From 803bf386c7abe7bfe20b0d6593a4da2abef1d04e Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 05:26:11 +0200
Subject: [PATCH 041/359] fix(demuxer): guard the provider reference and answer
 stream lookups from a locked copy (audit DMX-11, NAT-7)

DMX-11: `markClosed()` loaded `avioProvider` from another thread while
`close()` or a failed open cleared it. The reference now sits behind a
leaf lock of its own, so the cross-thread abort takes a retained
snapshot.

NAT-7: `stream(at:)` indexed `formatContext.streams` without a lock while
`av_read_frame` on MPEG-TS can reallocate that array. Lookups now answer
from a table copied under `accessLock` (after open, after stream info,
and whenever a read changes the stream count), taking the lock only with
`try` so a main-actor caller never waits out a network read.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 Sources/AetherEngine/Demuxer/Demuxer.swift    |  67 ++++++++++-
 .../DemuxerStreamLookupTests.swift            | 108 ++++++++++++++++++
 2 files changed, 171 insertions(+), 4 deletions(-)
 create mode 100644 Tests/AetherEngineTests/DemuxerStreamLookupTests.swift

diff --git a/Sources/AetherEngine/Demuxer/Demuxer.swift b/Sources/AetherEngine/Demuxer/Demuxer.swift
index 7465a04b1..ea4f51b24 100644
--- a/Sources/AetherEngine/Demuxer/Demuxer.swift
+++ b/Sources/AetherEngine/Demuxer/Demuxer.swift
@@ -225,9 +225,35 @@ public final class Demuxer: @unchecked Sendable {
     // concurrent access triggers assertion failures in matroskadec.c.
     private let accessLock = NSLock()
 
-    private var avioProvider: AVIOProvider?
+    /// Audit DMX-11: `markClosed()` is the lock-free cross-thread abort, so it loads this reference
+    /// while the demux thread may be clearing it in `close()` or a failed open. A leaf lock of its
+    /// own (never `accessLock`, which `av_read_frame` holds for a whole network read) makes that
+    /// load a retained snapshot instead of a race.
+    private let providerLock = NSLock()
+    private var _avioProvider: AVIOProvider?
+    private var avioProvider: AVIOProvider? {
+        get {
+            providerLock.lock()
+            defer { providerLock.unlock() }
+            return _avioProvider
+        }
+        set {
+            providerLock.lock()
+            _avioProvider = newValue
+            providerLock.unlock()
+        }
+    }
     private var openProfile: DemuxerOpenProfile = .playback
 
+    /// Audit NAT-7: the stream pointers `stream(at:)` hands out, copied out of `formatContext`
+    /// under `accessLock`. MPEG-TS adds streams inside `av_read_frame`, which reallocates the
+    /// `streams` array, so a caller on another thread must not index the live array while a read
+    /// holds the lock. The `AVStream`s themselves live until `avformat_close_input`. Guarded by
+    /// `streamTableLock`, a leaf lock; `streamTableSize` is its length, guarded by `accessLock`.
+    private let streamTableLock = NSLock()
+    private var streamTable: [UnsafeMutablePointer<AVStream>] = []
+    private var streamTableSize = 0
+
     /// The URL and headers this demuxer was opened from, kept for the recordless Dolby Vision audit's
     /// second open. nil for a custom reader (no second open to give) and for a live source.
     private var auditSource: (url: URL, headers: [String: String])?
@@ -472,6 +498,9 @@ public final class Demuxer: @unchecked Sendable {
         onOpenProgress?(.containerOpened)
 
         try probeStreams(openedCtx)
+        accessLock.lock()
+        refreshStreamTableLocked()
+        accessLock.unlock()
         onOpenProgress?(.streamsProbed)
     }
 
@@ -627,6 +656,9 @@ public final class Demuxer: @unchecked Sendable {
         onOpenProgress?(.containerOpened)   // #361
 
         try probeStreams(ctxPtr!)
+        accessLock.lock()
+        refreshStreamTableLocked()
+        accessLock.unlock()
         onOpenProgress?(.streamsProbed)     // #361
         // #281: every parse seek this open performs has happened by now, so the provider can drop
         // the cold-start state that only exists to serve them. Deliberately after probeStreams:
@@ -858,6 +890,7 @@ public final class Demuxer: @unchecked Sendable {
         guard let ctx = formatContext else { return }
         reclassifyAttachedPictures(ctx)
         _ = avformat_find_stream_info(ctx, nil)
+        refreshStreamTableLocked()
     }
 
     /// True if the stream at `index` is missing or carries no resolved codec yet (`AV_CODEC_ID_NONE`).
@@ -1309,10 +1342,34 @@ public final class Demuxer: @unchecked Sendable {
     }
 
     func stream(at index: Int32) -> UnsafeMutablePointer<AVStream>? {
-        guard let ctx = formatContext, index >= 0, index < ctx.pointee.nb_streams else {
-            return nil
+        guard index >= 0 else { return nil }
+        // `try`, not `lock`: a read can hold `accessLock` for a whole network stall, and a caller
+        // on the main actor must not wait that out. The table a busy read leaves behind is current
+        // anyway, since `readPacketLocked` refreshes it whenever a read adds a stream.
+        if accessLock.try() {
+            refreshStreamTableLocked()
+            accessLock.unlock()
+        }
+        streamTableLock.lock()
+        defer { streamTableLock.unlock() }
+        return Int(index) < streamTable.count ? streamTable[Int(index)] : nil
+    }
+
+    /// Caller holds `accessLock`.
+    private func refreshStreamTableLocked() {
+        var table: [UnsafeMutablePointer<AVStream>] = []
+        if let ctx = formatContext, let streams = ctx.pointee.streams {
+            let count = Int(ctx.pointee.nb_streams)
+            table.reserveCapacity(count)
+            for i in 0..<count {
+                guard let stream = streams[i] else { break }
+                table.append(stream)
+            }
         }
-        return ctx.pointee.streams[Int(index)]
+        streamTableSize = table.count
+        streamTableLock.lock()
+        streamTable = table
+        streamTableLock.unlock()
     }
 
     /// Sets AVDISCARD_ALL on streams outside `keep`. Without this, matroska reads
@@ -1477,6 +1534,7 @@ public final class Demuxer: @unchecked Sendable {
         var packet: UnsafeMutablePointer<AVPacket>? = trackedPacketAlloc()
         guard packet != nil else { return nil }
         let ret = av_read_frame(ctx, packet)
+        if Int(ctx.pointee.nb_streams) != streamTableSize { refreshStreamTableLocked() }
         do {
             try probeControl?.check()
             if ret >= 0, let packet { try probeControl?.receivedPacket(packet) }
@@ -2031,6 +2089,7 @@ public final class Demuxer: @unchecked Sendable {
         formatContext = nil
         compositionRepair = nil
         compositionRepairEvaluated = false
+        refreshStreamTableLocked()
         accessLock.unlock()
 
         avioProvider?.close()
diff --git a/Tests/AetherEngineTests/DemuxerStreamLookupTests.swift b/Tests/AetherEngineTests/DemuxerStreamLookupTests.swift
new file mode 100644
index 000000000..b949949d0
--- /dev/null
+++ b/Tests/AetherEngineTests/DemuxerStreamLookupTests.swift
@@ -0,0 +1,108 @@
+import Testing
+import Foundation
+import AetherLibavcodec
+@testable import AetherEngine
+
+/// `Demuxer.stream(at:)` is called from the main actor while the demux thread sits inside
+/// `av_read_frame`, which on MPEG-TS can reallocate the `streams` array (audit NAT-7). It answers
+/// from a table copied under the demuxer's lock, so it neither indexes the live array nor waits out a
+/// read that holds that lock for a whole network stall.
+@Suite("Demuxer stream lookup")
+struct DemuxerStreamLookupTests {
+
+    /// A WAV source whose reads can be made to block, the way a network read parks.
+    private final class GatedReader: IOReader, @unchecked Sendable {
+        private let inner: DataIOReader
+        private let lock = NSLock()
+        private var armed = false
+        private var _blocked = false
+        private let gate = DispatchSemaphore(value: 0)
+
+        init(data: Data) { inner = DataIOReader(data: data) }
+
+        var isBlocked: Bool { lock.lock(); defer { lock.unlock() }; return _blocked }
+
+        func arm() { lock.lock(); armed = true; lock.unlock() }
+
+        func release() {
+            lock.lock()
+            armed = false
+            lock.unlock()
+            gate.signal()
+        }
+
+        func read(_ buffer: UnsafeMutablePointer<UInt8>?, size: Int32) -> Int32 {
+            lock.lock()
+            let wait = armed
+            if wait { _blocked = true }
+            lock.unlock()
+            if wait { gate.wait() }
+            return inner.read(buffer, size: size)
+        }
+
+        func seek(offset: Int64, whence: Int32) -> Int64 { inner.seek(offset: offset, whence: whence) }
+        func close() { inner.close() }
+        func cancel() {}
+        func makeIndependentReader() -> IOReader? { nil }
+        var discImageProbeEnabled: Bool { false }
+    }
+
+    private func makeWAV(seconds: Double) -> Data {
+        let sampleRate = 48_000, channels = 2
+        let pcm = Data(count: Int(Double(sampleRate) * seconds) * channels * 2)
+        var d = Data()
+        func str(_ s: String) { d.append(s.data(using: .ascii)!) }
+        func u32(_ v: UInt32) { withUnsafeBytes(of: v.littleEndian) { d.append(contentsOf: $0) } }
+        func u16(_ v: UInt16) { withUnsafeBytes(of: v.littleEndian) { d.append(contentsOf: $0) } }
+        str("RIFF"); u32(UInt32(36 + pcm.count)); str("WAVE")
+        str("fmt "); u32(16); u16(1); u16(UInt16(channels)); u32(UInt32(sampleRate))
+        u32(UInt32(sampleRate * channels * 2)); u16(UInt16(channels * 2)); u16(16)
+        str("data"); u32(UInt32(pcm.count)); d.append(pcm)
+        return d
+    }
+
+    @Test("every opened stream is found, an index past them is not, and nothing is after close")
+    func lookupFollowsTheOpenStreams() throws {
+        let demuxer = Demuxer()
+        try demuxer.open(reader: DataIOReader(data: makeWAV(seconds: 1)))
+        let audio = demuxer.audioStreamIndex
+        try #require(audio >= 0)
+        #expect(demuxer.stream(at: audio)?.pointee.index == audio)
+        #expect(demuxer.stream(at: audio + 1) == nil)
+        #expect(demuxer.stream(at: -1) == nil)
+        demuxer.close()
+        #expect(demuxer.stream(at: audio) == nil)
+    }
+
+    @Test("a lookup does not wait for a read that holds the demuxer", .timeLimit(.minutes(1)))
+    func lookupDoesNotWaitOutARead() async throws {
+        let reader = GatedReader(data: makeWAV(seconds: 20))
+        let demuxer = Demuxer()
+        try demuxer.open(reader: reader)
+        let audio = demuxer.audioStreamIndex
+        try #require(audio >= 0)
+        reader.arm()
+
+        let done = DispatchSemaphore(value: 0)
+        Thread.detachNewThread {
+            while let packet = try? demuxer.readPacket() {
+                var p: UnsafeMutablePointer<AVPacket>? = packet
+                trackedPacketFree(&p)
+            }
+            done.signal()
+        }
+        try await waitFor { reader.isBlocked }
+
+        #expect(demuxer.stream(at: audio)?.pointee.index == audio)
+
+        demuxer.markClosed()
+        reader.release()
+        await withCheckedContinuation { (continuation: CheckedContinuation<Void, Never>) in
+            Thread.detachNewThread {
+                done.wait()
+                continuation.resume()
+            }
+        }
+        demuxer.close()
+    }
+}

From 394e2ded51fe23a0ec4c5a89e1462ec530a0a00e Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 05:15:55 +0200
Subject: [PATCH 042/359] fix(engine): a load or seek in flight at
 backgrounding gets the background teardown once it settles (audit CORE-2)

didEnterBackground judged the session once, and `backgroundAction` returns doNothing for
`.loading` and `.seeking` on the premise that nothing exists to tear down. A load has its loopback
server, AVIO connection and item by then, and nothing looked again: a load finishing after the TV
button autostarted in the background and crossed the tvOS suspension whole, which is the shape
that wedged mediaserverd (a plausible AE#597 contributor). The same held for a scrub in flight.

The observer now records that the decision is owed, and the `state` didSet applies the same
background policy (keepalive, grace window, teardown) once the state settles into `.playing` or
`.paused` while the app is still in the background. The observer body moved into
`applyBackgroundPolicy()` so both run the one decision. The keepalive test that pinned
`.loading -> doNothing` as "nothing to tear down" now pins the owed decision instead.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 Sources/AetherEngine/AetherEngine.swift       | 118 ++++++++++++------
 .../BackgroundKeepaliveTests.swift            |  19 ++-
 2 files changed, 94 insertions(+), 43 deletions(-)

diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index d9f204e49..055cc8fea 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -61,6 +61,9 @@ public final class AetherEngine: ObservableObject {
             if case .error = state {} else { errorInfo = nil }
             recomputePlaybackPhase()
             resolveLoadingStashedSeek(from: oldValue)
+            #if os(iOS) || os(tvOS)
+            settleOwedBackgroundAction()
+            #endif
         }
     }
 
@@ -873,6 +876,8 @@ public final class AetherEngine: ObservableObject {
     /// True between didEnterBackground and didBecomeActive; gates the pause-while-backgrounded teardown
     /// (iOS) and the PiP-closed-while-backgrounded teardown (tvOS).
     private var isBackgrounded = false
+    /// Audit CORE-2: didEnterBackground ran while a load or seek was in flight.
+    private var backgroundActionOwed = false
     #endif
     #if os(iOS)
     /// #127: pending grace-window teardown (sleep task + the background-task assertion holding it).
@@ -1034,6 +1039,13 @@ public final class AetherEngine: ObservableObject {
         return .teardownVideo
     }
 
+    /// Audit CORE-2: a state in which `backgroundAction` cannot judge the pipeline yet, although one
+    /// exists (a load has its loopback server and AVIO connection, a seek its whole session). The
+    /// decision is owed until the state settles.
+    nonisolated static func backgroundActionIsOwed(state: PlaybackState) -> Bool {
+        state == .loading || state == .seeking
+    }
+
     /// #127: how to execute a BackgroundAction. A PAUSED teardown on platforms with quick app switches
     /// (iOS) is deferred by a grace window held under a background-task assertion, so a 10-30 s app
     /// switch does not pay a full pipeline rebuild. Wedge-safety holds: the assertion keeps the app
@@ -6934,48 +6946,12 @@ public final class AetherEngine: ObservableObject {
         ) { [weak self] _ in
             Task { @MainActor in
                 guard let self = self else { return }
-                #if os(iOS)
                 self.isBackgrounded = true
-                // Keep the video pipeline alive for PiP / background audio while the app stays running.
-                // Wedge-safe: a pause while backgrounded tears down via pause() below, so nothing crosses
-                // an idle suspension.
-                let keepAlive = Self.shouldKeepVideoAlive(enabled: self.backgroundPlaybackEnabled,
-                                                          pipActive: self.pictureInPictureActive,
-                                                          state: self.state)
-                let supportsGrace = true
-                #else
-                self.isBackgrounded = true
-                // tvOS: only an active PiP window defers the wedge-safe teardown (the system keeps the app
-                // running while its PiP window lives); no grace window, no background-audio case. The
-                // pictureInPictureActive didSet tears down the moment PiP ends while still backgrounded.
-                let keepAlive = Self.shouldKeepVideoAliveTV(enabled: self.backgroundPlaybackEnabled,
-                                                            pipActive: self.pictureInPictureActive)
-                let supportsGrace = false
-                #endif
-                let action = Self.backgroundAction(
-                    isAudioBackend: self.audioAVPlayerActive || self.audioHost != nil,
-                    hasSoftwareHost: self.softwareHost != nil,
-                    keepVideoAlive: keepAlive,
-                    pipActive: self.pictureInPictureActive,
-                    state: self.state
-                )
-                switch Self.backgroundStep(
-                    action: action,
-                    state: self.state,
-                    supportsGraceWindow: supportsGrace,
-                    graceSeconds: self.backgroundTeardownGraceSeconds
-                ) {
-                case .perform(.doNothing):
-                    return
-                case .perform(.enterSoftwareAudioOnly):
-                    self.softwareHost?.enterBackgroundAudioOnly()
-                case .perform(.teardownVideo):
-                    await self.teardownVideoForBackground()
-                case .deferTeardown(let seconds):
-                    #if os(iOS)
-                    self.scheduleBackgroundGraceTeardown(afterSeconds: seconds)
-                    #endif
-                }
+                // Audit CORE-2: a load or seek in flight has a pipeline (loopback server, AVIO
+                // connection, the item) but no settled state to judge it by, and it settles into
+                // `.playing` in the background with nothing left to look again. Owe it the decision.
+                self.backgroundActionOwed = Self.backgroundActionIsOwed(state: self.state)
+                await self.applyBackgroundPolicy()
             }
         }
         lifecycleObservers.append(bgObserver)
@@ -6995,6 +6971,7 @@ public final class AetherEngine: ObservableObject {
                 let returnedFromBackground = self.isBackgrounded
                 self.isBackgrounded = false
                 if returnedFromBackground { Self.clearPanelRefusalOnForegroundReturn() }
+                self.backgroundActionOwed = false
             }
         }
         lifecycleObservers.append(fgObserver)
@@ -7109,6 +7086,65 @@ public final class AetherEngine: ObservableObject {
             category: .engine)
     }
 
+    /// What didEnterBackground does with the running session. Runs again when a load or seek that
+    /// was in flight at that moment settles while the app is still in the background (audit CORE-2).
+    private func applyBackgroundPolicy() async {
+        guard isBackgrounded else { return }
+        #if os(iOS)
+        // Keep the video pipeline alive for PiP / background audio while the app stays running.
+        // Wedge-safe: a pause while backgrounded tears down via pause(), so nothing crosses
+        // an idle suspension.
+        let keepAlive = Self.shouldKeepVideoAlive(enabled: backgroundPlaybackEnabled,
+                                                  pipActive: pictureInPictureActive,
+                                                  state: state)
+        let supportsGrace = true
+        #else
+        // tvOS: only an active PiP window defers the wedge-safe teardown (the system keeps the app
+        // running while its PiP window lives); no grace window, no background-audio case. The
+        // pictureInPictureActive didSet tears down the moment PiP ends while still backgrounded.
+        let keepAlive = Self.shouldKeepVideoAliveTV(enabled: backgroundPlaybackEnabled,
+                                                    pipActive: pictureInPictureActive)
+        let supportsGrace = false
+        #endif
+        let action = Self.backgroundAction(
+            isAudioBackend: audioAVPlayerActive || audioHost != nil,
+            hasSoftwareHost: softwareHost != nil,
+            keepVideoAlive: keepAlive,
+            pipActive: pictureInPictureActive,
+            state: state
+        )
+        switch Self.backgroundStep(
+            action: action,
+            state: state,
+            supportsGraceWindow: supportsGrace,
+            graceSeconds: backgroundTeardownGraceSeconds
+        ) {
+        case .perform(.doNothing):
+            return
+        case .perform(.enterSoftwareAudioOnly):
+            softwareHost?.enterBackgroundAudioOnly()
+        case .perform(.teardownVideo):
+            await teardownVideoForBackground()
+        case .deferTeardown(let seconds):
+            #if os(iOS)
+            scheduleBackgroundGraceTeardown(afterSeconds: seconds)
+            #endif
+        }
+    }
+
+    /// Audit CORE-2: called from the `state` didSet. A load or seek that was in flight when the app
+    /// went to the background gets the background decision once it settles into a transport state.
+    private func settleOwedBackgroundAction() {
+        guard backgroundActionOwed, !Self.backgroundActionIsOwed(state: state) else { return }
+        backgroundActionOwed = false
+        guard isBackgrounded, state == .playing || state == .paused else { return }
+        EngineLog.emit(
+            "[AetherEngine] background: the load or seek in flight at didEnterBackground settled "
+            + "(state=\(state)); applying the background policy now (audit CORE-2)",
+            category: .engine)
+        Task { @MainActor [weak self] in await self?.applyBackgroundPolicy() }
+    }
+
     private func teardownVideoForBackground() async {
         let app = UIApplication.shared
         let bgTask = app.beginBackgroundTask(withName: "AetherEngine.bgVideoTeardown")
diff --git a/Tests/AetherEngineTests/BackgroundKeepaliveTests.swift b/Tests/AetherEngineTests/BackgroundKeepaliveTests.swift
index 1972f0e37..451d8041a 100644
--- a/Tests/AetherEngineTests/BackgroundKeepaliveTests.swift
+++ b/Tests/AetherEngineTests/BackgroundKeepaliveTests.swift
@@ -49,9 +49,24 @@ struct BackgroundKeepaliveTests {
         #expect(AetherEngine.backgroundAction(isAudioBackend: false, hasSoftwareHost: true, keepVideoAlive: false, pipActive: false, state: .paused) == .teardownVideo)
     }
 
-    @Test("do nothing when idle or loading (nothing to tear down)")
-    func doNothingWhenNotPlayable() {
+    /// Audit CORE-2: a load or seek in flight DOES have a pipeline (loopback server, AVIO connection,
+    /// the item). It is not torn down mid-flight, it is judged once it settles, and that judgement is
+    /// owed rather than skipped: a load finishing after the TV button used to start playing in the
+    /// background and cross the suspension whole.
+    @Test("a load or seek in flight is not torn down mid-flight, the decision is owed until it settles")
+    func loadOrSeekInFlightOwesTheDecision() {
         #expect(AetherEngine.backgroundAction(isAudioBackend: false, hasSoftwareHost: false, keepVideoAlive: false, pipActive: false, state: .loading) == .doNothing)
+        #expect(AetherEngine.backgroundAction(isAudioBackend: false, hasSoftwareHost: false, keepVideoAlive: false, pipActive: false, state: .seeking) == .doNothing)
+        #expect(AetherEngine.backgroundActionIsOwed(state: .loading))
+        #expect(AetherEngine.backgroundActionIsOwed(state: .seeking))
+    }
+
+    @Test("a settled or idle session owes nothing")
+    func settledStatesOweNothing() {
+        #expect(AetherEngine.backgroundAction(isAudioBackend: false, hasSoftwareHost: false, keepVideoAlive: false, pipActive: false, state: .idle) == .doNothing)
+        for state: PlaybackState in [.idle, .playing, .paused, .ended, .error("x")] {
+            #expect(!AetherEngine.backgroundActionIsOwed(state: state))
+        }
     }
 
     @Test("tvOS: an active PiP window keeps the video pipeline alive")

From 1b09bd3cfd187e6688bafc1cc1f898c4de6c10da Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 05:15:55 +0200
Subject: [PATCH 043/359] fix(engine): a second background teardown keeps the
 selection the first one parked (audit CORE-3)

On iOS a `pause()` while backgrounded re-arms the #127 grace window after the first teardown, and
its expiry captured the selection again from a session `stopInternal` had already wiped, replacing
the parked audio pick, subtitle pick and disc title with nothing (the #357 symptom through a second
door). The capture now merges the live read over what is parked, the same rule the reload applies
when it claims it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 .../BackgroundTeardownSelection.swift         | 16 ++++++++------
 ...e357BackgroundTeardownSelectionTests.swift | 21 +++++++++++++++++++
 2 files changed, 31 insertions(+), 6 deletions(-)

diff --git a/Sources/AetherEngine/BackgroundTeardownSelection.swift b/Sources/AetherEngine/BackgroundTeardownSelection.swift
index aa2e4603a..314e54ffb 100644
--- a/Sources/AetherEngine/BackgroundTeardownSelection.swift
+++ b/Sources/AetherEngine/BackgroundTeardownSelection.swift
@@ -19,12 +19,12 @@ extension AetherEngine {
 
     /// Park the current selection for the reload that follows this teardown. Called by both #127
     /// teardown paths (grace expiry and the synchronous assertion backstop) BEFORE `stopInternal`.
+    ///
+    /// Audit CORE-3: merged over what is already parked rather than replacing it. A second teardown
+    /// before the reload claims the first (an iOS `pause()` while backgrounded re-arms the grace
+    /// window) reads a session `stopInternal` has already wiped, and used to park that emptiness.
     func captureBackgroundTeardownSelection() {
-        backgroundTeardownSelection = BackgroundTeardownSelection(
-            subtitles: captureSubtitleSessionCarryover(),
-            audioTrackIndex: activeAudioTrackIndex,
-            discTitleID: activeDiscTitleID
-        )
+        backgroundTeardownSelection = liveSelection(over: backgroundTeardownSelection)
     }
 
     /// The selection a session-preserving reload must restore, claiming any parked teardown
@@ -32,7 +32,11 @@ extension AetherEngine {
     func consumeReloadSelection() -> BackgroundTeardownSelection {
         let parked = backgroundTeardownSelection
         backgroundTeardownSelection = nil
-        return BackgroundTeardownSelection(
+        return liveSelection(over: parked)
+    }
+
+    private func liveSelection(over parked: BackgroundTeardownSelection?) -> BackgroundTeardownSelection {
+        BackgroundTeardownSelection(
             subtitles: Self.mergedSubtitleCarryover(
                 live: captureSubtitleSessionCarryover(), snapshot: parked?.subtitles),
             audioTrackIndex: activeAudioTrackIndex ?? parked?.audioTrackIndex,
diff --git a/Tests/AetherEngineTests/Issue357BackgroundTeardownSelectionTests.swift b/Tests/AetherEngineTests/Issue357BackgroundTeardownSelectionTests.swift
index 888915379..9c7523542 100644
--- a/Tests/AetherEngineTests/Issue357BackgroundTeardownSelectionTests.swift
+++ b/Tests/AetherEngineTests/Issue357BackgroundTeardownSelectionTests.swift
@@ -86,6 +86,27 @@ struct Issue357BackgroundTeardownSelectionTests {
         #expect(selection.subtitles.reapplyOrdinalMatchesActiveTrack)
     }
 
+    /// Audit CORE-3: on iOS a `pause()` while backgrounded re-arms the grace window after the first
+    /// teardown, and its expiry tears down again. That second capture reads what `stopInternal`
+    /// already wiped and used to replace the good snapshot with it.
+    @Test("a second teardown before the reload keeps the selection the first one parked")
+    func secondTeardownKeepsParkedSelection() throws {
+        let engine = try AetherEngine()
+        let track = engine.addExternalSubtitleTrack(makeTrack("picked"))
+        engine.selectSubtitleTrack(index: track.id)
+        engine.activeAudioTrackIndex = 2
+        engine.activeDiscTitleID = 7
+
+        backgroundTeardown(engine)
+        backgroundTeardown(engine)
+
+        let selection = engine.consumeReloadSelection()
+        #expect(selection.subtitles.activeSubtitleTrackIndex == track.id)
+        #expect(selection.subtitles.hostExplicitSubtitleAction)
+        #expect(selection.audioTrackIndex == 2)
+        #expect(selection.discTitleID == 7)
+    }
+
     @Test("a pick made after the teardown is newer intent and wins over the snapshot")
     func newerIntentWins() throws {
         let engine = try AetherEngine()

From 52191c8af29c246ade0804229ca5ff5523e5497f Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 05:17:48 +0200
Subject: [PATCH 044/359] fix(engine): a media services reset rebuilds the
 audio-only AVPlayer as well as the video one (audit CORE-4)

The AE#597 reset flag only stopped the load from preserving the native video host. The audio-only
AVPlayer host is kept across every teardown on purpose (its MPNowPlayingSession persists between
tracks), was never released anywhere, and so music after a reset went to an AVPlayer the platform
had already invalidated. The first load of any kind also cleared the flag without acting on it.

The load that consumes the reset now stops and drops the audio-only host as well, whatever that
load plays, and the next audio load builds a fresh one with a fresh Now Playing session. The reset
log line no longer claims a rebuild that did not happen.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 Sources/AetherEngine/AetherEngine.swift       | 22 +++++++++++--
 .../Issue597MediaServicesResetTests.swift     | 31 +++++++++++++++++++
 2 files changed, 51 insertions(+), 2 deletions(-)

diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index 055cc8fea..a961d36ce 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -975,7 +975,8 @@ public final class AetherEngine: ObservableObject {
         mediaServicesResetPending = true
         EngineLog.emit(
             "[AetherEngine] #597 media services were \(lost ? "lost" : "reset"): every audio and "
-            + "video object this process holds is invalid, so the next load builds a fresh host",
+            + "video object this process holds is invalid, so the next load builds fresh native and "
+            + "audio-only players",
             category: .engine)
     }
 
@@ -985,6 +986,21 @@ public final class AetherEngine: ObservableObject {
         return pending
     }
 
+    /// Audit CORE-4: the audio-only AVPlayer host is kept across every `stopInternal` on purpose (its
+    /// MPNowPlayingSession must persist between tracks), so after a reset nothing ever replaced it and
+    /// the next track was handed to a dead AVPlayer. Any load consumes the reset, so it is dropped
+    /// here whatever that load plays; the next audio load builds a fresh one with a fresh session.
+    func dropAudioPlayerHostAfterMediaServicesReset() {
+        guard let host = audioAVPlayerHost else { return }
+        host.stop()
+        audioAVPlayerHost = nil
+        audioAVPlayerActive = false
+        EngineLog.emit(
+            "[AetherEngine] #597 audio-only AVPlayer dropped after the media services reset; the next "
+            + "audio load builds a fresh one",
+            category: .engine)
+    }
+
     /// Consume the one-shot host request at the load boundary, folded with PiP's mandatory handover.
     /// Consumed here rather than where it is read so one episode transition cannot change the
     /// teardown of a later, unrelated load.
@@ -3660,9 +3676,10 @@ public final class AetherEngine: ObservableObject {
         // registration survives the seam (issue #15). Captured before stopInternal resets playbackBackend;
         // the SW dispatch branch releases it if this source routes software.
         let priorBackendWasNative = (playbackBackend == .native)
+        let mediaServicesWereReset = consumeMediaServicesReset()
         let preserveNativeHost = Self.shouldPreserveNativeHostAcrossLoad(
             backend: playbackBackend, nativeHostSurvives: nativeHost != nil,
-            mediaServicesWereReset: consumeMediaServicesReset())
+            mediaServicesWereReset: mediaServicesWereReset)
         // AE#158: while a PiP window is live, or when the host asked for it, the running item must
         // survive this load's teardown; the loopback host.load callsite finishes the handover
         // (inPlaceSwap). The host request is consumed here so it can affect only this load. The
@@ -3675,6 +3692,7 @@ public final class AetherEngine: ObservableObject {
         // reloads. Sessions that never reach apply() clear a stale criteria via loadDisplayCriteriaAction
         // (audio-only fast path, suppressed hosts); a load() that throws before routing leaves it for stop().
         stopInternal(resetDisplayCriteria: false, keepNativeHost: preserveNativeHost, keepCurrentItem: handOverInPlace)
+        if mediaServicesWereReset { dropAudioPlayerHostAfterMediaServicesReset() }
         // #35/#93: a genuinely new item has not rendered yet; re-arm the cold-startup wedge suspension.
         // Scrub/seek/producer-restart never route through load(), so mid-stream #93 detection stays armed.
         hasRenderedFirstFrameMirror.set(false)
diff --git a/Tests/AetherEngineTests/Issue597MediaServicesResetTests.swift b/Tests/AetherEngineTests/Issue597MediaServicesResetTests.swift
index 8ecb0da31..64e2708dd 100644
--- a/Tests/AetherEngineTests/Issue597MediaServicesResetTests.swift
+++ b/Tests/AetherEngineTests/Issue597MediaServicesResetTests.swift
@@ -1,3 +1,4 @@
+import Foundation
 import Testing
 @testable import AetherEngine
 
@@ -29,4 +30,34 @@ struct Issue597MediaServicesResetTests {
         #expect(!AetherEngine.shouldPreserveNativeHostAcrossLoad(
             backend: .software, nativeHostSurvives: true, mediaServicesWereReset: true))
     }
+
+    private static let missingSource = URL(fileURLWithPath: "/nonexistent/aether-597-reset.m4a")
+
+    /// Audit CORE-4: the audio-only host is kept across every teardown so its Now Playing session
+    /// persists between tracks, and the reset only ever dropped the video host. Music after a reset
+    /// went to the dead AVPlayer, and the first load of any kind cleared the flag.
+    @Test("the load that consumes a reset drops the audio-only player too")
+    @MainActor
+    func resetDropsTheAudioOnlyPlayer() async throws {
+        let engine = try AetherEngine()
+        engine.audioAVPlayerHost = AudioAVPlayerHost()
+        engine.noteMediaServicesReset(lost: false)
+
+        _ = try? await engine.load(url: Self.missingSource)
+
+        #expect(engine.audioAVPlayerHost == nil)
+        #expect(!engine.consumeMediaServicesReset())
+    }
+
+    @Test("without a reset the audio-only player survives a load, as its Now Playing session must")
+    @MainActor
+    func audioOnlyPlayerSurvivesWithoutAReset() async throws {
+        let engine = try AetherEngine()
+        let host = AudioAVPlayerHost()
+        engine.audioAVPlayerHost = host
+
+        _ = try? await engine.load(url: Self.missingSource)
+
+        #expect(engine.audioAVPlayerHost === host)
+    }
 }

From d8c3fbaed2455db392759bfce53914ddd545ddc1 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 05:19:37 +0200
Subject: [PATCH 045/359] fix(recording): a late failure of the previous
 recording no longer ends the next one (audit CORE-5)

The writer reports a failure from its teardown queue, after draining and writing the trailer, and
`recordingDidFail` only checked that some recording was running. A recording that failed as the
viewer zapped could therefore land its report after the host had started the next one, which was
then ended without a trailer and reported with the previous recording's reason. The failure
handler is now bound to the recording it was built for, and a report from an earlier one is
logged and ignored.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 .../AetherEngine/AetherEngine+Recording.swift | 29 ++++++++++++-----
 Sources/AetherEngine/AetherEngine.swift       |  3 ++
 .../LiveRecordingAPITests.swift               | 32 +++++++++++++++++++
 3 files changed, 56 insertions(+), 8 deletions(-)

diff --git a/Sources/AetherEngine/AetherEngine+Recording.swift b/Sources/AetherEngine/AetherEngine+Recording.swift
index 968e9be0c..1db408d80 100644
--- a/Sources/AetherEngine/AetherEngine+Recording.swift
+++ b/Sources/AetherEngine/AetherEngine+Recording.swift
@@ -40,9 +40,7 @@ public extension AetherEngine {
             url: url,
             streams: descriptors,
             ceilingBytes: Self.recordingQueueCeilingBytes,
-            onFailure: { [weak self] failure in
-                Task { @MainActor in self?.recordingDidFail(failure) }
-            }
+            onFailure: makeRecordingFailureHandler()
         )
 
         activeRecording = writer
@@ -107,9 +105,26 @@ extension AetherEngine {
         recordingState = .ended(reason)
     }
 
+    /// The writer's failure callback, bound to the recording it is built for. The writer reports
+    /// from its teardown queue after draining and writing the trailer, so the report of a recording
+    /// that has already ended can land after the next one started (a zap with auto-record). Without
+    /// the binding it ended that next recording, unfinalized, with the previous one's reason
+    /// (audit CORE-5).
+    func makeRecordingFailureHandler() -> @Sendable (RecordingFailure) -> Void {
+        recordingGeneration &+= 1
+        let generation = recordingGeneration
+        return { [weak self] failure in
+            Task { @MainActor in self?.recordingDidFail(failure, generation: generation) }
+        }
+    }
+
     /// Called from the writer's failure callback, already hopped to the main actor.
-    func recordingDidFail(_ failure: RecordingFailure) {
-        guard activeRecording != nil else { return }
+    func recordingDidFail(_ failure: RecordingFailure, generation: UInt64) {
+        guard activeRecording != nil, generation == recordingGeneration else {
+            EngineLog.emit("[Recording] failure of an earlier recording ignored: \(failure)",
+                           category: .session)
+            return
+        }
         (activeRecordingHost as? LiveRecordingHost)?.setRecordingSink(nil)
         activeRecordingHost = nil
         activeRecording = nil
@@ -194,9 +209,7 @@ extension AetherEngine {
             url: url,
             streams: host.recordingStreamDescriptors(),
             ceilingBytes: Self.recordingQueueCeilingBytes,
-            onFailure: { [weak self] failure in
-                Task { @MainActor in self?.recordingDidFail(failure) }
-            }
+            onFailure: makeRecordingFailureHandler()
         )
         activeRecording = writer
         activeRecordingHost = host
diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index a961d36ce..0f57f358d 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -1320,6 +1320,9 @@ public final class AetherEngine: ObservableObject {
     /// producer or software host is owned by its session and may be torn down under us.
     weak var activeRecordingHost: AnyObject?
 
+    /// Which recording a writer failure belongs to (audit CORE-5). Bumped once per writer.
+    var recordingGeneration: UInt64 = 0
+
     /// Republishes `recordingState` progress at 1 Hz while a recording runs.
     var recordingProgressTimer: Timer?
 
diff --git a/Tests/AetherEngineTests/LiveRecordingAPITests.swift b/Tests/AetherEngineTests/LiveRecordingAPITests.swift
index 480f2c38e..985a9de83 100644
--- a/Tests/AetherEngineTests/LiveRecordingAPITests.swift
+++ b/Tests/AetherEngineTests/LiveRecordingAPITests.swift
@@ -105,4 +105,36 @@ struct LiveRecordingAPITests {
         await engine.stopRecording()
         #expect(engine.recordingState == .ended(.stoppedByHost))
     }
+
+    /// Audit CORE-5: the writer reports a failure from its teardown queue, after the host may have
+    /// ended that recording and started the next.
+    @Test("a late failure of the previous recording does not end the next one")
+    func staleFailureDoesNotEndTheNextRecording() async throws {
+        let engine = try AetherEngine()
+        let host = AetherEngine.TestRecordingHost()
+        let first = tempURL()
+        let second = tempURL()
+        defer {
+            try? FileManager.default.removeItem(at: first)
+            try? FileManager.default.removeItem(at: second)
+        }
+
+        try engine._testStartRecordingWithStubHost(to: first, host: host)
+        let firstGeneration = engine.recordingGeneration
+        engine.endRecordingIfRunning(reason: .sessionEnded)
+        try engine._testStartRecordingWithStubHost(to: second, host: host)
+        let running = engine.activeRecording
+
+        engine.recordingDidFail(.writeTooSlow(bytesWritten: 1, queuedBytesDropped: 1),
+                                generation: firstGeneration)
+        #expect(engine.activeRecording === running)
+        #expect(host.installedSink != nil)
+        #expect({ if case .recording = engine.recordingState { return true }; return false }())
+
+        engine.recordingDidFail(.writeTooSlow(bytesWritten: 1, queuedBytesDropped: 1),
+                                generation: engine.recordingGeneration)
+        #expect(engine.activeRecording == nil)
+        #expect(engine.recordingState == .failed(.writeTooSlow(bytesWritten: 1, queuedBytesDropped: 1)))
+        running?.finish(reason: .sessionEnded)
+    }
 }

From 022c194ed412eea316ee73e5d79df0bdfaa9ba18 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 05:20:22 +0200
Subject: [PATCH 046/359] fix(live): the live-only edge snap leaves the clock
 alone when a zap or scrub superseded it (audit CORE-7)

The live-only branch of seekToLiveEdge() awaited the native host's seek and then wrote the clock
unconditionally. The native host survives a native-to-native zap, so a snap raised on the old
channel (the resume-after-long-pause clamp fires it as a detached task) could finish against the
new one and publish the old channel's position as its currentTime and sourceTime. It now checks
the load and seek generations after the await, like every other seek path.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 Sources/AetherEngine/AetherEngine+Live.swift | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/Sources/AetherEngine/AetherEngine+Live.swift b/Sources/AetherEngine/AetherEngine+Live.swift
index 7f8101b60..20b8bdc7b 100644
--- a/Sources/AetherEngine/AetherEngine+Live.swift
+++ b/Sources/AetherEngine/AetherEngine+Live.swift
@@ -731,7 +731,16 @@ extension AetherEngine {
                 "[AetherEngine] live-only edge snap: clockTarget=\(String(format: "%.1f", clockTarget))",
                 category: .engine
             )
+            let loadGen = loadGeneration
+            let seekGen = currentSeekGeneration
             await host.seek(to: clockTarget)
+            // Audit CORE-7: the native host survives a native-to-native zap, so this seek can finish
+            // against the next channel's item, and a scrub started meanwhile owns the clock too.
+            guard loadGeneration == loadGen, currentSeekGeneration == seekGen else {
+                EngineLog.emit("[AetherEngine] live-only edge snap superseded; clock left to the successor",
+                               category: .engine)
+                return
+            }
             nativeClockSeconds = clockTarget
             clock.currentTime = clockTarget + playlistShiftSeconds
             clock.sourceTime = currentTime

From 5c1a6fb6e5f2fb3845efc378ee7307ee2acc8a4f Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 05:23:22 +0200
Subject: [PATCH 047/359] fix(native): injected subtitle renditions are
 selected by the NAME the master declares, and a name cannot write master
 lines (audit NAT-2, NAT-6)

The remote-HLS master rewriter writes a sidecar's NAME disambiguated (against the origin's names
and earlier sidecars) and escaped, but the engine keyed the injected renditions on the raw name
the track asked for. Two sidecars both called "English", or one sharing a name with an origin
rendition, selected the wrong option and hid the origin's own track from the list; a name with a
`"` in it could not be selected at all. The rewriter now hands back the exact NAME it wrote for
each rendition, one string across every group, and the engine keys on those.

The escaping only replaced `"`. A CR/LF (or U+2028, U+0085, any control character) in a
host-supplied name or language ended the `#EXT-X-MEDIA` tag and let the rest of the string write
its own master lines, a variant pointing anywhere included. Those scalars now become spaces.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 .../AetherEngine/AetherEngine+Loading.swift   |  6 +-
 .../AetherEngine/AetherEngine+Subtitles.swift |  5 +-
 .../Native/RemoteHLSMasterRewrite.swift       | 80 ++++++++++++++-----
 .../Native/RemoteHLSSubtitleProxy.swift       |  8 +-
 .../RemoteHLSMasterRewriteTests.swift         | 58 ++++++++++++++
 5 files changed, 131 insertions(+), 26 deletions(-)

diff --git a/Sources/AetherEngine/AetherEngine+Loading.swift b/Sources/AetherEngine/AetherEngine+Loading.swift
index 70a22b7dd..40069dba8 100644
--- a/Sources/AetherEngine/AetherEngine+Loading.swift
+++ b/Sources/AetherEngine/AetherEngine+Loading.swift
@@ -644,10 +644,12 @@ extension AetherEngine {
             return nil
         }
         remoteHLSSubtitleProxy = prepared
+        // Audit NAT-2: the NAMEs the served master carries, which the selection and the legible-list
+        // filter match against, not the names the tracks asked for (the rewriter disambiguates and
+        // escapes them).
         injectedSubtitleRenditionNames = prepared.servesSubtitleRenditions
             ? Dictionary(
-                uniqueKeysWithValues: zip(tracks.map(\.externalID),
-                                          RemoteHLSSubtitleProvider.renditions(for: tracks).map(\.name)))
+                uniqueKeysWithValues: zip(tracks.map(\.externalID), prepared.renditionNames))
             : [:]
         #if os(iOS)
         // #86 / #227: a receiver cannot reach 127.0.0.1. Mounting while already AirPlaying has to hand out
diff --git a/Sources/AetherEngine/AetherEngine+Subtitles.swift b/Sources/AetherEngine/AetherEngine+Subtitles.swift
index 69e8dfaef..c9f18f626 100644
--- a/Sources/AetherEngine/AetherEngine+Subtitles.swift
+++ b/Sources/AetherEngine/AetherEngine+Subtitles.swift
@@ -2544,8 +2544,9 @@ extension AetherEngine {
     /// the host registered it under, but the selection is an `AVMediaSelection` one, so AVPlayer renders
     /// it and it survives leaving the view hierarchy.
     ///
-    /// Matched by NAME: the rewriter guarantees uniqueness within the group (it disambiguates against the
-    /// origin's own names), and `AVMediaSelectionOption.displayName` is the rendition's NAME attribute.
+    /// Matched by NAME: `name` is the one the served master declares (`RemoteHLSMasterRewrite`
+    /// disambiguates it against the origin's names and every other sidecar, and escapes it), and
+    /// `AVMediaSelectionOption.displayName` is the rendition's NAME attribute.
     /// A miss leaves the previous selection alone and says so rather than silently reporting success.
     func selectInjectedSubtitleRendition(id: Int, name: String) {
         guard let item = currentAVPlayer?.currentItem else { return }
diff --git a/Sources/AetherEngine/Native/RemoteHLSMasterRewrite.swift b/Sources/AetherEngine/Native/RemoteHLSMasterRewrite.swift
index 1530bbc31..15d14118c 100644
--- a/Sources/AetherEngine/Native/RemoteHLSMasterRewrite.swift
+++ b/Sources/AetherEngine/Native/RemoteHLSMasterRewrite.swift
@@ -59,14 +59,36 @@ enum RemoteHLSMasterRewrite {
                         originURL: URL,
                         renditions: [Rendition],
                         mediaPlaylistBandwidth: Int = 5_000_000) throws -> String {
+        try rewriteDeclaringNames(originPlaylist: originPlaylist, originURL: originURL,
+                                  renditions: renditions,
+                                  mediaPlaylistBandwidth: mediaPlaylistBandwidth).master
+    }
+
+    /// The rewritten master, and the NAME it declares for each rendition, in `renditions` order.
+    struct Rewritten: Equatable, Sendable {
+        var master: String
+        var renditionNames: [String]
+    }
+
+    /// `rewrite`, also answering with the exact NAME each rendition was written under. The engine
+    /// selects an injected rendition by that NAME and hides it from the legible list by it, so it has
+    /// to key on what the master says, not on the name it asked for (audit NAT-2): a sidecar that
+    /// repeats another's name, or the origin's, is written with a disambiguator.
+    static func rewriteDeclaringNames(originPlaylist: String,
+                                      originURL: URL,
+                                      renditions: [Rendition],
+                                      mediaPlaylistBandwidth: Int = 5_000_000) throws -> Rewritten {
         guard !renditions.isEmpty else { throw Refusal.noRenditions }
         let lines = originPlaylist.components(separatedBy: .newlines)
         guard lines.contains(where: { $0.trimmingCharacters(in: .whitespaces).hasPrefix("#EXTM3U") }) else {
             throw Refusal.notAPlaylist
         }
         guard lines.contains(where: { $0.hasPrefix("#EXT-X-STREAM-INF:") }) else {
-            return wrapMediaPlaylist(originURL: originURL, renditions: renditions,
-                                     bandwidth: mediaPlaylistBandwidth)
+            let names = declaredNames(for: renditions, taken: [])
+            return Rewritten(
+                master: wrapMediaPlaylist(originURL: originURL, renditions: renditions, names: names,
+                                          bandwidth: mediaPlaylistBandwidth),
+                renditionNames: names)
         }
         return try rewriteMaster(lines: lines, originURL: originURL, renditions: renditions)
     }
@@ -75,20 +97,19 @@ enum RemoteHLSMasterRewrite {
 
     private static func rewriteMaster(lines: [String],
                                       originURL: URL,
-                                      renditions: [Rendition]) throws -> String {
+                                      renditions: [Rendition]) throws -> Rewritten {
         // Which groups the injected renditions have to join: every SUBTITLES group the origin declares
         // (a variant references exactly one, and different variants may reference different ones), plus
         // our own group if any variant references none.
         var originGroups: [String] = []
-        var namesPerGroup: [String: Set<String>] = [:]
+        var originNames: Set<String> = []
         for line in lines where line.hasPrefix("#EXT-X-MEDIA:") {
             guard HLSPlaylistParser.attribute("TYPE", in: line) == "SUBTITLES",
                   let group = HLSPlaylistParser.attribute("GROUP-ID", in: line) else { continue }
             if !originGroups.contains(group) { originGroups.append(group) }
-            if let name = HLSPlaylistParser.attribute("NAME", in: line) {
-                namesPerGroup[group, default: []].insert(name)
-            }
+            if let name = HLSPlaylistParser.attribute("NAME", in: line) { originNames.insert(name) }
         }
+        let names = declaredNames(for: renditions, taken: originNames)
         let variantsWithoutGroup = lines.contains {
             $0.hasPrefix("#EXT-X-STREAM-INF:") && HLSPlaylistParser.attribute("SUBTITLES", in: $0) == nil
         }
@@ -113,8 +134,8 @@ enum RemoteHLSMasterRewrite {
                 // The renditions have to be declared before the first variant references their group.
                 if !injected {
                     out.append(contentsOf: mediaTags(renditions: renditions,
-                                                     groups: targetGroups,
-                                                     takenNames: namesPerGroup))
+                                                     names: names,
+                                                     groups: targetGroups))
                     injected = true
                 }
                 out.append(withSubtitlesGroup(trimmed))
@@ -124,7 +145,7 @@ enum RemoteHLSMasterRewrite {
             out.append(rewriteURIAttribute(in: line, against: originURL))
         }
         guard sawVariantURI else { throw Refusal.masterWithoutVariants }
-        return out.joined(separator: "\n") + "\n"
+        return Rewritten(master: out.joined(separator: "\n") + "\n", renditionNames: names)
     }
 
     /// A variant that already names a SUBTITLES group keeps it (the injected renditions joined that
@@ -138,11 +159,12 @@ enum RemoteHLSMasterRewrite {
 
     private static func wrapMediaPlaylist(originURL: URL,
                                           renditions: [Rendition],
+                                          names: [String],
                                           bandwidth: Int) -> String {
         var lines = ["#EXTM3U", "#EXT-X-INDEPENDENT-SEGMENTS"]
         lines.append(contentsOf: mediaTags(renditions: renditions,
-                                           groups: [injectedGroupID],
-                                           takenNames: [:]))
+                                           names: names,
+                                           groups: [injectedGroupID]))
         lines.append("#EXT-X-STREAM-INF:BANDWIDTH=\(bandwidth),SUBTITLES=\"\(injectedGroupID)\"")
         lines.append(originURL.absoluteString)
         return lines.joined(separator: "\n") + "\n"
@@ -156,14 +178,12 @@ enum RemoteHLSMasterRewrite {
     /// rendition whose language matches the selected audio regardless of the user's caption preference
     /// (Sodalite#38). `isForced` still rides the published `TrackInfo` so a host can label and pick it.
     private static func mediaTags(renditions: [Rendition],
-                                  groups: [String],
-                                  takenNames: [String: Set<String>]) -> [String] {
+                                  names: [String],
+                                  groups: [String]) -> [String] {
         var tags: [String] = []
         for group in groups {
-            var used = takenNames[group] ?? []
-            for rendition in renditions {
-                let name = uniqueName(rendition.name, in: &used)
-                var attrs = ["TYPE=SUBTITLES", "GROUP-ID=\"\(group)\"", "NAME=\"\(escaped(name))\""]
+            for (rendition, name) in zip(renditions, names) {
+                var attrs = ["TYPE=SUBTITLES", "GROUP-ID=\"\(group)\"", "NAME=\"\(name)\""]
                 if let language = rendition.language, !language.isEmpty {
                     attrs.append("LANGUAGE=\"\(escaped(language))\"")
                 }
@@ -181,7 +201,14 @@ enum RemoteHLSMasterRewrite {
 
     /// NAMEs must be unique within a group or AVFoundation collapses the legible options into one. The
     /// origin's own names are already taken, so a sidecar that repeats one gets a numeric disambiguator
-    /// rather than silently disappearing from the picker.
+    /// rather than silently disappearing from the picker. One name per rendition across every group,
+    /// taken against the origin names of all of them, so the engine can select it by that one string;
+    /// uniqueness is decided on the escaped form, which is the one the master carries.
+    private static func declaredNames(for renditions: [Rendition], taken: Set<String>) -> [String] {
+        var used = taken
+        return renditions.map { uniqueName(escaped($0.name), in: &used) }
+    }
+
     private static func uniqueName(_ preferred: String, in used: inout Set<String>) -> String {
         let base = preferred.isEmpty ? "Subtitle" : preferred
         if !used.contains(base) {
@@ -196,8 +223,21 @@ enum RemoteHLSMasterRewrite {
     }
 
     /// Quoted attribute values cannot carry a `"`; a name that contains one would truncate the tag.
+    /// Nor a line break or any other control character (audit NAT-6): a sidecar name is host input,
+    /// often a file name or server metadata, and a CR/LF in it would end the tag and let the rest of
+    /// the name write its own master lines, a variant included. Mapped per scalar, because CRLF is a
+    /// single Character and a Character-level test would let it through as one.
     private static func escaped(_ value: String) -> String {
-        value.replacingOccurrences(of: "\"", with: "'")
+        var out = String.UnicodeScalarView()
+        for scalar in value.unicodeScalars {
+            switch scalar.properties.generalCategory {
+            case .control, .lineSeparator, .paragraphSeparator:
+                out.append(" ")
+            default:
+                out.append(scalar == "\"" ? "'" : scalar)
+            }
+        }
+        return String(out)
     }
 
     // MARK: - URI absolutisation
diff --git a/Sources/AetherEngine/Native/RemoteHLSSubtitleProxy.swift b/Sources/AetherEngine/Native/RemoteHLSSubtitleProxy.swift
index 2d064f2a0..7419b055b 100644
--- a/Sources/AetherEngine/Native/RemoteHLSSubtitleProxy.swift
+++ b/Sources/AetherEngine/Native/RemoteHLSSubtitleProxy.swift
@@ -25,6 +25,8 @@ enum RemoteHLSSubtitleProxy {
         let server: HLSLocalServer
         let provider: RemoteHLSSubtitleProvider?
         let masterURL: URL
+        /// The NAME the served master declares for each injected track, in track order (audit NAT-2).
+        var renditionNames: [String] = []
 
         /// False when the relay stands alone and nothing was injected.
         var servesSubtitleRenditions: Bool { provider != nil }
@@ -127,10 +129,11 @@ enum RemoteHLSSubtitleProxy {
         let duration = try await programDuration(of: parsed, at: finalURL,
                                                  session: session, headers: httpHeaders)
 
-        let master = try RemoteHLSMasterRewrite.rewrite(
+        let rewritten = try RemoteHLSMasterRewrite.rewriteDeclaringNames(
             originPlaylist: body,
             originURL: finalURL,
             renditions: RemoteHLSSubtitleProvider.renditions(for: tracks))
+        let master = rewritten.master
 
         let provider = RemoteHLSSubtitleProvider(tracks: tracks, masterBody: master,
                                                  programDuration: duration,
@@ -161,7 +164,8 @@ enum RemoteHLSSubtitleProxy {
         // Decode up front: the rendition is fetched the moment the host selects it, and a whole-program
         // .vtt is fetched once and never again.
         provider.startFill()
-        return Prepared(server: server, provider: provider, masterURL: masterURL)
+        return Prepared(server: server, provider: provider, masterURL: masterURL,
+                        renditionNames: rewritten.renditionNames)
     }
 
     // MARK: - Playlist reads
diff --git a/Tests/AetherEngineTests/RemoteHLSMasterRewriteTests.swift b/Tests/AetherEngineTests/RemoteHLSMasterRewriteTests.swift
index b15b847b7..b48fd5ad1 100644
--- a/Tests/AetherEngineTests/RemoteHLSMasterRewriteTests.swift
+++ b/Tests/AetherEngineTests/RemoteHLSMasterRewriteTests.swift
@@ -245,4 +245,62 @@ struct RemoteHLSMasterRewriteTests {
             originPlaylist: master, originURL: Self.origin, renditions: [Self.english])
         #expect(Self.lines(out).contains("https://cdn.test/other/main.m3u8"))
     }
+
+    // MARK: - Declared names (audit NAT-2)
+
+    private static func declaredNames(in master: String, uri: String) -> [String] {
+        lines(master).filter { $0.contains("URI=\"\(uri)\"") }
+            .compactMap { HLSPlaylistParser.attribute("NAME", in: $0) }
+    }
+
+    /// The engine selects an injected rendition by NAME and hides it from the legible list by NAME.
+    /// It used to key on the name the track asked for, so a disambiguated sidecar selected the
+    /// origin's rendition, and the origin's own track disappeared from the list.
+    @Test("The names handed back are exactly the ones the master declares, one per rendition in every group")
+    func declaredNamesMatchTheMaster() throws {
+        let out = try RemoteHLSMasterRewrite.rewriteDeclaringNames(
+            originPlaylist: Self.masterMixedGroups, originURL: Self.origin,
+            renditions: [Self.english,
+                         RemoteHLSMasterRewrite.Rendition(ordinal: 1, name: "English", language: "en"),
+                         RemoteHLSMasterRewrite.Rendition(ordinal: 2, name: "The \"Cut\"")])
+
+        #expect(out.renditionNames == ["English 2", "English 3", "The 'Cut'"])
+        for (ordinal, name) in out.renditionNames.enumerated() {
+            let declared = Self.declaredNames(in: out.master, uri: "subs_\(ordinal).m3u8")
+            #expect(declared == [name, name], "one NAME for the rendition in both groups")
+        }
+    }
+
+    @Test("A wrapped media playlist hands back its names too")
+    func wrappedPlaylistDeclaresNames() throws {
+        let media = "#EXTM3U\n#EXT-X-TARGETDURATION:6\n#EXTINF:6,\nseg0.ts\n#EXT-X-ENDLIST\n"
+        let out = try RemoteHLSMasterRewrite.rewriteDeclaringNames(
+            originPlaylist: media, originURL: Self.origin,
+            renditions: [Self.english,
+                         RemoteHLSMasterRewrite.Rendition(ordinal: 1, name: "English", language: "en")])
+        #expect(out.renditionNames == ["English", "English 2"])
+        #expect(Self.declaredNames(in: out.master, uri: "subs_1.m3u8") == ["English 2"])
+    }
+
+    // MARK: - Control characters (audit NAT-6)
+
+    /// A sidecar name is host input, typically a file name or server metadata. A line break in it
+    /// ended the tag, and the rest of the name wrote master lines of its own, a variant included.
+    @Test("A line break in a name or language cannot write a line into the master")
+    func lineBreaksCannotInjectLines() throws {
+        let hostile = "x\r\n#EXT-X-STREAM-INF:BANDWIDTH=1\r\nhttp://attacker.test/v.m3u8\n#"
+        let out = try RemoteHLSMasterRewrite.rewriteDeclaringNames(
+            originPlaylist: Self.master, originURL: Self.origin,
+            renditions: [RemoteHLSMasterRewrite.Rendition(
+                ordinal: 0, name: hostile, language: "en\u{2028}#EXT-X-ENDLIST\u{85}x")])
+
+        let all = Self.lines(out.master)
+        #expect(all.filter { $0.hasPrefix("#EXT-X-STREAM-INF:") }.count == 1)
+        #expect(!all.contains { $0.hasPrefix("http://attacker.test") })
+        #expect(!all.contains("#EXT-X-ENDLIST"))
+        #expect(all.filter { $0.hasPrefix("#EXT-X-MEDIA:") }.count == 1)
+        let name = try #require(out.renditionNames.first)
+        #expect(!name.unicodeScalars.contains { $0.properties.generalCategory == .control })
+        #expect(Self.declaredNames(in: out.master, uri: "subs_0.m3u8") == [name])
+    }
 }

From b34a47c7ea6c7db537ac3462adc529375b341bed Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 05:24:44 +0200
Subject: [PATCH 048/359] fix(native): the live-join buffer probe does not act
 on an item that replaced the one it read (audit NAT-4)

The AE#440 probe reads the item's buffer off the main actor and then decided on the state that
existed afterwards, without checking that it was still the same item. A load during the read had
reset the one-shot and the in-flight flag for the new item, so the stale reading could spend the
new item's one-shot and call playImmediately, and its defer cleared the new probe's in-flight
flag. The probe now drops out when the session moved, and after a swap it clears only its own
flag.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 Sources/AetherEngine/Native/NativeAVPlayerHost.swift | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/Sources/AetherEngine/Native/NativeAVPlayerHost.swift b/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
index 616889af3..75122fa6c 100644
--- a/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
+++ b/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
@@ -1278,10 +1278,16 @@ final class NativeAVPlayerHost {
         else { return }
         liveJoinImmediateStartProbeInFlight = true
         let probeStart = DispatchTime.now()
+        let sid = sessionID
         Task { @MainActor [weak self] in
             guard let self else { return }
-            defer { self.liveJoinImmediateStartProbeInFlight = false }
             let reading = await Self.liveJoinBufferReading(item)
+            // Audit NAT-4: a load during the read reset the one-shot and the in-flight flag for its own
+            // item, and a swap replaced the item this reading describes. Neither is this probe's to
+            // spend or clear.
+            guard self.sessionID == sid else { return }
+            self.liveJoinImmediateStartProbeInFlight = false
+            guard self.playerItem === item else { return }
             // AE#422: the reading is async, so the hold it described may be over. Decide on the state
             // that exists now, not on the edge that asked.
             guard !self.liveJoinImmediateStartSpent,

From aad577495119e4e7ab83981cb1de37ea33c30d13 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 05:27:29 +0200
Subject: [PATCH 049/359] docs(changelog): audit network security fixes

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 CHANGELOG.md | 21 ++++++++++++++++++++-
 1 file changed, 20 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b8a9324f2..9ca7830a6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,7 +10,26 @@ the public-API contract.
 
 ## [Unreleased]
 
-_Nothing yet._
+### Security
+
+- **The origin relay no longer writes the media server's access token into its local URLs.** They
+  name the origin by a per-session sealed reference, so the token no longer reaches the request
+  log, `load url=` lines, rewritten playlists or an AirPlay receiver (audit NET-1).
+- **Log redaction also catches credentials that are percent-encoded, or encoded twice, inside
+  another URL.** `api%5Fkey%3D...` is now stripped the same as `api_key=...` (audit NET-1).
+- **Credential headers stay with the host's own origin when a playlist names another host or drops
+  to http.** Other headers still go everywhere, the same rule redirects already follow (audit NET-7).
+- **A LAN peer can no longer hold the loopback server's connection slots.** Connections without the
+  session token must send a request head within 10 s, and LAN peers are held to 24 of the 32 slots
+  (audit NET-6).
+
+### Fixed
+
+- **Playlist and held relay bodies are capped while they download, not after.** A runaway origin can
+  no longer grow one until the app is killed (audit NET-10).
+- **The accept loop backs off when the process runs out of file descriptors**, instead of spinning a
+  core and flooding the log (audit NET-13).
+- **The server's stop line names the port it released** (audit NET-12).
 
 ## [7.16.1] - 2026-09-24
 

From e202c2869a0565e7d05aea48cc96a0aa2e4f266b Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 05:36:52 +0200
Subject: [PATCH 050/359] fix(hls): ignore the exit of a producer the session
 already replaced (audit HLS-1)

The #79 wedge abort and stop() both markClosed a pump's demuxer mid-read, and the
aborted read came back as .readError. handlePumpFinished had no currency check on
the VOD arms, so that exit spent the session-lifetime read-error revive gate,
marked the fresh demuxer suspect, queued an authoritative restart at the stale
position (emitting unscoped seek-state signals), and on the third wedge failed a
healthy session with "Source read failed". A superseded producer's exit is now
ignored, and a read error after a stop request is reported as .stopRequested.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 .../Video/HLSSegmentProducer.swift            |  5 ++
 .../Video/HLSVideoEngine+LiveReopen.swift     | 15 ++++
 .../SupersededPumpExitTests.swift             | 84 +++++++++++++++++++
 3 files changed, 104 insertions(+)
 create mode 100644 Tests/AetherEngineTests/SupersededPumpExitTests.swift

diff --git a/Sources/AetherEngine/Video/HLSSegmentProducer.swift b/Sources/AetherEngine/Video/HLSSegmentProducer.swift
index 6f4eebd90..3c09a3097 100644
--- a/Sources/AetherEngine/Video/HLSSegmentProducer.swift
+++ b/Sources/AetherEngine/Video/HLSSegmentProducer.swift
@@ -4049,6 +4049,11 @@ final class HLSSegmentProducer: @unchecked Sendable {
                 lastError = -1
                 exitReason = .readError(code: -1)
             }
+            // Audit HLS-1: a stop aborts a parked read through markClosed, which surfaces here.
+            stateLock.lock()
+            let stopped = shouldStop
+            stateLock.unlock()
+            if stopped { exitReason = .stopRequested }
             EngineLog.emit(
                 "[HLSSegmentProducer] demuxer.readPacket threw: \(error)",
                 category: .session
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine+LiveReopen.swift b/Sources/AetherEngine/Video/HLSVideoEngine+LiveReopen.swift
index 617085ea9..44ceb208b 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine+LiveReopen.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine+LiveReopen.swift
@@ -167,6 +167,21 @@ extension HLSVideoEngine {
 
     func handlePumpFinished(_ prod: HLSSegmentProducer,
                                     reason: HLSSegmentProducer.PumpExitReason) {
+        // Audit HLS-1: a superseded pump (the #79 markClosed of a wedged read, or stop()) reports
+        // an aborted read as `.readError`. Acting on it spent the session-lifetime revive gate,
+        // doomed the replacement demuxer and queued an authoritative restart at a stale position.
+        restartLock.lock()
+        let isCurrent = producer === prod
+        restartLock.unlock()
+        guard isCurrent else {
+            if case .stopRequested = reason {} else {
+                EngineLog.emit(
+                    "[HLSVideoEngine] superseded producer exited (reason=\(reason)); not the session's pump, ignored",
+                    category: .session
+                )
+            }
+            return
+        }
         // #65 (VOD only): a broken backpressure wedge means AVPlayer is stuck behind a parked producer.
         // Re-anchor the producer on AVPlayer's real position so the segments it is starved for get produced.
         if case .backpressureWedge = reason {
diff --git a/Tests/AetherEngineTests/SupersededPumpExitTests.swift b/Tests/AetherEngineTests/SupersededPumpExitTests.swift
new file mode 100644
index 000000000..2bdfe787d
--- /dev/null
+++ b/Tests/AetherEngineTests/SupersededPumpExitTests.swift
@@ -0,0 +1,84 @@
+import Testing
+import Foundation
+import AetherLibavcodec
+import AetherLibavutil
+@testable import AetherEngine
+
+/// Audit HLS-1: a producer the session already replaced (the #79 wedge abort, or `stop()`)
+/// reports its aborted read as a read error. That exit must not reach the session's recovery
+/// arms: no revive-gate spend, no seek-state or failure signal to the host.
+@Suite("Superseded pump exit")
+struct SupersededPumpExitTests {
+
+    private final class Recorder: @unchecked Sendable {
+        private let lock = NSLock()
+        private var _failures = 0
+        private var _seekSignals = 0
+        var failures: Int { lock.lock(); defer { lock.unlock() }; return _failures }
+        var seekSignals: Int { lock.lock(); defer { lock.unlock() }; return _seekSignals }
+        func fail() { lock.lock(); _failures += 1; lock.unlock() }
+        func seek() { lock.lock(); _seekSignals += 1; lock.unlock() }
+    }
+
+    private func makeProducer(codecpar: UnsafeMutablePointer<AVCodecParameters>) throws -> HLSSegmentProducer {
+        try HLSSegmentProducer(
+            demuxer: Demuxer(),
+            videoStreamIndex: 0,
+            video: .init(codecpar: UnsafePointer(codecpar),
+                         timeBase: AVRational(num: 1, den: 90_000),
+                         codecTagOverride: nil),
+            cache: SegmentCache(forwardWindow: 4, backwardWindow: 4),
+            videoFallbackDurationPts: 3_000,
+            desiredFirstVideoTfdtPts: 0,
+            segmentBoundaries: [0, 540_000]
+        )
+    }
+
+    private func makeEngine(_ recorder: Recorder) -> HLSVideoEngine {
+        let engine = HLSVideoEngine(url: URL(fileURLWithPath: "/nonexistent/superseded.mkv"),
+                                    dvModeAvailable: false)
+        engine.onVODSourceFailed = { _, _, _ in recorder.fail() }
+        engine.onSeekStateChanged = { _, _ in recorder.seek() }
+        return engine
+    }
+
+    @Test("a read error from a replaced producer spends nothing and signals nothing")
+    func supersededReadErrorIsIgnored() throws {
+        var codecpar: UnsafeMutablePointer<AVCodecParameters>? = try #require(avcodec_parameters_alloc())
+        defer { avcodec_parameters_free(&codecpar) }
+        codecpar!.pointee.codec_id = AV_CODEC_ID_H264
+        codecpar!.pointee.codec_type = AVMEDIA_TYPE_VIDEO
+
+        let recorder = Recorder()
+        let engine = makeEngine(recorder)
+        let stale = try makeProducer(codecpar: codecpar!)
+        let current = try makeProducer(codecpar: codecpar!)
+        engine.producer = current
+
+        engine.handlePumpFinished(stale, reason: .readError(code: -1))
+        engine.producer = nil
+        engine.handlePumpFinished(stale, reason: .readError(code: -1))
+
+        #expect(engine.readErrorReviveGate.attempts == 0)
+        #expect(!engine.mainDemuxerSuspectDead)
+        #expect(recorder.failures == 0)
+        #expect(recorder.seekSignals == 0)
+    }
+
+    @Test("the same read error from the session's own producer still reaches the recovery arms")
+    func currentReadErrorIsHandled() throws {
+        var codecpar: UnsafeMutablePointer<AVCodecParameters>? = try #require(avcodec_parameters_alloc())
+        defer { avcodec_parameters_free(&codecpar) }
+        codecpar!.pointee.codec_id = AV_CODEC_ID_H264
+        codecpar!.pointee.codec_type = AVMEDIA_TYPE_VIDEO
+
+        let recorder = Recorder()
+        let engine = makeEngine(recorder)
+        let current = try makeProducer(codecpar: codecpar!)
+        engine.producer = current
+
+        engine.handlePumpFinished(current, reason: .readError(code: -1))
+
+        #expect(recorder.failures == 1)
+    }
+}

From ccdb9b7ea6923f56627874cda67a4b3eb1af1d81 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 05:36:52 +0200
Subject: [PATCH 051/359] fix(hls): a live reopen that slept through a zap no
 longer opens the old channel (audit HLS-2)

performLiveReopen checked the session only before its backoff sleep (up to 8 s),
then registered and opened a fresh demuxer unconditionally. A stop() during the
sleep left an orphan connect plus find_stream_info against the old origin, which
on single-slot tuners competes with the new channel. Registration now checks the
producer atomically under restartLock, and Demuxer.markClosed() is sticky, so a
close that lands before or during open aborts it instead of being a no-op.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 Sources/AetherEngine/Demuxer/Demuxer.swift    | 18 +++++-
 .../Video/HLSVideoEngine+LiveReopen.swift     | 12 +++-
 .../LiveReopenAfterTeardownTests.swift        | 59 +++++++++++++++++++
 3 files changed, 85 insertions(+), 4 deletions(-)
 create mode 100644 Tests/AetherEngineTests/LiveReopenAfterTeardownTests.swift

diff --git a/Sources/AetherEngine/Demuxer/Demuxer.swift b/Sources/AetherEngine/Demuxer/Demuxer.swift
index 7465a04b1..242b5d3d7 100644
--- a/Sources/AetherEngine/Demuxer/Demuxer.swift
+++ b/Sources/AetherEngine/Demuxer/Demuxer.swift
@@ -226,6 +226,10 @@ public final class Demuxer: @unchecked Sendable {
     private let accessLock = NSLock()
 
     private var avioProvider: AVIOProvider?
+    /// Audit HLS-2: `markClosed()` before the provider exists used to be a no-op, so a teardown
+    /// that raced an in-flight open let it finish its connect and probe.
+    private let closeRequestLock = NSLock()
+    private var closeRequested = false
     private var openProfile: DemuxerOpenProfile = .playback
 
     /// The URL and headers this demuxer was opened from, kept for the recordless Dolby Vision audit's
@@ -545,8 +549,16 @@ public final class Demuxer: @unchecked Sendable {
         inputFormat: UnsafePointer<AVInputFormat>? = nil,
         isLive: Bool = false
     ) throws {
+        closeRequestLock.lock()
+        let closedBeforeConnect = closeRequested
+        closeRequestLock.unlock()
+        if closedBeforeConnect { throw DemuxerError.openFailed(code: -1) }
         try provider.open()
+        closeRequestLock.lock()
         avioProvider = provider
+        let closedDuringConnect = closeRequested
+        closeRequestLock.unlock()
+        if closedDuringConnect { provider.markClosed() }
         onOpenProgress?(.sourceOpened)   // #361
 
         // AE#460 follow-up: a live source rebuilt on a RETAINED reader resumes where that reader
@@ -2016,7 +2028,11 @@ public final class Demuxer: @unchecked Sendable {
     /// Fast lock-free unblock: AVIO read callback returns -1, av_read_frame returns
     /// at once. No resource freeing. Call before close() when cancelling a pump.
     func markClosed() {
-        avioProvider?.markClosed()
+        closeRequestLock.lock()
+        closeRequested = true
+        let provider = avioProvider
+        closeRequestLock.unlock()
+        provider?.markClosed()
     }
 
     /// Static metadata probes only. Strong ownership outlives the native interrupt callback.
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine+LiveReopen.swift b/Sources/AetherEngine/Video/HLSVideoEngine+LiveReopen.swift
index 44ceb208b..9d874ba0a 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine+LiveReopen.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine+LiveReopen.swift
@@ -918,7 +918,9 @@ extension HLSVideoEngine {
             try? await Task.sleep(nanoseconds: UInt64(delay * 1_000_000_000))
 
             let dem = Demuxer()
-            registerReopenDemuxer(dem)  // register before blocking open so stop() can abort via markClosed
+            // Audit HLS-2: a zap during the sleep above must not open the old channel; on a
+            // single-slot tuner that orphan open takes the slot the new channel needs.
+            guard registerReopenDemuxer(dem, failedProducer: failedProducer) else { return }
             defer { unregisterReopenDemuxer(dem) }
             var freshReader: IOReader?
             do {
@@ -988,10 +990,14 @@ extension HLSVideoEngine {
         return producer === p
     }
 
-    private func registerReopenDemuxer(_ dem: Demuxer) {
+    /// Registers `dem` for `stop()` to abort, atomically with the check that the session still
+    /// belongs to `failedProducer`. False means a stop or a newer producer already took over.
+    func registerReopenDemuxer(_ dem: Demuxer, failedProducer: HLSSegmentProducer) -> Bool {
         restartLock.lock()
+        defer { restartLock.unlock() }
+        guard producer === failedProducer else { return false }
         reopenDemuxer = dem
-        restartLock.unlock()
+        return true
     }
 
     private func unregisterReopenDemuxer(_ dem: Demuxer) {
diff --git a/Tests/AetherEngineTests/LiveReopenAfterTeardownTests.swift b/Tests/AetherEngineTests/LiveReopenAfterTeardownTests.swift
new file mode 100644
index 000000000..7d9b6425d
--- /dev/null
+++ b/Tests/AetherEngineTests/LiveReopenAfterTeardownTests.swift
@@ -0,0 +1,59 @@
+import Testing
+import Foundation
+import AetherLibavcodec
+import AetherLibavutil
+@testable import AetherEngine
+
+/// Audit HLS-2: a live reopen that slept through a zap must not open the old channel.
+@Suite("Live reopen after teardown")
+struct LiveReopenAfterTeardownTests {
+
+    @Test("a reopen demuxer is only registered while the failed producer is still the session's")
+    func registrationRequiresCurrentProducer() throws {
+        var codecpar: UnsafeMutablePointer<AVCodecParameters>? = try #require(avcodec_parameters_alloc())
+        defer { avcodec_parameters_free(&codecpar) }
+        codecpar!.pointee.codec_id = AV_CODEC_ID_H264
+        codecpar!.pointee.codec_type = AVMEDIA_TYPE_VIDEO
+        let engine = HLSVideoEngine(url: URL(fileURLWithPath: "/nonexistent/live.ts"),
+                                    dvModeAvailable: false)
+        let failed = try HLSSegmentProducer(
+            demuxer: Demuxer(), videoStreamIndex: 0,
+            video: .init(codecpar: UnsafePointer(codecpar!),
+                         timeBase: AVRational(num: 1, den: 90_000), codecTagOverride: nil),
+            cache: SegmentCache(forwardWindow: 4, backwardWindow: 4),
+            videoFallbackDurationPts: 3_000, desiredFirstVideoTfdtPts: 0,
+            segmentBoundaries: [0, 540_000])
+
+        engine.producer = failed
+        #expect(engine.registerReopenDemuxer(Demuxer(), failedProducer: failed))
+        engine.stop()
+        #expect(!engine.registerReopenDemuxer(Demuxer(), failedProducer: failed),
+                "after stop() the reopen must not register (and so must not open)")
+    }
+
+    private final class CountingReader: IOReader, @unchecked Sendable {
+        private let lock = NSLock()
+        private var _reads = 0
+        var reads: Int { lock.lock(); defer { lock.unlock() }; return _reads }
+        func read(_ buffer: UnsafeMutablePointer<UInt8>?, size: Int32) -> Int32 {
+            lock.lock(); _reads += 1; lock.unlock()
+            return 0
+        }
+        func seek(offset: Int64, whence: Int32) -> Int64 { -1 }
+        func close() {}
+        func cancel() {}
+        func makeIndependentReader() -> IOReader? { nil }
+        var discImageProbeEnabled: Bool { false }
+    }
+
+    @Test("a demuxer marked closed before its open never touches the source")
+    func markClosedBeforeOpenAbortsTheOpen() {
+        let demuxer = Demuxer()
+        let reader = CountingReader()
+        demuxer.markClosed()
+        #expect(throws: DemuxerError.self) {
+            try demuxer.open(reader: reader, formatHint: "mpegts", isLive: true)
+        }
+        #expect(reader.reads == 0)
+    }
+}

From cb8aab48612cb2e508ee8ae7d52bb8bc4b9b48c9 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 05:39:02 +0200
Subject: [PATCH 052/359] fix(hls): derive the HEVC CODECS attribute from the
 SPS of Annex-B extradata (audit HLS-3)

plainHEVCCodecs only parsed an hvcC record. Annex-B HEVC (MPEG-TS, Annex-B
Matroska) carries none, so the route fell back to the hardcoded Main10
`hvc1.2.4.L<level>` while the mp4 muxer built the init's hvcC from the SPS, which
for an 8-bit source says Main. On tvOS HEVC always goes through the master, the
same mismatch AE#187 measured a strict Apple TV rejecting. The string now comes
from the SPS profile_tier_level, which is byte for byte the hvcC header the muxer
writes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 .../AetherEngine/Video/CodecRoutePolicy.swift | 23 +++++++-
 Sources/AetherEngine/Video/H264SPS.swift      |  2 +-
 .../Video/VideoConfigRecord.swift             |  2 +-
 .../HEVCCodecStringTests.swift                | 55 +++++++++++++++++++
 4 files changed, 77 insertions(+), 5 deletions(-)

diff --git a/Sources/AetherEngine/Video/CodecRoutePolicy.swift b/Sources/AetherEngine/Video/CodecRoutePolicy.swift
index 31fdb6c35..8c9769699 100644
--- a/Sources/AetherEngine/Video/CodecRoutePolicy.swift
+++ b/Sources/AetherEngine/Video/CodecRoutePolicy.swift
@@ -181,6 +181,22 @@ extension HLSVideoEngine {
         return s
     }
 
+    /// Same string read off the first SPS of Annex-B extradata (MPEG-TS, Annex-B Matroska), which
+    /// carries no hvcC. The SPS's profile_tier_level general part is byte for byte the hvcC header
+    /// bytes 1..12, and it is what the mp4 muxer builds the init's hvcC from, so the two agree.
+    /// Audit HLS-3: without this an 8-bit Main TS source fell back to the Main10 declaration.
+    static func hevcCodecsString(
+        fromAnnexBExtradata extradata: [UInt8],
+        sampleEntry: String = "hvc1"
+    ) -> String? {
+        guard let sps = VideoConfigRecord.splitAnnexBNALs(extradata)
+            .first(where: { $0.count > 2 && (($0[0] >> 1) & 0x3F) == 33 }) else { return nil }
+        // Past the 2-byte NAL header: one byte of vps_id / max_sub_layers / nesting, then the PTL.
+        let rbsp = H264SPS.unescape(Array(sps.dropFirst(2)))
+        guard rbsp.count >= 13 else { return nil }
+        return hevcCodecsString(fromConfigRecord: [1] + Array(rbsp[1...12]), sampleEntry: sampleEntry)
+    }
+
     /// RFC 6381 `avc1.PPCCLL` read straight off the avcC configuration record, which states all three
     /// bytes outright: AVCProfileIndication, profile_compatibility (the constraint_set flags) and
     /// AVCLevelIndication are bytes 1..3. Same reasoning as `hevcCodecsString`: the record is what the
@@ -239,8 +255,8 @@ extension HLSVideoEngine {
             profile: codecpar.pointee.profile, level: codecpar.pointee.level)
     }
 
-    /// Derive the plain-HEVC CODECS string from the source hvcC when parseable, else fall back to the
-    /// legacy Main10 form. Used only by the non-DV `.none` / `.profile82` branch; DV variants keep their
+    /// Derive the plain-HEVC CODECS string from the source hvcC (or the SPS of Annex-B extradata) when
+    /// parseable, else fall back to the legacy Main10 form. Used only by the non-DV `.none` / `.profile82` branch; DV variants keep their
     /// deliberate `hvc1.2.4` (Main10 PQ base) declaration.
     private func plainHEVCCodecs(
         codecpar: UnsafePointer<AVCodecParameters>,
@@ -249,7 +265,8 @@ extension HLSVideoEngine {
         if let ed = codecpar.pointee.extradata, codecpar.pointee.extradata_size > 0 {
             let bytes = Array(UnsafeBufferPointer(
                 start: ed, count: Int(codecpar.pointee.extradata_size)))
-            if let derived = Self.hevcCodecsString(fromConfigRecord: bytes) {
+            if let derived = Self.hevcCodecsString(fromConfigRecord: bytes)
+                ?? Self.hevcCodecsString(fromAnnexBExtradata: bytes) {
                 return derived
             }
         }
diff --git a/Sources/AetherEngine/Video/H264SPS.swift b/Sources/AetherEngine/Video/H264SPS.swift
index d01e7660f..a0ef696f5 100644
--- a/Sources/AetherEngine/Video/H264SPS.swift
+++ b/Sources/AetherEngine/Video/H264SPS.swift
@@ -161,7 +161,7 @@ enum H264SPS {
         return sc + sps + sc + pps
     }
 
-    private static func unescape(_ b: [UInt8]) -> [UInt8] {  // remove emulation-prevention bytes (00 00 03 -> 00 00)
+    static func unescape(_ b: [UInt8]) -> [UInt8] {  // remove emulation-prevention bytes (00 00 03 -> 00 00)
         var out = [UInt8](); out.reserveCapacity(b.count)
         var zeros = 0
         var i = 0
diff --git a/Sources/AetherEngine/Video/VideoConfigRecord.swift b/Sources/AetherEngine/Video/VideoConfigRecord.swift
index 4e4d415ce..6df1b4ff5 100644
--- a/Sources/AetherEngine/Video/VideoConfigRecord.swift
+++ b/Sources/AetherEngine/Video/VideoConfigRecord.swift
@@ -192,7 +192,7 @@ enum VideoConfigRecord {
     /// Zero bytes immediately before a start code belong to the start code (a 4-byte code is a 3-byte
     /// one with a leading `trailing_zero_8bits`), so they are trimmed off the preceding NAL. A
     /// parameter set never ends in `0x00`: its last byte carries the rbsp_stop_one_bit.
-    private static func splitAnnexBNALs(_ bytes: [UInt8]) -> [[UInt8]] {
+    static func splitAnnexBNALs(_ bytes: [UInt8]) -> [[UInt8]] {
         var starts: [Int] = []
         var i = 0
         while i + 3 <= bytes.count {
diff --git a/Tests/AetherEngineTests/HEVCCodecStringTests.swift b/Tests/AetherEngineTests/HEVCCodecStringTests.swift
index b24c70def..f106db63a 100644
--- a/Tests/AetherEngineTests/HEVCCodecStringTests.swift
+++ b/Tests/AetherEngineTests/HEVCCodecStringTests.swift
@@ -1,4 +1,7 @@
 import Testing
+import Foundation
+import AetherLibavcodec
+import AetherLibavutil
 @testable import AetherEngine
 
 /// AE#187 part 2: the plain-HEVC CODECS string. The `.none` / `.profile82` branch hardcoded
@@ -113,4 +116,56 @@ struct HEVCCodecStringTests {
     func tooShortReturnsNil() {
         #expect(HLSVideoEngine.hevcCodecsString(fromConfigRecord: [1, 1, 0x60, 0, 0, 0]) == nil)
     }
+
+    /// Audit HLS-3: 8-bit Main L3.1 as MPEG-TS carries it, a VPS and an SPS behind start codes with
+    /// the emulation-prevention bytes a real encoder writes into the zero runs of the PTL.
+    static let annexBMain8bit: [UInt8] = [
+        0x00, 0x00, 0x00, 0x01, 0x40, 0x01, 0x0c, 0x01, 0xff, 0xff, 0x01, 0x60, 0x00, 0x00, 0x03, 0x00,
+        0x90, 0x00, 0x00, 0x03, 0x00, 0x00, 0x03, 0x00, 0x5d, 0x95, 0x94, 0x09,
+        0x00, 0x00, 0x00, 0x01, 0x42, 0x01, 0x01, 0x01, 0x60, 0x00, 0x00, 0x03, 0x00, 0x90, 0x00, 0x00,
+        0x03, 0x00, 0x00, 0x03, 0x00, 0x5d, 0xa0, 0x02, 0x80, 0x80, 0x2d, 0x16, 0x59, 0x59, 0xa4, 0x93,
+        0x2b, 0x80,
+    ]
+
+    @Test("Annex-B 8-bit Main SPS -> hvc1.1.6.L93.90, not the Main10 fallback")
+    func annexBMain8bitFromSPS() {
+        #expect(HLSVideoEngine.hevcCodecsString(fromAnnexBExtradata: Self.annexBMain8bit)
+            == "hvc1.1.6.L93.90")
+    }
+
+    @Test("Annex-B Main10 SPS keeps its own profile and level")
+    func annexBMain10FromSPS() {
+        let annexB: [UInt8] = [
+            0x00, 0x00, 0x01, 0x42, 0x01, 0x01, 0x02, 0x20, 0x00, 0x00, 0x03, 0x00, 0x90, 0x00, 0x00,
+            0x03, 0x00, 0x00, 0x03, 0x00, 0x78, 0xa0, 0x03, 0xc0, 0x80, 0x11, 0x07, 0xca,
+        ]
+        #expect(HLSVideoEngine.hevcCodecsString(fromAnnexBExtradata: annexB) == "hvc1.2.4.L120.90")
+    }
+
+    @Test("Annex-B extradata without an SPS returns nil")
+    func annexBWithoutSPS() {
+        #expect(HLSVideoEngine.hevcCodecsString(
+            fromAnnexBExtradata: [0x00, 0x00, 0x01, 0x40, 0x01, 0x0c, 0x01, 0xff]) == nil)
+    }
+
+    @Test("the plain HEVC route declares the Annex-B source's own profile in the master")
+    func plainRouteUsesAnnexBSPS() throws {
+        var codecpar: UnsafeMutablePointer<AVCodecParameters>? = try #require(avcodec_parameters_alloc())
+        defer { avcodec_parameters_free(&codecpar) }
+        let cp = codecpar!
+        cp.pointee.codec_type = AVMEDIA_TYPE_VIDEO
+        cp.pointee.codec_id = AV_CODEC_ID_HEVC
+        cp.pointee.level = 93
+        let bytes = Self.annexBMain8bit
+        let ed = try #require(av_mallocz(bytes.count + Int(AV_INPUT_BUFFER_PADDING_SIZE)))
+            .assumingMemoryBound(to: UInt8.self)
+        bytes.withUnsafeBufferPointer { ed.update(from: $0.baseAddress!, count: bytes.count) }
+        cp.pointee.extradata = ed
+        cp.pointee.extradata_size = Int32(bytes.count)
+
+        let engine = HLSVideoEngine(url: URL(fileURLWithPath: "/nonexistent/main8.ts"),
+                                    dvModeAvailable: false)
+        let route = try engine.resolveCodecRoute(codecpar: UnsafePointer(cp))
+        #expect(route.primaryCodecs == "hvc1.1.6.L93.90")
+    }
 }

From 205740fbb61e9e413c1d937276e5199f1aa89ca5 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 05:39:55 +0200
Subject: [PATCH 053/359] fix(hls): the AE#412 re-cut restart runs inside its 2
 s gate bound (audit HLS-4)

preparedSeekLanding called requestRestart inline. With an idle coalescer that ran
the whole performRestart on the seek's own task (up to a 5 s stop wait, a #79
fresh WAN open, the demuxer seek, and every target queued meanwhile) before the
2 s gate wait even started, all ahead of the seek's 8 s landing bound. The
restart now goes out on a global queue and the gate wait bounds the re-cut.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 Sources/AetherEngine/Video/HLSVideoEngine.swift | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/Sources/AetherEngine/Video/HLSVideoEngine.swift b/Sources/AetherEngine/Video/HLSVideoEngine.swift
index 5f8faa36a..bd1a86175 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine.swift
@@ -3462,7 +3462,12 @@ public final class HLSVideoEngine: @unchecked Sendable {
         anchorShiftLock.lock()
         recutIndices.insert(index)
         anchorShiftLock.unlock()
-        requestRestart(at: index, authoritative: true)
+        // Audit HLS-4: off this task, so the gate wait below bounds the whole re-cut. Inline, an idle
+        // coalescer ran the restart here (a 5 s stop wait, a #79 reopen, the demuxer seek) before the
+        // wait began, all outside the seek's 8 s landing bound.
+        DispatchQueue.global(qos: .userInitiated).async { [weak self] in
+            self?.requestRestart(at: index, authoritative: true)
+        }
         guard let opened = awaitGateOpen(forIndex: index, timeout: Self.recutGateWaitSeconds) else {
             anchorShiftLock.lock()
             recutIndices.remove(index)

From 2ddbea07ab4132ebc4e00ddfd858a3b3a6554ccb Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 05:40:06 +0200
Subject: [PATCH 054/359] test(server): observe the stranger drop from the
 client side (audit NET-6)

The server drops an idle stranger after 0.5 s, so on a loaded full run a deadline-free wait for
activeConnectionCount == 1 could start after the drop and park until the suite's time limit.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 .../HLSLocalServerSlowPeerTests.swift         | 28 +++++++++++++++----
 1 file changed, 22 insertions(+), 6 deletions(-)

diff --git a/Tests/AetherEngineTests/HLSLocalServerSlowPeerTests.swift b/Tests/AetherEngineTests/HLSLocalServerSlowPeerTests.swift
index 5f6452b9c..92d779b5e 100644
--- a/Tests/AetherEngineTests/HLSLocalServerSlowPeerTests.swift
+++ b/Tests/AetherEngineTests/HLSLocalServerSlowPeerTests.swift
@@ -16,11 +16,14 @@ struct HLSLocalServerSlowPeerTests {
 
         let fd = try #require(Self.connect(port: server.port, host: "127.0.0.1"))
         defer { close(fd) }
-        try await waitFor { server.activeConnectionCount == 1 }
 
+        // Observed from the client side: the server may drop the connection before a poll of its
+        // count ever sees it, which on a loaded run left a wait for "count == 1" parked forever.
         // The old per-recv timeout was 60 s, so closing well inside that is the fix.
-        let dropped = try await waitFor(upTo: .seconds(20)) { server.activeConnectionCount == 0 }
-        #expect(dropped, "an idle unauthenticated connection kept its slot")
+        #expect(await Self.onOwnThread { Self.peerCloses(fd: fd, within: 20) },
+                "an idle unauthenticated connection kept its slot")
+        let released = try await waitFor(upTo: .seconds(20)) { server.activeConnectionCount == 0 }
+        #expect(released)
     }
 
     @Test("A peer trickling its head one byte at a time is dropped at the head deadline")
@@ -32,10 +35,11 @@ struct HLSLocalServerSlowPeerTests {
         let fd = try #require(Self.connect(port: server.port, host: "127.0.0.1"))
         let trickle = Trickle(fd: fd)
         defer { trickle.stop(); close(fd) }
-        try await waitFor { server.activeConnectionCount == 1 }
 
-        let dropped = try await waitFor(upTo: .seconds(20)) { server.activeConnectionCount == 0 }
-        #expect(dropped, "a byte every 200 ms kept an unauthenticated connection open")
+        #expect(await Self.onOwnThread { Self.peerCloses(fd: fd, within: 20) },
+                "a byte every 200 ms kept an unauthenticated connection open")
+        let released = try await waitFor(upTo: .seconds(20)) { server.activeConnectionCount == 0 }
+        #expect(released)
     }
 
     @Test("A connection that presented the token keeps its keep-alive idle past the stranger deadline")
@@ -150,6 +154,18 @@ struct HLSLocalServerSlowPeerTests {
         }
     }
 
+    /// True once the server has closed or reset `fd`, false if it is still open after `seconds`.
+    private static func peerCloses(fd: Int32, within seconds: Int) -> Bool {
+        var timeout = timeval(tv_sec: seconds, tv_usec: 0)
+        _ = setsockopt(fd, SOL_SOCKET, SO_RCVTIMEO, &timeout, socklen_t(MemoryLayout<timeval>.size))
+        var chunk = [UInt8](repeating: 0, count: 512)
+        while true {
+            let n = recv(fd, &chunk, chunk.count, 0)
+            if n == 0 { return true }
+            if n < 0 { return errno == ECONNRESET }
+        }
+    }
+
     private static func onOwnThread<T: Sendable>(_ body: @escaping @Sendable () -> T) async -> T {
         await withCheckedContinuation { continuation in
             Thread.detachNewThread { continuation.resume(returning: body()) }

From eb68747737cdda770c408a0af03fa8fe009f3950 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 05:41:46 +0200
Subject: [PATCH 055/359] fix(routing): AV1 High and Professional profiles go
 to software even where HW AV1 exists (audit HLS-5)

The native AV1 route was gated only on the codec-level av1Available. Apple's
hardware AV1 decoders take Main profile only (8/10-bit 4:2:0), so a 4:4:4,
4:2:2 or 12-bit AV1 source on an A17 Pro / M3 device reached AVPlayer and
rendered nothing while dav1d would have played it. AV1 now consults the
second-stage format gate, which reads seq_profile from the av1C (codecpar
profile as fallback, unknown keeps native).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 README.md                                     |  4 +--
 .../Decoder/VideoRoutingPolicy.swift          | 19 ++++++++--
 .../Video/VTCapabilityProbe.swift             | 14 +++++++-
 .../VideoRoutingPolicyTests.swift             | 36 ++++++++++++++++---
 4 files changed, 63 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index b4533f039..882bd2733 100644
--- a/README.md
+++ b/README.md
@@ -59,8 +59,8 @@ A scannable summary; the depth for each row lives in **[docs/formats.md](docs/fo
 | --- | --- |
 | Containers | MKV, MP4, WebM, MPEG-TS, AVI, ASF / WMV, OGG, FLV |
 | Disc | DVD-Video and Blu-ray ISO (decrypted): selectable titles and chapters, demuxed through the normal path |
-| Video (HW) | H.264, HEVC, HEVC Main10 via VideoToolbox; AV1 where HW AV1 exists |
-| Video (SW) | AV1 (dav1d) without HW, VP9 / VP8, MPEG-4 Part 2 / MPEG-2 / VC-1, QuickTime RLE, the Flash tail (Sorenson Spark, On2 VP6) and anything else the FFmpeg build carries a decoder for (software is the default route; only HEVC, H.264 and HW-decodable AV1 go native), H.264 High 4:2:2 / 4:4:4 / 10 and HEVC Rext where VideoToolbox has no HW decoder (Intel Macs, older chips), interlaced H.264 (AVPlayer does not deinterlace; on VOD the declared field order is verified against decoded frames, so progressive-in-interlaced-carriage keeps hardware decode); GPU deinterlace (yadif_videotoolbox, Metal, field-rate by default) with a CPU bwdif fallback |
+| Video (HW) | H.264, HEVC, HEVC Main10 via VideoToolbox; AV1 Main profile where HW AV1 exists |
+| Video (SW) | AV1 (dav1d) without HW, and AV1 High / Professional (4:4:4, 4:2:2, 12-bit) everywhere, VP9 / VP8, MPEG-4 Part 2 / MPEG-2 / VC-1, QuickTime RLE, the Flash tail (Sorenson Spark, On2 VP6) and anything else the FFmpeg build carries a decoder for (software is the default route; only HEVC, H.264 and HW-decodable AV1 go native), H.264 High 4:2:2 / 4:4:4 / 10 and HEVC Rext where VideoToolbox has no HW decoder (Intel Macs, older chips), interlaced H.264 (AVPlayer does not deinterlace; on VOD the declared field order is verified against decoded frames, so progressive-in-interlaced-carriage keeps hardware decode); GPU deinterlace (yadif_videotoolbox, Metal, field-rate by default) with a CPU bwdif fallback |
 | HDR | HDR10, HDR10+ (per-frame ST 2094-40), Dolby Vision (P5, P7 as single-layer 8.1, P8.1, P8.4, AV1 P10.x), HLG |
 | Audio | AAC, AC3, EAC3, FLAC, ALAC stream-copy lossless; TrueHD / MLP / DTS / DTS-HD MA / MP3 / MP2 / Opus / Vorbis / LPCM (incl. Blu-ray, G.711) / WMA (Standard, Pro, Lossless, Voice) / Nellymoser / ADPCM-SWF / Speex bridge to EAC3 5.1 (default) or lossless FLAC |
 | Dolby Atmos | EAC3+JOC stream-copied on every route (HDMI MAT 2.0, AirPods spatial, BT downmix). No container reliably declares JOC pre-decode, so an honest `TrackInfo.isAtmos` needs a bounded decode: `AetherEngine.probeDetectingAtmos(url:/source:)` answers for a details screen without starting playback, and `LoadOptions.confirmAtmos` has the running session confirm its own tracks in the background and republish `audioTracks`. Both are opt-in and neither sits on the playback-start path |
diff --git a/Sources/AetherEngine/Decoder/VideoRoutingPolicy.swift b/Sources/AetherEngine/Decoder/VideoRoutingPolicy.swift
index c88cf06b9..064268275 100644
--- a/Sources/AetherEngine/Decoder/VideoRoutingPolicy.swift
+++ b/Sources/AetherEngine/Decoder/VideoRoutingPolicy.swift
@@ -101,8 +101,8 @@ enum VideoRoutingPolicy {
     /// AVPlayer path reaches readyToPlay and then renders nothing (H.264 High 4:2:2/4:4:4/High-10, HEVC Rext
     /// on Intel Macs / older Apple TV). Pure so it is unit-testable; the impure VT probe
     /// (`VTCapabilityProbe.canHardwareDecode`) is injected as the `canHardwareDecode` closure and only runs
-    /// when the gate actually consults it. Only H.264 / HEVC consult this gate; AV1 / VP9 / etc. already
-    /// have their own routing above and must not be reclassified here.
+    /// when the gate actually consults it. H.264 / HEVC and HW-routed AV1 consult this gate (AV1 by
+    /// profile, see `av1FitsHardwareDecoder`); VP9 / etc. have their own routing above.
     ///
     /// #176: HEVC DV Profile 5 bypasses the gate entirely. The probe builds a plain-HEVC format description
     /// from the raw hvcC, which is not what the native path plays (dvh1 + dvcC, decoded by Apple's DV
@@ -118,13 +118,26 @@ enum VideoRoutingPolicy {
         switch codecID {
         case AV_CODEC_ID_HEVC where dvProfile == 5:
             return false
-        case AV_CODEC_ID_H264, AV_CODEC_ID_HEVC:
+        case AV_CODEC_ID_H264, AV_CODEC_ID_HEVC, AV_CODEC_ID_AV1:
             return !canHardwareDecode()
         default:
             return false
         }
     }
 
+    /// Audit HLS-5: Apple's hardware AV1 decoders (A17 Pro, M3 and later) decode Main profile only,
+    /// 8/10-bit 4:2:0. `av1Available` is a codec-level answer, so High (4:4:4) and Professional
+    /// (4:2:2, 12-bit) reached AVPlayer and rendered nothing while dav1d would have played them.
+    /// The av1C states `seq_profile` in the top 3 bits of its second byte; the codecpar profile is the
+    /// fallback. Unknown on both counts keeps the native route, like the H.264 / HEVC probe gap.
+    static func av1FitsHardwareDecoder(av1C: [UInt8]?, codecparProfile: Int32) -> Bool {
+        if let av1C, av1C.count >= 4, av1C[0] & 0x80 != 0 {
+            return av1C[1] >> 5 == 0
+        }
+        guard codecparProfile >= 0 else { return true }
+        return codecparProfile == 0
+    }
+
     /// AE#461: the decode path a session ends up on, given what the routing concluded and what the
     /// host asked for. Pure so the override is unit-testable next to the decisions it overrules.
     ///
diff --git a/Sources/AetherEngine/Video/VTCapabilityProbe.swift b/Sources/AetherEngine/Video/VTCapabilityProbe.swift
index c2bf17ce5..5187c9c1f 100644
--- a/Sources/AetherEngine/Video/VTCapabilityProbe.swift
+++ b/Sources/AetherEngine/Video/VTCapabilityProbe.swift
@@ -53,7 +53,19 @@ enum VTCapabilityProbe {
     /// wrongly forces the software path. Not the question `SoftwarePlaybackHost` asks, see
     /// `HardwareDecodeVerdict`.
     static func canHardwareDecode(codecpar: UnsafePointer<AVCodecParameters>) -> Bool {
-        hardwareDecodeVerdict(codecpar: codecpar).keepsNativeRoute
+        if codecpar.pointee.codec_id == AV_CODEC_ID_AV1 {
+            let av1C = codecpar.pointee.extradata.map {
+                Array(UnsafeBufferPointer(start: $0, count: Int(max(0, codecpar.pointee.extradata_size))))
+            }
+            let fits = VideoRoutingPolicy.av1FitsHardwareDecoder(
+                av1C: av1C, codecparProfile: codecpar.pointee.profile)
+            EngineLog.emit(
+                "[VTProbe] canHardwareDecode codec=av01 profile=\(codecpar.pointee.profile) -> \(fits)",
+                category: .engine
+            )
+            return fits
+        }
+        return hardwareDecodeVerdict(codecpar: codecpar).keepsNativeRoute
     }
 
     /// The throwaway session is invalidated immediately; the whole probe costs well under a millisecond and
diff --git a/Tests/AetherEngineTests/VideoRoutingPolicyTests.swift b/Tests/AetherEngineTests/VideoRoutingPolicyTests.swift
index 32ae48081..8c45a3d53 100644
--- a/Tests/AetherEngineTests/VideoRoutingPolicyTests.swift
+++ b/Tests/AetherEngineTests/VideoRoutingPolicyTests.swift
@@ -148,16 +148,44 @@ struct VideoRoutingPolicyTests {
             codecID: AV_CODEC_ID_HEVC, dvProfile: nil, canHardwareDecode: { true }))
     }
 
-    @Test("non-H.264/HEVC codecs ignore the undecodable gate (own policy governs them)")
+    @Test("codecs outside the gate ignore it (own policy governs them)")
     func otherCodecsIgnoreUndecodableGate() {
-        // AV1 without HW is already routed software by requiresSoftwarePath; this gate must not double-handle
-        // it, and must never reclassify VP9 / MPEG-2 / etc. off a codec they don't apply to.
-        for codec in [AV_CODEC_ID_AV1, AV_CODEC_ID_VP9, AV_CODEC_ID_MPEG2VIDEO, AV_CODEC_ID_VC1] {
+        // Must never reclassify VP9 / MPEG-2 / etc. off a codec it doesn't apply to.
+        for codec in [AV_CODEC_ID_VP9, AV_CODEC_ID_MPEG2VIDEO, AV_CODEC_ID_VC1] {
             #expect(!VideoRoutingPolicy.forcesSoftwareForUndecodableFormat(
                 codecID: codec, dvProfile: nil, canHardwareDecode: { false }))
         }
     }
 
+    // MARK: - Audit HLS-5: HW AV1 is Main profile only
+
+    @Test("AV1 on a HW-AV1 device the decoder cannot take falls back to software")
+    func av1OutsideHardwareProfileSoftware() {
+        #expect(VideoRoutingPolicy.forcesSoftwareForUndecodableFormat(
+            codecID: AV_CODEC_ID_AV1, dvProfile: nil, canHardwareDecode: { false }))
+        #expect(!VideoRoutingPolicy.forcesSoftwareForUndecodableFormat(
+            codecID: AV_CODEC_ID_AV1, dvProfile: nil, canHardwareDecode: { true }))
+    }
+
+    @Test("av1C seq_profile decides: Main fits the hardware decoder, High and Professional do not")
+    func av1ProfileFromAV1C() {
+        // marker|version 0x81, then seq_profile (3 bits) | seq_level_idx_0 (5 bits), flags, reserved.
+        let main10 = [UInt8]([0x81, 0x08, 0x4C, 0x00])      // profile 0, high_bitdepth
+        let high444 = [UInt8]([0x81, 0x28, 0x00, 0x00])     // profile 1
+        let pro12bit = [UInt8]([0x81, 0x48, 0x60, 0x00])    // profile 2, high_bitdepth + twelve_bit
+        #expect(VideoRoutingPolicy.av1FitsHardwareDecoder(av1C: main10, codecparProfile: -99))
+        #expect(!VideoRoutingPolicy.av1FitsHardwareDecoder(av1C: high444, codecparProfile: -99))
+        #expect(!VideoRoutingPolicy.av1FitsHardwareDecoder(av1C: pro12bit, codecparProfile: -99))
+    }
+
+    @Test("without an av1C the codecpar profile decides, and unknown keeps the native route")
+    func av1ProfileFallback() {
+        #expect(VideoRoutingPolicy.av1FitsHardwareDecoder(av1C: nil, codecparProfile: 0))
+        #expect(!VideoRoutingPolicy.av1FitsHardwareDecoder(av1C: nil, codecparProfile: 1))
+        #expect(!VideoRoutingPolicy.av1FitsHardwareDecoder(av1C: [], codecparProfile: 2))
+        #expect(VideoRoutingPolicy.av1FitsHardwareDecoder(av1C: nil, codecparProfile: -99))
+    }
+
     // MARK: - #176 DV Profile 5 bypasses the VT probe gate
 
     @Test("HEVC DV P5 stays native even when the raw-hvcC probe says undecodable")

From 90007dbf59eed7049aeb148205f145abd1ee02b2 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 05:41:56 +0200
Subject: [PATCH 056/359] docs(changelog): audit demuxer fixes

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 CHANGELOG.md | 26 +++++++++++++++++++++++---
 1 file changed, 23 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9ca7830a6..5ee5656e1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -22,9 +22,29 @@ the public-API contract.
 - **A LAN peer can no longer hold the loopback server's connection slots.** Connections without the
   session token must send a request head within 10 s, and LAN peers are held to 24 of the 32 slots
   (audit NET-6).
-
-### Fixed
-
+- **A crafted Matroska SeekHead no longer crashes the app during prewarm.** A SeekPosition near the
+  top of the 64-bit range is skipped instead of overflowing (audit DMX-2).
+- **The held source connection no longer sends media-server credentials to a redirect target on
+  another origin**, and writes the request path as the URL spells it, so an encoded line break can
+  no longer inject header lines and IPv6 hosts get a valid Host header (audit DMX-3, DMX-4).
+
+### Fixed
+
+- **An origin that ignores Range no longer streams the whole file into memory.** Bytes past the
+  requested range are dropped and the connection is ended. Such an origin could never seek, and a
+  file larger than memory got the app killed; it now ends in a read error instead, and
+  `LoadOptions.sequentialOrigin` stays the way to play one (audit DMX-1).
+- **A 206 that starts somewhere other than the requested offset is refused** instead of shifting every
+  later read (audit DMX-5).
+- **A length-less stream that drops or stalls reports an error** instead of ending playback as if the
+  title had finished, and its buffer has a hard 128 MB bound for a transport that ignores the suspend
+  (audit DMX-6, DMX-7).
+- **A failed chunk fetch during a probe or still extraction reports an error** instead of a truncated
+  file (audit DMX-10).
+- **Tail prefetch checks its span against the file size and tolerates over-delivered bytes**, instead
+  of giving up suffix ranges for that origin until restart (audit DMX-8, DMX-9).
+- **Two demuxer races closed:** the provider reference during a cross-thread abort, and stream lookups
+  while an MPEG-TS read adds streams (audit DMX-11, NAT-7).
 - **Playlist and held relay bodies are capped while they download, not after.** A runaway origin can
   no longer grow one until the app is killed (audit NET-10).
 - **The accept loop backs off when the process runs out of file descriptors**, instead of spinning a

From f7d4d326db4c4caf603c690394686085a104e7d7 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 05:43:29 +0200
Subject: [PATCH 057/359] docs(changelog): audit engine core fixes

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 CHANGELOG.md | 24 +++++++++++++++++++++---
 1 file changed, 21 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5ee5656e1..504b2a52d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -27,9 +27,27 @@ the public-API contract.
 - **The held source connection no longer sends media-server credentials to a redirect target on
   another origin**, and writes the request path as the URL spells it, so an encoded line break can
   no longer inject header lines and IPv6 hosts get a valid Host header (audit DMX-3, DMX-4).
-
-### Fixed
-
+- **A sidecar subtitle name can no longer add lines to the served HLS master.** Line breaks and other
+  control characters in a name or language are neutralised (audit NAT-6).
+
+### Fixed
+
+- **Leaving a session while its software rebuild is running no longer leaves an error behind.** A
+  `stop()` or new `load()` during the AE#561 rebuild used to put the engine into `.error`, including
+  onto the next title's startup. The rebuild also runs in its own task now, so its waits no longer
+  spin inside the cancelled item-death task (audit CORE-1).
+- **A title started just before pressing the TV button no longer plays on in the background.** A
+  load or scrub still in flight when the app backgrounds gets the background teardown once it
+  settles, instead of carrying a live pipeline through the tvOS suspension (audit CORE-2, AE#597).
+- **Track selections survive a second background teardown on iOS** (audit CORE-3).
+- **Music plays again after a media services reset.** The reset rebuilds the audio-only AVPlayer too,
+  not only the video player (audit CORE-4, AE#597).
+- **A recording that fails while zapping no longer ends the next channel's recording**, and the live
+  edge snap no longer writes the previous channel's position after a zap (audit CORE-5, CORE-7).
+- **Load-time sidecar subtitles on the remote-HLS path select the right track** when names repeat,
+  match an origin rendition, or contain a quote (audit NAT-2).
+- **A superseded load or live-join probe no longer acts on the session that replaced it** (audit
+  CORE-6, NAT-4).
 - **An origin that ignores Range no longer streams the whole file into memory.** Bytes past the
   requested range are dropped and the connection is ended. Such an origin could never seek, and a
   file larger than memory got the app killed; it now ends in a read error instead, and

From c907c90da2a5e10b6812bdf648f17af34a6533fe Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 05:43:49 +0200
Subject: [PATCH 058/359] fix(hls): scrub stills map the cached segment instead
 of copying it into the heap (audit SEG-2)

scrubThumbnailSource read the whole segment into the heap and concatenated it
with the init segment, two full copies per still, even when the extractor LRU
already held that segment. On a miss the concatenation was retained per LRU
entry, up to six, which on 4K sources is 180-600 MB of dirty memory. Resolving
the source now reads nothing, the caller builds a reader only on an LRU miss, and
that reader serves init.mp4 plus the memory-mapped segment file back to back
(DataIOReader takes parts). SegmentCache only replaces or unlinks segment files,
so a mapping stays valid.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 Sources/AetherEngine/AetherEngine+Live.swift  |  3 +-
 .../AetherEngine+ScrubThumbnail.swift         |  6 +-
 Sources/AetherEngine/IO/DataIOReader.swift    | 59 +++++++++++++-----
 .../AetherEngine/Video/HLSVideoEngine.swift   | 24 ++++++--
 .../ScrubThumbnailSegmentMappingTests.swift   | 61 +++++++++++++++++++
 5 files changed, 130 insertions(+), 23 deletions(-)
 create mode 100644 Tests/AetherEngineTests/ScrubThumbnailSegmentMappingTests.swift

diff --git a/Sources/AetherEngine/AetherEngine+Live.swift b/Sources/AetherEngine/AetherEngine+Live.swift
index 7f8101b60..1b37eee9e 100644
--- a/Sources/AetherEngine/AetherEngine+Live.swift
+++ b/Sources/AetherEngine/AetherEngine+Live.swift
@@ -38,7 +38,8 @@ extension AetherEngine {
             scrubThumbnailExtractors.append(hit)
             extractor = hit.extractor
         } else {
-            extractor = FrameExtractor(reader: DataIOReader(data: source.data), formatHint: "mp4")
+            guard let reader = source.makeReader() else { return nil }
+            extractor = FrameExtractor(reader: reader, formatHint: "mp4")
             scrubThumbnailExtractors.append((source.segmentIndex, extractor))
             while scrubThumbnailExtractors.count > 2 {
                 let evicted = scrubThumbnailExtractors.removeFirst()
diff --git a/Sources/AetherEngine/AetherEngine+ScrubThumbnail.swift b/Sources/AetherEngine/AetherEngine+ScrubThumbnail.swift
index feb8af635..ebff1fc35 100644
--- a/Sources/AetherEngine/AetherEngine+ScrubThumbnail.swift
+++ b/Sources/AetherEngine/AetherEngine+ScrubThumbnail.swift
@@ -5,7 +5,8 @@ extension AetherEngine {
 
     /// The 2026-09-02 Whole Title trace opened 30 software decoders in 20 seconds while
     /// scrubbing three resident 100 MB segments and back. Six keeps that small working set
-    /// warm; the segment bytes are already disk-backed and the bound remains fixed.
+    /// warm; each extractor maps its segment file (audit SEG-2), so the entries hold clean
+    /// file-backed pages rather than heap copies, and the bound remains fixed.
     nonisolated static let scrubThumbnailExtractorLimit = 6
 
     /// Cache-backed scrub still for the active native session (live or VOD). Decodes from
@@ -54,7 +55,8 @@ extension AetherEngine {
             scrubThumbnailExtractors.append(hit)
             extractor = hit.extractor
         } else {
-            extractor = FrameExtractor(reader: DataIOReader(data: source.data), formatHint: "mp4")
+            guard let reader = source.makeReader() else { return nil }
+            extractor = FrameExtractor(reader: reader, formatHint: "mp4")
             scrubThumbnailExtractors.append((source.segmentIndex, extractor))
             trimScrubThumbnailExtractors()
         }
diff --git a/Sources/AetherEngine/IO/DataIOReader.swift b/Sources/AetherEngine/IO/DataIOReader.swift
index abf473448..8b2db4078 100644
--- a/Sources/AetherEngine/IO/DataIOReader.swift
+++ b/Sources/AetherEngine/IO/DataIOReader.swift
@@ -1,43 +1,72 @@
 import Foundation
 
-/// In-memory `IOReader` over an immutable `Data` blob. Used by the scrub-thumbnail path: engine composes init.mp4 + cached segment into one buffer and demuxes via `FrameExtractor(reader:)`. NSLock makes read/seek safe off the demux thread.
+/// In-memory `IOReader` over immutable `Data` parts read back to back as one stream. The scrub-thumbnail
+/// path hands it init.mp4 plus a memory-mapped cached segment, so the segment is never copied into the heap
+/// (audit SEG-2: concatenating the two made two full heap copies per still, one retained per LRU entry).
+/// NSLock makes read/seek safe off the demux thread.
 final class DataIOReader: IOReader, @unchecked Sendable {
-    private let data: Data
+    private let parts: [Data]
+    private let partStarts: [Int]
+    private let totalCount: Int
     private var position = 0
     private let lock = NSLock()
 
-    init(data: Data) {
-        self.data = data
+    convenience init(data: Data) {
+        self.init(parts: [data])
+    }
+
+    init(parts: [Data]) {
+        self.parts = parts
+        var starts: [Int] = []
+        var offset = 0
+        for part in parts {
+            starts.append(offset)
+            offset += part.count
+        }
+        self.partStarts = starts
+        self.totalCount = offset
     }
 
     func read(_ buffer: UnsafeMutablePointer<UInt8>?, size: Int32) -> Int32 {
         guard let buffer, size > 0 else { return -1 }
         lock.lock()
         defer { lock.unlock() }
-        guard position < data.count else { return 0 }  // EOF
-        let n = min(Int(size), data.count - position)
-        data.copyBytes(
-            to: UnsafeMutableBufferPointer(start: buffer, count: n),
-            from: position..<(position + n)
-        )
-        position += n
-        return Int32(n)
+        guard position < totalCount else { return 0 }  // EOF
+        let n = min(Int(size), totalCount - position)
+        var copied = 0
+        var partIndex = (partStarts.lastIndex(where: { $0 <= position }) ?? 0)
+        while copied < n, partIndex < parts.count {
+            let part = parts[partIndex]
+            let offsetInPart = position + copied - partStarts[partIndex]
+            let take = min(n - copied, part.count - offsetInPart)
+            if take > 0 {
+                let lower = part.startIndex + offsetInPart
+                part.copyBytes(
+                    to: UnsafeMutableBufferPointer(start: buffer + copied, count: take),
+                    from: lower..<(lower + take)
+                )
+                copied += take
+            }
+            partIndex += 1
+        }
+        position += copied
+        return Int32(copied)
     }
 
     func seek(offset: Int64, whence: Int32) -> Int64 {
         // AVSEEK_SIZE (65536): report total length, do not move.
-        if whence == 65536 { return Int64(data.count) }
+        if whence == 65536 { return Int64(totalCount) }
         lock.lock()
         defer { lock.unlock() }
         let target: Int
         switch whence {
         case SEEK_SET: target = Int(offset)
         case SEEK_CUR: target = position + Int(offset)
-        case SEEK_END: target = data.count + Int(offset)
+        case SEEK_END: target = totalCount + Int(offset)
         default: return -1
         }
         guard target >= 0 else { return -1 }
-        position = min(target, data.count)
+        position = min(target, totalCount)
         return Int64(position)
     }
 
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine.swift b/Sources/AetherEngine/Video/HLSVideoEngine.swift
index bd1a86175..ea9fc71bb 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine.swift
@@ -2390,15 +2390,29 @@ public final class HLSVideoEngine: @unchecked Sendable {
         return prov?.sealedLiveTargetDurationSeconds
     }
 
-    func scrubThumbnailSource(atSeconds seconds: Double) -> (data: Data, segmentIndex: Int)? {
+    /// A resident segment a scrub still can decode from. Resolving it reads nothing, so an extractor
+    /// LRU hit costs no I/O; `makeReader()` maps the segment file rather than reading it into the heap
+    /// (audit SEG-2). SegmentCache only ever replaces or unlinks a segment file, never rewrites it in
+    /// place, so a mapping stays valid for as long as the reader holds it.
+    struct ScrubThumbnailSource: Sendable {
+        let segmentIndex: Int
+        let initData: Data
+        let segmentURL: URL
+
+        func makeReader() -> DataIOReader? {
+            guard let segment = try? Data(contentsOf: segmentURL, options: .alwaysMapped) else { return nil }
+            return DataIOReader(parts: [initData, segment])
+        }
+    }
+
+    func scrubThumbnailSource(atSeconds seconds: Double) -> ScrubThumbnailSource? {
         restartLock.lock()
         let prov = provider
         restartLock.unlock()
         guard let prov else { return nil }
-        guard let seg = prov.thumbnailSegment(atSeconds: seconds) else { return nil }
-        guard let initData = prov.peekInitSegment(),
-              let segData = try? Data(contentsOf: seg.fileURL) else { return nil }
-        return (initData + segData, seg.index)
+        guard let seg = prov.thumbnailSegment(atSeconds: seconds),
+              let initData = prov.peekInitSegment() else { return nil }
+        return ScrubThumbnailSource(segmentIndex: seg.index, initData: initData, segmentURL: seg.fileURL)
     }
 
     public func stop() {
diff --git a/Tests/AetherEngineTests/ScrubThumbnailSegmentMappingTests.swift b/Tests/AetherEngineTests/ScrubThumbnailSegmentMappingTests.swift
new file mode 100644
index 000000000..9df683e5b
--- /dev/null
+++ b/Tests/AetherEngineTests/ScrubThumbnailSegmentMappingTests.swift
@@ -0,0 +1,61 @@
+import Testing
+import Foundation
+@testable import AetherEngine
+
+/// Audit SEG-2: scrub stills read init.mp4 plus a mapped segment file as one stream instead of
+/// concatenating two heap copies. The reader must present exactly the bytes the concatenation did.
+@Suite("Scrub thumbnail segment mapping")
+struct ScrubThumbnailSegmentMappingTests {
+
+    private func readAll(_ reader: DataIOReader, chunk: Int32) -> [UInt8] {
+        var out: [UInt8] = []
+        var buffer = [UInt8](repeating: 0, count: Int(chunk))
+        while true {
+            let n = buffer.withUnsafeMutableBufferPointer { reader.read($0.baseAddress, size: chunk) }
+            if n <= 0 { break }
+            out += buffer[0..<Int(n)]
+        }
+        return out
+    }
+
+    @Test("a multi-part reader reads across the part boundary like one buffer")
+    func readsAcrossParts() {
+        let head = [UInt8](0..<7)
+        let tail = [UInt8](100..<150)
+        let reader = DataIOReader(parts: [Data(head), Data(), Data(tail)])
+        #expect(reader.seek(offset: 0, whence: 65536) == 57)
+        #expect(readAll(reader, chunk: 5) == head + tail)
+    }
+
+    @Test("seeks land on the right part, including SEEK_END and a slice with a nonzero start index")
+    func seeksAcrossParts() {
+        let backing = Data([UInt8](0..<20))
+        let slice = backing[10..<20]   // startIndex 10
+        let reader = DataIOReader(parts: [Data([0xAA, 0xBB]), slice])
+        #expect(reader.seek(offset: 3, whence: SEEK_SET) == 3)
+        #expect(readAll(reader, chunk: 4) == [UInt8](11..<20))
+        #expect(reader.seek(offset: -11, whence: SEEK_END) == 1)
+        #expect(readAll(reader, chunk: 64) == [0xBB] + [UInt8](10..<20))
+    }
+
+    @Test("the source maps the segment file and yields init followed by segment")
+    func sourceMapsSegmentFile() throws {
+        let dir = FileManager.default.temporaryDirectory
+            .appendingPathComponent("scrub-map-\(UUID().uuidString)", isDirectory: true)
+        try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
+        defer { try? FileManager.default.removeItem(at: dir) }
+        let segURL = dir.appendingPathComponent("seg-3.m4s")
+        let segBytes = (0..<4096).map { UInt8($0 & 0xFF) }
+        try Data(segBytes).write(to: segURL)
+        let initBytes: [UInt8] = [1, 2, 3, 4]
+
+        let source = HLSVideoEngine.ScrubThumbnailSource(
+            segmentIndex: 3, initData: Data(initBytes), segmentURL: segURL)
+        let reader = try #require(source.makeReader())
+        #expect(readAll(reader, chunk: 1000) == initBytes + segBytes)
+
+        let missing = HLSVideoEngine.ScrubThumbnailSource(
+            segmentIndex: 4, initData: Data(initBytes), segmentURL: dir.appendingPathComponent("gone.m4s"))
+        #expect(missing.makeReader() == nil, "an evicted segment is a nil still, not a crash")
+    }
+}

From ec659ab3b865acbc7c66ba7d02dba64342f5cd2b Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 05:49:15 +0200
Subject: [PATCH 059/359] fix(segments): bound demuxed timestamps and saturate
 the pump's tick arithmetic (audit SEG-1)

A crafted Matroska cluster time or a garbage live fMP4 tfdt (2^62 then -2^62) overflowed the
pump's plain Int64 subtraction and trapped the process. Source packets now pass through a bound
at the merge funnel that turns any timestamp beyond 2^60 into AV_NOPTS_VALUE, which the existing
NOPTS repair handles, and the rebase, glitch, shift and duration arithmetic saturates instead of
trapping.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 .../Video/HLSSegmentProducer.swift            | 70 ++++++++++++-------
 .../Video/SourceTimestampBounds.swift         | 46 ++++++++++++
 .../SourceTimestampBoundsTests.swift          | 64 +++++++++++++++++
 3 files changed, 153 insertions(+), 27 deletions(-)
 create mode 100644 Sources/AetherEngine/Video/SourceTimestampBounds.swift
 create mode 100644 Tests/AetherEngineTests/SourceTimestampBoundsTests.swift

diff --git a/Sources/AetherEngine/Video/HLSSegmentProducer.swift b/Sources/AetherEngine/Video/HLSSegmentProducer.swift
index 6f4eebd90..63bf04179 100644
--- a/Sources/AetherEngine/Video/HLSSegmentProducer.swift
+++ b/Sources/AetherEngine/Video/HLSSegmentProducer.swift
@@ -282,9 +282,9 @@ final class HLSSegmentProducer: @unchecked Sendable {
         oldShift: Int64,
         fallbackDurationPts: Int64
     ) -> (newShift: Int64, continuationDts: Int64) {
-        let lastOutputDts = lastSrcDts - oldShift
-        let continuationDts = lastOutputDts + max(fallbackDurationPts, 1)
-        return (srcDts - continuationDts, continuationDts)
+        let lastOutputDts = SourceTimestampBounds.difference(lastSrcDts, oldShift)
+        let continuationDts = SourceTimestampBounds.sum(lastOutputDts, max(fallbackDurationPts, 1))
+        return (SourceTimestampBounds.difference(srcDts, continuationDts), continuationDts)
     }
 
     /// Derive audio shift so boundary packet lands exactly on the video seam regardless of source base.
@@ -293,7 +293,7 @@ final class HLSSegmentProducer: @unchecked Sendable {
         audioBoundarySrcDts: Int64,
         seamOutAudioTb: Int64
     ) -> Int64 {
-        audioBoundarySrcDts - seamOutAudioTb
+        SourceTimestampBounds.difference(audioBoundarySrcDts, seamOutAudioTb)
     }
 
     /// Raw source PTS of the previous video packet (before shift); used for live discontinuity detection.
@@ -1324,7 +1324,7 @@ final class HLSSegmentProducer: @unchecked Sendable {
         guard firstSeenDts != Int64.min, tbSeconds > 0 else { return nil }
         let windowTicks = Int64(Self.sourceReplayStartWindowSeconds / tbSeconds)
         if jumpTicks < 0 {
-            return newDts <= firstSeenDts + windowTicks ? .rewind : nil
+            return newDts <= SourceTimestampBounds.sum(firstSeenDts, windowTicks) ? .rewind : nil
         }
         guard isLive, newDts >= Self.mpegTSWrapTicks else { return nil }
         return newDts % Self.mpegTSWrapTicks <= windowTicks ? .axisReset : nil
@@ -2681,14 +2681,16 @@ final class HLSSegmentProducer: @unchecked Sendable {
     private func readNextSourcePacketMerged() throws -> (packet: UnsafeMutablePointer<AVPacket>, origin: PacketOrigin)? {
         guard let side = sideAudioDemuxer else {
             guard let packet = try demuxer.readPacket() else { return nil }
+            boundSourceTimestamps(packet)
             return (packet, .main)
         }
         if mergeMainLookahead == nil, !mergeMainEOF {
             mergeMainLookahead = try demuxer.readPacket()
-            if mergeMainLookahead == nil { mergeMainEOF = true }
+            if let pkt = mergeMainLookahead { boundSourceTimestamps(pkt) } else { mergeMainEOF = true }
         }
         if mergeSideLookahead == nil, !mergeSideEOF {
             mergeSideLookahead = try side.readPacket()
+            if let pkt = mergeSideLookahead { boundSourceTimestamps(pkt) }
             if mergeSideLookahead == nil {
                 mergeSideEOF = true
             } else if packedSideAudioClock != nil, let pkt = mergeSideLookahead {
@@ -2715,6 +2717,20 @@ final class HLSSegmentProducer: @unchecked Sendable {
         return (main, .main)
     }
 
+    /// Pump-thread-only: an out-of-range source timestamp was logged once for this producer.
+    private var implausibleTimestampLogged = false
+
+    private func boundSourceTimestamps(_ packet: UnsafeMutablePointer<AVPacket>) {
+        let pts = packet.pointee.pts, dts = packet.pointee.dts
+        guard SourceTimestampBounds.sanitize(packet), !implausibleTimestampLogged else { return }
+        implausibleTimestampLogged = true
+        EngineLog.emit(
+            "[HLSSegmentProducer] source packet on stream \(packet.pointee.stream_index) carries an "
+            + "out-of-range timestamp (pts=\(pts) dts=\(dts)), treated as unset",
+            category: .session
+        )
+    }
+
     /// Ordering key: dts when valid, else pts; AV_NOPTS_VALUE (Int64.min) yields immediately (NOPTS repair handles it downstream).
     private static func mergeOrderingTicks(_ packet: UnsafeMutablePointer<AVPacket>) -> Int64 {
         if packet.pointee.dts != Int64.min { return packet.pointee.dts }
@@ -3109,7 +3125,7 @@ final class HLSSegmentProducer: @unchecked Sendable {
                 // adds #EXT-X-DISCONTINUITY at the seam.
                 if rebasesTimelineOnDiscontinuity, isVideoPkt, lastVideoSourceDts != Int64.min,
                    videoShiftPts != Int64.min, packet.pointee.dts != Int64.min {
-                    let jumpTicks = packet.pointee.dts - lastVideoSourceDts
+                    let jumpTicks = SourceTimestampBounds.difference(packet.pointee.dts, lastVideoSourceDts)
                     let thresholdSeconds = jumpTicks < 0
                         ? Self.discontinuityBackwardThresholdSeconds
                         : Self.discontinuityThresholdSeconds
@@ -3189,7 +3205,7 @@ final class HLSSegmentProducer: @unchecked Sendable {
                 if rebasesTimelineOnDiscontinuity, isAudioPkt, lastAudioSourceDts != Int64.min,
                    audioShiftPts != Int64.min, packet.pointee.dts != Int64.min,
                    let audio = audioConfig {
-                    let jumpTicks = packet.pointee.dts - lastAudioSourceDts
+                    let jumpTicks = SourceTimestampBounds.difference(packet.pointee.dts, lastAudioSourceDts)
                     let tb = audio.sourceTimeBase
                     let thresholdSeconds = jumpTicks < 0
                         ? Self.discontinuityBackwardThresholdSeconds
@@ -3214,10 +3230,10 @@ final class HLSSegmentProducer: @unchecked Sendable {
                             )
                             pendingAudioShiftOverride = nil
                         }
-                        let lastOutputDts = lastAudioSourceDts - audioShiftPts
+                        let lastOutputDts = SourceTimestampBounds.difference(lastAudioSourceDts, audioShiftPts)
                         // Independent measurement (audio-first boundary): used directly only when no video-derived shift available.
-                        let measuredShift = packet.pointee.dts
-                            - (lastOutputDts + max(audioFallbackDurationPts, 1))
+                        let measuredShift = SourceTimestampBounds.difference(
+                            packet.pointee.dts, SourceTimestampBounds.sum(lastOutputDts, max(audioFallbackDurationPts, 1)))
                         var newShift = measuredShift
                         var inherited = false
                         if let p = pendingAudioInheritSeamOut,
@@ -3229,7 +3245,7 @@ final class HLSSegmentProducer: @unchecked Sendable {
                             )
                             if let bridge = audio.bridge {
                                 // Bridge: free-running encoder restamps continuously; jump its timeline by the residual gap.
-                                let driftTicks = measuredShift - candidate
+                                let driftTicks = SourceTimestampBounds.difference(measuredShift, candidate)
                                 let tbSec = tb.den > 0
                                     ? Double(tb.num) / Double(tb.den) : 0
                                 bridge.noteTimelineJump(
@@ -3240,14 +3256,14 @@ final class HLSSegmentProducer: @unchecked Sendable {
                                 // Stream-copy: apply candidate verbatim (absolute, not clamped to lastOutputDts).
                                 // Delta handoff accumulated A/V drift across SSAI pod creatives (device symptom: seconds late by content return).
                                 // Sub-frame overlap at the seam left to OutputTimestampSanitizer; > 0.5 s re-anchors.
-                                let firstOutputDts = packet.pointee.dts - candidate
+                                let firstOutputDts = SourceTimestampBounds.difference(packet.pointee.dts, candidate)
                                 let overlapTicks = lastOutputDts - firstOutputDts
                                 let maxOverlapTicks = audio.sourceTimeBase.num > 0
                                     ? Int64(0.5 * Double(audio.sourceTimeBase.den)
                                             / Double(audio.sourceTimeBase.num))
                                     : Int64.max
                                 if overlapTicks > maxOverlapTicks {
-                                    newShift = packet.pointee.dts - lastOutputDts - 1
+                                    newShift = SourceTimestampBounds.difference(SourceTimestampBounds.difference(packet.pointee.dts, lastOutputDts), 1)
                                     EngineLog.emit(
                                         "[HLSSegmentProducer] audio rebase inherit re-anchored: "
                                         + "candidate=\(candidate) overlap=\(overlapTicks) ticks "
@@ -3284,7 +3300,7 @@ final class HLSSegmentProducer: @unchecked Sendable {
                         if Date().timeIntervalSince(override_.at) < Self.rebasePairingWindowSeconds {
                             if let bridge = audio.bridge {
                                 // Bridge: residual between applied and video-derived shift becomes an encoder-timeline jump.
-                                let driftTicks = audioShiftPts - derivedShift
+                                let driftTicks = SourceTimestampBounds.difference(audioShiftPts, derivedShift)
                                 let tbSec = tb.den > 0
                                     ? Double(tb.num) / Double(tb.den) : 0
                                 bridge.noteTimelineJump(
@@ -3297,14 +3313,14 @@ final class HLSSegmentProducer: @unchecked Sendable {
                             } else {
                                 // Stream-copy: apply seam-derived shift; sub-frame overlap left to OutputTimestampSanitizer;
                                 // only > 0.5 s overlap re-anchors.
-                                let lastOutputDts = lastAudioSourceDts - audioShiftPts
-                                let firstOutputDts = override_.boundarySrcDts - derivedShift
+                                let lastOutputDts = SourceTimestampBounds.difference(lastAudioSourceDts, audioShiftPts)
+                                let firstOutputDts = SourceTimestampBounds.difference(override_.boundarySrcDts, derivedShift)
                                 let overlapTicks = lastOutputDts - firstOutputDts
                                 let maxOverlapTicks = tb.num > 0
                                     ? Int64(0.5 * Double(tb.den) / Double(tb.num))
                                     : Int64.max
                                 let applied = overlapTicks > maxOverlapTicks
-                                    ? packet.pointee.dts - lastOutputDts - 1
+                                    ? SourceTimestampBounds.difference(SourceTimestampBounds.difference(packet.pointee.dts, lastOutputDts), 1)
                                     : derivedShift
                                 EngineLog.emit(
                                     "[HLSSegmentProducer] audio rebase corrected to video-derived shift: "
@@ -3332,7 +3348,7 @@ final class HLSSegmentProducer: @unchecked Sendable {
                 if isVideoPkt, lastVideoSourceDts != Int64.min,
                    packet.pointee.dts != Int64.min,
                    packet.pointee.dts <= lastVideoSourceDts,
-                   lastVideoSourceDts - packet.pointee.dts <= monoGlitchVideoTicks {
+                   SourceTimestampBounds.difference(lastVideoSourceDts, packet.pointee.dts) <= monoGlitchVideoTicks {
                     let original = packet.pointee.dts
                     let bumped = lastVideoSourceDts + 1
                     let ptsValid = packet.pointee.pts != Int64.min
@@ -3370,7 +3386,7 @@ final class HLSSegmentProducer: @unchecked Sendable {
                 if isAudioPkt, lastAudioSourceDts != Int64.min,
                    packet.pointee.dts != Int64.min,
                    packet.pointee.dts <= lastAudioSourceDts,
-                   lastAudioSourceDts - packet.pointee.dts <= monoGlitchAudioTicks {
+                   SourceTimestampBounds.difference(lastAudioSourceDts, packet.pointee.dts) <= monoGlitchAudioTicks {
                     // Same logic for audio. Audio doesn't have B-frame
                     // pts/dts skew so dts <= pts isn't a useful gate;
                     // just bump.
@@ -3539,7 +3555,7 @@ final class HLSSegmentProducer: @unchecked Sendable {
                             actualFirstDts: firstActualVideoDts,
                             desiredTfdtPts: desiredFirstVideoTfdtPts,
                             planAnchorPts: planAnchorVideoPts)
-                        videoShiftPts = firstActualVideoDts - pinnedTfdtPts
+                        videoShiftPts = SourceTimestampBounds.difference(firstActualVideoDts, pinnedTfdtPts)
                         if audioWaitForVideo, let audio = audioConfig {
                             // Rescale into SOURCE audio TB (not encoder TB): FLAC bridge exposes this mismatch;
                             // using inputTimeBase landed the target 48x too far for bridged DTS sources.
@@ -3726,7 +3742,7 @@ final class HLSSegmentProducer: @unchecked Sendable {
                         } else {
                             gapInAudioTb = restartTargetAudioDts == Int64.min
                                 ? 0
-                                : firstActualAudioDts - restartTargetAudioDts
+                                : SourceTimestampBounds.difference(firstActualAudioDts, restartTargetAudioDts)
                         }
                         let gapMs = audioTb.den > 0
                             ? Double(gapInAudioTb) * Double(audioTb.num) * 1000.0 / Double(audioTb.den)
@@ -3760,7 +3776,7 @@ final class HLSSegmentProducer: @unchecked Sendable {
                    packet.pointee.pts != Int64.min {
                     let rawPts = packet.pointee.pts
                     if lastRawVideoPts != Int64.min {
-                        let deltaTicks = rawPts - lastRawVideoPts
+                        let deltaTicks = SourceTimestampBounds.difference(rawPts, lastRawVideoPts)
                         let deltaSeconds = Double(deltaTicks) * sourceVideoTbSeconds
                         if abs(deltaSeconds) >= Self.discontinuityThresholdSeconds {
                             pendingDiscontinuityFlag = true
@@ -3784,10 +3800,10 @@ final class HLSSegmentProducer: @unchecked Sendable {
                 let activeShift: Int64 = isVideoPkt ? videoShiftPts : audioShiftPts
                 if activeShift != Int64.min && activeShift != 0 {
                     if packet.pointee.dts != Int64.min {
-                        packet.pointee.dts -= activeShift
+                        packet.pointee.dts = SourceTimestampBounds.difference(packet.pointee.dts, activeShift)
                     }
                     if packet.pointee.pts != Int64.min {
-                        packet.pointee.pts -= activeShift
+                        packet.pointee.pts = SourceTimestampBounds.difference(packet.pointee.pts, activeShift)
                     }
                 }
 
@@ -4206,7 +4222,7 @@ final class HLSSegmentProducer: @unchecked Sendable {
         capTicks: Int64
     ) -> Int64 {
         if let next = nextDts, dts != Int64.min, next != Int64.min {
-            let inferred = next - dts
+            let inferred = SourceTimestampBounds.difference(next, dts)
             if inferred > 0, inferred <= capTicks { return inferred }
         }
         return existingDuration > 0 && existingDuration <= capTicks ? existingDuration : fallback
@@ -4342,7 +4358,7 @@ final class HLSSegmentProducer: @unchecked Sendable {
     ) {
         if packet.pointee.duration <= 0 {
             if let next = nextDts {
-                let inferred = next - packet.pointee.dts
+                let inferred = SourceTimestampBounds.difference(next, packet.pointee.dts)
                 packet.pointee.duration = inferred > 0 ? inferred : audioFallbackDurationPts
             } else {
                 packet.pointee.duration = audioFallbackDurationPts
diff --git a/Sources/AetherEngine/Video/SourceTimestampBounds.swift b/Sources/AetherEngine/Video/SourceTimestampBounds.swift
new file mode 100644
index 000000000..fbb61fee2
--- /dev/null
+++ b/Sources/AetherEngine/Video/SourceTimestampBounds.swift
@@ -0,0 +1,46 @@
+import Foundation
+import AetherLibavcodec
+
+/// Audit SEG-1: demuxed timestamps reach the pump unchecked (matroskadec stores a uint64 cluster
+/// time into an int64 pts, a live fMP4 tfdt is whatever the origin wrote), and Swift traps on
+/// Int64 overflow. Values outside `plausibleMagnitude` become AV_NOPTS_VALUE at the source funnel,
+/// which the pump's NOPTS repair already handles, and the tick arithmetic downstream saturates
+/// instead of trapping.
+enum SourceTimestampBounds {
+
+    /// 2^60 still holds an epoch-anchored tfdt at a 10 MHz timescale by three orders of magnitude,
+    /// and leaves room for the pump's three-term shift chains below 2^63.
+    static let plausibleMagnitude: Int64 = 1 << 60
+
+    static func plausible(_ ticks: Int64) -> Int64 {
+        guard ticks != Int64.min else { return ticks }
+        return ticks > -plausibleMagnitude && ticks < plausibleMagnitude ? ticks : Int64.min
+    }
+
+    /// Returns whether any field was out of range and got replaced.
+    @discardableResult
+    static func sanitize(_ packet: UnsafeMutablePointer<AVPacket>) -> Bool {
+        let pts = plausible(packet.pointee.pts)
+        let dts = plausible(packet.pointee.dts)
+        let duration = packet.pointee.duration
+        let durationOK = duration >= 0 && duration < plausibleMagnitude
+        guard pts != packet.pointee.pts || dts != packet.pointee.dts || !durationOK else { return false }
+        packet.pointee.pts = pts
+        packet.pointee.dts = dts
+        if !durationOK { packet.pointee.duration = 0 }
+        return true
+    }
+
+    /// Saturating tick arithmetic. The floor is `Int64.min + 1` so a result never reads as AV_NOPTS_VALUE.
+    static func difference(_ lhs: Int64, _ rhs: Int64) -> Int64 {
+        let (value, overflow) = lhs.subtractingReportingOverflow(rhs)
+        guard overflow else { return max(value, Int64.min + 1) }
+        return lhs < rhs ? Int64.min + 1 : Int64.max
+    }
+
+    static func sum(_ lhs: Int64, _ rhs: Int64) -> Int64 {
+        let (value, overflow) = lhs.addingReportingOverflow(rhs)
+        guard overflow else { return max(value, Int64.min + 1) }
+        return lhs < 0 ? Int64.min + 1 : Int64.max
+    }
+}
diff --git a/Tests/AetherEngineTests/SourceTimestampBoundsTests.swift b/Tests/AetherEngineTests/SourceTimestampBoundsTests.swift
new file mode 100644
index 000000000..28bcb5c5f
--- /dev/null
+++ b/Tests/AetherEngineTests/SourceTimestampBoundsTests.swift
@@ -0,0 +1,64 @@
+import Testing
+import AetherLibavcodec
+@testable import AetherEngine
+
+/// Audit SEG-1: a crafted Matroska cluster time or a garbage live tfdt must degrade a packet, not
+/// trap the pump on Int64 overflow.
+struct SourceTimestampBoundsTests {
+
+    private func withPacket(pts: Int64, dts: Int64, duration: Int64 = 0,
+                            _ body: (UnsafeMutablePointer<AVPacket>) -> Void) throws {
+        let packet = try #require(av_packet_alloc())
+        defer {
+            var owned: UnsafeMutablePointer<AVPacket>? = packet
+            av_packet_free(&owned)
+        }
+        packet.pointee.pts = pts
+        packet.pointee.dts = dts
+        packet.pointee.duration = duration
+        body(packet)
+    }
+
+    @Test func extremeSourceTimestampsBecomeUnset() throws {
+        try withPacket(pts: Int64(1) << 62, dts: -(Int64(1) << 62), duration: -5) { packet in
+            #expect(SourceTimestampBounds.sanitize(packet))
+            #expect(packet.pointee.pts == Int64.min)
+            #expect(packet.pointee.dts == Int64.min)
+            #expect(packet.pointee.duration == 0)
+        }
+    }
+
+    @Test func plausibleTimestampsPassUntouched() throws {
+        // An epoch-anchored live tfdt at a 10 MHz timescale sits near 1.8e16.
+        let epochTfdt: Int64 = 1_790_000_000 * 10_000_000
+        try withPacket(pts: epochTfdt + 400_000, dts: epochTfdt, duration: 400_000) { packet in
+            #expect(!SourceTimestampBounds.sanitize(packet))
+            #expect(packet.pointee.pts == epochTfdt + 400_000)
+            #expect(packet.pointee.dts == epochTfdt)
+            #expect(packet.pointee.duration == 400_000)
+        }
+        try withPacket(pts: Int64.min, dts: -1800) { packet in
+            #expect(!SourceTimestampBounds.sanitize(packet))
+            #expect(packet.pointee.pts == Int64.min)
+        }
+    }
+
+    @Test func tickArithmeticSaturatesInsteadOfTrapping() {
+        let big = Int64(1) << 62
+        #expect(SourceTimestampBounds.difference(big, -big) == Int64.max)
+        #expect(SourceTimestampBounds.difference(-big, big) == Int64.min + 1)
+        #expect(SourceTimestampBounds.sum(Int64.max, 1) == Int64.max)
+        #expect(SourceTimestampBounds.sum(Int64.min + 1, -2) == Int64.min + 1)
+        #expect(SourceTimestampBounds.difference(90_000, 1800) == 88_200)
+    }
+
+    @Test func rebaseMathSurvivesOppositeSignExtremes() {
+        let big = Int64(1) << 62
+        let shifted = HLSSegmentProducer.rebasedVideoShift(
+            srcDts: -big, lastSrcDts: big, oldShift: -big, fallbackDurationPts: 1800)
+        #expect(shifted.continuationDts == Int64.max)
+        #expect(HLSSegmentProducer.seamDerivedAudioShift(audioBoundarySrcDts: big, seamOutAudioTb: -big) == Int64.max)
+        #expect(HLSSegmentProducer.resolveVideoSampleDuration(
+            existingDuration: 0, dts: big, nextDts: -big, fallback: 1800, capTicks: 90_000) == 1800)
+    }
+}

From 52250c0ba1e647ffd004509666ad3aed1cfbb7fb Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 05:51:09 +0200
Subject: [PATCH 060/359] fix(segments): stop riding a restart once the segment
 cache is closed (audit SEG-3)

A closed SegmentCache answers fetch immediately, and while a restart outlived stop() the ride
loop neither counted attempts nor slept, so every waiting serve thread spun at full CPU until the
restart finished or the 90 s ride cap. The loop now ends as soon as the cache reports closed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 Sources/AetherEngine/Video/SegmentCache.swift |  6 +++++
 .../Video/VideoSegmentProvider.swift          |  3 +++
 .../SegmentFetchWaitTests.swift               | 22 +++++++++++++++++++
 3 files changed, 31 insertions(+)

diff --git a/Sources/AetherEngine/Video/SegmentCache.swift b/Sources/AetherEngine/Video/SegmentCache.swift
index 95c202d1c..5a3877f8f 100644
--- a/Sources/AetherEngine/Video/SegmentCache.swift
+++ b/Sources/AetherEngine/Video/SegmentCache.swift
@@ -457,6 +457,12 @@ final class SegmentCache: @unchecked Sendable {
                        category: .session)
     }
 
+    var isClosed: Bool {
+        condition.lock()
+        defer { condition.unlock() }
+        return closed
+    }
+
     func fetch(index: Int, timeout: TimeInterval = 15.0) -> Data? {
         condition.lock()
         if let url = entries[index] {
diff --git a/Sources/AetherEngine/Video/VideoSegmentProvider.swift b/Sources/AetherEngine/Video/VideoSegmentProvider.swift
index 286e414f0..1c39c96d6 100644
--- a/Sources/AetherEngine/Video/VideoSegmentProvider.swift
+++ b/Sources/AetherEngine/Video/VideoSegmentProvider.swift
@@ -1570,6 +1570,9 @@ final class VideoSegmentProvider: HLSSegmentProvider, @unchecked Sendable {
                 if let bytes = cache.fetch(index: index, timeout: repositionWaitSlice) {
                     return logServed(index: index, bytes: bytes, totalStart: totalStart, restarted: true)
                 }
+                // Audit SEG-3: a closed cache answers fetch at once, so riding a restart that
+                // outlives stop() would spin this thread until the ride cap.
+                if cache.isClosed { break }
             }
             return logServed(index: index, bytes: nil, totalStart: totalStart, restarted: true)
         }
diff --git a/Tests/AetherEngineTests/SegmentFetchWaitTests.swift b/Tests/AetherEngineTests/SegmentFetchWaitTests.swift
index e6975e08e..c7af72054 100644
--- a/Tests/AetherEngineTests/SegmentFetchWaitTests.swift
+++ b/Tests/AetherEngineTests/SegmentFetchWaitTests.swift
@@ -120,6 +120,28 @@ struct SegmentFetchWaitTests {
         #expect(elapsed >= 0.3)
     }
 
+    @Test("a fetch riding a restart that outlives close() returns instead of spinning")
+    func rideStopsWhenCacheCloses() {
+        let cache = SegmentCache(forwardWindow: 10, backwardWindow: 10)
+        storeAbove(cache, range: 45...50)
+        cache.close()
+        let recorder = Recorder()
+        let polls = PollCounter()
+        let provider = VideoSegmentProvider(
+            cache: cache, segments: segments(60), codecsString: "hvc1", supplementalCodecs: nil,
+            resolution: (1920, 1080), videoRange: .sdr, frameRate: 24.0, hdcpLevel: nil,
+            sourceBitrate: 8_000_000,
+            restartHandler: { idx in recorder.record(idx) },
+            restartActivity: { _ = polls.increment(); return true },
+            initialRestartIndex: 0,
+            repositionWaitSlice: 0.05,
+            repositionRideCapSeconds: 30.0
+        )
+        let served = provider.mediaSegment(at: 40)
+        #expect(served == nil)
+        #expect(polls.increment() <= 3)
+    }
+
     @Test("resume-anchored provider cold-waits at the anchor instead of restarting the producer")
     func resumeAnchorColdStart() {
         let cache = SegmentCache(forwardWindow: 10, backwardWindow: 10)

From c72d51ba8b640492aafa1c5a6fb86e2459e43049 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 05:51:56 +0200
Subject: [PATCH 061/359] docs(changelog): audit HLS engine fixes

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 CHANGELOG.md | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 504b2a52d..8944baef6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -32,6 +32,22 @@ the public-API contract.
 
 ### Fixed
 
+- **A slow source no longer ends a healthy session with "Source read failed" after a few scrubs.**
+  When the engine replaced a producer stuck in a read, the old producer's aborted read was treated as
+  the session failing: it spent the read-error revive budget, forced an extra reconnect and re-seeked
+  to a stale position. Exits from replaced producers and reads aborted by a stop are now ignored
+  (audit HLS-1).
+- **Changing channel during a live reconnect no longer opens the old channel again**, which on
+  single-connection tuners took the slot the new channel needed. A stop that lands during an open
+  now cancels it (audit HLS-2).
+- **8-bit HEVC in MPEG-TS is no longer advertised as Main10.** The CODECS string for Annex-B HEVC is
+  read from the stream's SPS, so the master playlist matches the init segment (audit HLS-3).
+- **Seeks that need a re-cut stay within their time limit** on slow sources (audit HLS-4).
+- **AV1 4:4:4, 4:2:2 and 12-bit play on devices with hardware AV1.** Apple's decoder handles AV1 Main
+  profile only; other profiles now take the dav1d software path for VOD (audit HLS-5).
+- **Scrub previews on large segments use far less memory.** The segment file is memory-mapped instead
+  of copied twice per preview, and nothing is read when a cached preview decoder already covers the
+  segment (audit SEG-2).
 - **Leaving a session while its software rebuild is running no longer leaves an error behind.** A
   `stop()` or new `load()` during the AE#561 rebuild used to put the engine into `.error`, including
   onto the next title's startup. The rebuild also runs in its own task now, so its waits no longer

From e4596cded750d8f8234c7e4ac6733ab9aba8917e Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 05:53:20 +0200
Subject: [PATCH 062/359] fix(segments): give every stored segment generation
 its own file (audit SEG-4)

SegmentCache.adopt replaced a resident segment with remove then move on the same path, and
entries were matched by that path. A reader that hit the gap could drop the freshly adopted
entry (its URL compared equal), and a prune deleting a doomed URL after unlocking could unlink a
newer adoption of the same index. Each store or adopt now gets a unique file name, the
superseded generation is deleted after the bookkeeping moved on, and a URL names exactly one set
of bytes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 Sources/AetherEngine/Video/SegmentCache.swift | 34 ++++++++++++++-----
 .../Issue451SessionSweepLivenessTests.swift   |  4 +--
 .../AetherEngineTests/SegmentCacheTests.swift | 28 +++++++++++++++
 3 files changed, 56 insertions(+), 10 deletions(-)

diff --git a/Sources/AetherEngine/Video/SegmentCache.swift b/Sources/AetherEngine/Video/SegmentCache.swift
index 5a3877f8f..2452511d5 100644
--- a/Sources/AetherEngine/Video/SegmentCache.swift
+++ b/Sources/AetherEngine/Video/SegmentCache.swift
@@ -2,7 +2,7 @@ import Darwin
 import Foundation
 
 /// Sliding-window disk-backed cache for HLS-fMP4 segments. Bytes go to
-/// <NSTemporaryDirectory>/aether-segments/<uuid>/seg-N.m4s; only URLs stay in RAM.
+/// <NSTemporaryDirectory>/aether-segments/<uuid>/seg-N-G.m4s; only URLs stay in RAM.
 /// Reads use .alwaysMapped (kernel pages in/out under memory pressure). Window:
 /// [currentTargetIndex - backwardWindow, currentTargetIndex + forwardWindow].
 /// The producer pauses via awaitFetchHighWater once forwardWindow ahead of target.
@@ -88,6 +88,19 @@ final class SegmentCache: @unchecked Sendable {
     /// Monotonic across prunes; NOT decremented by pruneOutsideWindow. Lets VideoSegmentProvider
     /// detect gaps below the producer's write head after eviction erases them from indexRange().
     private var _highestStoredIndex: Int = -1
+
+    /// Audit SEG-4: every stored generation of an index gets its own file name, so a URL names exactly
+    /// one set of bytes. A reader dropping a vanished entry, or a prune deleting a doomed one after
+    /// unlocking, can then never hit a newer adoption of the same index.
+    private var fileGeneration: UInt64 = 0
+
+    private func nextSegmentFileURL(index: Int) -> URL {
+        condition.lock()
+        fileGeneration += 1
+        let generation = fileGeneration
+        condition.unlock()
+        return sessionDir.appendingPathComponent("seg-\(index)-\(generation).m4s")
+    }
     /// Plan index -> how many pumps passed it without opening a segment (#358). Survives producer
     /// restarts on purpose: the repeat across a restart is the signal.
     private var foldCounts: [Int: Int] = [:]
@@ -264,7 +277,7 @@ final class SegmentCache: @unchecked Sendable {
     }
 
     func store(index: Int, data: Data) {
-        let fileURL = sessionDir.appendingPathComponent("seg-\(index).m4s")
+        let fileURL = nextSegmentFileURL(index: index)
         var writeOK: Bool
         do {
             try data.write(to: fileURL, options: [.atomic])
@@ -289,11 +302,14 @@ final class SegmentCache: @unchecked Sendable {
         // A re-store of a resident index changes bytes, not residency; only an insertion or an
         // eviction moves the set, and both are already known here without walking it.
         var residentSetChanged = false
+        var supersededFile: URL?
         if writeOK {
             if let oldBytes = entryBytes[index] {
                 _totalBytes -= oldBytes
             }
-            residentSetChanged = entries.updateValue(fileURL, forKey: index) == nil
+            let superseded = entries.updateValue(fileURL, forKey: index)
+            residentSetChanged = superseded == nil
+            if let superseded { supersededFile = superseded }
             entryBytes[index] = data.count
             _totalBytes += data.count
             if index > _highestStoredIndex { _highestStoredIndex = index }
@@ -302,6 +318,7 @@ final class SegmentCache: @unchecked Sendable {
         if !doomed.isEmpty { residentSetChanged = true }
         condition.broadcast()
         condition.unlock()
+        if let supersededFile { try? FileManager.default.removeItem(at: supersededFile) }
         for url in doomed { try? FileManager.default.removeItem(at: url) }
         if residentSetChanged { onResidentSetChanged?() }
     }
@@ -311,12 +328,9 @@ final class SegmentCache: @unchecked Sendable {
     /// `videoReach` (AE#412) is what this segment's video offers a cold arrival; nil leaves the
     /// previous claim in place only if the index is re-adopted without one, which no caller does.
     func adopt(index: Int, stagingPath: URL, byteCount: Int, videoReach: VideoReach? = nil) {
-        let fileURL = sessionDir.appendingPathComponent("seg-\(index).m4s")
+        let fileURL = nextSegmentFileURL(index: index)
         var renameOK: Bool
         do {
-            if FileManager.default.fileExists(atPath: fileURL.path) {
-                try FileManager.default.removeItem(at: fileURL)
-            }
             try FileManager.default.moveItem(at: stagingPath, to: fileURL)
             renameOK = true
         } catch {
@@ -338,11 +352,14 @@ final class SegmentCache: @unchecked Sendable {
             return
         }
         var residentSetChanged = false
+        var supersededFile: URL?
         if renameOK {
             if let oldBytes = entryBytes[index] {
                 _totalBytes -= oldBytes
             }
-            residentSetChanged = entries.updateValue(fileURL, forKey: index) == nil
+            let superseded = entries.updateValue(fileURL, forKey: index)
+            residentSetChanged = superseded == nil
+            if let superseded { supersededFile = superseded }
             entryBytes[index] = byteCount
             _totalBytes += byteCount
             if index > _highestStoredIndex { _highestStoredIndex = index }
@@ -357,6 +374,7 @@ final class SegmentCache: @unchecked Sendable {
         if !doomed.isEmpty { residentSetChanged = true }
         condition.broadcast()
         condition.unlock()
+        if let supersededFile { try? FileManager.default.removeItem(at: supersededFile) }
         for url in doomed { try? FileManager.default.removeItem(at: url) }
         if residentSetChanged { onResidentSetChanged?() }
     }
diff --git a/Tests/AetherEngineTests/Issue451SessionSweepLivenessTests.swift b/Tests/AetherEngineTests/Issue451SessionSweepLivenessTests.swift
index ed8e3cd1d..d46838302 100644
--- a/Tests/AetherEngineTests/Issue451SessionSweepLivenessTests.swift
+++ b/Tests/AetherEngineTests/Issue451SessionSweepLivenessTests.swift
@@ -111,7 +111,7 @@ struct Issue451SessionSweepLivenessTests {
         #expect(c.totalBytes == 512)
 
         // Whatever removed it (a sibling's sweep, the OS reclaiming tmp) is outside this class.
-        try? FileManager.default.removeItem(at: c.sessionDir.appendingPathComponent("seg-4.m4s"))
+        if let url = c.peekURL(index: 4) { try? FileManager.default.removeItem(at: url) }
 
         #expect(c.peekURL(index: 4) == nil,
                 "a URL handed to a response must name a file that exists")
@@ -127,7 +127,7 @@ struct Issue451SessionSweepLivenessTests {
         let c = SegmentCache(baseDirectory: base)
         defer { c.close() }
         c.store(index: 2, data: Data(repeating: 0xDD, count: 64))
-        try? FileManager.default.removeItem(at: c.sessionDir.appendingPathComponent("seg-2.m4s"))
+        if let url = c.peekURL(index: 2) { try? FileManager.default.removeItem(at: url) }
 
         // The serve that finds nothing answers a retriable 503; without dropping the entry, the
         // next fetch takes the same branch and the producer is never asked to make it again.
diff --git a/Tests/AetherEngineTests/SegmentCacheTests.swift b/Tests/AetherEngineTests/SegmentCacheTests.swift
index e30386e4e..74011795c 100644
--- a/Tests/AetherEngineTests/SegmentCacheTests.swift
+++ b/Tests/AetherEngineTests/SegmentCacheTests.swift
@@ -31,6 +31,34 @@ struct SegmentCacheTests {
         #expect(c.totalBytes == 250)
     }
 
+    @Test("A re-adopted index gets a fresh file and retires the previous one (audit SEG-4)")
+    func readoptionNeverReusesAPath() throws {
+        let c = SegmentCache(forwardWindow: 5, backwardWindow: 5)
+        defer { c.close() }
+        func staged(_ n: Int, fill: UInt8) throws -> URL {
+            let url = c.sessionDir.appendingPathComponent("staging-\(UUID().uuidString).tmp")
+            try makeData(n, fill: fill).write(to: url)
+            return url
+        }
+        c.adopt(index: 3, stagingPath: try staged(100, fill: 0x01), byteCount: 100)
+        let first = try #require(c.peekURL(index: 3))
+        c.adopt(index: 3, stagingPath: try staged(250, fill: 0x02), byteCount: 250)
+        let second = try #require(c.peekURL(index: 3))
+
+        // A reader that resolved the first URL and finds it gone must not be able to drop the
+        // second adoption, which it could while both generations shared one path.
+        #expect(first != second)
+        #expect(!FileManager.default.fileExists(atPath: first.path))
+        #expect(c.fetch(index: 3, timeout: 0.1)?.first == 0x02)
+        #expect(c.count == 1)
+        #expect(c.totalBytes == 250)
+
+        c.store(index: 3, data: makeData(40, fill: 0x03))
+        #expect(!FileManager.default.fileExists(atPath: second.path))
+        #expect(c.peek(index: 3)?.first == 0x03)
+        #expect(c.totalBytes == 40)
+    }
+
     @Test("Backward refetch does not evict already-produced forward segments")
     func backwardRefetchKeepsForward() {
         // forwardWindow small, backwardWindow wide so production never prunes the trailing end.

From 607a0ef0b56b8685aa3ea7a859514e1571c8f0dc Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 05:54:23 +0200
Subject: [PATCH 063/359] fix(segments): an abandoned pump never cuts a segment
 after stop (audit SEG-5)

advanceMuxer finalized and adopted the in-flight segment before any stop check, so a pump
abandoned mid-read that woke up with a packet from the new producer's seek position could store
its partial segment under a full index and EXTINF. The cut and the program-switch rotation now
return early once stop was requested, and the existing teardown rule decides the in-flight
segment (VOD discards a non-EOF partial).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 Sources/AetherEngine/Video/HLSSegmentProducer.swift | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/Sources/AetherEngine/Video/HLSSegmentProducer.swift b/Sources/AetherEngine/Video/HLSSegmentProducer.swift
index 63bf04179..a7e908bcc 100644
--- a/Sources/AetherEngine/Video/HLSSegmentProducer.swift
+++ b/Sources/AetherEngine/Video/HLSSegmentProducer.swift
@@ -1666,6 +1666,7 @@ final class HLSSegmentProducer: @unchecked Sendable {
     }
 
     private func rotateMuxerForProgramSwitch(to newIdx: Int) -> MP4SegmentMuxer? {
+        if checkShouldStop() { return nil }
         let finishedIdx = currentMuxerSegmentIndex
         finalizeSessionMuxerAndAdopt() // adopts finishedIdx, nils currentMuxer
         pendingVideoProgramSwitch = false
@@ -2286,6 +2287,10 @@ final class HLSSegmentProducer: @unchecked Sendable {
 
     private func advanceMuxer(to newIdx: Int) -> MP4SegmentMuxer? {
         guard let muxer = currentMuxer else { return nil }
+        // Audit SEG-5: an abandoned pump whose blocked read returns after stop() gets a packet from
+        // the NEW producer's position. Cutting on it would adopt this pump's partial segment under
+        // its full index; the teardown rule decides what happens to the in-flight segment instead.
+        if checkShouldStop() { return nil }
 
         switch muxer.cutFragmentForNextSegment(newIdx) {
         case .completed(let path, let bytesWritten):

From 4f70aa7e04a0494a2b3de729a4cb0806042abffe Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 05:54:28 +0200
Subject: [PATCH 064/359] fix(decoder): a flush between the epoch check and the
 send retires the packet too (audit DEC-1, DEC-4)

SoftwareVideoDecoder retried an EAGAIN send after draining, and the drain
drops the lock between frames, so a seek's flush could land there and the
retry sent the pre-seek packet into the flushed decoder (the AE#492 wedge).
The retry now re-checks the feed epoch under the lock.

HardwareVideoDecoder checked the epoch, released the lock, then built the
sample buffer and called VTDecompressionSessionDecodeFrame unlocked. The
epoch is now re-checked and the frame sent under one hold of the lock.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 Sources/AetherEngine/Decoder/HardwareVideoDecoder.swift | 9 ++++++++-
 Sources/AetherEngine/Decoder/SoftwareVideoDecoder.swift | 2 ++
 2 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/Sources/AetherEngine/Decoder/HardwareVideoDecoder.swift b/Sources/AetherEngine/Decoder/HardwareVideoDecoder.swift
index 8f3499ba4..603bf34a1 100644
--- a/Sources/AetherEngine/Decoder/HardwareVideoDecoder.swift
+++ b/Sources/AetherEngine/Decoder/HardwareVideoDecoder.swift
@@ -222,7 +222,7 @@ final class HardwareVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
         lock.lock()
         // AE#492: see `SoftwareVideoDecoder.decode`. Same rule, same lock as `flush()`.
         if let epoch, epoch != _feedEpoch { lock.unlock(); return }
-        guard let session = session, let formatDesc = formatDescription else {
+        guard session != nil, let formatDesc = formatDescription else {
             lock.unlock()
             return
         }
@@ -304,6 +304,12 @@ final class HardwareVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
             }
         }
 
+        // Audit DEC-4: the epoch check and the send sit under one hold of `lock`, or a flush landing
+        // while the sample buffer is built lets a pre-seek packet into VT after it. Safe to hold:
+        // the output callback never takes `lock`, and `close()` already holds it across the VT wait.
+        lock.lock()
+        if let epoch, epoch != _feedEpoch { lock.unlock(); return }
+        guard let session = self.session else { lock.unlock(); return }
         // Async decode with temporal queueing; callback fires on VT's internal queue.
         var infoFlags = VTDecodeInfoFlags()
         let decodeStatus = VTDecompressionSessionDecodeFrame(
@@ -313,6 +319,7 @@ final class HardwareVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
             frameRefcon: nil,
             infoFlagsOut: &infoFlags
         )
+        lock.unlock()
         if decodeStatus != noErr {
             EngineLog.emit(
                 "[HardwareVideoDecoder] decode error \(decodeStatus) at pts=\(ptsRaw)",
diff --git a/Sources/AetherEngine/Decoder/SoftwareVideoDecoder.swift b/Sources/AetherEngine/Decoder/SoftwareVideoDecoder.swift
index 37c421432..5bde2e2d6 100644
--- a/Sources/AetherEngine/Decoder/SoftwareVideoDecoder.swift
+++ b/Sources/AetherEngine/Decoder/SoftwareVideoDecoder.swift
@@ -236,6 +236,8 @@ final class SoftwareVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
         if Self.disposition(forSendResult: sendRet) == .drainAndRetry {
             drainDecodedFrames()
             lock.lock()
+            // Audit DEC-1: the drain drops the lock between frames, so a flush can land in it.
+            if let epoch, epoch != _feedEpoch { lock.unlock(); return }
             sendRet = codecContext == nil ? FFmpegErr.einval : avcodec_send_packet(ctx, packet)
             lock.unlock()
         }

From dc946124ebd9b388a6f7411a7d7fcc0e894dd97d Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 05:55:04 +0200
Subject: [PATCH 065/359] fix(audio): the audio-only host drops buffers decoded
 across a seek's flush (audit DEC-2)

The demux loop checked the seek generation only before decoding. A seek's
flush landing inside decode (or inside the EOF drain) let the pre-seek
buffers be enqueued into the emptied renderer, where one stamped at the old
position can hold the queue silent after a backward seek. Re-check after
decode and after drain, the rule SoftwarePlaybackHost got in AE#491.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 Sources/AetherEngine/Audio/AudioPlaybackHost.swift | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/Sources/AetherEngine/Audio/AudioPlaybackHost.swift b/Sources/AetherEngine/Audio/AudioPlaybackHost.swift
index 2e41867c0..cff1548fa 100644
--- a/Sources/AetherEngine/Audio/AudioPlaybackHost.swift
+++ b/Sources/AetherEngine/Audio/AudioPlaybackHost.swift
@@ -451,7 +451,9 @@ final class AudioPlaybackHost {
                 // tail. flush() alone dropped the final ~21ms+ of every audio-only title.
                 if let aDec = audioDecoder, let aOut = audioOutput,
                    seekGeneration() == seenSeekGeneration {
-                    let tail = aDec.drain()
+                    // Audit DEC-2: a seek's flush can land inside the drain, as in `decode` below.
+                    let drained = aDec.drain()
+                    let tail = seekGeneration() == seenSeekGeneration ? drained : []
                     for buf in tail { aOut.enqueue(sampleBuffer: buf) }
                     if let last = tail.last {
                         let end = CMTimeGetSeconds(CMSampleBufferGetPresentationTimeStamp(last))
@@ -493,6 +495,13 @@ final class AudioPlaybackHost {
             if packet.pointee.stream_index == audioStreamIndex,
                let aDec = audioDecoder, let aOut = audioOutput {
                 let buffers = aDec.decode(packet: packet)
+                // Audit DEC-2 (the AE#491 rule on the audio-only host): the seek's flush can land
+                // inside `decode`, so the buffers are checked out again.
+                if seekGeneration() != seenSeekGeneration {
+                    av_packet_unref(packet)
+                    av_packet_free_safe(packet)
+                    return true
+                }
                 for buf in buffers {
                     aOut.enqueue(sampleBuffer: buf)
                 }

From 5d27ac095924d9c6412854d5a18f118c74fd27bc Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 05:55:07 +0200
Subject: [PATCH 066/359] perf(segments): replay pre-gate audio through a
 cursor instead of removeFirst (audit SEG-6)

The pre-gate audio buffer was drained one removeFirst() per packet, which shifts the rest of the
array each time. At TrueHD's 1200 packets/s a gate scan across a long GOP buffers 10-20k packets,
and the quadratic drain cost 60-300 ms of pump CPU on the first segment after a seek. The replay
now walks an index and clears the array once it is exhausted.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 .../Video/HLSSegmentProducer.swift            | 38 ++++++++++++-------
 1 file changed, 24 insertions(+), 14 deletions(-)

diff --git a/Sources/AetherEngine/Video/HLSSegmentProducer.swift b/Sources/AetherEngine/Video/HLSSegmentProducer.swift
index a7e908bcc..5f6da8c70 100644
--- a/Sources/AetherEngine/Video/HLSSegmentProducer.swift
+++ b/Sources/AetherEngine/Video/HLSSegmentProducer.swift
@@ -550,6 +550,21 @@ final class HLSSegmentProducer: @unchecked Sendable {
     private var pregateAudioBuffer: [(UnsafeMutablePointer<AVPacket>, PacketOrigin)] = []
     private var pregateAudioBufferBytes: Int = 0
     private var pregateAudioReplaySorted = false
+    /// Audit SEG-6: replay cursor into `pregateAudioBuffer`. Entries before it were handed to the pump
+    /// (which owns and frees them); draining with removeFirst() was quadratic at TrueHD packet rates.
+    private var pregateAudioReplayIndex = 0
+
+    private var hasPregateAudioToReplay: Bool { pregateAudioReplayIndex < pregateAudioBuffer.count }
+
+    private func freeUnreplayedPregateAudio() {
+        for entry in pregateAudioBuffer[pregateAudioReplayIndex...] {
+            var pkt: UnsafeMutablePointer<AVPacket>? = entry.0
+            trackedPacketFree(&pkt)
+        }
+        pregateAudioBuffer.removeAll()
+        pregateAudioReplayIndex = 0
+        pregateAudioBufferBytes = 0
+    }
     private var pregateAudioOverflowLogged = false
     private static let maxPregateAudioBufferBytes = 8 * 1024 * 1024
 
@@ -1091,12 +1106,7 @@ final class HLSSegmentProducer: @unchecked Sendable {
     /// audio belongs to the abandoned position, and the source-dts anchors would read the backward
     /// seek as a timeline discontinuity.
     private func discardPregateScanState() {
-        for entry in pregateAudioBuffer {
-            var pkt: UnsafeMutablePointer<AVPacket>? = entry.0
-            trackedPacketFree(&pkt)
-        }
-        pregateAudioBuffer.removeAll()
-        pregateAudioBufferBytes = 0
+        freeUnreplayedPregateAudio()
         pregateAudioReplaySorted = false
         pregateAudioOverflowLogged = false
         pregateVideoDropCount = 0
@@ -2917,7 +2927,7 @@ final class HLSSegmentProducer: @unchecked Sendable {
 
                 let packet: UnsafeMutablePointer<AVPacket>
                 let origin: PacketOrigin
-                if !audioWaitForVideo, !pregateAudioBuffer.isEmpty {
+                if !audioWaitForVideo, hasPregateAudioToReplay {
                     // #74: once the video gate opens, drain the buffered head-of-stream audio in DTS
                     // order before reading further source packets. These were already counted in
                     // packetsRead when first read, so do not re-count them here.
@@ -2925,7 +2935,12 @@ final class HLSSegmentProducer: @unchecked Sendable {
                         pregateAudioBuffer.sort { Self.mergeOrderingTicks($0.0) < Self.mergeOrderingTicks($1.0) }
                         pregateAudioReplaySorted = true
                     }
-                    let entry = pregateAudioBuffer.removeFirst()
+                    let entry = pregateAudioBuffer[pregateAudioReplayIndex]
+                    pregateAudioReplayIndex += 1
+                    if pregateAudioReplayIndex == pregateAudioBuffer.count {
+                        pregateAudioBuffer.removeAll()
+                        pregateAudioReplayIndex = 0
+                    }
                     packet = entry.0
                     origin = entry.1
                     pregateAudioBufferBytes -= Int(packet.pointee.size)
@@ -4113,12 +4128,7 @@ final class HLSSegmentProducer: @unchecked Sendable {
 
         // #74: free any head-of-stream audio still buffered (e.g. the video gate never opened on a
         // corrupt or aborted source); replayed entries were already drained at the loop top.
-        for entry in pregateAudioBuffer {
-            var pkt: UnsafeMutablePointer<AVPacket>? = entry.0
-            trackedPacketFree(&pkt)
-        }
-        pregateAudioBuffer.removeAll()
-        pregateAudioBufferBytes = 0
+        freeUnreplayedPregateAudio()
 
         // Flush look-behind; fallback duration produces tail-correct trun for the final fragment.
         if let prev = pendingVideoPkt {

From 6679174cf167406d9dabfbd439754e3eea8b7a7a Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 05:58:16 +0200
Subject: [PATCH 067/359] fix(muxer): a 256-511 byte first NAL no longer hides
 a broken chain from the AE#561 cut (audit BIT-1)

The sanitizer treated any sample starting 00 00 01 as Annex B, and with a 4-byte length prefix
that is exactly a first NAL of 256 to 511 bytes, so an overlong length later in such a sample
reached Apple's parser and the segment died with -19602. The muxer now latches the framing once a
video sample of the track walks exactly as a length-prefixed chain, and from then on reads a
00 00 01 head as a length. A 4-byte start code is still refused.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 .../AetherEngine/Video/MP4SegmentMuxer.swift  | 15 ++++++++++-
 Sources/AetherEngine/Video/NALUnitChain.swift | 19 ++++++++++++--
 .../AetherEngineTests/NALUnitChainTests.swift | 25 +++++++++++++++++++
 3 files changed, 56 insertions(+), 3 deletions(-)

diff --git a/Sources/AetherEngine/Video/MP4SegmentMuxer.swift b/Sources/AetherEngine/Video/MP4SegmentMuxer.swift
index ec379c858..04c77d85f 100644
--- a/Sources/AetherEngine/Video/MP4SegmentMuxer.swift
+++ b/Sources/AetherEngine/Video/MP4SegmentMuxer.swift
@@ -174,6 +174,19 @@ final class MP4SegmentMuxer {
         ProcessInfo.processInfo.environment["AETHER_DISABLE_NAL_SANITIZER"] != nil
     /// How many video samples the AE#561 sanitizer has had to cut, over this muxer's life.
     private var truncatedVideoSamples: Int = 0
+    /// Audit BIT-1: a video sample of this track walked exactly as a length-prefixed chain, so a
+    /// `00 00 01` head is a 256-511 byte length from here on, not an Annex B start code.
+    private var videoNALFramingConfirmed = false
+
+    private func sanitizerCut(_ bytes: UnsafeRawBufferPointer, lengthPrefixSize: Int) -> Int? {
+        let cut = NALUnitChain.completeRunLength(
+            bytes, lengthPrefixSize: lengthPrefixSize, framingConfirmed: videoNALFramingConfirmed)
+        if cut == nil, !videoNALFramingConfirmed,
+           NALUnitChain.walksExactly(bytes, lengthPrefixSize: lengthPrefixSize) {
+            videoNALFramingConfirmed = true
+        }
+        return cut
+    }
 
     /// Only AC-3 / E-AC-3 / TrueHD build their mp4 sample entry from a parsed packet (dac3/dec3/dmlp),
     /// so only they can hit the "moov before audio parsed" wedge and need the #64-flush guard. Shared with
@@ -625,7 +638,7 @@ final class MP4SegmentMuxer {
            let lengthPrefixSize = videoNALLengthPrefixSize,
            let data = packet.pointee.data,
            packet.pointee.size > 0,
-           let complete = NALUnitChain.completeRunLength(
+           let complete = sanitizerCut(
                UnsafeRawBufferPointer(start: data, count: Int(packet.pointee.size)),
                lengthPrefixSize: lengthPrefixSize
            ) {
diff --git a/Sources/AetherEngine/Video/NALUnitChain.swift b/Sources/AetherEngine/Video/NALUnitChain.swift
index 859d48579..2a8113e6c 100644
--- a/Sources/AetherEngine/Video/NALUnitChain.swift
+++ b/Sources/AetherEngine/Video/NALUnitChain.swift
@@ -43,12 +43,20 @@ enum NALUnitChain {
     ///
     /// Zero means not one NAL unit in the payload is complete, which leaves the caller nothing to
     /// write.
-    static func completeRunLength(_ bytes: UnsafeRawBufferPointer, lengthPrefixSize: Int) -> Int? {
+    ///
+    /// `framingConfirmed` says an earlier sample of this track already walked exactly as a
+    /// length-prefixed chain. Audit BIT-1: with a 4-byte prefix, every first NAL of 256 to 511 bytes
+    /// starts `00 00 01 xx`, so the head test alone let exactly those damaged samples through. Once
+    /// the track is known to be length-prefixed that head is a length, not a start code.
+    static func completeRunLength(
+        _ bytes: UnsafeRawBufferPointer, lengthPrefixSize: Int, framingConfirmed: Bool = false
+    ) -> Int? {
         let count = bytes.count
         guard (1...4).contains(lengthPrefixSize), count >= lengthPrefixSize else { return nil }
         // An Annex B payload is not this framing at all, and reading its start code as a length would
         // cut every frame of a healthy stream down to nothing.
-        if count >= 3, bytes[0] == 0, bytes[1] == 0, bytes[2] == 1 { return nil }
+        let threeByteHeadIsLength = framingConfirmed && lengthPrefixSize == 4
+        if !threeByteHeadIsLength, count >= 3, bytes[0] == 0, bytes[1] == 0, bytes[2] == 1 { return nil }
         if count >= 4, bytes[0] == 0, bytes[1] == 0, bytes[2] == 0, bytes[3] == 1 { return nil }
 
         var offset = 0
@@ -62,4 +70,11 @@ enum NALUnitChain {
         }
         return offset == count ? nil : offset
     }
+
+    /// Whether the payload walks as a length-prefixed chain that ends exactly on its last byte. Annex B
+    /// data cannot do that by accident, since it would have to encode its own byte offsets.
+    static func walksExactly(_ bytes: UnsafeRawBufferPointer, lengthPrefixSize: Int) -> Bool {
+        guard let base = bytes.baseAddress?.assumingMemoryBound(to: UInt8.self) else { return false }
+        return VideoConfigRecord.walksAsLengthPrefixed(base, size: bytes.count, lengthSize: lengthPrefixSize)
+    }
 }
diff --git a/Tests/AetherEngineTests/NALUnitChainTests.swift b/Tests/AetherEngineTests/NALUnitChainTests.swift
index a38337884..134857afa 100644
--- a/Tests/AetherEngineTests/NALUnitChainTests.swift
+++ b/Tests/AetherEngineTests/NALUnitChainTests.swift
@@ -68,6 +68,31 @@ struct NALUnitChainTests {
         #expect(Self.run([0x00, 0x00, 0x01, 0x26, 0x01, 0xAA, 0xBB, 0xCC]) == nil)
     }
 
+    /// Audit BIT-1: a first NAL of 256 to 511 bytes has the 4-byte length `00 00 01 xx`, which the
+    /// head test alone reads as a start code, so the overlong length behind it reached the parser.
+    @Test("A 256-511 byte first NAL no longer hides an overrun once the track walked exactly")
+    func threeByteHeadIsALengthOnceConfirmed() {
+        let first = Self.nal([0x4E, 0x01] + [UInt8](repeating: 0x5A, count: 318))
+        #expect(Array(first.prefix(3)) == [0x00, 0x00, 0x01])
+        let broken: [UInt8] = [0x16, 0xE5, 0x7A, 0xB3] + [UInt8](repeating: 0x5A, count: 96)
+        let sample = first + broken
+
+        #expect(Self.run(sample) == nil, "unconfirmed, the head still reads as Annex B")
+        let confirmed = sample.withUnsafeBytes {
+            NALUnitChain.completeRunLength($0, lengthPrefixSize: 4, framingConfirmed: true)
+        }
+        #expect(confirmed == first.count)
+
+        // The healthy sample of the same shape is what confirms the framing in the first place.
+        #expect(first.withUnsafeBytes { NALUnitChain.walksExactly($0, lengthPrefixSize: 4) })
+        // Annex B never confirms it, and a 4-byte start code stays refused even once confirmed.
+        let annexB: [UInt8] = [0x00, 0x00, 0x00, 0x01, 0x26, 0x01, 0xAA, 0xBB, 0x00, 0x00, 0x01, 0x02, 0x01]
+        #expect(!annexB.withUnsafeBytes { NALUnitChain.walksExactly($0, lengthPrefixSize: 4) })
+        #expect(annexB.withUnsafeBytes {
+            NALUnitChain.completeRunLength($0, lengthPrefixSize: 4, framingConfirmed: true)
+        } == nil)
+    }
+
     @Test("The prefix width is honoured, not assumed to be four")
     func widthIsHonoured() {
         let two = Self.nal([0x26, 0x01, 0xAA], lengthPrefixSize: 2)

From a10811a672e34a3ee3511d84eb2bcab6b0bffd9b Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 05:59:26 +0200
Subject: [PATCH 068/359] fix(dv): bound the RPU audit walk by every packet it
 reads (audit BIT-2)

The recordless / AE#532 Dolby Vision RPU audit counted only video packets against its budget, so a
source whose video stops after the head made every open read the rest of the file over HTTP. The
walk now also ends after 16x its video budget in packets of any stream, or 64 MiB read. Other
streams are deliberately not set to AVDISCARD_ALL, since the demuxer would then skip them inside a
single read where no ceiling sees the bytes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 .../Video/DolbyVisionRecordAudit.swift         | 18 ++++++++++++++++++
 .../DolbyVisionRecordAuditTests.swift          |  9 +++++++++
 2 files changed, 27 insertions(+)

diff --git a/Sources/AetherEngine/Video/DolbyVisionRecordAudit.swift b/Sources/AetherEngine/Video/DolbyVisionRecordAudit.swift
index 807b46a47..a64e1b0de 100644
--- a/Sources/AetherEngine/Video/DolbyVisionRecordAudit.swift
+++ b/Sources/AetherEngine/Video/DolbyVisionRecordAudit.swift
@@ -200,12 +200,18 @@ public enum DolbyVisionRecordAudit {
             size: Int(codecpar?.pointee.extradata_size ?? 0))
 
         var walked = 0
+        var packetsRead = 0
+        var bytesRead = 0
         while walked < packetBudget {
+            guard !walkExhausted(packetsRead: packetsRead, bytesRead: bytesRead, packetBudget: packetBudget)
+            else { return nil }
             guard let packet = (try? demuxer.readPacket()) ?? nil else { return nil }
             defer {
                 av_packet_unref(packet)
                 av_packet_free_safe(packet)
             }
+            packetsRead += 1
+            bytesRead += Int(max(packet.pointee.size, 0))
             guard packet.pointee.stream_index == videoIdx else { continue }
             walked += 1
             if let profile = rpuProfile(packet, framing: framing) { return profile }
@@ -213,6 +219,18 @@ public enum DolbyVisionRecordAudit {
         return nil
     }
 
+    /// Audit BIT-2: the walk counted only video packets, so a source that stops delivering video after
+    /// its head made every open read the rest of the file. Every packet counts against these instead.
+    /// No AVDISCARD_ALL on the other streams: the demuxer would then skip them inside one read, where
+    /// neither ceiling can see the bytes go by.
+    static let foreignPacketFuseMultiplier = 16
+    static let walkByteBudget = 64 * 1024 * 1024
+
+    static func walkExhausted(packetsRead: Int, bytesRead: Int, packetBudget: Int) -> Bool {
+        let (fuse, overflow) = packetBudget.multipliedReportingOverflow(by: foreignPacketFuseMultiplier)
+        return packetsRead >= (overflow ? Int.max : fuse) || bytesRead >= walkByteBudget
+    }
+
     /// The verdict for a source in one call, gate included: opens it, reads the record and the VUI, and
     /// walks packets only when the record is contradicted. nil means the record stands.
     ///
diff --git a/Tests/AetherEngineTests/DolbyVisionRecordAuditTests.swift b/Tests/AetherEngineTests/DolbyVisionRecordAuditTests.swift
index d6e329c56..9d9d778bf 100644
--- a/Tests/AetherEngineTests/DolbyVisionRecordAuditTests.swift
+++ b/Tests/AetherEngineTests/DolbyVisionRecordAuditTests.swift
@@ -286,6 +286,15 @@ struct DolbyVisionRecordAuditTests {
         #expect(r.convertP7ToProfile81 == false)
     }
 
+    @Test("the RPU walk ends on foreign packets and bytes, not only on video packets")
+    func walkIsBoundedByEveryPacket() {
+        #expect(!DolbyVisionRecordAudit.walkExhausted(packetsRead: 63, bytesRead: 0, packetBudget: 4))
+        #expect(DolbyVisionRecordAudit.walkExhausted(packetsRead: 64, bytesRead: 0, packetBudget: 4))
+        #expect(DolbyVisionRecordAudit.walkExhausted(
+            packetsRead: 1, bytesRead: DolbyVisionRecordAudit.walkByteBudget, packetBudget: 4))
+        #expect(!DolbyVisionRecordAudit.walkExhausted(packetsRead: 1, bytesRead: 0, packetBudget: Int.max))
+    }
+
     // MARK: - Against real media
 
     @Test("the relabelled fixture's RPU reports the profile its record hides",

From 1e59deb77dccaf5516af2193cd7d92d348f51052 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 05:59:33 +0200
Subject: [PATCH 069/359] fix(pip): subtitle-composited frames keep the
 source's aspect and colour tags (audit DEC-3, DEC-5)

While a cue was on screen the SW-path PiP compositor rendered into a pool
buffer with no attachments and through BT.709. The renderer describes each
frame from the delivered buffer, so anamorphic content showed at its coded
size, HDR dropped to SDR, and the display-size observer fired at every cue
edge. The output now carries the source's propagatable attachments (before
the render, so CoreImage picks the right YCbCr matrix, and after it) and
renders in the source's own colour space.

The pool lookup also runs under the lock reset() takes on the actor during
stop(), so the two can no longer race on the pool reference.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 .../Renderer/SubtitleFrameCompositor.swift    | 29 +++++++-
 .../SubtitleFrameCompositorTests.swift        | 73 +++++++++++++++++++
 2 files changed, 101 insertions(+), 1 deletion(-)

diff --git a/Sources/AetherEngine/Renderer/SubtitleFrameCompositor.swift b/Sources/AetherEngine/Renderer/SubtitleFrameCompositor.swift
index 086c86f80..9cfe59087 100644
--- a/Sources/AetherEngine/Renderer/SubtitleFrameCompositor.swift
+++ b/Sources/AetherEngine/Renderer/SubtitleFrameCompositor.swift
@@ -116,12 +116,35 @@ final class SubtitleFrameCompositor: @unchecked Sendable {
             logFailureOnce("pool exhausted")
             return buffer
         }
+        // Audit DEC-3: the renderer builds the format description from the delivered buffer, so
+        // the output has to carry the source's pixel aspect ratio and colour tags, or anamorphic
+        // content shows at coded size and HDR drops to SDR for as long as a cue is up. Carried
+        // before the render too, because CoreImage picks the YCbCr matrix from the destination.
+        Self.carryAttachments(from: buffer, to: output)
         let base = CIImage(cvPixelBuffer: buffer)
         let composited = overlay.composited(over: base)
-        ciContext.render(composited, to: output, bounds: CGRect(x: 0, y: 0, width: width, height: height), colorSpace: CGColorSpace(name: CGColorSpace.itur_709))
+        ciContext.render(composited, to: output, bounds: CGRect(x: 0, y: 0, width: width, height: height),
+                         colorSpace: Self.renderColorSpace(for: buffer))
+        Self.carryAttachments(from: buffer, to: output)
         return output
     }
 
+    /// The source's own colour space, so the render encodes the picture the way it was decoded
+    /// (PQ and HLG included). BT.709 only when the source carries no usable tags.
+    nonisolated static func renderColorSpace(for buffer: CVPixelBuffer) -> CGColorSpace {
+        if let attachments = CVBufferCopyAttachments(buffer, .shouldPropagate),
+           let space = CVImageBufferCreateColorSpaceFromAttachments(attachments)?.takeRetainedValue() {
+            return space
+        }
+        return CGColorSpace(name: CGColorSpace.itur_709) ?? CGColorSpaceCreateDeviceRGB()
+    }
+
+    /// Replaces rather than adds: a recycled pool buffer can hold a previous source's tags.
+    nonisolated static func carryAttachments(from source: CVPixelBuffer, to output: CVPixelBuffer) {
+        CVBufferRemoveAllAttachments(output)
+        CVBufferPropagateAttachments(source, output)
+    }
+
     /// One CGImage per cue-set change: text cues bottom-up in the default look, image cues at their
     /// canvas-mapped rects. CG coordinate origin is bottom-left; layout values are top-left based,
     /// so y flips via frameHeight.
@@ -317,7 +340,11 @@ final class SubtitleFrameCompositor: @unchecked Sendable {
         }
     }
 
+    /// Audit DEC-5: `reset()` clears the pool under `lock` from the actor while the decode thread can
+    /// be in here, so the pool reference is only read and replaced under the same lock.
     private func dequeueBuffer(width: Int, height: Int, pixelFormat: OSType) -> CVPixelBuffer? {
+        lock.lock()
+        defer { lock.unlock() }
         if poolFormat?.width != width || poolFormat?.height != height || poolFormat?.pixelFormat != pixelFormat {
             let attrs: [CFString: Any] = [
                 kCVPixelBufferWidthKey: width,
diff --git a/Tests/AetherEngineTests/SubtitleFrameCompositorTests.swift b/Tests/AetherEngineTests/SubtitleFrameCompositorTests.swift
index 747826fcb..17ce5e7f8 100644
--- a/Tests/AetherEngineTests/SubtitleFrameCompositorTests.swift
+++ b/Tests/AetherEngineTests/SubtitleFrameCompositorTests.swift
@@ -94,4 +94,77 @@ struct SubtitleFrameCompositorTests {
         // No active cue at this PTS: passthrough again.
         #expect(compositor.composite(buffer, ptsSeconds: 20) === buffer)
     }
+
+    private func blackFrame(_ format: OSType) throws -> CVPixelBuffer {
+        var pb: CVPixelBuffer?
+        let attrs: [CFString: Any] = [kCVPixelBufferIOSurfacePropertiesKey: [:] as CFDictionary]
+        CVPixelBufferCreate(kCFAllocatorDefault, 720, 480, format, attrs as CFDictionary, &pb)
+        return try #require(pb)
+    }
+
+    private func attachment(_ buffer: CVPixelBuffer, _ key: CFString) -> CFTypeRef? {
+        CVBufferCopyAttachment(buffer, key, nil)
+    }
+
+    /// Audit DEC-3: the renderer describes the frame from the delivered buffer's attachments, so a
+    /// composited frame that dropped them showed anamorphic content at coded size and HDR as SDR
+    /// for exactly as long as a cue was on screen.
+    @Test("a composited frame keeps the source's pixel aspect ratio and colour tags")
+    func compositedFrameKeepsSourceAttachments() throws {
+        let compositor = SubtitleFrameCompositor()
+        compositor.update(cues: [SubtitleCue(id: 1, startTime: 0, endTime: 10, body: .text("HELLO"))], enabled: true)
+
+        let hdr = try blackFrame(kCVPixelFormatType_420YpCbCr10BiPlanarVideoRange)
+        let aspect: NSDictionary = [
+            kCVImageBufferPixelAspectRatioHorizontalSpacingKey: 32,
+            kCVImageBufferPixelAspectRatioVerticalSpacingKey: 27,
+        ]
+        CVBufferSetAttachment(hdr, kCVImageBufferPixelAspectRatioKey, aspect, .shouldPropagate)
+        CVBufferSetAttachment(hdr, kCVImageBufferColorPrimariesKey, kCVImageBufferColorPrimaries_ITU_R_2020, .shouldPropagate)
+        CVBufferSetAttachment(hdr, kCVImageBufferTransferFunctionKey, kCVImageBufferTransferFunction_SMPTE_ST_2084_PQ, .shouldPropagate)
+        CVBufferSetAttachment(hdr, kCVImageBufferYCbCrMatrixKey, kCVImageBufferYCbCrMatrix_ITU_R_2020, .shouldPropagate)
+
+        let out = compositor.composite(hdr, ptsSeconds: 5)
+        #expect(out !== hdr)
+        let par = attachment(out, kCVImageBufferPixelAspectRatioKey) as? NSDictionary
+        #expect(par?[kCVImageBufferPixelAspectRatioHorizontalSpacingKey] as? Int == 32)
+        #expect(par?[kCVImageBufferPixelAspectRatioVerticalSpacingKey] as? Int == 27)
+        #expect(attachment(out, kCVImageBufferTransferFunctionKey) as? String
+                == kCVImageBufferTransferFunction_SMPTE_ST_2084_PQ as String)
+        #expect(attachment(out, kCVImageBufferColorPrimariesKey) as? String
+                == kCVImageBufferColorPrimaries_ITU_R_2020 as String)
+        #expect(attachment(out, kCVImageBufferYCbCrMatrixKey) as? String
+                == kCVImageBufferYCbCrMatrix_ITU_R_2020 as String)
+
+        let space = SubtitleFrameCompositor.renderColorSpace(for: hdr)
+        #expect(space.name == CGColorSpace.itur_2100_PQ)
+    }
+
+    @Test("a recycled output buffer does not keep an earlier source's pixel aspect ratio")
+    func recycledBufferDropsStaleAspect() throws {
+        let compositor = SubtitleFrameCompositor()
+        compositor.update(cues: [SubtitleCue(id: 1, startTime: 0, endTime: 10, body: .text("HELLO"))], enabled: true)
+        let format = kCVPixelFormatType_420YpCbCr8BiPlanarVideoRange
+
+        let anamorphic = try blackFrame(format)
+        let aspect: NSDictionary = [
+            kCVImageBufferPixelAspectRatioHorizontalSpacingKey: 32,
+            kCVImageBufferPixelAspectRatioVerticalSpacingKey: 27,
+        ]
+        CVBufferSetAttachment(anamorphic, kCVImageBufferPixelAspectRatioKey, aspect, .shouldPropagate)
+        // Several rounds, so the pool hands a buffer that already held the ratio back out.
+        for _ in 0..<4 { _ = compositor.composite(anamorphic, ptsSeconds: 5) }
+
+        let square = try blackFrame(format)
+        for _ in 0..<4 {
+            let out = compositor.composite(square, ptsSeconds: 5)
+            #expect(attachment(out, kCVImageBufferPixelAspectRatioKey) == nil)
+        }
+    }
+
+    @Test("an untagged source renders through BT.709")
+    func untaggedSourceFallsBackTo709() throws {
+        let space = SubtitleFrameCompositor.renderColorSpace(for: try blackFrame(kCVPixelFormatType_420YpCbCr8BiPlanarVideoRange))
+        #expect(space.name == CGColorSpace.itur_709)
+    }
 }

From 159e961685842da1a8f51d46d07a3069cef31e8c Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 06:00:47 +0200
Subject: [PATCH 070/359] fix(audio): a resampler rebuild the format rejects no
 longer mutes the bridge for good (audit DEC-6)

reconfigureSwrInputIfNeeded rebuilt the live SwrContext in place, and
swr_alloc_set_opts2 frees it on a rejected set-opts. Every later feed() and
flush() then returned early before any counter moved, so the bridge stayed
silent for the rest of the session and the AE#396 detector never saw it.
The rebuild now goes through a scratch context swapped in only after
swr_init succeeds; a frame the resampler cannot take is dropped, counted
and logged, and the old context keeps serving the format it was built for.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 Sources/AetherEngine/Audio/AudioBridge.swift | 43 +++++++++++++++-----
 1 file changed, 32 insertions(+), 11 deletions(-)

diff --git a/Sources/AetherEngine/Audio/AudioBridge.swift b/Sources/AetherEngine/Audio/AudioBridge.swift
index 5314350c4..c01a15a1a 100644
--- a/Sources/AetherEngine/Audio/AudioBridge.swift
+++ b/Sources/AetherEngine/Audio/AudioBridge.swift
@@ -169,6 +169,7 @@ final class AudioBridge: @unchecked Sendable {
     /// before overwrite and in cleanup.
     private var swrInFmt: AVSampleFormat = AV_SAMPLE_FMT_NONE
     private var swrInRate: Int32 = 0
+    private var swrReconfigureFailures = 0
     private var swrInLayout = AVChannelLayout()
     /// FIFO buffering resampled PCM until >= encoderCtx.frame_size samples. FLAC's wrapper has
     /// AV_CODEC_CAP_SMALL_LAST_FRAME but not VARIABLE_FRAME_SIZE, so non-final frames must hit frame_size exactly
@@ -974,24 +975,30 @@ final class AudioBridge: @unchecked Sendable {
     /// probe), and reading S32 integers as FLTP floats is noise. Re-derive the input from the frame, keeping
     /// the output side pinned to the encoder, exactly as AudioDecoder configures its resampler from the frame.
     /// No-op in the common case where find_stream_info already resolved the format (frame == seed), so working
-    /// paths are untouched; only a wrong seed or a genuine mid-stream format change rebuilds. swr_alloc_set_opts2
-    /// reuses the context pointer on success and frees it on failure (the caller re-binds swrCtx); swr_init drops
+    /// paths are untouched; only a wrong seed or a genuine mid-stream format change rebuilds. A rebuild drops
     /// the sub-frame resampler delay, as startSegment already does. Runs under feed()'s opLock (never re-lock).
+    ///
+    /// Audit DEC-6: built on a scratch context and swapped in only once it initialised. Rebuilding the
+    /// live one lost it for good on a rejected format (set-opts frees it), after which every feed
+    /// returned early, the bridge stayed mute, and not even the AE#396 detector could see it. A frame
+    /// the resampler cannot take is now dropped and counted, and the old context keeps serving the
+    /// format it was built for. Returns false when this frame must not reach `swr_convert`.
     private func reconfigureSwrInputIfNeeded(
         forFrame sf: UnsafeMutablePointer<AVFrame>,
         enc: UnsafeMutablePointer<AVCodecContext>
-    ) {
+    ) -> Bool {
         let frameFmtRaw = sf.pointee.format
         let frameRate = sf.pointee.sample_rate
-        guard frameFmtRaw >= 0, frameRate > 0, sf.pointee.ch_layout.nb_channels > 0 else { return }
+        guard frameFmtRaw >= 0, frameRate > 0, sf.pointee.ch_layout.nb_channels > 0 else { return true }
         let matchesCurrent = frameFmtRaw == swrInFmt.rawValue
             && frameRate == swrInRate
             && av_channel_layout_compare(&swrInLayout, &sf.pointee.ch_layout) == 0
-        guard !matchesCurrent else { return }
+        guard !matchesCurrent else { return true }
 
         let frameFmt = AVSampleFormat(rawValue: frameFmtRaw)
+        var scratch: OpaquePointer?
         let setRet = swr_alloc_set_opts2(
-            &swrCtx,
+            &scratch,
             &enc.pointee.ch_layout,
             pcmSampleFmt,
             enc.pointee.sample_rate,
@@ -1001,7 +1008,22 @@ final class AudioBridge: @unchecked Sendable {
             0,
             nil
         )
-        guard setRet >= 0, swrCtx != nil, swr_init(swrCtx) >= 0 else { return }
+        let initRet = setRet >= 0 && scratch != nil ? swr_init(scratch) : setRet
+        guard initRet >= 0 else {
+            swr_free(&scratch)
+            swrReconfigureFailures += 1
+            if swrReconfigureFailures == 1 || swrReconfigureFailures % 500 == 0 {
+                EngineLog.emit(
+                    "[AudioBridge] ERROR: resampler rejected decoded \(frameRate)Hz/"
+                    + "\(sf.pointee.ch_layout.nb_channels)ch fmt=\(frameFmtRaw) (ret=\(initRet)); "
+                    + "\(swrReconfigureFailures) frame(s) dropped",
+                    category: .session
+                )
+            }
+            return false
+        }
+        swr_free(&swrCtx)
+        swrCtx = scratch
 
         av_channel_layout_uninit(&swrInLayout)
         av_channel_layout_copy(&swrInLayout, &sf.pointee.ch_layout)
@@ -1023,6 +1045,7 @@ final class AudioBridge: @unchecked Sendable {
                 category: .session
             )
         }
+        return true
     }
 
     /// Resample sf (decoded source frame) to encoder format and push into the FIFO (swr_convert may produce
@@ -1047,10 +1070,8 @@ final class AudioBridge: @unchecked Sendable {
 
         // Align swr's INPUT to the frame the decoder actually produced before converting. No-op once the seed
         // matched (the usual case); only a wrong init seed or a genuine mid-stream format change rebuilds swr.
-        reconfigureSwrInputIfNeeded(forFrame: sf, enc: enc)
-        // The rebuild reuses the context pointer on success, but swr_alloc_set_opts2 frees it on a set-opts
-        // failure (swr_free(ps) -> swrCtx == nil), which would dangle the caller's `swr`. Re-bind to the live one.
-        guard let swr = swrCtx else {
+        // A successful rebuild replaces the context, which would dangle the caller's `swr`. Re-bind to the live one.
+        guard reconfigureSwrInputIfNeeded(forFrame: sf, enc: enc), let swr = swrCtx else {
             stats.framesDroppedBeforeFIFO += 1
             return
         }

From 6138d050fabecd6ca59040908426beba5192d4ed Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 06:01:21 +0200
Subject: [PATCH 071/359] fix(demuxer): a picture waiting when an IDR closes
 its sequence keeps that sequence's slot (audit BIT-3)

The #511 Matroska slot permutation reset its slot ladder on an IDR while held pictures still
carried ranks counted against the old one, so a picture waiting for a slot its sequence never
stated later took the new sequence's slot at that rank and duplicated a presentation time. The
session now settles every held rank before the IDR is admitted: from the closing ladder when the
slot is known, else from the closing sequence's unclaimed slots in display order.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 .../Video/H264MatroskaSlotPermutation.swift   | 55 ++++++++++++++++---
 .../Issue511MatroskaCodingOrderTests.swift    | 16 ++++++
 2 files changed, 64 insertions(+), 7 deletions(-)

diff --git a/Sources/AetherEngine/Video/H264MatroskaSlotPermutation.swift b/Sources/AetherEngine/Video/H264MatroskaSlotPermutation.swift
index 92c0e4060..53720e956 100644
--- a/Sources/AetherEngine/Video/H264MatroskaSlotPermutation.swift
+++ b/Sources/AetherEngine/Video/H264MatroskaSlotPermutation.swift
@@ -159,6 +159,9 @@ enum H264MatroskaSlotPermutation {
         /// Presentation slots in the order they arrived, which for this defect is decode order. The
         /// slot a picture owns is the one at its DISPLAY rank, so this is the whole lookup table.
         private(set) var slots: [Int64] = []
+        /// Slot positions already spoken for in this sequence: a rank handed out, or the coding
+        /// position of a picture that goes out on its own slot.
+        private var claimed: Set<Int64> = []
         private(set) var repairedPictures = 0
         private(set) var unrepairedPictures = 0
         /// A seek leaves the sequence behind; only an IDR starts a new one. A landing that is not one
@@ -176,9 +179,17 @@ enum H264MatroskaSlotPermutation {
 
         mutating func noteSeek() {
             slots.removeAll(keepingCapacity: true)
+            claimed.removeAll(keepingCapacity: true)
             awaitingSequenceStart = true
         }
 
+        /// Audit BIT-3: the slots of this sequence no picture has claimed, in display order. When an
+        /// IDR closes the sequence these are the only slots the pictures still waiting on it can own;
+        /// the next sequence's slots belong to its own pictures.
+        func unclaimedSlots() -> [Int64] {
+            slots.indices.filter { !claimed.contains(Int64($0)) }.map { slots[$0] }
+        }
+
         /// Records a video picture and returns the display rank whose slot it should carry, or nil
         /// when it has to go out exactly as it arrived. The slot is recorded either way: it belongs
         /// to whichever picture owns this coding position, and that picture may still be coming.
@@ -196,6 +207,7 @@ enum H264MatroskaSlotPermutation {
             }
             if isKeyframe, pictureOrderCount == 0 {
                 slots = [slot]
+                claimed = [0]
                 awaitingSequenceStart = false
                 repairedPictures += 1
                 return 0
@@ -209,21 +221,24 @@ enum H264MatroskaSlotPermutation {
                 return nil
             }
             slots.append(slot)
+            let codingIndex = Int64(slots.count - 1)
             guard let pictureOrderCount, pictureOrderCount >= 0,
                   pictureOrderCount % pocStep == 0 else {
                 unrepairedPictures += 1
+                claimed.insert(codingIndex)
                 return nil
             }
             let rank = pictureOrderCount / pocStep
-            let codingIndex = Int64(slots.count - 1)
             // Behind its own slot by more than the reorder delay would put the picture before its
             // stated decode time; further ahead than the ceiling is not a mini-GOP any more.
             guard codingIndex - rank <= Int64(videoDelay),
                   rank - codingIndex <= H264MatroskaSlotPermutation.lookaheadCeiling else {
                 unrepairedPictures += 1
+                claimed.insert(codingIndex)
                 return nil
             }
             repairedPictures += 1
+            claimed.insert(rank)
             return rank
         }
 
@@ -342,10 +357,35 @@ final class H264MatroskaSlotPermutationSession: H264TimestampRepairSession {
         _ packet: UnsafeMutablePointer<AVPacket>,
         pictureOrderCount: Int64?
     ) -> Int64? {
-        sequence?.admit(
-            slot: packet.pointee.pts,
-            pictureOrderCount: packet.pointee.pts == Int64.min ? nil : pictureOrderCount,
-            isKeyframe: isKeyframe(packet))
+        let pictureOrderCount = packet.pointee.pts == Int64.min ? nil : pictureOrderCount
+        let keyframe = isKeyframe(packet)
+        if keyframe, pictureOrderCount == 0 { settleRanksOfClosingSequence() }
+        return sequence?.admit(slot: packet.pointee.pts, pictureOrderCount: pictureOrderCount, isKeyframe: keyframe)
+    }
+
+    /// Audit BIT-3: a rank means something only on the ladder it was counted against, and an IDR is
+    /// about to replace that ladder. Every held picture still carrying a rank gets its slot from the
+    /// closing sequence now: the one its rank owns when the container stated it, else one of the
+    /// slots no picture claimed, in display order. Left pending, the lookup answered from the NEW
+    /// sequence and two pictures shared one presentation time.
+    private func settleRanksOfClosingSequence() {
+        guard let sequence, sequence.brokenReason == nil else { return }
+        var waiting: [(index: Int, rank: Int64)] = []
+        for index in pending.indices {
+            guard let rank = pending[index].rank else { continue }
+            if let slot = sequence.slot(forRank: rank) {
+                pending[index].packet.pointee.pts = slot
+            } else {
+                waiting.append((index, rank))
+            }
+            pending[index].rank = nil
+        }
+        guard !waiting.isEmpty else { return }
+        var free = sequence.unclaimedSlots()[...]
+        for entry in waiting.sorted(by: { $0.rank < $1.rank }) {
+            guard let slot = free.popFirst() else { break }
+            pending[entry.index].packet.pointee.pts = slot
+        }
     }
 
     /// Hands out everything at the head of the queue whose slot is known. A picture still waiting for
@@ -418,8 +458,9 @@ final class H264MatroskaSlotPermutationSession: H264TimestampRepairSession {
             // is stateful and must see each picture exactly once.
             for index in pending.indices where pending[index].isPicture {
                 let entry = pending[index]
-                pending[index].rank = admit(
-                    entry.packet, pictureOrderCount: entry.pictureOrderCount)
+                // Bound first: admitting an IDR settles the ranks already held in `pending`.
+                let rank = admit(entry.packet, pictureOrderCount: entry.pictureOrderCount)
+                pending[index].rank = rank
             }
             drain()
         case .healthy:
diff --git a/Tests/AetherEngineTests/Issue511MatroskaCodingOrderTests.swift b/Tests/AetherEngineTests/Issue511MatroskaCodingOrderTests.swift
index 7957e3b9e..f63122715 100644
--- a/Tests/AetherEngineTests/Issue511MatroskaCodingOrderTests.swift
+++ b/Tests/AetherEngineTests/Issue511MatroskaCodingOrderTests.swift
@@ -134,6 +134,22 @@ struct Issue511MatroskaCodingOrderTests {
         #expect(result.sequence.slots == [Self.reportedSlots[60]])
     }
 
+    /// Audit BIT-3: `I0 P(poc6) B(poc2)` then an IDR. P waits for rank 3, which this sequence never
+    /// states; the slot it can own is the one rank 2 would have taken, not rank 3 of the next GOP.
+    @Test("a picture left waiting when an IDR closes its sequence takes that sequence's free slot")
+    func waitingPictureKeepsItsOwnSequence() throws {
+        var sequence = Permutation.Sequence(pocStep: 2, videoDelay: 1)
+        #expect(sequence.admit(slot: 0, pictureOrderCount: 0, isKeyframe: true) == 0)
+        let admitted = sequence.admit(slot: 33, pictureOrderCount: 6, isKeyframe: false)
+        let waiting = try #require(admitted)
+        #expect(sequence.admit(slot: 67, pictureOrderCount: 2, isKeyframe: false) == 1)
+        #expect(sequence.slot(forRank: waiting) == nil)
+        #expect(sequence.unclaimedSlots() == [67])
+
+        _ = sequence.admit(slot: 100, pictureOrderCount: 0, isKeyframe: true)
+        #expect(sequence.unclaimedSlots().isEmpty)
+    }
+
     @Test("a healthy reordered MKV is out on the packet that steps back, not after the window")
     func healthyLadderExits() {
         // The same pictures with their slots where the format says they belong: in display order,

From 62083e4e9bc3053fb3ccf81e74c972f0515d8153 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 06:02:33 +0200
Subject: [PATCH 072/359] perf(hdr10plus): memmem the T.35 header before
 walking a packet's NALs (audit BIT-4)

The playback scan runs on every video packet until its first hit, so a source without HDR10+
paid a byte-wise Annex B walk plus an unescape allocation per SEI for the whole session. The
six-byte T.35 header holds no 00 00 pair, so no emulation-prevention byte can split it and AV1
does not escape: an exact memmem prefilter now turns those packets away before the walk.
Matroska side data is still checked first.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 .../Video/HDR10PlusMetadataScan.swift         | 11 ++++++++-
 .../HDR10PlusMetadataScanTests.swift          | 23 +++++++++++++++++++
 2 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/Sources/AetherEngine/Video/HDR10PlusMetadataScan.swift b/Sources/AetherEngine/Video/HDR10PlusMetadataScan.swift
index 47755ce2c..4f7d7f817 100644
--- a/Sources/AetherEngine/Video/HDR10PlusMetadataScan.swift
+++ b/Sources/AetherEngine/Video/HDR10PlusMetadataScan.swift
@@ -45,7 +45,7 @@ enum HDR10PlusMetadataScan {
     static func bytesCarryHDR10Plus(
         _ data: UnsafePointer<UInt8>?, size: Int, codecID: AVCodecID, framing: VideoNALFraming = .annexB
     ) -> Bool {
-        guard let data, size > 0 else { return false }
+        guard let data, size > 0, mayContainT35Header(data, size: size) else { return false }
         let bytes = UnsafeBufferPointer(start: data, count: size)
         switch codecID {
         case AV_CODEC_ID_H264, AV_CODEC_ID_HEVC:
@@ -57,6 +57,15 @@ enum HDR10PlusMetadataScan {
         }
     }
 
+    /// Audit BIT-4: exact prefilter. The playback scan runs on every video packet until its first hit,
+    /// so a source without HDR10+ paid a byte-wise NAL walk for the whole session. The T.35 header
+    /// holds no `00 00` pair, so no emulation-prevention byte can land inside it and AV1 does not
+    /// escape at all: a payload that carries HDR10+ in-band carries these six bytes verbatim.
+    static func mayContainT35Header(_ data: UnsafePointer<UInt8>, size: Int) -> Bool {
+        guard size >= t35Header.count else { return false }
+        return t35Header.withUnsafeBufferPointer { memmem(data, size, $0.baseAddress, $0.count) != nil }
+    }
+
     // MARK: - H.264 / HEVC
 
     /// A walk that runs into malformed framing stops and reports what it had already VALIDATED, rather
diff --git a/Tests/AetherEngineTests/HDR10PlusMetadataScanTests.swift b/Tests/AetherEngineTests/HDR10PlusMetadataScanTests.swift
index 2e4bad2bb..3be54aa0c 100644
--- a/Tests/AetherEngineTests/HDR10PlusMetadataScanTests.swift
+++ b/Tests/AetherEngineTests/HDR10PlusMetadataScanTests.swift
@@ -163,6 +163,29 @@ struct HDR10PlusMetadataScanTests {
         #expect(scan(Self.annexB([0x4E, 0x01] + escaped)))
     }
 
+    /// Audit BIT-4: the prefilter must never hide a payload the full walk would confirm, in any
+    /// framing, and must turn away a packet that has no T.35 header at all.
+    @Test("The T.35 header prefilter keeps every carriage and rejects packets without the header")
+    func t35PrefilterIsExact() {
+        let carriers: [[UInt8]] = [
+            Self.annexB(Self.sei()),
+            Self.annexB(Self.sei(hevc: false), fourBytes: true),
+            Self.lengthPrefixed(Self.sei(), width: 4),
+            Self.annexB([0x4E, 0x01] + Self.escaped(
+                Self.message(Self.t35(windows: 3, grids: true, toneMapping: true)) + [0x80])),
+        ]
+        for bytes in carriers {
+            #expect(bytes.withUnsafeBufferPointer {
+                HDR10PlusMetadataScan.mayContainT35Header($0.baseAddress!, size: $0.count)
+            })
+        }
+        let slice = Self.annexB([0x26, 0x01] + [UInt8](repeating: 0x5A, count: 4096))
+        #expect(!slice.withUnsafeBufferPointer {
+            HDR10PlusMetadataScan.mayContainT35Header($0.baseAddress!, size: $0.count)
+        })
+        #expect(!scan(slice))
+    }
+
     @Test("Raw markers, slices, parameter sets, and unregistered SEI never confirm")
     func nonMetadataMarkers() {
         #expect(!scan(Self.header))

From 0db085baafbe7462b8159d9cae6e45c9d4103180 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 06:07:29 +0200
Subject: [PATCH 073/359] fix(hls): parse CRLF playlists and bound a hostile
 MEDIA-SEQUENCE (audit NET-2, NAT-3, NET-3)

split(separator: "\n") compares whole Characters, and "\r\n" is one grapheme
cluster in Swift, so a CRLF playlist (Windows-hosted IPTV panels, some
packagers) came back as a single line and every ingest path rejected it with
"missing TARGETDURATION". Split on Character.isNewline instead, which matches
"\r\n", "\n" and "\r" alike.

Separately, an unchecked EXT-X-MEDIA-SEQUENCE (a hostile or MITM live
playlist) let mediaSequence + segments.count overflow and trap in
HLSPlaylistTracker, killing the whole process. The parser now rejects a
negative or absurd sequence number, and the tracker combines sequence
numbers with &+/&- so a value that reached it some other way cannot trap
either.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 .../IO/HLSIngest/HLSPlaylist.swift            | 15 ++++++-
 .../IO/HLSIngest/HLSPlaylistTracker.swift     |  9 ++--
 .../AetherEngineTests/HLSPlaylistTests.swift  | 42 +++++++++++++++++++
 .../HLSPlaylistTrackerTests.swift             |  9 ++++
 4 files changed, 70 insertions(+), 5 deletions(-)

diff --git a/Sources/AetherEngine/IO/HLSIngest/HLSPlaylist.swift b/Sources/AetherEngine/IO/HLSIngest/HLSPlaylist.swift
index a27082336..6e2070fc9 100644
--- a/Sources/AetherEngine/IO/HLSIngest/HLSPlaylist.swift
+++ b/Sources/AetherEngine/IO/HLSIngest/HLSPlaylist.swift
@@ -82,8 +82,11 @@ enum HLSPlaylist: Equatable {
 enum HLSPlaylistParser {
 
     static func parse(_ text: String) throws -> HLSPlaylist {
+        // `split(separator: "\n")` compares whole Characters, and "\r\n" is one grapheme cluster in
+        // Swift, so a CRLF playlist came back as a single line (audit NET-2, NAT-3). `isNewline` is
+        // true for "\r\n", "\n" and "\r" alike.
         let lines = text
-            .split(separator: "\n", omittingEmptySubsequences: true)
+            .split(whereSeparator: \.isNewline)
             .map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }
             .filter { !$0.isEmpty }
         guard lines.first?.hasPrefix("#EXTM3U") == true else {
@@ -177,7 +180,15 @@ enum HLSPlaylistParser {
             if line.hasPrefix("#EXT-X-TARGETDURATION:") {
                 targetDuration = Double(line.dropFirst("#EXT-X-TARGETDURATION:".count))
             } else if line.hasPrefix("#EXT-X-MEDIA-SEQUENCE:") {
-                mediaSequence = Int(line.dropFirst("#EXT-X-MEDIA-SEQUENCE:".count)) ?? 0
+                // A hostile or MITM value near Int.max makes `mediaSequence + segments.count`
+                // overflow and trap downstream (audit NET-3); reject it here instead. A merely
+                // unparseable tag keeps the pre-existing default of 0.
+                if let parsed = Int(line.dropFirst("#EXT-X-MEDIA-SEQUENCE:".count)) {
+                    guard parsed >= 0, parsed <= Int.max / 2 else {
+                        throw HLSIngestError.playlistInvalid(reason: "media sequence out of range")
+                    }
+                    mediaSequence = parsed
+                }
             } else if line.hasPrefix("#EXTINF:") {
                 let payload = line.dropFirst("#EXTINF:".count)
                 pendingDuration = Double(payload.split(separator: ",").first.map(String.init) ?? "")
diff --git a/Sources/AetherEngine/IO/HLSIngest/HLSPlaylistTracker.swift b/Sources/AetherEngine/IO/HLSIngest/HLSPlaylistTracker.swift
index 851d74fa4..3e48c225a 100644
--- a/Sources/AetherEngine/IO/HLSIngest/HLSPlaylistTracker.swift
+++ b/Sources/AetherEngine/IO/HLSIngest/HLSPlaylistTracker.swift
@@ -41,10 +41,13 @@ struct HLSPlaylistTracker {
 
     mutating func newSegments(in playlist: HLSMediaPlaylist) -> [HLSMediaSegment] {
         let windowStart = playlist.mediaSequence
-        let windowEnd = playlist.mediaSequence + playlist.segments.count // exclusive
+        // The parser rejects a MEDIA-SEQUENCE outside `0...Int.max/2` (audit NET-3), but the struct
+        // itself can be built directly (tests, or a future caller), so this combines with `&+`/`&-`
+        // rather than trapping on a value that slipped past that guard.
+        let windowEnd = playlist.mediaSequence &+ playlist.segments.count // exclusive
 
         func segments(from sequence: Int, markFirstDiscontinuity: Bool) -> [HLSMediaSegment] {
-            let startIndex = sequence - windowStart
+            let startIndex = sequence &- windowStart
             guard startIndex < playlist.segments.count else { return [] }
             var result = Array(playlist.segments[max(0, startIndex)...])
             if markFirstDiscontinuity, !result.isEmpty {
@@ -70,7 +73,7 @@ struct HLSPlaylistTracker {
                 taken += 1
                 seconds += segment.duration
             }
-            return windowEnd - taken
+            return windowEnd &- taken
         }
 
         guard let cursor = nextSequence else {
diff --git a/Tests/AetherEngineTests/HLSPlaylistTests.swift b/Tests/AetherEngineTests/HLSPlaylistTests.swift
index dbbe00aa9..086257d6d 100644
--- a/Tests/AetherEngineTests/HLSPlaylistTests.swift
+++ b/Tests/AetherEngineTests/HLSPlaylistTests.swift
@@ -204,6 +204,48 @@ final class HLSPlaylistTests: XCTestCase {
         XCTAssertThrowsError(try HLSPlaylistParser.parse("#EXTM3U\n#EXT-X-TARGETDURATION:6\n"))
     }
 
+    // audit NET-2 / NAT-3: "\r\n" is one Character in Swift, so `split(separator: "\n")` read a
+    // whole CRLF playlist (Windows-hosted IPTV panels, some packagers) as a single line.
+    func testParsesCRLFMediaPlaylist() throws {
+        let text = "#EXTM3U\r\n#EXT-X-TARGETDURATION:6\r\n#EXT-X-MEDIA-SEQUENCE:147\r\n"
+        + "#EXTINF:6.000,\r\nseg147.ts\r\n"
+        guard case .media(let media) = try HLSPlaylistParser.parse(text) else {
+            return XCTFail("expected media playlist")
+        }
+        XCTAssertEqual(media.targetDuration, 6.0)
+        XCTAssertEqual(media.mediaSequence, 147)
+        XCTAssertEqual(media.segments.map(\.uri), ["seg147.ts"])
+    }
+
+    func testParsesCRLFMasterPlaylist() throws {
+        let text = "#EXTM3U\r\n#EXT-X-STREAM-INF:BANDWIDTH=1000\r\nv.m3u8\r\n"
+        guard case .master(let master) = try HLSPlaylistParser.parse(text) else {
+            return XCTFail("expected master playlist")
+        }
+        XCTAssertEqual(master.variants.map(\.uri), ["v.m3u8"])
+    }
+
+    // audit NET-3: a hostile or MITM MEDIA-SEQUENCE near Int.max used to reach
+    // `mediaSequence + segments.count` unchecked in HLSPlaylistTracker and trap.
+    func testRejectsMediaSequenceNearIntMax() {
+        let text = "#EXTM3U\n#EXT-X-TARGETDURATION:6\n#EXT-X-MEDIA-SEQUENCE:9223372036854775807\n"
+        + "#EXTINF:6.000,\nseg.ts\n"
+        XCTAssertThrowsError(try HLSPlaylistParser.parse(text)) { error in
+            guard case HLSIngestError.playlistInvalid = error else {
+                return XCTFail("expected playlistInvalid, got \(error)")
+            }
+        }
+    }
+
+    func testRejectsNegativeMediaSequence() {
+        let text = "#EXTM3U\n#EXT-X-TARGETDURATION:6\n#EXT-X-MEDIA-SEQUENCE:-1\n#EXTINF:6.000,\nseg.ts\n"
+        XCTAssertThrowsError(try HLSPlaylistParser.parse(text)) { error in
+            guard case HLSIngestError.playlistInvalid = error else {
+                return XCTFail("expected playlistInvalid, got \(error)")
+            }
+        }
+    }
+
     // AE#359: the master's SUBTITLES group was parsed away, so a live channel that offers WebVTT
     // renditions (every public German broadcaster does) had no subtitle track to select. Fixture is
     // MDR Sachsen's real master, trimmed to one variant and its rendition line.
diff --git a/Tests/AetherEngineTests/HLSPlaylistTrackerTests.swift b/Tests/AetherEngineTests/HLSPlaylistTrackerTests.swift
index 32d46b2ac..b33128edb 100644
--- a/Tests/AetherEngineTests/HLSPlaylistTrackerTests.swift
+++ b/Tests/AetherEngineTests/HLSPlaylistTrackerTests.swift
@@ -161,6 +161,15 @@ final class HLSPlaylistTrackerTests: XCTestCase {
         XCTAssertEqual(new.map(\.uri), ["e", "f"])
     }
 
+    // audit NET-3: a MEDIA-SEQUENCE the parser somehow let through near Int.max used to trap
+    // `mediaSequence + segments.count` here. `&+`/`&-` compute mod 2^64, so relative distances
+    // (and therefore which segments are new) come out the same as at a small sequence number.
+    func testDoesNotTrapOnMediaSequenceNearIntMax() {
+        var tracker = HLSPlaylistTracker(edgeOffset: 3, minJoinCoverageSeconds: 8)
+        let new = tracker.newSegments(in: playlist(sequence: Int.max - 1, uris: ["a", "b", "c"]))
+        XCTAssertEqual(new.map(\.uri), ["b", "c"])
+    }
+
     func testJoinSegmentLimitAppliesTheMarginOnlyBelowTheCap() {
         XCTAssertEqual(HLSPlaylistTracker.joinSegmentLimit(edgeOffset: 8, windowSegmentCount: 3), 8)
         XCTAssertEqual(HLSPlaylistTracker.joinSegmentLimit(edgeOffset: 8, windowSegmentCount: 4), 3)

From e758fe8f8b628bc73503f70e6ddb4f599b65f6ae Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 06:07:37 +0200
Subject: [PATCH 074/359] fix(disc): bound the UDF volume descriptor scan and
 partition-map field reads (audit NET-4, NET-11)

vdsLen is an untrusted u32 taken straight from the anchor; unclamped it can
drive up to ~2 million sequential sector reads before parsing ever fails.
Clamp it to 256 sectors (a real Volume Descriptor Sequence is 16 per
ECMA-167), and actually stop at the Terminating Descriptor: the `break`
inside the tag switch only exited the switch, not the scan loop.

Separately, off + len <= lvd.count only bounds a partition map's OWN
declared length; type 1 and type 2 maps read fixed fields past that length
(off+4, off+38..43), so a short len with a long-enough run of preceding maps
still let those reads run past the sector buffer and trap. Require len >= 6
/ len >= 44 before reading those fields; a too-short map of a known type
falls through to the existing generic placeholder.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 Sources/AetherEngine/Disc/UDFReader.swift    | 17 +++--
 Tests/AetherEngineTests/UDFReaderTests.swift | 66 ++++++++++++++++++++
 2 files changed, 78 insertions(+), 5 deletions(-)

diff --git a/Sources/AetherEngine/Disc/UDFReader.swift b/Sources/AetherEngine/Disc/UDFReader.swift
index a8f10dc3e..5caad1b7f 100644
--- a/Sources/AetherEngine/Disc/UDFReader.swift
+++ b/Sources/AetherEngine/Disc/UDFReader.swift
@@ -97,15 +97,18 @@ final class UDFReader {
         let avdp = try readSector(256)
         guard tagID(avdp) == 2 else { throw DiscError.notUDF }
         let vdsLen = u32(avdp, 16), vdsLoc = u32(avdp, 20)
-        let vdsSectors = max(1, vdsLen / ss)
+        // A real Volume Descriptor Sequence is 16 sectors (ECMA-167); vdsLen is an untrusted u32
+        // from the anchor, and an unclamped one can drive millions of sector reads before parsing
+        // ever fails (audit NET-11).
+        let vdsSectors = min(max(1, vdsLen / ss), 256)
 
         var lvd: [UInt8]? = nil
-        for i in 0..<vdsSectors {
+        volumeDescriptorSequence: for i in 0..<vdsSectors {
             let d = try readSector(vdsLoc + i)
             switch tagID(d) {
             case 5: physPartStart[u16(d, 22)] = u32(d, 188)  // Partition Descriptor
             case 6: lvd = d                                   // LVD
-            case 8: break                                     // Terminating
+            case 8: break volumeDescriptorSequence            // Terminating (bare `break` only exits the switch, audit NET-11)
             default: break
             }
         }
@@ -119,10 +122,14 @@ final class UDFReader {
             guard off + 2 <= lvd.count else { break }
             let type = Int(lvd[off]); let len = Int(lvd[off+1])
             guard len > 0, off + len <= lvd.count else { break }
-            if type == 1 {
+            // `off + len <= lvd.count` only bounds the map's OWN declared length; type 1 and type 2
+            // maps read fixed fields past that length (off+4, off+38..43), so a short len with a
+            // long-enough neighbour still let those reads run past the sector buffer and trap
+            // (audit NET-4). A too-short map of a known type falls through to the generic case below.
+            if type == 1, len >= 6 {
                 let pn = u16(lvd, off+4)
                 partMaps.append(PartMap(isMetadata: false, physicalPartNumber: pn, metadataFileBlock: 0))
-            } else if type == 2 {
+            } else if type == 2, len >= 44 {
                 let pn = u16(lvd, off+38)
                 let metaFileBlock = u32(lvd, off+40)
                 partMaps.append(PartMap(isMetadata: true, physicalPartNumber: pn, metadataFileBlock: metaFileBlock))
diff --git a/Tests/AetherEngineTests/UDFReaderTests.swift b/Tests/AetherEngineTests/UDFReaderTests.swift
index 905aa87b7..688afaba8 100644
--- a/Tests/AetherEngineTests/UDFReaderTests.swift
+++ b/Tests/AetherEngineTests/UDFReaderTests.swift
@@ -94,6 +94,38 @@ final class UDFReaderTests: XCTestCase {
         }
     }
 
+    // audit NET-4: `off + len <= lvd.count` only bounds the map's OWN declared length; a type 1 or
+    // type 2 map short enough to pass that check but too short to hold the fields the reader
+    // indexes (off+4, off+38..43) used to read past the sector buffer and trap once a run of
+    // padding maps pushed `off` near the sector's end.
+    func test_craftedPartitionMapDoesNotReadPastSector() {
+        var data = [UInt8](image())
+        let lvdBase = 258 * 2048
+        var maps: [UInt8] = []
+        for _ in 0..<6 { maps += [0, 255] + [UInt8](repeating: 0, count: 253) } // type 0, len 255 (padding)
+        maps += [0, 74] + [UInt8](repeating: 0, count: 72)                     // type 0, len 74 (padding)
+        maps += [1, 2]                                                         // type 1, len 2: too short for off+4
+        XCTAssertLessThanOrEqual(440 + maps.count, 2048, "the crafted layout must still fit the sector")
+        for (i, b) in maps.enumerated() { data[lvdBase + 440 + i] = b }
+        for (i, b) in UDFFixture.le32(maps.count).enumerated() { data[lvdBase + 264 + i] = b } // MapTableLength
+        for (i, b) in UDFFixture.le32(8).enumerated() { data[lvdBase + 268 + i] = b }          // NumberOfPartitionMaps
+        XCTAssertThrowsError(try UDFReader(reader: DataIOReader(data: Data(data))))
+    }
+
+    // audit NET-11: `vdsLen` is an untrusted u32 from the anchor; unclamped it can drive up to
+    // ~2 million sequential sector reads before parsing fails. The scan must stay capped near the
+    // real Volume Descriptor Sequence's size (ECMA-167: 16 sectors) instead of trusting the anchor.
+    func test_hostileAnchorLengthCapsTheVDSScan() {
+        let mock = SparseSectorReader()
+        var avdp = [UInt8](repeating: 0, count: 2048)
+        UDFFixture.tag(2, location: 256, into: &avdp)
+        avdp[16..<24] = ArraySlice(UDFFixture.extentAD(lenBytes: 0xFFFF_FFFF, location: 300))
+        mock.setSector(256, avdp)
+        XCTAssertThrowsError(try UDFReader(reader: mock))
+        XCTAssertTrue((200...300).contains(mock.sectorReads),
+                      "expected the VDS scan capped near 256 sectors, got \(mock.sectorReads)")
+    }
+
     func test_truncatedImageThrowsNotTrap() throws {
         // UDF image truncated before VDS (AVDP present at sector 256, VDS cut off): must throw, not trap.
         func be16(_ v: Int) -> [UInt8] { [UInt8((v>>8)&0xff), UInt8(v&0xff)] }
@@ -117,3 +149,37 @@ final class UDFReaderTests: XCTestCase {
         }())
     }
 }
+
+/// Answers every sector as zero-filled unless a specific one was set, and counts reads: proves a
+/// scan is bounded rather than trusting an untrusted extent length (audit NET-11).
+private final class SparseSectorReader: IOReader, @unchecked Sendable {
+    private let ss = 2048
+    private var sectors: [Int: [UInt8]] = [:]
+    private var position: Int64 = 0
+    private let lock = NSLock()
+    private var _sectorReads = 0
+    var sectorReads: Int { lock.lock(); defer { lock.unlock() }; return _sectorReads }
+
+    func setSector(_ index: Int, _ bytes: [UInt8]) { sectors[index] = bytes }
+
+    func read(_ buffer: UnsafeMutablePointer<UInt8>?, size: Int32) -> Int32 {
+        guard let buffer, size > 0 else { return -1 }
+        lock.lock(); defer { lock.unlock() }
+        let sector = Int(position / Int64(ss))
+        let bytes = sectors[sector] ?? [UInt8](repeating: 0, count: ss)
+        let n = min(Int(size), bytes.count)
+        bytes.withUnsafeBufferPointer { buffer.update(from: $0.baseAddress!, count: n) }
+        position += Int64(n)
+        _sectorReads += 1
+        return Int32(n)
+    }
+
+    func seek(offset: Int64, whence: Int32) -> Int64 {
+        if whence == 65536 { return Int64.max / 2 }
+        guard whence == SEEK_SET else { return -1 }
+        position = offset
+        return position
+    }
+
+    func close() {}
+}

From 49ab19cb4d196dae50ec9cf00641aef68c3bff32 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 06:07:44 +0200
Subject: [PATCH 075/359] fix(disc): cap ISO9660 directory extents instead of
 trapping on a hostile length (audit NET-5)

A directory record's length is an unchecked on-disc u32. A crafted root or
subdirectory record declaring 0xFFFFFFFF zero-fills up to 4 GB before a
single byte is read (jetsam on tvOS/iOS), and Int32(count - got) traps for
anything past Int32.max. Cap a directory extent at 8 MB, matching
UDFReader.readDirectory's own directory cap, and clamp every read chunk so
the Int32 conversion is always in range regardless of what a future caller
passes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 Sources/AetherEngine/Disc/ISO9660Reader.swift | 16 +++++++++++++--
 .../ISO9660ReaderTests.swift                  | 20 +++++++++++++++++++
 2 files changed, 34 insertions(+), 2 deletions(-)

diff --git a/Sources/AetherEngine/Disc/ISO9660Reader.swift b/Sources/AetherEngine/Disc/ISO9660Reader.swift
index a0fcc1b0e..2329d9ad2 100644
--- a/Sources/AetherEngine/Disc/ISO9660Reader.swift
+++ b/Sources/AetherEngine/Disc/ISO9660Reader.swift
@@ -102,8 +102,17 @@ final class ISO9660Reader {
 
     // MARK: - Raw IO
 
+    /// Matches `UDFReader.readDirectory`'s directory cap. `length` is an unchecked on-disc u32
+    /// (root record or a subdirectory record); unclamped, a crafted `0xFFFFFFFF` zero-fills up to
+    /// 4 GB (jetsam on tvOS/iOS) and `Int32(count - got)` traps for anything past `Int32.max`
+    /// (audit NET-5).
+    private static let maxExtentBytes = 8 * 1024 * 1024
+
     private func readExtent(lba: Int, length: Int) throws -> [UInt8] {
-        try ISO9660Reader.readBytes(reader, at: lba * sectorSize, count: length)
+        guard length >= 0, length <= Self.maxExtentBytes else {
+            throw DiscError.malformed("extent length \(length) exceeds \(Self.maxExtentBytes) bytes")
+        }
+        return try ISO9660Reader.readBytes(reader, at: lba * sectorSize, count: length)
     }
 
     private static func readBytes(_ reader: IOReader, at offset: Int, count: Int) throws -> [UInt8] {
@@ -114,7 +123,10 @@ final class ISO9660Reader {
         var got = 0
         try buf.withUnsafeMutableBufferPointer { ptr in
             while got < count {
-                let n = reader.read(ptr.baseAddress!.advanced(by: got), size: Int32(count - got))
+                // Clamped so `Int32(...)` is always a checked, in-range conversion, whatever `count`
+                // a future caller passes (audit NET-5: `Int32(count - got)` used to trap directly).
+                let chunk = min(count - got, 1 << 20)
+                let n = reader.read(ptr.baseAddress!.advanced(by: got), size: Int32(chunk))
                 if n == 0 { break }            // EOF
                 if n < 0 { throw DiscError.malformed("read error at \(offset + got)") }
                 got += Int(n)
diff --git a/Tests/AetherEngineTests/ISO9660ReaderTests.swift b/Tests/AetherEngineTests/ISO9660ReaderTests.swift
index 1ad61d479..1aa417284 100644
--- a/Tests/AetherEngineTests/ISO9660ReaderTests.swift
+++ b/Tests/AetherEngineTests/ISO9660ReaderTests.swift
@@ -32,6 +32,26 @@ final class ISO9660ReaderTests: XCTestCase {
         }
     }
 
+    // audit NET-5: an unchecked 32-bit directory length let a crafted root record zero-fill up to
+    // 4 GB (jetsam on tvOS/iOS) and then trap converting `count - got` to Int32. Must throw a
+    // normal error instead, and never attempt the allocation.
+    func test_hostileRootLengthIsRejectedNotAllocated() throws {
+        var pvd = [UInt8](repeating: 0, count: ISO9660Fixture.sectorSize)
+        pvd[0] = 1
+        for (i, b) in Array("CD001".utf8).enumerated() { pvd[1 + i] = b }
+        pvd[6] = 1
+        for (i, b) in ISO9660Fixture.both16(ISO9660Fixture.sectorSize).enumerated() { pvd[128 + i] = b }
+        let rootRec = ISO9660Fixture.dirRecord(name: [0x00], isDir: true, lba: 17, length: 0xFFFF_FFFF)
+        for (i, b) in rootRec.enumerated() { pvd[156 + i] = b }
+        var image = [UInt8](repeating: 0, count: 18 * ISO9660Fixture.sectorSize)
+        for (i, b) in pvd.enumerated() { image[16 * ISO9660Fixture.sectorSize + i] = b }
+
+        let iso = try ISO9660Reader(reader: DataIOReader(data: Data(image)))
+        XCTAssertThrowsError(try iso.list(directory: "VIDEO_TS")) { err in
+            guard case DiscError.malformed = err else { return XCTFail("wrong error: \(err)") }
+        }
+    }
+
     func test_truncatedImageThrowsMalformedOrNotISO() throws {
         // PVD present but root extent cut off: must throw, not trap.
         let full = ISO9660Fixture.make(files: [.init(name: "VTS_01_1.VOB", length: 100)])

From 98259714fb4b72ffeb7a793591a389127ac19f55 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 06:07:49 +0200
Subject: [PATCH 076/359] docs(changelog): audit segment pipeline and bitstream
 fixes

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 CHANGELOG.md | 24 +++++++++++++++++++++---
 1 file changed, 21 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8944baef6..a91909768 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -29,9 +29,22 @@ the public-API contract.
   no longer inject header lines and IPv6 hosts get a valid Host header (audit DMX-3, DMX-4).
 - **A sidecar subtitle name can no longer add lines to the served HLS master.** Line breaks and other
   control characters in a name or language are neutralised (audit NAT-6).
-
-### Fixed
-
+- **A crafted or broken source timestamp no longer crashes the app.** Demuxed pts/dts beyond
+  plus or minus 2^60 are treated as unset, and the segment pump's timestamp arithmetic saturates
+  instead of trapping (audit SEG-1).
+- **The Dolby Vision profile check can no longer read a whole file while playback is starting.** It
+  stops after a fixed number of packets from any stream, or 64 MiB (audit BIT-2).
+
+### Fixed
+
+- **Closing the player during a scrub restart no longer spins segment requests at full CPU**
+  (audit SEG-3).
+- **A re-cut segment can no longer be dropped by a request that is reading it at the same moment**,
+  and a replaced pump no longer stores a cut-off segment (audit SEG-4, SEG-5).
+- **Segments with a 256 to 511 byte first NAL are covered by the AE#561 repair**, instead of being
+  mistaken for Annex B and failing with -19602 (audit BIT-1).
+- **Matroska H.264 timing repair no longer gives two frames the same time at a GOP boundary**
+  (audit BIT-3).
 - **A slow source no longer ends a healthy session with "Source read failed" after a few scrubs.**
   When the engine replaced a producer stuck in a read, the old producer's aborted read was treated as
   the session failing: it spent the read-error revive budget, forced an extra reconnect and re-seeked
@@ -85,6 +98,11 @@ the public-API contract.
   core and flooding the log (audit NET-13).
 - **The server's stop line names the port it released** (audit NET-12).
 
+### Performance
+
+- **Faster first segment after a seek on TrueHD sources, and less CPU for HDR10+ detection on sources
+  without HDR10+** (audit SEG-6, BIT-4).
+
 ## [7.16.1] - 2026-09-24
 
 ### Fixed

From a7c76025135988c48a8d4e599d113eba5a836a2f Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 06:07:53 +0200
Subject: [PATCH 077/359] fix(disc): require an exact-offset 206 for a remote
 disc image read (audit NET-9)

Range support is only verified once, in init's probe. After that,
fetchWithRetry accepted any 206 (its Content-Range never checked) or an
unrelated 200, and stored the body as if it started at `position`. A CDN or
proxy that falls back to a full 200 on a cache miss, coalesces ranges, or
answers a 206 that starts somewhere else silently misplaces disc structure
or media bytes, and a full 200 on a large ISO buffers the whole file before
anything can use it. Now a response is only accepted as a 206 whose parsed
Content-Range start equals the requested offset, and the body is trimmed to
the requested length in case the server sent more.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 .../AetherEngine/IO/HTTPDiscIOReader.swift    | 21 ++++++++-
 .../HTTPDiscIOReaderTests.swift               | 47 ++++++++++++++++++-
 2 files changed, 65 insertions(+), 3 deletions(-)

diff --git a/Sources/AetherEngine/IO/HTTPDiscIOReader.swift b/Sources/AetherEngine/IO/HTTPDiscIOReader.swift
index 3c40980df..4e1fff94e 100644
--- a/Sources/AetherEngine/IO/HTTPDiscIOReader.swift
+++ b/Sources/AetherEngine/IO/HTTPDiscIOReader.swift
@@ -88,6 +88,15 @@ final class HTTPDiscIOReader: IOReader, @unchecked Sendable {
         return Int64(total)
     }
 
+    /// Start offset from a `Content-Range` value (`bytes 100-200/12345` -> 100). Nil for junk.
+    static func parseContentRangeStart(_ value: String) -> Int64? {
+        let trimmed = value.trimmingCharacters(in: .whitespaces)
+        guard trimmed.hasPrefix("bytes ") else { return nil }
+        let rest = trimmed.dropFirst("bytes ".count)
+        guard let dash = rest.firstIndex(of: "-") else { return nil }
+        return Int64(rest[rest.startIndex..<dash])
+    }
+
     /// Next adaptive window: `base` when `position` is not the sequential continuation of the last
     /// refill, otherwise the previous window doubled and capped at `maxChunkSize`.
     static func nextChunkSize(position: Int64, lastFetchEnd: Int64, current: Int,
@@ -158,6 +167,12 @@ final class HTTPDiscIOReader: IOReader, @unchecked Sendable {
     // MARK: - HTTP
 
     /// One range GET retried up to `maxRetries` times with linear backoff; aborts early on cancel.
+    ///
+    /// Requires a 206 whose `Content-Range` start matches `offset` exactly: a proxy that answers a
+    /// range request with a full 200 (cache miss, range coalescing, a Range-stripping origin) or a
+    /// 206 that starts somewhere else places its body at `position` regardless, corrupting the disc
+    /// structure or media stream read through it (audit NET-9). The body is also trimmed to `length`
+    /// in case the server sent more than asked.
     private func fetchWithRetry(offset: Int64, length: Int) -> Data? {
         var attempt = 0
         while true {
@@ -165,8 +180,10 @@ final class HTTPDiscIOReader: IOReader, @unchecked Sendable {
             if stop { return nil }
             if let r = Self.rangeGet(url: url, extraHeaders: extraHeaders, session: session,
                                      timeout: requestTimeout, offset: offset, length: length),
-               r.status == 206 || r.status == 200, !r.body.isEmpty {
-                return r.body
+               r.status == 206, !r.body.isEmpty,
+               let contentRange = r.contentRange,
+               Self.parseContentRangeStart(contentRange) == offset {
+                return r.body.count > length ? r.body.prefix(length) : r.body
             }
             attempt += 1
             if attempt > maxRetries { return nil }
diff --git a/Tests/AetherEngineTests/HTTPDiscIOReaderTests.swift b/Tests/AetherEngineTests/HTTPDiscIOReaderTests.swift
index 2d3695ec6..e17b0ad53 100644
--- a/Tests/AetherEngineTests/HTTPDiscIOReaderTests.swift
+++ b/Tests/AetherEngineTests/HTTPDiscIOReaderTests.swift
@@ -112,6 +112,34 @@ struct HTTPDiscIOReaderTests {
         #expect(Array(out[0..<100]) == Array(src[0..<100]))
     }
 
+    // audit NET-9: a 206 that claims a different start than what was requested must never be
+    // accepted; the reader would otherwise place those bytes at `position` and corrupt whatever
+    // structure or stream is read through it.
+    @Test("A 206 whose Content-Range start does not match the request is refused, not served")
+    func misrangedResponseIsRefused() throws {
+        let src = (0..<2000).map { UInt8($0 & 0xff) }
+        let r = try #require(makeReader(src))  // the offset-0 probe is unaffected and succeeds
+        MockRangeURLProtocol.misrangedFor.insert("http://disc.test/test.iso")
+        #expect(r.seek(offset: 1000, whence: SEEK_SET) == 1000)
+        var out = [UInt8](repeating: 0, count: 100)
+        let n = out.withUnsafeMutableBufferPointer { r.read($0.baseAddress, size: 100) }
+        #expect(n == -1)
+    }
+
+    // audit NET-9: a proxy that falls back to a full 200 mid-session (cache miss, range
+    // coalescing, a Range-stripping origin) must be treated as fatal for this reader, not read as
+    // if byte 0 of the body were the requested offset.
+    @Test("A 200 answer mid-session is refused, not served as if it started at the requested offset")
+    func plain200MidSessionIsRefused() throws {
+        let src = (0..<2000).map { UInt8($0 & 0xff) }
+        let r = try #require(makeReader(src))  // the offset-0 probe is unaffected and succeeds
+        MockRangeURLProtocol.plain200AfterProbeFor.insert("http://disc.test/test.iso")
+        #expect(r.seek(offset: 1000, whence: SEEK_SET) == 1000)
+        var out = [UInt8](repeating: 0, count: 100)
+        let n = out.withUnsafeMutableBufferPointer { r.read($0.baseAddress, size: 100) }
+        #expect(n == -1)
+    }
+
     @Test("A server without range support fails init (caller falls back to streaming)")
     func noRangeSupport() {
         let url = URL(string: "http://disc.test/noRange.iso")!
@@ -143,9 +171,17 @@ final class MockRangeURLProtocol: URLProtocol, @unchecked Sendable {
     nonisolated(unsafe) static var disableRangeFor: Set<String> = []
     /// Number of leading requests per URL that should fail with a network error (retry testing).
     nonisolated(unsafe) static var failFirstForURL: [String: Int] = [:]
+    /// audit NET-9: any request at a non-zero offset gets a 206 that claims to start at 0 (a
+    /// mis-ranged response) instead of the requested offset, with junk bytes so a caller that
+    /// trusted it would read garbage rather than the source.
+    nonisolated(unsafe) static var misrangedFor: Set<String> = []
+    /// audit NET-9: any request at a non-zero offset gets a full 200 instead of a 206 (a
+    /// Range-ignoring proxy or a cache-miss fallback), body starting at byte 0 of the source.
+    nonisolated(unsafe) static var plain200AfterProbeFor: Set<String> = []
 
     static func reset() {
         bytesByURL = [:]; disableRangeFor = []; failFirstForURL = [:]
+        misrangedFor = []; plain200AfterProbeFor = []
     }
 
     override class func canInit(with request: URLRequest) -> Bool { true }
@@ -180,7 +216,16 @@ final class MockRangeURLProtocol: URLProtocol, @unchecked Sendable {
             status = 206
             headers["Content-Range"] = "bytes \(lower)-\(upper)/\(total)"
         }
-        let slice = (lower <= upper && lower < total) ? data.subdata(in: lower..<(upper + 1)) : Data()
+        var slice = (lower <= upper && lower < total) ? data.subdata(in: lower..<(upper + 1)) : Data()
+        if lower > 0, status == 206, Self.misrangedFor.contains(url.absoluteString) {
+            headers["Content-Range"] = "bytes 0-\(slice.count - 1)/\(total)"
+            slice = Data(repeating: 0xEE, count: slice.count)
+        }
+        if lower > 0, status == 206, Self.plain200AfterProbeFor.contains(url.absoluteString) {
+            status = 200
+            headers["Content-Range"] = nil
+            slice = data
+        }
         headers["Content-Length"] = String(slice.count)
         let resp = HTTPURLResponse(url: url, statusCode: status, httpVersion: "HTTP/1.1", headerFields: headers)!
         client?.urlProtocol(self, didReceive: resp, cacheStoragePolicy: .notAllowed)

From 49d6ec6f8245916ef73896d2abd3a6e9dedf7e84 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 06:08:01 +0200
Subject: [PATCH 078/359] perf(hls): stop re-copying the whole FIFO buffer on
 every read (audit NET-8)

storage.subdata(in:) re-bases the FIFO's single Data buffer on every read,
copying whatever is still queued. With a full 16 MB FIFO drained in 256 KB
reads that is about 64 reads averaging an 8 MB copy each, roughly 512 MB of
memcpy (plus 64 up-to-16 MB allocations) for every 16 MB actually delivered,
which is the normal live state once the producer gets ahead of the
real-time demuxer.

Switch to the shape HLSVODIngestReader already uses: a queue of whole
written chunks plus a head offset into the front one, dropping a fully
consumed chunk with Array.removeFirst (an Array operation, not
Data.removeFirst's slice-retention problem the single-buffer design was
built to avoid). Read/write semantics are unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 .../AetherEngine/IO/HLSIngest/ByteFIFO.swift  | 45 ++++++++++++++-----
 Tests/AetherEngineTests/ByteFIFOTests.swift   | 31 +++++++++++++
 2 files changed, 66 insertions(+), 10 deletions(-)

diff --git a/Sources/AetherEngine/IO/HLSIngest/ByteFIFO.swift b/Sources/AetherEngine/IO/HLSIngest/ByteFIFO.swift
index 9d2f5d295..625fe2f58 100644
--- a/Sources/AetherEngine/IO/HLSIngest/ByteFIFO.swift
+++ b/Sources/AetherEngine/IO/HLSIngest/ByteFIFO.swift
@@ -1,10 +1,19 @@
 import Foundation
 
-/// Bounded blocking byte queue between the HLS fetch loop (writer) and demux thread (reader). NSCondition-based; `finish()` signals EOF, `cancel()` signals error. Capacity is a soft bound: write blocks while at/above capacity then appends the whole chunk (overshoot = at most one chunk). Storage uses `subdata` re-base on consume, never `removeFirst` (Data.removeFirst slice-leak, AetherEngine 70430de).
+/// Bounded blocking byte queue between the HLS fetch loop (writer) and demux thread (reader). NSCondition-based; `finish()` signals EOF, `cancel()` signals error. Capacity is a soft bound: write blocks while at/above capacity then appends the whole chunk (overshoot = at most one chunk).
+///
+/// Storage is a queue of whole written chunks plus a head offset into the front one, the same shape
+/// `HLSVODIngestReader` uses: a consumed chunk is dropped with `Array.removeFirst` (an Array op, not
+/// `Data.removeFirst`'s slice-leak, AetherEngine 70430de). Earlier this was one `Data` re-based with
+/// `subdata` on every read, which re-copies whatever is still queued: draining a full 16 MB FIFO in
+/// 256 KB reads did about 64 reads averaging an 8 MB copy each, roughly 512 MB of memcpy for 16 MB
+/// delivered (audit NET-8).
 final class ByteFIFO: @unchecked Sendable {
     private let capacity: Int
     private let condition = NSCondition()
-    private var storage = Data()
+    private var queue: [Data] = []
+    private var headOffset = 0
+    private var pendingCount = 0
     private var finished = false
     private var cancelled = false
     /// Callers parked in `read` or `write`, guarded by the condition above. A reader from another
@@ -27,12 +36,13 @@ final class ByteFIFO: @unchecked Sendable {
         condition.lock()
         defer { condition.unlock() }
         parked += 1
-        while storage.count >= capacity && !finished && !cancelled {
+        while pendingCount >= capacity && !finished && !cancelled {
             condition.wait()
         }
         parked -= 1
         if finished || cancelled { return false }
-        storage.append(data)
+        queue.append(data)
+        pendingCount += data.count
         condition.broadcast()
         return true
     }
@@ -42,17 +52,32 @@ final class ByteFIFO: @unchecked Sendable {
         condition.lock()
         defer { condition.unlock() }
         parked += 1
-        while storage.isEmpty && !finished && !cancelled {
+        while queue.isEmpty && !finished && !cancelled {
             condition.wait()
         }
         parked -= 1
         if cancelled { return -1 }
-        if storage.isEmpty { return 0 } // finished + drained
-        let n = min(maxLength, storage.count)
-        storage.copyBytes(to: UnsafeMutableBufferPointer(start: buffer, count: n), from: 0..<n)
-        storage = storage.subdata(in: n..<storage.count) // subdata re-base: Data.removeFirst retains backing storage
+        guard !queue.isEmpty else { return 0 } // finished + drained
+
+        var copied = 0
+        while copied < maxLength, !queue.isEmpty {
+            let available = queue[0].count - headOffset
+            let n = min(maxLength - copied, available)
+            queue[0].withUnsafeBytes { raw in
+                guard let base = raw.baseAddress else { return }
+                buffer.advanced(by: copied).update(
+                    from: base.assumingMemoryBound(to: UInt8.self).advanced(by: headOffset), count: n)
+            }
+            headOffset += n
+            copied += n
+            pendingCount -= n
+            if headOffset == queue[0].count {
+                queue.removeFirst()
+                headOffset = 0
+            }
+        }
         condition.broadcast()
-        return n
+        return copied
     }
 
     func finish() {
diff --git a/Tests/AetherEngineTests/ByteFIFOTests.swift b/Tests/AetherEngineTests/ByteFIFOTests.swift
index 96e9cdbdf..76e9f3fd6 100644
--- a/Tests/AetherEngineTests/ByteFIFOTests.swift
+++ b/Tests/AetherEngineTests/ByteFIFOTests.swift
@@ -61,6 +61,37 @@ final class ByteFIFOTests: XCTestCase {
         wait(for: [expectation], timeout: 2)
     }
 
+    // audit NET-8: storage moved from one re-based `Data` to a queue of chunks plus a head offset;
+    // these pin that a read still spans chunk boundaries and resumes mid-chunk correctly.
+    func testReadSpansMultipleWrites() {
+        let fifo = ByteFIFO(capacity: 1024)
+        XCTAssertTrue(fifo.write(Data([1, 2])))
+        XCTAssertTrue(fifo.write(Data([3, 4, 5])))
+        var buffer = [UInt8](repeating: 0, count: 10)
+        let n = buffer.withUnsafeMutableBufferPointer {
+            fifo.read(into: $0.baseAddress!, maxLength: 10)
+        }
+        XCTAssertEqual(n, 5)
+        XCTAssertEqual(Array(buffer[0..<5]), [1, 2, 3, 4, 5])
+    }
+
+    func testPartialReadResumesMidChunk() {
+        let fifo = ByteFIFO(capacity: 1024)
+        XCTAssertTrue(fifo.write(Data([1, 2, 3, 4, 5, 6])))
+        var first = [UInt8](repeating: 0, count: 3)
+        let n1 = first.withUnsafeMutableBufferPointer {
+            fifo.read(into: $0.baseAddress!, maxLength: 3)
+        }
+        XCTAssertEqual(n1, 3)
+        XCTAssertEqual(Array(first[0..<3]), [1, 2, 3])
+        var second = [UInt8](repeating: 0, count: 3)
+        let n2 = second.withUnsafeMutableBufferPointer {
+            fifo.read(into: $0.baseAddress!, maxLength: 3)
+        }
+        XCTAssertEqual(n2, 3)
+        XCTAssertEqual(Array(second[0..<3]), [4, 5, 6])
+    }
+
     func testWriteBlocksAtCapacityUntilRead() {
         let fifo = ByteFIFO(capacity: 4)
         XCTAssertTrue(fifo.write(Data([1, 2, 3, 4])))

From 405bc465e9a020bbaf50eaadcbcc60f1e0cc0059 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 06:08:11 +0200
Subject: [PATCH 079/359] fix(native): bound the #316 subtitle proxy's program
 duration and playlist fetch (audit NAT-1, NAT-5)

An origin's #EXTINF:inf, (or a finite but huge total) summed unchecked into
the whole-program duration, which reaches Int(Double) in
wholeSecondsCovering once the sidecar rendition is fetched and traps,
killing the whole process. sumSegmentDurations now refuses a non-finite,
negative or absurd EXTINF sum where it is computed, and
RemoteHLSSubtitleProvider.init clamps again as the last stop before the
value leaves the provider, in case a future caller builds one directly.

Separately, fetchPlaylist read the origin's master/variant body with
session.data(for:), which buffers the whole response with no size cap
(siblings cap at 2 MiB): a hostile or misconfigured origin serving a fast
stream under the m3u8 URL could push the app into jetsam before anything
plays. It now goes through BoundedPlaylistFetch, the same helper the
sibling HLS fetchers use.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 .../Native/RemoteHLSSubtitleProvider.swift    |  8 +++-
 .../Native/RemoteHLSSubtitleProxy.swift       | 35 +++++++++++++--
 .../RemoteHLSSubtitleProxyTests.swift         | 44 +++++++++++++++++++
 3 files changed, 82 insertions(+), 5 deletions(-)

diff --git a/Sources/AetherEngine/Native/RemoteHLSSubtitleProvider.swift b/Sources/AetherEngine/Native/RemoteHLSSubtitleProvider.swift
index b61daf988..7be840124 100644
--- a/Sources/AetherEngine/Native/RemoteHLSSubtitleProvider.swift
+++ b/Sources/AetherEngine/Native/RemoteHLSSubtitleProvider.swift
@@ -44,7 +44,13 @@ final class RemoteHLSSubtitleProvider: HLSSegmentProvider, @unchecked Sendable {
          vttFillWaitSeconds: TimeInterval = defaultVTTFillWaitSeconds) {
         self.tracks = tracks
         self.staticMasterPlaylistBody = masterBody
-        self.programDuration = max(1, programDuration)
+        // `RemoteHLSSubtitleProxy.sumSegmentDurations` already refuses a non-finite, negative or
+        // absurd EXTINF sum before it reaches here; this is the last stop before the value leaves
+        // the provider (`segmentDuration(at:)`) for `wholeSecondsCovering`'s `Int(Double)`, which
+        // traps on `+inf` (audit NAT-1). Bounded again here so a caller that builds this provider
+        // directly, bypassing the proxy, cannot reintroduce the trap.
+        let finiteDuration = programDuration.isFinite ? programDuration : 1
+        self.programDuration = min(max(1, finiteDuration), RemoteHLSSubtitleProxy.maxProgramDurationSeconds)
         self.defaultHeaders = defaultHeaders
         self.vttFillWaitSeconds = vttFillWaitSeconds
         self.stores = tracks.map { _ in NativeSubtitleCueStore() }
diff --git a/Sources/AetherEngine/Native/RemoteHLSSubtitleProxy.swift b/Sources/AetherEngine/Native/RemoteHLSSubtitleProxy.swift
index 7419b055b..b369f27d7 100644
--- a/Sources/AetherEngine/Native/RemoteHLSSubtitleProxy.swift
+++ b/Sources/AetherEngine/Native/RemoteHLSSubtitleProxy.swift
@@ -179,6 +179,12 @@ enum RemoteHLSSubtitleProxy {
             configuration: config, delegate: EngineTLS.sessionDelegate, delegateQueue: nil)
     }
 
+    /// Matches the sibling HLS fetchers (`HLSCarriageProbe`, `HLSVODIngestReader`). This proxy fetches
+    /// an origin master and one variant before AVPlayer ever opens the source, so an origin that
+    /// answers with a fast, unbounded stream under the m3u8 URL could otherwise buffer until jetsam
+    /// (audit NAT-5).
+    private static let maximumPlaylistBytes = 2 * 1024 * 1024
+
     /// Returns the body and the URL it finally came from; every relative URI in the playlist resolves
     /// against the latter, so a redirecting origin (Plex's transcode handoff) still rewrites correctly.
     private static func fetchPlaylist(_ url: URL,
@@ -189,9 +195,10 @@ enum RemoteHLSSubtitleProxy {
         let data: Data
         let response: URLResponse
         do {
-            (data, response) = try await session.data(for: request)
+            (data, response) = try await BoundedPlaylistFetch.data(
+                for: request, session: session, limit: maximumPlaylistBytes)
         } catch {
-            throw Refusal.fetchFailed("\(error.localizedDescription)")
+            throw Refusal.fetchFailed("\(error)")
         }
         if let http = response as? HTTPURLResponse, !(200..<300).contains(http.statusCode) {
             throw Refusal.fetchFailed("HTTP \(http.statusCode)")
@@ -219,7 +226,7 @@ enum RemoteHLSSubtitleProxy {
         switch playlist {
         case .media(let media):
             guard media.hasEndList else { throw Refusal.notVOD }
-            return media.segments.reduce(0) { $0 + $1.duration }
+            return try sumSegmentDurations(media.segments)
         case .master(let master):
             guard let variant = master.variants.first,
                   let variantURL = HLSPlaylistParser.resolve(uri: variant.uri, against: url) else {
@@ -230,7 +237,27 @@ enum RemoteHLSSubtitleProxy {
                 throw Refusal.unusablePlaylist("variant is not a media playlist")
             }
             guard media.hasEndList else { throw Refusal.notVOD }
-            return media.segments.reduce(0) { $0 + $1.duration }
+            return try sumSegmentDurations(media.segments)
+        }
+    }
+
+    /// Longest program this proxy will serve as a whole-program WebVTT rendition.
+    static let maxProgramDurationSeconds: Double = 7 * 24 * 3600
+
+    /// A hostile or malformed EXTINF (`inf`, negative, or a huge total) reaches `Int(Double)` in
+    /// `wholeSecondsCovering` downstream and traps (audit NAT-1); refuse it here instead. Internal
+    /// rather than private so the parsing rule is testable without a network fixture.
+    static func sumSegmentDurations(_ segments: [HLSMediaSegment]) throws -> Double {
+        var total = 0.0
+        for segment in segments {
+            guard segment.duration.isFinite, segment.duration >= 0 else {
+                throw Refusal.unusablePlaylist("EXTINF is not a finite, non-negative duration")
+            }
+            total += segment.duration
+        }
+        guard total.isFinite, total <= maxProgramDurationSeconds else {
+            throw Refusal.unusablePlaylist("program duration exceeds \(maxProgramDurationSeconds)s")
         }
+        return total
     }
 }
diff --git a/Tests/AetherEngineTests/RemoteHLSSubtitleProxyTests.swift b/Tests/AetherEngineTests/RemoteHLSSubtitleProxyTests.swift
index d97e656d2..22e7f7768 100644
--- a/Tests/AetherEngineTests/RemoteHLSSubtitleProxyTests.swift
+++ b/Tests/AetherEngineTests/RemoteHLSSubtitleProxyTests.swift
@@ -242,6 +242,50 @@ struct RemoteHLSSubtitleProxyTests {
         #expect(merged.isEmpty)
     }
 
+    // MARK: - NAT-1: a hostile EXTINF never reaches Int(Double)
+
+    private static func seg(_ duration: Double) -> HLSMediaSegment {
+        HLSMediaSegment(uri: "s.ts", duration: duration, discontinuityBefore: false)
+    }
+
+    @Test("An infinite, negative or absurd EXTINF is refused before it becomes a program duration")
+    func rejectsHostileSegmentDurations() {
+        #expect(throws: RemoteHLSSubtitleProxy.Refusal.self) {
+            _ = try RemoteHLSSubtitleProxy.sumSegmentDurations([Self.seg(.infinity)])
+        }
+        #expect(throws: RemoteHLSSubtitleProxy.Refusal.self) {
+            _ = try RemoteHLSSubtitleProxy.sumSegmentDurations([Self.seg(.nan)])
+        }
+        #expect(throws: RemoteHLSSubtitleProxy.Refusal.self) {
+            _ = try RemoteHLSSubtitleProxy.sumSegmentDurations([Self.seg(-1)])
+        }
+        #expect(throws: RemoteHLSSubtitleProxy.Refusal.self) {
+            // Finite, but a sum this large is still out of range (audit NAT-1's "finite but huge" case).
+            _ = try RemoteHLSSubtitleProxy.sumSegmentDurations([Self.seg(5e18), Self.seg(5e18)])
+        }
+    }
+
+    @Test("An ordinary EXTINF sum is unaffected")
+    func sumsOrdinaryDurations() throws {
+        let total = try RemoteHLSSubtitleProxy.sumSegmentDurations([Self.seg(5), Self.seg(6.5)])
+        #expect(total == 11.5)
+    }
+
+    @Test("A non-finite or absurd program duration is clamped before it reaches the provider's segment")
+    func providerClampsAHostileProgramDuration() {
+        let providerInf = RemoteHLSSubtitleProvider(
+            tracks: [], masterBody: Self.master, programDuration: .infinity, defaultHeaders: [:])
+        #expect(providerInf.segmentDuration(at: 0).isFinite)
+
+        let providerHuge = RemoteHLSSubtitleProvider(
+            tracks: [], masterBody: Self.master, programDuration: 5e18, defaultHeaders: [:])
+        #expect(providerHuge.segmentDuration(at: 0) <= RemoteHLSSubtitleProxy.maxProgramDurationSeconds)
+
+        let providerNaN = RemoteHLSSubtitleProvider(
+            tracks: [], masterBody: Self.master, programDuration: .nan, defaultHeaders: [:])
+        #expect(providerNaN.segmentDuration(at: 0) == 1)
+    }
+
     @Test("Without an m3u8/NAME the display name is still the key")
     func injectionKeyFallsBackToDisplayName() {
         let bare = RemoteHLSMediaSelection.LegibleOption(

From 0648c9778b07aacfbb7437fb9022085bf6bdeccd Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 06:10:54 +0200
Subject: [PATCH 080/359] fix(subtitles): strip ASS override blocks in one pass
 (audit SUB-1)

MovTextSampleBuilder.sanitize removed each {...} block in place, shifting
the rest of the cue per block. A remote cue built from many small blocks
(karaoke tracks emit one per syllable) made that quadratic on the thread
serving the WebVTT rendition: 200k blocks took 525 s. It now copies the
text between blocks in one forward pass (0.15 s), with the same result for
an unclosed brace.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 .../Subtitles/MovTextSampleBuilder.swift       | 18 +++++++++++++++---
 .../MovTextSampleBuilderTests.swift            | 15 +++++++++++++++
 2 files changed, 30 insertions(+), 3 deletions(-)

diff --git a/Sources/AetherEngine/Subtitles/MovTextSampleBuilder.swift b/Sources/AetherEngine/Subtitles/MovTextSampleBuilder.swift
index 0b1000c7b..c5fb03a8e 100644
--- a/Sources/AetherEngine/Subtitles/MovTextSampleBuilder.swift
+++ b/Sources/AetherEngine/Subtitles/MovTextSampleBuilder.swift
@@ -5,10 +5,22 @@ import Foundation
 enum MovTextSampleBuilder {
 
     /// Strip ASS/SSA override blocks (`{\...}`) and normalize inline escapes to plain text.
+    ///
+    /// Audit SUB-1: one forward pass. Removing each block in place shifted the whole remaining cue
+    /// per block, quadratic on a remote cue made of many small blocks (karaoke tracks emit one per
+    /// syllable). An unclosed `{` keeps itself and everything after it, as before.
     static func sanitize(_ assText: String) -> String {
-        var s = assText
-        while let open = s.firstIndex(of: "{"), let close = s[open...].firstIndex(of: "}") {
-            s.removeSubrange(open...close)
+        var s = ""
+        s.reserveCapacity(assText.utf8.count)
+        var cursor = assText.startIndex
+        while cursor < assText.endIndex {
+            guard let open = assText[cursor...].firstIndex(of: "{"),
+                  let close = assText[open...].firstIndex(of: "}") else {
+                s += assText[cursor...]
+                break
+            }
+            s += assText[cursor..<open]
+            cursor = assText.index(after: close)
         }
         s = s.replacingOccurrences(of: "\\N", with: "\n")
         s = s.replacingOccurrences(of: "\\n", with: "\n")
diff --git a/Tests/AetherEngineTests/MovTextSampleBuilderTests.swift b/Tests/AetherEngineTests/MovTextSampleBuilderTests.swift
index f354ac26f..6312282c1 100644
--- a/Tests/AetherEngineTests/MovTextSampleBuilderTests.swift
+++ b/Tests/AetherEngineTests/MovTextSampleBuilderTests.swift
@@ -17,4 +17,19 @@ final class MovTextSampleBuilderTests: XCTestCase {
     func test_sanitize_trimsSurroundingWhitespace() {
         XCTAssertEqual(MovTextSampleBuilder.sanitize("  hello  "), "hello")
     }
+
+    func test_sanitize_keepsAnUnclosedBraceAndWhatFollows() {
+        XCTAssertEqual(MovTextSampleBuilder.sanitize("{\\b1}bold{unclosed tail"), "bold{unclosed tail")
+        XCTAssertEqual(MovTextSampleBuilder.sanitize("{a{b}c}"), "c}")
+    }
+
+    /// Audit SUB-1: stripping this cue block by block took 525 s on an M-series Mac; one pass, 0.15 s.
+    func test_sanitize_isLinearOnAHostileCueOfManySmallBlocks() {
+        let hostile = String(repeating: "{\\1c&H00FF00&}x", count: 200_000)
+        let started = Date()
+        let clean = MovTextSampleBuilder.sanitize(hostile)
+        XCTAssertEqual(clean.count, 200_000)
+        XCTAssertTrue(clean.allSatisfy { $0 == "x" })
+        XCTAssertLessThan(Date().timeIntervalSince(started), 2.0)
+    }
 }

From 154f68c858fe0431c7e7f1dece00177a1a5415ea Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 06:12:18 +0200
Subject: [PATCH 081/359] docs(changelog): audit parser and disc image fixes

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 CHANGELOG.md | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index a91909768..1500acd2e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -34,9 +34,20 @@ the public-API contract.
   instead of trapping (audit SEG-1).
 - **The Dolby Vision profile check can no longer read a whole file while playback is starting.** It
   stops after a fixed number of packets from any stream, or 64 MiB (audit BIT-2).
+- **Hostile playlists and disc images no longer crash the app.** An `EXT-X-MEDIA-SEQUENCE` near
+  `Int.max`, a crafted UDF partition map or descriptor sequence, a 4 GB ISO9660 directory length and a
+  `#EXTINF:inf` behind an injected subtitle sidecar all trapped; each is now rejected or bounded at
+  parse, and the sidecar playlist fetch is size-capped (audit NET-3, NET-4, NET-5, NET-11, NAT-1,
+  NAT-5).
 
 ### Fixed
 
+- **CRLF-terminated HLS playlists parse.** In Swift `"\r\n"` is one Character, so splitting on `"\n"`
+  read the whole playlist as one line and rejected it on the live/VOD ingest, the audio tap and the
+  subtitle proxy (audit NET-2).
+- **A remote disc image only accepts a 206 that starts at the requested offset**, instead of placing
+  wrong bytes or buffering a whole-file 200. The UDF descriptor scan also stops at its Terminating
+  Descriptor again (audit NET-9, NET-11).
 - **Closing the player during a scrub restart no longer spins segment requests at full CPU**
   (audit SEG-3).
 - **A re-cut segment can no longer be dropped by a request that is reading it at the same moment**,
@@ -102,6 +113,7 @@ the public-API contract.
 
 - **Faster first segment after a seek on TrueHD sources, and less CPU for HDR10+ detection on sources
   without HDR10+** (audit SEG-6, BIT-4).
+- **The live ingest FIFO no longer re-copies its whole buffer on every read** (audit NET-8).
 
 ## [7.16.1] - 2026-09-24
 

From 6bdc7390d5c04fb830c30a18bcda34c0ae81fa88 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 06:14:07 +0200
Subject: [PATCH 082/359] fix(recording): stopping a recording no longer drains
 its backlog on the main actor (audit REC-1)

LiveRecordingQueue took its backlog one removeFirst() at a time, quadratic
on the tens of thousands of small packets the 16 MiB ceiling admits, and
finish() ran that drain on the caller, which for stopRecording and a
session reset was the main actor. The pump now swaps the backlog out a
batch at a time (bytes still leave the ceiling one write at a time), and
finish() drains on the writer queue.

endRecordingIfRunning hands the writer's drain and trailer to a detached
task and publishes .ended once it is done, since .ended promises a closed
file. stopRecording awaits it, startRecording waits for it before opening
a new file (the path can be the same), and a recording started in the
meantime keeps its state.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 .../AetherEngine/AetherEngine+Recording.swift | 18 +++++++++++--
 Sources/AetherEngine/AetherEngine.swift       |  3 +++
 .../Recording/LiveRecordingQueue.swift        | 23 ++++++++++------
 .../LiveRecordingAPITests.swift               | 27 +++++++++++++++++++
 .../LiveRecordingQueueTests.swift             | 24 +++++++++++++++++
 docs/api.md                                   |  4 +++
 6 files changed, 89 insertions(+), 10 deletions(-)

diff --git a/Sources/AetherEngine/AetherEngine+Recording.swift b/Sources/AetherEngine/AetherEngine+Recording.swift
index 1db408d80..0d7734eb0 100644
--- a/Sources/AetherEngine/AetherEngine+Recording.swift
+++ b/Sources/AetherEngine/AetherEngine+Recording.swift
@@ -22,6 +22,8 @@ public extension AetherEngine {
     /// or a path that cannot be created. Anything that can only be discovered while writing arrives
     /// through `$recordingState` as `.failed`, never through both.
     func startRecording(to url: URL) async throws {
+        // The previous file is still being finalized off the main actor; it may be this path.
+        await recordingFinish?.value
         if case .recording(let progress) = recordingState {
             throw RecordingFailure.alreadyRecording(progress.url)
         }
@@ -62,6 +64,7 @@ public extension AetherEngine {
     /// Ends the recording and closes the file. Idempotent, and a no-op when nothing is recording.
     func stopRecording() async {
         endRecordingIfRunning(reason: .stoppedByHost)
+        await recordingFinish?.value
     }
 }
 
@@ -95,14 +98,25 @@ extension AetherEngine {
     }
 
     /// Ends a running recording, if any, for a reason that is not a failure. Idempotent.
+    ///
+    /// Audit REC-1: the writer drains up to the queue ceiling to disk and writes the trailer, which
+    /// used to run right here on the main actor. It runs detached now, and `.ended` is published
+    /// once it is done, because `.ended` promises a closed, playable file. A recording started in
+    /// the meantime owns the state, so the late `.ended` of this one is dropped.
     func endRecordingIfRunning(reason: RecordingEndReason) {
         guard let writer = activeRecording else { return }
         (activeRecordingHost as? LiveRecordingHost)?.setRecordingSink(nil)
         activeRecordingHost = nil
         activeRecording = nil
         stopRecordingProgressTimer()
-        writer.finish(reason: reason)
-        recordingState = .ended(reason)
+        let generation = recordingGeneration
+        let previous = recordingFinish
+        recordingFinish = Task { [weak self] in
+            await previous?.value
+            await Task.detached(priority: .utility) { writer.finish(reason: reason) }.value
+            guard let self, self.recordingGeneration == generation else { return }
+            self.recordingState = .ended(reason)
+        }
     }
 
     /// The writer's failure callback, bound to the recording it is built for. The writer reports
diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index 0f57f358d..2c9f63d9b 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -1323,6 +1323,9 @@ public final class AetherEngine: ObservableObject {
     /// Which recording a writer failure belongs to (audit CORE-5). Bumped once per writer.
     var recordingGeneration: UInt64 = 0
 
+    /// The ended recording's drain and trailer, run off the main actor (audit REC-1).
+    var recordingFinish: Task<Void, Never>?
+
     /// Republishes `recordingState` progress at 1 Hz while a recording runs.
     var recordingProgressTimer: Timer?
 
diff --git a/Sources/AetherEngine/Recording/LiveRecordingQueue.swift b/Sources/AetherEngine/Recording/LiveRecordingQueue.swift
index 655093ee7..efb635ddb 100644
--- a/Sources/AetherEngine/Recording/LiveRecordingQueue.swift
+++ b/Sources/AetherEngine/Recording/LiveRecordingQueue.swift
@@ -62,17 +62,19 @@ final class LiveRecordingQueue: @unchecked Sendable {
     }
 
     /// Drains what is queued and stops accepting. Blocks the CALLER, never the demux thread: only
-    /// `stopRecording` and teardown call it.
+    /// the writer's teardown calls it, and never from the main actor.
     func finish() {
         lock.lock()
         finished = true
         lock.unlock()
-        // Let an in-flight pump finish, then drain whatever it left behind, then let that finish.
-        queue.sync { }
-        pump()
-        queue.sync { }
+        // The queue is serial, so an in-flight pump finishes first and this one drains what it left.
+        queue.sync { pump() }
     }
 
+    /// Audit REC-1: takes the backlog a batch at a time. `removeFirst()` per item shifted the whole
+    /// array each time, quadratic on the tens of thousands of small packets the ceiling admits. The
+    /// bytes still leave `pendingBytes` one write at a time, so the ceiling keeps counting a batch
+    /// that is taken but not yet on disk.
     private func pump() {
         while true {
             lock.lock()
@@ -81,10 +83,15 @@ final class LiveRecordingQueue: @unchecked Sendable {
                 lock.unlock()
                 return
             }
-            let item = pending.removeFirst()
-            pendingBytes -= item.bytes.count
+            var batch: [QueuedPacket] = []
+            swap(&batch, &pending)
             lock.unlock()
-            drain(item)
+            for item in batch {
+                drain(item)
+                lock.lock()
+                pendingBytes -= item.bytes.count
+                lock.unlock()
+            }
         }
     }
 }
diff --git a/Tests/AetherEngineTests/LiveRecordingAPITests.swift b/Tests/AetherEngineTests/LiveRecordingAPITests.swift
index 985a9de83..b945e2847 100644
--- a/Tests/AetherEngineTests/LiveRecordingAPITests.swift
+++ b/Tests/AetherEngineTests/LiveRecordingAPITests.swift
@@ -63,6 +63,8 @@ struct LiveRecordingAPITests {
         #expect(host.installedSink != nil)
 
         engine.endRecordingIfRunning(reason: .sourceReset)
+        #expect(host.installedSink == nil, "the sink comes off the route at once, before the drain")
+        await engine.recordingFinish?.value
         #expect(engine.recordingState == .ended(.sourceReset))
         #expect(host.installedSink == nil, "the sink must be removed from the route")
     }
@@ -77,6 +79,7 @@ struct LiveRecordingAPITests {
         try engine._testStartRecordingWithStubHost(to: url, host: host)
         engine.endRecordingIfRunning(reason: .stoppedByHost)
         engine.endRecordingIfRunning(reason: .sessionEnded)
+        await engine.recordingFinish?.value
         #expect(engine.recordingState == .ended(.stoppedByHost))
     }
 
@@ -137,4 +140,28 @@ struct LiveRecordingAPITests {
         #expect(engine.recordingState == .failed(.writeTooSlow(bytesWritten: 1, queuedBytesDropped: 1)))
         running?.finish(reason: .sessionEnded)
     }
+
+    /// Audit REC-1: the drain and the trailer run off the main actor, and `.ended` still means the
+    /// file is closed. A recording started in the meantime keeps the state; the late `.ended` of
+    /// the one before it must not overwrite `.recording`.
+    @Test("a stop followed at once by a new recording leaves the new one's state standing")
+    func lateEndedDoesNotOverwriteTheNextRecording() async throws {
+        let engine = try AetherEngine()
+        let host = AetherEngine.TestRecordingHost()
+        let first = tempURL()
+        let second = tempURL()
+        defer {
+            try? FileManager.default.removeItem(at: first)
+            try? FileManager.default.removeItem(at: second)
+        }
+
+        try engine._testStartRecordingWithStubHost(to: first, host: host)
+        engine.endRecordingIfRunning(reason: .sourceReset)
+        try engine._testStartRecordingWithStubHost(to: second, host: host)
+        await engine.recordingFinish?.value
+        #expect({ if case .recording(let p) = engine.recordingState { return p.url == second }; return false }())
+        await engine.stopRecording()
+        #expect(engine.recordingState == .ended(.stoppedByHost))
+        #expect(engine.activeRecording == nil)
+    }
 }
diff --git a/Tests/AetherEngineTests/LiveRecordingQueueTests.swift b/Tests/AetherEngineTests/LiveRecordingQueueTests.swift
index a11d994b7..6bc637ed9 100644
--- a/Tests/AetherEngineTests/LiveRecordingQueueTests.swift
+++ b/Tests/AetherEngineTests/LiveRecordingQueueTests.swift
@@ -98,4 +98,28 @@ struct LiveRecordingQueueTests {
         q.finish()
         #expect(q.offer(packet(64)) == false)
     }
+
+    /// Audit REC-1: `finish` used to drain what was left on the calling thread, which for a stop was
+    /// the main actor, one `removeFirst()` per packet.
+    @Test("finish drains a large backlog in order on the writer queue, not the caller's thread")
+    func finishDrainsBacklogOnTheWriterQueue() {
+        let gate = Latch()
+        let seen = Locked<[Int64]>([])
+        let offQueue = Locked(0)
+        let q = LiveRecordingQueue(ceilingBytes: 1 << 24) { item in
+            gate.wait()
+            let label = String(cString: __dispatch_queue_get_label(nil))
+            if label != "de.superuser404.aether.recording.write" { offQueue.withLock { $0 += 1 } }
+            seen.withLock { $0.append(item.pts) }
+        }
+        let count = 100_000
+        for i in 0..<count { _ = q.offer(packet(16, pts: Int64(i))) }
+        gate.open()
+        let start = DispatchTime.now()
+        q.finish()
+        let elapsed = Double(DispatchTime.now().uptimeNanoseconds - start.uptimeNanoseconds) / 1e9
+        #expect(seen.withLock { $0 } == (0..<count).map(Int64.init))
+        #expect(offQueue.withLock { $0 } == 0)
+        #expect(elapsed < 5, "draining \(count) packets took \(elapsed) s")
+    }
 }
diff --git a/docs/api.md b/docs/api.md
index 76d815ab4..a2e319952 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -814,6 +814,10 @@ declared from the old source produces a file that is unplayable or silently wron
 host has the event and starts part two if it wants one. `stop()` and a new `load()` end it the same
 way with `.ended(.sessionEnded)`; a recording never outlives its session.
 
+`.ended` is published once the file is closed. The queued tail and the trailer are written off the
+main actor, so it can arrive a moment after the call that ended the recording; `stopRecording()`
+returns only after it, and a `startRecording(to:)` issued in that moment waits for it first.
+
 **Not implemented: recording from the start of what is already buffered.** A recording begins at the
 call, not at the back of the DVR window. On `.loopback` what is retained is remuxed fMP4 with
 **bridged** audio, not source packets, so prepending it would produce one file whose audio codec

From 174c9e72040a68d0295e3b388dc944a6cf4cbe40 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 06:14:22 +0200
Subject: [PATCH 083/359] docs(security): state the supported line as the
 latest release, not a version that rots (audit OPS-1)

The table still named 2.1.x as the only supported line on 7.16.1, which
contradicted the prose above it. It now points at the latest release's
minor line, the policy the prose already states.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 SECURITY.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/SECURITY.md b/SECURITY.md
index 11453089d..0b4e7041e 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -4,10 +4,10 @@
 
 AetherEngine ships fixes on the latest released minor line. Security fixes land there first; older lines are not back-patched. Host apps pin the engine by commit SHA, so picking up a fix means bumping the pin to the patched release.
 
-| Version | Supported          |
-| ------- | ------------------ |
-| 2.1.x   | :white_check_mark: |
-| < 2.1   | :x:                |
+| Version | Supported |
+| ------- | --------- |
+| The minor line of the [latest release](https://github.com/superuser404notfound/AetherEngine/releases/latest) | :white_check_mark: |
+| Every earlier minor line | :x: |
 
 ## Reporting a vulnerability
 

From 2afe3f2cebb4b4e8ea555916205f86a9fc363ccb Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 06:14:52 +0200
Subject: [PATCH 084/359] ci: pin third-party actions to commit SHAs and let
 Dependabot move them (audit OPS-2)

setup-xcode, github-issue-parser and create-pull-request were pinned by
mutable major tags; release-dmg.yml runs setup-xcode in the same job that
later imports the signing certificate and notarization credentials. Each is
now pinned to the commit its tag resolves to today (v1.7.0, v3.2.5, v6.1.0),
and a weekly github-actions Dependabot config opens PRs for new releases.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 .github/dependabot.yml            | 9 +++++++++
 .github/workflows/ci.yml          | 8 ++++----
 .github/workflows/release-dmg.yml | 2 +-
 .github/workflows/used-by-add.yml | 4 ++--
 4 files changed, 16 insertions(+), 7 deletions(-)
 create mode 100644 .github/dependabot.yml

diff --git a/.github/dependabot.yml b/.github/dependabot.yml
new file mode 100644
index 000000000..d457c480a
--- /dev/null
+++ b/.github/dependabot.yml
@@ -0,0 +1,9 @@
+version: 2
+updates:
+  # Third-party actions are pinned by commit SHA (audit OPS-2); this keeps the pins moving.
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    commit-message:
+      prefix: "chore(ci)"
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 6a554ddbc..ab77d7d2f 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -19,7 +19,7 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - uses: maxim-lobanov/setup-xcode@v1
+      - uses: maxim-lobanov/setup-xcode@ed7a3b1fda3918c0306d1b724322adc0b8cc0a90 # v1.7.0
         with:
           xcode-version: latest-stable
 
@@ -72,7 +72,7 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - uses: maxim-lobanov/setup-xcode@v1
+      - uses: maxim-lobanov/setup-xcode@ed7a3b1fda3918c0306d1b724322adc0b8cc0a90 # v1.7.0
         with:
           xcode-version: latest-stable
 
@@ -121,7 +121,7 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - uses: maxim-lobanov/setup-xcode@v1
+      - uses: maxim-lobanov/setup-xcode@ed7a3b1fda3918c0306d1b724322adc0b8cc0a90 # v1.7.0
         with:
           xcode-version: latest-stable
 
@@ -156,7 +156,7 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - uses: maxim-lobanov/setup-xcode@v1
+      - uses: maxim-lobanov/setup-xcode@ed7a3b1fda3918c0306d1b724322adc0b8cc0a90 # v1.7.0
         with:
           xcode-version: latest-stable
 
diff --git a/.github/workflows/release-dmg.yml b/.github/workflows/release-dmg.yml
index 9bec23dff..788e44a4e 100644
--- a/.github/workflows/release-dmg.yml
+++ b/.github/workflows/release-dmg.yml
@@ -51,7 +51,7 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - uses: maxim-lobanov/setup-xcode@v1
+      - uses: maxim-lobanov/setup-xcode@ed7a3b1fda3918c0306d1b724322adc0b8cc0a90 # v1.7.0
         with:
           xcode-version: latest-stable
 
diff --git a/.github/workflows/used-by-add.yml b/.github/workflows/used-by-add.yml
index 17eec145f..cee3d35a5 100644
--- a/.github/workflows/used-by-add.yml
+++ b/.github/workflows/used-by-add.yml
@@ -62,7 +62,7 @@ jobs:
 
       - name: Parse issue form
         id: parse
-        uses: stefanbuck/github-issue-parser@v3
+        uses: stefanbuck/github-issue-parser@cb6e97157cbf851e3a393ff8d57c93a484cc323f # v3.2.5
         with:
           template-path: .github/ISSUE_TEMPLATE/used-by-submission.yml
           issue-body: ${{ steps.normalise.outputs.body }}
@@ -151,7 +151,7 @@ jobs:
       - name: Open pull request
         if: steps.build.outputs.skip == 'false'
         id: pr
-        uses: peter-evans/create-pull-request@v6
+        uses: peter-evans/create-pull-request@c5a7806660adbe173f04e3e038b0ccdcd758773c # v6.1.0
         with:
           # Only the README, so no stray runner file can ride along.
           add-paths: README.md

From de6a5b723d785c6b5e35ec64a0b7973a96a709e4 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 06:16:02 +0200
Subject: [PATCH 085/359] fix(aetherctl): debug output goes to a private
 per-run directory, not fixed /tmp names (audit OPS-3)

dovitest, extract, the play --host-calls still drill and audiotap's default
--out wrote to fixed names in the shared /tmp, which another local user can
pre-create as a symlink. They now write into one mkdtemp directory (0700)
under the user's temporary directory, created on first use and printed
with each path; audiotap --out still takes an explicit path.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 Sources/aetherctl/DebugOutput.swift | 21 +++++++++++++++++++++
 Sources/aetherctl/DoviTest.swift    | 13 +++++++------
 Sources/aetherctl/Extract.swift     |  2 +-
 Sources/aetherctl/PlaybackCmd.swift |  2 +-
 Sources/aetherctl/main.swift        |  8 +++++---
 docs/cli.md                         | 10 +++++-----
 6 files changed, 40 insertions(+), 16 deletions(-)
 create mode 100644 Sources/aetherctl/DebugOutput.swift

diff --git a/Sources/aetherctl/DebugOutput.swift b/Sources/aetherctl/DebugOutput.swift
new file mode 100644
index 000000000..38fab53f7
--- /dev/null
+++ b/Sources/aetherctl/DebugOutput.swift
@@ -0,0 +1,21 @@
+import Foundation
+
+/// Audit OPS-3: debug artefacts go into one private directory per run (`mkdtemp`, mode 0700) under
+/// the user's temporary directory. A fixed name in the shared `/tmp` could be pre-created as a
+/// symlink by another local user, and the write would follow it.
+let debugOutputDirectory: String = {
+    let template = FileManager.default.temporaryDirectory.appendingPathComponent("aetherctl-XXXXXX").path
+    var buffer = Array(template.utf8CString)
+    if let made = mkdtemp(&buffer) {
+        return String(cString: made)
+    }
+    let fallback = FileManager.default.temporaryDirectory
+        .appendingPathComponent("aetherctl-\(UUID().uuidString)").path
+    try? FileManager.default.createDirectory(atPath: fallback, withIntermediateDirectories: false,
+                                             attributes: [.posixPermissions: 0o700])
+    return fallback
+}()
+
+func debugOutputPath(_ name: String) -> String {
+    (debugOutputDirectory as NSString).appendingPathComponent(name)
+}
diff --git a/Sources/aetherctl/DoviTest.swift b/Sources/aetherctl/DoviTest.swift
index afded3c42..6b9902e44 100644
--- a/Sources/aetherctl/DoviTest.swift
+++ b/Sources/aetherctl/DoviTest.swift
@@ -3,9 +3,10 @@ import AetherEngine
 
 // MARK: - dovitest
 
-/// Validate DoviRpuConverter.convertPacketToProfile81 against dovi_tool ground truth. Walks the HEVC stream, converts DV P7 -> P8.1, writes Annex-B to /tmp/aetherctl-dovitest.hevc.
+/// Validate DoviRpuConverter.convertPacketToProfile81 against dovi_tool ground truth. Walks the HEVC stream, converts DV P7 -> P8.1, writes Annex-B to aetherctl-dovitest.hevc in the run's private temporary directory.
 func runDoviTest(url: URL) -> Int32 {
-    let outputPath = "/tmp/aetherctl-dovitest.hevc"
+    let outputPath = debugOutputPath("aetherctl-dovitest.hevc")
+    let rpuPath = debugOutputPath("host.rpu")
     print("aetherctl dovitest: \(url.absoluteString)")
     print("output: \(outputPath)")
     print("")
@@ -35,14 +36,14 @@ func runDoviTest(url: URL) -> Int32 {
     if result.failures > 0 {
         print("VERDICT: dovitest had \(result.failures) converter failure(s).")
         print("         Validate the surviving RPUs against dovi_tool, then debug:")
-        print("           dovi_tool extract-rpu -i \(outputPath) -o /tmp/host.rpu")
-        print("           dovi_tool info -i /tmp/host.rpu -f 0")
+        print("           dovi_tool extract-rpu -i \(outputPath) -o \(rpuPath)")
+        print("           dovi_tool info -i \(rpuPath) -f 0")
         return 3
     }
 
     print("VERDICT: converted \(result.conversions) packet(s) to Profile 8.1.")
     print("         Validate against dovi_tool ground truth:")
-    print("           dovi_tool extract-rpu -i \(outputPath) -o /tmp/host.rpu")
-    print("           dovi_tool info -i /tmp/host.rpu -f 0 | grep -iE 'dovi_profile|disable_residual|rpu_data_crc32'")
+    print("           dovi_tool extract-rpu -i \(outputPath) -o \(rpuPath)")
+    print("           dovi_tool info -i \(rpuPath) -f 0 | grep -iE 'dovi_profile|disable_residual|rpu_data_crc32'")
     return 0
 }
diff --git a/Sources/aetherctl/Extract.swift b/Sources/aetherctl/Extract.swift
index ff36b4f58..4fb9dc163 100644
--- a/Sources/aetherctl/Extract.swift
+++ b/Sources/aetherctl/Extract.swift
@@ -49,7 +49,7 @@ func runExtract(url: URL, at seconds: Double, mode: FrameMode, loops: Int, maxWi
         if let image {
             produced += 1
             if i == 0 {
-                let out = "/tmp/aetherctl-extract-\(mode).png"
+                let out = debugOutputPath("aetherctl-extract-\(mode).png")
                 if writePNG(image, to: out) {
                     print("Wrote \(image.width)x\(image.height) -> \(out)")
                 } else {
diff --git a/Sources/aetherctl/PlaybackCmd.swift b/Sources/aetherctl/PlaybackCmd.swift
index a834ca465..df88a06e9 100644
--- a/Sources/aetherctl/PlaybackCmd.swift
+++ b/Sources/aetherctl/PlaybackCmd.swift
@@ -1030,7 +1030,7 @@ private func playSmokeTest(url: URL, seconds: Double, live: Bool, forceSoftware:
             stillAttempts += 1
             if let image {
                 stillHits += 1
-                let path = "/tmp/aetherctl-still-\(tick).png"
+                let path = debugOutputPath("aetherctl-still-\(tick).png")
                 let written = writeStillPNG(image, to: path)
                 print(String(format: "  HOSTCALL still(at: %.2f, %@) -> %dx%d in %d ms  %@",
                              target, label, image.width, image.height, ms,
diff --git a/Sources/aetherctl/main.swift b/Sources/aetherctl/main.swift
index c29df3079..01af9dd09 100644
--- a/Sources/aetherctl/main.swift
+++ b/Sources/aetherctl/main.swift
@@ -234,7 +234,8 @@ func printUsage() {
                 packet's Dolby Vision RPU from Profile 7 to Profile
                 8.1 (and drop the enhancement layer) via
                 DoviRpuConverter, and write the result to
-                /tmp/aetherctl-dovitest.hevc in Annex-B form. Feed
+                aetherctl-dovitest.hevc (Annex-B) in a private
+                per-run temporary directory, printed. Feed
                 that to `dovi_tool extract-rpu` + `info` to validate
                 the rewritten RPU against ground truth.
 
@@ -257,7 +258,8 @@ func printUsage() {
                 to --width. Snapshot mode (--snapshot) decodes
                 frame-accurately at full resolution. Use --loops N
                 with `leaks --atExit` to detect memory leaks.
-                Writes the first frame to /tmp/aetherctl-extract-<mode>.png.
+                Writes the first frame to aetherctl-extract-<mode>.png
+                in a private per-run temporary directory, printed.
 
       audio     Load a source through the engine's audio-only path
                 (LoadOptions.audioOnly=true), play for ~10 seconds,
@@ -471,7 +473,7 @@ if first == "pktdump" {
 if first == "audiotap" {
     var rest = Array(args.dropFirst(2))
     let duration = takeDoubleFlag("--duration", from: &rest) ?? 30
-    let outPath = takeStringFlag("--out", from: &rest) ?? "/tmp/audiotap.wav"
+    let outPath = takeStringFlag("--out", from: &rest) ?? debugOutputPath("audiotap.wav")
     let remote = rest.contains("--remote")
     rest.removeAll { $0 == "--remote" }
     let software = rest.contains("--software")
diff --git a/docs/cli.md b/docs/cli.md
index 361220b28..767210a4f 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -140,7 +140,7 @@ the same clock as `FIRSTFRAME`. The 1 Hz tick samples the phase, which is far to
 signal apart from the moment the rate rolls; a healthy native join is exactly two edges, `loading` at the
 load and `playing` at the roll (AE#440).
 
-`--subs <codec-or-lang>` matches against the track's libavcodec name or language and logs every overlay cue and cue trim as it lands. `--host-calls` replays host post-load behavior against the fresh session: `play`, `extractor` (`makeFrameExtractor`), `setrate` (`setRate(1.0)`), `pausestart` (Sodalite#104 round 4: `pause()` the instant load returns, before any frame exists, and `play()` at t=8; the shape of a host that holds a fresh load paused, and a software session used to answer it with eight ticks of `enq=+0 status=unknown r4d=n`, a black picture under a paused clock; now the `[SWHost] #104` lines show the first frame presented at a stopped clock and `startup 8/8 presenting` arrives while paused), `ratehold` (set 1.5, pause at tick 3, resume at tick 5, then read the rate back off the transport itself: the #436 drill, and it fails the run if the resume came back at 1.0), `reloadlive` (reload the URL on the live path when the probe flags it live, the AetherPlayer Open URL flow), `seekback` (rewind 20 s into the DVR window at t=15, return to the live edge at t=30), `overlapseek` (the #292 seek-window drills below), `pausehold` (Sodalite#104: pause at t=10 and HOLD until ten seconds before the end, printing the playhead, the edge and the resident depth every second, which is how a session paused for longer than its own DVR window is measured without waiting out a real one: pair it with `--dvr-window 30` and `--seconds 90` and the ninety minute question becomes a ninety second run), `still` (#544: asks for a scrub still at three aims, 20 s behind the playhead at t=15, 5 s behind at t=20 and at the edge at t=25, writing each to `/tmp/aetherctl-still-<tick>.png` and reporting hit or MISS with the decode time; pair it with `--sw --dvr-window N`, where the picture comes out of the DVR packet ring rather than a segment cache, and read the FILE as well as the count, because the bundled seed burns its own second into the frame so a still asked for 14.85 s showing `14` is the verdict that it decoded the right moment and not merely an image; exit 6 when nothing hit, 5 when the session ended before the first aim; on a VOD session (AE#605) the three aims are 10.5 s behind the playhead, 4.5 s ahead of it and 600 s past it, through `scrubThumbnail`, and the third is EXPECTED to miss, because a frame the cache does not hold yet must not be answered with the one before it: `--sw` against an HTTP source is the software packet-cache case, and the testsrc fixture's counter in the PNG is the verdict that the still decoded to the target rather than snapping to its keyframe), `stallclock` (AE#549: stop the master clock at t=4 behind the host's back, the way an interrupted audio session does, then call a plain `play()` at t=7 and read whether the playhead moves again; the interruption itself cannot be staged on macOS, its outcome can, and without the `RendererClockResume` branch the run ends with the clock standing exactly where the stall left it, which is the field log's shape; the drill drives DEBUG-only engine hooks, so a Release `aetherctl` prints a notice and ends inconclusive, build it with `swift build --product aetherctl`), `pausereload`, `playreload` and `extplayreload` (#623: force the #93/#65 stage-2 item reload at t=10, on a session paused at t=6, on one left playing, and on one paused through the engine at t=6 and resumed at t=8 straight on the `AVPlayer` the way AVKit's transport does, which leaves the engine's intent reading paused while the player runs; the run fails with exit 4 if the clock moves after the paused reload or stands still after either playing one, and before #623 `pausereload` ended `+7.20 s, state=playing`), and `pauseseek` (pause at t=12, seek at t=15 while paused, resume at t=20; with `--sw` the five paused ticks between landing and resume show what the `[SWDiag]` line reports while the pump is parked and has not heard of the seek, the AE#479 shape); this is how the pre-arming `setRate` wedge was isolated.
+`--subs <codec-or-lang>` matches against the track's libavcodec name or language and logs every overlay cue and cue trim as it lands. `--host-calls` replays host post-load behavior against the fresh session: `play`, `extractor` (`makeFrameExtractor`), `setrate` (`setRate(1.0)`), `pausestart` (Sodalite#104 round 4: `pause()` the instant load returns, before any frame exists, and `play()` at t=8; the shape of a host that holds a fresh load paused, and a software session used to answer it with eight ticks of `enq=+0 status=unknown r4d=n`, a black picture under a paused clock; now the `[SWHost] #104` lines show the first frame presented at a stopped clock and `startup 8/8 presenting` arrives while paused), `ratehold` (set 1.5, pause at tick 3, resume at tick 5, then read the rate back off the transport itself: the #436 drill, and it fails the run if the resume came back at 1.0), `reloadlive` (reload the URL on the live path when the probe flags it live, the AetherPlayer Open URL flow), `seekback` (rewind 20 s into the DVR window at t=15, return to the live edge at t=30), `overlapseek` (the #292 seek-window drills below), `pausehold` (Sodalite#104: pause at t=10 and HOLD until ten seconds before the end, printing the playhead, the edge and the resident depth every second, which is how a session paused for longer than its own DVR window is measured without waiting out a real one: pair it with `--dvr-window 30` and `--seconds 90` and the ninety minute question becomes a ninety second run), `still` (#544: asks for a scrub still at three aims, 20 s behind the playhead at t=15, 5 s behind at t=20 and at the edge at t=25, writing each to `aetherctl-still-<tick>.png` in the run's private temporary directory (the path is printed) and reporting hit or MISS with the decode time; pair it with `--sw --dvr-window N`, where the picture comes out of the DVR packet ring rather than a segment cache, and read the FILE as well as the count, because the bundled seed burns its own second into the frame so a still asked for 14.85 s showing `14` is the verdict that it decoded the right moment and not merely an image; exit 6 when nothing hit, 5 when the session ended before the first aim; on a VOD session (AE#605) the three aims are 10.5 s behind the playhead, 4.5 s ahead of it and 600 s past it, through `scrubThumbnail`, and the third is EXPECTED to miss, because a frame the cache does not hold yet must not be answered with the one before it: `--sw` against an HTTP source is the software packet-cache case, and the testsrc fixture's counter in the PNG is the verdict that the still decoded to the target rather than snapping to its keyframe), `stallclock` (AE#549: stop the master clock at t=4 behind the host's back, the way an interrupted audio session does, then call a plain `play()` at t=7 and read whether the playhead moves again; the interruption itself cannot be staged on macOS, its outcome can, and without the `RendererClockResume` branch the run ends with the clock standing exactly where the stall left it, which is the field log's shape; the drill drives DEBUG-only engine hooks, so a Release `aetherctl` prints a notice and ends inconclusive, build it with `swift build --product aetherctl`), `pausereload`, `playreload` and `extplayreload` (#623: force the #93/#65 stage-2 item reload at t=10, on a session paused at t=6, on one left playing, and on one paused through the engine at t=6 and resumed at t=8 straight on the `AVPlayer` the way AVKit's transport does, which leaves the engine's intent reading paused while the player runs; the run fails with exit 4 if the clock moves after the paused reload or stands still after either playing one, and before #623 `pausereload` ended `+7.20 s, state=playing`), and `pauseseek` (pause at t=12, seek at t=15 while paused, resume at t=20; with `--sw` the five paused ticks between landing and resume show what the `[SWDiag]` line reports while the pump is parked and has not heard of the seek, the AE#479 shape); this is how the pre-arming `setRate` wedge was isolated.
 
 `--seek-every N` seeks once every N ticks past tick 10, walking `--seek-pattern <abs,abs,...>` if one is given (a short backward hop otherwise), and `--seek-count K` stops after K seeks so a run can be a BURST and then play. Both halves are needed for anything about what a seek sequence leaves behind: the burst puts the store in the state under test, and only the playing half shows what the overlay carries through it. That pairing is what made AE#362's second mechanism reproducible (a hole between a restarted pump and the island the previous run left ahead of it, decoded across and then never re-read).
 
@@ -428,11 +428,11 @@ A healthy run prints `contiguous` on every line. AE#561 is the counter-example i
 
 ## dovitest
 
-Runs the Dolby Vision Profile 7 to 8.1 converter over every video packet of the source and writes the converted elementary stream (Annex B) to `/tmp/aetherctl-dovitest.hevc`, reporting packets processed, conversions, and failures. Lets you confirm the in-engine `DoviRpuConverter` (libdovi) output matches the `dovi_tool -m 2` ground truth offline, without a DV panel:
+Runs the Dolby Vision Profile 7 to 8.1 converter over every video packet of the source and writes the converted elementary stream (Annex B) to `aetherctl-dovitest.hevc` in the run's private temporary directory (the path is printed), reporting packets processed, conversions, and failures. Lets you confirm the in-engine `DoviRpuConverter` (libdovi) output matches the `dovi_tool -m 2` ground truth offline, without a DV panel:
 
 ```bash
 swift run aetherctl dovitest <p7-source>
-dovi_tool extract-rpu -i /tmp/aetherctl-dovitest.hevc -o out.rpu
+dovi_tool extract-rpu -i <printed output path> -o out.rpu
 dovi_tool info -i out.rpu -f 0   # expect dovi_profile 8, disable_residual_flag true
 ```
 
@@ -452,7 +452,7 @@ The profile differential is the diagnostic: a `video_delay=0` plus NOPTS or non-
 
 ## extract
 
-Opens a `FrameExtractor` against the source and pulls a still frame. Thumbnail mode (default) snaps to the nearest keyframe and downscales to `--width` (default 320); `--snapshot` decodes frame-accurately at full resolution. `--at <sec>` sets the seek position (default 60.0). The first frame is written to `/tmp/aetherctl-extract-<mode>.png`. `--loops N` repeats the extraction across eight cycling positions, which pairs with `leaks --atExit` to validate the decode-context teardown is clean:
+Opens a `FrameExtractor` against the source and pulls a still frame. Thumbnail mode (default) snaps to the nearest keyframe and downscales to `--width` (default 320); `--snapshot` decodes frame-accurately at full resolution. `--at <sec>` sets the seek position (default 60.0). The first frame is written to `aetherctl-extract-<mode>.png` in the run's private temporary directory (the path is printed). `--loops N` repeats the extraction across eight cycling positions, which pairs with `leaks --atExit` to validate the decode-context teardown is clean:
 
 ```bash
 swift run aetherctl extract --at 612 --snapshot <url>          # frame-accurate still
@@ -468,7 +468,7 @@ Plays a source through the audio-only pipeline (default ten seconds, `--seconds
 
     aetherctl audiotap [--duration S] [--out PATH.wav] [--remote | --software] <url>
 
-Brings up the loopback session headless, decodes the audio tap (#95) as fast as segments are produced, writes mono Float32 48 kHz WAV (default `/tmp/audiotap.wav`), and prints buffer count, PCM seconds, discontinuity count, and the covered `sourceTime` span. A clean run reports exactly one discontinuity (the install itself). `--remote` drives the remote-HLS delivery path instead (direct AVPlayer ingest of an HLS url, no loopback): rendition/variant resolution, segment fetch + decrypt, playhead-follow decode. Verification tool for the PCM audio tap across the stream-copy and bridge audio paths.
+Brings up the loopback session headless, decodes the audio tap (#95) as fast as segments are produced, writes mono Float32 48 kHz WAV (default `audiotap.wav` in the run's private temporary directory; `--out` sets the path), and prints buffer count, PCM seconds, discontinuity count, and the covered `sourceTime` span. A clean run reports exactly one discontinuity (the install itself). `--remote` drives the remote-HLS delivery path instead (direct AVPlayer ingest of an HLS url, no loopback): rendition/variant resolution, segment fetch + decrypt, playhead-follow decode. Verification tool for the PCM audio tap across the stream-copy and bridge audio paths.
 
 `--software` drives the third delivery path, the SW sink (`AudioTapPCMConverter`), which the other two modes cannot reach: they drive their readers directly, while the sink only exists inside a real session. This mode therefore loads the source through the whole engine, fails if it did not route to the software host, installs the tap through the public `installAudioTap()` and plays, so the sink runs exactly as it does in a host. It is bound to wall clock (the SW host decodes in real time), and it reports `peak` next to the buffer count because the two ways this path fails look identical in a report otherwise: **exit 3 covers both no buffers at all and buffers of digital silence**, which at a consumer is indistinguishable from a muted source. That gap is not hypothetical. With no harness here, a force unwrap that trapped on the FIRST buffer of any multichannel track shipped in 6.1.3 and survived to main (#400), and the silent-downmix defect underneath it only became visible once the trap was gone. Software routing needs a source the native path declines, e.g. `ffmpeg -f lavfi -i testsrc2 -f lavfi -i sine -c:v libvpx-vp9 -c:a aac -shortest clip.mkv`; add `-af "pan=5.1|c0=c0|c1=c0|c2=c0|c3=c0|c4=c0|c5=c0"` for the multichannel case and `-af "pan=quad|c0=c0|c1=c0|c2=c0|c3=c0"` for the layout AVAudioConverter refuses to mix.
 

From 780e9f87af7ddc0185a6a3ff791af8042c4a86de Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 06:18:53 +0200
Subject: [PATCH 086/359] fix(hdr10plus): bound the scan's source reads below
 the demuxer, where dropped streams are read

The scan sets AVDISCARD_ALL on every stream but video, and matroska and mov read and drop those
streams' blocks inside one av_read_frame. Its packet caps and the foreign-packet fuse never see
them, so a file with one video packet followed by gigabytes of another stream was read to its end.
The demuxer now has an input byte budget enforced at the byte source (the AVIO providers' read
callbacks, and the interrupt callback for a local URLContext input), and the scan arms it at four
times maxBytes, at least 4 MiB. A refused read reports byteCap.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 .../AetherEngine/Demuxer/AVIOProvider.swift   |  40 +++++
 Sources/AetherEngine/Demuxer/AVIOReader.swift |  13 +-
 .../Demuxer/CustomIOReaderBridge.swift        |   9 +-
 Sources/AetherEngine/Demuxer/Demuxer.swift    |  86 ++++++++--
 .../Video/HDR10PlusDetectionProbe.swift       |  23 ++-
 .../HDR10PlusScanInputBudgetTests.swift       | 149 ++++++++++++++++++
 docs/api.md                                   |   2 +-
 7 files changed, 306 insertions(+), 16 deletions(-)
 create mode 100644 Tests/AetherEngineTests/HDR10PlusScanInputBudgetTests.swift

diff --git a/Sources/AetherEngine/Demuxer/AVIOProvider.swift b/Sources/AetherEngine/Demuxer/AVIOProvider.swift
index f39cd8aa6..207c733bb 100644
--- a/Sources/AetherEngine/Demuxer/AVIOProvider.swift
+++ b/Sources/AetherEngine/Demuxer/AVIOProvider.swift
@@ -38,6 +38,18 @@ protocol AVIOProvider: AnyObject {
     /// seek fallback when a timestamp seek times out on an index-less container.
     var resolvedByteSize: Int64? { get }
 
+    /// Ceiling on the bytes this provider hands libavformat until `endReadByteBudget`, for a pass whose
+    /// packet caps cannot see what the demuxer reads and drops inside one `av_read_frame` (the blocks of
+    /// AVDISCARD_ALL streams). A read past it fails like a deadline abort. Demux-thread-only, same
+    /// contract as the read deadline.
+    func beginReadByteBudget(_ bytes: Int64)
+
+    /// Disarm the budget armed by `beginReadByteBudget`.
+    func endReadByteBudget()
+
+    /// True when a read was refused because the byte budget was spent.
+    var readByteBudgetExhausted: Bool { get }
+
     /// AE#460 follow-up: whether the byte source behind this provider outlives the provider, so a
     /// rebuild reopens onto a source that is already positioned. True only for the custom-reader
     /// bridge, which does not own its reader; a provider that opens its own transport per session
@@ -74,3 +86,31 @@ extension AVIOProvider {
     var currentSourceOffset: Int64? { nil }
     var sourceSurvivesReopen: Bool { false }
 }
+
+/// The shared bookkeeping behind `AVIOProvider.beginReadByteBudget`. Not thread-safe: it lives on the
+/// demux thread with the read callback that consults it.
+struct ReadByteBudget {
+    private var remaining: Int64?
+    private(set) var exhausted = false
+
+    mutating func begin(_ bytes: Int64) {
+        remaining = max(0, bytes)
+        exhausted = false
+    }
+
+    mutating func end() { remaining = nil }
+
+    /// The size a read may ask for, or nil (latching `exhausted`) once the budget is spent.
+    mutating func allowance(_ size: Int32) -> Int32? {
+        guard let remaining else { return size }
+        guard remaining > 0 else {
+            exhausted = true
+            return nil
+        }
+        return Int32(min(Int64(size), remaining))
+    }
+
+    mutating func consumed(_ count: Int32) {
+        if count > 0, let remaining { self.remaining = remaining - Int64(count) }
+    }
+}
diff --git a/Sources/AetherEngine/Demuxer/AVIOReader.swift b/Sources/AetherEngine/Demuxer/AVIOReader.swift
index 8dd07023b..c4d453481 100644
--- a/Sources/AetherEngine/Demuxer/AVIOReader.swift
+++ b/Sources/AetherEngine/Demuxer/AVIOReader.swift
@@ -1468,6 +1468,11 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
         readDeadline = .distantFuture
     }
 
+    private var readByteBudget = ReadByteBudget()
+    var readByteBudgetExhausted: Bool { readByteBudget.exhausted }
+    func beginReadByteBudget(_ bytes: Int64) { readByteBudget.begin(bytes) }
+    func endReadByteBudget() { readByteBudget.end() }
+
     /// Deadline expired; latches `readDeadlineFired` at the check sites.
     private var readDeadlinePassedOrAborted: Bool { isPastReadDeadline }
 
@@ -1588,13 +1593,15 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
     func read(into buf: UnsafeMutablePointer<UInt8>, size: Int32) -> Int32 {
         guard !isClosed else { return -1 }
         if readDeadlinePassedOrAborted { readDeadlineFired = true; return -1 }
+        guard let allowed = readByteBudget.allowance(size) else { return -1 }
         // Check usePersistentReader before isStreaming: live feeds without
         // Content-Length must use the reconnect-capable persistent path.
         let n: Int32
-        if usePersistentReader { n = readPersistent(into: buf, size: size) }
-        else if isStreaming { n = readStreaming(into: buf, size: size) }
-        else { n = readSeekable(into: buf, size: size) }
+        if usePersistentReader { n = readPersistent(into: buf, size: allowed) }
+        else if isStreaming { n = readStreaming(into: buf, size: allowed) }
+        else { n = readSeekable(into: buf, size: allowed) }
         if n > 0 { applyThrottle(deliveredBytes: Int(n)) }
+        readByteBudget.consumed(n)
         return n
     }
 
diff --git a/Sources/AetherEngine/Demuxer/CustomIOReaderBridge.swift b/Sources/AetherEngine/Demuxer/CustomIOReaderBridge.swift
index 6b6eabd0e..0032ffe57 100644
--- a/Sources/AetherEngine/Demuxer/CustomIOReaderBridge.swift
+++ b/Sources/AetherEngine/Demuxer/CustomIOReaderBridge.swift
@@ -40,6 +40,11 @@ final class CustomIOReaderBridge: AVIOProvider, @unchecked Sendable {
         readDeadline = .distantFuture
     }
 
+    private var readByteBudget = ReadByteBudget()
+    var readByteBudgetExhausted: Bool { readByteBudget.exhausted }
+    func beginReadByteBudget(_ bytes: Int64) { readByteBudget.begin(bytes) }
+    func endReadByteBudget() { readByteBudget.end() }
+
     /// #112 round 9: the byte axis libavformat sees through this bridge (for a disc adapter, the
     /// virtual concat stream length via AVSEEK_SIZE), backing the byte-estimate seek fallback.
     var resolvedByteSize: Int64? {
@@ -180,8 +185,10 @@ final class CustomIOReaderBridge: AVIOProvider, @unchecked Sendable {
         // -1 = forced abort (not EOF); mirrors AVIOReader.read so FFmpeg doesn't run EOS handling.
         guard !isClosed else { return -1 }
         if isPastReadDeadline { readDeadlineFired = true; return -1 }
-        let n = callingHost { reader.read(buf, size: size) }
+        guard let allowed = readByteBudget.allowance(size) else { return -1 }
+        let n = callingHost { reader.read(buf, size: allowed) }
         if n == 0 { return FFmpegErr.eof }  // IOReader uses 0 for EOF; avio expects AVERROR_EOF.
+        readByteBudget.consumed(n)
         return n
     }
 
diff --git a/Sources/AetherEngine/Demuxer/Demuxer.swift b/Sources/AetherEngine/Demuxer/Demuxer.swift
index f8e32d8ac..05439e4db 100644
--- a/Sources/AetherEngine/Demuxer/Demuxer.swift
+++ b/Sources/AetherEngine/Demuxer/Demuxer.swift
@@ -692,14 +692,15 @@ public final class Demuxer: @unchecked Sendable {
     private func applyProbeBudget(_ ctx: UnsafeMutablePointer<AVFormatContext>) {
         ctx.pointee.probesize = openProfile.probesize
         ctx.pointee.max_analyze_duration = openProfile.maxAnalyzeDuration
-        if let probeControl {
-            ctx.pointee.interrupt_callback = AVIOInterruptCB(
-                callback: { opaque in
-                    guard let opaque else { return 0 }
-                    return Unmanaged<ProbeControl>.fromOpaque(opaque).takeUnretainedValue().isStopped ? 1 : 0
-                },
-                opaque: Unmanaged.passUnretained(probeControl).toOpaque())
-        }
+        // Installed unconditionally: a local input's URLContext copies the callback at open, so the
+        // input byte budget could not reach it later.
+        ctx.pointee.interrupt_callback = AVIOInterruptCB(
+            callback: { opaque in
+                guard let opaque else { return 0 }
+                return Unmanaged<DemuxInterrupt>.fromOpaque(opaque).takeUnretainedValue()
+                    .shouldInterrupt() ? 1 : 0
+            },
+            opaque: Unmanaged.passUnretained(interrupt).toOpaque())
     }
 
     /// Demuxer fflags applied to every avformat_open_input.
@@ -2095,11 +2096,47 @@ public final class Demuxer: @unchecked Sendable {
     }
 
     /// Static metadata probes only. Strong ownership outlives the native interrupt callback.
-    var probeControl: ProbeControl?
+    var probeControl: ProbeControl? {
+        get { interrupt.probeControl }
+        set { interrupt.probeControl = newValue }
+    }
+
+    /// Target of the format context's interrupt callback, owned for the demuxer's whole life so the
+    /// unretained pointer libavformat holds cannot dangle.
+    private let interrupt = DemuxInterrupt()
+
+    /// Caps the source bytes libavformat may consume until `endInputByteBudget`, enforced below
+    /// `av_read_frame`. A pass that sets AVDISCARD_ALL on other streams needs this: the demuxer reads
+    /// and drops their blocks inside one `av_read_frame`, where no packet or packet-byte cap sees them.
+    /// Overshoot is at most one read. Call from the thread that reads packets.
+    func beginInputByteBudget(_ bytes: Int64) {
+        accessLock.lock()
+        defer { accessLock.unlock() }
+        if let provider = avioProvider {
+            provider.beginReadByteBudget(bytes)
+        } else if let pb = formatContext?.pointee.pb {
+            interrupt.armInputCeiling(pb: pb, bytes: bytes)
+        }
+    }
+
+    func endInputByteBudget() {
+        accessLock.lock()
+        defer { accessLock.unlock() }
+        avioProvider?.endReadByteBudget()
+        interrupt.disarmInputCeiling()
+    }
+
+    /// True when a read was refused because the budget armed by `beginInputByteBudget` was spent.
+    var inputByteBudgetExhausted: Bool {
+        accessLock.lock()
+        defer { accessLock.unlock() }
+        return (avioProvider?.readByteBudgetExhausted ?? false) || interrupt.inputCeilingHit
+    }
 
     func close() {
         avioProvider?.markClosed()  // unblocks av_read_frame (tvOS suspends threads in background)
         accessLock.lock()
+        interrupt.disarmInputCeiling()
         if formatContext != nil {
             avformat_close_input(&formatContext)
         }
@@ -2136,3 +2173,34 @@ enum DemuxerError: Error, CustomStringConvertible, LocalizedError {
 
     var errorDescription: String? { description }
 }
+
+/// Answers libavformat's interrupt callback. `probeControl` is set before open; the input ceiling is
+/// armed and read only on the thread that holds the demuxer's access lock for the native call.
+private final class DemuxInterrupt: @unchecked Sendable {
+    var probeControl: ProbeControl?
+    private var pb: UnsafeMutablePointer<AVIOContext>?
+    private var ceiling: Int64 = .max
+    private(set) var inputCeilingHit = false
+
+    /// Local (URLContext) inputs only: a provider-backed input never consults this callback per read.
+    func armInputCeiling(pb: UnsafeMutablePointer<AVIOContext>, bytes: Int64) {
+        self.pb = pb
+        let (sum, overflow) = pb.pointee.bytes_read.addingReportingOverflow(max(0, bytes))
+        ceiling = overflow ? .max : sum
+        inputCeilingHit = false
+    }
+
+    func disarmInputCeiling() {
+        pb = nil
+        ceiling = .max
+    }
+
+    func shouldInterrupt() -> Bool {
+        if probeControl?.isStopped == true { return true }
+        if let pb, pb.pointee.bytes_read >= ceiling {
+            inputCeilingHit = true
+            return true
+        }
+        return false
+    }
+}
diff --git a/Sources/AetherEngine/Video/HDR10PlusDetectionProbe.swift b/Sources/AetherEngine/Video/HDR10PlusDetectionProbe.swift
index 1845ddb4e..87ea1fb94 100644
--- a/Sources/AetherEngine/Video/HDR10PlusDetectionProbe.swift
+++ b/Sources/AetherEngine/Video/HDR10PlusDetectionProbe.swift
@@ -25,6 +25,10 @@ public struct HDR10PlusDetectionOptions: Sendable, Equatable {
     /// This is the cap that actually binds on the content the feature targets: one UHD HEVC keyframe runs to
     /// several MB, so a handful of packets can exhaust it long before `maxPackets` does. A packet larger
     /// than the remaining budget stops the pass BEFORE inspection, even if it carries HDR10+.
+    ///
+    /// It also sets what the pass may read from the source in total, video or not: four times this
+    /// value, and never less than 4 MiB. That bound sits below the demuxer, so the blocks of the other
+    /// streams, which the demuxer reads and drops without ever handing them back as packets, count too.
     public var maxBytes: Int64
 
     /// Soft wall-clock budget, checked before and after reads and after inspection. NOT preemptive:
@@ -104,6 +108,15 @@ extension AetherEngine {
         return nil
     }
 
+    /// Source bytes the scan may consume, whatever stream they belong to. `maxBytes` alone bounds only
+    /// the video packets the scan sees; with the other streams at AVDISCARD_ALL the demuxer reads and
+    /// drops their blocks inside one `av_read_frame`, so a file with one video packet followed by
+    /// gigabytes of another stream would otherwise be read to its end. Saturating: `maxBytes` is public.
+    nonisolated static func hdr10PlusInputByteBudget(maxBytes: Int64) -> Int64 {
+        let (product, overflowed) = max(0, maxBytes).multipliedReportingOverflow(by: 4)
+        return overflowed ? .max : max(product, 4 * 1024 * 1024)
+    }
+
     /// Packet ceiling for the AVDISCARD_ALL fuse, saturating rather than trapping: `maxPackets` is public and
     /// `Int.max` is a plausible "no limit" value to pass.
     nonisolated static func hdr10PlusForeignPacketFuse(maxPackets: Int) -> Int {
@@ -148,6 +161,12 @@ extension AetherEngine {
         // Matroska's BlockAdditional carriage is attached by the demuxer to the packet, so the scan needs the
         // packets themselves either way; dropping the other streams keeps the byte budget spent on video.
         demuxer.discardAllStreamsExcept([videoIndex])
+        demuxer.beginInputByteBudget(Self.hdr10PlusInputByteBudget(maxBytes: options.maxBytes))
+        defer { demuxer.endInputByteBudget() }
+        // A read the input budget refused surfaces as an error or as EOF, depending on the container.
+        func readEnded(_ reason: HDR10PlusDetectionOutcome.StopReason) -> HDR10PlusDetectionOutcome.StopReason {
+            demuxer.inputByteBudgetExhausted ? .byteCap : reason
+        }
 
         let start = now()
         func elapsed() -> TimeInterval {
@@ -170,7 +189,7 @@ extension AetherEngine {
                 packet = try demuxer.readPacket()
             } catch {
                 return HDR10PlusDetectionOutcome(
-                    stopReason: .demuxError, packetsRead: packetsRead, bytesRead: bytesRead)
+                    stopReason: readEnded(.demuxError), packetsRead: packetsRead, bytesRead: bytesRead)
             }
             defer {
                 if let packet {
@@ -184,7 +203,7 @@ extension AetherEngine {
             }
             guard let pkt = packet else {
                 return HDR10PlusDetectionOutcome(
-                    stopReason: .demuxEOF, packetsRead: packetsRead, bytesRead: bytesRead)
+                    stopReason: readEnded(.demuxEOF), packetsRead: packetsRead, bytesRead: bytesRead)
             }
 
             var found = false
diff --git a/Tests/AetherEngineTests/HDR10PlusScanInputBudgetTests.swift b/Tests/AetherEngineTests/HDR10PlusScanInputBudgetTests.swift
new file mode 100644
index 000000000..a94c9f043
--- /dev/null
+++ b/Tests/AetherEngineTests/HDR10PlusScanInputBudgetTests.swift
@@ -0,0 +1,149 @@
+import Testing
+import Foundation
+@testable import AetherEngine
+
+/// The HDR10+ scan drops every stream but video (AVDISCARD_ALL), and the demuxer reads and throws away
+/// those streams' blocks inside one `av_read_frame`, where the scan's packet and packet-byte caps never see
+/// them. The fixture is the adversarial shape: two tiny video packets, then ~24 MiB of another stream. The
+/// scan must stop on its input budget instead of reading the file to its end.
+@Suite("HDR10+ scan: the input byte budget holds below the demuxer")
+struct HDR10PlusScanInputBudgetTests {
+
+    @Test("A tail of dropped foreign blocks stops the scan on its byte cap, on local and custom inputs",
+          arguments: [false, true])
+    func foreignTailHitsTheInputBudget(customReader: Bool) throws {
+        let data = try TailHeavyMatroska.make(foreignBytes: 24 * 1024 * 1024)
+        try ProbeTestFixtures.withFile(data) { url in
+            let outcome = try Self.scan(url, customReader: customReader, maxBytes: 1024)
+            #expect(outcome.stopReason == .byteCap)
+            #expect(outcome.packetsRead == 2)
+        }
+    }
+
+    @Test("A budget that covers the file still reaches EOF, so the cap is the budget and not the fixture")
+    func coveringBudgetReachesEOF() throws {
+        let data = try TailHeavyMatroska.make(foreignBytes: 24 * 1024 * 1024)
+        try ProbeTestFixtures.withFile(data) { url in
+            let outcome = try Self.scan(url, customReader: false, maxBytes: 16 * 1024 * 1024)
+            #expect(outcome.stopReason == .demuxEOF)
+        }
+    }
+
+    @Test("The input budget is four times maxBytes with a 4 MiB floor, and saturates")
+    func inputBudgetArithmetic() {
+        #expect(AetherEngine.hdr10PlusInputByteBudget(maxBytes: 16 * 1024 * 1024) == 64 * 1024 * 1024)
+        #expect(AetherEngine.hdr10PlusInputByteBudget(maxBytes: 0) == 4 * 1024 * 1024)
+        #expect(AetherEngine.hdr10PlusInputByteBudget(maxBytes: -5) == 4 * 1024 * 1024)
+        #expect(AetherEngine.hdr10PlusInputByteBudget(maxBytes: .max) == .max)
+    }
+
+    private static func scan(_ url: URL, customReader: Bool, maxBytes: Int64) throws -> HDR10PlusDetectionOutcome {
+        let demuxer = Demuxer()
+        defer { demuxer.close() }
+        if customReader {
+            try demuxer.open(reader: try #require(FileIOReader(url: url)))
+        } else {
+            try demuxer.open(url: url)
+        }
+        return AetherEngine.detectHDR10Plus(
+            demuxer: demuxer, videoIndex: demuxer.videoStreamIndex,
+            options: HDR10PlusDetectionOptions(maxPackets: 32, maxBytes: maxBytes, timeBudget: 60))
+    }
+}
+
+/// Matroska with the plain HDR10 fixture's two HEVC frames at the head and a long PCM tail after them.
+private enum TailHeavyMatroska {
+
+    static func make(foreignBytes: Int) throws -> Data {
+        let mp4 = try ProbeTestFixtures.decode(HDR10PlusProbeIntegrationTests.hdr10Base64)
+        let (hvcC, frames) = try hevcTrack(mp4)
+
+        var out = Data()
+        out += element([0x1A, 0x45, 0xDF, 0xA3],
+                       element([0x42, 0x82], Array("matroska".utf8)) +
+                       element([0x42, 0x87], uint(4)) +
+                       element([0x42, 0x85], uint(2)))
+
+        let info = element([0x15, 0x49, 0xA9, 0x66], element([0x2A, 0xD7, 0xB1], uint(1_000_000)))
+        let video = element([0xAE],
+                            element([0xD7], uint(1)) + element([0x73, 0xC5], uint(1)) +
+                            element([0x83], uint(1)) + element([0x86], Array("V_MPEGH/ISO/HEVC".utf8)) +
+                            element([0x63, 0xA2], hvcC) +
+                            // DefaultDuration: without a frame rate, stream analysis at open reads
+                            // (and queues) seconds of the tail looking for one.
+                            element([0x23, 0xE3, 0x83], uint(40_000_000)) +
+                            element([0xE0], element([0xB0], uint(64)) + element([0xBA], uint(64))))
+        let audio = element([0xAE],
+                            element([0xD7], uint(2)) + element([0x73, 0xC5], uint(2)) +
+                            element([0x83], uint(2)) + element([0x86], Array("A_PCM/INT/LIT".utf8)) +
+                            element([0xE1], element([0xB5], float64(48_000)) +
+                                            element([0x9F], uint(2)) + element([0x62, 0x64], uint(16))))
+        let tracks = element([0x16, 0x54, 0xAE, 0x6B], video + audio)
+
+        // 32 KiB of 16-bit stereo at 48 kHz is 170 ms. One cluster per block keeps every relative
+        // timestamp at zero.
+        let blockBytes = 32 * 1024
+        var clusters: [UInt8] = []
+        clusters += element([0x1F, 0x43, 0xB6, 0x75],
+                            element([0xE7], uint(0)) +
+                            simpleBlock(track: 1, relative: 0, payload: frames[0]) +
+                            simpleBlock(track: 1, relative: 40, payload: frames[1]))
+        let silence = [UInt8](repeating: 0, count: blockBytes)
+        for i in 0..<max(1, foreignBytes / blockBytes) {
+            clusters += element([0x1F, 0x43, 0xB6, 0x75],
+                                element([0xE7], uint(100 + i * 170)) +
+                                simpleBlock(track: 2, relative: 0, payload: silence))
+        }
+        out += element([0x18, 0x53, 0x80, 0x67], info + tracks + clusters)
+        return out
+    }
+
+    /// The hvcC payload and the sample bytes of the fixture's single video track (one chunk).
+    private static func hevcTrack(_ mp4: Data) throws -> (hvcC: [UInt8], frames: [[UInt8]]) {
+        let bytes = [UInt8](mp4)
+        func box(_ type: String) throws -> Int {
+            let tag = Array(type.utf8)
+            let at = try #require((4...(bytes.count - 4)).first { Array(bytes[$0..<$0 + 4]) == tag })
+            return at - 4
+        }
+        func u32(_ i: Int) -> Int { bytes[i..<i + 4].reduce(0) { $0 << 8 | Int($1) } }
+        let hvcCAt = try box("hvcC")
+        let hvcC = Array(bytes[(hvcCAt + 8)..<(hvcCAt + u32(hvcCAt))])
+        let stsz = try box("stsz")
+        let count = u32(stsz + 16)
+        let sizes = (0..<count).map { u32(stsz + 20 + 4 * $0) }
+        var offset = u32(try box("stco") + 16)
+        var frames: [[UInt8]] = []
+        for size in sizes {
+            frames.append(Array(bytes[offset..<offset + size]))
+            offset += size
+        }
+        try #require(frames.count == 2)
+        return (hvcC, frames)
+    }
+
+    private static func simpleBlock(track: UInt8, relative: Int, payload: [UInt8]) -> [UInt8] {
+        element([0xA3], [0x80 | track, UInt8((relative >> 8) & 0xFF), UInt8(relative & 0xFF), 0x80] + payload)
+    }
+
+    private static func element(_ id: [UInt8], _ payload: [UInt8]) -> [UInt8] {
+        var size: [UInt8] = [0x01]
+        for shift in stride(from: 48, through: 0, by: -8) { size.append(UInt8((payload.count >> shift) & 0xFF)) }
+        return id + size + payload
+    }
+
+    private static func uint(_ v: Int) -> [UInt8] {
+        var bytes: [UInt8] = []
+        var v = v
+        repeat {
+            bytes.insert(UInt8(v & 0xFF), at: 0)
+            v >>= 8
+        } while v > 0
+        return bytes
+    }
+
+    private static func float64(_ v: Double) -> [UInt8] {
+        let bits = v.bitPattern
+        return (0..<8).map { UInt8((bits >> (56 - 8 * UInt64($0))) & 0xFF) }
+    }
+}
diff --git a/docs/api.md b/docs/api.md
index 76d815ab4..75e2c81e3 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -414,7 +414,7 @@ try await player.reloadAtCurrentPosition()
 | `AetherEngine.probeDetectingAtmos(url:options:atmosDetection:)` | `probe` plus a bounded decode pass that authoritatively resolves E-AC-3 JOC for an Atmos badge. Strictly more expensive; never on the playback-start path. Decode-side failures degrade to "not confirmed" rather than throwing. Same thing as `probe(url:detecting: .atmos)`. |
 | `AetherEngine.probe(url:options:detecting:atmosDetection:hdr10PlusDetection:)` / `probe(source:...)` | `probe` plus the opt-in passes named in `ProbeDetail`, over one demuxer: `.atmos` (the bounded JOC decode above) and `.hdr10Plus` (structurally validated ST 2094-40 carriage). Both passes share the optional trailing `limits` and `cancellation`. Empty set is the header probe with the same controls. Both passes only ever SET `isAtmos` / `carriesHDR10PlusMetadata`; ordinary pass failures and per-pass caps leave the detail unconfirmed. A whole-probe stop throws, with no partial result. |
 | `ProbeDetail` | `OptionSet`: `.atmos`, `.hdr10Plus`. |
-| `HDR10PlusDetectionOptions` | Bounds for the HDR10+ scan: `maxPackets` (32), `maxBytes` (16 MiB), `timeBudget` (2 s). The byte cap is the one that binds on UHD remuxes, where a single keyframe runs to several MB. |
+| `HDR10PlusDetectionOptions` | Bounds for the HDR10+ scan: `maxPackets` (32), `maxBytes` (16 MiB), `timeBudget` (2 s). The byte cap is the one that binds on UHD remuxes, where a single keyframe runs to several MB. It also bounds the total source read to four times `maxBytes` (at least 4 MiB), below the demuxer, so blocks of dropped streams count. |
 | `ProbeLimits` | Optional whole-probe controls: `maxInputBytes` (8 MiB), `maxPackets` (128), `maxPacketBytes` (2 MiB), `timeBudget` (5 s). Nonnegative values required; the time budget must be finite. |
 | `ProbeCancellation` | Thread-safe, one-shot token: `init()`, `isCancelled`, `cancel()`. Available on every URL/custom header, detail and `probeDetectingAtmos` overload. Cancellation is a request, not a completion notification. |
 | `ProbeError` | `invalidLimits`, `inputLimit`, `packetLimit`, `packetSizeLimit`, `timedOut`, `invalidReaderResult`, `unsupportedURL`, `sourceBusy`; `errorDescription` describes the stop. Explicit caller cancellation throws `CancellationError` instead. |

From 8eeed62fc017b0b18ab952a46344a9e59a1193f7 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 06:20:59 +0200
Subject: [PATCH 087/359] docs(changelog): audit decoder, audio, subtitle and
 CI fixes

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 CHANGELOG.md | 25 ++++++++++++++++++++++---
 1 file changed, 22 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1500acd2e..4686324e5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -39,9 +39,26 @@ the public-API contract.
   `#EXTINF:inf` behind an injected subtitle sidecar all trapped; each is now rejected or bounded at
   parse, and the sidecar playlist fetch is size-capped (audit NET-3, NET-4, NET-5, NET-11, NAT-1,
   NAT-5).
-
-### Fixed
-
+- **SECURITY.md names the current supported release line** instead of 2.1.x, CI pins third-party
+  GitHub Actions to commit SHAs with Dependabot proposing updates, and aetherctl writes its debug
+  files into a private per-run temporary directory instead of fixed names in `/tmp` (audit OPS-1,
+  OPS-2, OPS-3).
+
+### Fixed
+
+- **A seek on the software path no longer lets one pre-seek frame wedge the picture.** A seek that
+  landed while the decoder was retrying a full queue, or while the hardware decoder was preparing a
+  packet, still let that packet through after the flush (audit DEC-1, DEC-4, AE#492).
+- **Seeking in audio-only playback no longer leaves stale audio queued ahead of the new position**
+  (audit DEC-2).
+- **Subtitles in Picture in Picture no longer squash anamorphic video or turn HDR to SDR while a line
+  is showing.** Composited frames keep the source's pixel aspect ratio, colour tags and colour space,
+  and the compositor's buffer pool is no longer raced at stop (audit DEC-3, DEC-5).
+- **A bridged audio track no longer goes silent for the rest of the session after one frame the
+  resampler rejects.** The frame is dropped and logged, and the previous resampler keeps running
+  (audit DEC-6).
+- **Stopping a live recording no longer blocks the main thread while the backlog is written.**
+  `recordingState` turns `.ended` once the file is closed, a moment after the stop (audit REC-1).
 - **CRLF-terminated HLS playlists parse.** In Swift `"\r\n"` is one Character, so splitting on `"\n"`
   read the whole playlist as one line and rejected it on the live/VOD ingest, the audio tap and the
   subtitle proxy (audit NET-2).
@@ -114,6 +131,8 @@ the public-API contract.
 - **Faster first segment after a seek on TrueHD sources, and less CPU for HDR10+ detection on sources
   without HDR10+** (audit SEG-6, BIT-4).
 - **The live ingest FIFO no longer re-copies its whole buffer on every read** (audit NET-8).
+- **Stripping ASS override tags from a cue is linear.** A cue of 200k tags took 525 s and now takes
+  0.15 s on the PiP and AirPlay subtitle track (audit SUB-1).
 
 ## [7.16.1] - 2026-09-24
 

From 171a3f2b994431c53d77fb183147747dc30cc73a Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 06:21:20 +0200
Subject: [PATCH 088/359] fix(hls): stop() aborts the replacement demuxer a
 wedged-pump restart is opening (audit SEG-3 follow-up)

The #79 / #169 restart opened its fresh demuxer in a local that stop() could not see, so a stop
during that open let it run its connect and stream probe, and the seek after it, to the end. The
replacement is now registered under the restart lock before its open, atomically with the epoch
check, and stop() marks it closed (sticky since HLS-2). The restart still owns closing it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 .../AetherEngine/Video/HLSVideoEngine.swift   | 29 +++++++++++++--
 .../RestartReopenStopTests.swift              | 35 +++++++++++++++++++
 2 files changed, 62 insertions(+), 2 deletions(-)
 create mode 100644 Tests/AetherEngineTests/RestartReopenStopTests.swift

diff --git a/Sources/AetherEngine/Video/HLSVideoEngine.swift b/Sources/AetherEngine/Video/HLSVideoEngine.swift
index ea9fc71bb..3f2ee300d 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine.swift
@@ -622,6 +622,9 @@ public final class HLSVideoEngine: @unchecked Sendable {
     /// In-flight live reopen demuxer, registered before its blocking open so `stop()` can abort it
     /// (prevents orphan reconnect loops across channel zaps).
     var reopenDemuxer: Demuxer?
+    /// The #79 / #169 restart's replacement demuxer, from before its open until the restart installs
+    /// or drops it, so `stop()` can abort that open and the seek after it (audit SEG-3 follow-up).
+    private var restartReopenDemuxer: Demuxer?
     /// Fires on live program-boundary rebase: `(newShiftSeconds, seamOutputSeconds)`. AetherEngine
     /// defers applying the shift until playback crosses `seamOutputSeconds` so the clock doesn't jump.
     var onPlaylistShiftRebased: (@Sendable (Double, Double) -> Void)?
@@ -2450,12 +2453,16 @@ public final class HLSVideoEngine: @unchecked Sendable {
         ownedCodecParams = []
         let reopening = reopenDemuxer
         reopenDemuxer = nil
+        let restartReopening = restartReopenDemuxer
+        restartReopenDemuxer = nil
         // #199: factory-vended ingest reader feeding the current demuxer; session-owned, closed here.
         let reopenReader = reopenCustomReader
         reopenCustomReader = nil
         segmentPlan = []
         restartLock.unlock()
         reopening?.markClosed()
+        // The restart that opened it closes it once it sees the epoch moved.
+        restartReopening?.markClosed()
         // Close before waitForFinish: cancels the reader's FIFO so a pump parked in a blocking
         // custom-IO read unblocks (mirrors markClosed for URL demuxers).
         reopenReader?.close()
@@ -3817,6 +3824,23 @@ public final class HLSVideoEngine: @unchecked Sendable {
         return parts.joined(separator: " ")
     }
 
+    /// A new demuxer for the #79 / #169 reopen, registered for `stop()` before its blocking open, or
+    /// nil when a stop already superseded the restart at `epoch`.
+    func registerRestartReopenDemuxer(epoch: UInt64) -> Demuxer? {
+        restartLock.lock()
+        defer { restartLock.unlock() }
+        guard sessionEpoch == epoch else { return nil }
+        let fresh = Demuxer()
+        restartReopenDemuxer = fresh
+        return fresh
+    }
+
+    private func unregisterRestartReopenDemuxer(_ dem: Demuxer) {
+        restartLock.lock()
+        if restartReopenDemuxer === dem { restartReopenDemuxer = nil }
+        restartLock.unlock()
+    }
+
     // Driven exclusively through requestRestart(at:) so bursts coalesce (#35).
     private func performRestart(at idx: Int) {
         restartGate.lock()
@@ -3875,9 +3899,8 @@ public final class HLSVideoEngine: @unchecked Sendable {
             // AE#169 round 2 takes the same path when the pump exited BECAUSE the demuxer's read
             // threw: the connection is known-bad, so the revive gets one fresh connection instead
             // of seeking the demuxer that just failed.
-            if !isLiveSession, sideAudioDemuxer == nil {
+            if !isLiveSession, sideAudioDemuxer == nil, let fresh = registerRestartReopenDemuxer(epoch: epoch) {
                 let reopenStart = DispatchTime.now()
-                let fresh = Demuxer()
                 do {
                     // .restartReopen: bounded find_stream_info budget; the FULL playback budget was
                     // the bulk of a 44 s wedge-reopen over WAN (#93 residual). The pass itself must
@@ -3900,6 +3923,7 @@ public final class HLSVideoEngine: @unchecked Sendable {
                         category: .session
                     )
                 } catch {
+                    unregisterRestartReopenDemuxer(fresh)
                     fresh.close()
                     EngineLog.emit(
                         "[HLSVideoEngine] restart at idx=\(idx): "
@@ -3935,6 +3959,7 @@ public final class HLSVideoEngine: @unchecked Sendable {
 
         // Re-validate: a stop() landing during waits bumped sessionEpoch; don't resurrect into a torn-down session.
         restartLock.lock()
+        if let freshDemuxer, restartReopenDemuxer === freshDemuxer { restartReopenDemuxer = nil }
         guard sessionEpoch == epoch else {
             restartLock.unlock()
             // #79: a reopened demuxer (replacing a wedged one) must not leak when stop() superseded us.
diff --git a/Tests/AetherEngineTests/RestartReopenStopTests.swift b/Tests/AetherEngineTests/RestartReopenStopTests.swift
new file mode 100644
index 000000000..fad8dfe8c
--- /dev/null
+++ b/Tests/AetherEngineTests/RestartReopenStopTests.swift
@@ -0,0 +1,35 @@
+import Testing
+import Foundation
+@testable import AetherEngine
+
+/// The #79 / #169 restart opens a replacement demuxer while the old pump is wedged. `stop()` has to reach
+/// that open: an unregistered one ran its connect and stream probe to the end after the session was gone.
+@Suite("Restart reopen: stop() reaches the replacement demuxer")
+struct RestartReopenStopTests {
+
+    private func makeEngine() -> HLSVideoEngine {
+        HLSVideoEngine(url: URL(fileURLWithPath: "/nonexistent/restart-reopen.mkv"), dvModeAvailable: false)
+    }
+
+    @Test("A stop after registration aborts the replacement's open before it reaches the origin")
+    func stopAbortsTheRegisteredOpen() throws {
+        let origin = try ProbeHTTPTestOrigin(data: try ProbeTestFixtures.hdr10Plus())
+        defer { origin.stop() }
+        let engine = makeEngine()
+        let fresh = try #require(engine.registerRestartReopenDemuxer(epoch: 0))
+        defer { fresh.close() }
+
+        engine.stop()
+
+        let url = try #require(URL(string: "http://127.0.0.1:\(origin.port)/restart-reopen.mp4"))
+        #expect(throws: (any Error).self) { try fresh.open(url: url) }
+        #expect(origin.requests.isEmpty)
+    }
+
+    @Test("A restart that a stop already superseded opens no replacement at all")
+    func supersededRestartRegistersNothing() {
+        let engine = makeEngine()
+        engine.stop()
+        #expect(engine.registerRestartReopenDemuxer(epoch: 0) == nil)
+    }
+}

From 06c241270941f8300a6ae807eeca9aa082e66257 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Fri, 25 Sep 2026 04:21:32 +0000
Subject: [PATCH 089/359] chore(ci): bump actions/checkout from 4 to 7

Bumps [actions/checkout](https://github.com/actions/checkout) from 4 to 7.
- [Release notes](https://github.com/actions/checkout/releases)
- [Changelog](https://github.com/actions/checkout/blob/main/CHANGELOG.md)
- [Commits](https://github.com/actions/checkout/compare/v4...v7)

---
updated-dependencies:
- dependency-name: actions/checkout
  dependency-version: '7'
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>
---
 .github/workflows/ci.yml          | 14 +++++++-------
 .github/workflows/release-dmg.yml |  2 +-
 .github/workflows/used-by-add.yml |  2 +-
 3 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index ab77d7d2f..642b3ab20 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -17,7 +17,7 @@ jobs:
     runs-on: macos-15
     timeout-minutes: 30
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
       - uses: maxim-lobanov/setup-xcode@ed7a3b1fda3918c0306d1b724322adc0b8cc0a90 # v1.7.0
         with:
@@ -70,7 +70,7 @@ jobs:
     runs-on: macos-15
     timeout-minutes: 30
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
       - uses: maxim-lobanov/setup-xcode@ed7a3b1fda3918c0306d1b724322adc0b8cc0a90 # v1.7.0
         with:
@@ -119,7 +119,7 @@ jobs:
     runs-on: macos-15
     timeout-minutes: 30
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
       - uses: maxim-lobanov/setup-xcode@ed7a3b1fda3918c0306d1b724322adc0b8cc0a90 # v1.7.0
         with:
@@ -154,7 +154,7 @@ jobs:
     runs-on: macos-15
     timeout-minutes: 30
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
       - uses: maxim-lobanov/setup-xcode@ed7a3b1fda3918c0306d1b724322adc0b8cc0a90 # v1.7.0
         with:
@@ -188,7 +188,7 @@ jobs:
     runs-on: xcode-27
     timeout-minutes: 30
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
       - name: Show toolchain
         run: |
@@ -203,7 +203,7 @@ jobs:
     runs-on: xcode-27
     timeout-minutes: 30
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
       - name: Build for tvOS Simulator
         run: |
@@ -234,7 +234,7 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 5
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
       - name: Validate relative links and heading anchors in the published docs
         run: python3 Scripts/check-doc-links.py
diff --git a/.github/workflows/release-dmg.yml b/.github/workflows/release-dmg.yml
index 788e44a4e..7cba074db 100644
--- a/.github/workflows/release-dmg.yml
+++ b/.github/workflows/release-dmg.yml
@@ -49,7 +49,7 @@ jobs:
     runs-on: macos-15
     timeout-minutes: 30
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
       - uses: maxim-lobanov/setup-xcode@ed7a3b1fda3918c0306d1b724322adc0b8cc0a90 # v1.7.0
         with:
diff --git a/.github/workflows/used-by-add.yml b/.github/workflows/used-by-add.yml
index cee3d35a5..d1a605bae 100644
--- a/.github/workflows/used-by-add.yml
+++ b/.github/workflows/used-by-add.yml
@@ -26,7 +26,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
 
       - name: Normalise the issue body
         id: normalise

From 02f2b65c36fbeb0e8099f1d0397269b13ca66377 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Fri, 25 Sep 2026 04:21:38 +0000
Subject: [PATCH 090/359] chore(ci): bump peter-evans/create-pull-request from
 6.1.0 to 8.1.1

Bumps [peter-evans/create-pull-request](https://github.com/peter-evans/create-pull-request) from 6.1.0 to 8.1.1.
- [Release notes](https://github.com/peter-evans/create-pull-request/releases)
- [Commits](https://github.com/peter-evans/create-pull-request/compare/c5a7806660adbe173f04e3e038b0ccdcd758773c...5f6978faf089d4d20b00c7766989d076bb2fc7f1)

---
updated-dependencies:
- dependency-name: peter-evans/create-pull-request
  dependency-version: 8.1.1
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>
---
 .github/workflows/used-by-add.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/used-by-add.yml b/.github/workflows/used-by-add.yml
index cee3d35a5..fd976bf1d 100644
--- a/.github/workflows/used-by-add.yml
+++ b/.github/workflows/used-by-add.yml
@@ -151,7 +151,7 @@ jobs:
       - name: Open pull request
         if: steps.build.outputs.skip == 'false'
         id: pr
-        uses: peter-evans/create-pull-request@c5a7806660adbe173f04e3e038b0ccdcd758773c # v6.1.0
+        uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1
         with:
           # Only the README, so no stray runner file can ride along.
           add-paths: README.md

From 078f1be54e5db7ea0f9183e9fb1837ea9ea21912 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 06:22:45 +0200
Subject: [PATCH 091/359] fix(hls): wholeSecondsCovering saturates instead of
 trapping on a non-finite duration

The helper behind #EXT-X-TARGETDURATION handed its rounded input straight to Int(_:), which traps
on infinity, NaN and anything beyond Int. It is now total: an unbounded duration saturates at one
day, which keeps the 3 x TD holdback arithmetic far from overflow, and NaN or a non-positive
duration covers nothing, so it drops out of the max() the target duration is built from.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 .../Video/VideoSegmentProvider.swift          | 12 +++++-
 .../WholeSecondsCoveringTotalityTests.swift   | 39 +++++++++++++++++++
 2 files changed, 50 insertions(+), 1 deletion(-)
 create mode 100644 Tests/AetherEngineTests/WholeSecondsCoveringTotalityTests.swift

diff --git a/Sources/AetherEngine/Video/VideoSegmentProvider.swift b/Sources/AetherEngine/Video/VideoSegmentProvider.swift
index 1c39c96d6..0169d9477 100644
--- a/Sources/AetherEngine/Video/VideoSegmentProvider.swift
+++ b/Sources/AetherEngine/Video/VideoSegmentProvider.swift
@@ -286,10 +286,20 @@ enum LiveEdgePolicy {
     }
 
     /// Whole seconds of promise covering a measured duration, taken at the served resolution.
+    ///
+    /// Total: a duration from a hostile or broken source (infinite, NaN, beyond `Int`) must not trap the
+    /// playlist writer. An unbounded one saturates at `maxCoveredWholeSeconds`, which keeps `3 x TD`
+    /// arithmetic far from overflow; NaN and anything at or below zero cover nothing.
     static func wholeSecondsCovering(_ seconds: Double) -> Int {
-        Int(servedSeconds(seconds).rounded(.up))
+        guard !seconds.isNaN else { return 0 }
+        let covered = servedSeconds(seconds).rounded(.up)
+        guard covered < Double(maxCoveredWholeSeconds) else { return maxCoveredWholeSeconds }
+        return covered > 0 ? Int(covered) : 0
     }
 
+    /// One day. Far above any real segment or cadence, far below where `Int` arithmetic on it overflows.
+    static let maxCoveredWholeSeconds = 86_400
+
     /// AE#454: the served `EXT-X-START:TIME-OFFSET` for a rejoin, or nil when this playlist cannot
     /// carry the placement.
     ///
diff --git a/Tests/AetherEngineTests/WholeSecondsCoveringTotalityTests.swift b/Tests/AetherEngineTests/WholeSecondsCoveringTotalityTests.swift
new file mode 100644
index 000000000..2c9a43f06
--- /dev/null
+++ b/Tests/AetherEngineTests/WholeSecondsCoveringTotalityTests.swift
@@ -0,0 +1,39 @@
+import Testing
+@testable import AetherEngine
+
+/// `wholeSecondsCovering` feeds `#EXT-X-TARGETDURATION` and the holdback. A duration from a broken source
+/// used to reach `Int(_:)` unchecked, which traps on infinity, NaN and anything beyond `Int.max`.
+@Suite("wholeSecondsCovering is total")
+struct WholeSecondsCoveringTotalityTests {
+
+    @Test("Finite durations keep their covering whole second", arguments: [
+        (2.0, 2), (2.0000000000000004, 2), (2.0005, 3), (0.2, 1), (6.5, 7),
+    ])
+    func finiteDurationsUnchanged(seconds: Double, expected: Int) {
+        #expect(LiveEdgePolicy.wholeSecondsCovering(seconds) == expected)
+    }
+
+    @Test("Hostile durations yield a bounded value instead of trapping", arguments: [
+        Double.infinity, 1e300, Double(Int.max), Double.greatestFiniteMagnitude,
+    ])
+    func unboundedSaturates(seconds: Double) {
+        #expect(LiveEdgePolicy.wholeSecondsCovering(seconds) == LiveEdgePolicy.maxCoveredWholeSeconds)
+    }
+
+    @Test("NaN, zero and negative durations cover nothing", arguments: [
+        Double.nan, -Double.infinity, -1e300, -3.0, 0.0,
+    ])
+    func emptyCoversNothing(seconds: Double) {
+        #expect(LiveEdgePolicy.wholeSecondsCovering(seconds) == 0)
+    }
+
+    @Test("The target duration survives a non-finite term, and the holdback stays computable")
+    func targetDurationSurvivesHostileTerms() {
+        let td = LiveEdgePolicy.targetDurationSeconds(
+            maxSegmentDuration: .infinity, cutTargetSeconds: .nan, cadenceFloorSeconds: .infinity)
+        #expect(td == LiveEdgePolicy.maxCoveredWholeSeconds)
+        #expect(LiveEdgePolicy.holdBackSeconds(targetDuration: td) == Double(3 * td))
+        #expect(LiveEdgePolicy.targetDurationSeconds(
+            maxSegmentDuration: 2.0, cutTargetSeconds: .nan, cadenceFloorSeconds: .nan) == 2)
+    }
+}

From b8ca97e7565dd8316cec1d9bc6f9697ada1fbd48 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 06:24:16 +0200
Subject: [PATCH 092/359] fix(routing): live AV1 High and Professional go to
 software too (audit HLS-5 follow-up)

HLS-5 routed AV1 High (4:4:4) and Professional (4:2:2, 12-bit) to the software host where the
hardware AV1 decoder only takes Main, but the format gate was skipped for every live load, so a
live AV1 High stream on a hardware-AV1 device still went native and rendered nothing. The gate now
runs on live for AV1 only. The software host already serves live AV1 wherever hardware AV1 is
missing, and H.264 / HEVC live keeps its verified native path.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 Sources/AetherEngine/AetherEngine.swift               |  8 +++++---
 Sources/AetherEngine/Decoder/VideoRoutingPolicy.swift |  9 +++++++++
 Tests/AetherEngineTests/VideoRoutingPolicyTests.swift | 10 ++++++++++
 docs/api.md                                           |  7 ++++---
 docs/cli.md                                           |  2 +-
 5 files changed, 29 insertions(+), 7 deletions(-)

diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index 0f57f358d..339f181c4 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -4528,11 +4528,13 @@ public final class AetherEngine: ObservableObject {
         // hardware-decode (H.264 High 4:2:2/4:4:4/High-10, HEVC Rext on Intel Macs / older Apple TV) reaches
         // readyToPlay then renders nothing on the native path. QuickTime plays it via its own software decoder;
         // there is no analogous fallback on the native route, so route it to the SoftwarePlaybackHost
-        // (libavcodec), which decodes these profiles. VOD only: forced-native live keeps its verified path, and
-        // broadcast H.264 / HEVC is HW-decodable. Apple Silicon HW-decodes these, so the probe keeps them native.
+        // (libavcodec), which decodes these profiles. VOD only for H.264 / HEVC: forced-native live keeps its
+        // verified path, and broadcast H.264 / HEVC is HW-decodable. AV1 is judged on live too (audit HLS-5).
+        // Apple Silicon HW-decodes these, so the probe keeps them native.
         // #176: DV Profile 5 is exempt inside the policy; the raw-hvcC probe misjudges the dvh1 route and the
         // software path decodes IPT-PQ-c2 with a green/purple cast, so P5 must stay native unconditionally.
-        if !useSoftwarePath, !options.isLive, probeOpened,
+        if !useSoftwarePath, probeOpened,
+           VideoRoutingPolicy.consultsUndecodableFormatGate(codecID: detectedCodecID, isLive: options.isLive),
            let vStream = probe.stream(at: probe.videoStreamIndex),
            let codecpar = vStream.pointee.codecpar {
             let dvProfile = Self.dvProfile(stream: vStream)
diff --git a/Sources/AetherEngine/Decoder/VideoRoutingPolicy.swift b/Sources/AetherEngine/Decoder/VideoRoutingPolicy.swift
index 064268275..a08acb2aa 100644
--- a/Sources/AetherEngine/Decoder/VideoRoutingPolicy.swift
+++ b/Sources/AetherEngine/Decoder/VideoRoutingPolicy.swift
@@ -125,6 +125,15 @@ enum VideoRoutingPolicy {
         }
     }
 
+    /// Whether a load consults `forcesSoftwareForUndecodableFormat` at all. H.264 / HEVC keep it VOD-only:
+    /// broadcast live is hardware-decodable and forced-native live keeps its verified path. AV1 is
+    /// consulted on live too (audit HLS-5 follow-up): a live AV1 High / Professional stream on a
+    /// hardware-AV1 device has no native picture, and live AV1 already goes to the software host
+    /// wherever hardware AV1 is missing entirely.
+    static func consultsUndecodableFormatGate(codecID: AVCodecID, isLive: Bool) -> Bool {
+        !isLive || codecID == AV_CODEC_ID_AV1
+    }
+
     /// Audit HLS-5: Apple's hardware AV1 decoders (A17 Pro, M3 and later) decode Main profile only,
     /// 8/10-bit 4:2:0. `av1Available` is a codec-level answer, so High (4:4:4) and Professional
     /// (4:2:2, 12-bit) reached AVPlayer and rendered nothing while dav1d would have played them.
diff --git a/Tests/AetherEngineTests/VideoRoutingPolicyTests.swift b/Tests/AetherEngineTests/VideoRoutingPolicyTests.swift
index 8c45a3d53..0f32d1b4b 100644
--- a/Tests/AetherEngineTests/VideoRoutingPolicyTests.swift
+++ b/Tests/AetherEngineTests/VideoRoutingPolicyTests.swift
@@ -167,6 +167,16 @@ struct VideoRoutingPolicyTests {
             codecID: AV_CODEC_ID_AV1, dvProfile: nil, canHardwareDecode: { true }))
     }
 
+    @Test("live consults the format gate for AV1 only; VOD consults it for every codec")
+    func liveConsultsFormatGateForAV1Only() {
+        #expect(VideoRoutingPolicy.consultsUndecodableFormatGate(codecID: AV_CODEC_ID_AV1, isLive: true))
+        #expect(!VideoRoutingPolicy.consultsUndecodableFormatGate(codecID: AV_CODEC_ID_H264, isLive: true))
+        #expect(!VideoRoutingPolicy.consultsUndecodableFormatGate(codecID: AV_CODEC_ID_HEVC, isLive: true))
+        for codec in [AV_CODEC_ID_AV1, AV_CODEC_ID_H264, AV_CODEC_ID_HEVC] {
+            #expect(VideoRoutingPolicy.consultsUndecodableFormatGate(codecID: codec, isLive: false))
+        }
+    }
+
     @Test("av1C seq_profile decides: Main fits the hardware decoder, High and Professional do not")
     func av1ProfileFromAV1C() {
         // marker|version 0x81, then seq_profile (3 bits) | seq_level_idx_0 (5 bits), flags, reserved.
diff --git a/docs/api.md b/docs/api.md
index 75e2c81e3..261da2391 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -227,8 +227,9 @@ try await player.reloadAtCurrentPosition { $0.preferredDecodePath = .software }
 the native path. That is the right default, and occasionally wrong. When VideoToolbox then cannot
 build a decoder for what arrives, the item reaches `readyToPlay` and renders nothing, and in-band
 parameter sets (`hev1` / `avc1` with an empty config record) are the class where the deciding
-evidence genuinely is not present at load time. A live load never reaches that gate at all: the
-capability check is VOD-only, so a live session keeps the native path with no classification step.
+evidence genuinely is not present at load time. A live H.264 / HEVC load never reaches that gate at
+all: for those codecs the capability check is VOD-only, so a live session keeps the native path with
+no classification step. Live AV1 is judged by profile like VOD (High and Professional go software).
 
 Detecting the symptom is a host's own job and is not hard (`AVPlayerItemVideoOutput.hasNewPixelBuffer`
 against `softwareHostFramesEnqueued`, both already exposed). The escape was the missing half. Before
@@ -941,7 +942,7 @@ All flags default to safe values; the table is the full set. Depth for the media
 | `keepDvh1TagWithoutDV` | false | Diagnostic lever: force dvh1 tags and a master playlist regardless of display capability. |
 | `forceDolbyVisionOnNonDVDisplay` | false | **Experimental (AE#455).** On a display with no Dolby Vision of its own, serve an HEVC Profile 8.1 source the way a Profile 5 source is served (`dvh1` sample entry, `dvcC` rewritten to profile 5 / compatibility 0, `CODECS="dvh1.05.LL"`), so AVPlayer composes the RPU itself instead of handing the panel the static-metadata HDR10 base layer. The bitstream is untouched; only the container's claim about it changes. Ignored on a display that does Dolby Vision, and Profile 8.1 only. See [formats.md](formats.md#dolby-vision-signaling) for what it buys and what it risks. |
 | `dolbyVisionHandling` | `.automatic` | A `DolbyVisionHandling`. `.baseLayerOnly` presents the HDR10 / HLG base layer of a Dolby Vision source and leaves the Dolby Vision out of the container on every display: plain `hvc1` / `av01` sample entry, `dvcC` stripped, no `SUPPLEMENTAL-CODECS`, HDR10 / HLG display criteria, `videoFormat` reads the base layer's format while `sourceVideoFormat` and `sourceDVProfile` keep saying what the file carries. The route a host offers as "Dolby Vision: off (HDR10)", for a source whose Dolby Vision is wrong and whose base layer is right: the reported shape is a remux carrying a Profile 7 RPU under a container record claiming Profile 5, where a player that believes the record decodes YCbCr as IPT and the picture comes out green / violet. Applies to HEVC Profile 7 / 8.1 / 8.4, AV1 Profile 10.1 / 10.4, and a Profile 5 (or AV1 10.0) record whose VUI declares a BT.2020 YCbCr PQ or HLG base; a Profile 5 whose VUI is unspecified carries IPT-PQ-c2, has no base layer to present, keeps its route, and the engine says so in the log. Takes precedence over `forceDolbyVisionOnNonDVDisplay`. A tuning field, correctable through `reloadAtCurrentPosition(applying:)`; a Profile 5 record the VUI contradicts also stops refusing the software path under it. See [formats.md](formats.md#dolby-vision-signaling). |
-| `preferredDecodePath` | `.automatic` | A `DecodePath`. `.software` serves this source through `SoftwarePlaybackHost` whatever the routing concluded, scoped to this session and costing the source nothing (seeks, the audio switch and the title switch all keep working). The escape for the formats `VTCapabilityProbe` deliberately cannot classify, and for live, which never reaches that gate at all. One-way: there is no `.native`. See [Overriding the decode path](#overriding-the-decode-path). |
+| `preferredDecodePath` | `.automatic` | A `DecodePath`. `.software` serves this source through `SoftwarePlaybackHost` whatever the routing concluded, scoped to this session and costing the source nothing (seeks, the audio switch and the title switch all keep working). The escape for the formats `VTCapabilityProbe` deliberately cannot classify, and for live H.264 / HEVC, which never reaches that gate at all. One-way: there is no `.native`. See [Overriding the decode path](#overriding-the-decode-path). |
 | `deinterlaceMode` | `.auto` | A `DeinterlaceMode` for the software path: the Metal / VideoToolbox graph with a CPU bwdif fallback, or `.software` to force the CPU path. |
 | `deinterlaceFieldRate` | `.field` | A `DeinterlaceFieldRate`: the hardware deinterlacer emits one frame per field (25i to 50p) or per frame. The software fallback is always frame rate, because doubling a CPU bwdif is the wrong trade and a fallback should not change cost class. |
 | `probesize`, `maxAnalyzeDuration` | nil | Caller-bounded open-time probe budget (defaults 50 MB / 60 s). They fail **open**: an over-tight budget loads with late-resolving tracks silently missing rather than throwing, so validate track presence if you tighten them. Do not pass `0` for `maxAnalyzeDuration`; FFmpeg maps it to a shorter heuristic. |
diff --git a/docs/cli.md b/docs/cli.md
index 361220b28..2919ebc06 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -244,7 +244,7 @@ live-only session took a rebuild that rejoins at the edge.
 
 `--reload-applying <key>=<value>` (repeatable, with one shared `--reload-applying-at <ms>`, default +20 s) corrects a `LoadOption` on the playing session through `reloadAtCurrentPosition(applying:)` (#460). Keys: `header.<Name>`, `audio-bridge`, `preferred-audio`, `decode-path`, `is-live`, which is there to drive the refusal, since a field that names the session has to be observably refused rather than observably ignored, and `autoplay`, which drives the third answer: a field the session owns, neither refused nor applied. Both outcomes print, which is the pair a host's recovery ladder has to tell apart. Pair it with a header-logging origin to read the correction from the other end: with `--header "X-Auth: stale"` at load and `--reload-applying header.X-Auth=fresh`, the origin log shows three requests carrying the stale value, then three carrying the fresh one, and the transport telemetry carries straight through the rebuild (`resumed at 10.90s from 9.90s`).
 
-`play --sw` sets `LoadOptions.preferredDecodePath = .software` (#461), the shipping per-session lever, rather than the process-global `setForceSoftwarePathForTesting` it drove before; that hook is still what `live --sw` and `dvr` use, since those harnesses run several sessions and want every one of them on the software host. `--reload-applying decode-path=software` is the same lever applied to a session that is already playing: on the 300 s H.264 fixture the run dispatches `codec=27 → native`, takes the correction at t=9.90 s and comes back `codec=27 → software` at 10.81 s, playing. On a live load the override reaches the same routing decision, which is the case with no alternative, since the #2 capability gate is VOD-only and a live session is never classified at all.
+`play --sw` sets `LoadOptions.preferredDecodePath = .software` (#461), the shipping per-session lever, rather than the process-global `setForceSoftwarePathForTesting` it drove before; that hook is still what `live --sw` and `dvr` use, since those harnesses run several sessions and want every one of them on the software host. `--reload-applying decode-path=software` is the same lever applied to a session that is already playing: on the 300 s H.264 fixture the run dispatches `codec=27 → native`, takes the correction at t=9.90 s and comes back `codec=27 → software` at 10.81 s, playing. On a live load the override reaches the same routing decision, which is the case with no alternative, since the #2 capability gate is VOD-only for H.264 / HEVC and such a live session is never classified at all.
 
 `--drop-audio` forces every audio pipeline to fail, so the AE#462 video-only drop is observable without a source this build has no decoder for: the loopback cascade skips both the stream-copy probe and the bridge, and `SoftwarePlaybackHost` refuses its decoder open. The run then prints `audio delivery=droppedNoPipeline pipeline=none`, which is the pair a host reads (the typed fact plus the human label), against `delivery=streamCopy` / `bridged` / `decoded` on the same source without the flag. It is loud in the log on purpose, in both the CLI line and the engine's own, because a forced classification read as a real one would be worse than no harness.
 

From c5d410121a08d1c1e645947689005138055e361f Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 06:30:07 +0200
Subject: [PATCH 093/359] fix(audio): bound the Atmos probe's input bytes below
 the demuxer

The probe sets AVDISCARD_ALL on every other stream, so a crafted file with one E-AC-3 packet
followed by gigabytes of another stream was read inside a single av_read_frame, where neither
maxBytes nor the packet fuse sees it. Same gap and same fix as the HDR10+ probe: an input byte
budget of 16 x maxBytes (at least 64 MiB, wider because the audio sits behind interleaved UHD
video), reported as .byteCap.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 .../AetherEngine/Audio/AtmosDetectionProbe.swift  | 15 +++++++++++++--
 .../AtmosDetectionOptionsTests.swift              |  8 ++++++++
 2 files changed, 21 insertions(+), 2 deletions(-)

diff --git a/Sources/AetherEngine/Audio/AtmosDetectionProbe.swift b/Sources/AetherEngine/Audio/AtmosDetectionProbe.swift
index 0697cc094..498712296 100644
--- a/Sources/AetherEngine/Audio/AtmosDetectionProbe.swift
+++ b/Sources/AetherEngine/Audio/AtmosDetectionProbe.swift
@@ -137,6 +137,15 @@ extension AetherEngine {
     /// Packet ceiling for the AVDISCARD_ALL fuse, saturating instead of trapping: `maxPackets` is a public
     /// option and `Int.max` is a plausible "no limit" value for a host to pass (`forwardBufferSegments`
     /// takes exactly that), which would overflow a plain multiply.
+    /// Source bytes the probe may consume across every stream. With the other streams at AVDISCARD_ALL
+    /// the demuxer reads and drops a video run inside one `av_read_frame`, where neither `maxBytes` nor
+    /// the packet fuse sees it. Wider than the HDR10+ budget because the audio sits behind interleaved
+    /// UHD video here: 16 x `maxBytes`, at least 64 MiB. Saturating: `maxBytes` is public.
+    nonisolated static func atmosInputByteBudget(maxBytes: Int64) -> Int64 {
+        let (product, overflowed) = max(0, maxBytes).multipliedReportingOverflow(by: 16)
+        return overflowed ? .max : max(product, 64 * 1024 * 1024)
+    }
+
     nonisolated static func atmosForeignPacketFuse(maxPackets: Int) -> Int {
         let (product, overflowed) = maxPackets.multipliedReportingOverflow(by: foreignPacketFuseMultiplier)
         return overflowed ? Int.max : product
@@ -228,6 +237,8 @@ extension AetherEngine {
         // exhaust the 8 MiB byte cap in well under a second of container data, and the probe returns
         // .byteCap having fed the decoder nothing -- reporting "not Atmos" for genuinely Atmos media.
         demuxer.discardAllStreamsExcept([targetIndex])
+        demuxer.beginInputByteBudget(Self.atmosInputByteBudget(maxBytes: options.maxBytes))
+        defer { demuxer.endInputByteBudget() }
 
         while true {
             let elapsed = Double(DispatchTime.now().uptimeNanoseconds - start.uptimeNanoseconds) / 1_000_000_000
@@ -242,10 +253,10 @@ extension AetherEngine {
             do {
                 packet = try demuxer.readPacket()
             } catch {
-                return stopped(.demuxError)
+                return stopped(demuxer.inputByteBudgetExhausted ? .byteCap : .demuxError)
             }
             guard let pkt = packet else {
-                return stopped(.demuxEOF)
+                return stopped(demuxer.inputByteBudgetExhausted ? .byteCap : .demuxEOF)
             }
             let afterRead = Double(DispatchTime.now().uptimeNanoseconds - start.uptimeNanoseconds) / 1_000_000_000
             if afterRead >= options.timeBudget {
diff --git a/Tests/AetherEngineTests/AtmosDetectionOptionsTests.swift b/Tests/AetherEngineTests/AtmosDetectionOptionsTests.swift
index 35ffecd2a..59089d978 100644
--- a/Tests/AetherEngineTests/AtmosDetectionOptionsTests.swift
+++ b/Tests/AetherEngineTests/AtmosDetectionOptionsTests.swift
@@ -75,6 +75,14 @@ struct AtmosDetectionOptionsTests {
         #expect(AetherEngine.atmosForeignPacketFuse(maxPackets: Int.max) == Int.max)
     }
 
+    @Test("the input byte budget covers interleaved UHD video and saturates instead of trapping")
+    func inputByteBudgetIsBoundedAndSaturates() {
+        #expect(AetherEngine.atmosInputByteBudget(maxBytes: 8 * 1024 * 1024) == 128 * 1024 * 1024)
+        #expect(AetherEngine.atmosInputByteBudget(maxBytes: 0) == 64 * 1024 * 1024)
+        #expect(AetherEngine.atmosInputByteBudget(maxBytes: -1) == 64 * 1024 * 1024)
+        #expect(AetherEngine.atmosInputByteBudget(maxBytes: .max) == .max)
+    }
+
     @Test("no default audio stream (-1) surfaces unchanged when no override is given")
     func noAudioStreamPropagatesAsNegativeOne() {
         let options = AtmosDetectionOptions()

From 5b3388df4446e61fd3eaec32e32aa65693efd474 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 06:30:07 +0200
Subject: [PATCH 094/359] docs(changelog): audit follow-ups

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 CHANGELOG.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4686324e5..d49701f8b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -43,9 +43,17 @@ the public-API contract.
   GitHub Actions to commit SHAs with Dependabot proposing updates, and aetherctl writes its debug
   files into a private per-run temporary directory instead of fixed names in `/tmp` (audit OPS-1,
   OPS-2, OPS-3).
+- **The HDR10+ and Atmos probes no longer read a crafted file to its end.** Blocks of the streams
+  they ignore are now counted against a byte budget below the demuxer, so one target packet followed
+  by gigabytes of another stream stops the probe instead of downloading it.
 
 ### Fixed
 
+- **Stopping playback during a restart after a stalled read aborts the replacement connection**,
+  instead of letting it finish its connect and stream probe after the session was gone.
+- **A non-finite segment or cadence duration can no longer crash the live playlist writer.**
+- **Live AV1 High and Professional streams play on hardware-AV1 devices**, through the software host
+  like VOD.
 - **A seek on the software path no longer lets one pre-seek frame wedge the picture.** A seek that
   landed while the decoder was retrying a full queue, or while the hardware decoder was preparing a
   packet, still let that packet through after the flush (audit DEC-1, DEC-4, AE#492).

From 996deb57709e2064545bce1fcc28ca990b4c6653 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 08:07:48 +0200
Subject: [PATCH 095/359] feat(native): a host can decline or observe the
 software-path rebuild (AE#629)

A host that re-plans a failing title with a ladder of its own had no say in the
AE#561 rung and no way to see it: the rebuild could not be declined, published only
a videoRoute change, and a load() still waiting on the startup it took over threw
the same bare CancellationError a host's own supersession throws. The reporter's
host read that as a failed load and stopped the session that had just come back.

- LoadOptions.escalatesToSoftwarePath (default true, correctable). false surfaces
  the native failure as .error, on the host-probe branches and on #93 revive
  exhaustion, where a declined rung would otherwise leave the session dead unsaid.
- softwarePathEscalations publishes SoftwarePathEscalationEvent when the rung is
  taken: the absorbed failure as PlaybackErrorInfo, the position, and whether a
  load() was waiting.
- A load() whose generation the rebuild ended follows the rebuild and returns
  with it, the way a #361 reroute keeps its wait. The takeover is claimed only by
  the rebuild's own teardown of the failed generation, so a rebuild refused before
  teardown, or beaten to it by a host stop(), leaves the load to the host. A
  rebuild whose session is already gone no longer runs at all.
- aetherctl play --no-sw-escalation, and an ESCALATION line on every run.

Measured on a 40 s HEVC fixture damaged at 20 s, AETHER_DISABLE_NAL_SANITIZER=1:
  default   ESCALATION at 12.00s absorbed=CoreMediaErrorDomain/-19602, rebuilt on
            the software path, plays to the end, VERDICT: OK
  declined  no escalation, .error -19602 at 12.00s, exit 2

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 CHANGELOG.md                                  |  12 ++
 .../AetherEngine/AetherEngine+Loading.swift   |  14 +-
 .../AetherEngine+ReloadWithOptions.swift      |   2 +-
 .../AetherEngine+SoftwarePathEscalation.swift |  67 +++++--
 Sources/AetherEngine/AetherEngine.swift       |  66 +++++++
 .../Native/SoftwarePathEscalation.swift       |  37 ++++
 Sources/AetherEngine/PlayerState.swift        |  17 +-
 Sources/aetherctl/PlaybackCmd.swift           |  19 +-
 Sources/aetherctl/main.swift                  |   5 +-
 .../SoftwarePathEscalationTests.swift         | 176 +++++++++++++++++-
 docs/api.md                                   |  18 +-
 docs/cli.md                                   |   2 +
 12 files changed, 412 insertions(+), 23 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d49701f8b..c37a9ba78 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,14 @@ the public-API contract.
 
 ## [Unreleased]
 
+### Added
+
+- **`LoadOptions.escalatesToSoftwarePath` (default `true`) lets a host decline the AE#561 rebuild**
+  onto the software path and get the native failure as `.error`, for hosts that re-plan a failing
+  title with a ladder of their own (AE#629).
+- **`softwarePathEscalations` publishes that rebuild when it is taken**, with the failure it
+  absorbed, where a host used to see only `videoRoute` change (AE#629).
+
 ### Security
 
 - **The origin relay no longer writes the media server's access token into its local URLs.** They
@@ -49,6 +57,10 @@ the public-API contract.
 
 ### Fixed
 
+- **A `load()` still waiting when the engine rebuilds its session on the software path now returns
+  with the rebuilt session** instead of throwing the `CancellationError` a host's own supersession
+  throws, which a host read as a failed load and answered by stopping the session that had just come
+  back (AE#629).
 - **Stopping playback during a restart after a stalled read aborts the replacement connection**,
   instead of letting it finish its connect and stream probe after the session was gone.
 - **A non-finite segment or cadence duration can no longer crash the live playlist writer.**
diff --git a/Sources/AetherEngine/AetherEngine+Loading.swift b/Sources/AetherEngine/AetherEngine+Loading.swift
index 40069dba8..81a4699c8 100644
--- a/Sources/AetherEngine/AetherEngine+Loading.swift
+++ b/Sources/AetherEngine/AetherEngine+Loading.swift
@@ -1613,6 +1613,15 @@ extension AetherEngine {
                             message: "item death at a frozen position, revive budget exhausted",
                             positionSeconds: position.isFinite ? max(0, position) : 0
                         )
+                        // AE#629: a host that declined the rung asked for exactly this failure. Left
+                        // unsaid, the session sits dead, which is what 7.8.1 did here too.
+                        guard self.loadedOptions.escalatesToSoftwarePath else {
+                            EngineLog.emit(
+                                "[AetherEngine] #629 the host declined the software-path rung; "
+                                + "surfacing the item death", category: .engine)
+                            self.publishError(Self.absorbedFailure(request))
+                            return
+                        }
                         Task { @MainActor [weak self] in await self?.escalateToSoftwarePath(request) }
                         return
                     }
@@ -1643,11 +1652,13 @@ extension AetherEngine {
         let escalationBudget = softwarePathEscalationBudget
         let escalationPreferred = loadedOptions.preferredDecodePath
         let escalationRemoteHLS = loadedOptions.nativeRemoteHLS
+        let escalationAllowed = loadedOptions.escalatesToSoftwarePath
         host.softwarePathAvailability = {
             SoftwarePathEscalation.Availability(
                 alreadyEscalated: escalationBudget.isSpent,
                 preferredDecodePath: escalationPreferred,
-                nativeRemoteHLS: escalationRemoteHLS
+                nativeRemoteHLS: escalationRemoteHLS,
+                hostAllowsEscalation: escalationAllowed
             )
         }
         host.$pendingSoftwarePathEscalation
@@ -2210,6 +2221,7 @@ extension AetherEngine {
         // It follows the TARGET route, not the previous one: a rebuild that flips to software renders
         // into its own layer, and a preserved host would leave AVKit bound to a stale player with
         // audio still flowing into the next load (the release `load()` does by hand on that branch).
+        claimSoftwarePathTakeover()   // AE#629
         stopInternal(resetDisplayCriteria: false, keepNativeHost: !targetSoftwarePath, keepCustomReader: true)
         EngineLog.emit("[AetherEngine] reload: stopInternal done (\(elapsedMs(since: reloadStart))ms)", category: .engine)
         let gen = loadGeneration
diff --git a/Sources/AetherEngine/AetherEngine+ReloadWithOptions.swift b/Sources/AetherEngine/AetherEngine+ReloadWithOptions.swift
index cbbe71472..e77f79875 100644
--- a/Sources/AetherEngine/AetherEngine+ReloadWithOptions.swift
+++ b/Sources/AetherEngine/AetherEngine+ReloadWithOptions.swift
@@ -400,6 +400,6 @@ enum SessionOptionCorrection {
         "declaredDurationSeconds", "probesize", "maxAnalyzeDuration", "preferredAudioLanguages",
         "preferredSubtitleLanguages", "externalSubtitles", "forwardBufferSegments", "autoplay",
         "audioDelaySeconds", "teletextPage", "deinterlaceMode", "deinterlaceFieldRate", "preferredDecodePath",
-        "isLiveRejoin", "subtitleSessionCarryover",
+        "escalatesToSoftwarePath", "isLiveRejoin", "subtitleSessionCarryover",
     ]
 }
diff --git a/Sources/AetherEngine/AetherEngine+SoftwarePathEscalation.swift b/Sources/AetherEngine/AetherEngine+SoftwarePathEscalation.swift
index a11c48ece..ce6abbc1b 100644
--- a/Sources/AetherEngine/AetherEngine+SoftwarePathEscalation.swift
+++ b/Sources/AetherEngine/AetherEngine+SoftwarePathEscalation.swift
@@ -24,22 +24,53 @@ extension AetherEngine {
             availability: SoftwarePathEscalation.Availability(
                 alreadyEscalated: softwarePathEscalationBudget.isSpent,
                 preferredDecodePath: loadedOptions.preferredDecodePath,
-                nativeRemoteHLS: loadedOptions.nativeRemoteHLS
+                nativeRemoteHLS: loadedOptions.nativeRemoteHLS,
+                hostAllowsEscalation: loadedOptions.escalatesToSoftwarePath
             )
         ) else { return }
         // The host's probe read mount-time options and the #93 rung does not consult it at all, so
         // the decision is made again here, against what the session is actually running on.
         guard softwarePathEscalationBudget.take() else { return }
 
+        let absorbed = Self.absorbedFailure(request)
+        // AE#629: a load() still waiting on this session's startup is about to be superseded by the
+        // rebuild's own. It follows the rebuild instead of unwinding, and the rebuild continues its
+        // #361 startup sequence rather than dropping the host's bar back to zero.
+        let supersededGeneration = loadGeneration
+        let duringStartup = waitingLoadGenerations.contains(supersededGeneration)
+
         EngineLog.emit(
             "[AetherEngine] #561 AVPlayer refused the media (\(request.domain)/\(request.code)) at "
             + "\(String(format: "%.2f", request.positionSeconds))s; rebuilding this session on the "
-            + "software path, which decodes it with libavcodec instead: \(request.message)",
+            + "software path, which decodes it with libavcodec instead"
+            + (duringStartup ? " (the waiting load follows it)" : "") + ": \(request.message)",
             category: .engine
         )
+        softwarePathEscalations.send(SoftwarePathEscalationEvent(
+            absorbedFailure: absorbed,
+            positionSeconds: request.positionSeconds,
+            duringStartup: duringStartup))
+
+        let rebuild = Task { @MainActor in
+            // Both are armed where nothing can run before the rebuild's teardown consumes them, and
+            // withdrawn after, for the paths that never reach one (a correction refused up front).
+            // The takeover is only CLAIMED by that teardown, and only if the session it ends is still
+            // the one that failed: a rebuild refused before it tore anything down, or a host stop()
+            // that got in first, must leave the waiting load to unwind as the host's own.
+            // The failure's session is already gone: rebuilding now would tear down its successor.
+            guard self.loadGeneration == supersededGeneration else { throw CancellationError() }
+            if duringStartup { self.continueStartupAcrossReroute() }
+            self.softwarePathTakeoverArm = supersededGeneration
+            defer {
+                self.abandonStartupContinuation()
+                self.softwarePathTakeoverArm = nil
+            }
+            _ = try await self.reloadAtCurrentPosition { $0.preferredDecodePath = .software }
+        }
+        softwarePathRebuild = rebuild
 
         do {
-            try await reloadAtCurrentPosition { $0.preferredDecodePath = .software }
+            try await rebuild.value
             EngineLog.emit(
                 "[AetherEngine] #561 rebuilt on the software path", category: .engine)
         } catch is CancellationError {
@@ -56,14 +87,28 @@ extension AetherEngine {
                 + "surfacing the original failure",
                 category: .engine
             )
-            publishError(
-                PlaybackErrorInfo(
-                    kind: .nativeItemFailed,
-                    message: request.message,
-                    underlyingDomain: request.domain.isEmpty ? nil : request.domain,
-                    underlyingCode: request.code == 0 ? nil : request.code
-                )
-            )
+            publishError(absorbed)
         }
     }
+
+    /// Called by a teardown about to end `loadGeneration`: when that teardown is the escalation's own
+    /// rebuild, a `load()` still waiting on the ended generation follows the rebuild (AE#629).
+    @MainActor
+    func claimSoftwarePathTakeover() {
+        guard let armed = softwarePathTakeoverArm else { return }
+        softwarePathTakeoverArm = nil
+        guard armed == loadGeneration, let rebuild = softwarePathRebuild else { return }
+        softwarePathTakeover = SoftwarePathEscalation.Takeover(
+            supersededGeneration: armed, rebuild: rebuild)
+    }
+
+    /// The failure an escalation takes instead of surfacing, in the shape it would have surfaced in.
+    nonisolated static func absorbedFailure(_ request: SoftwarePathEscalation.Request) -> PlaybackErrorInfo {
+        PlaybackErrorInfo(
+            kind: .nativeItemFailed,
+            message: request.message,
+            underlyingDomain: request.domain.isEmpty ? nil : request.domain,
+            underlyingCode: request.code == 0 ? nil : request.code
+        )
+    }
 }
diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index 633d996af..d0692cf1d 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -1365,6 +1365,13 @@ public final class AetherEngine: ObservableObject {
     /// fired and which of its own tracks matches. No replay; subscribe per session.
     public let systemCaptionRequest = PassthroughSubject<SystemCaptionRequest, Never>()
 
+    /// Fires when a native session AVPlayer refused on its merits is rebuilt on the software path
+    /// (AE#561), carrying the failure the rebuild absorbed. Without it a host sees only `videoRoute`
+    /// change, which a host re-planning failing titles itself cannot tell from a routing decision
+    /// (AE#629). `LoadOptions.escalatesToSoftwarePath = false` declines the rebuild instead. No
+    /// replay; subscribe per session.
+    public let softwarePathEscalations = PassthroughSubject<SoftwarePathEscalationEvent, Never>()
+
     // MARK: - Scrub thumbnails
 
     /// LRU (cap 2) of FrameExtractor contexts for cache-backed scrub thumbnails (live and
@@ -1916,6 +1923,10 @@ public final class AetherEngine: ObservableObject {
     /// the time `load()` runs they look identical.
     private var startupContinuesAcrossReroute = false
 
+    /// AE#629: generations of the `load()` calls a caller is still awaiting. The software-path
+    /// rebuild reads it to tell a startup it is taking over from a session that already returned.
+    var waitingLoadGenerations: Set<UInt64> = []
+
     /// Open a startup sequence for the load now beginning, and return its generation for the call
     /// sites that have to record checkpoints from detached work. A reroute continues the sequence
     /// already in flight instead of opening a new one.
@@ -1940,6 +1951,12 @@ public final class AetherEngine: ObservableObject {
         startupContinuesAcrossReroute = true
     }
 
+    /// Withdraw a continuation that no `load()` consumed, because the reroute was refused before it
+    /// reached one. Left set, it would fold the host's NEXT load into a startup that already ended.
+    func abandonStartupContinuation() {
+        startupContinuesAcrossReroute = false
+    }
+
     /// Record a checkpoint against a startup generation. `generation` defaults to the running one,
     /// which is what every main-actor call site wants; detached work and Combine sinks that can
     /// outlive their load pass the generation they captured, so a straggler cannot write into a
@@ -2319,6 +2336,14 @@ public final class AetherEngine: ObservableObject {
     /// the media. Replaced (not reset) on teardown, so a closure held by a dead host cannot spend
     /// the next session's.
     var softwarePathEscalationBudget = SoftwarePathEscalation.Budget()
+
+    /// AE#629: the escalation rebuild in flight or finished, kept so a `load()` whose startup it
+    /// superseded can wait for it instead of throwing. Matched by generation, so a stale one is inert.
+    var softwarePathTakeover: SoftwarePathEscalation.Takeover?
+    /// The escalation rebuild most recently started, and the generation it is armed to take over
+    /// until its teardown claims it (see `claimSoftwarePathTakeover`).
+    var softwarePathRebuild: Task<Void, Error>?
+    var softwarePathTakeoverArm: UInt64?
     /// #65 final rung, storm shape: on a frozen live playlist each stage-2 reload replays the tail,
     /// re-stalls within seconds, and the fresh stall SUPERSEDES the ladder task before its
     /// post-reload rung can run, so the reload cycle alone would loop forever. This gate persists
@@ -3649,6 +3674,43 @@ public final class AetherEngine: ObservableObject {
         options: LoadOptions = .init(),
         audioSourceStreamIndex: Int32? = nil,
         discTitleID: Int? = nil
+    ) async throws -> SourceProbe? {
+        let attempt = LoadAttempt()
+        defer { if let gen = attempt.generation { waitingLoadGenerations.remove(gen) } }
+        do {
+            return try await loadSession(
+                source: source, startPosition: startPosition, options: options,
+                audioSourceStreamIndex: audioSourceStreamIndex, discTitleID: discTitleID,
+                attempt: attempt)
+        } catch is CancellationError {
+            // AE#629: the engine took this startup over itself (the AE#561 rebuild), so the caller is
+            // still waiting for the same thing and gets it, the way a #361 reroute keeps its wait. A
+            // load the HOST superseded matches no takeover and unwinds as before.
+            guard let generation = attempt.generation,
+                  let takeover = softwarePathTakeover,
+                  takeover.supersededGeneration == generation else { throw CancellationError() }
+            EngineLog.emit(
+                "[AetherEngine] #629 load (gen \(generation)) follows the software-path rebuild "
+                + "instead of unwinding", category: .engine)
+            try await takeover.rebuild.value
+            return attempt.probe
+        }
+    }
+
+    /// What `loadSession` tells the public `load` about itself: the generation it ran under and the
+    /// probe it assembled, which a load followed across a takeover still returns (AE#629).
+    final class LoadAttempt {
+        var generation: UInt64?
+        var probe: SourceProbe?
+    }
+
+    private func loadSession(
+        source: MediaSource,
+        startPosition: Double?,
+        options: LoadOptions,
+        audioSourceStreamIndex: Int32?,
+        discTitleID: Int?,
+        attempt: LoadAttempt
     ) async throws -> SourceProbe? {
         var source = source
         var options = options
@@ -3697,6 +3759,7 @@ public final class AetherEngine: ObservableObject {
         // here bounces the panel through SDR before apply() re-negotiates the same mode on video->video
         // reloads. Sessions that never reach apply() clear a stale criteria via loadDisplayCriteriaAction
         // (audio-only fast path, suppressed hosts); a load() that throws before routing leaves it for stop().
+        claimSoftwarePathTakeover()   // AE#629
         stopInternal(resetDisplayCriteria: false, keepNativeHost: preserveNativeHost, keepCurrentItem: handOverInPlace)
         if mediaServicesWereReset { dropAudioPlayerHostAfterMediaServicesReset() }
         // #35/#93: a genuinely new item has not rendered yet; re-arm the cold-startup wedge suspension.
@@ -3712,6 +3775,8 @@ public final class AetherEngine: ObservableObject {
         DiscReader.clearCache()
         // Capture generation; every suspension point re-checks for supersession.
         let gen = loadGeneration
+        attempt.generation = gen
+        waitingLoadGenerations.insert(gen)
         // #361: open the host-visible startup sequence. A reroute re-entering load() continues the
         // one already running rather than starting a second.
         let startupGen = beginStartupProgress()
@@ -4196,6 +4261,7 @@ public final class AetherEngine: ObservableObject {
         let sourceProbe: SourceProbe? = probeOpened
             ? Self.makeSourceProbe(demuxer: probe, displayURL: url)
             : nil
+        attempt.probe = sourceProbe
         // Resolve the initial audio track: an explicit host override wins, else the ordered language
         // preference (#72) resolved from this single probe. selectedAudio is nil when neither applies,
         // so the session keeps its own default pick (empty preferences + no override is a behavioural
diff --git a/Sources/AetherEngine/Native/SoftwarePathEscalation.swift b/Sources/AetherEngine/Native/SoftwarePathEscalation.swift
index 241e7a2c8..586a76f70 100644
--- a/Sources/AetherEngine/Native/SoftwarePathEscalation.swift
+++ b/Sources/AetherEngine/Native/SoftwarePathEscalation.swift
@@ -1,5 +1,31 @@
 import Foundation
 
+/// A native session the engine rebuilt on the software path because AVPlayer refused its media
+/// (AE#561), published through `AetherEngine.softwarePathEscalations` the moment the rebuild is
+/// taken (AE#629).
+///
+/// The failure it carries is the one the engine absorbed instead of surfacing, so a host with a
+/// fallback ladder of its own can count it, log it, or decline the next one through
+/// `LoadOptions.escalatesToSoftwarePath`. If the rebuild then fails, that failure arrives as `.error`
+/// the usual way; if it succeeds, `videoRoute` moves to `.software`.
+public struct SoftwarePathEscalationEvent: Sendable, Equatable {
+    /// The failure the rebuild absorbed. `kind` is `.nativeItemFailed`; a failure the engine
+    /// inferred from a frozen position across its own revives carries no underlying code.
+    public let absorbedFailure: PlaybackErrorInfo
+    /// Where the session was when the native path gave up, in seconds.
+    public let positionSeconds: Double
+    /// True when a `load()` was still waiting on this session's startup. That `load()` keeps waiting
+    /// across the rebuild and returns when the rebuilt session is up, instead of throwing the
+    /// `CancellationError` a load superseded by the host would throw.
+    public let duringStartup: Bool
+
+    public init(absorbedFailure: PlaybackErrorInfo, positionSeconds: Double, duringStartup: Bool) {
+        self.absorbedFailure = absorbedFailure
+        self.positionSeconds = positionSeconds
+        self.duringStartup = duringStartup
+    }
+}
+
 /// The last rung under a native session AVPlayer will not play: hand the source to the engine's own
 /// decoder instead of ending the session (AE#561).
 ///
@@ -56,6 +82,15 @@ enum SoftwarePathEscalation {
         let preferredDecodePath: DecodePath
         /// The remote-HLS bypass, where the engine decodes nothing at all.
         let nativeRemoteHLS: Bool
+        /// `LoadOptions.escalatesToSoftwarePath`: false when the host re-plans a failing title itself.
+        var hostAllowsEscalation: Bool = true
+    }
+
+    /// The rebuild a still-waiting `load()` hands its wait to (AE#629). `supersededGeneration` is the
+    /// load generation the rebuild's teardown ended, so only the load that owned it can follow.
+    struct Takeover {
+        let supersededGeneration: UInt64
+        let rebuild: Task<Void, Error>
     }
 
     /// The domain of a media failure, i.e. AVFoundation could not make sense of what it was served.
@@ -70,6 +105,8 @@ enum SoftwarePathEscalation {
     /// which is never a reason to swallow a failure.
     static func shouldEscalate(errorDomain: String?, availability: Availability?) -> Bool {
         guard let availability, !availability.alreadyEscalated else { return false }
+        // AE#629: a host with its own fallback ladder needs the failure, not a rescue it cannot see.
+        guard availability.hostAllowsEscalation else { return false }
         // Already there, or the host asked for a path this cannot improve on.
         guard availability.preferredDecodePath == .automatic else { return false }
         // The bypass has no local muxer and decodes nothing here, so #461 ignores the option anyway.
diff --git a/Sources/AetherEngine/PlayerState.swift b/Sources/AetherEngine/PlayerState.swift
index 97f87772b..7f15c1367 100644
--- a/Sources/AetherEngine/PlayerState.swift
+++ b/Sources/AetherEngine/PlayerState.swift
@@ -841,6 +841,19 @@ public struct LoadOptions: Sendable, Equatable {
     /// is demuxed), so this has nothing to act on there and the engine says so in the log.
     public var preferredDecodePath: DecodePath = .automatic
 
+    /// Whether a native session AVPlayer refuses on its merits may be rebuilt on the software path
+    /// (AE#561). Default `true`.
+    ///
+    /// When AVPlayer fails the item with a verdict on the MEDIA (`CoreMediaErrorDomain`), every native
+    /// recovery answers the same bytes again, so the engine spends one rebuild per session on
+    /// `SoftwarePlaybackHost`, whose libavcodec skips the frame Apple's parser refused. `false`
+    /// declines that rung: the failure surfaces as `.error` with `PlaybackErrorKind.nativeItemFailed`,
+    /// the way it did before 7.9.0, for a host that re-plans a failing title with a ladder of its own
+    /// (AE#629). Either way `softwarePathEscalations` says when the rung is taken.
+    ///
+    /// A tuning field: correctable on a playing session through `reloadAtCurrentPosition(applying:)`.
+    public var escalatesToSoftwarePath: Bool = true
+
     /// ENGINE-INTERNAL: marks this load as a live REJOIN (`reloadAtCurrentPosition`). Not settable from the public initializer. When true, the native load path skips its explicit initial seek so AVPlayer picks edge-minus-holdback (see `LiveReloadPolicy`); without it the reloaded item can wedge in `waitingToPlay` against Jellyfin's re-served backlog. Meaningful only when `isLive` is true.
     var isLiveRejoin: Bool = false
 
@@ -892,7 +905,8 @@ public struct LoadOptions: Sendable, Equatable {
         audioDelaySeconds: Double = 0,
         deinterlaceMode: DeinterlaceMode = .auto,
         deinterlaceFieldRate: DeinterlaceFieldRate = .field,
-        preferredDecodePath: DecodePath = .automatic
+        preferredDecodePath: DecodePath = .automatic,
+        escalatesToSoftwarePath: Bool = true
     ) {
         self.omitCriteriaColorExtensions = omitCriteriaColorExtensions
         self.suppressDisplayCriteria = suppressDisplayCriteria
@@ -935,6 +949,7 @@ public struct LoadOptions: Sendable, Equatable {
         self.deinterlaceMode = deinterlaceMode
         self.deinterlaceFieldRate = deinterlaceFieldRate
         self.preferredDecodePath = preferredDecodePath
+        self.escalatesToSoftwarePath = escalatesToSoftwarePath
     }
 }
 
diff --git a/Sources/aetherctl/PlaybackCmd.swift b/Sources/aetherctl/PlaybackCmd.swift
index df88a06e9..46559b532 100644
--- a/Sources/aetherctl/PlaybackCmd.swift
+++ b/Sources/aetherctl/PlaybackCmd.swift
@@ -98,7 +98,7 @@ enum LoadOptionChange {
 /// and optionally activate an embedded subtitle track (`--subs <codec-or-lang>`)
 /// and log every overlay cue that arrives. Repro harness for "loads but never
 /// plays" reports and for live teletext end-to-end validation (#107).
-func runPlay(url: URL, seconds: Double, live: Bool, nativeHLS: Bool = false, liveIngest: Bool = false, fastZap: Bool = false, liveStartImmediately: Bool = true, dvrWindow: Double?, subsPick: String?, hostCalls: [String], audioStats: Bool = false, seekEvery: Double? = nil, seekPattern: [Double] = [], seekCount: Int? = nil, startPosition: Double? = nil, mallocCensus: Bool = false, forceSoftware: Bool = false,
+func runPlay(url: URL, seconds: Double, live: Bool, nativeHLS: Bool = false, liveIngest: Bool = false, fastZap: Bool = false, liveStartImmediately: Bool = true, dvrWindow: Double?, subsPick: String?, hostCalls: [String], audioStats: Bool = false, seekEvery: Double? = nil, seekPattern: [Double] = [], seekCount: Int? = nil, startPosition: Double? = nil, mallocCensus: Bool = false, forceSoftware: Bool = false, softwareEscalation: Bool = true,
                     censusThresholdMB: Int? = nil, censusHz: Double? = nil, frameTimes: Bool = false, presentTimes: Bool = false, pictureProbe: Bool = false, pictureOrigin: Double = 0,
                     sidecars: [ExternalSubtitleTrack] = [], audioSwitch: AudioSwitchRequest? = nil,
                     teletextPage: Int? = nil, teletextSwitch: TeletextPageSwitchRequest? = nil,
@@ -122,6 +122,7 @@ func runPlay(url: URL, seconds: Double, live: Bool, nativeHLS: Bool = false, liv
     // rather than the process-global test hook it used before. The hook forces every session on the
     // engine, so it could never exercise the thing a host actually calls.
     if forceSoftware { print("[aetherctl] decode path: preferredDecodePath=.software (#461)") }
+    if !softwareEscalation { print("[aetherctl] escalatesToSoftwarePath=false (AE#629)") }
     if let audioSwitch {
         print("[aetherctl] audio switch: selectAudioTrack(index: \(audioSwitch.index)) "
               + "\(audioSwitch.delayMilliseconds) ms after the load returns")
@@ -131,7 +132,7 @@ func runPlay(url: URL, seconds: Double, live: Bool, nativeHLS: Bool = false, liv
     // CFRunLoopRun, not a blocking semaphore: AetherEngine is @MainActor, so parking the main thread would deadlock the executor.
     let box = UncheckedBox<Int32?>(nil)
     Task { @MainActor in
-        box.value = await playSmokeTest(url: url, seconds: seconds, live: live, forceSoftware: forceSoftware, nativeHLS: nativeHLS, liveIngest: liveIngest, fastZap: fastZap, liveStartImmediately: liveStartImmediately, dvrWindow: dvrWindow, subsPick: subsPick, hostCalls: hostCalls, audioStats: audioStats, seekEvery: seekEvery, seekPattern: seekPattern, seekCount: seekCount, startPosition: startPosition, frameTimes: frameTimes, presentTimes: presentTimes, pictureProbe: pictureProbe, pictureOrigin: pictureOrigin, sidecars: sidecars, audioSwitch: audioSwitch, teletextPage: teletextPage, teletextSwitch: teletextSwitch, audioDelayMs: audioDelayMs, audioDelaySwitches: audioDelaySwitches, pausedMount: pausedMount, optionCorrection: optionCorrection, sequentialOrigin: sequentialOrigin, maxConcurrentRequests: maxConcurrentRequests, heldConnection: heldConnection, declaredDuration: declaredDuration, httpHeaders: httpHeaders, deinterlaceFieldRate: deinterlaceFieldRate, assertDolbyVision: assertDolbyVision, preserveASSMarkup: preserveASSMarkup, dolbyVisionHandling: dolbyVisionHandling, record: record)
+        box.value = await playSmokeTest(url: url, seconds: seconds, live: live, forceSoftware: forceSoftware, softwareEscalation: softwareEscalation, nativeHLS: nativeHLS, liveIngest: liveIngest, fastZap: fastZap, liveStartImmediately: liveStartImmediately, dvrWindow: dvrWindow, subsPick: subsPick, hostCalls: hostCalls, audioStats: audioStats, seekEvery: seekEvery, seekPattern: seekPattern, seekCount: seekCount, startPosition: startPosition, frameTimes: frameTimes, presentTimes: presentTimes, pictureProbe: pictureProbe, pictureOrigin: pictureOrigin, sidecars: sidecars, audioSwitch: audioSwitch, teletextPage: teletextPage, teletextSwitch: teletextSwitch, audioDelayMs: audioDelayMs, audioDelaySwitches: audioDelaySwitches, pausedMount: pausedMount, optionCorrection: optionCorrection, sequentialOrigin: sequentialOrigin, maxConcurrentRequests: maxConcurrentRequests, heldConnection: heldConnection, declaredDuration: declaredDuration, httpHeaders: httpHeaders, deinterlaceFieldRate: deinterlaceFieldRate, assertDolbyVision: assertDolbyVision, preserveASSMarkup: preserveASSMarkup, dolbyVisionHandling: dolbyVisionHandling, record: record)
         CFRunLoopStop(CFRunLoopGetMain())
     }
     CFRunLoopRun()
@@ -450,7 +451,7 @@ private func seekIntentDrill(
 }
 
 @MainActor
-private func playSmokeTest(url: URL, seconds: Double, live: Bool, forceSoftware: Bool = false, nativeHLS: Bool = false, liveIngest: Bool = false, fastZap: Bool = false, liveStartImmediately: Bool = true, dvrWindow: Double?, subsPick: String?, hostCalls: [String], audioStats: Bool, seekEvery: Double? = nil, seekPattern: [Double] = [], seekCount: Int? = nil, startPosition: Double? = nil, frameTimes: Bool = false, presentTimes: Bool = false, pictureProbe: Bool = false, pictureOrigin: Double = 0, sidecars: [ExternalSubtitleTrack] = [], audioSwitch: AudioSwitchRequest? = nil, teletextPage: Int? = nil, teletextSwitch: TeletextPageSwitchRequest? = nil, audioDelayMs: Int = 0, audioDelaySwitches: [AudioDelaySwitchRequest] = [], pausedMount: Bool = false, optionCorrection: LoadOptionCorrectionRequest? = nil, sequentialOrigin: Bool = false, maxConcurrentRequests: Int? = nil, heldConnection: Bool = false, declaredDuration: Double? = nil, httpHeaders: [String: String] = [:], deinterlaceFieldRate: DeinterlaceFieldRate = .field, assertDolbyVision: Bool = false, preserveASSMarkup: Bool = false, dolbyVisionHandling: DolbyVisionHandling = .automatic, record: URL? = nil) async -> Int32 {
+private func playSmokeTest(url: URL, seconds: Double, live: Bool, forceSoftware: Bool = false, softwareEscalation: Bool = true, nativeHLS: Bool = false, liveIngest: Bool = false, fastZap: Bool = false, liveStartImmediately: Bool = true, dvrWindow: Double?, subsPick: String?, hostCalls: [String], audioStats: Bool, seekEvery: Double? = nil, seekPattern: [Double] = [], seekCount: Int? = nil, startPosition: Double? = nil, frameTimes: Bool = false, presentTimes: Bool = false, pictureProbe: Bool = false, pictureOrigin: Double = 0, sidecars: [ExternalSubtitleTrack] = [], audioSwitch: AudioSwitchRequest? = nil, teletextPage: Int? = nil, teletextSwitch: TeletextPageSwitchRequest? = nil, audioDelayMs: Int = 0, audioDelaySwitches: [AudioDelaySwitchRequest] = [], pausedMount: Bool = false, optionCorrection: LoadOptionCorrectionRequest? = nil, sequentialOrigin: Bool = false, maxConcurrentRequests: Int? = nil, heldConnection: Bool = false, declaredDuration: Double? = nil, httpHeaders: [String: String] = [:], deinterlaceFieldRate: DeinterlaceFieldRate = .field, assertDolbyVision: Bool = false, preserveASSMarkup: Bool = false, dolbyVisionHandling: DolbyVisionHandling = .automatic, record: URL? = nil) async -> Int32 {
     let engine: AetherEngine
     do {
         engine = try AetherEngine()
@@ -567,8 +568,18 @@ private func playSmokeTest(url: URL, seconds: Double, live: Bool, forceSoftware:
         // separates "the deinterlaced path loses frames" from "it emits 2.5x as many of them" could
         // only be asked of a reporter. send_frame halves the output rate and changes nothing else.
         deinterlaceFieldRate: deinterlaceFieldRate,
-        preferredDecodePath: forceSoftware ? .software : .automatic
+        preferredDecodePath: forceSoftware ? .software : .automatic,
+        escalatesToSoftwarePath: softwareEscalation
     )
+    // AE#629: the rescue a host used to see only as a route change.
+    let escalationSub = engine.softwarePathEscalations.sink { event in
+        let failure = event.absorbedFailure
+        print(String(format: "ESCALATION at %.2fs duringStartup=%@ absorbed=%@/%@ %@",
+                     event.positionSeconds, String(event.duringStartup),
+                     failure.underlyingDomain ?? "-", failure.underlyingCode.map(String.init) ?? "-",
+                     failure.kind.rawValue))
+    }
+    defer { escalationSub.cancel() }
     // #311: installed BEFORE the load on purpose. The engine holds it and arms the host it builds,
     // which is the documented usage and the part a host would otherwise have to re-do per load.
     let frameProbe = frameTimes ? FrameTimeProbe() : nil
diff --git a/Sources/aetherctl/main.swift b/Sources/aetherctl/main.swift
index 01af9dd09..60247ece8 100644
--- a/Sources/aetherctl/main.swift
+++ b/Sources/aetherctl/main.swift
@@ -70,7 +70,7 @@ func printUsage() {
       aetherctl serve [--no-dv] [--force-dv] [--dv-base-layer] [--start-position S] <url>
       aetherctl validate [--no-dv] [--force-dv] [--dv-base-layer] <url>
       aetherctl swdecode [--frames N] <url>
-      aetherctl play [--seconds N] [--live] [--fast-zap] [--live-start-immediately] [--dvr-window N] [--subs <codec-or-lang>]
+      aetherctl play [--seconds N] [--live] [--no-sw-escalation] [--fast-zap] [--live-start-immediately] [--dvr-window N] [--subs <codec-or-lang>]
                  [--assert-dv] [--dv-base-layer]
                  [--start-position S] [--switch-audio <index>[@ms]]
                  [--teletext-page N] [--switch-teletext-page <page|auto>[@ms]]
@@ -635,6 +635,7 @@ if first == "play" {
     let seekCount = takeIntFlag("--seek-count", from: &rest)
     let mallocCensus = takeFlag("--malloc-census", from: &rest)
     let playForceSW = takeFlag("--sw", from: &rest)
+    let playSoftwareEscalation = !takeFlag("--no-sw-escalation", from: &rest)
     // AE#493: `LoadOptions.panelPresentsDolbyVision`, the host assertion. macOS has no per-mode display
     // capability API, so DV is unclaimable from inside the engine and a Mac run routes every DV source
     // as its HDR10 base layer until the host says otherwise.
@@ -873,7 +874,7 @@ if first == "play" {
         }
         done.wait()
     }
-    exit(runPlay(url: parseSourceURL(urlArg), seconds: seconds, live: live, nativeHLS: nativeHLS, liveIngest: liveIngest, fastZap: playFastZap, liveStartImmediately: liveStartImmediately, dvrWindow: dvrWindow, subsPick: subsPick, hostCalls: hostCalls, audioStats: audioStats, seekEvery: seekEvery, seekPattern: seekPattern, seekCount: seekCount, startPosition: playStartPosition, mallocCensus: mallocCensus, forceSoftware: playForceSW,
+    exit(runPlay(url: parseSourceURL(urlArg), seconds: seconds, live: live, nativeHLS: nativeHLS, liveIngest: liveIngest, fastZap: playFastZap, liveStartImmediately: liveStartImmediately, dvrWindow: dvrWindow, subsPick: subsPick, hostCalls: hostCalls, audioStats: audioStats, seekEvery: seekEvery, seekPattern: seekPattern, seekCount: seekCount, startPosition: playStartPosition, mallocCensus: mallocCensus, forceSoftware: playForceSW, softwareEscalation: playSoftwareEscalation,
                  censusThresholdMB: censusThresholdMB, censusHz: censusHz, frameTimes: frameTimes, presentTimes: presentTimes, pictureProbe: pictureProbe, pictureOrigin: pictureOrigin, sidecars: sidecars,
                  audioSwitch: audioSwitch,
                  teletextPage: teletextPage, teletextSwitch: teletextSwitch,
diff --git a/Tests/AetherEngineTests/SoftwarePathEscalationTests.swift b/Tests/AetherEngineTests/SoftwarePathEscalationTests.swift
index 9c154fcd5..706057ed5 100644
--- a/Tests/AetherEngineTests/SoftwarePathEscalationTests.swift
+++ b/Tests/AetherEngineTests/SoftwarePathEscalationTests.swift
@@ -13,12 +13,18 @@ struct SoftwarePathEscalationTests {
     private static func availability(
         escalated: Bool = false,
         path: DecodePath = .automatic,
-        remoteHLS: Bool = false
+        remoteHLS: Bool = false,
+        hostAllows: Bool = true
     ) -> SoftwarePathEscalation.Availability {
         SoftwarePathEscalation.Availability(
-            alreadyEscalated: escalated, preferredDecodePath: path, nativeRemoteHLS: remoteHLS)
+            alreadyEscalated: escalated, preferredDecodePath: path, nativeRemoteHLS: remoteHLS,
+            hostAllowsEscalation: hostAllows)
     }
 
+    private static let mediaFailure = SoftwarePathEscalation.Request(
+        domain: SoftwarePathEscalation.mediaErrorDomain, code: -19602,
+        message: "item death at a frozen position", positionSeconds: 12)
+
     @Test("A media failure on a fresh native session is escalated")
     func mediaFailureEscalates() {
         #expect(SoftwarePathEscalation.shouldEscalate(
@@ -97,4 +103,170 @@ struct SoftwarePathEscalationTests {
         #expect(engine.state == .idle)
         #expect(engine.errorInfo == nil)
     }
+
+    // MARK: - AE#629: a host with its own fallback ladder
+
+    /// The switch is the ask's first form: a declining host gets the failure its ladder reads.
+    @Test("A host that declines the rung is never escalated")
+    func hostDeclines() {
+        #expect(!SoftwarePathEscalation.shouldEscalate(
+            errorDomain: "CoreMediaErrorDomain", availability: Self.availability(hostAllows: false)))
+    }
+
+    @Test("The rung is on by default and correctable on a playing session")
+    func defaultAndCorrectable() {
+        #expect(LoadOptions().escalatesToSoftwarePath)
+        var proposed = LoadOptions()
+        proposed.escalatesToSoftwarePath = false
+        #expect(SessionOptionCorrection.refusedFields(from: LoadOptions(), to: proposed).isEmpty)
+        #expect(SessionOptionCorrection.changedFields(from: LoadOptions(), to: proposed)
+            == ["escalatesToSoftwarePath"])
+    }
+
+    @Test("A declined rung spends nothing and says nothing")
+    @MainActor
+    func declinedEngineSideSpendsNothing() async throws {
+        let engine = try AetherEngine()
+        engine.applySessionOptionCorrection(LoadOptions(escalatesToSoftwarePath: false))
+        var events: [SoftwarePathEscalationEvent] = []
+        let sub = engine.softwarePathEscalations.sink { events.append($0) }
+        defer { sub.cancel() }
+
+        await engine.escalateToSoftwarePath(Self.mediaFailure)
+
+        #expect(events.isEmpty)
+        #expect(!engine.softwarePathEscalationBudget.isSpent)
+        #expect(engine.softwarePathTakeover == nil)
+    }
+
+    /// The ask's second form. Measured by the reporter: a host that heard only `videoRoute` could not
+    /// tell the rescue from a routing decision.
+    @Test("A taken rung publishes the failure it absorbed", .timeLimit(.minutes(2)))
+    @MainActor
+    func takenRungIsPublished() async throws {
+        let origin = try ProbeHTTPTestOrigin(data: ProbeTestFixtures.hdr10Plus(), stage: .headers)
+        defer { origin.stop() }
+        let engine = try AetherEngine()
+        engine.loadedURL = try #require(URL(string: "http://127.0.0.1:\(origin.port)/source.mkv"))
+        var events: [SoftwarePathEscalationEvent] = []
+        let sub = engine.softwarePathEscalations.sink { events.append($0) }
+        defer { sub.cancel() }
+
+        let escalation = Task { @MainActor in await engine.escalateToSoftwarePath(Self.mediaFailure) }
+        try await waitFor { origin.blocked.entered }
+        engine.stop()
+        origin.stop()
+        await escalation.value
+
+        #expect(events == [SoftwarePathEscalationEvent(
+            absorbedFailure: PlaybackErrorInfo(
+                kind: .nativeItemFailed, message: "item death at a frozen position",
+                underlyingDomain: "CoreMediaErrorDomain", underlyingCode: -19602),
+            positionSeconds: 12,
+            duringStartup: false)])
+    }
+
+    /// A custom source whose first read parks until the engine cancels it: a load that cannot finish
+    /// and cannot time out, so the takeover is decided against a startup that is really in flight.
+    final class ParkedReader: IOReader, @unchecked Sendable {
+        private let condition = NSCondition()
+        private var released = false
+        private var arrivals = 0
+        var entered: Bool { condition.withLock { arrivals > 0 } }
+
+        func read(_ buffer: UnsafeMutablePointer<UInt8>?, size: Int32) -> Int32 {
+            condition.lock(); defer { condition.unlock() }
+            arrivals += 1
+            while !released { condition.wait() }
+            return -1
+        }
+        func seek(offset: Int64, whence: Int32) -> Int64 { whence == 65536 ? 1 << 20 : offset }
+        func close() { cancel() }
+        func cancel() { condition.withLock { released = true; condition.broadcast() } }
+        func makeIndependentReader() -> IOReader? { nil }
+        var discImageProbeEnabled: Bool { false }
+    }
+
+    /// The ask's third form. A load() the rebuild superseded used to throw the same
+    /// CancellationError as a load the host superseded itself, and the reporter's host read it as a
+    /// failed load and stopped the rebuilt session. It now follows the rebuild and returns when the
+    /// rebuild does; before this change the same load threw at once.
+    @Test("A load followed across a takeover returns when the rebuild comes back", .timeLimit(.minutes(2)))
+    @MainActor
+    func followedLoadReturnsOnRebuild() async throws {
+        let engine = try AetherEngine()
+        let reader = ParkedReader()
+        let (rebuildGate, finishRebuild) = AsyncStream<Void>.makeStream()
+
+        let hostLoad = Task { @MainActor in
+            try await engine.load(source: .custom(reader, formatHint: "matroska"),
+                                  options: LoadOptions(suppressDisplayCriteria: true))
+        }
+        try await waitFor { reader.entered }
+        let generation = engine.loadGeneration
+        #expect(engine.waitingLoadGenerations.contains(generation))
+
+        // What the escalation's rebuild does at its teardown: arm, then claim for the live generation.
+        engine.softwarePathRebuild = Task { for await _ in rebuildGate {} }
+        engine.softwarePathTakeoverArm = generation
+        engine.claimSoftwarePathTakeover()
+        engine.stop()
+
+        // The load has unwound its own session and is parked on the rebuild, not finished.
+        try await waitFor { engine.loadGeneration != generation }
+        try await Task.sleep(for: .milliseconds(200))
+        #expect(engine.waitingLoadGenerations.contains(generation))
+
+        finishRebuild.finish()
+        _ = try await hostLoad.value
+        #expect(engine.waitingLoadGenerations.isEmpty)
+    }
+
+    /// The other half of the same contract: a rebuild refused before it tore anything down never
+    /// owned the session, so the waiting load is still the host's and a host stop() ends it with the
+    /// CancellationError it always threw. Here the refusal is `customSourceNotSeekable`, because the
+    /// probe that would establish seekability is the one still parked.
+    @Test("A rebuild refused before its teardown leaves the waiting load to the host", .timeLimit(.minutes(2)))
+    @MainActor
+    func refusedRebuildTakesNothingOver() async throws {
+        let engine = try AetherEngine()
+        let reader = ParkedReader()
+        var events: [SoftwarePathEscalationEvent] = []
+        let sub = engine.softwarePathEscalations.sink { events.append($0) }
+        defer { sub.cancel() }
+
+        let hostLoad = Task { @MainActor in
+            try await engine.load(source: .custom(reader, formatHint: "matroska"),
+                                  options: LoadOptions(suppressDisplayCriteria: true))
+        }
+        try await waitFor { reader.entered }
+
+        await engine.escalateToSoftwarePath(Self.mediaFailure)
+        #expect(events.map(\.duringStartup) == [true])
+        #expect(engine.softwarePathTakeover == nil)
+        #expect(engine.softwarePathTakeoverArm == nil)
+        #expect(engine.errorInfo?.kind == .nativeItemFailed)
+
+        engine.stop()
+        await #expect(throws: CancellationError.self) { try await hostLoad.value }
+    }
+
+    /// A rebuild refused before it tore anything down, or one a host stop() beat to the teardown,
+    /// never became the session's owner, so the load it would have taken over is still the host's.
+    @Test("Only the rebuild's own teardown of the failed generation claims the takeover")
+    @MainActor
+    func takeoverIsClaimedOnlyByItsOwnTeardown() throws {
+        let engine = try AetherEngine()
+        engine.softwarePathRebuild = Task {}
+
+        engine.softwarePathTakeoverArm = engine.loadGeneration &+ 1
+        engine.claimSoftwarePathTakeover()
+        #expect(engine.softwarePathTakeover == nil)
+        #expect(engine.softwarePathTakeoverArm == nil)
+
+        engine.softwarePathTakeoverArm = engine.loadGeneration
+        engine.claimSoftwarePathTakeover()
+        #expect(engine.softwarePathTakeover?.supersededGeneration == engine.loadGeneration)
+        #expect(engine.softwarePathTakeoverArm == nil)
+    }
 }
diff --git a/docs/api.md b/docs/api.md
index 3e24642b2..09c80402e 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -35,13 +35,14 @@ A working shape for the live contracts below, compiled against the engine: [`Exa
 | --- | --- | --- |
 | The source could not be opened, probed, or routed | throws | `.error(message)` is published as well |
 | A newer `load()` or a `stop()` superseded this one | throws `CancellationError` | belongs to the successor, untouched |
+| AVPlayer refused the media during startup and the engine rebuilt the session on the software path (AE#561) | keeps waiting, then returns (or throws what the rebuild threw) | whatever the rebuilt session reaches; `softwarePathEscalations` fires with `duringStartup` |
 | A custom `IOReader` whose initial probe failed | throws | `.error` |
 | Dolby Vision with no compatible base layer on the software path | throws `AetherEngineError.dolbyVisionUnplayableOnSoftwarePath` | `.error` |
 | An HLS playlist handed to the raw live path by a custom reader | throws `AetherEngineError.hlsPlaylistOnRawLivePath` | `.error` |
 | The session died after the load returned (source loss, a reload that never became ready, a track switch that failed) | already returned | `.error(message)` only |
 | A live session the engine cannot revive | already returned | no `.error`; `liveSourceReset` fires instead |
 
-**`CancellationError` is not a playback failure.** It is what a superseded load throws at its first checkpoint, so every channel zap, every next-episode call and every `stop()` during a load produces one. A host that retries, falls back to a second engine, or shows an error on "load threw" reacts to its own navigation unless it lets `CancellationError` through untouched.
+**`CancellationError` is not a playback failure.** It is what a superseded load throws at its first checkpoint, so every channel zap, every next-episode call and every `stop()` during a load produces one. A load the ENGINE superseded does not throw it: the software-path rebuild below takes over the startup, and the `load()` the host is awaiting follows it, the way a #361 reroute keeps its wait (AE#629). A host that retries, falls back to a second engine, or shows an error on "load threw" reacts to its own navigation unless it lets `CancellationError` through untouched.
 
 The message inside `.error` is worth logging verbatim, and it comes from two different places. Some are the engine's own sentence and name the cause rather than the symptom (`"AVFoundation built no track for it within 45s and the source's carriage could not be identified"`, `"Live source unavailable"`, the Dolby Vision hardware refusal); a host timeout that fires first replaces that sentence with its own. The rest are forwarded from the failure underneath, and on the native paths that is `AVPlayerItem.error.localizedDescription` verbatim, which AVFoundation localizes into the device language and whose `NSError` domain and code reach the host only as whatever the localized text happens to embed.
 
@@ -118,6 +119,19 @@ player.systemCaptionRequest       // PassthroughSubject<SystemCaptionRequest, Ne
 
 iOS 26's Automatic Subtitles (show when muted, on skip back, on a language mismatch) turn captions on with no read API behind them, so the selection is the only observable ask. The engine deselects its own rendition, because one rendered in fullscreen draws a caption box over the host's overlay, and forwards the request with the language it named. A host that wants the behaviour answers by selecting its own matching track.
 
+### The engine moves a refused session onto the software path
+
+```swift
+player.softwarePathEscalations   // PassthroughSubject<SoftwarePathEscalationEvent, Never>; subscribe per session
+options.escalatesToSoftwarePath  // default true; false declines the rebuild
+```
+
+When AVPlayer fails a native item with a verdict on the MEDIA (`CoreMediaErrorDomain`, typically `-19602` on a sample Apple's parser refuses), every native recovery reloads the same bytes, so the engine spends one rebuild per session on `SoftwarePlaybackHost` at the session's playhead instead of making the failure terminal (AE#561). libavcodec skips the frame Apple refused and plays on. It is not taken on the remote-HLS bypass, on a session already asked onto `.software`, or for a URL-loading failure, which both paths would read through the same reader; whether the software path can serve the source at all is the same check a `preferredDecodePath` correction runs.
+
+The event fires the moment the rebuild is taken and carries the failure it absorbed, in the `PlaybackErrorInfo` shape it would have surfaced in (`kind` `.nativeItemFailed`), plus the position and whether a `load()` was still waiting. If the rebuild then fails, the original failure is published as `.error` the usual way; if it succeeds, `videoRoute` moves to `.software`. A startup take does not end the host's `load()` with a `CancellationError`: that call keeps waiting across the rebuild and returns the probe it already assembled.
+
+A host that re-plans a failing title with a ladder of its own (a transcode rung, a second player) sets `escalatesToSoftwarePath = false` and gets the failure as `.error` instead, as before 7.9.0. It is a tuning field, correctable through `reloadAtCurrentPosition(applying:)`.
+
 ### The audio tap ends with its session
 
 `installAudioTap()` returns an `AsyncStream<AudioTapBuffer>` bound to the session it was installed against. It finishes on `load()`, on `stop()`, and on a **session-preserving reload**: an audio-track switch, a subtitle-track switch, a disc-title switch, `reloadAtCurrentPosition()`. Re-install on stream end to follow the new session (#356). This is deliberate rather than a gap: each install gets a fresh monotonic filter, so the new session's timeline starts clean instead of stitched across a reload that resumes slightly behind the old position.
@@ -572,6 +586,7 @@ suppressing `AVPlayerItemLegibleOutput` to keep the measurement running.
 | `$isSessionReady` | The session is ready in the AVFoundation sense. Not the edge a black cover comes off on. |
 | `$hasFirstFrameReadyForDisplay` | The picture for **this** load is up. A picture, not motion: a live join presents its first frame and can then hold it bit-static for seconds while AVPlayer decides whether to start (AE#440), so a host dropping a spinner here drops it onto a frozen frame. Use `$playbackPhase` for "it is moving". Latched for the load, cleared at the next `load()` / `stop()`. Audio-only sessions never arm it. On an external screen (`isExternalPlaybackActive`) the local layer never reaches readiness, so the item's readiness is the honest edge and the flag latches there (#315). |
 | `$startupProgress` | `StartupProgress?` for a determinate loading bar. |
+| `softwarePathEscalations`, `SoftwarePathEscalationEvent` | A native session AVPlayer refused, rebuilt on the software path, with the failure it absorbed. See [The engine moves a refused session onto the software path](#the-engine-moves-a-refused-session-onto-the-software-path). |
 | `$videoRoute` | `VideoRoute`: which pipeline is actually serving, one of `.none`, `.remoteBypass`, `.loopback`, `.software`, `.audio`. `LoadOptions.nativeRemoteHLS` is only the request; the carriage watchdog, the remembered verdict and the HLS reroutes move a session between routes, mid-session too. Branch on this, above all for who draws subtitles. |
 | `$audioDelivery` | `AudioDelivery`: how the audio reaches the renderer, one of `.none`, `.noAudioInSource`, `.streamCopy`, `.bridged`, `.decoded`, `.droppedNoPipeline`, `.playerManaged`. `.droppedNoPipeline` is a source that HAS audio playing video-only because no pipeline could be built for it: the value a fallback ladder demotes on. See [Reading whether the audio was delivered](#reading-whether-the-audio-was-delivered). |
 | `$videoFormat` | The format being presented: `.sdr`, `.hdr10`, `.hdr10Plus`, `.dolbyVision`, `.hlg`. On a platform with no per-mode capability table (macOS), a Dolby Vision session the clamp sent to `.hdr10` is upgraded back to `.dolbyVision` once the item AVFoundation is playing turns out to carry a `dvh1` / `dvhe` sample entry (AE#515). On tvOS the panel term behind it no longer comes from the headroom alone: a session serving an HDR master that AVFoundation has not refused publishes the presented format half a second in, because a display that takes an HDR master is presenting HDR while one that is not refuses in 54 to 61 ms, and `currentEDRHeadroom` has been measured reading 1.00 through exactly that acceptance (AE#459). |
@@ -947,6 +962,7 @@ All flags default to safe values; the table is the full set. Depth for the media
 | `forceDolbyVisionOnNonDVDisplay` | false | **Experimental (AE#455).** On a display with no Dolby Vision of its own, serve an HEVC Profile 8.1 source the way a Profile 5 source is served (`dvh1` sample entry, `dvcC` rewritten to profile 5 / compatibility 0, `CODECS="dvh1.05.LL"`), so AVPlayer composes the RPU itself instead of handing the panel the static-metadata HDR10 base layer. The bitstream is untouched; only the container's claim about it changes. Ignored on a display that does Dolby Vision, and Profile 8.1 only. See [formats.md](formats.md#dolby-vision-signaling) for what it buys and what it risks. |
 | `dolbyVisionHandling` | `.automatic` | A `DolbyVisionHandling`. `.baseLayerOnly` presents the HDR10 / HLG base layer of a Dolby Vision source and leaves the Dolby Vision out of the container on every display: plain `hvc1` / `av01` sample entry, `dvcC` stripped, no `SUPPLEMENTAL-CODECS`, HDR10 / HLG display criteria, `videoFormat` reads the base layer's format while `sourceVideoFormat` and `sourceDVProfile` keep saying what the file carries. The route a host offers as "Dolby Vision: off (HDR10)", for a source whose Dolby Vision is wrong and whose base layer is right: the reported shape is a remux carrying a Profile 7 RPU under a container record claiming Profile 5, where a player that believes the record decodes YCbCr as IPT and the picture comes out green / violet. Applies to HEVC Profile 7 / 8.1 / 8.4, AV1 Profile 10.1 / 10.4, and a Profile 5 (or AV1 10.0) record whose VUI declares a BT.2020 YCbCr PQ or HLG base; a Profile 5 whose VUI is unspecified carries IPT-PQ-c2, has no base layer to present, keeps its route, and the engine says so in the log. Takes precedence over `forceDolbyVisionOnNonDVDisplay`. A tuning field, correctable through `reloadAtCurrentPosition(applying:)`; a Profile 5 record the VUI contradicts also stops refusing the software path under it. See [formats.md](formats.md#dolby-vision-signaling). |
 | `preferredDecodePath` | `.automatic` | A `DecodePath`. `.software` serves this source through `SoftwarePlaybackHost` whatever the routing concluded, scoped to this session and costing the source nothing (seeks, the audio switch and the title switch all keep working). The escape for the formats `VTCapabilityProbe` deliberately cannot classify, and for live H.264 / HEVC, which never reaches that gate at all. One-way: there is no `.native`. See [Overriding the decode path](#overriding-the-decode-path). |
+| `escalatesToSoftwarePath` | `true` | Whether a native session AVPlayer refuses on its merits (`CoreMediaErrorDomain`) may be rebuilt once on the software path (AE#561). `false` surfaces the failure as `.error` instead, for a host with its own fallback ladder (AE#629). Correctable. |
 | `deinterlaceMode` | `.auto` | A `DeinterlaceMode` for the software path: the Metal / VideoToolbox graph with a CPU bwdif fallback, or `.software` to force the CPU path. |
 | `deinterlaceFieldRate` | `.field` | A `DeinterlaceFieldRate`: the hardware deinterlacer emits one frame per field (25i to 50p) or per frame. The software fallback is always frame rate, because doubling a CPU bwdif is the wrong trade and a fallback should not change cost class. |
 | `probesize`, `maxAnalyzeDuration` | nil | Caller-bounded open-time probe budget (defaults 50 MB / 60 s). They fail **open**: an over-tight budget loads with late-resolving tracks silently missing rather than throwing, so validate track presence if you tighten them. Do not pass `0` for `maxAnalyzeDuration`; FFmpeg maps it to a shorter heuristic. |
diff --git a/docs/cli.md b/docs/cli.md
index 8ec5c1c64..3e4f5a51e 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -246,6 +246,8 @@ live-only session took a rebuild that rejoins at the edge.
 
 `play --sw` sets `LoadOptions.preferredDecodePath = .software` (#461), the shipping per-session lever, rather than the process-global `setForceSoftwarePathForTesting` it drove before; that hook is still what `live --sw` and `dvr` use, since those harnesses run several sessions and want every one of them on the software host. `--reload-applying decode-path=software` is the same lever applied to a session that is already playing: on the 300 s H.264 fixture the run dispatches `codec=27 → native`, takes the correction at t=9.90 s and comes back `codec=27 → software` at 10.81 s, playing. On a live load the override reaches the same routing decision, which is the case with no alternative, since the #2 capability gate is VOD-only for H.264 / HEVC and such a live session is never classified at all.
 
+`play --no-sw-escalation` sets `LoadOptions.escalatesToSoftwarePath = false` (AE#629), and every `play` run prints an `ESCALATION at <s> duringStartup=<bool> absorbed=<domain>/<code> <kind>` line when the AE#561 rebuild is taken. The pair is the A/B for a host's own fallback ladder. On a 40 s HEVC fixture from `Scripts/nal-overrun-fixture.py --after 20`, played with `AETHER_DISABLE_NAL_SANITIZER=1`, the default arm prints `ESCALATION at 12.00s duringStartup=false absorbed=CoreMediaErrorDomain/-19602 nativeItemFailed`, rebuilds on the software path and plays to the end (`VERDICT: OK`). The declining arm prints no escalation, goes to `.error` with `-19602` at 12.00 s and exits 2.
+
 `--drop-audio` forces every audio pipeline to fail, so the AE#462 video-only drop is observable without a source this build has no decoder for: the loopback cascade skips both the stream-copy probe and the bridge, and `SoftwarePlaybackHost` refuses its decoder open. The run then prints `audio delivery=droppedNoPipeline pipeline=none`, which is the pair a host reads (the typed fact plus the human label), against `delivery=streamCopy` / `bridged` / `decoded` on the same source without the flag. It is loud in the log on purpose, in both the CLI line and the engine's own, because a forced classification read as a real one would be worse than no harness.
 
 `--deinterlace-field-rate field|frame` sets `LoadOptions.deinterlaceFieldRate` (AE#492). `send_field`, the default, emits one output frame per FIELD, so a 29.97i source hands the layer 59.94 frames per second against 23.976 for a progressive one. That factor is the confound in every per-seek counter taken across the two, and this flag is the only way to take it out: the same file, the same seeks, half the output rate, nothing else changed. Measured on a 480i fixture through the hardware chain, four runs an arm: 59.9 fps and 17.47 drops/s at `field` against 30.0 fps and 7.49 at `frame`, which is 0.291 against 0.250 per frame delivered, with the progressive arm at 0.254. Note that nothing binds a render surface in a CLI run, so the absolute level is the harness's own; only the ratio between arms is a measurement.

From 11c686269159053f61f0cd1ffbb7b9c0f91602a2 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 09:29:10 +0200
Subject: [PATCH 096/359] fix(subtitles): decode bitmap subtitles off the
 MainActor (AE#628)

Enabling a PGS track on a Blu-ray remux put imageForSubtitleRect at the top
of the Main Thread profile under subtitleDrainTick. Every display set was
expanded pixel by pixel on the MainActor, twice per set (alpha bounding box,
then RGBA), and a selection or seek backfilled a whole 75 s window in one
tick. The Phase D OCR worker decoded the same packets a second time there.

- The drain tick is split into prepare (MainActor), decode (detached) and
  finish (MainActor). One tick at most is in flight; a tick asked for
  meanwhile is queued. A channel re-selected, cleared or rebuilt while its
  batch decoded is skipped with its cursor unmoved, and stopping the drainer
  drops the batch by serial.
- The OCR worker plans and resolves on the MainActor and decodes in its own
  detached loop.
- imageForSubtitleRect resolves the palette once into a premultiplied lookup
  table and scans rows for the crop, byte-identical output. Full 1080p set on
  an M1: 5.08 -> 1.31 ms release, 215 -> 52 ms debug.

Verified with aetherctl play on a generated full-canvas 1920x1080 PGS track:
identical cue windows on main and on this branch, across a seek.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 CHANGELOG.md                                  |   4 +
 .../AetherEngine+SubtitleOCR.swift            |  84 +++++--
 .../AetherEngine/AetherEngine+Subtitles.swift | 158 +++++++++++--
 Sources/AetherEngine/AetherEngine.swift       |  12 +
 .../Decoder/EmbeddedSubtitleDecoder.swift     |  69 +++---
 ...ue587PreserveASSMarkupCodecGateTests.swift |   2 +-
 .../Issue628PGSOffMainDecodeTests.swift       | 221 ++++++++++++++++++
 7 files changed, 481 insertions(+), 69 deletions(-)
 create mode 100644 Tests/AetherEngineTests/Issue628PGSOffMainDecodeTests.swift

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c37a9ba78..73aebe86e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -153,6 +153,10 @@ the public-API contract.
 - **The live ingest FIFO no longer re-copies its whole buffer on every read** (audit NET-8).
 - **Stripping ASS override tags from a cue is linear.** A cue of 200k tags took 525 s and now takes
   0.15 s on the PiP and AirPlay subtitle track (audit SUB-1).
+- **PGS and other bitmap subtitles decode off the main thread.** The overlay drain and the PiP/AirPlay
+  OCR worker used to expand every display set on the MainActor, including the whole window a
+  selection or seek backfills at once. Each bitmap is also about 4x cheaper to convert (a full
+  1080p set measured 5 ms before, 1.3 ms after, in a release build on an M1) (AE#628).
 
 ## [7.16.1] - 2026-09-24
 
diff --git a/Sources/AetherEngine/AetherEngine+SubtitleOCR.swift b/Sources/AetherEngine/AetherEngine+SubtitleOCR.swift
index 5c3b489e1..781939efb 100644
--- a/Sources/AetherEngine/AetherEngine+SubtitleOCR.swift
+++ b/Sources/AetherEngine/AetherEngine+SubtitleOCR.swift
@@ -2,8 +2,8 @@ import Foundation
 
 // Phase D: selection-armed worker feeding a bitmap track's native WebVTT rendition with
 // OCR-recognized text cues, so PGS/DVB/DVD subtitles survive PiP / AirPlay / external display
-// on the native path. Packet source is the session SubtitlePacketStore (#112 harvest); decode
-// runs on the MainActor tick (overlay-drainer cost class), Vision runs on a dedicated thread.
+// on the native path. Packet source is the session SubtitlePacketStore (#112 harvest); the tick
+// plans and resolves on the MainActor, decodes off it (AE#628), and Vision runs on a dedicated thread.
 extension AetherEngine {
 
     /// Arm for the selected embedded bitmap track. The per-ordinal cursor survives re-arming.
@@ -17,9 +17,16 @@ extension AetherEngine {
         subtitleOCRWorkerTask = Task.detached(priority: .utility) { [weak self] in
             while !Task.isCancelled {
                 guard let self else { return }
+                // AE#628: plan on the MainActor, decode here, off it, then resolve ends back on it.
+                // The decode is the bitmap blit, the heaviest frame of the report's profile.
+                let planned = await MainActor.run { [weak self] () -> SubtitleOCRTickPlan? in
+                    guard !Task.isCancelled, let self else { return nil }
+                    return self.subtitleOCRPlanTick(ordinal: ordinal, streamIndex: streamIndex)
+                }
+                let decoded = planned?.decodeHandoff.decode().first ?? []
                 let batch = await MainActor.run { [weak self] in
-                    guard !Task.isCancelled, let self else { return [SubtitleCue]() }
-                    let batch = self.subtitleOCRCollectTick(ordinal: ordinal, streamIndex: streamIndex)
+                    guard !Task.isCancelled, let self, let planned else { return [SubtitleCue]() }
+                    let batch = self.subtitleOCRFinishTick(planned, events: decoded)
                     self.subtitleOCRBatchInFlight = !batch.isEmpty
                     return batch
                 }
@@ -57,17 +64,12 @@ extension AetherEngine {
         subtitleOCRPendingStates.removeAll()
     }
 
-    /// MainActor tick: plan the window (drainer pacing, larger lead), decode the stored packets
-    /// (bounded per tick), resolve composition ends, return CLOSED cues for off-main OCR.
-    private func subtitleOCRCollectTick(ordinal: Int, streamIndex: Int32) -> [SubtitleCue] {
-        guard let packetStore = activeSubtitlePacketStore else { return [] }
+    /// MainActor half before the decode: plan the window (drainer pacing, larger lead) and pick the
+    /// stored packets (bounded per tick). The decode runs off the MainActor (AE#628) and
+    /// `subtitleOCRFinishTick` resolves composition ends into CLOSED cues for off-main OCR.
+    fileprivate func subtitleOCRPlanTick(ordinal: Int, streamIndex: Int32) -> SubtitleOCRTickPlan? {
+        guard let packetStore = activeSubtitlePacketStore else { return nil }
         let playhead = sourceTime
-        var pending = subtitleOCRPendingStates[ordinal] ?? SubtitleOCRPendingState()
-        var closed: [SubtitleCue] = []
-        defer {
-            closed.append(contentsOf: pending.expired(asOf: playhead))
-            subtitleOCRPendingStates[ordinal] = pending
-        }
         // #271: same rule as the overlay drainer, a tick that ran long is not a seek.
         let tickUptime = Double(DispatchTime.now().uptimeNanoseconds) / 1_000_000_000
         let elapsed = subtitleOCRLastTickUptime.map { tickUptime - $0 } ?? 0
@@ -82,18 +84,21 @@ extension AetherEngine {
         switch plan {
         case .idle:
             subtitleOCRCursors[ordinal]?.lastPlayhead = playhead
-            return closed
+            return SubtitleOCRTickPlan(ordinal: ordinal, playhead: playhead, plan: plan,
+                                       window: (playhead, playhead), decoder: nil, batch: [])
         case .decode(let from, let through):
             window = (from, through)
         case .resetAndDecode(let from, let through):
             subtitleOCRDecoder = nil
-            pending = SubtitleOCRPendingState()
             window = (from, through)
         }
         if subtitleOCRDecoder == nil {
             subtitleOCRDecoder = makeSubtitleDrainDecoder(streamIndex: streamIndex)
         }
-        guard let decoder = subtitleOCRDecoder else { return closed }
+        guard let decoder = subtitleOCRDecoder else {
+            return SubtitleOCRTickPlan(ordinal: ordinal, playhead: playhead, plan: .idle,
+                                       window: window, decoder: nil, batch: [])
+        }
         let entries = packetStore.entries(streamIndex: streamIndex,
                                           from: window.from, through: window.through)
         // #271: the cap has to fall on a PTS boundary. The cursor is a bare PTS advanced by
@@ -104,20 +109,38 @@ extension AetherEngine {
         let batchEnd = SubtitleOverlayDrainer.batchEnd(
             count: entries.count, cap: Self.subtitleOCRMaxPacketsPerTick,
             ptsAt: { entries[$0].ptsSeconds })
-        let batch = entries[..<batchEnd]
+        return SubtitleOCRTickPlan(ordinal: ordinal, playhead: playhead, plan: plan, window: window,
+                                   decoder: decoder, batch: entries[..<batchEnd])
+    }
+
+    /// MainActor half after the decode: resolve composition ends and return the CLOSED cues. A
+    /// batch whose decoder was replaced while it decoded (seek, re-arm) is dropped with its cursor
+    /// unmoved, so the next tick plans that window again.
+    fileprivate func subtitleOCRFinishTick(_ tick: SubtitleOCRTickPlan,
+                                           events: [EmbeddedSubtitleDecoder.SubtitleEvent?]) -> [SubtitleCue] {
+        let ordinal = tick.ordinal
+        var pending = subtitleOCRPendingStates[ordinal] ?? SubtitleOCRPendingState()
+        var closed: [SubtitleCue] = []
+        defer {
+            closed.append(contentsOf: pending.expired(asOf: tick.playhead))
+            subtitleOCRPendingStates[ordinal] = pending
+        }
+        guard let decoder = tick.decoder else { return closed }
+        guard subtitleOCRArmedOrdinal == ordinal, subtitleOCRDecoder === decoder else { return closed }
+        if case .resetAndDecode = tick.plan { pending = SubtitleOCRPendingState() }
         var lastDecoded = subtitleOCRCursors[ordinal]?.lastDecodedPts
-        for entry in batch {
-            if let event = Self.decodeStoredSubtitlePacket(entry, with: decoder) {
+        for (entry, decoded) in zip(tick.batch, events) {
+            if let event = decoded {
                 closed.append(contentsOf: pending.consume(
                     eventPts: entry.ptsSeconds, cues: event.cues, trimAt: event.pgsTrimAt))
             }
             lastDecoded = entry.ptsSeconds
         }
-        if case .resetAndDecode = plan, batch.isEmpty {
-            lastDecoded = window.from
+        if case .resetAndDecode = tick.plan, tick.batch.isEmpty {
+            lastDecoded = tick.window.from
         }
         subtitleOCRCursors[ordinal] = SubtitleDrainCursor(
-            lastDecodedPts: lastDecoded ?? window.from, lastPlayhead: playhead)
+            lastDecodedPts: lastDecoded ?? tick.window.from, lastPlayhead: tick.playhead)
         return closed
     }
 
@@ -139,3 +162,18 @@ extension AetherEngine {
         }
     }
 }
+
+/// AE#628: one OCR worker tick between its MainActor halves. `decoder` is nil for a tick that
+/// decodes nothing (idle, or no decoder could be built), which still expires pending cues.
+fileprivate struct SubtitleOCRTickPlan: @unchecked Sendable {
+    let ordinal: Int
+    let playhead: Double
+    let plan: SubtitleDrainPlan
+    let window: (from: Double, through: Double)
+    let decoder: EmbeddedSubtitleDecoder?
+    let batch: ArraySlice<StoredSubtitlePacket>
+
+    var decodeHandoff: SubtitleDrainDecodeHandoff {
+        SubtitleDrainDecodeHandoff(jobs: decoder.map { [($0, batch)] } ?? [])
+    }
+}
diff --git a/Sources/AetherEngine/AetherEngine+Subtitles.swift b/Sources/AetherEngine/AetherEngine+Subtitles.swift
index c9f18f626..307344d74 100644
--- a/Sources/AetherEngine/AetherEngine+Subtitles.swift
+++ b/Sources/AetherEngine/AetherEngine+Subtitles.swift
@@ -114,7 +114,7 @@ extension AetherEngine {
         // #112 rework: every embedded track (text and bitmap, VOD and live) is served by the
         // playhead-paced drainer from the session's packet store. The producer keeps all subtitle
         // streams from init, so selection needs no side demuxer, no positioning, and no recovery:
-        // the immediate drainer tick backfills the window around the playhead synchronously.
+        // the immediate drainer tick backfills the window around the playhead (off the MainActor, AE#628).
         cancelSidecarTask()
         isSubtitleActive = true
         subtitleCues = []
@@ -135,7 +135,7 @@ extension AetherEngine {
         isLoadingSubtitles = false
         EngineLog.emit(
             "[AetherEngine] overlay fed by packet-store drainer for stream=\(index) "
-            + "(backfilled \(subtitleCues.count) cues)",
+            + "(backfill requested)",
             category: .engine
         )
     }
@@ -193,7 +193,7 @@ extension AetherEngine {
         cancelSidecarTask(channel: .secondary)
 
         // #112 rework: secondary embedded tracks ride the same packet-store drainer on their
-        // own channel; the immediate tick backfills synchronously.
+        // own channel; the immediate tick backfills it.
         isSecondarySubtitleActive = true
         secondarySubtitleCues = []
         pgsStaleArrivalGates[.secondary]?.reset()   // #100
@@ -240,20 +240,53 @@ extension AetherEngine {
 
     /// Build a fresh overlay decoder for the stream on whichever host owns the session demuxer.
     func makeSubtitleDrainDecoder(streamIndex: Int32) -> EmbeddedSubtitleDecoder? {
-        nativeVideoSession?.makeOverlayDecoder(streamIndex: streamIndex)
+        #if DEBUG
+        if let factory = subtitleDrainDecoderFactoryForTesting { return factory(streamIndex) }
+        #endif
+        return nativeVideoSession?.makeOverlayDecoder(streamIndex: streamIndex)
             ?? softwareHost?.makeOverlayDecoder(streamIndex: streamIndex)
     }
 
-    /// Start (or keep) the 500ms drain loop. Performs an immediate tick so a fresh selection
-    /// backfills from the packet store synchronously, matching the #32 tap-overlay UX.
+    /// Start (or keep) the 500ms drain loop. Requests an immediate tick so a fresh selection
+    /// backfills from the packet store without waiting out the first interval (#32 tap-overlay UX).
     func startSubtitleDrainer() {
-        subtitleDrainTick()
+        requestSubtitleDrainTick()
         guard subtitleDrainerTask == nil else { return }
         subtitleDrainerTask = Task { [weak self] in
             while !Task.isCancelled {
                 try? await Task.sleep(nanoseconds: AetherEngine.subtitleDrainTickNanoseconds)
                 guard let self, !Task.isCancelled else { return }
-                self.subtitleDrainTick()
+                self.requestSubtitleDrainTick()
+            }
+        }
+    }
+
+    /// AE#628: the drain loop's tick. Plans on the MainActor, decodes the batch off it, and applies
+    /// the result back on it. A bitmap decode expands a full-canvas indexed plane per display set,
+    /// and a selection or seek backfills a whole window of them at once; on the MainActor that was
+    /// the top frame of the report's profile. A tick asked for while one is in flight is queued,
+    /// not run beside it: the decoders are not reentrant.
+    func requestSubtitleDrainTick() {
+        guard subtitleDrainTickInFlight == nil else {
+            subtitleDrainTickRequested = true
+            return
+        }
+        guard let work = prepareSubtitleDrainTick() else { return }
+        let handoff = work.decodeHandoff
+        guard !handoff.isEmpty else {
+            finishSubtitleDrainTick(work, events: handoff.decode())
+            return
+        }
+        subtitleDrainTickSerial &+= 1
+        let serial = subtitleDrainTickSerial
+        subtitleDrainTickInFlight = Task { [weak self] in
+            let events = await Task.detached(priority: .userInitiated) { handoff.decode() }.value
+            guard let self, self.subtitleDrainTickSerial == serial else { return }
+            self.subtitleDrainTickInFlight = nil
+            self.finishSubtitleDrainTick(work, events: events)
+            if self.subtitleDrainTickRequested {
+                self.subtitleDrainTickRequested = false
+                self.requestSubtitleDrainTick()
             }
         }
     }
@@ -261,6 +294,9 @@ extension AetherEngine {
     func stopSubtitleDrainer(reason: SubtitleDrainStopReason) {
         subtitleDrainerTask?.cancel()
         subtitleDrainerTask = nil
+        subtitleDrainTickInFlight = nil   // AE#628: its batch lands on a stale serial and is dropped
+        subtitleDrainTickRequested = false
+        subtitleDrainTickSerial &+= 1
         subtitleDrainDecoders.removeAll()
         subtitleDrainCursors.removeAll()
         subtitleDrainLastTickUptime = nil   // #271
@@ -289,8 +325,22 @@ extension AetherEngine {
         activeSubtitlePacketStore?.setProtectedStreams(Set(subtitleDrainTargets.values))
     }
 
+    /// The synchronous tick: plan, decode and apply in one go on the MainActor. Kept for the
+    /// teletext page change and for tests; the drain loop goes through `requestSubtitleDrainTick`,
+    /// which decodes off the MainActor (AE#628). Queued rather than run while that one is in flight.
     func subtitleDrainTick() {
-        guard !subtitleDrainTargets.isEmpty, let store = activeSubtitlePacketStore else { return }
+        guard subtitleDrainTickInFlight == nil else {
+            subtitleDrainTickRequested = true
+            return
+        }
+        guard let work = prepareSubtitleDrainTick() else { return }
+        finishSubtitleDrainTick(work, events: work.decodeHandoff.decode())
+    }
+
+    /// AE#628: the MainActor half before the decode. Plans every channel, states the ticks that
+    /// decode nothing (idle, no decoder), and hands back what the decode needs.
+    func prepareSubtitleDrainTick() -> SubtitleDrainTickWork? {
+        guard !subtitleDrainTargets.isEmpty, let store = activeSubtitlePacketStore else { return nil }
         store.setProtectedStreams(Set(subtitleDrainTargets.values))   // #166: re-assert protection
         let playhead = sourceTime
         // #416: the pump is rendering the frame at the playhead, so it has necessarily read from
@@ -304,7 +354,7 @@ extension AetherEngine {
         let tickUptime = Double(DispatchTime.now().uptimeNanoseconds) / 1_000_000_000
         let elapsed = subtitleDrainLastTickUptime.map { tickUptime - $0 } ?? 0
         subtitleDrainLastTickUptime = tickUptime
-        var prefetchNeedsReanchor = false
+        var work = SubtitleDrainTickWork(store: store, playhead: playhead)
         for (channel, streamIndex) in subtitleDrainTargets {
             let hadCursor = subtitleDrainCursors[channel] != nil
             let plan = SubtitleOverlayDrainer.drainPlan(
@@ -315,7 +365,7 @@ extension AetherEngine {
                 jumpThreshold: Self.subtitleDrainJumpThresholdSeconds,
                 elapsedSinceLastPlan: elapsed)
             if Self.subtitleForwardPrefetchNeedsReanchor(plan: plan, hadCursor: hadCursor) {
-                prefetchNeedsReanchor = true
+                work.prefetchNeedsReanchor = true
             }
             let window: (from: Double, through: Double)
             // #250: a reset starts a fresh contiguous decoded run; a steady tick extends the one
@@ -419,6 +469,40 @@ extension AetherEngine {
                 gapHoldTicksLeft = held?.harvestGapAt == cut.at
                     ? (held?.harvestGapTicksLeft ?? 0) - 1 : Self.subtitleDrainHarvestGapTicks
             }
+            work.channels.append(SubtitleDrainChannelWork(
+                channel: channel, streamIndex: streamIndex, plan: plan, isReset: isReset,
+                window: window, coverageStart: coverageStart, retained: retained,
+                decoder: decoder, entries: entries, batchEnd: batchEnd, decodeEnd: decodeEnd,
+                gapHoldAt: gapHoldAt, gapHoldSequence: gapHoldSequence,
+                gapHoldTicksLeft: gapHoldTicksLeft))
+        }
+        return work
+    }
+
+    /// AE#628: the MainActor half after the decode. `events` holds one decoded result per packet
+    /// the prepare half handed out, channel by channel. A channel re-selected, cleared or rebuilt
+    /// while its batch decoded is skipped: its cursor did not move, so the next tick redoes it.
+    func finishSubtitleDrainTick(_ work: SubtitleDrainTickWork,
+                                 events decodedByChannel: [[EmbeddedSubtitleDecoder.SubtitleEvent?]]) {
+        let store = work.store
+        let playhead = work.playhead
+        guard activeSubtitlePacketStore === store else { return }
+        for (job, events) in zip(work.channels, decodedByChannel) {
+            let channel = job.channel
+            let streamIndex = job.streamIndex
+            guard subtitleDrainTargets[channel] == streamIndex,
+                  subtitleDrainDecoders[channel] === job.decoder else { continue }
+            let plan = job.plan
+            let isReset = job.isReset
+            let window = job.window
+            let coverageStart = job.coverageStart
+            let retained = job.retained
+            let entries = job.entries
+            let batchEnd = job.batchEnd
+            let decodeEnd = job.decodeEnd
+            let gapHoldAt = job.gapHoldAt
+            let gapHoldSequence = job.gapHoldSequence
+            let gapHoldTicksLeft = job.gapHoldTicksLeft
             // #271: bind the channel's cue array ONCE for the whole batch. `subtitleCues` is
             // `@Published`, whose wrapper exposes get/set and no `_modify`, so passing it inout per
             // event both copy-on-writes the array and publishes it: every consumer then walks a
@@ -444,8 +528,8 @@ extension AetherEngine {
             // #362: the cursor's own harvest sequence rides with it, so the next tick can tell
             // whether its first entry was read by the same run or is the far side of a hole.
             var lastDecodedSequence = subtitleDrainCursors[channel]?.lastDecodedSequence ?? 0
-            for entry in entries[..<decodeEnd] {
-                if let event = Self.decodeStoredSubtitlePacket(entry, with: decoder) {
+            for (entry, decoded) in zip(entries[..<decodeEnd], events) {
+                if let event = decoded {
                     tally.events += 1
                     tally.cues += event.cues.count
                     // A cue-less event still matters: a PGS clear composition carries only
@@ -583,7 +667,7 @@ extension AetherEngine {
         // #151: a jump (seek / producer re-anchor) moves the drain window out from under the
         // prefetcher's read position; restart it at the new playhead. Once per tick, not per
         // channel: both channels ride the same playhead and the same side demuxer.
-        if prefetchNeedsReanchor { startSubtitleForwardPrefetcher() }
+        if work.prefetchNeedsReanchor { startSubtitleForwardPrefetcher() }
         // #125: the packet store is NOT time-pruned here. A trailing playhead-relative prune
         // (was: playhead - retentionSeconds) evicted packets a backward seek could still land on:
         // a backward jump into segment-cache-resident content is served without a producer restart,
@@ -2604,3 +2688,49 @@ extension AetherEngine {
         }
     }
 }
+
+/// AE#628: one channel's share of a drain tick, everything the decode needs and everything the
+/// apply half reads back. Built and consumed on the MainActor; only `decodeHandoff` leaves it.
+struct SubtitleDrainChannelWork {
+    let channel: SubtitleChannel
+    let streamIndex: Int32
+    let plan: SubtitleDrainPlan
+    let isReset: Bool
+    let window: (from: Double, through: Double)
+    let coverageStart: Double?
+    let retained: SubtitleResolutionStatement.Retention?
+    let decoder: EmbeddedSubtitleDecoder
+    let entries: [StoredSubtitlePacket]
+    let batchEnd: Int
+    let decodeEnd: Int
+    let gapHoldAt: Double?
+    let gapHoldSequence: UInt64
+    let gapHoldTicksLeft: Int
+}
+
+struct SubtitleDrainTickWork {
+    let store: SubtitlePacketStore
+    let playhead: Double
+    var channels: [SubtitleDrainChannelWork] = []
+    var prefetchNeedsReanchor = false
+
+    var decodeHandoff: SubtitleDrainDecodeHandoff {
+        SubtitleDrainDecodeHandoff(jobs: channels.map { ($0.decoder, $0.entries[..<$0.decodeEnd]) })
+    }
+}
+
+/// AE#628: the decode half of a drain tick, the only part that runs off the MainActor. Unchecked
+/// because a decoder wraps an AVCodecContext; sound because a decoder is only ever driven by the
+/// one tick in flight (`subtitleDrainTickInFlight`), and a decoder the channel dropped meanwhile is
+/// never read again once its batch lands.
+struct SubtitleDrainDecodeHandoff: @unchecked Sendable {
+    let jobs: [(decoder: EmbeddedSubtitleDecoder, packets: ArraySlice<StoredSubtitlePacket>)]
+
+    var isEmpty: Bool { jobs.allSatisfy { $0.packets.isEmpty } }
+
+    func decode() -> [[EmbeddedSubtitleDecoder.SubtitleEvent?]] {
+        jobs.map { job in
+            job.packets.map { AetherEngine.decodeStoredSubtitlePacket($0, with: job.decoder) }
+        }
+    }
+}
diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index d0692cf1d..d7e92e967 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -1162,6 +1162,18 @@ public final class AetherEngine: ObservableObject {
     /// the embedded side-demuxer reader for every host, VOD and live, text and bitmap.
     var subtitleDrainTargets: [SubtitleChannel: Int32] = [:]
     var subtitleDrainerTask: Task<Void, Never>?
+    /// AE#628: the drain tick whose decode is running off the MainActor, nil while none is. At most
+    /// one at a time, because a channel's decoder is one AVCodecContext and the tick in flight owns
+    /// it; a tick asked for meanwhile sets `subtitleDrainTickRequested` and runs when it lands.
+    var subtitleDrainTickInFlight: Task<Void, Never>?
+    var subtitleDrainTickRequested = false
+    /// AE#628: bumped by `stopSubtitleDrainer`, so a batch still decoding for a stopped drainer
+    /// lands on a newer serial and is dropped instead of clearing a later tick's in-flight slot.
+    var subtitleDrainTickSerial: UInt64 = 0
+    #if DEBUG
+    /// AE#628: lets a test drive the drain tick with a real decoder but no playback session.
+    var subtitleDrainDecoderFactoryForTesting: ((Int32) -> EmbeddedSubtitleDecoder?)?
+    #endif
     /// SW-host sessions have no HLSVideoEngine; their tap fills this store instead.
     var softwareSubtitlePacketStore: SubtitlePacketStore?
     var subtitleDrainDecoders: [SubtitleChannel: EmbeddedSubtitleDecoder] = [:]
diff --git a/Sources/AetherEngine/Decoder/EmbeddedSubtitleDecoder.swift b/Sources/AetherEngine/Decoder/EmbeddedSubtitleDecoder.swift
index 1fc274e42..6cb4293fb 100644
--- a/Sources/AetherEngine/Decoder/EmbeddedSubtitleDecoder.swift
+++ b/Sources/AetherEngine/Decoder/EmbeddedSubtitleDecoder.swift
@@ -641,21 +641,38 @@ final class EmbeddedSubtitleDecoder {
         // Malformed rect guard: stride < width would read past the plane allocation.
         guard stride >= width else { return nil }
 
+        // AE#628: resolve the palette once. Every pixel below is then one table read instead of a
+        // palette walk plus a premultiply; on a full-canvas plane that is the difference between 5 ms
+        // and 1.3 ms per display set in release, and 211 ms and 52 ms in a debug build.
+        // Premultiplied: straight alpha produces black-fringe edges in CGImage premultipliedLast.
+        // Packed so a little-endian store lays the bytes out as R, G, B, A.
+        let alphaThreshold: UInt8 = 8
+        var visible = [Bool](repeating: false, count: 256)
+        var premultiplied = [UInt32](repeating: 0, count: 256)
+        for i in 0..<256 {
+            let b = UInt32(palettePtr[i * 4 + 0])
+            let g = UInt32(palettePtr[i * 4 + 1])
+            let red = UInt32(palettePtr[i * 4 + 2])
+            let a = UInt32(palettePtr[i * 4 + 3])
+            visible[i] = palettePtr[i * 4 + 3] >= alphaThreshold
+            premultiplied[i] = ((red * a + 127) / 255)
+                | (((g * a + 127) / 255) << 8)
+                | (((b * a + 127) / 255) << 16)
+                | (a << 24)
+        }
+
         // Re-crop to non-zero-alpha bounding box: some Blu-ray-to-MKV conversions emit full 1920x1080 ODS bitmaps
         // with cropping params that FFmpeg's pgssubdec discards, carrying ~8 MB of transparent pixels per cue.
-        let alphaThreshold: UInt8 = 8
         var minX = width, minY = height, maxX = -1, maxY = -1
-        for y in 0..<height {
-            let rowOff = y * stride
-            for x in 0..<width {
-                let palIdx = Int(pixelsPtr[rowOff + x])
-                let alpha = palettePtr[palIdx * 4 + 3]
-                if alpha >= alphaThreshold {
-                    if x < minX { minX = x }
-                    if y < minY { minY = y }
-                    if x > maxX { maxX = x }
-                    if y > maxY { maxY = y }
-                }
+        visible.withUnsafeBufferPointer { visible in
+            for y in 0..<height {
+                let row = UnsafeBufferPointer(start: pixelsPtr + y * stride, count: width)
+                guard let first = row.firstIndex(where: { visible[Int($0)] }),
+                      let last = row.lastIndex(where: { visible[Int($0)] }) else { continue }
+                minX = min(minX, first)
+                maxX = max(maxX, last)
+                if minY == height { minY = y }
+                maxY = y
             }
         }
         guard maxX >= minX, maxY >= minY else { return nil }
@@ -665,27 +682,17 @@ final class EmbeddedSubtitleDecoder {
         let absX = Int(r.x) + minX
         let absY = Int(r.y) + minY
 
-        var rgba = [UInt8](repeating: 0, count: cropW * cropH * 4)
-        for cy in 0..<cropH {
-            let srcRow = (minY + cy) * stride
-            let dstRow = cy * cropW * 4
-            for cx in 0..<cropW {
-                let palIdx = Int(pixelsPtr[srcRow + minX + cx])
-                let palOff = palIdx * 4
-                let b = palettePtr[palOff + 0]
-                let g = palettePtr[palOff + 1]
-                let red = palettePtr[palOff + 2]
-                let a = palettePtr[palOff + 3]
-                // Premultiply: straight alpha produces black-fringe edges in CGImage premultipliedLast.
-                let outOff = dstRow + cx * 4
-                rgba[outOff + 0] = UInt8((Int(red) * Int(a) + 127) / 255)
-                rgba[outOff + 1] = UInt8((Int(g) * Int(a) + 127) / 255)
-                rgba[outOff + 2] = UInt8((Int(b) * Int(a) + 127) / 255)
-                rgba[outOff + 3] = a
+        var data = Data(count: cropW * cropH * 4)
+        data.withUnsafeMutableBytes { raw in
+            let out = raw.bindMemory(to: UInt32.self)
+            premultiplied.withUnsafeBufferPointer { lut in
+                for cy in 0..<cropH {
+                    let src = pixelsPtr + (minY + cy) * stride + minX
+                    let dst = cy * cropW
+                    for cx in 0..<cropW { out[dst + cx] = lut[Int(src[cx])].littleEndian }
+                }
             }
         }
-
-        let data = Data(rgba)
         guard let provider = CGDataProvider(data: data as CFData),
               let colorSpace = CGColorSpace(name: CGColorSpace.sRGB)
         else { return nil }
diff --git a/Tests/AetherEngineTests/Issue587PreserveASSMarkupCodecGateTests.swift b/Tests/AetherEngineTests/Issue587PreserveASSMarkupCodecGateTests.swift
index f58803995..c97ecf552 100644
--- a/Tests/AetherEngineTests/Issue587PreserveASSMarkupCodecGateTests.swift
+++ b/Tests/AetherEngineTests/Issue587PreserveASSMarkupCodecGateTests.swift
@@ -94,7 +94,7 @@ struct Issue587PreserveASSMarkupCodecGateTests {
         #expect(bodies == ["styled ass line", "second ass line"])
     }
 
-    private static let base64 = [
+    static let base64 = [
         "GkXfo6NChoEBQveBAULygQRC84EIQoKIbWF0cm9za2FCh4EEQoWBAhhTgGcBAAAAAAAIqBFNm3TAv4QrfW8sTbuLU6uEFUmpZlOs",
         "gaFNu4tTq4QWVK5rU6yB8U27jFOrhBJUw2dTrIID9k27jFOrhBxTu2tTrIIIPOwBAAAAAAAAUwAAAAAAAAAAAAAAAAAAAAAAAAAA",
         "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAFUmpZsu/hGgSNtMq",
diff --git a/Tests/AetherEngineTests/Issue628PGSOffMainDecodeTests.swift b/Tests/AetherEngineTests/Issue628PGSOffMainDecodeTests.swift
new file mode 100644
index 000000000..befd45daf
--- /dev/null
+++ b/Tests/AetherEngineTests/Issue628PGSOffMainDecodeTests.swift
@@ -0,0 +1,221 @@
+import Foundation
+import CoreGraphics
+import Testing
+import AetherLibavcodec
+import AetherLibavutil
+@testable import AetherEngine
+
+/// AE#628 (ijuniorfu): enabling a PGS track on a Blu-ray remux took the process past 100% CPU, with
+/// `imageForSubtitleRect` the heaviest frame on the Main Thread under `subtitleDrainTick`.
+///
+/// Two halves. The blit expanded a full-canvas 1920x1080 indexed plane pixel by pixel, twice (alpha
+/// bounding box, then RGBA), measured at 5 ms per display set in release and 211 ms in a debug build
+/// on an M1; it now resolves the palette once into a lookup table. And the drain tick decoded on the
+/// MainActor, including the selection and seek backfill of a whole 75 s window in one go; the decode
+/// now runs off it and only the apply half comes back.
+struct Issue628PGSOffMainDecodeTests {
+
+    // MARK: - Blit
+
+    /// The pre-#628 algorithm, kept verbatim as the reference the lookup-table blit must match byte
+    /// for byte (the #146 same-geometry replacement keys on the crop, so the crop may not move).
+    private static func referenceRGBA(pixels: [UInt8], palette: [UInt8], width: Int, height: Int,
+                                      stride: Int) -> (rgba: [UInt8], x: Int, y: Int, w: Int, h: Int)? {
+        var minX = width, minY = height, maxX = -1, maxY = -1
+        for y in 0..<height {
+            for x in 0..<width where palette[Int(pixels[y * stride + x]) * 4 + 3] >= 8 {
+                minX = min(minX, x); minY = min(minY, y); maxX = max(maxX, x); maxY = max(maxY, y)
+            }
+        }
+        guard maxX >= minX, maxY >= minY else { return nil }
+        let cropW = maxX - minX + 1, cropH = maxY - minY + 1
+        var rgba = [UInt8](repeating: 0, count: cropW * cropH * 4)
+        for cy in 0..<cropH {
+            for cx in 0..<cropW {
+                let p = Int(pixels[(minY + cy) * stride + minX + cx]) * 4
+                let b = Int(palette[p]), g = Int(palette[p + 1]), r = Int(palette[p + 2])
+                let a = Int(palette[p + 3])
+                let o = (cy * cropW + cx) * 4
+                rgba[o] = UInt8((r * a + 127) / 255)
+                rgba[o + 1] = UInt8((g * a + 127) / 255)
+                rgba[o + 2] = UInt8((b * a + 127) / 255)
+                rgba[o + 3] = UInt8(a)
+            }
+        }
+        return (rgba, minX, minY, cropW, cropH)
+    }
+
+    private static func bytes(of image: CGImage) -> [UInt8] {
+        let data = image.dataProvider!.data! as Data
+        var out: [UInt8] = []
+        for row in 0..<image.height {
+            let start = row * image.bytesPerRow
+            out.append(contentsOf: data[start..<(start + image.width * 4)])
+        }
+        return out
+    }
+
+    @Test("the lookup-table blit is byte-identical to the per-pixel one, crop and premultiply included",
+          arguments: [UInt64(1), 7, 628, 4096])
+    func blitMatchesReference(seed: UInt64) throws {
+        var rng = SplitMix(seed: seed)
+        let width = 96, height = 40, stride = 112   // stride > width: the padding must never be read
+        var palette = [UInt8](repeating: 0, count: 256 * 4)
+        for i in 0..<256 {
+            for c in 0..<4 { palette[i * 4 + c] = UInt8(truncatingIfNeeded: rng.next()) }
+        }
+        // Around the threshold on purpose: 7 is invisible, 8 is not.
+        palette[0 * 4 + 3] = 0; palette[1 * 4 + 3] = 7; palette[2 * 4 + 3] = 8; palette[3 * 4 + 3] = 255
+        var pixels = [UInt8](repeating: 0, count: stride * height)
+        for y in 8..<30 {
+            for x in 11..<83 { pixels[y * stride + x] = UInt8(truncatingIfNeeded: rng.next()) }
+        }
+        for y in 0..<height {
+            for x in width..<stride { pixels[y * stride + x] = 3 }   // opaque, outside the plane
+        }
+
+        let reference = try #require(Self.referenceRGBA(pixels: pixels, palette: palette,
+                                                        width: width, height: height, stride: stride))
+        let image = try pixels.withUnsafeMutableBufferPointer { px in
+            try palette.withUnsafeMutableBufferPointer { pal in
+                var rect = AVSubtitleRect()
+                rect.type = SUBTITLE_BITMAP
+                rect.x = 100; rect.y = 200
+                rect.w = Int32(width); rect.h = Int32(height)
+                rect.linesize.0 = Int32(stride)
+                rect.data.0 = px.baseAddress
+                rect.data.1 = pal.baseAddress
+                return try #require(withUnsafeMutablePointer(to: &rect) {
+                    EmbeddedSubtitleDecoder.imageForSubtitleRect($0, videoWidth: 1920, videoHeight: 1080)
+                })
+            }
+        }
+        #expect(image.cgImage.width == reference.w)
+        #expect(image.cgImage.height == reference.h)
+        #expect(Self.bytes(of: image.cgImage) == reference.rgba)
+        #expect(Int((image.position.origin.x * 1920).rounded()) == 100 + reference.x)
+        #expect(Int((image.position.origin.y * 1080).rounded()) == 200 + reference.y)
+    }
+
+    @Test("a plane with nothing above the alpha threshold yields no image")
+    func invisiblePlaneYieldsNil() {
+        var pixels = [UInt8](repeating: 1, count: 16 * 4)
+        var palette = [UInt8](repeating: 255, count: 256 * 4)
+        palette[1 * 4 + 3] = 7
+        let image = pixels.withUnsafeMutableBufferPointer { px in
+            palette.withUnsafeMutableBufferPointer { pal in
+                var rect = AVSubtitleRect()
+                rect.type = SUBTITLE_BITMAP
+                rect.w = 16; rect.h = 4; rect.linesize.0 = 16
+                rect.data.0 = px.baseAddress
+                rect.data.1 = pal.baseAddress
+                return withUnsafeMutablePointer(to: &rect) {
+                    EmbeddedSubtitleDecoder.imageForSubtitleRect($0, videoWidth: 1920, videoHeight: 1080)
+                }
+            }
+        }
+        #expect(image == nil)
+    }
+
+    // MARK: - Drain tick
+
+    /// The #587 fixture's SubRip stream: two cues, at 1 s and 3 s.
+    private static let subripStreamIndex: Int32 = 1
+
+    @MainActor
+    private func engineWithHarvestedSubRip() throws -> (AetherEngine, SubtitlePacketStore, Demuxer) {
+        let data = try #require(Data(base64Encoded: Issue587PreserveASSMarkupCodecGateTests.base64.joined()))
+        let demuxer = Demuxer()
+        try demuxer.open(reader: DataIOReader(data: data), formatHint: "matroska")
+        let store = SubtitlePacketStore()
+        let stream = try #require(demuxer.stream(at: Self.subripStreamIndex))
+        while let pkt = try? demuxer.readPacket() {
+            if pkt.pointee.stream_index == Self.subripStreamIndex {
+                store.harvest(streamIndex: Self.subripStreamIndex, packet: pkt,
+                              timeBase: stream.pointee.time_base)
+            }
+            var p: UnsafeMutablePointer<AVPacket>? = pkt
+            trackedPacketFree(&p)
+        }
+        let engine = try AetherEngine()
+        engine.loadedURL = URL(string: "https://s/movie.mkv")!
+        engine.softwareSubtitlePacketStore = store
+        engine.isSubtitleActive = true
+        engine.subtitleDrainTargets[.primary] = Self.subripStreamIndex
+        engine.subtitleDrainDecoderFactoryForTesting = { index in
+            guard let stream = demuxer.stream(at: index) else { return nil }
+            return EmbeddedSubtitleDecoder(stream: stream, sourceVideoWidth: 16, sourceVideoHeight: 16)
+        }
+        engine.clock.sourceTime = 1.5
+        return (engine, store, demuxer)
+    }
+
+    @MainActor
+    @Test("a requested drain tick decodes off the MainActor and applies when it lands")
+    func requestedTickDecodesOffMain() async throws {
+        let (engine, _, demuxer) = try engineWithHarvestedSubRip()
+        defer { demuxer.close() }
+
+        engine.requestSubtitleDrainTick()
+        // Nothing decoded on the caller's stack: the batch is in flight, not applied.
+        let inFlight = try #require(engine.subtitleDrainTickInFlight)
+        #expect(engine.subtitleCues.isEmpty)
+        #expect(engine.subtitleDrainCursors[.primary] == nil)
+
+        await inFlight.value
+        #expect(engine.subtitleDrainTickInFlight == nil)
+        #expect(engine.subtitleCues.map(\.startTime) == [1, 3])
+        #expect(engine.subtitleDrainCursors[.primary] != nil)
+    }
+
+    @MainActor
+    @Test("a batch whose channel was re-selected while it decoded is dropped, and the tick runs again")
+    func reselectionDropsTheStaleBatch() async throws {
+        let (engine, _, demuxer) = try engineWithHarvestedSubRip()
+        defer { demuxer.close() }
+
+        engine.requestSubtitleDrainTick()
+        let stale = try #require(engine.subtitleDrainTickInFlight)
+        // What a selection does to the channel (selectSubtitleTrack): a fresh decoder and cursor.
+        engine.subtitleDrainDecoders[.primary] = nil
+        engine.subtitleDrainCursors[.primary] = nil
+        engine.subtitleDrainTick()   // arrives while the stale batch is in flight: queued, not run
+        #expect(engine.subtitleDrainTickRequested)
+
+        await stale.value
+        // The stale batch published nothing; the queued tick is now the one in flight.
+        let rerun = try #require(engine.subtitleDrainTickInFlight)
+        #expect(engine.subtitleCues.isEmpty)
+        await rerun.value
+        #expect(engine.subtitleCues.map(\.startTime) == [1, 3])
+    }
+
+    @MainActor
+    @Test("stopping the drainer while a batch decodes discards it")
+    func stopDiscardsTheInFlightBatch() async throws {
+        let (engine, _, demuxer) = try engineWithHarvestedSubRip()
+        defer { demuxer.close() }
+
+        engine.requestSubtitleDrainTick()
+        let inFlight = try #require(engine.subtitleDrainTickInFlight)
+        engine.clearSubtitleDrainTarget(channel: .primary, reason: .subtitlesCleared)
+        #expect(engine.subtitleDrainTickInFlight == nil)
+
+        await inFlight.value
+        #expect(engine.subtitleCues.isEmpty)
+        #expect(engine.subtitleDrainCursors.isEmpty)
+    }
+}
+
+/// Deterministic generator so a failing seed reproduces.
+private struct SplitMix {
+    var state: UInt64
+    init(seed: UInt64) { state = seed }
+    mutating func next() -> UInt64 {
+        state &+= 0x9E3779B97F4A7C15
+        var z = state
+        z = (z ^ (z >> 30)) &* 0xBF58476D1CE4E5B9
+        z = (z ^ (z >> 27)) &* 0x94D049BB133111EB
+        return z ^ (z >> 31)
+    }
+}

From 083f312356966ed3f3763809f89d0c4298fea7ab Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 09:56:04 +0200
Subject: [PATCH 097/359] chore(ci): pin actions/checkout to a commit SHA like
 every other action

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 .github/workflows/ci.yml          | 14 +++++++-------
 .github/workflows/release-dmg.yml |  2 +-
 .github/workflows/used-by-add.yml |  2 +-
 3 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 642b3ab20..d6b527ece 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -17,7 +17,7 @@ jobs:
     runs-on: macos-15
     timeout-minutes: 30
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - uses: maxim-lobanov/setup-xcode@ed7a3b1fda3918c0306d1b724322adc0b8cc0a90 # v1.7.0
         with:
@@ -70,7 +70,7 @@ jobs:
     runs-on: macos-15
     timeout-minutes: 30
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - uses: maxim-lobanov/setup-xcode@ed7a3b1fda3918c0306d1b724322adc0b8cc0a90 # v1.7.0
         with:
@@ -119,7 +119,7 @@ jobs:
     runs-on: macos-15
     timeout-minutes: 30
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - uses: maxim-lobanov/setup-xcode@ed7a3b1fda3918c0306d1b724322adc0b8cc0a90 # v1.7.0
         with:
@@ -154,7 +154,7 @@ jobs:
     runs-on: macos-15
     timeout-minutes: 30
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - uses: maxim-lobanov/setup-xcode@ed7a3b1fda3918c0306d1b724322adc0b8cc0a90 # v1.7.0
         with:
@@ -188,7 +188,7 @@ jobs:
     runs-on: xcode-27
     timeout-minutes: 30
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Show toolchain
         run: |
@@ -203,7 +203,7 @@ jobs:
     runs-on: xcode-27
     timeout-minutes: 30
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Build for tvOS Simulator
         run: |
@@ -234,7 +234,7 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 5
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Validate relative links and heading anchors in the published docs
         run: python3 Scripts/check-doc-links.py
diff --git a/.github/workflows/release-dmg.yml b/.github/workflows/release-dmg.yml
index 7cba074db..1809d080b 100644
--- a/.github/workflows/release-dmg.yml
+++ b/.github/workflows/release-dmg.yml
@@ -49,7 +49,7 @@ jobs:
     runs-on: macos-15
     timeout-minutes: 30
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - uses: maxim-lobanov/setup-xcode@ed7a3b1fda3918c0306d1b724322adc0b8cc0a90 # v1.7.0
         with:
diff --git a/.github/workflows/used-by-add.yml b/.github/workflows/used-by-add.yml
index 69074e47e..79386b3ec 100644
--- a/.github/workflows/used-by-add.yml
+++ b/.github/workflows/used-by-add.yml
@@ -26,7 +26,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v7
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Normalise the issue body
         id: normalise

From f56e8ed772244460e18bf209e4780d85f2ed718d Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 10:54:43 +0200
Subject: [PATCH 098/359] test(probe): wait for the park before the drain in
 the stopped-HTTP test

In the body stage the size probe runs ahead of the parked request. When its
callbacks arrive late, rangeProbeFileSize spends its 25 s budget, cancels and
drains, which sets isDrainingProbeRequestForTesting. The wait accepted that
drain as the one under test and then found the origin never entered: both body
cases failed together at ~29 s on a loaded runner (main 36108892404, #636's
first attempt). Delaying the session's callback queue by 27 s reproduces it
exactly, at 25.0 s; with the wait split into park, then drain, the same delay
passes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 Tests/AetherEngineTests/ProbeControlTests.swift | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/Tests/AetherEngineTests/ProbeControlTests.swift b/Tests/AetherEngineTests/ProbeControlTests.swift
index 5a51158bb..e0b61b3eb 100644
--- a/Tests/AetherEngineTests/ProbeControlTests.swift
+++ b/Tests/AetherEngineTests/ProbeControlTests.swift
@@ -1117,8 +1117,11 @@ struct ProbeControlTests {
             try reader.open()
             try control.check()
         }
-        try await waitFor { reader.isDrainingProbeRequestForTesting || job.isFinished || origin.failure != nil }
+        // Park first, drain second: in the body stage the size probe ahead of the parked request
+        // drains too when its callbacks run late, and that drain is not the one under test.
+        try await waitFor { origin.blocked.entered || job.isFinished || origin.failure != nil }
         try #require(origin.blocked.entered)
+        try await waitFor { reader.isDrainingProbeRequestForTesting || job.isFinished }
         #expect(reader.isDrainingProbeRequestForTesting)
         #expect(!job.isFinished, "Cancellation is not completion while the task callback is still queued")
         #expect(OriginRequestBudget.shared.snapshot(for: url)?.inflight == 1)

From eaf9e2472e87969d2c4fd1cab1b4bc59c170b266 Mon Sep 17 00:00:00 2001
From: superuser404notfound
 <264232962+superuser404notfound@users.noreply.github.com>
Date: Fri, 25 Sep 2026 09:40:34 +0000
Subject: [PATCH 099/359] docs(used-by): add Gflix

---
 README.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/README.md b/README.md
index 882bd2733..0cd72493a 100644
--- a/README.md
+++ b/README.md
@@ -47,6 +47,7 @@ You provide the transport bar. You provide the dropdowns. You provide the pretty
 - [Vivid](https://github.com/blurbery/vivid): open-source media app for iPhone, iPad and Apple TV.
 - [Snappier IPTV](https://apps.apple.com/gb/app/snappier-iptv/id1579702567): IPTV App for iOS/iPadOS and tvOS.
 - [stashy](https://stashy.shelf.am/): iOS/tvOS native player for stash.
+- [Gflix](https://gflixhub.app/): A flawless media app for your media.
 <!-- used-by:end -->
 
 Shipping something on AetherEngine? [Submit it](https://github.com/superuser404notfound/AetherEngine/issues/new?template=used-by-submission.yml) to get listed here and on [aetherengine.superuser404.de](https://aetherengine.superuser404.de).

From 5e9a8bebefa5d6c060c80387062de6ec3b05eda1 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Fri, 25 Sep 2026 13:04:55 +0200
Subject: [PATCH 100/359] docs(used-by): add Melon Video (#639)

Co-authored-by: superuser404notfound <264232962+superuser404notfound@users.noreply.github.com>
---
 README.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/README.md b/README.md
index 0cd72493a..0b0cdc2f9 100644
--- a/README.md
+++ b/README.md
@@ -48,6 +48,7 @@ You provide the transport bar. You provide the dropdowns. You provide the pretty
 - [Snappier IPTV](https://apps.apple.com/gb/app/snappier-iptv/id1579702567): IPTV App for iOS/iPadOS and tvOS.
 - [stashy](https://stashy.shelf.am/): iOS/tvOS native player for stash.
 - [Gflix](https://gflixhub.app/): A flawless media app for your media.
+- [Melon Video](https://apps.apple.com/ca/app/melon-video/id6811750997): Video Player for Vision Pro.
 <!-- used-by:end -->
 
 Shipping something on AetherEngine? [Submit it](https://github.com/superuser404notfound/AetherEngine/issues/new?template=used-by-submission.yml) to get listed here and on [aetherengine.superuser404.de](https://aetherengine.superuser404.de).

From 3e90927f218de39a7cb2313e081141f316d670bf Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 13:43:38 +0200
Subject: [PATCH 101/359] test(diagnostics): blocked-probe tests use a pool
 whose lanes do not give up

The AE#597 lane timeout (15 s) is a deadline on the one step these tests
hold on purpose: a probe parked until the test releases it. On the
oversubscribed CI runner the release came later than 15 s, the lane
abandoned the read, and ItemDiagnosticReadTests reported that instead of
the behaviour under test: a retirement finishing incomplete (count 1,
100 instead of 150 bytes) and four tests waiting 180 s for a delivery that
an abandoned read never makes (main run 36127452234). Reproduced locally by
setting the timeout below waitFor's 20 ms cadence: the same five tests fail
the same way, plus the two-lane bound in AVFoundationOffMainTests, which
opens a third lane once one gives up.

The timeout tests in Issue597StrandedDiagnosticReadTests keep their own
0.2 s value.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 .../AVFoundationOffMainTests.swift            |  2 +-
 .../ItemDiagnosticReadTests.swift             | 22 +++++++++----------
 .../Support/DiagnosticPoolTesting.swift       | 14 ++++++++++++
 3 files changed, 26 insertions(+), 12 deletions(-)
 create mode 100644 Tests/AetherEngineTests/Support/DiagnosticPoolTesting.swift

diff --git a/Tests/AetherEngineTests/AVFoundationOffMainTests.swift b/Tests/AetherEngineTests/AVFoundationOffMainTests.swift
index 047faa8ea..17a9ae99d 100644
--- a/Tests/AetherEngineTests/AVFoundationOffMainTests.swift
+++ b/Tests/AetherEngineTests/AVFoundationOffMainTests.swift
@@ -74,7 +74,7 @@ struct AVFoundationOffMainTests {
     /// concurrent queue has to fail here rather than pass on an unrelated carrier test.
     @Test("the diagnostics pool reads on two lanes, each on its own thread", .timeLimit(.minutes(3)))
     func poolAdmitsTwoLanesOffThePool() async throws {
-        let pool = ItemDiagnosticReadPool()
+        let pool = ItemDiagnosticReadPool.withoutReadTimeout()
         let counter = LaneCounter()
         let release = DispatchSemaphore(value: 0)
         defer { release.signal() }
diff --git a/Tests/AetherEngineTests/ItemDiagnosticReadTests.swift b/Tests/AetherEngineTests/ItemDiagnosticReadTests.swift
index 522229e9c..3442f1d80 100644
--- a/Tests/AetherEngineTests/ItemDiagnosticReadTests.swift
+++ b/Tests/AetherEngineTests/ItemDiagnosticReadTests.swift
@@ -56,7 +56,7 @@ struct ItemDiagnosticReadTests {
 
     @Test("blocking getters leave the main actor free and notification bursts coalesce")
     func coalescesWhileBlocked() async throws {
-        let pool = ItemDiagnosticReadPool()
+        let pool = ItemDiagnosticReadPool.withoutReadTimeout()
         let probe = DiagnosticReadProbe()
         defer { probe.unblock() }
         let reader = AVPlayerItemDiagnostics(item: item(), pool: pool, read: probe.read)
@@ -84,7 +84,7 @@ struct ItemDiagnosticReadTests {
 
     @Test("cancellation does not release a blocked lane; a new item can use the other lane")
     func cancellationDoesNotPretendToDrain() async throws {
-        let pool = ItemDiagnosticReadPool()
+        let pool = ItemDiagnosticReadPool.withoutReadTimeout()
         let probe = DiagnosticReadProbe()
         defer { probe.unblock() }
         let old = AVPlayerItemDiagnostics(item: item(), pool: pool, read: probe.read)
@@ -111,7 +111,7 @@ struct ItemDiagnosticReadTests {
 
     @Test("two blocked lanes bound swap bursts, retain observed counters, and prioritize current errors")
     func saturationBoundsRetirement() async throws {
-        let pool = ItemDiagnosticReadPool()
+        let pool = ItemDiagnosticReadPool.withoutReadTimeout()
         let probe = DiagnosticReadProbe()
         defer { probe.unblock() }
         let blocked = (0..<2).map { _ in
@@ -158,7 +158,7 @@ struct ItemDiagnosticReadTests {
 
     @Test("retirement reconciles a post-detach final sample without losing a newer observed baseline")
     func retirementReconcilesCounters() async throws {
-        let pool = ItemDiagnosticReadPool()
+        let pool = ItemDiagnosticReadPool.withoutReadTimeout()
         let probe = DiagnosticReadProbe(snapshot: .init(access: [access(150, 7), access(-1, -1)]))
         defer { probe.unblock() }
         let reader = AVPlayerItemDiagnostics(item: item(), pool: pool, read: probe.read)
@@ -203,7 +203,7 @@ struct ItemDiagnosticReadTests {
 
     @Test("native notification reads are item-bound and a late old poison cannot affect a fresh load")
     func nativeNotificationWiring() async throws {
-        let pool = ItemDiagnosticReadPool()
+        let pool = ItemDiagnosticReadPool.withoutReadTimeout()
         let oldProbe = DiagnosticReadProbe(snapshot: .init(
             errors: [.init(code: -15628, domain: "CoreMediaErrorDomain")]), onlyFirstItem: true)
         defer { oldProbe.unblock() }
@@ -230,7 +230,7 @@ struct ItemDiagnosticReadTests {
 
     @Test("native swaps fold cached counters immediately, reconcile once, and reset on a new session")
     func nativeCounterHandover() async throws {
-        let pool = ItemDiagnosticReadPool()
+        let pool = ItemDiagnosticReadPool.withoutReadTimeout()
         let probe = DiagnosticReadProbe(snapshot: .init(access: [access(150, 7)]))
         defer { probe.unblock() }
         let host = NativeAVPlayerHost(diagnosticPool: pool, diagnosticRead: probe.read)
@@ -252,7 +252,7 @@ struct ItemDiagnosticReadTests {
 
     @Test("a blocked retirement cannot reconcile counters into an unrelated new load")
     func lateCounterReconciliationIsDiscarded() async throws {
-        let pool = ItemDiagnosticReadPool()
+        let pool = ItemDiagnosticReadPool.withoutReadTimeout()
         let probe = DiagnosticReadProbe(snapshot: .init(access: [access(999, 99)]))
         defer { probe.unblock() }
         let host = NativeAVPlayerHost(diagnosticPool: pool, diagnosticRead: probe.read)
@@ -275,7 +275,7 @@ struct ItemDiagnosticReadTests {
 
     @Test("native coalesced error notifications still publish startup loader poison once")
     func nativeLoaderPoison() async throws {
-        let pool = ItemDiagnosticReadPool()
+        let pool = ItemDiagnosticReadPool.withoutReadTimeout()
         let probe = DiagnosticReadProbe(snapshot: .init(
             errors: [.init(code: -15628, domain: "CoreMediaErrorDomain"),
                      .init(code: 404, domain: "HTTP")]))
@@ -299,7 +299,7 @@ struct ItemDiagnosticReadTests {
     @Test("a synchronous stall subscriber replacing the item rejects the rest of the old batch",
           arguments: [false, true])
     func replacementDuringDelivery(inPlace: Bool) async throws {
-        let pool = ItemDiagnosticReadPool()
+        let pool = ItemDiagnosticReadPool.withoutReadTimeout()
         let probe = DiagnosticReadProbe(snapshot: .init(
             errors: [.init(code: -15628, domain: "CoreMediaErrorDomain"),
                      .init(code: -15628, domain: "CoreMediaErrorDomain")]), onlyFirstItem: true)
@@ -334,7 +334,7 @@ struct ItemDiagnosticReadTests {
 
     @Test("audio error notifications leave the callback free and stop rejects the late snapshot")
     func audioNotificationWiring() async throws {
-        let pool = ItemDiagnosticReadPool()
+        let pool = ItemDiagnosticReadPool.withoutReadTimeout()
         let probe = DiagnosticReadProbe()
         defer { probe.unblock() }
         let host = AudioAVPlayerHost(diagnosticPool: pool, diagnosticRead: probe.read)
@@ -358,7 +358,7 @@ struct ItemDiagnosticReadTests {
 
     @Test("real idle AVFoundation log getters produce missing rather than fabricated counters")
     func idleNativeRead() async throws {
-        let pool = ItemDiagnosticReadPool()
+        let pool = ItemDiagnosticReadPool.withoutReadTimeout()
         let reader = AVPlayerItemDiagnostics(item: item(), pool: pool)
         defer { reader.cancel() }
         var result: ItemDiagnosticSnapshot?
diff --git a/Tests/AetherEngineTests/Support/DiagnosticPoolTesting.swift b/Tests/AetherEngineTests/Support/DiagnosticPoolTesting.swift
new file mode 100644
index 000000000..a1f5df00b
--- /dev/null
+++ b/Tests/AetherEngineTests/Support/DiagnosticPoolTesting.swift
@@ -0,0 +1,14 @@
+@testable import AetherEngine
+
+extension ItemDiagnosticReadPool {
+    /// A pool whose lanes do not give up on a read.
+    ///
+    /// The AE#597 read timeout is a deadline on a step these tests hold on purpose: a probe that
+    /// blocks until the test releases it. On an oversubscribed runner the release can come later
+    /// than 15 s, the lane then abandons the read, and the test reports the timeout instead of the
+    /// behaviour it is about (a retirement finishing incomplete, a delivery that never comes, a
+    /// third lane opening). Tests of the timeout itself pass their own small value.
+    static func withoutReadTimeout() -> ItemDiagnosticReadPool {
+        ItemDiagnosticReadPool(readTimeout: 86_400)
+    }
+}

From 5b917c006c97b3b26c3fc99bf6ac35b3188f9b9a Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 14:00:10 +0200
Subject: [PATCH 102/359] chore(release): prep 7.17.0 - audit hardening, sealed
 relay URLs, host-declinable software escalation

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 CHANGELOG.md                                    | 4 ++++
 Examples/README.md                              | 2 +-
 README.md                                       | 6 +++---
 Sources/AetherEngine/AetherEngine+Version.swift | 2 +-
 4 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 73aebe86e..cb9eba88f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,10 @@ the public-API contract.
 
 ## [Unreleased]
 
+_Nothing yet._
+
+## [7.17.0] - 2026-09-25
+
 ### Added
 
 - **`LoadOptions.escalatesToSoftwarePath` (default `true`) lets a host decline the AE#561 rebuild**
diff --git a/Examples/README.md b/Examples/README.md
index 82ae152fe..f52c19d81 100644
--- a/Examples/README.md
+++ b/Examples/README.md
@@ -18,7 +18,7 @@ Three samples covering different audiences:
    ```
    https://github.com/superuser404notfound/AetherEngine
    ```
-   Dependency Rule: Up to Next Major Version, starting from `7.16.1`. Add the `AetherEngine` library product to your app target.
+   Dependency Rule: Up to Next Major Version, starting from `7.17.0`. Add the `AetherEngine` library product to your app target.
 
 3. **Drop the file in.** Replace the Xcode template's default `App.swift` (or whatever the generated `@main` file is called) with the contents of [`MinimalPlayerApp.swift`](MinimalPlayer/MinimalPlayerApp.swift). The file is self-contained: it defines both the `@main App` struct and the `ContentView`.
 
diff --git a/README.md b/README.md
index 0b0cdc2f9..824590343 100644
--- a/README.md
+++ b/README.md
@@ -384,7 +384,7 @@ Subtitle cues land in raw source PTS; render the overlay against `player.sourceT
 Install via Swift Package Manager:
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.16.1")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.17.0")
 ```
 
 Three samples ship in `Examples/`:
@@ -631,10 +631,10 @@ Browse all of this as a searchable site at **[aetherengine.superuser404.de](http
 AetherEngine uses [Semantic Versioning](https://semver.org). The public API surface, every `public` declaration in `Sources/AetherEngine/`, is the stability contract. **Major** removes / renames public symbols or breaks adopters; **Minor** adds public API or codec / format support; **Patch** fixes bugs with no public API change. `internal` types are not part of the contract.
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.16.1")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.17.0")
 ```
 
-Pin to `.upToNextMinor(from: "7.16.1")` for stricter teams that prefer to opt into minor bumps explicitly.
+Pin to `.upToNextMinor(from: "7.17.0")` for stricter teams that prefer to opt into minor bumps explicitly.
 
 ## Requirements
 
diff --git a/Sources/AetherEngine/AetherEngine+Version.swift b/Sources/AetherEngine/AetherEngine+Version.swift
index 8969f7437..bc883e1f9 100644
--- a/Sources/AetherEngine/AetherEngine+Version.swift
+++ b/Sources/AetherEngine/AetherEngine+Version.swift
@@ -11,5 +11,5 @@ extension AetherEngine {
     ///
     /// Between releases, and in a consumer that pins an unreleased commit for a device test, this
     /// names the last PUBLISHED version the checkout descends from, not every patch in it.
-    public nonisolated static let version = "7.16.1"
+    public nonisolated static let version = "7.17.0"
 }

From ca2ba97b246d37f124fc4d6625c8a998c50f2364 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 19:17:55 +0200
Subject: [PATCH 103/359] fix(live): open an H.264 join on an intra recovery
 point, not only on an IDR (AE#627)

The #133 join gate required an IDR slice in the gating access unit. Some
broadcast encoders never send one: their entry points are I-pictures behind
a recovery point SEI with recovery_frame_cnt 0. FFmpeg's parser flags those
as keyframes, the gate refused every one, and the channel went through three
15 s reopen cycles into the same refusal before giving up.

An access unit now opens the gate when it carries an IDR, or a recovery
point with recovery_frame_cnt 0 on a picture coded only in I/SI slices.
Pictures from there on in output order decode exactly, and the open-GOP
leading pictures that do not are already dropped behind the gate. A
recovery point with a later recovery frame (gradual intra refresh) is still
refused.

The gate's wait and timeout lines now count the keyframes they dropped. The
line describes only the packet it is printed on, so a gate refusing every
keyframe read as a feed that had none, which misled the report.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 Sources/AetherEngine/Video/H264SPS.swift      | 59 ++++++++++++--
 .../Video/HLSSegmentProducer.swift            | 32 +++++---
 Tests/AetherEngineTests/H264SPSTests.swift    | 78 +++++++++++++------
 3 files changed, 126 insertions(+), 43 deletions(-)

diff --git a/Sources/AetherEngine/Video/H264SPS.swift b/Sources/AetherEngine/Video/H264SPS.swift
index a0ef696f5..8020b12f9 100644
--- a/Sources/AetherEngine/Video/H264SPS.swift
+++ b/Sources/AetherEngine/Video/H264SPS.swift
@@ -133,10 +133,16 @@ enum H264SPS {
         return nil
     }
 
-    /// Scan Annex-B for a coded IDR slice NAL (type 5). #133: a mid-stream live join must open on a true
-    /// IDR, not an open-GOP recovery-point I-slice (type 1) whose references precede the join point; starting
-    /// there renders garbage (green frames) until the next real IDR. Cheap NAL-header walk, no RBSP parse.
-    static func containsIDR(fromAnnexB data: UnsafeBufferPointer<UInt8>) -> Bool {
+    /// AE#627: whether a decoder can start at this access unit. An IDR slice qualifies, and so does a
+    /// picture coded only in I/SI slices behind a recovery point SEI with `recovery_frame_cnt == 0`:
+    /// every picture from it on in output order decodes exactly (H.264 D.2.8), and the leading
+    /// pictures that do not are dropped behind the gate. Some broadcast encoders never send an IDR,
+    /// so on those feeds a gate that required one never opened. A recovery point with a later
+    /// recovery frame (gradual refresh) is not an entry point and stays refused.
+    static func isRandomAccessEntry(fromAnnexB data: UnsafeBufferPointer<UInt8>) -> Bool {
+        var recoversHere = false
+        var sawSlice = false
+        var allIntra = true
         var i = 0
         let n = data.count
         func startCode(at p: Int) -> Int {
@@ -149,10 +155,49 @@ enum H264SPS {
             if sc == 0 { i += 1; continue }
             let start = i + sc
             guard start < n else { break }
-            if (data[start] & 0x1f) == 5 { return true }
-            i = start
+            var j = start
+            while j < n, startCode(at: j) == 0 { j += 1 }
+            switch data[start] & 0x1f {
+            case 5:
+                return true
+            case 1:
+                sawSlice = true
+                // first_mb_in_slice and slice_type sit in the first few bytes.
+                let head = unescape(Array(data[(start + 1)..<min(j, start + 17)]))
+                var r = BitReader(head)
+                guard r.ue() != nil, let sliceType = r.ue() else { return false }
+                if sliceType % 5 != 2 && sliceType % 5 != 4 { allIntra = false }
+            case 6:
+                if recoveryFrameCount(seiRBSP: unescape(Array(data[(start + 1)..<j]))) == 0 {
+                    recoversHere = true
+                }
+            default:
+                break
+            }
+            i = j
         }
-        return false
+        return recoversHere && sawSlice && allIntra
+    }
+
+    /// `recovery_frame_cnt` of the recovery point message in one SEI NAL payload (header stripped), nil if absent.
+    static func recoveryFrameCount(seiRBSP rbsp: [UInt8]) -> Int? {
+        var p = 0
+        func sei() -> Int? {
+            var v = 0
+            while p < rbsp.count, rbsp[p] == 0xff { v += 255; p += 1 }
+            guard p < rbsp.count else { return nil }
+            v += Int(rbsp[p]); p += 1
+            return v
+        }
+        while p < rbsp.count, rbsp[p] != 0x80 {
+            guard let type = sei(), let size = sei(), p + size <= rbsp.count else { return nil }
+            if type == 6 {
+                var r = BitReader(Array(rbsp[p..<(p + size)]))
+                return r.ue()
+            }
+            p += size
+        }
+        return nil
     }
 
     /// Build Annex-B extradata the mov muxer accepts directly; ff_isom_write_avcc sniffs the start code and packs avcC.
diff --git a/Sources/AetherEngine/Video/HLSSegmentProducer.swift b/Sources/AetherEngine/Video/HLSSegmentProducer.swift
index 91a814f4c..b1ef49640 100644
--- a/Sources/AetherEngine/Video/HLSSegmentProducer.swift
+++ b/Sources/AetherEngine/Video/HLSSegmentProducer.swift
@@ -534,6 +534,9 @@ final class HLSSegmentProducer: @unchecked Sendable {
 
     /// Pre-gate drop counters; surface the "lädt unendlich" failure mode when the gate never opens.
     private var pregateVideoDropCount: Int = 0
+    /// AE#627: dropped packets that did carry the key flag. The wait line describes only the packet it
+    /// is printed on, so without this a join gate refusing every keyframe read as a feed with none.
+    private var pregateKeyDropCount: Int = 0
     private var pregateWaitStart: Date?
     private static let liveKeyframeGateTimeoutSeconds: TimeInterval = 15
 
@@ -1110,6 +1113,7 @@ final class HLSSegmentProducer: @unchecked Sendable {
         pregateAudioReplaySorted = false
         pregateAudioOverflowLogged = false
         pregateVideoDropCount = 0
+        pregateKeyDropCount = 0
         pregateAudioDropCount = 0
         lastPregateVideoLog = 0
         lastPregateAudioLog = 0
@@ -1271,8 +1275,9 @@ final class HLSSegmentProducer: @unchecked Sendable {
     private let a53CodecKind: A53SEIParser.CodecKind?
     private let a53NALFraming: A53SEIParser.NALFraming
 
-    /// #133: latched at init. When true, the video gate withholds until a decodable IDR access unit
-    /// (in-band SPS+PPS+IDR) arrives, rather than opening on any AV_PKT_FLAG_KEY packet.
+    /// #133: latched at init. When true, the video gate withholds until a decodable access unit
+    /// (in-band SPS+PPS and an IDR or immediate intra recovery point, AE#627) arrives, rather than
+    /// opening on any AV_PKT_FLAG_KEY packet.
     private let liveH264AnnexBJoin: Bool
 
     /// Sodalite#32: text-subtitle tap, generalizing the #77 CC tap. Streams in this set are kept by the
@@ -1733,14 +1738,15 @@ final class HLSSegmentProducer: @unchecked Sendable {
         return active != incoming
     }
 
-    /// #133 join gate: a decodable H.264 access unit at a mid-stream join needs in-band SPS + PPS and a true
-    /// IDR slice (not an open-GOP recovery point). Returns the reconstructed (width, height, Annex-B extradata)
-    /// so a zero-dimension probe codecpar can be backfilled into the first muxer. nil until such an AU arrives.
+    /// #133 join gate: a decodable H.264 access unit at a mid-stream join needs in-band SPS + PPS and an
+    /// entry point, an IDR or an immediate intra recovery point (AE#627, see `isRandomAccessEntry`). Returns
+    /// the reconstructed (width, height, Annex-B extradata) so a zero-dimension probe codecpar can be
+    /// backfilled into the first muxer. nil until such an AU arrives.
     private func extractJoinVideoConfig(_ packet: UnsafeMutablePointer<AVPacket>) -> (width: Int32, height: Int32, extradata: [UInt8])? {
         guard let data = packet.pointee.data, packet.pointee.size > 0 else { return nil }
         let buf = UnsafeBufferPointer(start: data, count: Int(packet.pointee.size))
         guard let (sps, pps) = H264SPS.extractSPSandPPS(fromAnnexB: buf),
-              H264SPS.containsIDR(fromAnnexB: buf),
+              H264SPS.isRandomAccessEntry(fromAnnexB: buf),
               let dim = H264SPS.dimensions(fromNAL: sps) else { return nil }
         return (Int32(dim.width), Int32(dim.height),
                 H264SPS.annexBExtradata(sps: sps, pps: pps))
@@ -3459,9 +3465,9 @@ final class HLSSegmentProducer: @unchecked Sendable {
                             pts: packet.pointee.pts, dts: packet.pointee.dts,
                             targetPts: effectiveGateTargetPts)
                         // #133: on a live H.264 Annex-B mid-stream join, opening on a bare keyframe flag is not
-                        // enough. A join packet must carry a decodable IDR access unit (in-band SPS+PPS+IDR);
-                        // otherwise the decoder renders references it never received (green frames) or, when the
-                        // probe joined before any SPS and left codecpar at 0x0, the first muxer alloc gets 0x0
+                        // enough. A join packet must carry a decodable access unit (in-band SPS+PPS and an
+                        // IDR or immediate intra recovery point, AE#627); otherwise the decoder renders references
+                        // it never received (green frames) or, when the probe joined before any SPS and left codecpar at 0x0, the first muxer alloc gets 0x0
                         // dimensions and avformat_write_header fails -22, dead-ending the channel. The bounded
                         // live timeout below covers the miss (keyframeStarvation -> reopen), unlike muxerFailed.
                         let joinConfig = (liveH264AnnexBJoin && isKey && targetSatisfied)
@@ -3472,6 +3478,7 @@ final class HLSSegmentProducer: @unchecked Sendable {
                                 let ts = packet.pointee.pts != Int64.min
                                     ? packet.pointee.pts : packet.pointee.dts
                                 if ts != Int64.min { notePregateDroppedKeyframe(pts: ts) }
+                                pregateKeyDropCount += 1
                             }
                             // AE#408: the scan has reached ground already known to carry no sync
                             // sample (the boundary itself on the first pass, the abandoned aim after
@@ -3497,10 +3504,10 @@ final class HLSSegmentProducer: @unchecked Sendable {
                             if pregateVideoDropCount - lastPregateVideoLog >= Self.pregateLogInterval {
                                 lastPregateVideoLog = pregateVideoDropCount
                                 let awaiting = (isKey && targetSatisfied && liveH264AnnexBJoin)
-                                    ? "SPS/PPS/IDR access unit" : "video keyframe"
+                                    ? "SPS/PPS + entry-point access unit" : "video keyframe"
                                 EngineLog.emit(
                                     "[HLSSegmentProducer] still waiting for \(awaiting): "
-                                    + "dropped=\(pregateVideoDropCount) "
+                                    + "dropped=\(pregateVideoDropCount) (keyframes=\(pregateKeyDropCount)) "
                                     + "lastDts=\(packet.pointee.dts) lastPts=\(packet.pointee.pts) "
                                     + "isKey=\(isKey) "
                                     + "target=\(effectiveGateTargetPts)"
@@ -3516,7 +3523,8 @@ final class HLSSegmentProducer: @unchecked Sendable {
                                 EngineLog.emit(
                                     "[HLSSegmentProducer] live keyframe gate timed out after "
                                     + "\(Int(Self.liveKeyframeGateTimeoutSeconds))s "
-                                    + "(dropped=\(pregateVideoDropCount)); exiting pump for reopen",
+                                    + "(dropped=\(pregateVideoDropCount), keyframes=\(pregateKeyDropCount)); "
+                                    + "exiting pump for reopen",
                                     category: .session
                                 )
                                 exitReason = .keyframeStarvation
diff --git a/Tests/AetherEngineTests/H264SPSTests.swift b/Tests/AetherEngineTests/H264SPSTests.swift
index 92a90e3a8..326f12de0 100644
--- a/Tests/AetherEngineTests/H264SPSTests.swift
+++ b/Tests/AetherEngineTests/H264SPSTests.swift
@@ -47,42 +47,72 @@ final class H264SPSTests: XCTestCase {
         bytes.withUnsafeBufferPointer { body($0) }
     }
 
-    // #133: a mid-stream join must start on a true IDR (NAL type 5), not an open-GOP recovery
-    // point (non-IDR slice, type 1), or the panel renders references it never received (green frames).
-    func testContainsIDRDetectsType5Slice() {
-        let au = annexB([sps720, pps, [0x65, 0x88, 0x84, 0x00]]) // 0x65 = IDR slice (type 5)
-        XCTAssertTrue(withBuf(au) { H264SPS.containsIDR(fromAnnexB: $0) })
+    // #133 / AE#627: a mid-stream join opens on an entry point: an IDR (NAL type 5), or an intra
+    // picture behind a recovery point SEI with recovery_frame_cnt 0. A bare non-IDR slice is neither.
+    private var iSlice: [UInt8] { [0x41, 0x88, 0x84, 0x00] }          // non-IDR, first_mb 0, slice_type 7 (I)
+    private var pSlice: [UInt8] { [0x41, 0x9a, 0x00, 0x00] }          // non-IDR, first_mb 0, slice_type 5 (P)
+    private var recoveryNow: [UInt8] { [0x06, 0x06, 0x01, 0xc4, 0x80] }  // recovery point, cnt 0 (x264's bytes)
+    private var recoveryLater: [UInt8] { [0x06, 0x06, 0x01, 0x71, 0x80] } // recovery point, cnt 2 (gradual refresh)
+
+    func testIDRIsAnEntry() {
+        let au = annexB([sps720, pps, [0x65, 0x88, 0x84, 0x00]])
+        XCTAssertTrue(withBuf(au) { H264SPS.isRandomAccessEntry(fromAnnexB: $0) })
     }
 
-    func testContainsIDRRejectsNonIDRAccessUnit() {
-        let au = annexB([sps720, pps, [0x41, 0x9a, 0x00, 0x00]]) // 0x41 = non-IDR slice (type 1)
-        XCTAssertFalse(withBuf(au) { H264SPS.containsIDR(fromAnnexB: $0) })
+    func testBareNonIDRSliceIsNotAnEntry() {
+        XCTAssertFalse(withBuf(annexB([sps720, pps, pSlice])) { H264SPS.isRandomAccessEntry(fromAnnexB: $0) })
+        XCTAssertFalse(withBuf(annexB([sps720, pps, iSlice])) { H264SPS.isRandomAccessEntry(fromAnnexB: $0) })
     }
 
-    func testContainsIDRRejectsBareParameterSets() {
-        let au = annexB([sps720, pps]) // params only, no coded slice
-        XCTAssertFalse(withBuf(au) { H264SPS.containsIDR(fromAnnexB: $0) })
+    func testBareParameterSetsAreNotAnEntry() {
+        XCTAssertFalse(withBuf(annexB([sps720, pps])) { H264SPS.isRandomAccessEntry(fromAnnexB: $0) })
+        XCTAssertFalse(withBuf(annexB([sps720, pps, recoveryNow])) { H264SPS.isRandomAccessEntry(fromAnnexB: $0) })
     }
 
-    func testContainsIDRHandlesThreeByteStartCodes() {
+    func testEntryHandlesThreeByteStartCodes() {
         let sc3: [UInt8] = [0, 0, 1]
-        var au: [UInt8] = sc3
-        au += sps720
-        au += sc3
-        au += pps
-        au += sc3
-        au += [0x65, 0x88]
-        XCTAssertTrue(withBuf(au) { H264SPS.containsIDR(fromAnnexB: $0) })
+        let au = sc3 + sps720 + sc3 + pps + sc3 + [0x65, 0x88]
+        XCTAssertTrue(withBuf(au) { H264SPS.isRandomAccessEntry(fromAnnexB: $0) })
+    }
+
+    // AE#627: the reporter's feed never sends an IDR. Its entry points are AUD, SPS, PPS, SEI
+    // [recovery point cnt 0, pic_timing], then an I-picture.
+    func testImmediateIntraRecoveryPointIsAnEntry() {
+        let aud: [UInt8] = [0x09, 0xf0]
+        let au = annexB([aud, sps720, pps, recoveryNow, iSlice])
+        XCTAssertTrue(withBuf(au) { H264SPS.isRandomAccessEntry(fromAnnexB: $0) })
+    }
+
+    func testRecoveryPointBehindAnotherSEIMessageIsFound() {
+        let sei: [UInt8] = [0x06, 0x05, 0x02, 0xaa, 0xbb, 0x06, 0x01, 0xc4, 0x80]
+        XCTAssertTrue(withBuf(annexB([sps720, pps, sei, iSlice])) { H264SPS.isRandomAccessEntry(fromAnnexB: $0) })
+    }
+
+    func testGradualRefreshRecoveryPointIsNotAnEntry() {
+        XCTAssertFalse(withBuf(annexB([sps720, pps, recoveryLater, iSlice])) {
+            H264SPS.isRandomAccessEntry(fromAnnexB: $0)
+        })
+    }
+
+    func testRecoveryPointOnAPictureWithAPSliceIsNotAnEntry() {
+        XCTAssertFalse(withBuf(annexB([sps720, pps, recoveryNow, pSlice])) { H264SPS.isRandomAccessEntry(fromAnnexB: $0) })
+        XCTAssertFalse(withBuf(annexB([sps720, pps, recoveryNow, iSlice, pSlice])) {
+            H264SPS.isRandomAccessEntry(fromAnnexB: $0)
+        })
+    }
+
+    func testRecoveryFrameCountParsesTheMessage() {
+        XCTAssertEqual(H264SPS.recoveryFrameCount(seiRBSP: [0x06, 0x01, 0xc4, 0x80]), 0)
+        XCTAssertEqual(H264SPS.recoveryFrameCount(seiRBSP: [0x06, 0x01, 0x71, 0x80]), 2)
+        XCTAssertNil(H264SPS.recoveryFrameCount(seiRBSP: [0x05, 0x02, 0xaa, 0xbb, 0x80]))
+        XCTAssertNil(H264SPS.recoveryFrameCount(seiRBSP: [0x06, 0x09, 0xc4]))  // size past the end
     }
 
-    // #133 join gate: the decodable-access-unit predicate needs SPS + PPS + IDR all present.
-    // A recovery-point AU (params present, but slice is non-IDR) must NOT satisfy it.
     func testExtractSPSandPPSStillSucceedsOnRecoveryPointAU() {
-        let au = annexB([sps720, pps, [0x41, 0x9a]])
+        let au = annexB([sps720, pps, recoveryNow, iSlice])
         let got = withBuf(au) { H264SPS.extractSPSandPPS(fromAnnexB: $0) }
-        XCTAssertNotNil(got)                                    // params are there
+        XCTAssertNotNil(got)
         XCTAssertEqual(H264SPS.dimensions(fromNAL: got!.sps)?.width, 1280)
-        XCTAssertFalse(withBuf(au) { H264SPS.containsIDR(fromAnnexB: $0) }) // but no IDR -> gate stays closed
     }
 
     // MARK: - #150 frame_mbs_only_flag fallback

From 843c688d04b25e9f8fa233b9e0850cce243ca480 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 20:25:18 +0200
Subject: [PATCH 104/359] fix(live): a join without an entry point goes to the
 software path after one wait (AE#627)

A live join whose keyframe wait read video for the full 15 s and found no
picture the native route can open (gradual intra refresh, or no key flags at
all) reopened into the same bitstream three times before the host heard
anything, about a minute of black ending in a dead session.

On the session's first join (no segment ever produced) with video arriving,
the engine now skips the reopens and takes the AE#561 rung: the session is
rebuilt on the software path, which decodes through such a stream. When the
host declined that rung, or it is not on offer, the join ends as
liveSourceReset right away. A starvation after segments were produced, or a
wait that saw no video, keeps its reopens.

Measured with aetherctl against a real-time intra-refresh feed: before,
three gate timeouts and exit 2; after, the software path plays from t=20;
with --no-sw-escalation, liveSourceReset after the first wait.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 CHANGELOG.md                                  | 12 +++-
 .../AetherEngine/AetherEngine+Loading.swift   | 31 ++++++++++
 .../AetherEngine+SoftwarePathEscalation.swift |  5 +-
 .../Native/SoftwarePathEscalation.swift       |  8 ++-
 .../Video/HLSSegmentProducer.swift            | 11 ++++
 .../Video/HLSVideoEngine+LiveReopen.swift     | 34 +++++++++-
 .../AetherEngine/Video/HLSVideoEngine.swift   |  5 ++
 .../LiveJoinWithoutEntryPointTests.swift      | 62 +++++++++++++++++++
 docs/api.md                                   |  4 +-
 9 files changed, 167 insertions(+), 5 deletions(-)
 create mode 100644 Tests/AetherEngineTests/LiveJoinWithoutEntryPointTests.swift

diff --git a/CHANGELOG.md b/CHANGELOG.md
index cb9eba88f..b8b9d27c5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,7 +10,17 @@ the public-API contract.
 
 ## [Unreleased]
 
-_Nothing yet._
+### Fixed
+
+- **A live H.264 join opens on an intra recovery point, not only on an IDR.** Feeds whose encoder
+  never sends an IDR (entry points are I-pictures behind a recovery point SEI with
+  `recovery_frame_cnt` 0) never started on the native route; the join gate refused every entry
+  point and gave up after three 15 s reopen cycles (AE#627).
+- **A live join that finds no entry point at all goes to the software path after one wait**, instead
+  of three reopen cycles into the same bitstream, or to `liveSourceReset` when the host declined
+  that rung (AE#627).
+- **The keyframe wait log counts the keyframes it dropped** (`keyframes=N`), so a gate refusing
+  every entry point no longer reads as a feed without keyframes (AE#627).
 
 ## [7.17.0] - 2026-09-25
 
diff --git a/Sources/AetherEngine/AetherEngine+Loading.swift b/Sources/AetherEngine/AetherEngine+Loading.swift
index 81a4699c8..0822dff41 100644
--- a/Sources/AetherEngine/AetherEngine+Loading.swift
+++ b/Sources/AetherEngine/AetherEngine+Loading.swift
@@ -1003,6 +1003,37 @@ extension AetherEngine {
                 self.liveSourceReset.send()
             }
         }
+        // AE#627: the first join found no entry point the native route can open. Reopening joins the
+        // same bitstream, so the session goes to the software path, or straight to the host when
+        // that rung is not on offer, instead of spending three 15 s reopen cycles first.
+        session.onLiveJoinWithoutEntryPoint = { [weak self, weak session] in
+            Task { @MainActor in
+                guard let self, let session, self.nativeVideoSession === session else { return }
+                let request = SoftwarePathEscalation.Request(
+                    domain: SoftwarePathEscalation.liveJoinErrorDomain,
+                    code: 0,
+                    message: "live join found no entry point the native route can open",
+                    positionSeconds: 0
+                )
+                let offered = SoftwarePathEscalation.shouldEscalate(
+                    errorDomain: request.domain,
+                    availability: SoftwarePathEscalation.Availability(
+                        alreadyEscalated: self.softwarePathEscalationBudget.isSpent,
+                        preferredDecodePath: self.loadedOptions.preferredDecodePath,
+                        nativeRemoteHLS: self.loadedOptions.nativeRemoteHLS,
+                        hostAllowsEscalation: self.loadedOptions.escalatesToSoftwarePath))
+                guard offered else {
+                    EngineLog.emit(
+                        "[AetherEngine] AE#627 software path not on offer for this session; "
+                        + "handing the join failure to the host",
+                        category: .session
+                    )
+                    session.giveUpLiveJoinWithoutEntryPoint()
+                    return
+                }
+                await self.escalateToSoftwarePath(request)
+            }
+        }
         // #126: zero-progress VOD pump death (readError before any packet/segment), and #169:
         // mid-session readError after the revive cap. Without this the host sees
         // isPlayable=true / a stalled item and waits until its own timeout.
diff --git a/Sources/AetherEngine/AetherEngine+SoftwarePathEscalation.swift b/Sources/AetherEngine/AetherEngine+SoftwarePathEscalation.swift
index ce6abbc1b..c0fee08c9 100644
--- a/Sources/AetherEngine/AetherEngine+SoftwarePathEscalation.swift
+++ b/Sources/AetherEngine/AetherEngine+SoftwarePathEscalation.swift
@@ -39,8 +39,11 @@ extension AetherEngine {
         let supersededGeneration = loadGeneration
         let duringStartup = waitingLoadGenerations.contains(supersededGeneration)
 
+        let verdict = request.domain == SoftwarePathEscalation.liveJoinErrorDomain
+            ? "the native route cannot open this live bitstream"
+            : "AVPlayer refused the media (\(request.domain)/\(request.code))"
         EngineLog.emit(
-            "[AetherEngine] #561 AVPlayer refused the media (\(request.domain)/\(request.code)) at "
+            "[AetherEngine] #561 \(verdict) at "
             + "\(String(format: "%.2f", request.positionSeconds))s; rebuilding this session on the "
             + "software path, which decodes it with libavcodec instead"
             + (duringStartup ? " (the waiting load follows it)" : "") + ": \(request.message)",
diff --git a/Sources/AetherEngine/Native/SoftwarePathEscalation.swift b/Sources/AetherEngine/Native/SoftwarePathEscalation.swift
index 586a76f70..84a96b711 100644
--- a/Sources/AetherEngine/Native/SoftwarePathEscalation.swift
+++ b/Sources/AetherEngine/Native/SoftwarePathEscalation.swift
@@ -96,6 +96,12 @@ enum SoftwarePathEscalation {
     /// The domain of a media failure, i.e. AVFoundation could not make sense of what it was served.
     static let mediaErrorDomain = "CoreMediaErrorDomain"
 
+    /// AE#627: a live join that read video for the whole keyframe wait and found no picture the native
+    /// route can open a segment on (a feed without IDRs or recovery points, or with gradual refresh
+    /// only). Like a CoreMedia failure it is a verdict on the media, and libavcodec starts on such a
+    /// stream by decoding through it.
+    static let liveJoinErrorDomain = "AetherEngine.LiveJoin"
+
     /// Whether a failed native item is worth handing to the engine's own decoder.
     ///
     /// The domain is the discriminator. A CoreMedia failure is a verdict on the MEDIA, which is the
@@ -111,6 +117,6 @@ enum SoftwarePathEscalation {
         guard availability.preferredDecodePath == .automatic else { return false }
         // The bypass has no local muxer and decodes nothing here, so #461 ignores the option anyway.
         guard !availability.nativeRemoteHLS else { return false }
-        return errorDomain == mediaErrorDomain
+        return errorDomain == mediaErrorDomain || errorDomain == liveJoinErrorDomain
     }
 }
diff --git a/Sources/AetherEngine/Video/HLSSegmentProducer.swift b/Sources/AetherEngine/Video/HLSSegmentProducer.swift
index b1ef49640..0a3cf7c2c 100644
--- a/Sources/AetherEngine/Video/HLSSegmentProducer.swift
+++ b/Sources/AetherEngine/Video/HLSSegmentProducer.swift
@@ -871,6 +871,14 @@ final class HLSSegmentProducer: @unchecked Sendable {
         defer { packetCounterLock.unlock() }
         return _lastPregateDroppedKeyframePts
     }
+    /// AE#627: video packets the gate dropped before a keyframe starvation ended the pump. Non-zero
+    /// means the source delivered video for the whole wait and none of it could open a segment.
+    private var _starvedVideoDrops = 0
+    var starvedVideoDrops: Int {
+        packetCounterLock.lock()
+        defer { packetCounterLock.unlock() }
+        return _starvedVideoDrops
+    }
     var hasRestartTarget: Bool { restartTargetVideoPts != Int64.min }
     private func markVideoGateOpened() {
         packetCounterLock.lock()
@@ -3527,6 +3535,9 @@ final class HLSSegmentProducer: @unchecked Sendable {
                                     + "exiting pump for reopen",
                                     category: .session
                                 )
+                                packetCounterLock.lock()
+                                _starvedVideoDrops = pregateVideoDropCount
+                                packetCounterLock.unlock()
                                 exitReason = .keyframeStarvation
                                 break readLoop
                             }
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine+LiveReopen.swift b/Sources/AetherEngine/Video/HLSVideoEngine+LiveReopen.swift
index 9d874ba0a..0bbc3b580 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine+LiveReopen.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine+LiveReopen.swift
@@ -155,6 +155,27 @@ extension HLSVideoEngine {
         }
     }
 
+    /// AE#627: a keyframe starvation on the session's FIRST join (no segment ever produced) while video
+    /// kept arriving says the bitstream has no entry point this route accepts, not that the link
+    /// hiccupped. The same starvation after segments were produced is a mid-session loss and keeps its
+    /// reopens, and a wait that saw no video at all is a source problem a reopen can fix.
+    static func liveJoinFoundNoEntryPoint(
+        reason: HLSSegmentProducer.PumpExitReason,
+        segmentsProduced: Int,
+        starvedVideoDrops: Int
+    ) -> Bool {
+        guard case .keyframeStarvation = reason else { return false }
+        return segmentsProduced == 0 && starvedVideoDrops > 0
+    }
+
+    /// AE#627: the engine's answer to `onLiveJoinWithoutEntryPoint` when the software path is not on
+    /// offer. The reopens this skipped would have ended here too, a minute later.
+    func giveUpLiveJoinWithoutEntryPoint() {
+        escalateLiveReopenExhaustion(transport: Self.liveReopenTransport(
+            sourceReopenableByURL: sourceReopenableByURL,
+            hasCustomSourceReopenFactory: customSourceReopenFactory != nil))
+    }
+
     /// The whole escalation, so the two exhaustion sites (barren-cycle cap, reopen attempt cap)
     /// cannot drift apart: the decision plus BOTH of its effects. The halt is the half that is easy
     /// to lose, and losing it is what the -15410 zombie is made of; onLiveSourceReset alone (what
@@ -359,8 +380,19 @@ extension HLSVideoEngine {
                 return
             }
         }
-        restartLock.lock()
         let segmentsNow = provider?.liveContinuationPoint().nextIndex ?? 0
+        if let onLiveJoinWithoutEntryPoint,
+           Self.liveJoinFoundNoEntryPoint(
+               reason: reason, segmentsProduced: segmentsNow, starvedVideoDrops: prod.starvedVideoDrops) {
+            EngineLog.emit(
+                "[HLSVideoEngine] AE#627 live join read \(prod.starvedVideoDrops) video packets without an "
+                + "entry point the native route can open; a reopen joins the same bitstream, so not reopening",
+                category: .session
+            )
+            onLiveJoinWithoutEntryPoint()
+            return
+        }
+        restartLock.lock()
         let reopenDecision = Self.liveRecoveryBudgetDecision(
             progressIndex: segmentsNow,
             lastProgressIndex: lastReopenSegmentCount,
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine.swift b/Sources/AetherEngine/Video/HLSVideoEngine.swift
index 3f2ee300d..2af7a3391 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine.swift
@@ -630,6 +630,11 @@ public final class HLSVideoEngine: @unchecked Sendable {
     var onPlaylistShiftRebased: (@Sendable (Double, Double) -> Void)?
     /// Fires on `PumpExitReason.sourceReplay`; host must re-negotiate a fresh session.
     var onLiveSourceReset: (@Sendable () -> Void)?
+    /// AE#627: the first join read video for the whole keyframe wait and found no point the native
+    /// route can open a segment on. Reopening joins the same bitstream, so the engine decides between
+    /// the software path and telling the host (`escalateLiveReopenExhaustion`) instead. Unset, the
+    /// session falls back to the ordinary reopen budget.
+    var onLiveJoinWithoutEntryPoint: (@Sendable () -> Void)?
     /// #126: fires when a VOD pump dies on a read error having produced nothing (zero packets
     /// written, empty cache). The playlist exists but no segment will ever land, so AVPlayer
     /// would sit in waitingToPlay forever; the engine surfaces a fatal error instead.
diff --git a/Tests/AetherEngineTests/LiveJoinWithoutEntryPointTests.swift b/Tests/AetherEngineTests/LiveJoinWithoutEntryPointTests.swift
new file mode 100644
index 000000000..002fe60fc
--- /dev/null
+++ b/Tests/AetherEngineTests/LiveJoinWithoutEntryPointTests.swift
@@ -0,0 +1,62 @@
+// AE#627: a live join that reads video for the whole keyframe wait and finds nothing the native route
+// can open a segment on. Reopening joins the same bitstream, so three barren cycles bought a minute of
+// black before the host heard anything. The first join now goes to the software path, or to the host.
+import Foundation
+import Testing
+@testable import AetherEngine
+
+@Suite("Live join without an entry point (AE#627)")
+struct LiveJoinWithoutEntryPointTests {
+
+    @Test("A first join that starved while video kept arriving has no entry point")
+    func firstJoinStarvedOnVideo() {
+        #expect(HLSVideoEngine.liveJoinFoundNoEntryPoint(
+            reason: .keyframeStarvation, segmentsProduced: 0, starvedVideoDrops: 794))
+    }
+
+    /// Segments exist, so the bitstream had an entry point once: this is a mid-session loss, which
+    /// is what the reopen budget is for.
+    @Test("A starvation after segments were produced keeps its reopens")
+    func laterStarvationReopens() {
+        #expect(!HLSVideoEngine.liveJoinFoundNoEntryPoint(
+            reason: .keyframeStarvation, segmentsProduced: 12, starvedVideoDrops: 794))
+    }
+
+    /// No video arrived at all, so nothing is known about the bitstream and a reopen may well help.
+    @Test("A wait that saw no video is not a verdict on the bitstream")
+    func noVideoIsNotAVerdict() {
+        #expect(!HLSVideoEngine.liveJoinFoundNoEntryPoint(
+            reason: .keyframeStarvation, segmentsProduced: 0, starvedVideoDrops: 0))
+    }
+
+    @Test("Other pump exits are not a join without an entry point")
+    func otherExits() {
+        for reason: HLSSegmentProducer.PumpExitReason in [.eof, .readError(code: -5), .segmentStall] {
+            #expect(!HLSVideoEngine.liveJoinFoundNoEntryPoint(
+                reason: reason, segmentsProduced: 0, starvedVideoDrops: 794))
+        }
+    }
+
+    private static func availability(hostAllows: Bool = true, path: DecodePath = .automatic)
+        -> SoftwarePathEscalation.Availability {
+        SoftwarePathEscalation.Availability(
+            alreadyEscalated: false, preferredDecodePath: path, nativeRemoteHLS: false,
+            hostAllowsEscalation: hostAllows)
+    }
+
+    @Test("The join verdict is offered the software path like a media failure")
+    func joinVerdictEscalates() {
+        #expect(SoftwarePathEscalation.shouldEscalate(
+            errorDomain: SoftwarePathEscalation.liveJoinErrorDomain, availability: Self.availability()))
+    }
+
+    @Test("A host that declined the rung, or a session already on software, is not escalated")
+    func declinedOrPinned() {
+        #expect(!SoftwarePathEscalation.shouldEscalate(
+            errorDomain: SoftwarePathEscalation.liveJoinErrorDomain,
+            availability: Self.availability(hostAllows: false)))
+        #expect(!SoftwarePathEscalation.shouldEscalate(
+            errorDomain: SoftwarePathEscalation.liveJoinErrorDomain,
+            availability: Self.availability(path: .software)))
+    }
+}
diff --git a/docs/api.md b/docs/api.md
index 09c80402e..452586962 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -132,6 +132,8 @@ The event fires the moment the rebuild is taken and carries the failure it absor
 
 A host that re-plans a failing title with a ladder of its own (a transcode rung, a second player) sets `escalatesToSoftwarePath = false` and gets the failure as `.error` instead, as before 7.9.0. It is a tuning field, correctable through `reloadAtCurrentPosition(applying:)`.
 
+A live join takes the same rung when the source delivers video for the whole keyframe wait (15 s) and none of it is a picture the native route can open a segment on: no IDR and no recovery point with `recovery_frame_cnt` 0, which is what a feed carrying only gradual intra refresh looks like (AE#627). Reopening would join the same bitstream, so the first join does not spend its reopen cycles on it. The absorbed failure carries the domain `AetherEngine.LiveJoin`. With `escalatesToSoftwarePath = false`, or when the rung is not on offer, the join ends as `liveSourceReset` at that point, as the reopen cycles would have ended it a minute later. A starvation after the session has produced segments keeps its reopens.
+
 ### The audio tap ends with its session
 
 `installAudioTap()` returns an `AsyncStream<AudioTapBuffer>` bound to the session it was installed against. It finishes on `load()`, on `stop()`, and on a **session-preserving reload**: an audio-track switch, a subtitle-track switch, a disc-title switch, `reloadAtCurrentPosition()`. Re-install on stream end to follow the new session (#356). This is deliberate rather than a gap: each install gets a fresh monotonic filter, so the new session's timeline starts clean instead of stitched across a reload that resumes slightly behind the old position.
@@ -962,7 +964,7 @@ All flags default to safe values; the table is the full set. Depth for the media
 | `forceDolbyVisionOnNonDVDisplay` | false | **Experimental (AE#455).** On a display with no Dolby Vision of its own, serve an HEVC Profile 8.1 source the way a Profile 5 source is served (`dvh1` sample entry, `dvcC` rewritten to profile 5 / compatibility 0, `CODECS="dvh1.05.LL"`), so AVPlayer composes the RPU itself instead of handing the panel the static-metadata HDR10 base layer. The bitstream is untouched; only the container's claim about it changes. Ignored on a display that does Dolby Vision, and Profile 8.1 only. See [formats.md](formats.md#dolby-vision-signaling) for what it buys and what it risks. |
 | `dolbyVisionHandling` | `.automatic` | A `DolbyVisionHandling`. `.baseLayerOnly` presents the HDR10 / HLG base layer of a Dolby Vision source and leaves the Dolby Vision out of the container on every display: plain `hvc1` / `av01` sample entry, `dvcC` stripped, no `SUPPLEMENTAL-CODECS`, HDR10 / HLG display criteria, `videoFormat` reads the base layer's format while `sourceVideoFormat` and `sourceDVProfile` keep saying what the file carries. The route a host offers as "Dolby Vision: off (HDR10)", for a source whose Dolby Vision is wrong and whose base layer is right: the reported shape is a remux carrying a Profile 7 RPU under a container record claiming Profile 5, where a player that believes the record decodes YCbCr as IPT and the picture comes out green / violet. Applies to HEVC Profile 7 / 8.1 / 8.4, AV1 Profile 10.1 / 10.4, and a Profile 5 (or AV1 10.0) record whose VUI declares a BT.2020 YCbCr PQ or HLG base; a Profile 5 whose VUI is unspecified carries IPT-PQ-c2, has no base layer to present, keeps its route, and the engine says so in the log. Takes precedence over `forceDolbyVisionOnNonDVDisplay`. A tuning field, correctable through `reloadAtCurrentPosition(applying:)`; a Profile 5 record the VUI contradicts also stops refusing the software path under it. See [formats.md](formats.md#dolby-vision-signaling). |
 | `preferredDecodePath` | `.automatic` | A `DecodePath`. `.software` serves this source through `SoftwarePlaybackHost` whatever the routing concluded, scoped to this session and costing the source nothing (seeks, the audio switch and the title switch all keep working). The escape for the formats `VTCapabilityProbe` deliberately cannot classify, and for live H.264 / HEVC, which never reaches that gate at all. One-way: there is no `.native`. See [Overriding the decode path](#overriding-the-decode-path). |
-| `escalatesToSoftwarePath` | `true` | Whether a native session AVPlayer refuses on its merits (`CoreMediaErrorDomain`) may be rebuilt once on the software path (AE#561). `false` surfaces the failure as `.error` instead, for a host with its own fallback ladder (AE#629). Correctable. |
+| `escalatesToSoftwarePath` | `true` | Whether a native session AVPlayer refuses on its merits (`CoreMediaErrorDomain`), or a live join without an entry point the native route can open (`AetherEngine.LiveJoin`, AE#627), may be rebuilt once on the software path (AE#561). `false` surfaces the failure as `.error` instead, for a host with its own fallback ladder (AE#629). Correctable. |
 | `deinterlaceMode` | `.auto` | A `DeinterlaceMode` for the software path: the Metal / VideoToolbox graph with a CPU bwdif fallback, or `.software` to force the CPU path. |
 | `deinterlaceFieldRate` | `.field` | A `DeinterlaceFieldRate`: the hardware deinterlacer emits one frame per field (25i to 50p) or per frame. The software fallback is always frame rate, because doubling a CPU bwdif is the wrong trade and a fallback should not change cost class. |
 | `probesize`, `maxAnalyzeDuration` | nil | Caller-bounded open-time probe budget (defaults 50 MB / 60 s). They fail **open**: an over-tight budget loads with late-resolving tracks silently missing rather than throwing, so validate track presence if you tighten them. Do not pass `0` for `maxAnalyzeDuration`; FFmpeg maps it to a shorter heuristic. |

From d5aacea7e4e694f5b6c6826781ccfa612d81fd97 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 20:34:12 +0200
Subject: [PATCH 105/359] test(h264): build the three-byte start code AU
 stepwise so CI type-checks it (AE#627)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 Tests/AetherEngineTests/H264SPSTests.swift | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/Tests/AetherEngineTests/H264SPSTests.swift b/Tests/AetherEngineTests/H264SPSTests.swift
index 326f12de0..e0bc14182 100644
--- a/Tests/AetherEngineTests/H264SPSTests.swift
+++ b/Tests/AetherEngineTests/H264SPSTests.swift
@@ -71,7 +71,12 @@ final class H264SPSTests: XCTestCase {
 
     func testEntryHandlesThreeByteStartCodes() {
         let sc3: [UInt8] = [0, 0, 1]
-        let au = sc3 + sps720 + sc3 + pps + sc3 + [0x65, 0x88]
+        var au: [UInt8] = sc3
+        au += sps720
+        au += sc3
+        au += pps
+        au += sc3
+        au += [0x65, 0x88]
         XCTAssertTrue(withBuf(au) { H264SPS.isRandomAccessEntry(fromAnnexB: $0) })
     }
 

From d2fc59ee3c2223a751e6a138197c0169960abdb3 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 22:10:28 +0200
Subject: [PATCH 106/359] chore(deps): FFmpegBuild 3.6.0, MPEG-TS audio PIDs
 identified by payload (#641)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 Package.resolved | 6 +++---
 Package.swift    | 2 +-
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/Package.resolved b/Package.resolved
index a1d7314dc..701c31d10 100644
--- a/Package.resolved
+++ b/Package.resolved
@@ -1,13 +1,13 @@
 {
-  "originHash" : "e94fafbbd57b5e0ee24b958be3a6afe9445a45324b3568a74666e25dd9342513",
+  "originHash" : "aaad2851e63fbb5d8035f6ae9c6abb71e8e010beeeb30d2f9dbbe60ccd7022f6",
   "pins" : [
     {
       "identity" : "ffmpegbuild",
       "kind" : "remoteSourceControl",
       "location" : "https://github.com/superuser404notfound/FFmpegBuild",
       "state" : {
-        "revision" : "dcc8041eeeb08aedceb1b053f2a03a27fd12020a",
-        "version" : "3.5.0"
+        "revision" : "fda08325455bc12c112b5b82d014b98fa0fee0be",
+        "version" : "3.6.0"
       }
     },
     {
diff --git a/Package.swift b/Package.swift
index 4e2e0f2a1..93358b68a 100644
--- a/Package.swift
+++ b/Package.swift
@@ -38,7 +38,7 @@ let package = Package(
         // rebuilds still reach existing tags, which is where a pure rebuild
         // belongs; anything that adds slices or enables a component is a minor
         // and reaches consumers through an engine release.
-        .package(url: "https://github.com/superuser404notfound/FFmpegBuild", .upToNextMinor(from: "3.5.0")),  // 3.5.0: FFmpeg n8.1.3, 268 upstream commits over n8.1.2, of which six touch code this engine ships: VP9 kept `next_refs[]` referenced across `avcodec_flush_buffers()`, so a worker could reseed its references from the pre-flush set and the first inter frame after a seek decoded against released buffers (heap OOB read and write, and this engine decodes VP9 with frame threading and flushes on every reposition); the Dolby Vision RPU parser trims trailing zero padding again, which n8.1.2 had stopped doing, so a padded RPU no longer fails the ext-block size check and loses its dynamic metadata, and the RPU partition counts are bounded; a VC-1 picture ending on a one-bit skipped macroblock keeps that macroblock instead of falling into error concealment; the `dca_core` bsf clears the profile it has just stripped; and a container channel layout survives a failed decoder open during probing. Same dav1d 1.5.4, zimg 3.0.6 and libzvbi 0.2.45 (all current upstream), same component set, same six local patches, unchanged soname majors; 3.4.0: FFmpeg learns the `dav1` sample entry in both directions, the AV1 variant of `av01` that signals Dolby Vision, so a Profile 10.0 source can be read at all and can be remuxed with the tag its packaging requires; stock FFmpeg has it in neither of its two mp4 tag tables, so the read probes as "unknown codec" and the write fails EINVAL (#547); same n8.1.2 binaries as 3.3.0 otherwise, compiled against the Xcode 27 SDKs with unchanged deployment targets; 3.3.0: every slice a shipped app can embed carries its dSYM inside the xcframework, so Xcode copies it into `.xcarchive/dSYMs` and a crash inside FFmpeg symbolicates instead of staying a list of addresses (FFmpegBuild#4); same n8.1.2 binaries as 3.2.1 apart from their UUID, the libraries just compile with `-gline-tables-only` now and the debug map is harvested before the shipped binary is stripped; 3.2.1: vc1_parser seeds its parse context from extradata, so a seek landing on an entry point alone keeps its picture size instead of falling back to 0x0 or to a size read out of the following payload (#490, FFmpeg PR 24458); 3.2.0: the legacy Flash tail, video and audio together (flv1 / vp6 / vp6f / vp6a, nellymoser, adpcm_swf, speex, and FLV's pcm_s16be / pcm_u8 / pcm_alaw / pcm_mulaw), so a pre-2008 .flv plays with sound where before only H.264-in-FLV did; flashsv stays out, it needs zlib and would have been dropped silently; 3.1.0: native .wmv / .asf, the asf demuxer plus every WMA decoder (Standard, Pro, Lossless, Voice), which is the container half of the legacy Microsoft support 2.4.3 started (FFmpegBuild#3); 3.0.0: every target, product, framework bundle and install name carries an `Aether` prefix, so this build can sit in an app that already has an FFmpeg (FFmpegKit, MobileVLCKit, mpv); same n8.1.2 binaries as 2.5.0, only names changed; 2.5.0: libzvbi 0.2.45 for GHSA-86rm-g7qf-j2fh (OOB read/write + integer underflow, reachable through the libzvbi_teletext decoder), dav1d 1.5.4, zimg 3.0.6, and the concat demuxer removed (a script demuxer selectable by probing alone, which made any stream a potential file-open primitive); 2.4.3: the legacy Microsoft video decoders (msmpeg4v1/v2/v3, wmv1/wmv2/wmv3; FFmpegBuild#3); 2.4.2: pgssubdec missing-palette recovery, replaces the 2.1.1 Epoch-Continue retain (#142); 2.4.1: qtrle decoder; 2.4.0: visionOS (xros) device + simulator slices; 2.3.0: webvtt demuxer (standalone .vtt sidecars, plus the cue settings as packet side data); 2.2.0: matroska TTS warn-only per RFC 9559 (#145 rework); 2.1.3: sup demuxer (raw PGS sidecars); 2.1.2: matroska TrackTimestampScale clamp (#145, dropped in 2.2.0); 2.1.1: pgssubdec Epoch-Continue retain (#142); 2.1.0: yadif_videotoolbox + hwupload (Metal GPU deinterlace); 2.0.0: dynamic frameworks (LGPL), zvbi GPL excision
+        .package(url: "https://github.com/superuser404notfound/FFmpegBuild", .upToNextMinor(from: "3.6.0")),  // 3.6.0: an MPEG-TS audio PID is identified by its payload when its label does not name the codec: the raw dts / truehd / loas demuxers are in, so the mpegts content probe can confirm DTS, TrueHD and LATM at all (without them the lenient mp3 probe named the track, whatever the label), and a PID labelled 0x03 (MPEG-1 audio) gets the same content probe as 0x04; a DTS-HD IPTV channel opened as mp3 and never produced a frame (#641); same n8.1.3 otherwise; 3.5.0: FFmpeg n8.1.3, 268 upstream commits over n8.1.2, of which six touch code this engine ships: VP9 kept `next_refs[]` referenced across `avcodec_flush_buffers()`, so a worker could reseed its references from the pre-flush set and the first inter frame after a seek decoded against released buffers (heap OOB read and write, and this engine decodes VP9 with frame threading and flushes on every reposition); the Dolby Vision RPU parser trims trailing zero padding again, which n8.1.2 had stopped doing, so a padded RPU no longer fails the ext-block size check and loses its dynamic metadata, and the RPU partition counts are bounded; a VC-1 picture ending on a one-bit skipped macroblock keeps that macroblock instead of falling into error concealment; the `dca_core` bsf clears the profile it has just stripped; and a container channel layout survives a failed decoder open during probing. Same dav1d 1.5.4, zimg 3.0.6 and libzvbi 0.2.45 (all current upstream), same component set, same six local patches, unchanged soname majors; 3.4.0: FFmpeg learns the `dav1` sample entry in both directions, the AV1 variant of `av01` that signals Dolby Vision, so a Profile 10.0 source can be read at all and can be remuxed with the tag its packaging requires; stock FFmpeg has it in neither of its two mp4 tag tables, so the read probes as "unknown codec" and the write fails EINVAL (#547); same n8.1.2 binaries as 3.3.0 otherwise, compiled against the Xcode 27 SDKs with unchanged deployment targets; 3.3.0: every slice a shipped app can embed carries its dSYM inside the xcframework, so Xcode copies it into `.xcarchive/dSYMs` and a crash inside FFmpeg symbolicates instead of staying a list of addresses (FFmpegBuild#4); same n8.1.2 binaries as 3.2.1 apart from their UUID, the libraries just compile with `-gline-tables-only` now and the debug map is harvested before the shipped binary is stripped; 3.2.1: vc1_parser seeds its parse context from extradata, so a seek landing on an entry point alone keeps its picture size instead of falling back to 0x0 or to a size read out of the following payload (#490, FFmpeg PR 24458); 3.2.0: the legacy Flash tail, video and audio together (flv1 / vp6 / vp6f / vp6a, nellymoser, adpcm_swf, speex, and FLV's pcm_s16be / pcm_u8 / pcm_alaw / pcm_mulaw), so a pre-2008 .flv plays with sound where before only H.264-in-FLV did; flashsv stays out, it needs zlib and would have been dropped silently; 3.1.0: native .wmv / .asf, the asf demuxer plus every WMA decoder (Standard, Pro, Lossless, Voice), which is the container half of the legacy Microsoft support 2.4.3 started (FFmpegBuild#3); 3.0.0: every target, product, framework bundle and install name carries an `Aether` prefix, so this build can sit in an app that already has an FFmpeg (FFmpegKit, MobileVLCKit, mpv); same n8.1.2 binaries as 2.5.0, only names changed; 2.5.0: libzvbi 0.2.45 for GHSA-86rm-g7qf-j2fh (OOB read/write + integer underflow, reachable through the libzvbi_teletext decoder), dav1d 1.5.4, zimg 3.0.6, and the concat demuxer removed (a script demuxer selectable by probing alone, which made any stream a potential file-open primitive); 2.4.3: the legacy Microsoft video decoders (msmpeg4v1/v2/v3, wmv1/wmv2/wmv3; FFmpegBuild#3); 2.4.2: pgssubdec missing-palette recovery, replaces the 2.1.1 Epoch-Continue retain (#142); 2.4.1: qtrle decoder; 2.4.0: visionOS (xros) device + simulator slices; 2.3.0: webvtt demuxer (standalone .vtt sidecars, plus the cue settings as packet side data); 2.2.0: matroska TTS warn-only per RFC 9559 (#145 rework); 2.1.3: sup demuxer (raw PGS sidecars); 2.1.2: matroska TrackTimestampScale clamp (#145, dropped in 2.2.0); 2.1.1: pgssubdec Epoch-Continue retain (#142); 2.1.0: yadif_videotoolbox + hwupload (Metal GPU deinterlace); 2.0.0: dynamic frameworks (LGPL), zvbi GPL excision
         // Pure-Swift SMB2 client (MIT) that speaks the protocol over
         // NWConnection. Replaces AMSMB2/libsmb2, which EPERMs on tvOS/iOS.
         // Pinned to the 0.3.x minor: SMBClient is pre-1.0 with an actively

From b6da4c95066e0f5fecdf7fc3dfde11836d4f0b19 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 22:24:07 +0200
Subject: [PATCH 107/359] fix(live): a live bridge that decodes nothing
 rebuilds the session video-only (AE#641)

A FLAC bridge builds its sample entry from the encoder's extradata, so on
live a bridge that decoded nothing reached no muxer death and no AE#396
arm: segments kept being cut with an audio track that never carried a
sample, and AVPlayer showed the first picture and waited on it for the
rest of the session (measured: t=5.40 s for 40 s, ranges=0, restarts=0).

AudioBridge now reports the decoder arm of structural silence once.
A live session hands it to the engine, which marks the stream
undecodable and rebuilds through the AE#629 takeover path (extracted
from the software escalation as startTakeoverRebuild). The rebuilt
cascade skips that stream and ends in its video-only tail, so
audioDelivery reads .droppedNoPipeline. The mark outlives the session's
own rebuilds and clears on a host load.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 CHANGELOG.md                                  |  10 ++
 .../AetherEngine+LiveAudioDrop.swift          |  50 ++++++++
 .../AetherEngine/AetherEngine+Loading.swift   |   9 ++
 .../AetherEngine+SoftwarePathEscalation.swift |  56 +++++----
 Sources/AetherEngine/AetherEngine.swift       |  13 ++-
 Sources/AetherEngine/Audio/AudioBridge.swift  |   8 ++
 Sources/AetherEngine/PlayerState.swift        |   8 +-
 .../Video/HLSVideoEngine+AudioRoute.swift     |  22 +++-
 .../AetherEngine/Video/HLSVideoEngine.swift   |   9 ++
 .../Issue641LiveUndecodableAudioTests.swift   | 110 ++++++++++++++++++
 docs/api.md                                   |  11 +-
 11 files changed, 270 insertions(+), 36 deletions(-)
 create mode 100644 Sources/AetherEngine/AetherEngine+LiveAudioDrop.swift
 create mode 100644 Tests/AetherEngineTests/Issue641LiveUndecodableAudioTests.swift

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b8b9d27c5..0a9862c15 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -19,6 +19,16 @@ the public-API contract.
 - **A live join that finds no entry point at all goes to the software path after one wait**, instead
   of three reopen cycles into the same bitstream, or to `liveSourceReset` when the host declined
   that rung (AE#627).
+- **A live channel whose audio the bridge cannot decode plays video-only instead of stalling.** A
+  FLAC bridge builds its sample entry from the encoder's extradata, so a bridge that decoded nothing
+  left segments with an audio track that never carried a sample, and AVPlayer showed the first
+  picture and waited on it for the rest of the session. The engine now rebuilds the session without
+  that track and `audioDelivery` reads `.droppedNoPipeline` (AE#641).
+- **FFmpegBuild 3.6.0: an MPEG-TS audio PID is identified by its payload.** The raw `dts`, `truehd`
+  and `loas` demuxers were missing, so the mpegts content probe could never confirm DTS, TrueHD or
+  LATM and the lenient mp3 probe named the track; a PID labelled 0x03 (MPEG-1 audio) was not probed
+  at all. A DTS-HD IPTV channel opened as mp3, and every packet failed with "Header missing"
+  (AE#641).
 - **The keyframe wait log counts the keyframes it dropped** (`keyframes=N`), so a gate refusing
   every entry point no longer reads as a feed without keyframes (AE#627).
 
diff --git a/Sources/AetherEngine/AetherEngine+LiveAudioDrop.swift b/Sources/AetherEngine/AetherEngine+LiveAudioDrop.swift
new file mode 100644
index 000000000..e70c17648
--- /dev/null
+++ b/Sources/AetherEngine/AetherEngine+LiveAudioDrop.swift
@@ -0,0 +1,50 @@
+import Foundation
+
+/// AE#641: a live channel whose audio the bridge cannot decode plays video-only instead of stalling.
+///
+/// The load-time cascade already ends in video-only when no pipeline can be BUILT (AE#462). A bridge
+/// that is built and then decodes nothing reaches no such tail: on VOD the first segment cut fails
+/// and the session surfaces `audioBridgeProducedNoOutput` (AE#396), but a live FLAC bridge builds its
+/// sample entry from the encoder's extradata, so segments keep being cut with an audio track that
+/// never carries a sample. AVPlayer presents the first picture and waits on the audio for as long as
+/// the session lasts, with nothing surfaced. The reporter's channel was DTS-HD labelled as MPEG audio.
+///
+/// Nothing inside the session reaches it: a producer rebuild hands the same decoder the same bytes.
+/// So the session is rebuilt with that stream marked undecodable, the cascade takes its video-only
+/// tail, and `audioDelivery` reads `.droppedNoPipeline`, the fact a host ladder demotes on.
+extension AetherEngine {
+
+    /// What a load keeps of the undecodable stream: the session's own rebuilds keep it, which is
+    /// what keeps them video-only, and a host load is a new source and starts clean.
+    nonisolated static func undecodableAudioStreamIndexAcrossLoad(
+        _ current: Int32?, sessionPreservingReload: Bool
+    ) -> Int32? {
+        sessionPreservingReload ? current : nil
+    }
+
+    @MainActor
+    func dropUndecodableLiveAudio(streamIndex: Int32, bridgeSummary: String) async {
+        guard undecodableLiveAudioStreamIndex == nil else { return }
+        undecodableLiveAudioStreamIndex = streamIndex
+        EngineLog.emit(
+            "[AetherEngine] AE#641 the live audio bridge decoded nothing from stream \(streamIndex) "
+            + "(\(bridgeSummary)); rebuilding the session video-only instead of serving an audio "
+            + "track that will never be filled",
+            category: .engine
+        )
+        do {
+            try await startTakeoverRebuild { _ in }.value
+            EngineLog.emit(
+                "[AetherEngine] AE#641 rebuilt video-only, audio delivery = \(audioDelivery.rawValue)",
+                category: .engine)
+        } catch is CancellationError {
+            EngineLog.emit(
+                "[AetherEngine] AE#641 video-only rebuild superseded; nothing to do", category: .engine)
+        } catch {
+            EngineLog.emit(
+                "[AetherEngine] AE#641 video-only rebuild refused (\(error)); the session keeps its "
+                + "silent audio track",
+                category: .engine)
+        }
+    }
+}
diff --git a/Sources/AetherEngine/AetherEngine+Loading.swift b/Sources/AetherEngine/AetherEngine+Loading.swift
index 0822dff41..f323f8773 100644
--- a/Sources/AetherEngine/AetherEngine+Loading.swift
+++ b/Sources/AetherEngine/AetherEngine+Loading.swift
@@ -797,6 +797,7 @@ extension AetherEngine {
             matchContentEnabled: matchContentEnabled,
             panelIsInHDRMode: panelIsInHDRMode,
             audioSourceStreamIndexOverride: audioSourceStreamIndex,
+            undecodableAudioStreamIndex: undecodableLiveAudioStreamIndex,
             audioBridgeMode: audioBridgeMode,
             isLiveSession: isLive,
             dvrWindowSeconds: dvrWindowSeconds,
@@ -1034,6 +1035,14 @@ extension AetherEngine {
                 await self.escalateToSoftwarePath(request)
             }
         }
+        // AE#641: the live bridge decoded nothing, so the served media carries an audio track that
+        // will never be filled and AVPlayer waits on it forever. The session is rebuilt video-only.
+        session.onLiveAudioDecodesNothing = { [weak self, weak session] streamIndex, summary in
+            Task { @MainActor in
+                guard let self, let session, self.nativeVideoSession === session else { return }
+                await self.dropUndecodableLiveAudio(streamIndex: streamIndex, bridgeSummary: summary)
+            }
+        }
         // #126: zero-progress VOD pump death (readError before any packet/segment), and #169:
         // mid-session readError after the revive cap. Without this the host sees
         // isPlayable=true / a stalled item and waits until its own timeout.
diff --git a/Sources/AetherEngine/AetherEngine+SoftwarePathEscalation.swift b/Sources/AetherEngine/AetherEngine+SoftwarePathEscalation.swift
index c0fee08c9..232dd335e 100644
--- a/Sources/AetherEngine/AetherEngine+SoftwarePathEscalation.swift
+++ b/Sources/AetherEngine/AetherEngine+SoftwarePathEscalation.swift
@@ -33,11 +33,7 @@ extension AetherEngine {
         guard softwarePathEscalationBudget.take() else { return }
 
         let absorbed = Self.absorbedFailure(request)
-        // AE#629: a load() still waiting on this session's startup is about to be superseded by the
-        // rebuild's own. It follows the rebuild instead of unwinding, and the rebuild continues its
-        // #361 startup sequence rather than dropping the host's bar back to zero.
-        let supersededGeneration = loadGeneration
-        let duringStartup = waitingLoadGenerations.contains(supersededGeneration)
+        let duringStartup = waitingLoadGenerations.contains(loadGeneration)
 
         let verdict = request.domain == SoftwarePathEscalation.liveJoinErrorDomain
             ? "the native route cannot open this live bitstream"
@@ -54,23 +50,7 @@ extension AetherEngine {
             positionSeconds: request.positionSeconds,
             duringStartup: duringStartup))
 
-        let rebuild = Task { @MainActor in
-            // Both are armed where nothing can run before the rebuild's teardown consumes them, and
-            // withdrawn after, for the paths that never reach one (a correction refused up front).
-            // The takeover is only CLAIMED by that teardown, and only if the session it ends is still
-            // the one that failed: a rebuild refused before it tore anything down, or a host stop()
-            // that got in first, must leave the waiting load to unwind as the host's own.
-            // The failure's session is already gone: rebuilding now would tear down its successor.
-            guard self.loadGeneration == supersededGeneration else { throw CancellationError() }
-            if duringStartup { self.continueStartupAcrossReroute() }
-            self.softwarePathTakeoverArm = supersededGeneration
-            defer {
-                self.abandonStartupContinuation()
-                self.softwarePathTakeoverArm = nil
-            }
-            _ = try await self.reloadAtCurrentPosition { $0.preferredDecodePath = .software }
-        }
-        softwarePathRebuild = rebuild
+        let rebuild = startTakeoverRebuild { $0.preferredDecodePath = .software }
 
         do {
             try await rebuild.value
@@ -94,7 +74,37 @@ extension AetherEngine {
         }
     }
 
-    /// Called by a teardown about to end `loadGeneration`: when that teardown is the escalation's own
+    /// Start a rebuild of this session that the engine decided on itself (AE#561 software path, AE#641
+    /// video-only), in a shape a `load()` still waiting on the session's startup can follow.
+    ///
+    /// AE#629: that load is about to be superseded by the rebuild's own. It follows the rebuild instead
+    /// of unwinding, and the rebuild continues its #361 startup sequence rather than dropping the
+    /// host's bar back to zero.
+    @MainActor
+    func startTakeoverRebuild(applying change: @escaping @Sendable (inout LoadOptions) -> Void) -> Task<Void, Error> {
+        let supersededGeneration = loadGeneration
+        let duringStartup = waitingLoadGenerations.contains(supersededGeneration)
+        let rebuild = Task { @MainActor in
+            // Both are armed where nothing can run before the rebuild's teardown consumes them, and
+            // withdrawn after, for the paths that never reach one (a correction refused up front).
+            // The takeover is only CLAIMED by that teardown, and only if the session it ends is still
+            // the one that failed: a rebuild refused before it tore anything down, or a host stop()
+            // that got in first, must leave the waiting load to unwind as the host's own.
+            // The failure's session is already gone: rebuilding now would tear down its successor.
+            guard self.loadGeneration == supersededGeneration else { throw CancellationError() }
+            if duringStartup { self.continueStartupAcrossReroute() }
+            self.softwarePathTakeoverArm = supersededGeneration
+            defer {
+                self.abandonStartupContinuation()
+                self.softwarePathTakeoverArm = nil
+            }
+            _ = try await self.reloadAtCurrentPosition(applying: change)
+        }
+        softwarePathRebuild = rebuild
+        return rebuild
+    }
+
+    /// Called by a teardown about to end `loadGeneration`: when that teardown is the engine's own
     /// rebuild, a `load()` still waiting on the ended generation follows the rebuild (AE#629).
     @MainActor
     func claimSoftwarePathTakeover() {
diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index d7e92e967..5b412120f 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -2349,13 +2349,16 @@ public final class AetherEngine: ObservableObject {
     /// the next session's.
     var softwarePathEscalationBudget = SoftwarePathEscalation.Budget()
 
-    /// AE#629: the escalation rebuild in flight or finished, kept so a `load()` whose startup it
+    /// AE#629: the engine's own rebuild in flight or finished, kept so a `load()` whose startup it
     /// superseded can wait for it instead of throwing. Matched by generation, so a stale one is inert.
     var softwarePathTakeover: SoftwarePathEscalation.Takeover?
-    /// The escalation rebuild most recently started, and the generation it is armed to take over
+    /// The engine's own rebuild most recently started, and the generation it is armed to take over
     /// until its teardown claims it (see `claimSoftwarePathTakeover`).
     var softwarePathRebuild: Task<Void, Error>?
     var softwarePathTakeoverArm: UInt64?
+    /// AE#641: the live audio stream whose bridge decoded nothing in this session. It outlives the
+    /// session's own rebuilds, which is what keeps them video-only, and a host load clears it.
+    var undecodableLiveAudioStreamIndex: Int32?
     /// #65 final rung, storm shape: on a frozen live playlist each stage-2 reload replays the tail,
     /// re-stalls within seconds, and the fresh stall SUPERSEDES the ladder task before its
     /// post-reload rung can run, so the reload cycle alone would loop forever. This gate persists
@@ -3695,14 +3698,14 @@ public final class AetherEngine: ObservableObject {
                 audioSourceStreamIndex: audioSourceStreamIndex, discTitleID: discTitleID,
                 attempt: attempt)
         } catch is CancellationError {
-            // AE#629: the engine took this startup over itself (the AE#561 rebuild), so the caller is
+            // AE#629: the engine took this startup over itself (the AE#561 / AE#641 rebuild), so the caller is
             // still waiting for the same thing and gets it, the way a #361 reroute keeps its wait. A
             // load the HOST superseded matches no takeover and unwinds as before.
             guard let generation = attempt.generation,
                   let takeover = softwarePathTakeover,
                   takeover.supersededGeneration == generation else { throw CancellationError() }
             EngineLog.emit(
-                "[AetherEngine] #629 load (gen \(generation)) follows the software-path rebuild "
+                "[AetherEngine] #629 load (gen \(generation)) follows the engine's own rebuild "
                 + "instead of unwinding", category: .engine)
             try await takeover.rebuild.value
             return attempt.probe
@@ -3876,6 +3879,8 @@ public final class AetherEngine: ObservableObject {
         itemDeathReviveGate = ItemDeathReviveGate(maxAttempts: 3)
         stallReloadReviveGate = ItemDeathReviveGate(maxAttempts: 2)
         softwarePathEscalationBudget = SoftwarePathEscalation.Budget()
+        undecodableLiveAudioStreamIndex = Self.undecodableAudioStreamIndexAcrossLoad(
+            undecodableLiveAudioStreamIndex, sessionPreservingReload: sessionPreservingReloadInFlight)
         masterFallbackUsed = false
         nativeSubtitleReanchorTask?.cancel()
         nativeSubtitleReanchorTask = nil
diff --git a/Sources/AetherEngine/Audio/AudioBridge.swift b/Sources/AetherEngine/Audio/AudioBridge.swift
index c01a15a1a..c33014ec0 100644
--- a/Sources/AetherEngine/Audio/AudioBridge.swift
+++ b/Sources/AetherEngine/Audio/AudioBridge.swift
@@ -577,6 +577,13 @@ final class AudioBridge: @unchecked Sendable {
     /// One-shot: a bridge that stays silent for an hour costs one line, not one per packet.
     private(set) var silentFeedReported = false
 
+    /// AE#641: called once, on the pump thread, when the silence is structural AND the decoder is the
+    /// arm that failed (`decodedNothing`). A live session has no muxer death to learn it from: a FLAC
+    /// sample entry is built from the encoder's extradata, so segments keep being cut with an audio
+    /// track that never carries a sample, and AVPlayer shows the first picture and waits on the audio
+    /// forever. Set before the producer starts feeding.
+    var onDecoderProducedNothing: (@Sendable (FeedStats) -> Void)?
+
     /// AE#474: the DECODER arm's unit, and only its unit. Source went in and the FIFO got nothing
     /// back, so there is no sample count to bound anything with and packets are all there is.
     private static let silentFeedPacketThreshold = 64
@@ -966,6 +973,7 @@ final class AudioBridge: @unchecked Sendable {
             + "written, so this session will fail its first segment cut unless output starts.",
             category: .session
         )
+        if stats.decodedNothing { onDecoderProducedNothing?(stats) }
     }
 
     /// Align swr's INPUT side to the frame the decoder actually produced. libswresample reads `extended_data`
diff --git a/Sources/AetherEngine/PlayerState.swift b/Sources/AetherEngine/PlayerState.swift
index 7f15c1367..6c448a575 100644
--- a/Sources/AetherEngine/PlayerState.swift
+++ b/Sources/AetherEngine/PlayerState.swift
@@ -116,9 +116,11 @@ public enum AudioDelivery: String, Sendable, Equatable, CaseIterable {
     /// libavcodec decodes the audio and the engine renders it itself (the software path and the
     /// software audio-only host).
     case decoded
-    /// The source HAS audio and none of it could be delivered: no libavcodec decoder for it, or the
-    /// bridge could not be built or could not write its header. The session plays video-only and
-    /// silently. This is the one value a fallback ladder acts on.
+    /// The source HAS audio and none of it could be delivered: no libavcodec decoder for it, the
+    /// bridge could not be built or could not write its header, or a live bridge was built and its
+    /// decoder produced nothing, after which the engine rebuilt the session without the track
+    /// (AE#641). The session plays video-only and silently. This is the one value a fallback ladder
+    /// acts on.
     case droppedNoPipeline
     /// AVFoundation owns the audio: the remote-HLS bypass and the native audio-only host both hand
     /// the source to AVPlayer, which does its own media selection. The engine has no pipeline of its
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine+AudioRoute.swift b/Sources/AetherEngine/Video/HLSVideoEngine+AudioRoute.swift
index 199e385f4..806f03d91 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine+AudioRoute.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine+AudioRoute.swift
@@ -160,13 +160,25 @@ extension HLSVideoEngine {
         // AE#462 harness (TEST-ONLY): both attempts are skipped so the video-only tail is reachable
         // without a source this build has no decoder for. Loud, because a run that read as a real
         // classification would be worse than no harness at all.
-        let forcedDrop = AetherEngine.forceAudioPipelineFailureForTesting
-        if forcedDrop {
+        let forcedForTesting = AetherEngine.forceAudioPipelineFailureForTesting
+        if forcedForTesting {
             EngineLog.emit(
                 "[HLSVideoEngine] TEST-ONLY: audio pipeline forced to fail, skipping stream-copy and bridge",
                 category: .session
             )
         }
+        // AE#641: this session's bridge already decoded nothing from this stream, and a second
+        // bridge would be handed the same bytes.
+        let knownUndecodable = sourceAudioStreamIndex >= 0
+            && undecodableAudioStreamIndex == sourceAudioStreamIndex
+        if knownUndecodable {
+            EngineLog.emit(
+                "[HLSVideoEngine] AE#641 audio stream \(sourceAudioStreamIndex) decoded nothing earlier "
+                + "in this session; skipping stream-copy and bridge",
+                category: .session
+            )
+        }
+        let forcedDrop = forcedForTesting || knownUndecodable
 
         let sourceCodecLabel: String = {  // falls back to "audio" for codecs with no libavcodec name entry
             if let stream = sourceAudioStream,
@@ -301,6 +313,12 @@ extension HLSVideoEngine {
                 )
                 self.savedAudioConfig = cfg
                 self.audioBridge = bridge
+                if isLiveSession, sideAudioDemuxer == nil {
+                    let streamIndex = sourceAudioStreamIndex
+                    bridge.onDecoderProducedNothing = { [weak self] stats in
+                        self?.onLiveAudioDecodesNothing?(streamIndex, stats.summary)
+                    }
+                }
                 do {
                     let prod = try makeProducer(baseIndex: initialProducerBaseIndex)
                     // The label and the CODECS attribute come from the encoder the bridge ACTUALLY opened,
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine.swift b/Sources/AetherEngine/Video/HLSVideoEngine.swift
index 2af7a3391..8f2284d2b 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine.swift
@@ -77,6 +77,9 @@ public final class HLSVideoEngine: @unchecked Sendable {
     /// Caller-chosen audio stream index; nil falls back to `av_find_best_stream`. Enables
     /// host-driven track switching via `AetherEngine.selectAudioTrack(index:)` reload.
     private let audioSourceStreamIndexOverride: Int32?
+    /// AE#641: a source audio stream this session already found undecodable (its bridge decoded
+    /// nothing). When the pick lands on it again, the cascade goes straight to its video-only tail.
+    let undecodableAudioStreamIndex: Int32?
 
     /// AE#443: whoever REPLACES one of these two mid-session owes the session the totals the outgoing
     /// instance held (`retireDemuxer` / `retireProducer` below). They carry the session's byte and
@@ -635,6 +638,10 @@ public final class HLSVideoEngine: @unchecked Sendable {
     /// the software path and telling the host (`escalateLiveReopenExhaustion`) instead. Unset, the
     /// session falls back to the ordinary reopen budget.
     var onLiveJoinWithoutEntryPoint: (@Sendable () -> Void)?
+    /// AE#641: the live audio bridge decoded not one frame of the selected stream (index, bridge
+    /// summary). Nothing inside the session can recover it: a producer rebuild hands the same decoder
+    /// the same bytes, and the served media keeps an audio track that will never be filled.
+    var onLiveAudioDecodesNothing: (@Sendable (Int32, String) -> Void)?
     /// #126: fires when a VOD pump dies on a read error having produced nothing (zero packets
     /// written, empty cache). The playlist exists but no segment will ever land, so AVPlayer
     /// would sit in waitingToPlay forever; the engine surfaces a fatal error instead.
@@ -866,6 +873,7 @@ public final class HLSVideoEngine: @unchecked Sendable {
         matchContentEnabled: Bool = true,
         panelIsInHDRMode: Bool = false,
         audioSourceStreamIndexOverride: Int32? = nil,
+        undecodableAudioStreamIndex: Int32? = nil,
         audioBridgeMode: AudioBridgeMode = .surroundCompat,
         isLiveSession: Bool = false,
         dvrWindowSeconds: Double? = nil,
@@ -910,6 +918,7 @@ public final class HLSVideoEngine: @unchecked Sendable {
         self.matchContentEnabled = matchContentEnabled
         self.panelIsInHDRMode = panelIsInHDRMode
         self.audioSourceStreamIndexOverride = audioSourceStreamIndexOverride
+        self.undecodableAudioStreamIndex = undecodableAudioStreamIndex
         self.audioBridgeMode = audioBridgeMode
         self.isLiveSession = isLiveSession
         self.dvrWindowSeconds = dvrWindowSeconds
diff --git a/Tests/AetherEngineTests/Issue641LiveUndecodableAudioTests.swift b/Tests/AetherEngineTests/Issue641LiveUndecodableAudioTests.swift
new file mode 100644
index 000000000..01e97a6ed
--- /dev/null
+++ b/Tests/AetherEngineTests/Issue641LiveUndecodableAudioTests.swift
@@ -0,0 +1,110 @@
+import Testing
+import Foundation
+import AetherLibavcodec
+import AetherLibavutil
+@testable import AetherEngine
+
+/// AE#641: a live bridge that decodes nothing has to reach the engine, which rebuilds the session
+/// video-only. A FLAC sample entry is built from the encoder's extradata, so on live there is no
+/// muxer death to learn it from and AVPlayer would wait on the empty audio track forever.
+struct Issue641LiveUndecodableAudioTests {
+
+    private final class Calls: @unchecked Sendable {
+        private let lock = NSLock()
+        private var stats: [AudioBridge.FeedStats] = []
+        func append(_ s: AudioBridge.FeedStats) { lock.withLock { stats.append(s) } }
+        var all: [AudioBridge.FeedStats] { lock.withLock { stats } }
+    }
+
+    private func freeAll(_ packets: inout [UnsafeMutablePointer<AVPacket>]) {
+        for p in packets {
+            var pp: UnsafeMutablePointer<AVPacket>? = p
+            trackedPacketFree(&pp)
+        }
+        packets.removeAll()
+    }
+
+    private func makeCodecpar(_ id: AVCodecID) -> UnsafeMutablePointer<AVCodecParameters> {
+        let par = avcodec_parameters_alloc()!
+        par.pointee.codec_type = AVMEDIA_TYPE_AUDIO
+        par.pointee.codec_id = id
+        par.pointee.sample_rate = 48_000
+        if id == AV_CODEC_ID_PCM_S16LE {
+            par.pointee.format = AV_SAMPLE_FMT_S16.rawValue
+            par.pointee.bits_per_coded_sample = 16
+            par.pointee.block_align = 4
+        } else {
+            par.pointee.format = AV_SAMPLE_FMT_FLTP.rawValue
+        }
+        av_channel_layout_default(&par.pointee.ch_layout, 2)
+        return par
+    }
+
+    /// Bytes the mp3 decoder cannot make a frame of, the shape a mislabelled PID hands the bridge.
+    private func makeUndecodablePackets(count: Int) -> [UnsafeMutablePointer<AVPacket>] {
+        (0..<count).compactMap { i in
+            guard let pkt = trackedPacketAlloc(), av_new_packet(pkt, 130) >= 0 else { return nil }
+            memset(pkt.pointee.data, 0xFF, 130)
+            pkt.pointee.pts = Int64(i) * 26
+            pkt.pointee.dts = pkt.pointee.pts
+            return pkt
+        }
+    }
+
+    /// Stereo S16 PCM, 1152 samples a packet: decodes, and fills FLAC's 4608-sample frame every fourth.
+    private func makePCMPackets(count: Int) -> [UnsafeMutablePointer<AVPacket>] {
+        let samples = 1152
+        return (0..<count).compactMap { i in
+            guard let pkt = trackedPacketAlloc(), av_new_packet(pkt, Int32(samples * 4)) >= 0 else { return nil }
+            memset(pkt.pointee.data, 0, samples * 4)
+            pkt.pointee.pts = Int64(i * samples)
+            pkt.pointee.dts = pkt.pointee.pts
+            return pkt
+        }
+    }
+
+    private func feed(_ codec: AVCodecID, packets: [UnsafeMutablePointer<AVPacket>],
+                      timeBase: AVRational) throws -> (Calls, AudioBridge.FeedStats) {
+        let codecpar = makeCodecpar(codec)
+        defer {
+            var p: UnsafeMutablePointer<AVCodecParameters>? = codecpar
+            avcodec_parameters_free(&p)
+        }
+        let bridge = try AudioBridge(srcCodecpar: codecpar, srcTimeBase: timeBase, mode: .surroundCompat)
+        defer { bridge.close() }
+        let calls = Calls()
+        bridge.onDecoderProducedNothing = { calls.append($0) }
+        var outputs: [UnsafeMutablePointer<AVPacket>] = []
+        defer { freeAll(&outputs) }
+        for p in packets { outputs.append(contentsOf: (try? bridge.feed(packet: p)) ?? []) }
+        return (calls, bridge.feedStats)
+    }
+
+    @Test("a bridge that decodes nothing tells the session once, with its counters")
+    func undecodableFeedReportsOnce() throws {
+        var packets = makeUndecodablePackets(count: 200)
+        defer { freeAll(&packets) }
+        let (calls, stats) = try feed(AV_CODEC_ID_MP3, packets: packets,
+                                      timeBase: AVRational(num: 1, den: 1000))
+        #expect(stats.decodedNothing)
+        #expect(calls.all.count == 1, "one rebuild per session, not one per packet past the threshold")
+        #expect(calls.all.first?.framesDecoded == 0)
+    }
+
+    @Test("a bridge that decodes and emits never asks for the video-only rebuild")
+    func healthyFeedNeverReports() throws {
+        var packets = makePCMPackets(count: 200)
+        defer { freeAll(&packets) }
+        let (calls, stats) = try feed(AV_CODEC_ID_PCM_S16LE, packets: packets,
+                                      timeBase: AVRational(num: 1, den: 48_000))
+        #expect(stats.packetsEmitted > 0)
+        #expect(calls.all.isEmpty)
+    }
+
+    @Test("the session's own rebuild keeps the stream marked, a host load starts clean")
+    func markSurvivesOnlyTheSessionsOwnRebuild() {
+        #expect(AetherEngine.undecodableAudioStreamIndexAcrossLoad(1, sessionPreservingReload: true) == 1)
+        #expect(AetherEngine.undecodableAudioStreamIndexAcrossLoad(1, sessionPreservingReload: false) == nil)
+        #expect(AetherEngine.undecodableAudioStreamIndexAcrossLoad(nil, sessionPreservingReload: true) == nil)
+    }
+}
diff --git a/docs/api.md b/docs/api.md
index 452586962..d0ce6173a 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -288,13 +288,16 @@ typed fact rather than as something to reconstruct (AE#462).
 | `.streamCopy` | the source bitstream is muxed into fMP4 unchanged (Atmos, DTS-HD and everything else reach the renderer as authored) |
 | `.bridged` | decoded and re-encoded to FLAC or E-AC-3 for the fMP4 pipeline; lossless for the bed channels, object metadata does not survive the PCM intermediate |
 | `.decoded` | libavcodec decodes and the engine renders it (the software path, the FFmpeg audio-only host) |
-| `.droppedNoPipeline` | the source HAS audio and none of it could be delivered: no decoder for it in this build, or the bridge could not be built or could not write its header. The session plays video-only and silently |
+| `.droppedNoPipeline` | the source HAS audio and none of it could be delivered: no decoder for it in this build, the bridge could not be built or could not write its header, or (live only) the bridge was built and its decoder produced nothing, after which the engine rebuilds the session without the track (AE#641). The session plays video-only and silently |
 | `.playerManaged` | AVFoundation owns the audio (the remote-HLS bypass, the native audio-only host). The engine has no pipeline of its own to classify and does not answer on AVFoundation's behalf |
 
 **`.droppedNoPipeline` is the one a fallback ladder acts on**, the same way it demotes on
 `PlaybackErrorKind.audioBridgeProducedNoOutput`. The two are the same user outcome from opposite
-ends of the cascade: that kind fails loudly when a bridge WAS built and then decoded nothing, this
-value reports a bridge that could never be built at all. Neither ends a ladder: re-serving the
+ends of the cascade: that kind fails loudly when a VOD bridge WAS built and then decoded nothing,
+this value reports a bridge that could never be built at all. A live session whose bridge decodes
+nothing arrives here as well rather than at the error: its video is playable and a live source has
+no position to hand to a second player, so the engine rebuilds it video-only by itself and the
+value changes from `.bridged` to `.droppedNoPipeline` (AE#641). Neither ends a ladder: re-serving the
 source with audio the pipeline can carry (a server-side transcode, a second player that decodes it
 itself) plays it.
 
@@ -590,7 +593,7 @@ suppressing `AVPlayerItemLegibleOutput` to keep the measurement running.
 | `$startupProgress` | `StartupProgress?` for a determinate loading bar. |
 | `softwarePathEscalations`, `SoftwarePathEscalationEvent` | A native session AVPlayer refused, rebuilt on the software path, with the failure it absorbed. See [The engine moves a refused session onto the software path](#the-engine-moves-a-refused-session-onto-the-software-path). |
 | `$videoRoute` | `VideoRoute`: which pipeline is actually serving, one of `.none`, `.remoteBypass`, `.loopback`, `.software`, `.audio`. `LoadOptions.nativeRemoteHLS` is only the request; the carriage watchdog, the remembered verdict and the HLS reroutes move a session between routes, mid-session too. Branch on this, above all for who draws subtitles. |
-| `$audioDelivery` | `AudioDelivery`: how the audio reaches the renderer, one of `.none`, `.noAudioInSource`, `.streamCopy`, `.bridged`, `.decoded`, `.droppedNoPipeline`, `.playerManaged`. `.droppedNoPipeline` is a source that HAS audio playing video-only because no pipeline could be built for it: the value a fallback ladder demotes on. See [Reading whether the audio was delivered](#reading-whether-the-audio-was-delivered). |
+| `$audioDelivery` | `AudioDelivery`: how the audio reaches the renderer, one of `.none`, `.noAudioInSource`, `.streamCopy`, `.bridged`, `.decoded`, `.droppedNoPipeline`, `.playerManaged`. `.droppedNoPipeline` is a source that HAS audio playing video-only because no pipeline could be built for it, or because a live bridge decoded nothing (AE#641): the value a fallback ladder demotes on. See [Reading whether the audio was delivered](#reading-whether-the-audio-was-delivered). |
 | `$videoFormat` | The format being presented: `.sdr`, `.hdr10`, `.hdr10Plus`, `.dolbyVision`, `.hlg`. On a platform with no per-mode capability table (macOS), a Dolby Vision session the clamp sent to `.hdr10` is upgraded back to `.dolbyVision` once the item AVFoundation is playing turns out to carry a `dvh1` / `dvhe` sample entry (AE#515). On tvOS the panel term behind it no longer comes from the headroom alone: a session serving an HDR master that AVFoundation has not refused publishes the presented format half a second in, because a display that takes an HDR master is presenting HDR while one that is not refuses in 54 to 61 ms, and `currentEDRHeadroom` has been measured reading 1.00 through exactly that acceptance (AE#459). |
 | `$sourceVideoFormat` | The format the **source** carries, before any panel-driven mapping. The pair is what an honest badge needs: HDR content on an SDR panel differs between the two. |
 | `$sourceDVProfile`, `$sourceVideoFrameRate`, `$sourceVideoBitrate` | Source detail for an info panel. |

From 428fa8384c207726aa83ef9c1d920903182e4490 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 25 Sep 2026 23:02:33 +0200
Subject: [PATCH 108/359] fix(audio): a VOD bridge that decodes nothing
 surfaces its verdict, an unpicked stream is a drop (AE#641)

A FLAC bridge builds its sample entry from the encoder's extradata, so on
VOD a bridge that decoded nothing never failed a cut: the session played
silently while audioDelivery read .bridged, and the AE#396 verdict was
only reachable on the E-AC-3 route. The bridge's decoder-arm report now
surfaces .audioBridgeProducedNoOutput on VOD as well (live keeps the
video-only rebuild), and surfaceVODSourceFailure passes that kind on
once, since the E-AC-3 route's failed cut and exhausted revive follow.

Separately, a source whose audio stream av_find_best_stream passed over
(parameters left empty by the probe) read as .noAudioInSource on VOD and
on the software path, which only live fell back from. Both classify on
whether the source has an audio stream at all now, so it reads as
.droppedNoPipeline.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 CHANGELOG.md                                  |  9 ++++
 .../Native/SoftwarePlaybackHost.swift         | 12 +++--
 Sources/AetherEngine/PlayerState.swift        | 13 ++---
 .../Video/HLSVideoEngine+AudioRoute.swift     | 31 +++++++++--
 .../AetherEngine/Video/HLSVideoEngine.swift   | 12 +++++
 .../Issue462AudioDeliveryTests.swift          | 12 +++--
 .../Issue641LiveUndecodableAudioTests.swift   | 52 +++++++++++++++++++
 docs/api.md                                   |  7 +--
 8 files changed, 130 insertions(+), 18 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0a9862c15..f9ed00232 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -24,6 +24,15 @@ the public-API contract.
   left segments with an audio track that never carried a sample, and AVPlayer showed the first
   picture and waited on it for the rest of the session. The engine now rebuilds the session without
   that track and `audioDelivery` reads `.droppedNoPipeline` (AE#641).
+- **A VOD audio track the bridge cannot decode surfaces `.audioBridgeProducedNoOutput` on the FLAC
+  route too.** Only the E-AC-3 route reached that verdict, through its failed first cut; a FLAC
+  bridge builds its sample entry from the encoder's extradata, so the session played silently while
+  `audioDelivery` read `.bridged`, and a host ladder never heard of it. The verdict reaches the host
+  once, whichever arm finds it first (AE#641).
+- **`audioDelivery` reads `.droppedNoPipeline` for a source whose audio stream could not be picked**,
+  not `.noAudioInSource`. `av_find_best_stream` passes over a stream whose parameters the probe left
+  empty and only live fell back to it, so on VOD (and on the software path) a source with an
+  undecodable track read as one without audio (AE#641).
 - **FFmpegBuild 3.6.0: an MPEG-TS audio PID is identified by its payload.** The raw `dts`, `truehd`
   and `loas` demuxers were missing, so the mpegts content probe could never confirm DTS, TrueHD or
   LATM and the lenient mp3 probe named the track; a PID labelled 0x03 (MPEG-1 audio) was not probed
diff --git a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
index d4553fff9..19c95984a 100644
--- a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
+++ b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
@@ -656,8 +656,13 @@ final class SoftwarePlaybackHost {
     /// AE#462: how this host's audio ended up, from the two facts that decide it. Silence has two
     /// causes here exactly as it does in the loopback cascade, and only one of them is a reason for
     /// a host to demote to a source that carries the audio differently.
-    nonisolated static func audioDelivery(resolvedAudioIndex: Int32, decoderOpened: Bool) -> AudioDelivery {
-        guard resolvedAudioIndex >= 0 else { return .noAudioInSource }
+    ///
+    /// AE#641: an unresolved index is not a source without audio. On VOD nothing falls back past
+    /// `av_find_best_stream`, which passes over an audio stream whose parameters the probe left empty,
+    /// so the source's own streams decide which of the two silences this is.
+    nonisolated static func audioDelivery(resolvedAudioIndex: Int32, decoderOpened: Bool,
+                                          sourceCarriesAudio: Bool) -> AudioDelivery {
+        guard resolvedAudioIndex >= 0 else { return sourceCarriesAudio ? .droppedNoPipeline : .noAudioInSource }
         return decoderOpened ? .decoded : .droppedNoPipeline
     }
 
@@ -903,7 +908,8 @@ final class SoftwarePlaybackHost {
         // stream present but unusable (no codecpar) classifies as the drop it is rather than as a
         // source without audio.
         self.audioDelivery = Self.audioDelivery(resolvedAudioIndex: resolvedAudioIdx,
-                                                decoderOpened: self.audioDecoder != nil)
+                                                decoderOpened: self.audioDecoder != nil,
+                                                sourceCarriesAudio: dem.firstAudioStreamIndexByType >= 0)
         // #112 rework: capture embedded subtitle stream indices + time bases for the demux
         // loop's subtitle tap dispatch.
         var subIndices: Set<Int32> = []
diff --git a/Sources/AetherEngine/PlayerState.swift b/Sources/AetherEngine/PlayerState.swift
index 6c448a575..b2b8788c3 100644
--- a/Sources/AetherEngine/PlayerState.swift
+++ b/Sources/AetherEngine/PlayerState.swift
@@ -103,8 +103,9 @@ public enum VideoRoute: String, Sendable, Equatable {
 public enum AudioDelivery: String, Sendable, Equatable, CaseIterable {
     /// No session: pre-load, or torn down.
     case none
-    /// The source carries no audio stream (or none was selected). Silence is the source's, not the
-    /// engine's, and no ladder rung can change it.
+    /// The source carries no audio stream. Silence is the source's, not the engine's, and no ladder
+    /// rung can change it. A source whose audio stream the pick passed over (its parameters left
+    /// empty by the probe) is `.droppedNoPipeline`, not this (AE#641).
     case noAudioInSource
     /// The source's audio bitstream is muxed into fMP4 unchanged: Atmos, DTS-HD and every other
     /// bitstream reach the renderer exactly as authored.
@@ -117,10 +118,10 @@ public enum AudioDelivery: String, Sendable, Equatable, CaseIterable {
     /// software audio-only host).
     case decoded
     /// The source HAS audio and none of it could be delivered: no libavcodec decoder for it, the
-    /// bridge could not be built or could not write its header, or a live bridge was built and its
-    /// decoder produced nothing, after which the engine rebuilt the session without the track
-    /// (AE#641). The session plays video-only and silently. This is the one value a fallback ladder
-    /// acts on.
+    /// bridge could not be built or could not write its header, no stream could be picked because the
+    /// probe left its parameters empty, or a live bridge was built and its decoder produced nothing,
+    /// after which the engine rebuilt the session without the track (AE#641). The session plays
+    /// video-only and silently. This is the one value a fallback ladder acts on.
     case droppedNoPipeline
     /// AVFoundation owns the audio: the remote-HLS bypass and the native audio-only host both hand
     /// the source to AVPlayer, which does its own media selection. The engine has no pipeline of its
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine+AudioRoute.swift b/Sources/AetherEngine/Video/HLSVideoEngine+AudioRoute.swift
index 806f03d91..cff45e2a6 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine+AudioRoute.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine+AudioRoute.swift
@@ -131,6 +131,26 @@ extension HLSVideoEngine {
         hadSourceAudioStream ? .droppedNoPipeline : .noAudioInSource
     }
 
+    /// AE#641: the bridge decoded not one frame of the selected stream. A FLAC sample entry is built from
+    /// the encoder's extradata, so no muxer death follows on that route: a live session serves an
+    /// audio track that is never filled and AVPlayer waits on it, a VOD session plays silently while
+    /// reporting `.bridged`. Live hands it to the engine, which rebuilds video-only; VOD surfaces
+    /// the same verdict the E-AC-3 route reaches through its failed cut, so a host can hand the
+    /// position to a player that decodes the track itself.
+    func handleBridgeDecodedNothing(streamIndex: Int32, summary: String) {
+        if isLiveSession {
+            onLiveAudioDecodesNothing?(streamIndex, summary)
+            return
+        }
+        EngineLog.emit(
+            "[HLSVideoEngine] AE#641 the VOD audio bridge decoded nothing from stream \(streamIndex) "
+            + "(\(summary)); surfacing it instead of playing silently",
+            category: .session
+        )
+        surfaceVODSourceFailure(FFmpegErr.einval, "Audio track could not be decoded",
+                                kind: .audioBridgeProducedNoOutput)
+    }
+
     /// Guards `audioSourceStreamIndexOverride` against stale picker selections from a previous title.
     static func isAudioStream(demuxer: Demuxer, index: Int32) -> Bool {
         guard index >= 0, let stream = demuxer.stream(at: index) else {
@@ -147,6 +167,7 @@ extension HLSVideoEngine {
         streamCopyAudio: HLSSegmentProducer.AudioConfig?,
         sourceAudioStreamIndex: Int32,
         sourceAudioStream: UnsafeMutablePointer<AVStream>?,
+        sourceCarriesAudio: Bool,
         audioHLSCodecs: inout String?,
         audioLanguage: String? = nil
     ) throws -> HLSSegmentProducer {
@@ -313,10 +334,10 @@ extension HLSVideoEngine {
                 )
                 self.savedAudioConfig = cfg
                 self.audioBridge = bridge
-                if isLiveSession, sideAudioDemuxer == nil {
+                if sideAudioDemuxer == nil {
                     let streamIndex = sourceAudioStreamIndex
                     bridge.onDecoderProducedNothing = { [weak self] stats in
-                        self?.onLiveAudioDecodesNothing?(streamIndex, stats.summary)
+                        self?.handleBridgeDecodedNothing(streamIndex: streamIndex, summary: stats.summary)
                     }
                 }
                 do {
@@ -365,8 +386,12 @@ extension HLSVideoEngine {
         // AE#462: the drop becomes a fact the host can read, and a line that says which of the two
         // silences this is. The ERROR lines above name a failure; this one names the outcome, which
         // is what a reader of the log is actually looking for.
+        // AE#641: whether the SOURCE has audio, not whether a stream was picked. `av_find_best_stream`
+        // passes over an audio stream whose parameters the probe left empty, and on VOD nothing falls
+        // back to it, so a source with an undecodable track used to read as one without audio.
         self.audioDelivery = Self.videoOnlyAudioDelivery(
-            hadSourceAudioStream: sourceAudioStream != nil && sourceAudioStreamIndex >= 0)
+            hadSourceAudioStream: sourceCarriesAudio
+                || (sourceAudioStream != nil && sourceAudioStreamIndex >= 0))
         EngineLog.emit(
             "[HLSVideoEngine] audio delivery = \(audioDelivery.rawValue)"
             + (audioDelivery == .droppedNoPipeline
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine.swift b/Sources/AetherEngine/Video/HLSVideoEngine.swift
index 8f2284d2b..73bf66ed6 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine.swift
@@ -664,9 +664,20 @@ public final class HLSVideoEngine: @unchecked Sendable {
     /// Pairing the release with the surface makes that structural instead of a call site to remember.
     func surfaceVODSourceFailure(_ code: Int32, _ reason: String,
                                  kind: PlaybackErrorKind = .vodSourceFailed) {
+        // AE#641: a silent bridge is reported the moment it is structural and again by the muxer arms
+        // that follow it on the E-AC-3 route; the session learns it once.
+        if kind == .audioBridgeProducedNoOutput {
+            silentBridgeSurfaceLock.lock()
+            let first = !silentBridgeFailureSurfaced
+            silentBridgeFailureSurfaced = true
+            silentBridgeSurfaceLock.unlock()
+            guard first else { return }
+        }
         provider?.abortSequentialStartupWait()
         onVODSourceFailed?(code, reason, kind)
     }
+    private let silentBridgeSurfaceLock = NSLock()
+    private var silentBridgeFailureSurfaced = false
     /// Session-long FLAC bridge for codecs illegal in fMP4. Engine-owned (not producer-owned) so
     /// encoder state survives producer restarts; `startSegment()` rebases PTS on each restart.
     var audioBridge: AudioBridge?
@@ -1844,6 +1855,7 @@ public final class HLSVideoEngine: @unchecked Sendable {
             streamCopyAudio: streamCopyAudio,
             sourceAudioStreamIndex: audioStreamIndex,
             sourceAudioStream: audioStreamIndex >= 0 ? audioDem.stream(at: audioStreamIndex) : nil,
+            sourceCarriesAudio: audioDem.firstAudioStreamIndexByType >= 0,
             audioHLSCodecs: &audioHLSCodecs,
             audioLanguage: audioLanguage
         )
diff --git a/Tests/AetherEngineTests/Issue462AudioDeliveryTests.swift b/Tests/AetherEngineTests/Issue462AudioDeliveryTests.swift
index 2ba734c30..ff04d5616 100644
--- a/Tests/AetherEngineTests/Issue462AudioDeliveryTests.swift
+++ b/Tests/AetherEngineTests/Issue462AudioDeliveryTests.swift
@@ -158,9 +158,15 @@ struct AudioDeliveryClassificationTests {
     /// video-only, exactly like the loopback tail and just as silently.
     @Test("the software host separates an absent track from a decoder that would not open")
     func softwareHostSeparatesAbsentFromDropped() {
-        #expect(SoftwarePlaybackHost.audioDelivery(resolvedAudioIndex: 1, decoderOpened: true) == .decoded)
-        #expect(SoftwarePlaybackHost.audioDelivery(resolvedAudioIndex: 1, decoderOpened: false) == .droppedNoPipeline)
-        #expect(SoftwarePlaybackHost.audioDelivery(resolvedAudioIndex: -1, decoderOpened: false) == .noAudioInSource)
+        #expect(SoftwarePlaybackHost.audioDelivery(resolvedAudioIndex: 1, decoderOpened: true,
+                                                   sourceCarriesAudio: true) == .decoded)
+        #expect(SoftwarePlaybackHost.audioDelivery(resolvedAudioIndex: 1, decoderOpened: false,
+                                                   sourceCarriesAudio: true) == .droppedNoPipeline)
+        #expect(SoftwarePlaybackHost.audioDelivery(resolvedAudioIndex: -1, decoderOpened: false,
+                                                   sourceCarriesAudio: false) == .noAudioInSource)
+        // AE#641: a stream the pick passed over (empty parameters) is still the source's audio.
+        #expect(SoftwarePlaybackHost.audioDelivery(resolvedAudioIndex: -1, decoderOpened: false,
+                                                   sourceCarriesAudio: true) == .droppedNoPipeline)
     }
 
     /// The label is the second half of the same lie: it was built from the probe's track list, so a
diff --git a/Tests/AetherEngineTests/Issue641LiveUndecodableAudioTests.swift b/Tests/AetherEngineTests/Issue641LiveUndecodableAudioTests.swift
index 01e97a6ed..8ae75d1b7 100644
--- a/Tests/AetherEngineTests/Issue641LiveUndecodableAudioTests.swift
+++ b/Tests/AetherEngineTests/Issue641LiveUndecodableAudioTests.swift
@@ -107,4 +107,56 @@ struct Issue641LiveUndecodableAudioTests {
         #expect(AetherEngine.undecodableAudioStreamIndexAcrossLoad(1, sessionPreservingReload: false) == nil)
         #expect(AetherEngine.undecodableAudioStreamIndexAcrossLoad(nil, sessionPreservingReload: true) == nil)
     }
+
+    // MARK: - Where the verdict goes
+
+    private final class Surfaced: @unchecked Sendable {
+        private let lock = NSLock()
+        private var kinds: [PlaybackErrorKind] = []
+        private var live: [Int32] = []
+        func surface(_ kind: PlaybackErrorKind) { lock.withLock { kinds.append(kind) } }
+        func forward(_ index: Int32) { lock.withLock { live.append(index) } }
+        var surfacedKinds: [PlaybackErrorKind] { lock.withLock { kinds } }
+        var forwarded: [Int32] { lock.withLock { live } }
+    }
+
+    private func makeSession(live: Bool) -> (HLSVideoEngine, Surfaced) {
+        let session = HLSVideoEngine(url: URL(fileURLWithPath: "/nonexistent/ae641.mkv"),
+                                     dvModeAvailable: false, isLiveSession: live)
+        let surfaced = Surfaced()
+        session.onVODSourceFailed = { _, _, kind in surfaced.surface(kind) }
+        session.onLiveAudioDecodesNothing = { index, _ in surfaced.forward(index) }
+        return (session, surfaced)
+    }
+
+    @Test("a VOD bridge that decodes nothing surfaces the same verdict as the E-AC-3 route")
+    func vodSurfacesTheTypedFailure() {
+        let (session, surfaced) = makeSession(live: false)
+        session.handleBridgeDecodedNothing(streamIndex: 1, summary: "fed=64 decoded=0")
+        #expect(surfaced.surfacedKinds == [.audioBridgeProducedNoOutput],
+                "a FLAC bridge has no failed cut to report it, so it played silently as .bridged")
+        #expect(surfaced.forwarded.isEmpty)
+    }
+
+    @Test("a live bridge that decodes nothing goes to the engine's video-only rebuild, not to an error")
+    func liveForwardsInsteadOfFailing() {
+        let (session, surfaced) = makeSession(live: true)
+        session.handleBridgeDecodedNothing(streamIndex: 2, summary: "fed=64 decoded=0")
+        #expect(surfaced.forwarded == [2])
+        #expect(surfaced.surfacedKinds.isEmpty)
+    }
+
+    @Test("the silent-bridge verdict reaches the host once, every other failure as often as it happens")
+    func silentBridgeVerdictIsSurfacedOnce() {
+        let (session, surfaced) = makeSession(live: false)
+        // The detector, then the E-AC-3 route's failed cut, then its exhausted revive.
+        session.handleBridgeDecodedNothing(streamIndex: 1, summary: "fed=64 decoded=0")
+        session.surfaceVODSourceFailure(FFmpegErr.einval, "Audio track could not be decoded",
+                                        kind: .audioBridgeProducedNoOutput)
+        session.surfaceVODSourceFailure(FFmpegErr.einval, "Audio could not be transcoded for playback",
+                                        kind: .audioBridgeProducedNoOutput)
+        session.surfaceVODSourceFailure(FFmpegErr.einval, "Source audio cannot be muxed")
+        session.surfaceVODSourceFailure(FFmpegErr.einval, "Source audio cannot be muxed")
+        #expect(surfaced.surfacedKinds == [.audioBridgeProducedNoOutput, .vodSourceFailed, .vodSourceFailed])
+    }
 }
diff --git a/docs/api.md b/docs/api.md
index d0ce6173a..3ea6354d9 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -284,16 +284,17 @@ typed fact rather than as something to reconstruct (AE#462).
 | Value | Meaning |
 | --- | --- |
 | `.none` | no session |
-| `.noAudioInSource` | the source carries no audio track, or none was selected |
+| `.noAudioInSource` | the source carries no audio track |
 | `.streamCopy` | the source bitstream is muxed into fMP4 unchanged (Atmos, DTS-HD and everything else reach the renderer as authored) |
 | `.bridged` | decoded and re-encoded to FLAC or E-AC-3 for the fMP4 pipeline; lossless for the bed channels, object metadata does not survive the PCM intermediate |
 | `.decoded` | libavcodec decodes and the engine renders it (the software path, the FFmpeg audio-only host) |
-| `.droppedNoPipeline` | the source HAS audio and none of it could be delivered: no decoder for it in this build, the bridge could not be built or could not write its header, or (live only) the bridge was built and its decoder produced nothing, after which the engine rebuilds the session without the track (AE#641). The session plays video-only and silently |
+| `.droppedNoPipeline` | the source HAS audio and none of it could be delivered: no decoder for it in this build, the bridge could not be built or could not write its header, the probe left its parameters empty so no stream could be picked, or (live only) the bridge was built and its decoder produced nothing, after which the engine rebuilds the session without the track (AE#641). The session plays video-only and silently |
 | `.playerManaged` | AVFoundation owns the audio (the remote-HLS bypass, the native audio-only host). The engine has no pipeline of its own to classify and does not answer on AVFoundation's behalf |
 
 **`.droppedNoPipeline` is the one a fallback ladder acts on**, the same way it demotes on
 `PlaybackErrorKind.audioBridgeProducedNoOutput`. The two are the same user outcome from opposite
-ends of the cascade: that kind fails loudly when a VOD bridge WAS built and then decoded nothing,
+ends of the cascade: that kind fails loudly when a VOD bridge WAS built and then decoded nothing
+(on the FLAC route as well since AE#641, which used to play silently while reporting `.bridged`),
 this value reports a bridge that could never be built at all. A live session whose bridge decodes
 nothing arrives here as well rather than at the error: its video is playable and a live source has
 no position to hand to a second player, so the engine rebuilds it video-only by itself and the

From b5e300c1987cae43dea0434630f18e05ff81d699 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sat, 26 Sep 2026 05:41:48 +0200
Subject: [PATCH 109/359] test(subtitles): observe the stale-batch drop per
 publish, not after the await (AE#628)

The re-selection test sampled subtitleDrainTickInFlight and subtitleCues
after awaiting the stale batch. The queued tick starts inside that
landing, and its own detached decode can resume on the MainActor before
the test does, so under load the rerun had already landed: CI failed the
#require at line 187 after 65 s. A 50 ms sleep after the await
reproduces it 3 of 3. The engine was right, the test read a scheduler
outcome.

Every publish of subtitleCues is now stamped with the drain tick
current at that moment. The stale drop is "no publish under the stale
serial", the rerun is the serial moving on by one, and the final cues
are awaited if the rerun is still in flight. Green with the 50 ms
sleep; still fails when the decoder identity guard is removed (the stale
batch publishes) and when the queued tick is never re-run.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 .../Issue628PGSOffMainDecodeTests.swift       | 30 ++++++++++++++++---
 1 file changed, 26 insertions(+), 4 deletions(-)

diff --git a/Tests/AetherEngineTests/Issue628PGSOffMainDecodeTests.swift b/Tests/AetherEngineTests/Issue628PGSOffMainDecodeTests.swift
index befd45daf..f167fea5c 100644
--- a/Tests/AetherEngineTests/Issue628PGSOffMainDecodeTests.swift
+++ b/Tests/AetherEngineTests/Issue628PGSOffMainDecodeTests.swift
@@ -1,3 +1,4 @@
+import Combine
 import Foundation
 import CoreGraphics
 import Testing
@@ -168,14 +169,32 @@ struct Issue628PGSOffMainDecodeTests {
         #expect(engine.subtitleDrainCursors[.primary] != nil)
     }
 
+    /// Every publish of `subtitleCues`, stamped with the drain tick that was current when it happened.
+    @MainActor
+    private final class CuePublications {
+        var stamps: [(serial: UInt64, starts: [Double])] = []
+    }
+
     @MainActor
     @Test("a batch whose channel was re-selected while it decoded is dropped, and the tick runs again")
     func reselectionDropsTheStaleBatch() async throws {
         let (engine, _, demuxer) = try engineWithHarvestedSubRip()
         defer { demuxer.close() }
+        // Observed per publish rather than sampled after the await: the queued tick starts inside the
+        // stale batch's landing and its own decode can land before this test resumes, so "still in
+        // flight" and "nothing published yet" are scheduler outcomes, not the engine's (a CI run took
+        // 65 s and caught the rerun already finished).
+        let publications = CuePublications()
+        let observation = engine.$subtitleCues.dropFirst().sink { cues in
+            MainActor.assumeIsolated {
+                publications.stamps.append((engine.subtitleDrainTickSerial, cues.map(\.startTime)))
+            }
+        }
+        defer { observation.cancel() }
 
         engine.requestSubtitleDrainTick()
         let stale = try #require(engine.subtitleDrainTickInFlight)
+        let staleSerial = engine.subtitleDrainTickSerial
         // What a selection does to the channel (selectSubtitleTrack): a fresh decoder and cursor.
         engine.subtitleDrainDecoders[.primary] = nil
         engine.subtitleDrainCursors[.primary] = nil
@@ -183,10 +202,13 @@ struct Issue628PGSOffMainDecodeTests {
         #expect(engine.subtitleDrainTickRequested)
 
         await stale.value
-        // The stale batch published nothing; the queued tick is now the one in flight.
-        let rerun = try #require(engine.subtitleDrainTickInFlight)
-        #expect(engine.subtitleCues.isEmpty)
-        await rerun.value
+        // The landing dropped its batch and started the queued tick, whether or not that one has
+        // landed by now.
+        #expect(engine.subtitleDrainTickSerial == staleSerial &+ 1)
+        #expect(!engine.subtitleDrainTickRequested)
+        if let rerun = engine.subtitleDrainTickInFlight { await rerun.value }
+        #expect(!publications.stamps.contains { $0.serial == staleSerial },
+                "the stale batch published nothing")
         #expect(engine.subtitleCues.map(\.startTime) == [1, 3])
     }
 

From 7644079a61e35cd4c96d47755dc9579c6267411a Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sat, 26 Sep 2026 06:13:29 +0200
Subject: [PATCH 110/359] fix(native): a revived item keeps the playhead until
 it lands, a failed rebuild surfaces once (AE#629)

Reported by cmcpherson274 on AE#629 after 7.17.0, both reproduced here.

The #93 revive swaps a fresh item in at the place the session held. Until that
item lands its zero-tolerance mount seek, AVPlayer reads first the target and
then the start of the segment it decodes up from, and the periodic observer
published both. The second reading rewound the playhead, and the AE#561
rebuild, which resumes at positionForSessionRebuild, resumed there. The clock
is now held across an in-place swap until the mount seek completes finished,
the item plays, or a host seek takes it over. A value-based release does not
work: the optimistic target reading arrives first and would release the hold.

Measured on the 40 s HEVC fixture damaged at 20 s, AETHER_DISABLE_NAL_SANITIZER=1:
  before  revive mounted 15.97 s, refused at 12.00 s, seekClock to=12.000
  after   refused at 15.97 s, seekClock to=15.971 / 15.971 / 15.969, 3 of 3, VERDICT: OK
Controls: healthy fixture plain and with seeks OK, --no-sw-escalation still
ends in -19602.

A rebuild whose load failed after its teardown had already published that
failure; the rung then published the absorbed one on top, two .error for one
failure, the second contradicting what a following load() threw. The rung now
keeps the rebuild's own. New test fails without the change (errors.count 2).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 CHANGELOG.md                                  |  8 ++++++
 .../AetherEngine+SoftwarePathEscalation.swift | 11 ++++++++
 .../Native/NativeAVPlayerHost.swift           | 25 +++++++++++++++++--
 .../SoftwarePathEscalationTests.swift         | 21 ++++++++++++++++
 4 files changed, 63 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f9ed00232..8c559347a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,14 @@ the public-API contract.
 
 ### Fixed
 
+- **A session revived by the #93 item swap keeps its playhead until the fresh item lands there.**
+  Until then AVPlayer reports the start of the segment it decodes up from, so the playhead stepped
+  back by up to a segment, and a software-path rebuild raised in that window resumed there and
+  replayed the gap (3.97 s on a 15.97 s revive) (AE#629).
+- **A software-path rebuild that fails after its teardown surfaces one `.error`, its own.** The
+  rung then published the failure it had absorbed on top, a second `.error` that contradicted what
+  a `load()` following the rebuild threw. The absorbed failure stays on `softwarePathEscalations`
+  (AE#629).
 - **A live H.264 join opens on an intra recovery point, not only on an IDR.** Feeds whose encoder
   never sends an IDR (entry points are I-pictures behind a recovery point SEI with
   `recovery_frame_cnt` 0) never started on the native route; the join gate refused every entry
diff --git a/Sources/AetherEngine/AetherEngine+SoftwarePathEscalation.swift b/Sources/AetherEngine/AetherEngine+SoftwarePathEscalation.swift
index 232dd335e..f942ef406 100644
--- a/Sources/AetherEngine/AetherEngine+SoftwarePathEscalation.swift
+++ b/Sources/AetherEngine/AetherEngine+SoftwarePathEscalation.swift
@@ -63,6 +63,17 @@ extension AetherEngine {
                 "[AetherEngine] #561 software rebuild superseded; nothing to surface",
                 category: .engine)
         } catch {
+            // AE#629: a rebuild that failed after its teardown has already surfaced its own failure,
+            // and a load() that followed it threw that same error. Publishing the absorbed one on top
+            // would hand the host two `.error`s for one failure, the second contradicting the throw.
+            // The absorbed failure is not lost: `softwarePathEscalations` carried it.
+            if case .error = state {
+                EngineLog.emit(
+                    "[AetherEngine] #561 the software rebuild failed after its teardown (\(error)); "
+                    + "its own failure is the one surfaced",
+                    category: .engine)
+                return
+            }
             // The rung is gone and the failure was never surfaced, so it has to be surfaced here or
             // the session would sit on a picture that stopped with nothing said.
             EngineLog.emit(
diff --git a/Sources/AetherEngine/Native/NativeAVPlayerHost.swift b/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
index 5d580a376..ab4b71253 100644
--- a/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
+++ b/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
@@ -218,6 +218,14 @@ final class NativeAVPlayerHost {
     /// uses this as authoritative presented-frame evidence when that publication wins the MainActor
     /// queue race against the resumed deadline continuation.
     private(set) var latestSeekRenderedTimePublished = false
+    /// AE#629: an in-place swap whose fresh item has not landed its mount seek yet. The swap keeps the
+    /// outgoing item's clock and picture, and until the landing AVPlayer reads first the target, then
+    /// the start of the segment it decodes up from (12.00 s under a 15.97 s revive on the harness).
+    /// Published, that second reading rewinds the playhead, and a software-path rebuild raised in the
+    /// window resumed there and replayed the gap. So neither reading is a landing: only the seek's own
+    /// completion is, or the item playing, which it cannot do short of the target. A seek of the host's
+    /// own takes the clock over from here as well.
+    private var inPlaceSwapMountPending = false
 
     // MARK: - Output
 
@@ -441,6 +449,7 @@ final class NativeAVPlayerHost {
 
         self.sessionContract = contract
         mountedStartPosition = skipInitialSeek ? nil : (startPosition ?? 0)
+        inPlaceSwapMountPending = inPlaceSwap && !skipInitialSeek
         let forwardBufferDuration = contract.forwardBufferDuration
         let httpHeaders = contract.httpHeaders
         let armIngestFallback = contract.armIngestFallback
@@ -682,7 +691,10 @@ final class NativeAVPlayerHost {
                 self.timeControlStatus = status
                 self.startLiveJoinImmediatelyIfHolding(waitingReason: reason)
                 // First .playing: re-sample route after 2.5s settle -- AVKit only negotiates HDMI format on playback start (issue #24).
-                if status == .playing { self.hasEverPlayed = true }
+                if status == .playing {
+                    self.hasEverPlayed = true
+                    self.inPlaceSwapMountPending = false
+                }
                 if status == .playing, !self.didSampleSettledRoute {
                     self.didSampleSettledRoute = true
                     Task { @MainActor [weak self] in
@@ -800,6 +812,7 @@ final class NativeAVPlayerHost {
             let value = time.seconds.isFinite ? time.seconds : 0
             Task { @MainActor in
                 guard let self, self.sessionID == sid else { return }
+                if self.inPlaceSwapMountPending { return }
                 // renderedTime tracks the parked on-screen frame mid-seek (issue #49).
                 self.renderedTime = value
                 // seekInFlight suppresses currentTime: AVPlayer still reports pre-seek clock until physical landing (issue #37).
@@ -859,7 +872,13 @@ final class NativeAVPlayerHost {
                 category: .engine)
             // Load-time seek (not a user scrub): no seekInFlight needed; the async seek(to:) carries #37/#38 semantics for user seeks.
             avPlayer.seek(to: CMTime(seconds: startPosition ?? 0, preferredTimescale: 600),
-                          toleranceBefore: .zero, toleranceAfter: .zero)
+                          toleranceBefore: .zero, toleranceAfter: .zero) { [weak self] finished in
+                guard finished else { return }
+                Task { @MainActor in
+                    guard let self, self.sessionID == sid else { return }
+                    self.inPlaceSwapMountPending = false
+                }
+            }
         }
     }
 
@@ -1775,6 +1794,8 @@ final class NativeAVPlayerHost {
         seekGeneration &+= 1
         let gen = seekGeneration
         seekInFlight = true
+        // AE#629: this seek's own landing publishes the clock from here on.
+        inPlaceSwapMountPending = false
         latestSeekRenderedTimePublished = false
         let resumeGuard = SeekResumeGuard()
         return await withCheckedContinuation { (cont: CheckedContinuation<Bool, Never>) in
diff --git a/Tests/AetherEngineTests/SoftwarePathEscalationTests.swift b/Tests/AetherEngineTests/SoftwarePathEscalationTests.swift
index 706057ed5..aa746d91d 100644
--- a/Tests/AetherEngineTests/SoftwarePathEscalationTests.swift
+++ b/Tests/AetherEngineTests/SoftwarePathEscalationTests.swift
@@ -166,6 +166,27 @@ struct SoftwarePathEscalationTests {
             duringStartup: false)])
     }
 
+    /// Reported as a code reading on AE#629: a rebuild whose load failed after its teardown had
+    /// already published that failure, and the rung then published the absorbed one on top, so the
+    /// host saw two `.error`s for one failure and the second contradicted what `load()` threw.
+    @Test("A rebuild that fails after its teardown surfaces one failure, its own", .timeLimit(.minutes(2)))
+    @MainActor
+    func failedRebuildSurfacesOnce() async throws {
+        let engine = try AetherEngine()
+        // A port nothing listens on: the rebuild tears the session down and its open is refused.
+        engine.loadedURL = try #require(URL(string: "http://127.0.0.1:9/source.mkv"))
+        var errors: [PlaybackErrorInfo?] = []
+        let sub = engine.$state.sink { state in
+            if case .error = state { errors.append(engine.errorInfo) }
+        }
+        defer { sub.cancel() }
+
+        await engine.escalateToSoftwarePath(Self.mediaFailure)
+
+        #expect(errors.count == 1)
+        #expect(errors.first??.kind != .nativeItemFailed)
+    }
+
     /// A custom source whose first read parks until the engine cancels it: a load that cannot finish
     /// and cannot time out, so the takeover is decided against a startup that is really in flight.
     final class ParkedReader: IOReader, @unchecked Sendable {

From 7d2d1f212ae894c041059f92e928315e41e9dd05 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sat, 26 Sep 2026 06:32:36 +0200
Subject: [PATCH 111/359] chore(release): prep 7.17.1 - live joins on intra
 recovery points, undecodable audio no longer stalls or hides

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014AVNwe8YDG9EQM7uHdjT3f
---
 CHANGELOG.md                                    | 4 ++++
 Examples/README.md                              | 2 +-
 README.md                                       | 6 +++---
 Sources/AetherEngine/AetherEngine+Version.swift | 2 +-
 4 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8c559347a..c3ac39aaa 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,10 @@ the public-API contract.
 
 ## [Unreleased]
 
+_Nothing yet._
+
+## [7.17.1] - 2026-09-26
+
 ### Fixed
 
 - **A session revived by the #93 item swap keeps its playhead until the fresh item lands there.**
diff --git a/Examples/README.md b/Examples/README.md
index f52c19d81..409ae3cdd 100644
--- a/Examples/README.md
+++ b/Examples/README.md
@@ -18,7 +18,7 @@ Three samples covering different audiences:
    ```
    https://github.com/superuser404notfound/AetherEngine
    ```
-   Dependency Rule: Up to Next Major Version, starting from `7.17.0`. Add the `AetherEngine` library product to your app target.
+   Dependency Rule: Up to Next Major Version, starting from `7.17.1`. Add the `AetherEngine` library product to your app target.
 
 3. **Drop the file in.** Replace the Xcode template's default `App.swift` (or whatever the generated `@main` file is called) with the contents of [`MinimalPlayerApp.swift`](MinimalPlayer/MinimalPlayerApp.swift). The file is self-contained: it defines both the `@main App` struct and the `ContentView`.
 
diff --git a/README.md b/README.md
index 824590343..d3c03e854 100644
--- a/README.md
+++ b/README.md
@@ -384,7 +384,7 @@ Subtitle cues land in raw source PTS; render the overlay against `player.sourceT
 Install via Swift Package Manager:
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.17.0")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.17.1")
 ```
 
 Three samples ship in `Examples/`:
@@ -631,10 +631,10 @@ Browse all of this as a searchable site at **[aetherengine.superuser404.de](http
 AetherEngine uses [Semantic Versioning](https://semver.org). The public API surface, every `public` declaration in `Sources/AetherEngine/`, is the stability contract. **Major** removes / renames public symbols or breaks adopters; **Minor** adds public API or codec / format support; **Patch** fixes bugs with no public API change. `internal` types are not part of the contract.
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.17.0")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.17.1")
 ```
 
-Pin to `.upToNextMinor(from: "7.17.0")` for stricter teams that prefer to opt into minor bumps explicitly.
+Pin to `.upToNextMinor(from: "7.17.1")` for stricter teams that prefer to opt into minor bumps explicitly.
 
 ## Requirements
 
diff --git a/Sources/AetherEngine/AetherEngine+Version.swift b/Sources/AetherEngine/AetherEngine+Version.swift
index bc883e1f9..3f8065bfc 100644
--- a/Sources/AetherEngine/AetherEngine+Version.swift
+++ b/Sources/AetherEngine/AetherEngine+Version.swift
@@ -11,5 +11,5 @@ extension AetherEngine {
     ///
     /// Between releases, and in a consumer that pins an unreleased commit for a device test, this
     /// names the last PUBLISHED version the checkout descends from, not every patch in it.
-    public nonisolated static let version = "7.17.0"
+    public nonisolated static let version = "7.17.1"
 }

From 2b89ab78bed5fed827a172d766cdb224372c2c0f Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sat, 26 Sep 2026 15:31:53 +0200
Subject: [PATCH 112/359] feat(io): a remote disc image adopts a prewarmed
 source (AE#647)

HTTPDiscIOReader never looked at the prewarm store: a warmed .iso was
fetched, then the disc reader probed its size with bytes=0-0 and pulled
the head again while the warm sat unused until eviction.

The reader now takes the warm under the same rule AVIOReader adopts by
(head at zero, size stated, headers equal), uses its size instead of the
probe, serves reads inside the warmed spans from RAM and starts its first
request at the frontier. Forks share the spans and the size, so a
subtitle side reader or forward prefetcher no longer re-probes either. A
disc-image URL that is no disc hands the warm back to the store for the
streaming reader it falls back to.

Measured with aetherctl on an authored DVD over a 20 Mbit/s, 100 ms
origin: 10 requests after the warm instead of 19, first frame at 23.9 s
instead of 29.6 s.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mf4MXgM9bqugHoe5TW4BYf
---
 CHANGELOG.md                                  |  11 +-
 Sources/AetherEngine/Demuxer/Demuxer.swift    |  24 ++--
 .../AetherEngine/IO/HTTPDiscIOReader.swift    |  92 +++++++++++--
 .../Issue647DiscReaderPrewarmTests.swift      | 129 ++++++++++++++++++
 docs/api.md                                   |   2 +
 5 files changed, 236 insertions(+), 22 deletions(-)
 create mode 100644 Tests/AetherEngineTests/Issue647DiscReaderPrewarmTests.swift

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c3ac39aaa..d64f58483 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,7 +10,16 @@ the public-API contract.
 
 ## [Unreleased]
 
-_Nothing yet._
+### Changed
+
+- **A remote disc image adopts a warm (#647).** `AetherEngine.prewarm` on an `.iso` / `.img` /
+  `.udf` URL was fetched and then never used: the disc reader kept its own buffer, probed the size
+  with `bytes=0-0` and fetched the head again, and the warm stayed in the store. The disc reader now
+  takes the size from the warm, serves the disc structure and the title's opening extents out of it,
+  and starts its first request at the warm frontier; its forks share the same bytes without a copy
+  and no longer re-probe the size. A disc-image URL that turns out not to be a disc hands the warm
+  on to the streaming reader. Measured on an authored DVD over a 20 Mbit/s, 100 ms origin: 10
+  requests after the warm instead of 19, first frame 5.7 s sooner.
 
 ## [7.17.1] - 2026-09-26
 
diff --git a/Sources/AetherEngine/Demuxer/Demuxer.swift b/Sources/AetherEngine/Demuxer/Demuxer.swift
index 05439e4db..2da691188 100644
--- a/Sources/AetherEngine/Demuxer/Demuxer.swift
+++ b/Sources/AetherEngine/Demuxer/Demuxer.swift
@@ -541,17 +541,21 @@ public final class Demuxer: @unchecked Sendable {
         // straight to libavformat fails to probe; it is a filesystem, not a media container, #64).
         // Gated on the disc-image extension so normal media URLs skip the range-probe entirely; if
         // the source is not a recognizable disc, fall through to the streaming reader.
-        if !isLive, Self.isDiscImageURL(url),
-           let discReader = HTTPDiscIOReader(url: url, extraHeaders: extraHeaders) {
-            if let discInfo = try DiscReader.wrap(discReader, selectTitleID: selectTitleID, cacheKey: url.absoluteString) {
-                adoptDiscInfo(discInfo)
-                auditSource = nil
-                let bridge = CustomIOReaderBridge(reader: discInfo.reader)
-                let inputFormat = av_find_input_format(discInfo.formatHint)
-                try openWithProvider(bridge, inputFormat: inputFormat, isLive: false)
-                return
+        if !isLive, Self.isDiscImageURL(url) {
+            let warm = HTTPDiscIOReader.takePrewarm(for: url, extraHeaders: extraHeaders)
+            if let discReader = HTTPDiscIOReader(url: url, extraHeaders: extraHeaders, prewarmed: warm) {
+                if let discInfo = try DiscReader.wrap(discReader, selectTitleID: selectTitleID, cacheKey: url.absoluteString) {
+                    adoptDiscInfo(discInfo)
+                    auditSource = nil
+                    let bridge = CustomIOReaderBridge(reader: discInfo.reader)
+                    let inputFormat = av_find_input_format(discInfo.formatHint)
+                    try openWithProvider(bridge, inputFormat: inputFormat, isLive: false)
+                    return
+                }
+                discReader.close()
             }
-            discReader.close()
+            // Not a disc: hand the warm back so the streaming reader below adopts it (#647).
+            if let warm { SourcePrewarmStore.shared.store(warm, for: url) }
         }
         let reader = AVIOReader(
             url: url,
diff --git a/Sources/AetherEngine/IO/HTTPDiscIOReader.swift b/Sources/AetherEngine/IO/HTTPDiscIOReader.swift
index 4e1fff94e..12a2df881 100644
--- a/Sources/AetherEngine/IO/HTTPDiscIOReader.swift
+++ b/Sources/AetherEngine/IO/HTTPDiscIOReader.swift
@@ -14,6 +14,10 @@ import Foundation
 /// range request retries with backoff so a transient network blip does not end playback. The server
 /// MUST honor range requests (any static file host does); if it does not, `init` returns nil after a
 /// clear log and the caller falls back to the plain streaming path.
+///
+/// A source the host warmed with `AetherEngine.prewarm` (#551) is read out of those bytes first
+/// (#647): the warm has already stated the size and proven range support, so the reader neither
+/// probes nor refetches the head, and its first request starts at the warm frontier.
 final class HTTPDiscIOReader: IOReader, @unchecked Sendable {
 
     private let url: URL
@@ -24,6 +28,8 @@ final class HTTPDiscIOReader: IOReader, @unchecked Sendable {
     private let maxChunkSize: Int
     private let maxRetries: Int
     private let totalSize: Int64
+    /// Warmed bytes (#647), read before the network. Immutable, so a fork shares them without a copy.
+    private let residentSpans: [ResidentSpan]
 
     private let lock = NSLock()
     private var position: Int64 = 0
@@ -39,15 +45,35 @@ final class HTTPDiscIOReader: IOReader, @unchecked Sendable {
     private let cancelLock = NSLock()
     private var cancelled = false
 
-    /// Probes total size and range support with one (retried) `bytes=0-0` request. Returns nil if
-    /// the source is unreachable or answers `200` (full body, no range support); logs which.
-    init?(url: URL,
-          extraHeaders: [String: String] = [:],
-          baseChunkSize: Int = 256 * 1024,
-          maxChunkSize: Int = 8 * 1024 * 1024,
-          maxRetries: Int = 3,
-          requestTimeout: TimeInterval = 30,
-          sessionConfiguration: URLSessionConfiguration? = nil) {
+    /// Probes total size and range support with one (retried) `bytes=0-0` request, unless
+    /// `prewarmed` has already stated both. Returns nil if the source is unreachable or answers `200`
+    /// (full body, no range support); logs which.
+    convenience init?(url: URL,
+                      extraHeaders: [String: String] = [:],
+                      baseChunkSize: Int = 256 * 1024,
+                      maxChunkSize: Int = 8 * 1024 * 1024,
+                      maxRetries: Int = 3,
+                      requestTimeout: TimeInterval = 30,
+                      sessionConfiguration: URLSessionConfiguration? = nil,
+                      prewarmed: PrewarmedSource? = nil) {
+        self.init(url: url, extraHeaders: extraHeaders, baseChunkSize: baseChunkSize,
+                  maxChunkSize: maxChunkSize, maxRetries: maxRetries, requestTimeout: requestTimeout,
+                  sessionConfiguration: sessionConfiguration,
+                  knownSize: prewarmed?.contentLength,
+                  residentSpans: prewarmed.map { [$0.head] + ($0.tail.map { [$0] } ?? []) } ?? [])
+    }
+
+    /// `knownSize` skips the range probe. Only a source that has already answered a range request
+    /// with its total may pass it: the warm, or the reader a fork is made from.
+    private init?(url: URL,
+                  extraHeaders: [String: String],
+                  baseChunkSize: Int,
+                  maxChunkSize: Int,
+                  maxRetries: Int,
+                  requestTimeout: TimeInterval,
+                  sessionConfiguration: URLSessionConfiguration?,
+                  knownSize: Int64?,
+                  residentSpans: [ResidentSpan]) {
         self.url = url
         self.extraHeaders = extraHeaders
         self.baseChunkSize = max(64 * 1024, baseChunkSize)
@@ -62,7 +88,12 @@ final class HTTPDiscIOReader: IOReader, @unchecked Sendable {
         }()
         self.session = URLSession(
             configuration: config, delegate: EngineTLS.sessionDelegate, delegateQueue: nil)
+        self.residentSpans = residentSpans.filter { !$0.isEmpty }
 
+        if let knownSize, knownSize > 0 {
+            self.totalSize = knownSize
+            return
+        }
         guard let size = Self.probeSize(
             url: url, extraHeaders: extraHeaders, session: session,
             timeout: requestTimeout, maxRetries: max(0, maxRetries)
@@ -73,6 +104,28 @@ final class HTTPDiscIOReader: IOReader, @unchecked Sendable {
         self.totalSize = size
     }
 
+    /// #647: take what a host warmed for this URL, under the rule `AVIOReader` adopts by (#551).
+    ///
+    /// A take, like every adoption: the reader holds the bytes from here on. A caller whose source
+    /// turns out not to be a disc puts them back (`SourcePrewarmStore.store`) so the streaming
+    /// reader it falls back to adopts them instead.
+    static func takePrewarm(for url: URL, extraHeaders: [String: String],
+                            store: SourcePrewarmStore = .shared) -> PrewarmedSource? {
+        guard let warm = store.take(for: url) else { return nil }
+        guard warm.head.start == 0, !warm.head.isEmpty, warm.contentLength > 0 else { return nil }
+        guard warm.requestHeaders == extraHeaders else {
+            EngineLog.emit(
+                "[HTTPDiscIOReader] \(url.lastPathComponent): a warm exists for this URL but was "
+                + "fetched with different headers; opening cold (#647)", category: .demux)
+            return nil
+        }
+        EngineLog.emit(
+            "[HTTPDiscIOReader] \(url.lastPathComponent): adopted a prewarmed source: "
+            + "head=\(warm.head.data.count)B tail=\(warm.tail?.data.count ?? 0)B of "
+            + "\(warm.contentLength)B (#647)", category: .demux)
+        return warm
+    }
+
     // MARK: - Pure helpers
 
     /// Inclusive byte-range header for a half-open `[offset, offset+length)` window.
@@ -112,11 +165,26 @@ final class HTTPDiscIOReader: IOReader, @unchecked Sendable {
         lock.lock(); defer { lock.unlock() }
         if position >= totalSize { return 0 }
 
+        if let span = residentSpans.first(where: { $0.covers(position) }) {
+            let spanOffset = Int(position - span.start)
+            let toCopy = min(Int(n), span.data.count - spanOffset, Int(totalSize - position))
+            span.data.withUnsafeBytes { src in
+                out.update(from: src.baseAddress!.assumingMemoryBound(to: UInt8.self)
+                    .advanced(by: spanOffset), count: toCopy)
+            }
+            position += Int64(toCopy)
+            // Reading on past the span is the sequential continuation, so the window grows there.
+            lastFetchEnd = position
+            return Int32(toCopy)
+        }
+
         if position < bufferStart || position >= bufferStart + Int64(buffer.count) {
             currentChunkSize = Self.nextChunkSize(
                 position: position, lastFetchEnd: lastFetchEnd,
                 current: currentChunkSize, base: baseChunkSize, maxChunk: maxChunkSize)
-            let want = Int(min(Int64(currentChunkSize), totalSize - position))
+            // Stop at the next warmed span: its bytes are already here.
+            let limit = residentSpans.lazy.map(\.start).filter { $0 > self.position }.min() ?? totalSize
+            let want = Int(min(Int64(currentChunkSize), limit - position))
             guard want > 0, let data = fetchWithRetry(offset: position, length: want), !data.isEmpty else {
                 return -1
             }
@@ -161,7 +229,9 @@ final class HTTPDiscIOReader: IOReader, @unchecked Sendable {
     func makeIndependentReader() -> IOReader? {
         HTTPDiscIOReader(url: url, extraHeaders: extraHeaders,
                          baseChunkSize: baseChunkSize, maxChunkSize: maxChunkSize,
-                         maxRetries: maxRetries, requestTimeout: requestTimeout)
+                         maxRetries: maxRetries, requestTimeout: requestTimeout,
+                         sessionConfiguration: nil,
+                         knownSize: totalSize, residentSpans: residentSpans)
     }
 
     // MARK: - HTTP
diff --git a/Tests/AetherEngineTests/Issue647DiscReaderPrewarmTests.swift b/Tests/AetherEngineTests/Issue647DiscReaderPrewarmTests.swift
new file mode 100644
index 000000000..7604bb88b
--- /dev/null
+++ b/Tests/AetherEngineTests/Issue647DiscReaderPrewarmTests.swift
@@ -0,0 +1,129 @@
+import Testing
+import Foundation
+@testable import AetherEngine
+
+/// #647: a remote disc image the host warmed is read out of the warm, the way any other source is.
+///
+/// Before this the disc reader never looked at the store: it probed the size with `bytes=0-0`,
+/// refetched the head, and left the warm in the store for the streaming reader that never came.
+///
+/// `.serialized`: the Demuxer case goes through the process-wide store. The reader cases use a
+/// private store so nothing here depends on another suite leaving `.shared` alone.
+@Suite("Disc reader adopts a prewarmed source (#647)", .serialized)
+struct Issue647DiscReaderPrewarmTests {
+
+    private let fileSize: Int64 = 64 * 1024 * 1024
+    private let warmBytes = 1024 * 1024
+
+    private func url(_ server: ThrottledOriginServer, _ name: String = "disc.iso") -> URL {
+        URL(string: "http://127.0.0.1:\(server.port)/\(name)")!
+    }
+
+    private func read(_ reader: IOReader, at offset: Int64, _ size: Int) -> [UInt8] {
+        _ = reader.seek(offset: offset, whence: SEEK_SET)
+        var out: [UInt8] = []
+        let buf = UnsafeMutablePointer<UInt8>.allocate(capacity: size)
+        defer { buf.deallocate() }
+        while out.count < size {
+            let n = reader.read(buf, size: Int32(size - out.count))
+            guard n > 0 else { break }
+            out.append(contentsOf: UnsafeBufferPointer(start: buf, count: Int(n)))
+        }
+        return out
+    }
+
+    private func expected(at offset: Int64, _ size: Int) -> [UInt8] {
+        (0..<Int64(size)).map { ThrottledOriginServer.patternByte(at: offset + $0) }
+    }
+
+    private func warmedReader(_ server: ThrottledOriginServer,
+                              store: SourcePrewarmStore) async throws -> HTTPDiscIOReader {
+        let report = await SourcePrewarmFetcher.warm(url: url(server), extraHeaders: [:],
+                                                     byteBudget: warmBytes, into: store)
+        #expect(report.retainedBytes == warmBytes)
+        let warm = try #require(HTTPDiscIOReader.takePrewarm(for: url(server), extraHeaders: [:],
+                                                             store: store))
+        #expect(!store.isWarm(for: url(server)), "adoption takes the entry")
+        return try #require(HTTPDiscIOReader(url: url(server), prewarmed: warm))
+    }
+
+    @Test("reads inside the warm cost no request, and the size is not probed")
+    func warmServesTheHead() async throws {
+        let server = try #require(ThrottledOriginServer(totalSize: fileSize, patternedBody: true))
+        defer { server.stop() }
+        let reader = try await warmedReader(server, store: SourcePrewarmStore(totalByteCap: 8 << 20))
+        defer { reader.close() }
+        let afterWarm = server.requestedRanges.count
+
+        #expect(reader.seek(offset: 0, whence: 65536) == fileSize)
+        // The disc layer's opening shape: the ISO 9660 sniff at 0x8001, the UDF anchor at sector
+        // 256, a directory read back near the start.
+        #expect(read(reader, at: 0x8001, 5) == expected(at: 0x8001, 5))
+        #expect(read(reader, at: 256 * 2048, 2048) == expected(at: 256 * 2048, 2048))
+        #expect(read(reader, at: 40_960, 64 * 1024) == expected(at: 40_960, 64 * 1024))
+        #expect(server.requestedRanges.count == afterWarm,
+                "a read inside the warm went to the network: \(server.requestedRanges.dropFirst(afterWarm))")
+    }
+
+    @Test("a read across the warm frontier is exact and fetches from the frontier on")
+    func frontierContinues() async throws {
+        let server = try #require(ThrottledOriginServer(totalSize: fileSize, patternedBody: true))
+        defer { server.stop() }
+        let reader = try await warmedReader(server, store: SourcePrewarmStore(totalByteCap: 8 << 20))
+        defer { reader.close() }
+        let afterWarm = server.requestedRanges.count
+
+        let start = Int64(warmBytes) - 1000
+        #expect(read(reader, at: start, 300_000) == expected(at: start, 300_000))
+        let opened = Array(server.requestedRanges.dropFirst(afterWarm))
+        #expect(opened.first?.start == Int64(warmBytes), "requests: \(opened)")
+        #expect(!opened.contains(where: { $0.start < Int64(warmBytes) }), "requests: \(opened)")
+    }
+
+    @Test("a fork shares the warm and the size, so it neither probes nor refetches the head")
+    func forkSharesTheWarm() async throws {
+        let server = try #require(ThrottledOriginServer(totalSize: fileSize, patternedBody: true))
+        defer { server.stop() }
+        let reader = try await warmedReader(server, store: SourcePrewarmStore(totalByteCap: 8 << 20))
+        defer { reader.close() }
+        let afterWarm = server.requestedRanges.count
+
+        let fork = try #require(reader.makeIndependentReader())
+        defer { fork.close() }
+        #expect(fork.seek(offset: 0, whence: 65536) == fileSize)
+        #expect(read(fork, at: 0, 128 * 1024) == expected(at: 0, 128 * 1024))
+        #expect(server.requestedRanges.count == afterWarm,
+                "the fork went to the network: \(server.requestedRanges.dropFirst(afterWarm))")
+    }
+
+    @Test("a warm fetched with other headers is not adopted")
+    func headersMustMatch() async throws {
+        let server = try #require(ThrottledOriginServer(totalSize: fileSize))
+        defer { server.stop() }
+        let store = SourcePrewarmStore(totalByteCap: 8 << 20)
+        _ = await SourcePrewarmFetcher.warm(url: url(server), extraHeaders: ["Referer": "a"],
+                                            byteBudget: warmBytes, into: store)
+        #expect(HTTPDiscIOReader.takePrewarm(for: url(server), extraHeaders: ["Referer": "b"],
+                                             store: store) == nil)
+    }
+
+    @Test("a disc-image URL that is no disc hands the warm to the streaming reader")
+    func notADiscKeepsTheWarm() async throws {
+        let server = try #require(ThrottledOriginServer(totalSize: fileSize, patternedBody: true))
+        defer { server.stop() }
+        let source = url(server, "not-a-disc.iso")
+        _ = await SourcePrewarmFetcher.warm(url: source, extraHeaders: [:],
+                                            byteBudget: warmBytes, into: .shared)
+        let afterWarm = server.requestedRanges.count
+
+        let demuxer = Demuxer()
+        defer { demuxer.close() }
+        // Patterned bytes are no container, so the open fails; what it asked the origin is the point.
+        try? demuxer.open(url: source)
+
+        let opened = Array(server.requestedRanges.dropFirst(afterWarm))
+        #expect(!opened.contains(where: { $0.start == 0 }),
+                "the open re-fetched bytes it already had: \(opened)")
+        #expect(!SourcePrewarmStore.shared.isWarm(for: source))
+    }
+}
diff --git a/docs/api.md b/docs/api.md
index 3ea6354d9..f718096b3 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -521,6 +521,8 @@ What it fetches: one ranged GET from byte zero for the budget, plus a second one
 
 A warm also hands the load **where the bytes live**. A resolver URL that answers 302 with a temporary edge target is resolved once, by the warm, and the session starts at that target instead of resolving the chain again; a lease that has since run out falls back to the source URL through the same ladder a mid-session expiry uses. Credential headers (`Authorization`, `Cookie`, `X-Emby-Token` and the rest of the #126 set) never travel to a cross-origin target, whether it was reached through a redirect or pinned from a warm.
 
+Remote disc images (`.iso` / `.img` / `.udf` over HTTP) adopt a warm too (#647). The disc reader takes the size from the warm instead of probing for it, answers the disc layer's structure reads and the title's opening extents out of the head, and starts its first request at the warm frontier; its forks (the subtitle side reader, the forward prefetcher) share the same bytes without a copy. It does not pin the warm's redirect target, because that reader follows redirects per request. A disc-image URL that turns out not to be a disc hands the warm on to the streaming reader.
+
 Three limits are part of the contract rather than implementation detail:
 
 - **It never queues for the origin.** A warm takes a request slot only if one is free right now, and declines when the origin is metered down to one request at a time or is pacing the engine (`maxConcurrentSourceRequests`, #377). A prewarm that would have to wait for the playing session's uplink has stopped helping.

From 68aed09dc999a316bc956f86114eef9d39b6baf7 Mon Sep 17 00:00:00 2001
From: Andreas Busslinger <tschuegy@users.noreply.github.com>
Date: Sat, 26 Sep 2026 15:40:00 +0200
Subject: [PATCH 113/359] fix(session): a quiet consumer that is still
 rendering is not a backpressure wedge (AE#649)

The #65 slow path tripped on the fetch target alone. AVPlayer on a cellular
iPhone fetches the loopback playlist in bursts and then plays out a forward
buffer of up to 109 s without a request, so a healthy session broke the park
every few minutes; the #421 nudge seek it led to flushed the buffer on screen
(a half-second freeze of picture and sound) and the re-anchor read the source
it already held a second time.

The slow path now counts only seconds in which the consumer neither moved its
fetch target nor advanced its rendered clock: a second with an advancing clock
is held, a fetch still resets. Without a rendered position every second counts
as before. A consumer that really stopped fetching plays its buffer dry and
breaks on the fast path. The PARK line carries the count as idle= and names a
quiet but rendering consumer; aetherctl seektest reads idle=0s as a healthy
park.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md                                  | 12 +++-
 .../Video/HLSSegmentProducer.swift            |  7 +-
 .../Video/Issue65LivelockBreakers.swift       | 47 ++++++++++++--
 Sources/aetherctl/SeekTest.swift              |  9 +--
 .../Issue65LivelockTests.swift                | 65 +++++++++++++++++++
 docs/cli.md                                   |  2 +-
 6 files changed, 129 insertions(+), 13 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c3ac39aaa..7296866dc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,7 +10,17 @@ the public-API contract.
 
 ## [Unreleased]
 
-_Nothing yet._
+### Fixed
+
+- **A VOD consumer that goes quiet while it keeps playing no longer trips the #65 wedge breaker.**
+  AVPlayer on a cellular iPhone fetches in bursts, several segments at once and then nothing for 24
+  to 58 s while it plays out a forward buffer of up to 109 s. The slow path counted that silence alone, broke the
+  park every few minutes and nudge-seeked a healthy session, which flushed the buffer on screen: a
+  half-second freeze of picture and sound each time, and a re-anchor that fetched the source it
+  already held a second time. The slow path now counts only seconds in which the consumer neither
+  fetched nor rendered; one that really stopped fetching still breaks on the fast path once its
+  buffer runs dry. The `PARK` line carries the new count as `idle=` and names a quiet but playing
+  consumer as such (AE#649).
 
 ## [7.17.1] - 2026-09-26
 
diff --git a/Sources/AetherEngine/Video/HLSSegmentProducer.swift b/Sources/AetherEngine/Video/HLSSegmentProducer.swift
index 0a3cf7c2c..d35b797c7 100644
--- a/Sources/AetherEngine/Video/HLSSegmentProducer.swift
+++ b/Sources/AetherEngine/Video/HLSSegmentProducer.swift
@@ -768,7 +768,8 @@ final class HLSSegmentProducer: @unchecked Sendable {
 
     /// #65 watchdog: break a VOD backpressure park once the consumer fetch target has been frozen this long.
     /// Set above the log threshold so the diag tuple surfaces first. The host then re-anchors the producer on
-    /// AVPlayer's real position; a slow-but-advancing consumer never trips the detector (see BackpressureWedgeDetector).
+    /// AVPlayer's real position; a slow-but-advancing consumer never trips the detector, and seconds in which
+    /// the rendered clock advanced do not count toward it (AE#649; see BackpressureWedgeDetector).
     private static let backpressureWedgeBreakThresholdSeconds = 24
 
     /// #207: a disk park is normal steady state for an opt-in prefetch, so it stays quiet until it has
@@ -1825,12 +1826,16 @@ final class HLSSegmentProducer: @unchecked Sendable {
                     // asking for segments, and stuck= is that number: 0 is a viewer scrubbing through
                     // resident content, a climbing one is a consumer that went quiet.
                     : wedgeDetector.secondsSinceTargetMoved == 0 ? "(consumer still fetching)"
+                    // AE#649: quiet but rendering is a consumer playing out its forward buffer,
+                    // and idle= (what the breaker counts) stays put while it does.
+                    : wedgeDetector.lastPollRendered ? "(consumer quiet, still playing)"
                     : "(no playback progress)"
                 EngineLog.emit(
                     "[HLSSegmentProducer] #65 backpressure PARK (\(context)) head=\(head) "
                     + "target=\(target) cacheTarget=\(cacheTarget) "
                     + "highStored=\(cache.highestStoredIndex) cached=\(cache.count) parked=\(parked)s "
                     + "stuck=\(wedgeDetector.secondsSinceTargetMoved)s "
+                    + "idle=\(wedgeDetector.secondsWithoutProgress)s "
                     + suspendReason,
                     category: .session
                 )
diff --git a/Sources/AetherEngine/Video/Issue65LivelockBreakers.swift b/Sources/AetherEngine/Video/Issue65LivelockBreakers.swift
index f1c52e811..8a8151941 100644
--- a/Sources/AetherEngine/Video/Issue65LivelockBreakers.swift
+++ b/Sources/AetherEngine/Video/Issue65LivelockBreakers.swift
@@ -10,9 +10,10 @@ import Foundation
 /// (`SegmentCache.targetIndex`) reaches a release target. A genuine wedge is the consumer target
 /// frozen for `breakThresholdSeconds` while AVPlayer is stuck and issuing no forward segment request;
 /// a slow-but-advancing consumer (cold cache, throttled CDN) keeps nudging the target up and must
-/// NEVER trip the breaker. Feed `observe(currentTarget:)` once per ~1 s poll (`ParkClock` makes the
-/// caller's wakeups into seconds): it resets the stuck timer whenever the target MOVES, so only a
-/// target that is frozen for the whole window trips.
+/// NEVER trip the breaker, and neither must a quiet consumer that is still rendering (AE#649).
+/// Feed `observe(currentTarget:)` once per ~1 s poll (`ParkClock` makes the caller's wakeups into
+/// seconds): it resets the stuck timer whenever the target MOVES, so only a target that is frozen for
+/// the whole window trips.
 struct BackpressureWedgeDetector {
     let breakThresholdSeconds: Int
     /// #93 retest fast path: trip after this many consecutive polls where the fetch target AND the
@@ -27,10 +28,17 @@ struct BackpressureWedgeDetector {
     /// at all. `maxTargetSeen` cannot: it only ever climbs.
     private var lastTarget: Int
     private var stuckSeconds: Int = 0
+    /// AE#649: what the slow path trips on. Polls since the target last moved in which the rendered
+    /// clock did not advance either; a poll whose clock advanced is held, not counted. Without a
+    /// rendered position every poll counts, so it equals `stuckSeconds` exactly as before.
+    private var idleSeconds: Int = 0
     private var lastRenderedPosition: Double?
     private var flatSeconds: Int = 0
     /// Diagnostic: whether the last `true` from `observe` came from the fast path.
     private(set) var lastTripFast = false
+    /// AE#649 diagnostic: whether the last poll saw the rendered clock move. The PARK line names a
+    /// quiet consumer that is playing out what it already holds, so it cannot be read as a stuck one.
+    private(set) var lastPollRendered = false
 
     /// AE#528 diagnostic: polls since the consumer's fetch target last moved. The PARK line carries
     /// it, so a park that is plain backpressure behind a consumer that keeps fetching (stuck=0s, a
@@ -38,6 +46,11 @@ struct BackpressureWedgeDetector {
     /// instead of being inferred from `cacheTarget` deltas across log lines after the fact.
     var secondsSinceTargetMoved: Int { stuckSeconds }
 
+    /// AE#649 diagnostic: the count the slow path trips on (see `idleSeconds`). The PARK line carries
+    /// it beside `stuck=`, so a park behind a consumer that is quiet but playing (stuck climbing, idle
+    /// at 0) reads differently from one behind a consumer that stopped both fetching and rendering.
+    var secondsWithoutProgress: Int { idleSeconds }
+
     /// Rendered-clock deltas below this are aliasing/representation jitter, not playback progress
     /// (one poll second of real playback advances the clock by ~1 s).
     static let renderedClockFlatEpsilon: Double = 0.1
@@ -54,6 +67,17 @@ struct BackpressureWedgeDetector {
     /// Returns `true` once the consumer fetch target has been frozen for `breakThresholdSeconds`, or
     /// (fast path) once target and rendered clock have both been frozen for `fastBreakThresholdSeconds`.
     ///
+    /// AE#649: with a rendered position wired, frozen for the slow path means frozen with NO
+    /// playback progress. A consumer can go quiet for longer than the threshold while playing
+    /// perfectly: AVPlayer on a cellular iPhone fetches in bursts, several segments at once and
+    /// then nothing for 24 to 58 s while it plays out a forward buffer of up to 109 s (the same
+    /// title on Wi-Fi fetched one segment every 3 to 7 s). Counting that silence tripped the
+    /// breaker every few minutes, and the #421 nudge seek it led to flushed the buffer on screen: a
+    /// half-second freeze of picture and sound, each time. Seconds in which the rendered clock
+    /// advanced are therefore held rather than counted. A consumer that really stopped fetching
+    /// still plays its buffer dry and then renders nothing, and that is the fast path's shape, so
+    /// it breaks within `fastBreakThresholdSeconds` of the clock going flat.
+    ///
     /// AE#528: frozen means UNCHANGED, not "no higher than before". A viewer scrubbing backwards
     /// declares a LOWER fetch target on every GET, and against a monotone high-water that was
     /// indistinguishable from a consumer that had stopped asking for anything: the busiest consumer
@@ -70,8 +94,9 @@ struct BackpressureWedgeDetector {
     /// (AVPlayer wants to play but is starved, `timeControlStatus == .waitingToPlay`) keeps `wantsToPlay`
     /// true and still trips. Defaults to true so existing callers and live keep their prior behaviour.
     ///
-    /// `renderedPosition` feeds the fast path; nil (not wired: tests, live) keeps it inert. Any move
-    /// beyond the flat epsilon, forward or backward (a new seek landing), restarts the flat window.
+    /// `renderedPosition` feeds the fast path and holds the slow count while the clock moves; nil (not
+    /// wired: tests, live) keeps both inert. Any move beyond the flat epsilon, forward or backward (a new
+    /// seek landing), restarts the flat window.
     ///
     /// `hasStartedRendering` is the cold-startup guard: before AVPlayer has ever presented a frame
     /// (`timeControlStatus` never reached `.playing`), a flat rendered clock is normal pre-roll, NOT a
@@ -87,7 +112,9 @@ struct BackpressureWedgeDetector {
             if currentTarget > maxTargetSeen { maxTargetSeen = currentTarget }
             lastTarget = currentTarget
             stuckSeconds = 0
+            idleSeconds = 0
             flatSeconds = 0
+            lastPollRendered = false
             if let rendered = renderedPosition { lastRenderedPosition = rendered }
             return false
         }
@@ -97,12 +124,20 @@ struct BackpressureWedgeDetector {
         if targetAdvanced { maxTargetSeen = currentTarget }
         stuckSeconds = targetMoved ? 0 : stuckSeconds + 1
         var clockFlat = false
+        var clockMoved = false
         if let rendered = renderedPosition {
             if let last = lastRenderedPosition {
                 clockFlat = abs(rendered - last) < Self.renderedClockFlatEpsilon
+                clockMoved = !clockFlat
             }
             lastRenderedPosition = rendered
         }
+        lastPollRendered = clockMoved
+        if targetMoved {
+            idleSeconds = 0
+        } else if !clockMoved {
+            idleSeconds += 1
+        }
         if targetAdvanced || !clockFlat {
             flatSeconds = 0
         } else {
@@ -112,7 +147,7 @@ struct BackpressureWedgeDetector {
             lastTripFast = true
             return true
         }
-        if stuckSeconds >= breakThresholdSeconds {
+        if idleSeconds >= breakThresholdSeconds {
             lastTripFast = false
             return true
         }
diff --git a/Sources/aetherctl/SeekTest.swift b/Sources/aetherctl/SeekTest.swift
index 5c71b747a..b69d01b86 100644
--- a/Sources/aetherctl/SeekTest.swift
+++ b/Sources/aetherctl/SeekTest.swift
@@ -21,7 +21,8 @@ private func seekTestRun(url: URL, seeks: Int, gapMs: Int, settleSeconds: Double
     let parkCount = UncheckedBox<Int>(0)
     // AE#528: a park whose PARK line says stuck=0s is backpressure behind a consumer that is still
     // fetching (a viewer scrubbing through resident content), and the breaker deliberately does not
-    // fire there. Counted apart so the verdict cannot read a healthy park as an unrecovered wedge.
+    // fire there. AE#649 widened it to idle=0s, which also covers a consumer that is quiet but still
+    // rendering. Counted apart so the verdict cannot read a healthy park as an unrecovered wedge.
     let liveConsumerParkCount = UncheckedBox<Int>(0)
     // #65 fix signals: did the VOD wedge breaker fire and recover (Piece A producer re-anchor + Piece B
     // engine seek-deadline clock reconcile)? A wedge that is BROKEN + re-anchored is the fix engaging.
@@ -73,7 +74,7 @@ private func seekTestRun(url: URL, seeks: Int, gapMs: Int, settleSeconds: Double
         // "[HLSSegmentProducer] #65 backpressure PARK ...". Count abnormal parks (VOD wedge signature).
         if line.contains("#65 backpressure PARK") {
             parkCount.value += 1
-            if line.contains("stuck=0s") { liveConsumerParkCount.value += 1 }
+            if line.contains("idle=0s") { liveConsumerParkCount.value += 1 }
         }
         // Fix engaging: the wedge breaker exited the pump, the host re-anchored, and/or the seek deadline reconciled.
         if line.contains("#65 backpressure WEDGE BROKEN") { wedgeBrokenCount.value += 1 }
@@ -320,8 +321,8 @@ private func seekTestRun(url: URL, seeks: Int, gapMs: Int, settleSeconds: Double
         print("     leads the clock. The live seam-history port is the fix.")
     } else if parkCount.value > 0, parkCount.value == liveConsumerParkCount.value, !fixEngaged {
         print("  >> PARKED BEHIND A LIVE CONSUMER (not a wedge): \(parkCount.value) park(s), every one of them")
-        print("     logged stuck=0s, so the consumer kept declaring new fetch targets the whole time. The")
-        print("     breaker staying quiet here is AE#528 working; a wedge is a park whose stuck= climbs.")
+        print("     logged idle=0s, so the consumer kept declaring fetch targets or kept rendering the whole")
+        print("     time. The breaker staying quiet here is AE#528 working; a wedge is a park whose idle= climbs.")
     } else if parkCount.value > 0 {
         if fixEngaged {
             print("  >> PRODUCER WEDGE DETECTED AND BROKEN: \(parkCount.value) abnormal park(s) but the breaker fired")
diff --git a/Tests/AetherEngineTests/Issue65LivelockTests.swift b/Tests/AetherEngineTests/Issue65LivelockTests.swift
index 1196bade3..3fd01d981 100644
--- a/Tests/AetherEngineTests/Issue65LivelockTests.swift
+++ b/Tests/AetherEngineTests/Issue65LivelockTests.swift
@@ -285,6 +285,71 @@ struct Issue65LivelockTests {
         #expect(d.observe(currentTarget: 84, renderedPosition: 391.902) == true)  // 3s -> fast wedge
     }
 
+    // MARK: - BackpressureWedgeDetector quiet but rendering consumer (AE#649)
+
+    @Test("A consumer that goes quiet while it keeps rendering never trips the slow path (AE#649)")
+    func quietRenderingConsumerNeverTrips() {
+        // Field shape, cellular iPhone: AVPlayer fetched a burst of segments, then nothing for 58 s while
+        // it played through its forward buffer. Production thresholds: the old slow path tripped at 24 s
+        // and its nudge seek flushed the buffer on screen.
+        var d = BackpressureWedgeDetector(
+            breakThresholdSeconds: 24, fastBreakThresholdSeconds: 5,
+            initialTarget: 453, initialRenderedPosition: 1697.1)
+        for i in 1...58 {
+            #expect(d.observe(currentTarget: 453, renderedPosition: 1697.1 + Double(i)) == false)
+        }
+        #expect(d.secondsSinceTargetMoved == 58)
+        #expect(d.secondsWithoutProgress == 0)
+        #expect(d.lastPollRendered == true)
+    }
+
+    @Test("A quiet consumer that plays its buffer dry still breaks on the fast path (AE#649)")
+    func quietConsumerThatRunsDryFastTrips() {
+        // A consumer that really stopped fetching looks exactly like the healthy one above until its
+        // buffer runs out; from then it renders nothing, and that has to break in single digits.
+        var d = BackpressureWedgeDetector(
+            breakThresholdSeconds: 24, fastBreakThresholdSeconds: 5,
+            initialTarget: 453, initialRenderedPosition: 100.0)
+        for i in 1...30 {
+            #expect(d.observe(currentTarget: 453, renderedPosition: 100.0 + Double(i)) == false)
+        }
+        for _ in 1...4 {
+            #expect(d.observe(currentTarget: 453, renderedPosition: 130.0) == false)
+        }
+        #expect(d.observe(currentTarget: 453, renderedPosition: 130.0) == true) // 5th flat poll
+        #expect(d.lastTripFast == true)
+        #expect(d.lastPollRendered == false)
+    }
+
+    @Test("Rendering seconds hold the slow count rather than reset it (AE#649)")
+    func renderingHoldsTheSlowCount() {
+        // A consumer that neither fetches nor plays steadily (a frame now and then) is not saved by
+        // the odd frame: only the seconds without progress count, and they add up across the frames.
+        var d = BackpressureWedgeDetector(breakThresholdSeconds: 3, initialTarget: 53,
+                                          initialRenderedPosition: 10.0)
+        #expect(d.observe(currentTarget: 53, renderedPosition: 11.0) == false) // rendered, idle 0
+        #expect(d.observe(currentTarget: 53, renderedPosition: 11.0) == false) // idle 1
+        #expect(d.observe(currentTarget: 53, renderedPosition: 12.0) == false) // rendered, held at 1
+        #expect(d.observe(currentTarget: 53, renderedPosition: 12.0) == false) // idle 2
+        #expect(d.observe(currentTarget: 53, renderedPosition: 13.0) == false) // rendered, held at 2
+        #expect(d.observe(currentTarget: 53, renderedPosition: 13.0) == true)  // idle 3 -> slow wedge
+        #expect(d.lastTripFast == false)
+        #expect(d.secondsSinceTargetMoved == 6)
+    }
+
+    @Test("A fetch still restarts the slow count from zero (AE#649)")
+    func fetchResetsTheSlowCount() {
+        var d = BackpressureWedgeDetector(breakThresholdSeconds: 3, initialTarget: 53,
+                                          initialRenderedPosition: 10.0)
+        #expect(d.observe(currentTarget: 53, renderedPosition: 10.0) == false) // idle 1
+        #expect(d.observe(currentTarget: 53, renderedPosition: 10.0) == false) // idle 2
+        #expect(d.observe(currentTarget: 54, renderedPosition: 10.0) == false) // fetch -> 0
+        #expect(d.secondsWithoutProgress == 0)
+        #expect(d.observe(currentTarget: 54, renderedPosition: 10.0) == false) // idle 1
+        #expect(d.observe(currentTarget: 54, renderedPosition: 10.0) == false) // idle 2
+        #expect(d.observe(currentTarget: 54, renderedPosition: 10.0) == true)  // idle 3
+    }
+
     // MARK: - seekIsWedged (Piece B)
 
     @Test("Empty forward buffer at the rendered position is a wedge")
diff --git a/docs/cli.md b/docs/cli.md
index 3e4f5a51e..0b2bde2d1 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -733,7 +733,7 @@ Note that the slicing is byte-based, not keyframe-aligned, so segments start mid
 
 Drives a real AVPlayer (native loopback-HLS path) through a burst of rapid seeks and reports the producer-restart coalescing behavior, the longest "wedge" (state `.playing` but the clock frozen), and final settle accuracy (AetherEngine#35). A concurrent sampler probe also checks the seek clock-bounce / `isSeeking` signal (AetherEngine#37 / #38): a single backward seek must not bounce the clock back through the pre-seek position, and `isSeeking` must span the real landing. The run ends with a `#38 SEEK EVENT LEDGER`: every `.began` must reach a terminal event (an unpaired one is a stranded in-flight window), and `.stalled` seeks are listed with any late `.landed` that followed them. The ledger also prints **seek latency** (`.began` to its first terminal event, per seek, with min / median / max), which is what an A/B about the cost of work ON the seek path is read off: quote the median and the max, never a mean, because the tail belongs to the source rather than to the change under test. Note the burst is serialised, so every seek here terminates before the next is issued; to put a seek on top of an unsettled one use `play --seek-every 1 --seek-count N` against an origin below media rate, where `phase=seeking` holds across the run and the ledger shows supersedes. `--seeks N`, `--gap-ms N`, `--settle N` shape the burst; needs `> 30 s` of seekable VOD. `--throttle-kbps N` caps source-IO delivery to simulate a slow CDN and force rebuffers during the burst (see `serve`).
 
-The `#65` block of the results separates two parks that look alike in a log and mean opposite things (AE#528). A park whose `PARK` line reads `stuck=0s` is backpressure behind a consumer that is still declaring fetch targets, which is what a viewer scrubbing backwards through resident content looks like, and the wedge breaker staying quiet there is correct; the run says `PARKED BEHIND A LIVE CONSUMER (not a wedge)`. A wedge is a park whose `stuck=` climbs, and that one still breaks and re-anchors.
+The `#65` block of the results separates two parks that look alike in a log and mean opposite things (AE#528). A park whose `PARK` line reads `stuck=0s` is backpressure behind a consumer that is still declaring fetch targets, which is what a viewer scrubbing backwards through resident content looks like, and the wedge breaker staying quiet there is correct. `stuck=` counts the seconds since the consumer last declared a target and `idle=` only those in which it did not render either, and the breaker trips on `idle=` (AE#649): a park that reads `(consumer quiet, still playing)` with `stuck=` climbing and `idle=0s` is AVPlayer playing out a deep forward buffer between fetch bursts, which a cellular iPhone does for up to a minute at a time, and it does not break either. When every park of the run logged `idle=0s`, the run says `PARKED BEHIND A LIVE CONSUMER (not a wedge)`. A wedge is a park whose `idle=` climbs, and that one still breaks and re-anchors.
 
 ## hlslive
 

From 0973080465f784e898aa2b1705c8cc4af5d1e381 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sat, 26 Sep 2026 16:27:19 +0200
Subject: [PATCH 114/359] fix(disc): a DVD title declares its subpicture
 streams and probes briefly (AE#651)

mpegps sets AVFMTCTX_NOHEADER and never clears it, so find_stream_info
never takes its "all info found" exit and every DVD open read the full
playback budget (50 MB / 60 s). The window existed to discover streams
that start late, and it still missed any subtitle whose first packet
came after it.

The VTS IFO already declares the title's subpicture streams. They are
now created before the probe; mpegps routes packets to an existing
stream by id. libavformat attaches its dvdsub parser only to streams the
demuxer created (need_parsing is internal), so DVDSubpictureAssembler
joins the PES fragments in readPacketLocked under the parser's rule and
is reset at every flush. A title with a readable IFO then probes
8 MB / 5 s; a disc without one keeps the old budget.

Measured with aetherctl on an authored DVD over a 20 Mbit/s, 100 ms
origin: first frame at 6.5 s instead of 29.6 s, 0.5 s after a prewarm.
A subtitle first shown at 100 s is a track from the first frame and its
8 KB, multi-packet unit decodes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mf4MXgM9bqugHoe5TW4BYf
---
 CHANGELOG.md                                  |  12 ++
 Sources/AetherEngine/Demuxer/Demuxer.swift    | 110 +++++++++++-
 Sources/AetherEngine/Disc/DVDIFOParser.swift  |  28 +++
 .../Disc/DVDSubpictureAssembler.swift         |  69 +++++++
 Sources/AetherEngine/Disc/DiscMetadata.swift  |  10 +-
 Sources/AetherEngine/Disc/DiscReader.swift    |   5 +-
 .../Issue651DeclaredSubpictureTests.swift     | 168 ++++++++++++++++++
 docs/architecture.md                          |   3 +-
 docs/formats.md                               |   2 +
 9 files changed, 403 insertions(+), 4 deletions(-)
 create mode 100644 Sources/AetherEngine/Disc/DVDSubpictureAssembler.swift
 create mode 100644 Tests/AetherEngineTests/Issue651DeclaredSubpictureTests.swift

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d64f58483..33ec3d5d7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -21,6 +21,18 @@ the public-API contract.
   on to the streaming reader. Measured on an authored DVD over a 20 Mbit/s, 100 ms origin: 10
   requests after the warm instead of 19, first frame 5.7 s sooner.
 
+### Fixed
+
+- **A DVD title opens without reading 50 MB first, and lists every subtitle it has (#651).**
+  MPEG-PS never lets `find_stream_info` finish early, so every DVD open read the whole playback
+  probe budget (50 MB / 60 s) and still missed any subtitle stream whose first packet came later.
+  The subpicture streams the title's VTS IFO declares are now created before the probe, their
+  fragments are joined in the engine the way libavformat's `dvdsub` parser joins them for streams
+  it creates itself, and a title with a readable IFO probes 8 MB / 5 s. Measured on an authored
+  DVD over a 20 Mbit/s, 100 ms origin: first frame at 6.5 s instead of 29.6 s, 0.5 s after a
+  prewarm. A subtitle whose first packet sits at 100 s is a track from the first frame and
+  decodes. Discs without a readable VTS IFO, and plain `.mpg` / `.vob` URLs, keep the old budget.
+
 ## [7.17.1] - 2026-09-26
 
 ### Fixed
diff --git a/Sources/AetherEngine/Demuxer/Demuxer.swift b/Sources/AetherEngine/Demuxer/Demuxer.swift
index 2da691188..63c200dd2 100644
--- a/Sources/AetherEngine/Demuxer/Demuxer.swift
+++ b/Sources/AetherEngine/Demuxer/Demuxer.swift
@@ -348,6 +348,11 @@ public final class Demuxer: @unchecked Sendable {
     /// language inside the stream, so `trackInfo` backfills undetermined tracks from this; empty for every
     /// non-disc source, where it is a no-op (#527).
     private(set) var discStreamLanguages: [Int: String] = [:]
+    /// #651: the selected DVD title's declared subpicture substream ids, created before the probe.
+    private var discSubpictureStreamIDs: [Int]?
+    /// #651: one assembler per stream `declareDiscSubpictureStreams` created, keyed by stream index.
+    /// Those streams have no libavformat parser, so their fragments are joined here. Under `accessLock`.
+    private var subpictureAssemblers: [Int32: DVDSubpictureAssembler] = [:]
 
     /// Per-clip presentation-offset spans for a selected multi-clip Blu-ray title (empty otherwise). When
     /// non-empty, `readPacket` and `indexedKeyframes` fold each clip's timestamps onto one contiguous
@@ -377,6 +382,7 @@ public final class Demuxer: @unchecked Sendable {
         discTitles = info.titles
         selectedDiscTitleIndex = info.selectedTitleIndex
         discStreamLanguages = info.selectedTitle?.streamLanguages ?? [:]
+        discSubpictureStreamIDs = info.selectedTitle?.dvdSubpictureStreamIDs
         clipTimeline = info.clipTimeline
         lastClipIndex = 0
         lastReadClipIdx = -1
@@ -671,6 +677,7 @@ public final class Demuxer: @unchecked Sendable {
         }
         formatContext = ctxPtr  // avformat_open_input may reallocate
         onOpenProgress?(.containerOpened)   // #361
+        declareDiscSubpictureStreams(ctxPtr!)
 
         try probeStreams(ctxPtr!)
         accessLock.lock()
@@ -707,6 +714,56 @@ public final class Demuxer: @unchecked Sendable {
             opaque: Unmanaged.passUnretained(interrupt).toOpaque())
     }
 
+    /// #651: the probe budget of a DVD title whose IFO declared its streams.
+    ///
+    /// MPEG-PS sets `AVFMTCTX_NOHEADER` and never clears it, so `find_stream_info` never takes its
+    /// "all info found" exit and reads the whole budget on every open: 50 MB, most of a first frame on
+    /// a remote ISO. The long window only ever existed to discover streams that start late, and on a
+    /// DVD those are the subpictures, which the IFO has already declared. What is left to resolve is
+    /// the continuous streams (MPEG-2 video's rate, the audio's parameters), which a few seconds give.
+    static let declaredDiscTitleProbesize: Int64 = 8 * 1024 * 1024
+    static let declaredDiscTitleMaxAnalyzeDuration: Int64 = 5 * 1_000_000
+
+    /// #651: create the subpicture streams the selected DVD title's IFO declares, before anything is
+    /// read. `mpegps` looks a packet's stream up by `AVStream.id` before it creates one, so these
+    /// receive their packets exactly as if the demuxer had made them on the first one, and a subtitle
+    /// whose first packet is minutes in is a track from the first frame. Mirrors what `mpegps` sets
+    /// on a stream it creates, apart from `need_parsing`, which is internal: `dvdsubdec` reassembles
+    /// a subpicture split across packets itself.
+    private func declareDiscSubpictureStreams(_ ctx: UnsafeMutablePointer<AVFormatContext>) {
+        guard let ids = discSubpictureStreamIDs, !ids.isEmpty,
+              let name = ctx.pointee.iformat?.pointee.name, String(cString: name) == "mpeg" else { return }
+        var existing = Set<Int32>()
+        for i in 0..<Int(ctx.pointee.nb_streams) {
+            if let stream = ctx.pointee.streams[i] { existing.insert(stream.pointee.id) }
+        }
+        var declared = 0
+        for id in ids where !existing.contains(Int32(id)) {
+            guard let stream = avformat_new_stream(ctx, nil), let codecpar = stream.pointee.codecpar else { break }
+            stream.pointee.id = Int32(id)
+            subpictureAssemblers[stream.pointee.index] = DVDSubpictureAssembler()
+            stream.pointee.time_base = AVRational(num: 1, den: 90000)
+            stream.pointee.pts_wrap_bits = 64
+            codecpar.pointee.codec_type = AVMEDIA_TYPE_SUBTITLE
+            codecpar.pointee.codec_id = AV_CODEC_ID_DVD_SUBTITLE
+            declared += 1
+        }
+        if declared > 0 {
+            EngineLog.emit("[Demuxer] declared \(declared) DVD subpicture stream(s) from the IFO (#651)",
+                           category: .demux)
+        }
+    }
+
+    /// #651: shrink the probe to `declaredDiscTitle*` once the IFO has declared the title's streams.
+    /// Never raises a budget: a tighter caller budget (#68) still wins.
+    private func boundProbeForDeclaredDiscTitle(_ ctx: UnsafeMutablePointer<AVFormatContext>) {
+        guard discSubpictureStreamIDs != nil,
+              let name = ctx.pointee.iformat?.pointee.name, String(cString: name) == "mpeg" else { return }
+        ctx.pointee.probesize = min(ctx.pointee.probesize, Self.declaredDiscTitleProbesize)
+        ctx.pointee.max_analyze_duration = min(ctx.pointee.max_analyze_duration,
+                                               Self.declaredDiscTitleMaxAnalyzeDuration)
+    }
+
     /// Demuxer fflags applied to every avformat_open_input.
     /// +genpts: libavformat regenerates missing pts/dts; per AetherEngine#4 this is
     /// what Jellyfin's server-side remux uses. Cuts 4K HDR HEVC RSS growth ~50%
@@ -764,6 +821,7 @@ public final class Demuxer: @unchecked Sendable {
             return
         }
         reclassifyAttachedPictures(ctx)
+        boundProbeForDeclaredDiscTitle(ctx)
         let parked = parkUnresolvableAudio(ctx)
         let findRet = avformat_find_stream_info(ctx, nil)
         unparkUnresolvableAudio(ctx, parked)
@@ -1545,8 +1603,53 @@ public final class Demuxer: @unchecked Sendable {
         return entry.pointee.timestamp
     }
 
-    /// The read itself. Caller holds `accessLock`.
+    /// The read itself, with the fragments of a declared DVD subpicture stream joined (#651).
+    /// Caller holds `accessLock`.
     private func readPacketLocked() throws -> UnsafeMutablePointer<AVPacket>? {
+        while true {
+            guard let read = try readDemuxedPacketLocked() else { return nil }
+            var packet: UnsafeMutablePointer<AVPacket>? = read
+            let index = read.pointee.stream_index
+            guard var assembler = subpictureAssemblers[index] else { return read }
+            let timing = DVDSubpictureAssembler.Timing(
+                pts: read.pointee.pts, dts: read.pointee.dts,
+                pos: read.pointee.pos, duration: read.pointee.duration)
+            let unit = assembler.ingest(
+                UnsafeRawBufferPointer(start: read.pointee.data, count: Int(max(0, read.pointee.size))),
+                timing: timing)
+            subpictureAssemblers[index] = assembler
+            guard let unit else {
+                trackedPacketFree(&packet)
+                continue
+            }
+            // The first fragment's props, then the joined payload in place of its own.
+            guard let joined = trackedPacketAlloc() else { trackedPacketFree(&packet); return nil }
+            var out: UnsafeMutablePointer<AVPacket>? = joined
+            // `av_new_packet` resets every prop, so the copy comes after it.
+            guard av_new_packet(joined, Int32(unit.data.count)) >= 0,
+                  av_packet_copy_props(joined, read) >= 0 else {
+                trackedPacketFree(&out)
+                trackedPacketFree(&packet)
+                continue
+            }
+            unit.data.withUnsafeBytes { joined.pointee.data.update(from: $0.bindMemory(to: UInt8.self).baseAddress!, count: unit.data.count) }
+            joined.pointee.stream_index = index
+            joined.pointee.pts = unit.timing.pts
+            joined.pointee.dts = unit.timing.dts
+            joined.pointee.pos = unit.timing.pos
+            joined.pointee.duration = unit.timing.duration
+            trackedPacketFree(&packet)
+            return joined
+        }
+    }
+
+    /// #651: drop half-joined subpicture units along with libavformat's own parser state.
+    private func resetSubpictureAssembly() {
+        for key in subpictureAssemblers.keys { subpictureAssemblers[key]?.reset() }
+    }
+
+    /// One `av_read_frame`, as libavformat delivers it. Caller holds `accessLock`.
+    private func readDemuxedPacketLocked() throws -> UnsafeMutablePointer<AVPacket>? {
         guard let ctx = formatContext else { return nil }
         try probeControl?.willReadPacket()
         var packet: UnsafeMutablePointer<AVPacket>? = trackedPacketAlloc()
@@ -1663,6 +1766,7 @@ public final class Demuxer: @unchecked Sendable {
             #endif
         }
         avformat_flush(ctx)  // prevents assertion failures in matroskadec.c
+        resetSubpictureAssembly()  // #651: libavformat just dropped the parsers this stands in for
         lastReadClipIdx = -1  // AE#105: post-seek reads may land mid-clip; require a fresh clean crossing
         return ret >= 0
     }
@@ -1705,6 +1809,7 @@ public final class Demuxer: @unchecked Sendable {
             )
         }
         avformat_flush(ctx)
+        resetSubpictureAssembly()  // #651: libavformat just dropped the parsers this stands in for
         lastReadClipIdx = -1
         return ret >= 0
     }
@@ -1716,6 +1821,7 @@ public final class Demuxer: @unchecked Sendable {
             pb.pointee.error = 0
         }
         avformat_flush(ctx)
+        resetSubpictureAssembly()  // #651: libavformat just dropped the parsers this stands in for
         lastReadClipIdx = -1
     }
 
@@ -1830,6 +1936,7 @@ public final class Demuxer: @unchecked Sendable {
         }
         let ret = avformat_seek_file(ctx, anchor, Int64.min, timestamp, Int64.max, 0)
         avformat_flush(ctx)
+        resetSubpictureAssembly()  // #651: libavformat just dropped the parsers this stands in for
         lastReadClipIdx = -1  // AE#105: post-seek reads may land mid-clip; require a fresh clean crossing
         // matroska may return success with a partial index after abort; deadline flag
         // is authoritative, not ret.
@@ -2018,6 +2125,7 @@ public final class Demuxer: @unchecked Sendable {
         compositionRepair?.noteSeek()  // #409: re-anchor on the next keyframe
         let ret = avformat_seek_file(ctx, -1, Int64.min, byteTarget, Int64.max, AVSEEK_FLAG_BYTE)
         avformat_flush(ctx)
+        resetSubpictureAssembly()  // #651: libavformat just dropped the parsers this stands in for
         lastReadClipIdx = -1  // AE#105: post-seek reads may land mid-clip; require a fresh clean crossing
         return ret >= 0
     }
diff --git a/Sources/AetherEngine/Disc/DVDIFOParser.swift b/Sources/AetherEngine/Disc/DVDIFOParser.swift
index f64d4d44b..a8c5c7134 100644
--- a/Sources/AetherEngine/Disc/DVDIFOParser.swift
+++ b/Sources/AetherEngine/Disc/DVDIFOParser.swift
@@ -216,6 +216,34 @@ enum DVDIFOParser {
         return languages
     }
 
+    /// Every subpicture substream id the title's IFO declares, with or without a language, ascending.
+    ///
+    /// The same control-table reading as `parseStreamLanguages`: an entry the main PGC marks
+    /// unavailable is not in the VOBs, and each display-mode number an entry names is its own
+    /// MPEG-PS substream. Without a readable PGC the attribute position is the number (#651). nil when
+    /// the bytes are no VTS IFO, which is not the same answer as a title with no subpictures.
+    static func parseSubpictureStreamIDs(_ data: [UInt8]) -> [Int]? {
+        guard data.count >= 12, Array(data[0..<12]) == vtsMagic,
+              data.count > vtsSubpictureCountOffset else { return nil }
+        let pgc = mainPGCOffset(data)
+        let count = min(Int(data[vtsSubpictureCountOffset]), vtsMaxSubpictureStreams)
+        var ids = Set<Int>()
+        for n in 0..<count {
+            guard let pgc, pgc + pgcSubpictureControlOffset + n * 4 + 4 <= data.count else {
+                ids.insert(subpictureSubstreamBase + n)
+                continue
+            }
+            let control = be32(data, pgc + pgcSubpictureControlOffset + n * 4)
+            guard control & 0x8000_0000 != 0 else { continue }
+            ids.insert(subpictureSubstreamBase + ((control >> 24) & 0x1F))
+            for shift in [16, 8, 0] {
+                let number = (control >> shift) & 0x1F
+                if number != 0 { ids.insert(subpictureSubstreamBase + number) }
+            }
+        }
+        return ids.sorted()
+    }
+
     /// Base substream id for a DVD audio coding mode; a stream's id is this plus its substream number.
     /// AC-3, DTS and LPCM ride in private_stream_1, where FFmpeg reports the substream byte; MPEG audio
     /// has its own PES stream id, where FFmpeg reports the full start code. nil for the reserved coding
diff --git a/Sources/AetherEngine/Disc/DVDSubpictureAssembler.swift b/Sources/AetherEngine/Disc/DVDSubpictureAssembler.swift
new file mode 100644
index 000000000..6175d3285
--- /dev/null
+++ b/Sources/AetherEngine/Disc/DVDSubpictureAssembler.swift
@@ -0,0 +1,69 @@
+import Foundation
+
+/// #651: joins the PES fragments of one DVD subpicture unit back into the packet `dvdsubdec` expects.
+///
+/// `mpegps` hands a subpicture stream it created itself to libavformat's `dvdsub` parser, which does
+/// this join. A stream the engine declares from the IFO before the probe cannot ask for that parser
+/// (`need_parsing` is internal to libavformat), and a unit larger than one 2 KB pack then reaches the
+/// decoder as its first fragment alone, which does not decode. This is the same rule as
+/// `libavcodec/dvdsub_parser.c`: the unit's size is its first 16 bits (or the 32 bits after a zero
+/// there), fragments append until that size is reached, the unit carries the first fragment's
+/// timing, and a fragment that would overrun the size drops the unit.
+struct DVDSubpictureAssembler {
+
+    /// Timing of the fragment that opened the unit, which the joined packet carries.
+    struct Timing: Equatable {
+        let pts: Int64
+        let dts: Int64
+        let pos: Int64
+        let duration: Int64
+    }
+
+    struct Unit: Equatable {
+        let data: [UInt8]
+        let timing: Timing
+    }
+
+    private var buffer: [UInt8] = []
+    private var expected = 0
+    private var timing: Timing?
+
+    var isAssembling: Bool { timing != nil }
+
+    /// Feed one demuxed fragment. Returns the unit once it is complete, nil while it is not (or when
+    /// the fragment was dropped).
+    mutating func ingest(_ fragment: UnsafeRawBufferPointer, timing fragmentTiming: Timing) -> Unit? {
+        if timing == nil {
+            let bytes = fragment.bindMemory(to: UInt8.self)
+            guard bytes.count >= 2 else { return nil }
+            var size = Int(bytes[0]) << 8 | Int(bytes[1])
+            if size == 0 {
+                guard bytes.count >= 6 else { return nil }
+                size = Int(bytes[2]) << 24 | Int(bytes[3]) << 16 | Int(bytes[4]) << 8 | Int(bytes[5])
+            } else if bytes.count < 6 {
+                return nil
+            }
+            guard size > 0 else { return nil }
+            expected = size
+            timing = fragmentTiming
+            buffer.removeAll(keepingCapacity: true)
+            buffer.reserveCapacity(size)
+        }
+        guard buffer.count + fragment.count <= expected, let unitTiming = timing else {
+            reset()
+            return nil
+        }
+        buffer.append(contentsOf: fragment.bindMemory(to: UInt8.self))
+        guard buffer.count >= expected else { return nil }
+        let unit = Unit(data: buffer, timing: unitTiming)
+        reset()
+        return unit
+    }
+
+    /// Drop a half-joined unit, for a seek: the next fragment read is from somewhere else.
+    mutating func reset() {
+        buffer.removeAll(keepingCapacity: true)
+        expected = 0
+        timing = nil
+    }
+}
diff --git a/Sources/AetherEngine/Disc/DiscMetadata.swift b/Sources/AetherEngine/Disc/DiscMetadata.swift
index bc82a633b..96cc4957d 100644
--- a/Sources/AetherEngine/Disc/DiscMetadata.swift
+++ b/Sources/AetherEngine/Disc/DiscMetadata.swift
@@ -72,12 +72,19 @@ struct DiscTitle: Sendable, Equatable {
     /// every track as undetermined without this; `Demuxer.trackInfo` backfills from it. Empty when the
     /// disc declares none (#527).
     let streamLanguages: [Int: String]
+    /// DVD: every subpicture substream id (`0x20` + number) the VTS IFO declares for this title,
+    /// language or not, ascending. `Demuxer` creates these streams before the probe, so a subtitle
+    /// whose first packet comes late is a track from the start rather than whenever the probe
+    /// happens to reach it (#651). Empty when the IFO declares none, nil when it is unreadable: only a
+    /// title whose IFO was read gets the short probe, since only then is nothing left to discover.
+    let dvdSubpictureStreamIDs: [Int]?
 
     init(id: Int, durationTicks: UInt64, chapters: [DiscChapter] = [],
          bdClipIDs: [String]? = nil, bdClipSubtractTicks: [Int64]? = nil,
          bdClipCumulativeBeforeTicks: [UInt64]? = nil,
          dvdVTSN: Int? = nil, dvdTitleNumber: Int? = nil,
-         streamLanguages: [Int: String] = [:]) {
+         streamLanguages: [Int: String] = [:],
+         dvdSubpictureStreamIDs: [Int]? = nil) {
         self.id = id
         self.durationTicks = durationTicks
         self.chapters = chapters
@@ -87,6 +94,7 @@ struct DiscTitle: Sendable, Equatable {
         self.dvdVTSN = dvdVTSN
         self.dvdTitleNumber = dvdTitleNumber
         self.streamLanguages = streamLanguages
+        self.dvdSubpictureStreamIDs = dvdSubpictureStreamIDs
     }
 }
 
diff --git a/Sources/AetherEngine/Disc/DiscReader.swift b/Sources/AetherEngine/Disc/DiscReader.swift
index 8cfc23fca..52ec41dbd 100644
--- a/Sources/AetherEngine/Disc/DiscReader.swift
+++ b/Sources/AetherEngine/Disc/DiscReader.swift
@@ -195,6 +195,7 @@ enum DiscReader {
             var chapters: [DiscChapter] = []
             // The VOBs carry no track language, so the IFO's attribute tables are the only source (#527).
             var streamLanguages: [Int: String] = [:]
+            var subpictureStreamIDs: [Int]?
             let nn = g.vtsn < 10 ? "0\(g.vtsn)" : "\(g.vtsn)"
             let ifoName = "VTS_\(nn)_0.IFO"
             if let vtsIFO = files.first(where: { $0.name.uppercased() == ifoName }) {
@@ -207,9 +208,11 @@ enum DiscReader {
                     }
                 }
                 streamLanguages = DVDIFOParser.parseStreamLanguages(bytes)
+                subpictureStreamIDs = DVDIFOParser.parseSubpictureStreamIDs(bytes)
             }
             return DiscTitle(id: idx, durationTicks: durationTicks, chapters: chapters, dvdVTSN: g.vtsn,
-                             streamLanguages: streamLanguages)
+                             streamLanguages: streamLanguages,
+                             dvdSubpictureStreamIDs: subpictureStreamIDs)
         }
         storeRecognition(cacheKey: cacheKey, selectTitleID: selectTitleID,
                          formatHint: "mpeg", titles: titles, selectedIndex: selectedIndex, extents: extents)
diff --git a/Tests/AetherEngineTests/Issue651DeclaredSubpictureTests.swift b/Tests/AetherEngineTests/Issue651DeclaredSubpictureTests.swift
new file mode 100644
index 000000000..d91a6c399
--- /dev/null
+++ b/Tests/AetherEngineTests/Issue651DeclaredSubpictureTests.swift
@@ -0,0 +1,168 @@
+import Testing
+import Foundation
+import AetherLibavcodec
+@testable import AetherEngine
+
+/// #651: a DVD title whose IFO declares its subpicture streams opens them before the probe, joins
+/// their fragments the way libavformat's `dvdsub` parser would, and needs no long probe to find them.
+@Suite("DVD subpicture streams declared from the IFO (#651)")
+struct Issue651DeclaredSubpictureTests {
+
+    // MARK: - Assembler
+
+    private func timing(_ pts: Int64) -> DVDSubpictureAssembler.Timing {
+        .init(pts: pts, dts: pts, pos: 0, duration: 0)
+    }
+
+    private func ingest(_ a: inout DVDSubpictureAssembler, _ bytes: [UInt8], _ pts: Int64) -> DVDSubpictureAssembler.Unit? {
+        bytes.withUnsafeBytes { a.ingest($0, timing: timing(pts)) }
+    }
+
+    /// A unit of `size` bytes whose first two bytes state that size.
+    private func unit(_ size: Int) -> [UInt8] {
+        [UInt8(size >> 8), UInt8(size & 0xff)] + (2..<size).map { UInt8(truncatingIfNeeded: $0 &* 7) }
+    }
+
+    @Test("a unit in one fragment passes through")
+    func singleFragment() {
+        var a = DVDSubpictureAssembler()
+        let bytes = unit(100)
+        #expect(ingest(&a, bytes, 900) == .init(data: bytes, timing: timing(900)))
+        #expect(!a.isAssembling)
+    }
+
+    @Test("fragments join into one unit carrying the first fragment's timing")
+    func joinsFragments() {
+        var a = DVDSubpictureAssembler()
+        let bytes = unit(5000)
+        #expect(ingest(&a, Array(bytes[0..<2000]), 900) == nil)
+        #expect(ingest(&a, Array(bytes[2000..<4000]), Int64.min) == nil)
+        #expect(ingest(&a, Array(bytes[4000...]), Int64.min) == .init(data: bytes, timing: timing(900)))
+    }
+
+    @Test("a zero 16-bit size reads the 32-bit size behind it")
+    func thirtyTwoBitSize() {
+        var a = DVDSubpictureAssembler()
+        let size = 70_000
+        var bytes: [UInt8] = [0, 0, 0, 1, 0x11, 0x70]
+        bytes += [UInt8](repeating: 0xAB, count: size - bytes.count)
+        #expect(ingest(&a, Array(bytes[0..<40_000]), 1) == nil)
+        #expect(ingest(&a, Array(bytes[40_000...]), Int64.min)?.data.count == size)
+    }
+
+    @Test("a fragment that overruns the stated size drops the unit")
+    func overrunDrops() {
+        var a = DVDSubpictureAssembler()
+        let bytes = unit(3000)
+        #expect(ingest(&a, Array(bytes[0..<2000]), 1) == nil)
+        #expect(ingest(&a, [UInt8](repeating: 0, count: 2000), Int64.min) == nil)
+        #expect(!a.isAssembling)
+        // The next unit starts clean.
+        #expect(ingest(&a, unit(50), 2)?.timing.pts == 2)
+    }
+
+    @Test("a reset drops a half-joined unit")
+    func resetDrops() {
+        var a = DVDSubpictureAssembler()
+        #expect(ingest(&a, Array(unit(3000)[0..<2000]), 1) == nil)
+        a.reset()
+        #expect(ingest(&a, unit(40), 7)?.timing.pts == 7)
+    }
+
+    @Test("a first fragment too short to state a size is dropped")
+    func shortHeaderDrops() {
+        var a = DVDSubpictureAssembler()
+        #expect(ingest(&a, [0x00], 1) == nil)
+        #expect(ingest(&a, [0x00, 0x40, 1], 1) == nil)
+        #expect(!a.isAssembling)
+    }
+
+    // MARK: - IFO
+
+    /// A VTS IFO without a PGCIT declaring `count` subpictures, the first `withLanguage` of them with
+    /// a language.
+    private func vtsIFO(subpictures count: Int, withLanguage: Int) -> [UInt8] {
+        var ifo = [UInt8](repeating: 0, count: ISO9660Fixture.sectorSize)
+        ifo.replaceSubrange(0..<12, with: Array("DVDVIDEO-VTS".utf8))
+        ifo[0x255] = UInt8(count)
+        for n in 0..<withLanguage {
+            let s = 0x256 + n * 6
+            ifo[s] = 0x01
+            ifo[s + 2] = UInt8(ascii: "e")
+            ifo[s + 3] = UInt8(ascii: "n")
+        }
+        return ifo
+    }
+
+    @Test("every declared subpicture is a stream id, with a language or without")
+    func parsesDeclaredIDs() {
+        #expect(DVDIFOParser.parseSubpictureStreamIDs(vtsIFO(subpictures: 3, withLanguage: 1)) == [0x20, 0x21, 0x22])
+        #expect(DVDIFOParser.parseSubpictureStreamIDs(vtsIFO(subpictures: 0, withLanguage: 0)) == [])
+        #expect(DVDIFOParser.parseSubpictureStreamIDs([UInt8](repeating: 0, count: 2048)) == nil)
+    }
+
+    @Test("a title without a VTS IFO declares nothing, which is not the same as declaring no streams")
+    func unreadableIFOIsNil() throws {
+        let image = ISO9660Fixture.make(files: [.init(name: "VTS_01_1.VOB", length: 2048)])
+        let info = try #require(try DiscReader.wrap(DataIOReader(data: image)))
+        #expect(try #require(info.selectedTitle).dvdSubpictureStreamIDs == nil)
+    }
+
+    // MARK: - Through the demuxer
+
+    private func be16(_ v: Int) -> [UInt8] { [UInt8((v >> 8) & 0xff), UInt8(v & 0xff)] }
+
+    private let packHeader: [UInt8] = [0, 0, 1, 0xBA, 0x44, 0x00, 0x04, 0x00, 0x04, 0x01, 0x01, 0x89, 0xC3, 0xF8]
+
+    private func ptsBytes(_ pts: Int64) -> [UInt8] {
+        [UInt8(0x21 | ((pts >> 29) & 0x0E)), UInt8((pts >> 22) & 0xFF),
+         UInt8(((pts >> 14) & 0xFE) | 1), UInt8((pts >> 7) & 0xFF), UInt8(((pts << 1) & 0xFE) | 1)]
+    }
+
+    /// One pack holding one private_stream_1 PES for subpicture substream `substream`.
+    private func subpicturePack(substream: UInt8, payload: [UInt8], pts: Int64?) -> [UInt8] {
+        let header: [UInt8] = pts.map { [0x81, 0x80, 5] + ptsBytes($0) } ?? [0x81, 0x00, 0]
+        let body = header + [substream] + payload
+        return packHeader + [0, 0, 1, 0xBD] + be16(body.count) + body
+    }
+
+    @Test("a declared stream is a track before its first packet, and its fragments arrive joined")
+    func demuxerDeclaresAndJoins() throws {
+        // One sector in all: the fixture writes a single sector per file.
+        let spu = unit(1200)
+        var vob: [UInt8] = []
+        vob += subpicturePack(substream: 0x20, payload: Array(spu[0..<400]), pts: 90_000)
+        vob += subpicturePack(substream: 0x20, payload: Array(spu[400..<800]), pts: nil)
+        vob += subpicturePack(substream: 0x20, payload: Array(spu[800...]), pts: nil)
+        vob += [0, 0, 1, 0xB9]
+        vob += [UInt8](repeating: 0, count: ISO9660Fixture.sectorSize - vob.count)
+
+        let image = ISO9660Fixture.make(files: [
+            .init(name: "VIDEO_TS.IFO", length: 2048),
+            .init(name: "VTS_01_0.IFO", length: ISO9660Fixture.sectorSize,
+                  content: vtsIFO(subpictures: 2, withLanguage: 2)),
+            .init(name: "VTS_01_1.VOB", length: vob.count, content: vob),
+        ])
+        let demuxer = Demuxer()
+        defer { demuxer.close() }
+        try demuxer.open(reader: DataIOReader(data: image), formatHint: nil)
+
+        // 0x21 never carries a packet in this title, and is a track anyway.
+        let ids = (0..<32).compactMap { demuxer.stream(at: Int32($0))?.pointee.id }
+        #expect(ids.contains(0x20) && ids.contains(0x21), "stream ids: \(ids)")
+
+        var joined: [(data: [UInt8], pts: Int64)] = []
+        while let packet = try demuxer.readPacket() {
+            var p: UnsafeMutablePointer<AVPacket>? = packet
+            if demuxer.stream(at: packet.pointee.stream_index)?.pointee.id == 0x20 {
+                joined.append((Array(UnsafeBufferPointer(start: packet.pointee.data,
+                                                         count: Int(packet.pointee.size))),
+                               packet.pointee.pts))
+            }
+            trackedPacketFree(&p)
+        }
+        #expect(joined.count == 1)
+        #expect(joined.first?.data == spu)
+        #expect(joined.first?.pts == 90_000)
+    }
+}
diff --git a/docs/architecture.md b/docs/architecture.md
index d25519369..3acb9764c 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -384,7 +384,8 @@ Sources/AetherEngine/
 │   ├── DiscReader.swift                     Disc detection + routing: local `.iso` URLs and custom ISO readers into the demux path; enumerates titles and threads the selected one (DVD vs Blu-ray)
 │   ├── DiscMetadata.swift                   Public `TitleInfo` / `ChapterInfo` plus the internal disc title + chapter model (45 kHz ticks, extent keys)
 │   ├── ISO9660Reader.swift                  Read-only ISO9660 bridge-filesystem reader (DVD-Video images)
-│   ├── DVDIFOParser.swift                   DVD VMGI TT_SRPT title list + each VTS IFO program chain (per-title duration + chapters) and stream attribute tables (track languages)
+│   ├── DVDIFOParser.swift                   DVD VMGI TT_SRPT title list + each VTS IFO program chain (per-title duration + chapters) and stream attribute tables (track languages, declared subpicture streams)
+│   ├── DVDSubpictureAssembler.swift         Joins a DVD subpicture's PES fragments for the streams the engine declares from the IFO (the `dvdsub` parser's job, which libavformat only does for streams it created)
 │   ├── DVDTitleSelector.swift               Groups DVD title sets' content VOBs into selectable titles (whole-VTS, largest first)
 │   ├── ConcatIOReader.swift                 Synthetic seekable IOReader concatenating byte extents (DVD VOBs / Blu-ray M2TS clips) into one source
 │   ├── UDFReader.swift                      Read-only UDF 2.50 reader (Blu-ray BDMV, including the metadata partition and fragmented-file allocation descriptors)
diff --git a/docs/formats.md b/docs/formats.md
index 3f4861a80..031cef8c8 100644
--- a/docs/formats.md
+++ b/docs/formats.md
@@ -471,6 +471,8 @@ Both: no decryption (CSS / AACS retail discs must be ripped decrypted first), no
 
 **Track languages.** Neither disc format carries a track language in the stream, so a title demuxed on its own reports every audio and subtitle track as undetermined and `preferredAudioLanguages` / `preferredSubtitleLanguages` have nothing to match on. The languages are read out of the disc's own navigation data instead and backfilled onto the tracks by stream id: on Blu-ray from every PlayItem's STN table (the ISO 639-2 codes beside each stream's PID, first declaration winning), on DVD from the VTS IFO audio and subpicture attribute tables, with the title's main program chain naming the substream each attribute is actually carried as (a stream the chain marks absent is dropped, and without a readable chain the attribute's position is used, which is how the great majority of discs are authored). Only an undetermined track is filled in: a language the container really declares stays authoritative. `aetherctl disc-inspect` prints what a disc declares per title, so a disc whose tracks stay undetermined can be told apart from a disc that declares nothing (#527).
 
+**Subpicture streams and the probe.** An MPEG-PS demuxer can meet a new stream at any packet, so libavformat never lets `find_stream_info` stop early on a DVD. With the playback budget that meant 50 MB read on every open, and a subtitle whose first packet comes after it was not a track at all. For a title whose VTS IFO is readable, the engine creates every subpicture stream the IFO declares before the probe. `mpegps` routes packets to an existing stream by id, and the engine joins each subpicture's PES fragments itself, because libavformat's `dvdsub` parser only attaches to streams the demuxer created. Such a title then probes 8 MB / 5 s (#651). Stream indices on such a title start with those subpicture streams. A disc without a readable VTS IFO keeps the full budget.
+
 **Container chapters.** `engine.mediaChapters` (`@Published [ChapterInfo]`) carries the chapters a Matroska or MP4 container declares, read off the probe demuxer at load. It is empty for disc sources, which publish `discChapters` instead, so exactly one of the two is populated. Unlike disc chapters these need no base: a non-disc source plays on the container's own PTS axis on both backends, so `startSeconds` is a timestamp a host hands straight to `seek(to:)`. `selectChapter(id:)` resolves against `discChapters` only and no-ops for a container chapter id. Ids are assigned sequentially in start order, so they stay usable as list indices, and untitled entries are numbered "Chapter N". A chapter's duration runs to the next chapter's start rather than to its declared end, because muxers routinely write `end == start`; the last entry falls back to its declared end, then to the container duration.
 
 ## Custom byte sources (`IOReader`)

From da2b45046567a89a98fd6f6b8056cd87f3a84d4f Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sat, 26 Sep 2026 16:53:05 +0200
Subject: [PATCH 115/359] chore(release): prep 7.18.0 - remote disc images
 adopt a prewarm, DVD titles open without the 50 MB probe

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mf4MXgM9bqugHoe5TW4BYf
---
 CHANGELOG.md                                    | 4 ++++
 Examples/README.md                              | 2 +-
 README.md                                       | 6 +++---
 Sources/AetherEngine/AetherEngine+Version.swift | 2 +-
 4 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 33ec3d5d7..b0afd4e53 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,10 @@ the public-API contract.
 
 ## [Unreleased]
 
+_Nothing yet._
+
+## [7.18.0] - 2026-09-26
+
 ### Changed
 
 - **A remote disc image adopts a warm (#647).** `AetherEngine.prewarm` on an `.iso` / `.img` /
diff --git a/Examples/README.md b/Examples/README.md
index 409ae3cdd..9d2eef1db 100644
--- a/Examples/README.md
+++ b/Examples/README.md
@@ -18,7 +18,7 @@ Three samples covering different audiences:
    ```
    https://github.com/superuser404notfound/AetherEngine
    ```
-   Dependency Rule: Up to Next Major Version, starting from `7.17.1`. Add the `AetherEngine` library product to your app target.
+   Dependency Rule: Up to Next Major Version, starting from `7.18.0`. Add the `AetherEngine` library product to your app target.
 
 3. **Drop the file in.** Replace the Xcode template's default `App.swift` (or whatever the generated `@main` file is called) with the contents of [`MinimalPlayerApp.swift`](MinimalPlayer/MinimalPlayerApp.swift). The file is self-contained: it defines both the `@main App` struct and the `ContentView`.
 
diff --git a/README.md b/README.md
index d3c03e854..a47121533 100644
--- a/README.md
+++ b/README.md
@@ -384,7 +384,7 @@ Subtitle cues land in raw source PTS; render the overlay against `player.sourceT
 Install via Swift Package Manager:
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.17.1")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.18.0")
 ```
 
 Three samples ship in `Examples/`:
@@ -631,10 +631,10 @@ Browse all of this as a searchable site at **[aetherengine.superuser404.de](http
 AetherEngine uses [Semantic Versioning](https://semver.org). The public API surface, every `public` declaration in `Sources/AetherEngine/`, is the stability contract. **Major** removes / renames public symbols or breaks adopters; **Minor** adds public API or codec / format support; **Patch** fixes bugs with no public API change. `internal` types are not part of the contract.
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.17.1")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.18.0")
 ```
 
-Pin to `.upToNextMinor(from: "7.17.1")` for stricter teams that prefer to opt into minor bumps explicitly.
+Pin to `.upToNextMinor(from: "7.18.0")` for stricter teams that prefer to opt into minor bumps explicitly.
 
 ## Requirements
 
diff --git a/Sources/AetherEngine/AetherEngine+Version.swift b/Sources/AetherEngine/AetherEngine+Version.swift
index 3f8065bfc..675164a0f 100644
--- a/Sources/AetherEngine/AetherEngine+Version.swift
+++ b/Sources/AetherEngine/AetherEngine+Version.swift
@@ -11,5 +11,5 @@ extension AetherEngine {
     ///
     /// Between releases, and in a consumer that pins an unreleased commit for a device test, this
     /// names the last PUBLISHED version the checkout descends from, not every patch in it.
-    public nonisolated static let version = "7.17.1"
+    public nonisolated static let version = "7.18.0"
 }

From 9a8487035539c9b8df72839b81ed797da8aa28e7 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sat, 26 Sep 2026 17:47:16 +0200
Subject: [PATCH 116/359] docs(changelog): AE#649 entry reflowed, quiet spans
 from the retest

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mf4MXgM9bqugHoe5TW4BYf
---
 CHANGELOG.md | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0c09842e4..d7a247959 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -13,14 +13,14 @@ the public-API contract.
 ### Fixed
 
 - **A VOD consumer that goes quiet while it keeps playing no longer trips the #65 wedge breaker.**
-  AVPlayer on a cellular iPhone fetches in bursts, several segments at once and then nothing for 24
-  to 58 s while it plays out a forward buffer of up to 109 s. The slow path counted that silence alone, broke the
-  park every few minutes and nudge-seeked a healthy session, which flushed the buffer on screen: a
-  half-second freeze of picture and sound each time, and a re-anchor that fetched the source it
-  already held a second time. The slow path now counts only seconds in which the consumer neither
-  fetched nor rendered; one that really stopped fetching still breaks on the fast path once its
-  buffer runs dry. The `PARK` line carries the new count as `idle=` and names a quiet but playing
-  consumer as such (AE#649).
+  AVPlayer on a cellular iPhone fetches in bursts, several segments at once and then nothing for
+  half a minute to almost two while it plays out a forward buffer of up to 113 s. The slow path
+  counted that silence alone, broke the park every few minutes and nudge-seeked a healthy session,
+  which flushed the buffer on screen: a half-second freeze of picture and sound each time, and a
+  re-anchor that fetched the source it already held a second time. The slow path now counts only
+  seconds in which the consumer neither fetched nor rendered; one that really stopped fetching
+  still breaks on the fast path once its buffer runs dry. The `PARK` line carries the new count as
+  `idle=` and names a quiet but playing consumer as such (AE#649, thanks @tschuegy).
 
 ## [7.18.0] - 2026-09-26
 

From a13d801c17714a3ade33932e955f8b426cb37dd5 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sat, 26 Sep 2026 17:54:48 +0200
Subject: [PATCH 117/359] chore(release): prep 7.18.1 - a quiet consumer that
 is still playing is not a backpressure wedge

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mf4MXgM9bqugHoe5TW4BYf
---
 CHANGELOG.md                                    | 4 ++++
 Examples/README.md                              | 2 +-
 README.md                                       | 6 +++---
 Sources/AetherEngine/AetherEngine+Version.swift | 2 +-
 4 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d7a247959..9154fac13 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,10 @@ the public-API contract.
 
 ## [Unreleased]
 
+_Nothing yet._
+
+## [7.18.1] - 2026-09-26
+
 ### Fixed
 
 - **A VOD consumer that goes quiet while it keeps playing no longer trips the #65 wedge breaker.**
diff --git a/Examples/README.md b/Examples/README.md
index 9d2eef1db..7ab29d93b 100644
--- a/Examples/README.md
+++ b/Examples/README.md
@@ -18,7 +18,7 @@ Three samples covering different audiences:
    ```
    https://github.com/superuser404notfound/AetherEngine
    ```
-   Dependency Rule: Up to Next Major Version, starting from `7.18.0`. Add the `AetherEngine` library product to your app target.
+   Dependency Rule: Up to Next Major Version, starting from `7.18.1`. Add the `AetherEngine` library product to your app target.
 
 3. **Drop the file in.** Replace the Xcode template's default `App.swift` (or whatever the generated `@main` file is called) with the contents of [`MinimalPlayerApp.swift`](MinimalPlayer/MinimalPlayerApp.swift). The file is self-contained: it defines both the `@main App` struct and the `ContentView`.
 
diff --git a/README.md b/README.md
index a47121533..33de98473 100644
--- a/README.md
+++ b/README.md
@@ -384,7 +384,7 @@ Subtitle cues land in raw source PTS; render the overlay against `player.sourceT
 Install via Swift Package Manager:
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.18.0")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.18.1")
 ```
 
 Three samples ship in `Examples/`:
@@ -631,10 +631,10 @@ Browse all of this as a searchable site at **[aetherengine.superuser404.de](http
 AetherEngine uses [Semantic Versioning](https://semver.org). The public API surface, every `public` declaration in `Sources/AetherEngine/`, is the stability contract. **Major** removes / renames public symbols or breaks adopters; **Minor** adds public API or codec / format support; **Patch** fixes bugs with no public API change. `internal` types are not part of the contract.
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.18.0")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.18.1")
 ```
 
-Pin to `.upToNextMinor(from: "7.18.0")` for stricter teams that prefer to opt into minor bumps explicitly.
+Pin to `.upToNextMinor(from: "7.18.1")` for stricter teams that prefer to opt into minor bumps explicitly.
 
 ## Requirements
 
diff --git a/Sources/AetherEngine/AetherEngine+Version.swift b/Sources/AetherEngine/AetherEngine+Version.swift
index 675164a0f..1a486c031 100644
--- a/Sources/AetherEngine/AetherEngine+Version.swift
+++ b/Sources/AetherEngine/AetherEngine+Version.swift
@@ -11,5 +11,5 @@ extension AetherEngine {
     ///
     /// Between releases, and in a consumer that pins an unreleased commit for a device test, this
     /// names the last PUBLISHED version the checkout descends from, not every patch in it.
-    public nonisolated static let version = "7.18.0"
+    public nonisolated static let version = "7.18.1"
 }

From 278bdda41a2fec34155b09b7345558271dec9a10 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sat, 26 Sep 2026 19:27:39 +0200
Subject: [PATCH 118/359] fix(native): an escalation reports the position its
 rebuild resumes at (AE#629)

Under a mount raised by a host load(), AVPlayer's clock reads the start of
the segment it decodes up from until the mount seek lands. A refusal in
that window put that reading on the #561 line and the event, while the
rebuild resumed at the parked position: 12.00 s against 15.90 s on the
reporter's Apple TV. Both now read positionForSessionRebuild.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mf4MXgM9bqugHoe5TW4BYf
---
 CHANGELOG.md                                             | 9 ++++++++-
 .../AetherEngine+SoftwarePathEscalation.swift            | 9 +++++++--
 Sources/AetherEngine/Native/SoftwarePathEscalation.swift | 3 ++-
 .../AetherEngineTests/SoftwarePathEscalationTests.swift  | 9 +++++++--
 4 files changed, 24 insertions(+), 6 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9154fac13..73ba7cd60 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,7 +10,14 @@ the public-API contract.
 
 ## [Unreleased]
 
-_Nothing yet._
+### Fixed
+
+- **A software-path escalation reports the position its rebuild resumes at (AE#629).** Under a
+  mount raised by a host `load()`, AVPlayer's clock reads the start of the segment it decodes up
+  from until the mount seek lands, and a refusal in that window put that reading on the `#561` line
+  and on `SoftwarePathEscalationEvent.positionSeconds`, while the rebuild itself resumed at the
+  position the load was handed: 12.00 s against 15.90 s on the reporter's Apple TV. Both now carry
+  the rebuild's position.
 
 ## [7.18.1] - 2026-09-26
 
diff --git a/Sources/AetherEngine/AetherEngine+SoftwarePathEscalation.swift b/Sources/AetherEngine/AetherEngine+SoftwarePathEscalation.swift
index f942ef406..61c8ddad7 100644
--- a/Sources/AetherEngine/AetherEngine+SoftwarePathEscalation.swift
+++ b/Sources/AetherEngine/AetherEngine+SoftwarePathEscalation.swift
@@ -34,20 +34,25 @@ extension AetherEngine {
 
         let absorbed = Self.absorbedFailure(request)
         let duringStartup = waitingLoadGenerations.contains(loadGeneration)
+        // AE#629 round 3: the position the rebuild resumes at, not the host's reading at the refusal.
+        // Under a mount a load() of the host's own raised, AVPlayer's clock reads the start of the
+        // segment it decodes up from until the mount seek lands (12.00 s under 15.90 s on the
+        // reporter's box), so the event and the rebuild disagreed by that gap.
+        let resumesAt = positionForSessionRebuild
 
         let verdict = request.domain == SoftwarePathEscalation.liveJoinErrorDomain
             ? "the native route cannot open this live bitstream"
             : "AVPlayer refused the media (\(request.domain)/\(request.code))"
         EngineLog.emit(
             "[AetherEngine] #561 \(verdict) at "
-            + "\(String(format: "%.2f", request.positionSeconds))s; rebuilding this session on the "
+            + "\(String(format: "%.2f", resumesAt))s; rebuilding this session on the "
             + "software path, which decodes it with libavcodec instead"
             + (duringStartup ? " (the waiting load follows it)" : "") + ": \(request.message)",
             category: .engine
         )
         softwarePathEscalations.send(SoftwarePathEscalationEvent(
             absorbedFailure: absorbed,
-            positionSeconds: request.positionSeconds,
+            positionSeconds: resumesAt,
             duringStartup: duringStartup))
 
         let rebuild = startTakeoverRebuild { $0.preferredDecodePath = .software }
diff --git a/Sources/AetherEngine/Native/SoftwarePathEscalation.swift b/Sources/AetherEngine/Native/SoftwarePathEscalation.swift
index 84a96b711..a3bae67c5 100644
--- a/Sources/AetherEngine/Native/SoftwarePathEscalation.swift
+++ b/Sources/AetherEngine/Native/SoftwarePathEscalation.swift
@@ -12,7 +12,8 @@ public struct SoftwarePathEscalationEvent: Sendable, Equatable {
     /// The failure the rebuild absorbed. `kind` is `.nativeItemFailed`; a failure the engine
     /// inferred from a frozen position across its own revives carries no underlying code.
     public let absorbedFailure: PlaybackErrorInfo
-    /// Where the session was when the native path gave up, in seconds.
+    /// Where the session was when the native path gave up, in seconds: the position the rebuild
+    /// resumes at, which during a mount is the one the mount was handed rather than AVPlayer's clock.
     public let positionSeconds: Double
     /// True when a `load()` was still waiting on this session's startup. That `load()` keeps waiting
     /// across the rebuild and returns when the rebuilt session is up, instead of throwing the
diff --git a/Tests/AetherEngineTests/SoftwarePathEscalationTests.swift b/Tests/AetherEngineTests/SoftwarePathEscalationTests.swift
index aa746d91d..069ce81a0 100644
--- a/Tests/AetherEngineTests/SoftwarePathEscalationTests.swift
+++ b/Tests/AetherEngineTests/SoftwarePathEscalationTests.swift
@@ -141,13 +141,18 @@ struct SoftwarePathEscalationTests {
 
     /// The ask's second form. Measured by the reporter: a host that heard only `videoRoute` could not
     /// tell the rescue from a routing decision.
-    @Test("A taken rung publishes the failure it absorbed", .timeLimit(.minutes(2)))
+    @Test("A taken rung publishes the failure it absorbed, at the position the rebuild resumes", .timeLimit(.minutes(2)))
     @MainActor
     func takenRungIsPublished() async throws {
         let origin = try ProbeHTTPTestOrigin(data: ProbeTestFixtures.hdr10Plus(), stage: .headers)
         defer { origin.stop() }
         let engine = try AetherEngine()
         engine.loadedURL = try #require(URL(string: "http://127.0.0.1:\(origin.port)/source.mkv"))
+        // AE#629 round 3, measured by the reporter: a mount raised by a load() of the host's own was
+        // refused while AVPlayer's clock read 12.00 s, the start of the segment under the 15.90 s the
+        // load was handed. The rebuild resumed at 15.90 s and the event said 12.00 s.
+        engine.state = .loading
+        engine.positionUnderReconstruction = 15.9
         var events: [SoftwarePathEscalationEvent] = []
         let sub = engine.softwarePathEscalations.sink { events.append($0) }
         defer { sub.cancel() }
@@ -162,7 +167,7 @@ struct SoftwarePathEscalationTests {
             absorbedFailure: PlaybackErrorInfo(
                 kind: .nativeItemFailed, message: "item death at a frozen position",
                 underlyingDomain: "CoreMediaErrorDomain", underlyingCode: -19602),
-            positionSeconds: 12,
+            positionSeconds: 15.9,
             duringStartup: false)])
     }
 

From 4a5c4a499be93451dc57c7faa6780947434a47ab Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sat, 26 Sep 2026 19:42:05 +0200
Subject: [PATCH 119/359] chore(release): prep 7.18.2 - an escalation reports
 the position its rebuild resumes at

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mf4MXgM9bqugHoe5TW4BYf
---
 CHANGELOG.md                                    | 4 ++++
 Examples/README.md                              | 2 +-
 README.md                                       | 6 +++---
 Sources/AetherEngine/AetherEngine+Version.swift | 2 +-
 4 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 73ba7cd60..dc9a5fbd9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,10 @@ the public-API contract.
 
 ## [Unreleased]
 
+_Nothing yet._
+
+## [7.18.2] - 2026-09-26
+
 ### Fixed
 
 - **A software-path escalation reports the position its rebuild resumes at (AE#629).** Under a
diff --git a/Examples/README.md b/Examples/README.md
index 7ab29d93b..54d48b6b2 100644
--- a/Examples/README.md
+++ b/Examples/README.md
@@ -18,7 +18,7 @@ Three samples covering different audiences:
    ```
    https://github.com/superuser404notfound/AetherEngine
    ```
-   Dependency Rule: Up to Next Major Version, starting from `7.18.1`. Add the `AetherEngine` library product to your app target.
+   Dependency Rule: Up to Next Major Version, starting from `7.18.2`. Add the `AetherEngine` library product to your app target.
 
 3. **Drop the file in.** Replace the Xcode template's default `App.swift` (or whatever the generated `@main` file is called) with the contents of [`MinimalPlayerApp.swift`](MinimalPlayer/MinimalPlayerApp.swift). The file is self-contained: it defines both the `@main App` struct and the `ContentView`.
 
diff --git a/README.md b/README.md
index 33de98473..dba673a62 100644
--- a/README.md
+++ b/README.md
@@ -384,7 +384,7 @@ Subtitle cues land in raw source PTS; render the overlay against `player.sourceT
 Install via Swift Package Manager:
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.18.1")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.18.2")
 ```
 
 Three samples ship in `Examples/`:
@@ -631,10 +631,10 @@ Browse all of this as a searchable site at **[aetherengine.superuser404.de](http
 AetherEngine uses [Semantic Versioning](https://semver.org). The public API surface, every `public` declaration in `Sources/AetherEngine/`, is the stability contract. **Major** removes / renames public symbols or breaks adopters; **Minor** adds public API or codec / format support; **Patch** fixes bugs with no public API change. `internal` types are not part of the contract.
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.18.1")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.18.2")
 ```
 
-Pin to `.upToNextMinor(from: "7.18.1")` for stricter teams that prefer to opt into minor bumps explicitly.
+Pin to `.upToNextMinor(from: "7.18.2")` for stricter teams that prefer to opt into minor bumps explicitly.
 
 ## Requirements
 
diff --git a/Sources/AetherEngine/AetherEngine+Version.swift b/Sources/AetherEngine/AetherEngine+Version.swift
index 1a486c031..ced1f39e4 100644
--- a/Sources/AetherEngine/AetherEngine+Version.swift
+++ b/Sources/AetherEngine/AetherEngine+Version.swift
@@ -11,5 +11,5 @@ extension AetherEngine {
     ///
     /// Between releases, and in a consumer that pins an unreleased commit for a device test, this
     /// names the last PUBLISHED version the checkout descends from, not every patch in it.
-    public nonisolated static let version = "7.18.1"
+    public nonisolated static let version = "7.18.2"
 }

From 2114e430e4f9ee5c5e5b9e4f1fe6994439cf1254 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sat, 26 Sep 2026 23:34:50 +0200
Subject: [PATCH 120/359] fix(decoder): a software-decoded picture carries the
 colour tags VideoToolbox would give it (#654)

The software decoder attached a colour tag only where the frame declared
one AND the value had a CoreVideo mapping. An untagged file therefore
reached the display layer with no primaries, transfer or matrix, while the
same file through VideoToolbox arrives tagged BT.709 (VT stamps its guess
as `ColorInfoGuessedBy: VideoToolbox`). One file, two looks, decided by
which decoder the route picked, and the software route is where old
codecs land (MPEG-4 ASP, MPEG-2, VC-1, VP9, AV1 without hardware).

The mapping also knew no SD codepoint at all, so a correctly tagged
BT.601 / SMPTE-C / EBU source lost its tags on the software path as well.

- `ColorAttachments` maps BT.601 (SMPTE 170M / BT.470BG) matrices, SMPTE-C
  and EBU 3213 primaries, DCI-P3, SMPTE 240M, sRGB and linear transfer,
  and the SDR BT.2020 / BT.601 curves onto the BT.709 constant.
- `ColorAttachments.presented` fills the gaps the way VideoToolbox does,
  measured on its output: nothing declared reads BT.709 in all three at
  any size and codec, a lone BT.601 matrix gets SMPTE-C primaries.
- `SoftwareVideoDecoder` always writes all three attachments.
- `ColorDescription` keeps its gaps: the HDR gate and the tone mapper
  still see an untagged stream as untagged.
- `SoftwareDecodeProbeResult.firstFrameColor` and `aetherctl swdecode`
  report the tags the first picture carries.

Measured with `aetherctl swdecode`, before -> after: untagged 1080p H.264,
480p H.264 and a DivX AVI `- / - / -` -> BT.709 x3; fully tagged PAL
`- / - / -` -> EBU_3213 / 709 / 601_4, identical to VideoToolbox's output
for the same file.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mf4MXgM9bqugHoe5TW4BYf
---
 Sources/AetherEngine/AetherEngine+Probe.swift | 10 +++-
 .../Decoder/ColorDescription.swift            |  4 +-
 .../Decoder/SoftwareVideoDecoder.swift        | 19 ++-----
 .../Decoder/VideoDecoderTypes.swift           | 55 +++++++++++++++++-
 Sources/AetherEngine/PlayerState.swift        |  8 ++-
 Sources/aetherctl/SWDecode.swift              |  3 +
 .../ColorAttachmentsTests.swift               | 56 +++++++++++++++++++
 docs/cli.md                                   |  2 +-
 8 files changed, 139 insertions(+), 18 deletions(-)
 create mode 100644 Tests/AetherEngineTests/ColorAttachmentsTests.swift

diff --git a/Sources/AetherEngine/AetherEngine+Probe.swift b/Sources/AetherEngine/AetherEngine+Probe.swift
index d9bd51768..b8a390a2c 100644
--- a/Sources/AetherEngine/AetherEngine+Probe.swift
+++ b/Sources/AetherEngine/AetherEngine+Probe.swift
@@ -419,6 +419,7 @@ extension AetherEngine {
             var firstFramePixelFormat: String?
             var firstFrameWidth: Int = 0
             var firstFrameHeight: Int = 0
+            var firstFrameColor: String?
             /// #407: in decoder output order, i.e. presentation order. Capped so a long run stays a
             /// diagnostic rather than an allocation.
             var frameTimesSeconds: [Double] = []
@@ -444,6 +445,12 @@ extension AetherEngine {
                     accum.firstFramePixelFormat = "\(fourCC) (0x\(String(pfType, radix: 16)))"
                     accum.firstFrameWidth = CVPixelBufferGetWidth(pixelBuffer)
                     accum.firstFrameHeight = CVPixelBufferGetHeight(pixelBuffer)
+                    accum.firstFrameColor = [
+                        kCVImageBufferColorPrimariesKey,
+                        kCVImageBufferTransferFunctionKey,
+                        kCVImageBufferYCbCrMatrixKey,
+                    ].map { (CVBufferCopyAttachment(pixelBuffer, $0, nil) as? String) ?? "-" }
+                        .joined(separator: " / ")
                 }
             }
         } catch {
@@ -504,7 +511,8 @@ extension AetherEngine {
             firstFrameWidth: accum.firstFrameWidth,
             firstFrameHeight: accum.firstFrameHeight,
             firstError: firstError,
-            frameTimesSeconds: accum.frameTimesSeconds
+            frameTimesSeconds: accum.frameTimesSeconds,
+            firstFrameColor: accum.firstFrameColor
         )
     }
 
diff --git a/Sources/AetherEngine/Decoder/ColorDescription.swift b/Sources/AetherEngine/Decoder/ColorDescription.swift
index 009288ec7..0073fddf4 100644
--- a/Sources/AetherEngine/Decoder/ColorDescription.swift
+++ b/Sources/AetherEngine/Decoder/ColorDescription.swift
@@ -53,7 +53,9 @@ struct ColorDescription: Equatable {
     /// The description to act on: the bitstream wherever it committed to a value, the container for the
     /// fields it left open. Per field, because a partially filled VUI is the common case and the one
     /// that fails silently (a matrix without a transfer reads HDR to a gate and reads nothing to zimg).
-    /// Two silences stay silent: an untagged stream is not improved by inventing BT.709 for it.
+    /// Two silences stay silent: an untagged stream is not improved by inventing BT.709 for it here.
+    /// The BT.709 a display needs is chosen where the buffer meets CoreVideo, see
+    /// `ColorAttachments.presented` (AE#654), so the HDR gate and the tone mapper still see the gap.
     static func resolved(bitstream: ColorDescription, container: ColorDescription) -> ColorDescription {
         ColorDescription(
             primaries: bitstream.primaries == AVCOL_PRI_UNSPECIFIED ? container.primaries : bitstream.primaries,
diff --git a/Sources/AetherEngine/Decoder/SoftwareVideoDecoder.swift b/Sources/AetherEngine/Decoder/SoftwareVideoDecoder.swift
index 5bde2e2d6..e332a732d 100644
--- a/Sources/AetherEngine/Decoder/SoftwareVideoDecoder.swift
+++ b/Sources/AetherEngine/Decoder/SoftwareVideoDecoder.swift
@@ -638,20 +638,13 @@ final class SoftwareVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
     // MARK: - Color Space Metadata
 
     /// Map FFmpeg color metadata to CVPixelBuffer attachments for correct HDR10 rendering (BT.2020 + PQ).
+    /// Every field is written, a gap included (AE#654): VideoToolbox never hands the display layer an
+    /// untagged buffer, and neither may this decoder.
     private func attachColorSpace(from frame: UnsafeMutablePointer<AVFrame>, to pb: CVPixelBuffer) {
-        let primaries = ColorAttachments.primaries(frame.pointee.color_primaries)
-        let transfer = ColorAttachments.transfer(frame.pointee.color_trc)
-        let matrix = ColorAttachments.matrix(frame.pointee.colorspace)
-
-        if let primaries {
-            CVBufferSetAttachment(pb, kCVImageBufferColorPrimariesKey, primaries, .shouldPropagate)
-        }
-        if let transfer {
-            CVBufferSetAttachment(pb, kCVImageBufferTransferFunctionKey, transfer, .shouldPropagate)
-        }
-        if let matrix {
-            CVBufferSetAttachment(pb, kCVImageBufferYCbCrMatrixKey, matrix, .shouldPropagate)
-        }
+        let tags = ColorAttachments.presented(ColorDescription(frame: frame))
+        CVBufferSetAttachment(pb, kCVImageBufferColorPrimariesKey, tags.primaries, .shouldPropagate)
+        CVBufferSetAttachment(pb, kCVImageBufferTransferFunctionKey, tags.transfer, .shouldPropagate)
+        CVBufferSetAttachment(pb, kCVImageBufferYCbCrMatrixKey, tags.matrix, .shouldPropagate)
     }
 
     // MARK: - Pixel Aspect Ratio (anamorphic SD)
diff --git a/Sources/AetherEngine/Decoder/VideoDecoderTypes.swift b/Sources/AetherEngine/Decoder/VideoDecoderTypes.swift
index 4246cc063..909467b47 100644
--- a/Sources/AetherEngine/Decoder/VideoDecoderTypes.swift
+++ b/Sources/AetherEngine/Decoder/VideoDecoderTypes.swift
@@ -62,15 +62,23 @@ enum ColorAttachments {
         case AVCOL_PRI_BT709:    kCVImageBufferColorPrimaries_ITU_R_709_2
         case AVCOL_PRI_BT2020:   kCVImageBufferColorPrimaries_ITU_R_2020
         case AVCOL_PRI_SMPTE432: kCVImageBufferColorPrimaries_P3_D65
+        case AVCOL_PRI_SMPTE431: kCVImageBufferColorPrimaries_DCI_P3
+        case AVCOL_PRI_SMPTE170M, AVCOL_PRI_SMPTE240M: kCVImageBufferColorPrimaries_SMPTE_C
+        case AVCOL_PRI_BT470BG:  kCVImageBufferColorPrimaries_EBU_3213
         default:                 nil
         }
     }
 
     static func transfer(_ v: AVColorTransferCharacteristic) -> CFString? {
         switch v {
-        case AVCOL_TRC_BT709:        kCVImageBufferTransferFunction_ITU_R_709_2
+        // BT.601 and the SDR BT.2020 codepoints name the BT.709 curve, CoreVideo has one constant for all.
+        case AVCOL_TRC_BT709, AVCOL_TRC_SMPTE170M, AVCOL_TRC_BT2020_10, AVCOL_TRC_BT2020_12:
+            kCVImageBufferTransferFunction_ITU_R_709_2
         case AVCOL_TRC_SMPTE2084:    kCVImageBufferTransferFunction_SMPTE_ST_2084_PQ
         case AVCOL_TRC_ARIB_STD_B67: kCVImageBufferTransferFunction_ITU_R_2100_HLG
+        case AVCOL_TRC_IEC61966_2_1: kCVImageBufferTransferFunction_sRGB
+        case AVCOL_TRC_LINEAR:       kCVImageBufferTransferFunction_Linear
+        case AVCOL_TRC_SMPTE240M:    kCVImageBufferTransferFunction_SMPTE_240M_1995
         default:                     nil
         }
     }
@@ -79,10 +87,55 @@ enum ColorAttachments {
         switch v {
         case AVCOL_SPC_BT709:                       kCVImageBufferYCbCrMatrix_ITU_R_709_2
         case AVCOL_SPC_BT2020_NCL, AVCOL_SPC_BT2020_CL: kCVImageBufferYCbCrMatrix_ITU_R_2020
+        case AVCOL_SPC_SMPTE170M, AVCOL_SPC_BT470BG: kCVImageBufferYCbCrMatrix_ITU_R_601_4
+        case AVCOL_SPC_SMPTE240M:                   kCVImageBufferYCbCrMatrix_SMPTE_240M_1995
         default:                                    nil
         }
     }
 
+    struct Tags: Equatable {
+        var primaries: CFString
+        var transfer: CFString
+        var matrix: CFString
+    }
+
+    /// AE#654: the tags a software-decoded buffer is presented with, gaps filled the way VideoToolbox
+    /// fills them on the hardware path. A buffer without tags is not read as BT.709 by the display
+    /// layer, the report has it going out in the panel's own gamut, so one untagged file looked two
+    /// ways depending on which decoder the route picked. Measured
+    /// on VideoToolbox's output (`ColorInfoGuessedBy`): nothing declared reads as BT.709 in all three,
+    /// at 720x480 and 720x576 as much as at 1080p and for MPEG-2 as much as H.264, and a lone BT.601
+    /// matrix gets SMPTE-C primaries and the BT.709 curve.
+    static func presented(_ d: ColorDescription) -> Tags {
+        let declaredPrimaries = primaries(d.primaries)
+        let declaredMatrix = matrix(d.matrix)
+        let bt709 = kCVImageBufferColorPrimaries_ITU_R_709_2
+        let bt601Matrix = kCVImageBufferYCbCrMatrix_ITU_R_601_4
+        let bt2020Matrix = kCVImageBufferYCbCrMatrix_ITU_R_2020
+        let bt2020Primaries = kCVImageBufferColorPrimaries_ITU_R_2020
+        let smpteC = kCVImageBufferColorPrimaries_SMPTE_C
+        let ebu = kCVImageBufferColorPrimaries_EBU_3213
+
+        let resolvedPrimaries: CFString = declaredPrimaries ?? {
+            switch declaredMatrix {
+            case bt601Matrix?:  smpteC
+            case bt2020Matrix?: bt2020Primaries
+            default:            bt709
+            }
+        }()
+        let resolvedMatrix: CFString = declaredMatrix ?? {
+            switch declaredPrimaries {
+            case smpteC?, ebu?:     bt601Matrix
+            case bt2020Primaries?:  bt2020Matrix
+            default:                kCVImageBufferYCbCrMatrix_ITU_R_709_2
+            }
+        }()
+        return Tags(
+            primaries: resolvedPrimaries,
+            transfer: transfer(d.transfer) ?? kCVImageBufferTransferFunction_ITU_R_709_2,
+            matrix: resolvedMatrix)
+    }
+
     /// PQ (ST 2084) or HLG transfer means the stream is HDR.
     static func isHDRTransfer(_ trc: AVColorTransferCharacteristic) -> Bool {
         trc == AVCOL_TRC_SMPTE2084 || trc == AVCOL_TRC_ARIB_STD_B67
diff --git a/Sources/AetherEngine/PlayerState.swift b/Sources/AetherEngine/PlayerState.swift
index b2b8788c3..3c61a8813 100644
--- a/Sources/AetherEngine/PlayerState.swift
+++ b/Sources/AetherEngine/PlayerState.swift
@@ -1067,6 +1067,10 @@ public struct SoftwareDecodeProbeResult: Sendable {
     /// container that withheld its PTS and had one invented from decode order produces a sawtooth,
     /// which is the one shape no packet-level or renderer-level counter can see.
     public let frameTimesSeconds: [Double]
+    /// AE#654: the colour tags the first picture reached the display layer with, as
+    /// `primaries / transfer / matrix` in CoreVideo's names, `-` for a missing one. An untagged source
+    /// reads `ITU_R_709_2` in all three here, the same as VideoToolbox's own output for it.
+    public let firstFrameColor: String?
 
     public init(
         codecName: String,
@@ -1082,9 +1086,11 @@ public struct SoftwareDecodeProbeResult: Sendable {
         firstFrameWidth: Int,
         firstFrameHeight: Int,
         firstError: String?,
-        frameTimesSeconds: [Double] = []
+        frameTimesSeconds: [Double] = [],
+        firstFrameColor: String? = nil
     ) {
         self.frameTimesSeconds = frameTimesSeconds
+        self.firstFrameColor = firstFrameColor
         self.codecName = codecName
         self.codecID = codecID
         self.width = width
diff --git a/Sources/aetherctl/SWDecode.swift b/Sources/aetherctl/SWDecode.swift
index 32a20324e..1eb9c66a6 100644
--- a/Sources/aetherctl/SWDecode.swift
+++ b/Sources/aetherctl/SWDecode.swift
@@ -30,6 +30,9 @@ func runSWDecode(url: URL, maxPackets: Int) -> Int32 {
     if let fmt = result.firstFramePixelFormat {
         print("First frame pixfmt:   \(fmt)")
         print("First frame size:     \(result.firstFrameWidth)x\(result.firstFrameHeight)")
+        if let color = result.firstFrameColor {
+            print("First frame color:    \(color)")
+        }
     } else {
         print("First frame:          (none decoded)")
     }
diff --git a/Tests/AetherEngineTests/ColorAttachmentsTests.swift b/Tests/AetherEngineTests/ColorAttachmentsTests.swift
new file mode 100644
index 000000000..2dde1a853
--- /dev/null
+++ b/Tests/AetherEngineTests/ColorAttachmentsTests.swift
@@ -0,0 +1,56 @@
+import CoreVideo
+import Testing
+import AetherLibavutil
+@testable import AetherEngine
+
+struct ColorAttachmentsTests {
+
+    private func described(
+        _ primaries: AVColorPrimaries = AVCOL_PRI_UNSPECIFIED,
+        _ transfer: AVColorTransferCharacteristic = AVCOL_TRC_UNSPECIFIED,
+        _ matrix: AVColorSpace = AVCOL_SPC_UNSPECIFIED
+    ) -> ColorDescription {
+        ColorDescription(primaries: primaries, transfer: transfer, matrix: matrix, range: AVCOL_RANGE_MPEG)
+    }
+
+    @Test("AE#654: an untagged stream is presented as BT.709 in all three, whatever its size")
+    func untaggedIsBT709() {
+        let tags = ColorAttachments.presented(.unspecified)
+        #expect(tags == ColorAttachments.Tags(
+            primaries: kCVImageBufferColorPrimaries_ITU_R_709_2,
+            transfer: kCVImageBufferTransferFunction_ITU_R_709_2,
+            matrix: kCVImageBufferYCbCrMatrix_ITU_R_709_2))
+    }
+
+    @Test("AE#654: a lone BT.601 matrix gets SMPTE-C primaries, as VideoToolbox fills it")
+    func bt601MatrixImpliesSMPTEC() {
+        let tags = ColorAttachments.presented(described(AVCOL_PRI_UNSPECIFIED, AVCOL_TRC_UNSPECIFIED, AVCOL_SPC_SMPTE170M))
+        #expect(tags.primaries == kCVImageBufferColorPrimaries_SMPTE_C)
+        #expect(tags.transfer == kCVImageBufferTransferFunction_ITU_R_709_2)
+        #expect(tags.matrix == kCVImageBufferYCbCrMatrix_ITU_R_601_4)
+    }
+
+    @Test("AE#654: SD primaries without a matrix get the BT.601 matrix, not BT.709")
+    func sdPrimariesImplyBT601Matrix() {
+        #expect(ColorAttachments.presented(described(AVCOL_PRI_BT470BG)).matrix == kCVImageBufferYCbCrMatrix_ITU_R_601_4)
+        #expect(ColorAttachments.presented(described(AVCOL_PRI_SMPTE170M)).matrix == kCVImageBufferYCbCrMatrix_ITU_R_601_4)
+        #expect(ColorAttachments.presented(described(AVCOL_PRI_BT2020)).matrix == kCVImageBufferYCbCrMatrix_ITU_R_2020)
+    }
+
+    @Test("AE#654: a tagged SD stream keeps its tags; before, none of them had a CoreVideo mapping")
+    func taggedSDIsNotGuessed() {
+        let pal = ColorAttachments.presented(described(AVCOL_PRI_BT470BG, AVCOL_TRC_SMPTE170M, AVCOL_SPC_BT470BG))
+        #expect(pal.primaries == kCVImageBufferColorPrimaries_EBU_3213)
+        #expect(pal.transfer == kCVImageBufferTransferFunction_ITU_R_709_2)
+        #expect(pal.matrix == kCVImageBufferYCbCrMatrix_ITU_R_601_4)
+    }
+
+    @Test("AE#654: a declared HDR description passes through untouched")
+    func hdrUntouched() {
+        let tags = ColorAttachments.presented(described(AVCOL_PRI_BT2020, AVCOL_TRC_SMPTE2084, AVCOL_SPC_BT2020_NCL))
+        #expect(tags == ColorAttachments.Tags(
+            primaries: kCVImageBufferColorPrimaries_ITU_R_2020,
+            transfer: kCVImageBufferTransferFunction_SMPTE_ST_2084_PQ,
+            matrix: kCVImageBufferYCbCrMatrix_ITU_R_2020))
+    }
+}
diff --git a/docs/cli.md b/docs/cli.md
index 0b2bde2d1..e0c0e748b 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -78,7 +78,7 @@ open 'http://127.0.0.1:<port>/master.m3u8'   # macOS QuickTime
 
 ## swdecode
 
-Opens `SoftwareVideoDecoder` for the source's video stream, feeds up to N packets (default 100, override with `--frames N`), and reports counters plus first-frame metadata (pixel format, dimensions). Tests the SW-pipeline decode path end-to-end without needing a render layer. Useful for legacy codecs (MPEG-4 Part 2, MPEG-2, VC-1) and AV1 / VP9 on platforms where the native AVPlayer path doesn't accept them. Verdict distinguishes three failure modes:
+Opens `SoftwareVideoDecoder` for the source's video stream, feeds up to N packets (default 100, override with `--frames N`), and reports counters plus first-frame metadata (pixel format, dimensions, and `firstFrameColor`, the colour tags the picture reaches the display layer with, AE#654). Tests the SW-pipeline decode path end-to-end without needing a render layer. Useful for legacy codecs (MPEG-4 Part 2, MPEG-2, VC-1) and AV1 / VP9 on platforms where the native AVPlayer path doesn't accept them. Verdict distinguishes three failure modes:
 
 - decoder open failed (FFmpegBuild gate or malformed extradata)
 - decoder opened but no frames produced (pixel-format conversion, no IDR in window)

From 4c465d24407971529d018563fcf11885a38c98d4 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sat, 26 Sep 2026 23:43:37 +0200
Subject: [PATCH 121/359] fix(extractor): a still is converted with the
 picture's own matrix and range

`FrameDecodeContext.convertToCGImage` never called
`sws_setColorspaceDetails`, so every SDR still went through swscale's
default: the BT.601 matrix, and a range read from the pixel format alone.
Every HD still was therefore converted with the wrong matrix, and a 10-bit
full-range picture (no yuvj variant exists) was also read as limited.

The matrix now comes from `ColorAttachments.presented`, the rule the
displayed buffer is tagged by (AE#654), so an untagged still resolves its
gap exactly as playback does. Range comes from `color_range` or a JPEG
pixel format.

Measured with `aetherctl extract --snapshot` against ffmpeg's conversion
with the correct matrix and range, colour bars, max channel error before
-> after: 1080p BT.709 33 -> 0, 1080p untagged 33 -> 0, 8-bit full range
32 -> 0, 10-bit HEVC full range 31 -> 0 (neutral grey 203 against 192
before), PAL BT.601 0 -> 0.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mf4MXgM9bqugHoe5TW4BYf
---
 .../FrameExtractor/FrameDecodeContext.swift   | 31 +++++++++++++
 .../StillColorspaceTests.swift                | 43 +++++++++++++++++++
 2 files changed, 74 insertions(+)
 create mode 100644 Tests/AetherEngineTests/StillColorspaceTests.swift

diff --git a/Sources/AetherEngine/FrameExtractor/FrameDecodeContext.swift b/Sources/AetherEngine/FrameExtractor/FrameDecodeContext.swift
index 34385129a..40d4fd94e 100644
--- a/Sources/AetherEngine/FrameExtractor/FrameDecodeContext.swift
+++ b/Sources/AetherEngine/FrameExtractor/FrameDecodeContext.swift
@@ -1,6 +1,7 @@
 import Foundation
 import CoreGraphics
 import CoreMedia
+import CoreVideo
 import AetherLibavformat
 import AetherLibavcodec
 import AetherLibavutil
@@ -615,6 +616,29 @@ final class FrameDecodeContext: @unchecked Sendable {
         return AVRational(num: 1, den: 1)
     }
 
+    /// The sws coefficient table for the matrix `ColorAttachments.presented` resolves, so a gap is
+    /// filled here exactly as it is on the buffer playback shows.
+    static func swsColorspace(for description: ColorDescription) -> Int32 {
+        switch ColorAttachments.presented(description).matrix {
+        case kCVImageBufferYCbCrMatrix_ITU_R_601_4:     SWS_CS_ITU601
+        case kCVImageBufferYCbCrMatrix_ITU_R_2020:      SWS_CS_BT2020
+        case kCVImageBufferYCbCrMatrix_SMPTE_240M_1995: SWS_CS_SMPTE240M
+        default:                                        SWS_CS_ITU709
+        }
+    }
+
+    /// Full range when the frame says so, or when its pixel format is one of the JPEG variants that
+    /// carry the range in the format rather than in `color_range`.
+    static func isFullRange(_ frame: UnsafePointer<AVFrame>) -> Bool {
+        if frame.pointee.color_range == AVCOL_RANGE_JPEG { return true }
+        switch AVPixelFormat(rawValue: frame.pointee.format) {
+        case AV_PIX_FMT_YUVJ420P, AV_PIX_FMT_YUVJ422P, AV_PIX_FMT_YUVJ444P, AV_PIX_FMT_YUVJ440P, AV_PIX_FMT_YUVJ411P:
+            return true
+        default:
+            return false
+        }
+    }
+
     /// sws_scale the frame to RGBA at `targetWidth` (height from source aspect) into an
     /// owned-buffer CGImage. Mirrors the sws tuple-pointer dance in SoftwareVideoDecoder.
     private func convertToCGImage(frame: UnsafeMutablePointer<AVFrame>, targetWidth: Int) -> CGImage? {
@@ -637,6 +661,13 @@ final class FrameDecodeContext: @unchecked Sendable {
             Int32(SWS_BILINEAR.rawValue), nil, nil, nil
         )
         guard swsContext != nil else { return nil }
+        // Without this sws converts every picture with its BT.601 default, which put a 1080p
+        // BT.709 colour bar up to 33 levels off in the still while playback showed it right.
+        // The matrix comes from the rule the displayed buffer is tagged by, so both agree.
+        let coefficients = sws_getCoefficients(Self.swsColorspace(for: ColorDescription(frame: frame)))
+        sws_setColorspaceDetails(
+            swsContext, coefficients, Self.isFullRange(frame) ? 1 : 0,
+            coefficients, 1, 0, 1 << 16, 1 << 16)
 
         let bytesPerRow = dstW * 4
         var rgba = [UInt8](repeating: 0, count: bytesPerRow * dstH)
diff --git a/Tests/AetherEngineTests/StillColorspaceTests.swift b/Tests/AetherEngineTests/StillColorspaceTests.swift
new file mode 100644
index 000000000..5c94fec7b
--- /dev/null
+++ b/Tests/AetherEngineTests/StillColorspaceTests.swift
@@ -0,0 +1,43 @@
+import Testing
+import AetherLibavutil
+import AetherLibswscale
+@testable import AetherEngine
+
+struct StillColorspaceTests {
+
+    private func described(_ primaries: AVColorPrimaries, _ matrix: AVColorSpace) -> ColorDescription {
+        ColorDescription(primaries: primaries, transfer: AVCOL_TRC_UNSPECIFIED, matrix: matrix, range: AVCOL_RANGE_MPEG)
+    }
+
+    @Test("A BT.709 still is converted with the BT.709 matrix, not sws's BT.601 default")
+    func bt709() {
+        #expect(FrameDecodeContext.swsColorspace(for: described(AVCOL_PRI_BT709, AVCOL_SPC_BT709)) == SWS_CS_ITU709)
+    }
+
+    @Test("An untagged still takes the matrix the displayed buffer is tagged with (AE#654)")
+    func untaggedFollowsPlayback() {
+        #expect(FrameDecodeContext.swsColorspace(for: .unspecified) == SWS_CS_ITU709)
+        #expect(FrameDecodeContext.swsColorspace(for: described(AVCOL_PRI_BT470BG, AVCOL_SPC_UNSPECIFIED)) == SWS_CS_ITU601)
+    }
+
+    @Test("SD and BT.2020 matrices keep their own tables")
+    func declaredMatrices() {
+        #expect(FrameDecodeContext.swsColorspace(for: described(AVCOL_PRI_UNSPECIFIED, AVCOL_SPC_SMPTE170M)) == SWS_CS_ITU601)
+        #expect(FrameDecodeContext.swsColorspace(for: described(AVCOL_PRI_UNSPECIFIED, AVCOL_SPC_BT2020_NCL)) == SWS_CS_BT2020)
+    }
+
+    @Test("Full range is read from color_range and from the JPEG pixel formats")
+    func fullRange() throws {
+        var frame: UnsafeMutablePointer<AVFrame>? = av_frame_alloc()
+        let f = try #require(frame)
+        defer { av_frame_free(&frame) }
+        f.pointee.format = AV_PIX_FMT_YUV420P10LE.rawValue
+        f.pointee.color_range = AVCOL_RANGE_MPEG
+        #expect(!FrameDecodeContext.isFullRange(f))
+        f.pointee.color_range = AVCOL_RANGE_JPEG
+        #expect(FrameDecodeContext.isFullRange(f))
+        f.pointee.color_range = AVCOL_RANGE_UNSPECIFIED
+        f.pointee.format = AV_PIX_FMT_YUVJ420P.rawValue
+        #expect(FrameDecodeContext.isFullRange(f))
+    }
+}

From fc1c531da84726cd3c983f0d82b610bb45bb5db9 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sat, 26 Sep 2026 23:45:26 +0200
Subject: [PATCH 122/359] chore(release): prep 7.19.0 - a software-decoded
 picture and a still carry the colours playback shows

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mf4MXgM9bqugHoe5TW4BYf
---
 CHANGELOG.md                                  | 26 +++++++++++++++++++
 Examples/README.md                            |  2 +-
 README.md                                     |  6 ++---
 .../AetherEngine/AetherEngine+Version.swift   |  2 +-
 4 files changed, 31 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index dc9a5fbd9..d33a44d0d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,32 @@ the public-API contract.
 
 _Nothing yet._
 
+## [7.19.0] - 2026-09-26
+
+### Fixed
+
+- **A software-decoded picture carries the colour tags VideoToolbox would give it (AE#654).** The
+  software decoder attached a tag only where the frame declared one and CoreVideo had a mapping, so
+  an untagged source reached the display layer with no primaries, transfer or matrix, while the same
+  file through VideoToolbox arrives tagged BT.709. It now fills the gaps the way VideoToolbox does,
+  measured on its output: nothing declared means BT.709 in all three at any size and codec, and a
+  lone BT.601 matrix gets SMPTE-C primaries. Affects the software route (MPEG-4 ASP, MPEG-2, VC-1,
+  VP9, AV1 without hardware decode). `ColorDescription` keeps its gaps, so the HDR gate and the
+  tone mapper still see an untagged stream as untagged.
+- **Tagged SD sources keep their tags on the software path.** `ColorAttachments` had no mapping for
+  BT.601 matrices, SMPTE-C or EBU 3213 primaries, so a correctly tagged PAL or NTSC source lost all
+  three. Added with DCI-P3, SMPTE 240M, sRGB and linear transfer.
+- **A `FrameExtractor` still is converted with the picture's own matrix and range.** The SDR still
+  path never called `sws_setColorspaceDetails`, so every still went through swscale's BT.601
+  default and a range read from the pixel format alone: HD colour bars were up to 33 levels off, and
+  a 10-bit full-range picture (no `yuvj` variant exists) was read as limited. The matrix now follows
+  the rule the displayed buffer is tagged by, so an untagged still resolves exactly as playback.
+
+### Added
+
+- **`SoftwareDecodeProbeResult.firstFrameColor`**: the colour tags the first picture reaches the
+  display layer with, as `primaries / transfer / matrix`. Printed by `aetherctl swdecode`.
+
 ## [7.18.2] - 2026-09-26
 
 ### Fixed
diff --git a/Examples/README.md b/Examples/README.md
index 54d48b6b2..b9d830add 100644
--- a/Examples/README.md
+++ b/Examples/README.md
@@ -18,7 +18,7 @@ Three samples covering different audiences:
    ```
    https://github.com/superuser404notfound/AetherEngine
    ```
-   Dependency Rule: Up to Next Major Version, starting from `7.18.2`. Add the `AetherEngine` library product to your app target.
+   Dependency Rule: Up to Next Major Version, starting from `7.19.0`. Add the `AetherEngine` library product to your app target.
 
 3. **Drop the file in.** Replace the Xcode template's default `App.swift` (or whatever the generated `@main` file is called) with the contents of [`MinimalPlayerApp.swift`](MinimalPlayer/MinimalPlayerApp.swift). The file is self-contained: it defines both the `@main App` struct and the `ContentView`.
 
diff --git a/README.md b/README.md
index dba673a62..f49ebfa66 100644
--- a/README.md
+++ b/README.md
@@ -384,7 +384,7 @@ Subtitle cues land in raw source PTS; render the overlay against `player.sourceT
 Install via Swift Package Manager:
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.18.2")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.19.0")
 ```
 
 Three samples ship in `Examples/`:
@@ -631,10 +631,10 @@ Browse all of this as a searchable site at **[aetherengine.superuser404.de](http
 AetherEngine uses [Semantic Versioning](https://semver.org). The public API surface, every `public` declaration in `Sources/AetherEngine/`, is the stability contract. **Major** removes / renames public symbols or breaks adopters; **Minor** adds public API or codec / format support; **Patch** fixes bugs with no public API change. `internal` types are not part of the contract.
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.18.2")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.19.0")
 ```
 
-Pin to `.upToNextMinor(from: "7.18.2")` for stricter teams that prefer to opt into minor bumps explicitly.
+Pin to `.upToNextMinor(from: "7.19.0")` for stricter teams that prefer to opt into minor bumps explicitly.
 
 ## Requirements
 
diff --git a/Sources/AetherEngine/AetherEngine+Version.swift b/Sources/AetherEngine/AetherEngine+Version.swift
index ced1f39e4..cd16dd4d4 100644
--- a/Sources/AetherEngine/AetherEngine+Version.swift
+++ b/Sources/AetherEngine/AetherEngine+Version.swift
@@ -11,5 +11,5 @@ extension AetherEngine {
     ///
     /// Between releases, and in a consumer that pins an unreleased commit for a device test, this
     /// names the last PUBLISHED version the checkout descends from, not every patch in it.
-    public nonisolated static let version = "7.18.2"
+    public nonisolated static let version = "7.19.0"
 }

From 629cda92402064a5623de921ea6d393145bfc7f2 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sat, 26 Sep 2026 23:51:19 +0200
Subject: [PATCH 123/359] fix(extractor): a still carries the colour space
 playback shows the picture in

`FrameDecodeContext` tagged every SDR still sRGB while its pixels are in
the source's own primaries and video transfer. The still now carries the
colour space CoreVideo builds from the same tags the displayed buffer
carries (`ColorAttachments.colorSpace(for:)` over
`ColorAttachments.presented`), which for BT.709 is
`kCGColorSpaceCoreMedia709`, the space VideoToolbox's own conversion of
the frame is in.

Measured against VideoToolbox's `VTCreateCGImageFromCVPixelBuffer` of the
same frame, both rendered into sRGB, colour bars, max channel error before
-> after: 1080p BT.709 9 -> 2, untagged 9 -> 2, PAL EBU 19 -> 2, NTSC
SMPTE-C 52 -> 2, SDR BT.2020 10-bit 57 -> 2. The remaining 2 is 8-bit RGB
against VideoToolbox's 10-bit path.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mf4MXgM9bqugHoe5TW4BYf
---
 .../AetherEngine/Decoder/VideoDecoderTypes.swift   | 14 ++++++++++++++
 .../FrameExtractor/FrameDecodeContext.swift        |  6 ++++--
 .../AetherEngineTests/ColorAttachmentsTests.swift  | 11 +++++++++++
 3 files changed, 29 insertions(+), 2 deletions(-)

diff --git a/Sources/AetherEngine/Decoder/VideoDecoderTypes.swift b/Sources/AetherEngine/Decoder/VideoDecoderTypes.swift
index 909467b47..f725890fb 100644
--- a/Sources/AetherEngine/Decoder/VideoDecoderTypes.swift
+++ b/Sources/AetherEngine/Decoder/VideoDecoderTypes.swift
@@ -1,6 +1,7 @@
 import Foundation
 import CoreMedia
 import CoreVideo
+import CoreGraphics
 import AetherLibavformat
 import AetherLibavcodec
 
@@ -136,6 +137,19 @@ enum ColorAttachments {
             matrix: resolvedMatrix)
     }
 
+    /// The colour space CoreVideo manages a buffer with these tags in, i.e. the one playback shows the
+    /// picture in. An RGB still converted from the same picture has to carry it: tagged sRGB instead,
+    /// a BT.709 still drew 8 levels darker than VideoToolbox's own conversion of the frame, and an SDR
+    /// BT.2020 one up to 57 levels off in red.
+    static func colorSpace(for tags: Tags) -> CGColorSpace? {
+        let attachments: NSDictionary = [
+            kCVImageBufferColorPrimariesKey: tags.primaries,
+            kCVImageBufferTransferFunctionKey: tags.transfer,
+            kCVImageBufferYCbCrMatrixKey: tags.matrix,
+        ]
+        return CVImageBufferCreateColorSpaceFromAttachments(attachments)?.takeRetainedValue()
+    }
+
     /// PQ (ST 2084) or HLG transfer means the stream is HDR.
     static func isHDRTransfer(_ trc: AVColorTransferCharacteristic) -> Bool {
         trc == AVCOL_TRC_SMPTE2084 || trc == AVCOL_TRC_ARIB_STD_B67
diff --git a/Sources/AetherEngine/FrameExtractor/FrameDecodeContext.swift b/Sources/AetherEngine/FrameExtractor/FrameDecodeContext.swift
index 40d4fd94e..cb7bf67b8 100644
--- a/Sources/AetherEngine/FrameExtractor/FrameDecodeContext.swift
+++ b/Sources/AetherEngine/FrameExtractor/FrameDecodeContext.swift
@@ -664,7 +664,8 @@ final class FrameDecodeContext: @unchecked Sendable {
         // Without this sws converts every picture with its BT.601 default, which put a 1080p
         // BT.709 colour bar up to 33 levels off in the still while playback showed it right.
         // The matrix comes from the rule the displayed buffer is tagged by, so both agree.
-        let coefficients = sws_getCoefficients(Self.swsColorspace(for: ColorDescription(frame: frame)))
+        let description = ColorDescription(frame: frame)
+        let coefficients = sws_getCoefficients(Self.swsColorspace(for: description))
         sws_setColorspaceDetails(
             swsContext, coefficients, Self.isFullRange(frame) ? 1 : 0,
             coefficients, 1, 0, 1 << 16, 1 << 16)
@@ -705,7 +706,8 @@ final class FrameDecodeContext: @unchecked Sendable {
 
         let data = Data(rgba)
         guard let provider = CGDataProvider(data: data as CFData),
-              let colorSpace = CGColorSpace(name: CGColorSpace.sRGB) else {
+              let colorSpace = ColorAttachments.colorSpace(for: ColorAttachments.presented(description))
+                ?? CGColorSpace(name: CGColorSpace.sRGB) else {
             return nil
         }
         // sws_scale RGBA yields opaque pixels (alpha 0xFF), so alpha is ignorable not premultiplied.
diff --git a/Tests/AetherEngineTests/ColorAttachmentsTests.swift b/Tests/AetherEngineTests/ColorAttachmentsTests.swift
index 2dde1a853..0f32ee28a 100644
--- a/Tests/AetherEngineTests/ColorAttachmentsTests.swift
+++ b/Tests/AetherEngineTests/ColorAttachmentsTests.swift
@@ -53,4 +53,15 @@ struct ColorAttachmentsTests {
             transfer: kCVImageBufferTransferFunction_SMPTE_ST_2084_PQ,
             matrix: kCVImageBufferYCbCrMatrix_ITU_R_2020))
     }
+
+    @Test("A still's colour space is the one CoreVideo manages the displayed buffer in")
+    func stillColorSpaceFollowsPlayback() throws {
+        let untagged = try #require(ColorAttachments.colorSpace(for: ColorAttachments.presented(.unspecified)))
+        #expect(untagged.name as String? == "kCGColorSpaceCoreMedia709")
+        let sd = ColorAttachments.presented(described(AVCOL_PRI_SMPTE170M, AVCOL_TRC_SMPTE170M, AVCOL_SPC_SMPTE170M))
+        let sdSpace = try #require(ColorAttachments.colorSpace(for: sd))
+        #expect(sdSpace != untagged)
+        let sdr2020 = ColorAttachments.presented(described(AVCOL_PRI_BT2020, AVCOL_TRC_BT2020_10, AVCOL_SPC_BT2020_NCL))
+        #expect(ColorAttachments.colorSpace(for: sdr2020) != nil)
+    }
 }

From ed0ce13629b60bf4c031eca77cb49db172dd309e Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sun, 27 Sep 2026 05:44:25 +0200
Subject: [PATCH 124/359] docs(changelog): note the still colour-space fix
 under Unreleased

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mf4MXgM9bqugHoe5TW4BYf
---
 CHANGELOG.md | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d33a44d0d..51cfc5ac0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,7 +10,13 @@ the public-API contract.
 
 ## [Unreleased]
 
-_Nothing yet._
+### Fixed
+
+- **A `FrameExtractor` still carries the colour space playback shows the picture in.** SDR stills
+  were tagged sRGB while their pixels are in the source's own primaries and video transfer. They now
+  carry the space CoreVideo builds from the tags the displayed buffer carries
+  (`kCGColorSpaceCoreMedia709` for BT.709). Against VideoToolbox's own conversion of the same frame,
+  max channel error 9 -> 2 on BT.709, 52 -> 2 on NTSC SMPTE-C, 57 -> 2 on SDR BT.2020.
 
 ## [7.19.0] - 2026-09-26
 

From 70dc485d53af9488540fa900bcee18cd46e8cdbd Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sun, 27 Sep 2026 16:35:20 +0200
Subject: [PATCH 125/359] fix(hls): a forward-only source keeps its opening and
 all of its media

Three defects on a source that can only be read front to back, all measured
against a remote MKV that ignores Range and names no length:

- The cursor reset after the segment plan seeked a pb that cannot rewind.
  That drops the probe's buffered packets and leaves matroskadec resyncing
  from wherever the stream had got to, so the gate opened a GOP late (on the
  software path the reporter's session started 30 s in). The prewarm never
  runs on such a source, so the cursor never left the head; skip the reset.
- On a sequential origin audio opened segments by time while the playlist is
  built from the video keyframe cuts. With a GOP longer than the stride the
  video after an audio-opened boundary landed in a file the playlist never
  lists (4 to 11 s of an 11.3 s first GOP) and AVPlayer stalled at the end of
  seg0. Audio now follows the video cutter there, as it does on live.
- The finalize funnel anchored on the first REPORT, and the hole a long first
  GOP skips is known before seg0 is captured, so every later report was
  refused as out of order and the playlist stayed empty.

SequentialLongGOPPlaylistTests serves two fixtures (passthrough AAC and
bridged PCM) forward-only and counts the video frames the finished playlist
carries: 720 of 720 with the fix, 96 missing without the producer change and
the whole first GOP missing without the reset change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mf4MXgM9bqugHoe5TW4BYf
---
 Scripts/fetch-fixtures.sh                     |  16 +++
 .../Video/HLSSegmentProducer.swift            |  28 ++++-
 .../AetherEngine/Video/HLSVideoEngine.swift   |   7 +-
 .../Issue255BodyReserveTests.swift            |  11 ++
 .../SequentialLongGOPPlaylistTests.swift      | 108 ++++++++++++++++++
 5 files changed, 162 insertions(+), 8 deletions(-)
 create mode 100644 Tests/AetherEngineTests/SequentialLongGOPPlaylistTests.swift

diff --git a/Scripts/fetch-fixtures.sh b/Scripts/fetch-fixtures.sh
index 2c2e4514e..320facfb6 100755
--- a/Scripts/fetch-fixtures.sh
+++ b/Scripts/fetch-fixtures.sh
@@ -19,6 +19,7 @@
 #   a53-captions.mp4              - H.264 with in-picture A/53 CEA-608 SEI (#131, #259)
 #   hev1-inband-xps.mp4           - HEVC with in-band VPS/SPS/PPS and an empty hvcC
 #   cue-axis-bframes.mkv/.mp4     - one HEVC B-pyramid stream in both containers (AE#561)
+#   long-first-gop-{aac,pcm}.mkv  - 11 s first GOP, then 2 s GOPs; passthrough and bridged audio
 #   bridge-eac3-51.mkv            - 5.1 PCM in MKV, drives the EAC3 audio bridge (AE#561 follow-up)
 #
 # Real-world DV / Atmos / multichannel sources have to come from your
@@ -370,6 +371,21 @@ ffmpeg -hide_banner -loglevel error -y -copyts -i "$OFFSET_TS" -c copy \
     -hls_segment_filename "$FIXTURES_DIR/user/hls-hevc-vod-offset/seg%03d.ts" \
     "$FIXTURES_DIR/user/hls-hevc-vod-offset/media.m3u8"
 
+# A sequential origin's playlist is cut on video keyframes. A first GOP far longer than the 4 s stride
+# is the shape a remote MKV had (11.3 s). Served forward-only its Cues are never read, so the plan is
+# the uniform stride and audio reaches every boundary long before a keyframe does. One clip per audio
+# path: AAC is passed through, stereo PCM goes through the FLAC bridge (the reporter's Vorbis did).
+for AUDIO in aac pcm; do
+    CODEC=aac; [ "$AUDIO" = pcm ] && CODEC=pcm_s16le
+    echo "→ long-first-gop-$AUDIO.mkv (keyframes at 0, 11, 13, 15 ... s, 30 s)"
+    ffmpeg -hide_banner -loglevel error -y \
+        -f lavfi -i "testsrc2=size=320x180:rate=24" \
+        -f lavfi -i "sine=frequency=440:sample_rate=48000" -t 30 \
+        -c:v libx264 -preset veryfast -pix_fmt yuv420p -b:v 200k -bf 0 \
+        -g 1000 -sc_threshold 0 -force_key_frames "0,11,13,15,17,19,21,23,25,27,29" \
+        -c:a "$CODEC" -ac 2 -f matroska "$FIXTURES_DIR/long-first-gop-$AUDIO.mkv"
+done
+
 echo ""
 echo "Done. Try:"
 echo "  swift run aetherctl probe $FIXTURES_DIR/sdr-h264.mp4"
diff --git a/Sources/AetherEngine/Video/HLSSegmentProducer.swift b/Sources/AetherEngine/Video/HLSSegmentProducer.swift
index d35b797c7..1b00d2757 100644
--- a/Sources/AetherEngine/Video/HLSSegmentProducer.swift
+++ b/Sources/AetherEngine/Video/HLSSegmentProducer.swift
@@ -245,7 +245,10 @@ final class HLSSegmentProducer: @unchecked Sendable {
 
     /// Order-preserving funnel for sequential finalize reports.
     private func emitSequentialReport(index: Int, duration: Double) {
-        let base = seqNextReportIndex ?? index
+        // Anchored on the pump's first segment, not on the first report: a hole a long first GOP
+        // skipped is known before that segment's capture lands, and anchoring on the hole would
+        // leave every later report waiting for an index below it.
+        let base = seqNextReportIndex ?? min(index, baseIndex)
         seqNextReportIndex = base
         seqReadyReports[index] = duration
         var next = base
@@ -450,6 +453,14 @@ final class HLSSegmentProducer: @unchecked Sendable {
     private var firstSyncItemPtsBySegment: [Int: Int64] = [:]
     private var pendingAudioSegIndex: Int = 0
 
+    /// A sequential origin's playlist advertises a segment from the VIDEO cut ledger (its EXTINF is
+    /// the distance between two keyframe-gated opens, and a plan index no keyframe opened is a hole
+    /// with no URI). Audio routed by time against the plan would open that hole on its own wherever
+    /// the source's GOP is longer than the stride, and the video after it would land in a file the
+    /// playlist never lists: a remote MKV with an 11 s first GOP lost 4 to 11 s that way and stalled
+    /// AVPlayer at the end of seg0. So there, as on live, audio follows the video cutter.
+    private var audioFollowsVideoCut: Bool { !isLive && onSequentialSegmentFinalized != nil }
+
     /// VOD keyframe-gated cutter: opens each segment at the IRAP that reaches its plan boundary (#92).
     private var vodCutter: VODSegmentCutter
 
@@ -4040,10 +4051,13 @@ final class HLSSegmentProducer: @unchecked Sendable {
                                 trackedPacketFree(&fpVar)
                                 continue
                             }
-                            // Rescale FLAC pts to source video TB for segment lookup; live audio follows video cutter.
+                            // Rescale FLAC pts to source video TB for segment lookup; live and
+                            // sequential audio follow the video cutter.
                             let fpSeg: Int
                             if isLive {
                                 fpSeg = liveCurrentSegmentIndex
+                            } else if audioFollowsVideoCut {
+                                fpSeg = vodCutter.current
                             } else {
                                 let fpPtsInVideoTb = av_rescale_q(
                                     fp.pointee.pts,
@@ -4072,10 +4086,12 @@ final class HLSSegmentProducer: @unchecked Sendable {
                         continue
                     }
                     if audio.stripAacAdts { Self.stripADTSHeader(packet) }
-                    let thisAudioSeg: Int = isLive ? liveCurrentSegmentIndex : 0
+                    let thisAudioSeg: Int = isLive
+                        ? liveCurrentSegmentIndex
+                        : (audioFollowsVideoCut ? vodCutter.current : 0)
                     if let prev = pendingAudioPkt {
                         let prevSeg: Int
-                        if isLive {
+                        if isLive || audioFollowsVideoCut {
                             prevSeg = pendingAudioSegIndex
                         } else {
                             let prevPtsInVideoTb = av_rescale_q(
@@ -4096,7 +4112,7 @@ final class HLSSegmentProducer: @unchecked Sendable {
                         }
                     }
                     pendingAudioPkt = packet
-                    if isLive { pendingAudioSegIndex = thisAudioSeg }
+                    if isLive || audioFollowsVideoCut { pendingAudioSegIndex = thisAudioSeg }
                     pktPtr = nil
                     continue
                 }
@@ -4173,7 +4189,7 @@ final class HLSSegmentProducer: @unchecked Sendable {
         }
         if let prev = pendingAudioPkt, let audio = audioConfig {
             let prevSeg: Int
-            if isLive {
+            if isLive || audioFollowsVideoCut {
                 prevSeg = pendingAudioSegIndex
             } else {
                 let prevPtsInVideoTb = av_rescale_q(
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine.swift b/Sources/AetherEngine/Video/HLSVideoEngine.swift
index 73bf66ed6..2fda1e338 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine.swift
@@ -1431,9 +1431,12 @@ public final class HLSVideoEngine: @unchecked Sendable {
         }
 
         // 6. Reset demuxer cursor to 0 (cue prewarm moved it mid-file). Skipped for live
-        //    (no prewarm, forward-only feed).
+        //    (no prewarm, forward-only feed), and for a forward-only VOD source: the prewarm did not
+        //    run there, so the cursor never left the head, and a seek on a pb that cannot rewind
+        //    drops the probe's buffered packets and leaves matroskadec resyncing from wherever the
+        //    stream has got to (a remote MKV lost its first second, on the software path 30 s).
         if !isLiveSession {
-            dem.seek(to: 0)
+            if dem.isSourceSeekable { dem.seek(to: 0) }
             dem.endIndexPass()      // AE#585: the next read that lands outside a span is playback's
         }
 
diff --git a/Tests/AetherEngineTests/Issue255BodyReserveTests.swift b/Tests/AetherEngineTests/Issue255BodyReserveTests.swift
index bf140bd71..568fc659f 100644
--- a/Tests/AetherEngineTests/Issue255BodyReserveTests.swift
+++ b/Tests/AetherEngineTests/Issue255BodyReserveTests.swift
@@ -38,6 +38,8 @@ final class ScriptedOriginServer: @unchecked Sendable {
         /// Filler bytes actually written. May be far below or above `declaredLength`.
         var bodyBytes: Int = 0
         var close: Bool = false
+        /// Real bytes to serve instead of the filler; `bodyBytes` is ignored when set.
+        var body: Data? = nil
     }
 
     private let listenFD: Int32
@@ -179,6 +181,15 @@ final class ScriptedOriginServer: @unchecked Sendable {
         guard method != "HEAD" else { return keepAlive }
 
         let sliceBytes = 256 * 1024
+        if let body = r.body {
+            var sent = 0
+            while sent < body.count && !stopped {
+                let n = min(sliceBytes, body.count - sent)
+                guard writeCounting(fd, Array(body[sent..<(sent + n)])) else { return false }
+                sent += n
+            }
+            return keepAlive
+        }
         let slice = [UInt8](repeating: 0x5A, count: sliceBytes)
         var sent = 0
         while sent < r.bodyBytes && !stopped {
diff --git a/Tests/AetherEngineTests/SequentialLongGOPPlaylistTests.swift b/Tests/AetherEngineTests/SequentialLongGOPPlaylistTests.swift
new file mode 100644
index 000000000..dbb59d3e3
--- /dev/null
+++ b/Tests/AetherEngineTests/SequentialLongGOPPlaylistTests.swift
@@ -0,0 +1,108 @@
+// A sequential origin advertises its segments from the VIDEO cut ledger: a segment's EXTINF is the
+// distance between two keyframe-gated opens, and a plan index no keyframe opened is a zero-duration
+// hole with no URI. Audio used to be routed by time against the plan instead, so on a source whose
+// GOP is longer than the 4 s stride it opened that hole on its own, the video after it went into a
+// file the playlist never listed, and AVPlayer stalled at the end of seg0 (a remote MKV with an
+// 11.3 s first GOP lost 4 to 11 s). The same hole arrived before seg0's capture had, and the report
+// funnel anchored on it, so every later report was refused as out of order and the playlist stayed
+// empty. Both are witnessed here by counting what the finished playlist actually carries.
+import Foundation
+import Testing
+@testable import AetherEngine
+
+private func fixtureURL(_ name: String) -> URL {
+    URL(fileURLWithPath: #filePath)
+        .deletingLastPathComponent()
+        .deletingLastPathComponent()
+        .deletingLastPathComponent()
+        .appendingPathComponent("Fixtures")
+        .appendingPathComponent(name)
+}
+
+private func fixtureExists(_ name: String) -> Bool {
+    FileManager.default.fileExists(atPath: fixtureURL(name).path)
+}
+
+/// Video samples (track 1) across every fragment of a segment, from the `trun` sample counts.
+private func videoSampleCount(_ segment: Data) -> Int {
+    func u32(_ off: Int) -> UInt32 {
+        segment.withUnsafeBytes { UInt32(bigEndian: $0.loadUnaligned(fromByteOffset: off, as: UInt32.self)) }
+    }
+    func boxes(_ range: Range<Int>) -> [(String, Range<Int>)] {
+        var out: [(String, Range<Int>)] = []
+        var off = range.lowerBound
+        while off + 8 <= range.upperBound {
+            let size = Int(u32(off))
+            guard size >= 8, off + size <= range.upperBound else { break }
+            let type = String(bytes: segment[off + 4..<off + 8], encoding: .isoLatin1) ?? "????"
+            out.append((type, (off + 8)..<(off + size)))
+            off += size
+        }
+        return out
+    }
+    var count = 0
+    for (type, moof) in boxes(0..<segment.count) where type == "moof" {
+        for (t2, traf) in boxes(moof) where t2 == "traf" {
+            var track: UInt32 = 0
+            var samples = 0
+            for (t3, body) in boxes(traf) {
+                if t3 == "tfhd" { track = u32(body.lowerBound + 4) }
+                if t3 == "trun" { samples += Int(u32(body.lowerBound + 4)) }
+            }
+            if track == 1 { count += samples }
+        }
+    }
+    return count
+}
+
+@Suite("Sequential origin with a GOP longer than the stride", .serialized)
+struct SequentialLongGOPPlaylistTests {
+
+    /// `aac` is passed through, `pcm` goes through the FLAC bridge (the reporter's Vorbis did); the two
+    /// route their packets to segments at different sites, and both used to route by time.
+    @Test("the finished playlist lists every video frame and the whole duration",
+          .enabled(if: fixtureExists("long-first-gop-aac.mkv") && fixtureExists("long-first-gop-pcm.mkv"),
+                   "run Scripts/fetch-fixtures.sh to generate the witness clips"),
+          .timeLimit(.minutes(2)),
+          arguments: ["aac", "pcm"])
+    func longFirstGOPLosesNothing(audio: String) async throws {
+        // Served the way the reporting origin served it: `Range` ignored, no length, one plain 200.
+        // Over a seekable file the plan would come from the Cues and cut on the keyframes, which
+        // hides the defect; a forward-only source never reads them and gets the uniform stride.
+        let name = "long-first-gop-\(audio).mkv"
+        let body = try Data(contentsOf: fixtureURL(name))
+        let server = try #require(ScriptedOriginServer { _ in
+            .init(status: 200, declaredLength: nil, close: true, body: body)
+        })
+        defer { server.stop() }
+        let url = URL(string: "http://127.0.0.1:\(server.port)/\(name)")!
+        let engine = HLSVideoEngine(url: url, dvModeAvailable: false,
+                                    sequentialOrigin: true, declaredDurationSeconds: 30)
+        _ = try engine.start()
+        defer { engine.stop() }
+        let mediaURL = try #require(engine.mediaPlaylistURL)
+
+        var playlist = ""
+        for _ in 0..<300 {
+            playlist = (try? String(contentsOf: mediaURL, encoding: .utf8)) ?? ""
+            if playlist.contains("#EXT-X-ENDLIST") { break }
+            try await Task.sleep(nanoseconds: 50_000_000)
+        }
+        #expect(playlist.contains("#EXT-X-ENDLIST"), "the playlist never completed:\n\(playlist)")
+
+        let lines = playlist.split(whereSeparator: \.isNewline).map(String.init)
+        let durations = lines.filter { $0.hasPrefix("#EXTINF:") }
+            .compactMap { Double($0.dropFirst("#EXTINF:".count).split(separator: ",").first ?? "") }
+        let uris = lines.filter { $0.hasSuffix(".mp4") && !$0.hasPrefix("#") }
+        #expect(!uris.isEmpty)
+        #expect(abs(durations.reduce(0, +) - 30) < 0.5,
+                "EXTINF sums to \(durations.reduce(0, +)) s for a 30 s source:\n\(playlist)")
+
+        var frames = 0
+        for uri in uris {
+            let data = try Data(contentsOf: mediaURL.deletingLastPathComponent().appendingPathComponent(uri))
+            frames += videoSampleCount(data)
+        }
+        #expect(frames == 720, "the listed segments carry \(frames) of 720 video frames:\n\(playlist)")
+    }
+}

From c7d4626729396a0d0dc49492f0c9fe70a0d205f7 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sun, 27 Sep 2026 16:35:20 +0200
Subject: [PATCH 126/359] feat(routing): serve a forward-only URL source
 natively, and say when AirPlay gets no picture

A URL source the reader finds forward-only was forced onto the software host,
which cannot seek on it either and never hands an AirPlay receiver its picture:
the TV played the sound only, then gave the session up. When the container
states a duration the engine now serves such a source as the sequential origin
it is (native path, hardware decode, AVPlayer buffering, a picture on the
receiver). Custom readers, sources the routing already sent to software and a
host's preferredDecodePath = .software are left alone.

An AirPlay edge on a sequential origin swaps the item onto the LAN address
instead of rebuilding the session: a reopen can only restart from byte 0, and
the reload resumed at 0 and then sat seeking (on the remote origin it ended in
"Source cannot be repositioned"). The in-place swap keeps the playhead.

airPlayPictureStaysLocal publishes, on iOS, that a wireless receiver holds the
audio route while the software host draws the picture on the device, so a host
can tell the viewer instead of the receiver going quiet about it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mf4MXgM9bqugHoe5TW4BYf
---
 CHANGELOG.md                                  | 26 +++++-
 Sources/AetherEngine/AetherEngine.swift       | 88 ++++++++++++++++++-
 .../Decoder/VideoRoutingPolicy.swift          | 26 ++++++
 .../ForwardOnlySequentialPromotionTests.swift | 52 +++++++++++
 docs/api.md                                   |  3 +-
 5 files changed, 192 insertions(+), 3 deletions(-)
 create mode 100644 Tests/AetherEngineTests/ForwardOnlySequentialPromotionTests.swift

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 51cfc5ac0..3da906838 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,7 +10,31 @@ the public-API contract.
 
 ## [Unreleased]
 
-### Fixed
+### Added
+
+- **`airPlayPictureStaysLocal`.** iOS publishes true while a wireless AirPlay receiver holds the audio
+  route and the session runs on the software host, whose picture stays on the device while its sound
+  goes to the TV. Nothing fails there, so a host had no way to tell the viewer why the receiver showed
+  no picture.
+
+### Fixed
+
+- **A URL source that can only be read front to back plays on the native path, and AirPlays with a
+  picture.** An origin that ignores `Range` and names no length (a remote MKV on filesamples.com)
+  was forced onto the software host, which cannot seek on it either and never hands a receiver its
+  picture: AirPlay played the sound only. When the container states a duration the engine now serves
+  such a source as a sequential origin, and an AirPlay hop swaps the item onto the LAN address rather
+  than reopening a source that could only restart from byte 0.
+- **A forward-only source no longer loses its opening.** The cursor reset after the segment plan
+  seeked a source that cannot rewind, which drops the packets the probe had buffered and leaves the
+  Matroska demuxer resyncing wherever the stream had got to: the first GOP of a 30 s clip, 30 s into
+  a remote MKV on the software path.
+- **A sequential origin whose GOP is longer than the segment stride lists all of its media.** Audio
+  opened segments by time while the playlist is built from the video keyframe cuts, so the video
+  after an audio-opened boundary landed in a file the playlist never listed (4 to 11 s of an 11 s
+  first GOP), and AVPlayer stalled at the end of seg0. Audio now follows the video cut there, as on
+  live. The finalize reports are also anchored on the pump's first segment, so a skipped index known
+  before seg0 is captured no longer holds back every later one.
 
 - **A `FrameExtractor` still carries the colour space playback shows the picture in.** SDR stills
   were tagged sRGB while their pixels are in the source's own primaries and video transfer. They now
diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index 5b412120f..ae8c0537f 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -631,7 +631,36 @@ public final class AetherEngine: ObservableObject {
     /// Exposed for diagnostic overlays; hosts should not branch on it. Branch on `videoRoute` instead,
     /// which also separates the two native pipelines (#321).
     @Published public internal(set) var playbackBackend: PlaybackBackend = .none {
-        didSet { recomputeVideoRoute(); recomputeAudioDelivery() }
+        didSet { recomputeVideoRoute(); recomputeAudioDelivery(); recomputeAirPlayPictureStaysLocal() }
+    }
+
+    /// True while a wireless AirPlay receiver holds the audio route and the session's picture cannot
+    /// follow it, so the receiver plays the sound and the picture stays on this device.
+    ///
+    /// That is the software host (VP9, AV1 without a hardware decoder, deinterlaced MPEG-2 / VC-1 /
+    /// H.264, a host's `preferredDecodePath = .software`): it draws into an `AVSampleBufferDisplayLayer`,
+    /// and only its `AVSampleBufferAudioRenderer` follows the route. Nothing fails, so without this a host
+    /// has no way to tell the viewer why the TV shows no picture. iOS only; false everywhere else, and
+    /// false on the native paths, where AVPlayer hands the receiver the stream.
+    @Published public internal(set) var airPlayPictureStaysLocal = false
+
+    nonisolated static func airPlayPictureStaysLocal(backend: PlaybackBackend,
+                                                     wirelessAirPlayRoute: Bool) -> Bool {
+        wirelessAirPlayRoute && backend == .software
+    }
+
+    /// Idempotent, and logged on each change, so a report shows when the receiver lost the picture.
+    func recomputeAirPlayPictureStaysLocal() {
+        let next = Self.airPlayPictureStaysLocal(backend: playbackBackend,
+                                                 wirelessAirPlayRoute: Self.isWirelessAirPlayRoute())
+        guard airPlayPictureStaysLocal != next else { return }
+        airPlayPictureStaysLocal = next
+        EngineLog.emit(
+            next
+                ? "[AirPlay] wireless receiver holds the audio route, but the software path draws the "
+                  + "picture on this device: the receiver plays sound only"
+                : "[AirPlay] picture and audio route agree again",
+            category: .engine)
     }
 
     /// Pipeline actually serving this session (#321), including the reroutes the host never asked for.
@@ -4659,6 +4688,27 @@ public final class AetherEngine: ObservableObject {
         // (device trace: a 720p50 timeshift archive played clean on the native path and visibly
         // stuttered on the software one). Declared-interlaced archives still route software via
         // the field-order policy above - the #232 refute probe cannot run without a rewind.
+        if probeOpened, VideoRoutingPolicy.promotesForwardOnlySourceToSequential(
+            isSourceSeekable: probe.isSourceSeekable,
+            isLive: options.isLive,
+            declaredSequential: options.sequentialOrigin,
+            isCustomSource: isCustomSource,
+            routedSoftware: useSoftwarePath,
+            preferred: options.preferredDecodePath,
+            containerDurationSeconds: probe.duration
+        ) {
+            // Written into loadedOptions as well, so every rebuild of this session (AirPlay LAN swap,
+            // audio switch, background return) reopens it as the sequential origin it turned out to be.
+            options.sequentialOrigin = true
+            options.declaredDurationSeconds = probe.duration
+            loadedOptions.sequentialOrigin = true
+            loadedOptions.declaredDurationSeconds = probe.duration
+            EngineLog.emit(
+                "[AetherEngine] forward-only source with a container duration of "
+                + "\(String(format: "%.1f", probe.duration))s: serving it as a sequential origin",
+                category: .engine
+            )
+        }
         if !probe.isSourceSeekable && !options.isLive {
             if options.sequentialOrigin {
                 if !useSoftwarePath {
@@ -6304,12 +6354,38 @@ public final class AetherEngine: ObservableObject {
               AirPlayPlaylistDecision.routeChangeNeedsReload(
                 isRemoteHLSBypass: loadedOptions.nativeRemoteHLS,
                 bypassServesLoopbackOrigin: remoteHLSSubtitleProxy != nil) else { return }
+        if swapsItemForAirPlayEdge() { return }
         EngineLog.emit("[AirPlay] external playback \(wantAirPlay ? "active (wireless) -> LAN reload" : "ended -> loopback reload")"
                        + (loadedOptions.nativeRemoteHLS ? " (remote-HLS bypass on its #316 subtitle origin)" : ""),
                        category: .engine)
         Task { try? await reloadAtCurrentPosition() }
     }
 
+    /// A sequential origin crosses an AirPlay edge by swapping the item, not by rebuilding the session.
+    /// A rebuild reopens the source, and such a source can only be read again from byte 0: the reload
+    /// resumed at 0 instead of the playhead and then sat seeking while the producer re-read the prefix.
+    /// Nothing about the session has to change for the hop anyway. The server already listens on every
+    /// interface and keeps every segment it cut, so only the address AVPlayer is handed differs (the LAN
+    /// IP and the receiver's playlist, or the loopback again when the receiver lets go).
+    @MainActor
+    private func swapsItemForAirPlayEdge() -> Bool {
+        guard loadedOptions.sequentialOrigin, !loadedOptions.isLive, !loadedOptions.nativeRemoteHLS,
+              let host = nativeHost, let session = nativeVideoSession,
+              let loopback = session.servingMasterPlaylist
+                ? session.masterPlaylistURL : session.mediaPlaylistURL else { return false }
+        let position = currentTime
+        let served = airPlayAdjustedPlayback(url: loopback, session: session)
+        nativeSubtitleRenditionsServed = served.subtitleRenditionsServed
+        EngineLog.emit(
+            "[AirPlay] external playback \(airPlayActive ? "active (wireless)" : "ended") on a sequential "
+            + "origin -> item swap to \(served.url.absoluteString) at \(String(format: "%.2f", position))s "
+            + "(the source cannot be reopened past byte 0)",
+            category: .engine)
+        host.swapItem(url: served.url, startPosition: position)
+        armAirPlayProgressWatchdog(gen: loadGeneration, position: position)
+        return true
+    }
+
     /// Re-read external playback after a session-preserving reload and act on it if it really changed (#227).
     /// The player flag alone is not trustworthy at this instant: the rebuilt item may not have re-engaged the
     /// receiver yet, which would read as "AirPlay ended" and start the next reload of the same loop. The audio
@@ -7104,6 +7180,16 @@ public final class AetherEngine: ObservableObject {
             lifecycleObservers.append(observer)
         }
 
+        #if os(iOS)
+        let routeObserver = nc.addObserver(
+            forName: AVAudioSession.routeChangeNotification,
+            object: AVAudioSession.sharedInstance(), queue: .main
+        ) { [weak self] _ in
+            Task { @MainActor in self?.recomputeAirPlayPictureStaysLocal() }
+        }
+        lifecycleObservers.append(routeObserver)
+        #endif
+
         // Foreign-session interruption handling (Sodalite device-verify 2026-07-15): a live-camera
         // PiP re-claims the audio session on every play() and the system pauses AVPlayer ~10ms after
         // .playing (interruption BEGAN reason=default). The system pause never goes through pause(),
diff --git a/Sources/AetherEngine/Decoder/VideoRoutingPolicy.swift b/Sources/AetherEngine/Decoder/VideoRoutingPolicy.swift
index a08acb2aa..b2453b87e 100644
--- a/Sources/AetherEngine/Decoder/VideoRoutingPolicy.swift
+++ b/Sources/AetherEngine/Decoder/VideoRoutingPolicy.swift
@@ -168,6 +168,32 @@ enum VideoRoutingPolicy {
         }
     }
 
+    /// A URL source that turned out forward-only (the origin ignores `Range` and names no length, so
+    /// the reader could only stream it front to back) is served the way a declared sequential origin
+    /// is, when its container states a duration: native path, one linear pass, seeks unavailable.
+    /// The software path it used to take cannot seek on such a source either, so the promotion costs
+    /// nothing it had, and it buys what only the native path has: hardware decode, AVPlayer's
+    /// buffering, and a picture on an AirPlay receiver (the software host renders on the device,
+    /// only its audio follows the route).
+    ///
+    /// Only when the routing had already chosen native and the host did not ask for software, so
+    /// the promotion never moves a session between hosts on its own. A custom reader is the host's
+    /// to describe. Without a duration the segment plan has nothing to stride over, so that source
+    /// keeps the software path.
+    static func promotesForwardOnlySourceToSequential(
+        isSourceSeekable: Bool,
+        isLive: Bool,
+        declaredSequential: Bool,
+        isCustomSource: Bool,
+        routedSoftware: Bool,
+        preferred: DecodePath,
+        containerDurationSeconds: Double
+    ) -> Bool {
+        !isSourceSeekable && !isLive && !declaredSequential && !isCustomSource
+            && !routedSoftware && preferred == .automatic
+            && containerDurationSeconds.isFinite && containerDurationSeconds > 0
+    }
+
     /// #176 follow-up: DV variants whose only signal is IPT-PQ-c2 (no compatible base layer) cannot be
     /// color-correctly decoded by the software path: libavcodec / dav1d hand the IPT signal on as YCbCr,
     /// which renders with a green/purple cast. That is HEVC P5 and AV1 P10.0 (compat 0). P7 / P8.x /
diff --git a/Tests/AetherEngineTests/ForwardOnlySequentialPromotionTests.swift b/Tests/AetherEngineTests/ForwardOnlySequentialPromotionTests.swift
new file mode 100644
index 000000000..6d0aac6f9
--- /dev/null
+++ b/Tests/AetherEngineTests/ForwardOnlySequentialPromotionTests.swift
@@ -0,0 +1,52 @@
+// A URL source that turned out forward-only used to be forced onto the software host, which cannot
+// seek on it either and whose picture never reaches an AirPlay receiver (only its audio follows the
+// route). When the container states a duration, the engine now serves it as the sequential origin it
+// is. The software host itself still cannot hand a receiver its picture, and `airPlayPictureStaysLocal`
+// says so instead of letting the TV play sound only in silence.
+import Testing
+@testable import AetherEngine
+
+@Suite("Forward-only URL sources are served as sequential origins")
+struct ForwardOnlySequentialPromotionTests {
+
+    private func promotes(seekable: Bool = false, live: Bool = false, declared: Bool = false,
+                          custom: Bool = false, software: Bool = false,
+                          preferred: DecodePath = .automatic, duration: Double = 183.1) -> Bool {
+        VideoRoutingPolicy.promotesForwardOnlySourceToSequential(
+            isSourceSeekable: seekable, isLive: live, declaredSequential: declared,
+            isCustomSource: custom, routedSoftware: software, preferred: preferred,
+            containerDurationSeconds: duration)
+    }
+
+    @Test("a forward-only VOD URL with a container duration is promoted")
+    func promoted() {
+        #expect(promotes())
+    }
+
+    @Test("everything the promotion must leave alone")
+    func leftAlone() {
+        #expect(!promotes(seekable: true), "a seekable source keeps the ordinary native path")
+        #expect(!promotes(live: true), "live is exempt from the forward-only rule already")
+        #expect(!promotes(declared: true), "a host declaration needs no promotion")
+        #expect(!promotes(custom: true), "a custom reader is the host's to describe")
+        #expect(!promotes(software: true), "the promotion never moves a session between hosts")
+        #expect(!promotes(preferred: .software), "a host that asked for software gets software")
+    }
+
+    @Test("no usable duration keeps the software path")
+    func needsDuration() {
+        for duration in [0, -1, .nan, .infinity] as [Double] {
+            #expect(!promotes(duration: duration), "promoted with duration \(duration)")
+        }
+    }
+
+    @Test("only the software host leaves the picture behind on a wireless receiver")
+    func pictureStaysLocal() {
+        #expect(AetherEngine.airPlayPictureStaysLocal(backend: .software, wirelessAirPlayRoute: true))
+        for backend in [PlaybackBackend.native, .audio, .none] {
+            #expect(!AetherEngine.airPlayPictureStaysLocal(backend: backend, wirelessAirPlayRoute: true),
+                    "\(backend) reported a local picture")
+        }
+        #expect(!AetherEngine.airPlayPictureStaysLocal(backend: .software, wirelessAirPlayRoute: false))
+    }
+}
diff --git a/docs/api.md b/docs/api.md
index f718096b3..a8ca3dbfe 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -596,6 +596,7 @@ suppressing `AVPlayerItemLegibleOutput` to keep the measurement running.
 | `$startupProgress` | `StartupProgress?` for a determinate loading bar. |
 | `softwarePathEscalations`, `SoftwarePathEscalationEvent` | A native session AVPlayer refused, rebuilt on the software path, with the failure it absorbed. See [The engine moves a refused session onto the software path](#the-engine-moves-a-refused-session-onto-the-software-path). |
 | `$videoRoute` | `VideoRoute`: which pipeline is actually serving, one of `.none`, `.remoteBypass`, `.loopback`, `.software`, `.audio`. `LoadOptions.nativeRemoteHLS` is only the request; the carriage watchdog, the remembered verdict and the HLS reroutes move a session between routes, mid-session too. Branch on this, above all for who draws subtitles. |
+| `$airPlayPictureStaysLocal` | iOS: true while a wireless AirPlay receiver holds the audio route but the session runs on the software host (VP9, AV1 without hardware decode, deinterlaced MPEG-2 / VC-1 / H.264, `preferredDecodePath = .software`). That host draws into an `AVSampleBufferDisplayLayer`, and only its audio renderer follows the route, so the receiver plays sound only. Nothing fails, which is why the engine says so: show the viewer that this title's picture stays on the device. False on the native paths, where the receiver gets the stream, and everywhere off iOS. |
 | `$audioDelivery` | `AudioDelivery`: how the audio reaches the renderer, one of `.none`, `.noAudioInSource`, `.streamCopy`, `.bridged`, `.decoded`, `.droppedNoPipeline`, `.playerManaged`. `.droppedNoPipeline` is a source that HAS audio playing video-only because no pipeline could be built for it, or because a live bridge decoded nothing (AE#641): the value a fallback ladder demotes on. See [Reading whether the audio was delivered](#reading-whether-the-audio-was-delivered). |
 | `$videoFormat` | The format being presented: `.sdr`, `.hdr10`, `.hdr10Plus`, `.dolbyVision`, `.hlg`. On a platform with no per-mode capability table (macOS), a Dolby Vision session the clamp sent to `.hdr10` is upgraded back to `.dolbyVision` once the item AVFoundation is playing turns out to carry a `dvh1` / `dvhe` sample entry (AE#515). On tvOS the panel term behind it no longer comes from the headroom alone: a session serving an HDR master that AVFoundation has not refused publishes the presented format half a second in, because a display that takes an HDR master is presenting HDR while one that is not refuses in 54 to 61 ms, and `currentEDRHeadroom` has been measured reading 1.00 through exactly that acceptance (AE#459). |
 | `$sourceVideoFormat` | The format the **source** carries, before any panel-driven mapping. The pair is what an honest badge needs: HDR content on an SDR panel differs between the two. |
@@ -975,7 +976,7 @@ All flags default to safe values; the table is the full set. Depth for the media
 | `deinterlaceFieldRate` | `.field` | A `DeinterlaceFieldRate`: the hardware deinterlacer emits one frame per field (25i to 50p) or per frame. The software fallback is always frame rate, because doubling a CPU bwdif is the wrong trade and a fallback should not change cost class. |
 | `probesize`, `maxAnalyzeDuration` | nil | Caller-bounded open-time probe budget (defaults 50 MB / 60 s). They fail **open**: an over-tight budget loads with late-resolving tracks silently missing rather than throwing, so validate track presence if you tighten them. Do not pass `0` for `maxAnalyzeDuration`; FFmpeg maps it to a shorter heuristic. |
 | `forwardBufferSegments` | nil (10, about 40 s) | How far the producer may race ahead and how much the cache keeps resident. Clamped to 4...2700; past the historical 150 the real bound is the session's disk budget, so a "buffer without limit" option can pass `Int.max`. Ignored on `nativeRemoteHLS`. Native HLS retention is readable as `$residentRanges` (see Time). Software VOD uses the same forward-window and volume-budget policy for compressed packet read-ahead; its continuous selected A/V frontier is `bufferedPosition`, not native `residentRanges`. |
-| `sequentialOrigin` | false | Declare an origin that fabricates range answers: one long-lived unranged GET, no ranged probes, non-seekable pb. **Seeking is unavailable**; re-request the archive at a shifted start instead. |
+| `sequentialOrigin` | false | Declare an origin that fabricates range answers: one long-lived unranged GET, no ranged probes, non-seekable pb. **Seeking is unavailable**; re-request the archive at a shifted start instead. A URL source the reader finds forward-only by itself (`Range` ignored and no length, so it can only stream front to back) is served this way without the declaration when its container states a duration; `loadedOptions` then reads `true` with that duration declared, and without a duration it stays on the software path. An AirPlay hop on such a session swaps the item onto the LAN address instead of reopening the source, since a reopen could only start again from byte 0. |
 | `declaredDurationSeconds` | nil | Trusted duration, overriding the container's. Required alongside `sequentialOrigin` on VOD, where the tail read is gone. |
 | `maxConcurrentSourceRequests` | nil | Most requests the reader may have open against this origin at once, across every path it fetches on (pump ranges, detour blocks, size probes, tail prefetch, subtitle side reader). nil counts without capping and lowers the ceiling on its own after a 429/503/509. Set it when the provider states a limit; `1` also switches off the speculative parallel paths, which exist only to overlap with the pump. Counts **requests**, not TCP connections, because over HTTP/2 a session multiplexes every request onto one connection while the origin still counts each one (AE#377). It is also the only ceiling: several engines playing from one origin are bounded by this value and by what the origin refuses, not by a transport pool underneath it (AE#450). |
 | `heldSourceConnection` | false | Ask the source **once** and pull it, instead of ending the connection at the reader's window high water and asking again every 8 to 16 MB of drain (AE#377). For an origin that punishes repeated requests rather than concurrency: some CDNs refuse new requests for minutes at a stretch while serving an already open connection at full rate, and against one of those the request cadence is the defect, at any range size (measured at the reporting origin: 32 MB ranges raised to 256 MB, eight times fewer requests, the refusals unchanged). Where `maxConcurrentSourceRequests` bounds how many requests are in flight, this removes the second request. The read path is the engine's own HTTP/1.1 over a demand-driven stream task, so: **HTTP/1.1 only** (no ALPN, an HTTP/2-only origin is out of scope), the **system proxy configuration does not apply**, and TLS is the OS's through the same host trust decision as every other engine session but has not been exercised against a self-signed origin. A viewer who pauses ends the connection after five seconds and resuming costs one request at the frontier, because a held flow nobody reads is the process-wide Network.framework starvation of AE#310. Applies to the playback reader; the subtitle and enrichment side readers keep the default transport, since they park for minutes at a time. **Names the session**: the transport is chosen at open, so a reload that changes it is refused. |

From bb865b61114660bf8865cbfdeb5a277ebe2813a8 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sun, 27 Sep 2026 17:08:05 +0200
Subject: [PATCH 127/359] fix(hls): a sequential origin serves a resident
 backward target from the cache

Device run 2026-09-27 (iPhone to Apple TV and back): the receiver had
prefetched to seg20, the hop back swapped in a loopback item at 22.8 s and its
first fetch was seg5. The contiguity scan from there stopped at the hole the
cutter left at seg7, called it a gap nothing is producing, and asked for a
restart. A sequential origin refuses every restart, and the refusal published
"Source cannot be repositioned" over a session that had every segment it
needed. Such an origin keeps what it cut and has no restart to offer, so a
resident target is served from the cache.

SequentialBackwardTargetTests replays the device shape: restart requested at
[5] before, none after.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mf4MXgM9bqugHoe5TW4BYf
---
 CHANGELOG.md                                  |  4 ++
 .../Video/VideoSegmentProvider.swift          | 13 ++++++
 .../SequentialLongGOPPlaylistTests.swift      | 41 +++++++++++++++++++
 3 files changed, 58 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3da906838..840a9babf 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -35,6 +35,10 @@ the public-API contract.
   first GOP), and AVPlayer stalled at the end of seg0. Audio now follows the video cut there, as on
   live. The finalize reports are also anchored on the pump's first segment, so a skipped index known
   before seg0 is captured no longer holds back every later one.
+- **A backward jump on a sequential origin is served from the cache.** The residency scan read the
+  holes its cutter leaves as a gap and asked for a restart the origin cannot give, which published
+  "Source cannot be repositioned" over a session that held every segment it needed (an AirPlay hop
+  back to the device, 22 s in).
 
 - **A `FrameExtractor` still carries the colour space playback shows the picture in.** SDR stills
   were tagged sRGB while their pixels are in the source's own primaries and video transfer. They now
diff --git a/Sources/AetherEngine/Video/VideoSegmentProvider.swift b/Sources/AetherEngine/Video/VideoSegmentProvider.swift
index 0169d9477..098149882 100644
--- a/Sources/AetherEngine/Video/VideoSegmentProvider.swift
+++ b/Sources/AetherEngine/Video/VideoSegmentProvider.swift
@@ -1359,6 +1359,19 @@ final class VideoSegmentProvider: HLSSegmentProvider, @unchecked Sendable {
             // Cache gate: backwardWindow=20 covers Continuous-Audio handover refetches (~7-10 segments
             // backward); unconditional proactive restart re-armed the FLAC bridge and caused audible glitches.
             if cache.peekURL(index: index) != nil {
+                // A sequential origin has no restart to offer (its pump can only read from byte 0)
+                // and keeps every segment it cut, so a resident target is served from the cache.
+                // The contiguity scan below would read the plan indices its cutter left as holes
+                // (no URI, never listed) as a gap and hand the refusal a source failure to publish,
+                // which is what an AirPlay hop back to the loopback item did at 22 s in.
+                if sequentialAppendPlaylist {
+                    EngineLog.emit(
+                        "[HLSVideoEngine] declareTarget backward jump \(previousTarget) -> \(index): "
+                        + "resident on a sequential origin, served from the cache",
+                        category: .session
+                    )
+                    return
+                }
                 let frontier = cache.contiguousForwardFrontier(from: index)
                 let front = activeMarchFront
                 if Self.residentBackwardTargetKeepsProducer(
diff --git a/Tests/AetherEngineTests/SequentialLongGOPPlaylistTests.swift b/Tests/AetherEngineTests/SequentialLongGOPPlaylistTests.swift
index dbb59d3e3..0d32ca006 100644
--- a/Tests/AetherEngineTests/SequentialLongGOPPlaylistTests.swift
+++ b/Tests/AetherEngineTests/SequentialLongGOPPlaylistTests.swift
@@ -106,3 +106,44 @@ struct SequentialLongGOPPlaylistTests {
         #expect(frames == 720, "the listed segments carry \(frames) of 720 video frames:\n\(playlist)")
     }
 }
+
+/// Device log 2026-09-27: an AirPlay receiver had prefetched to seg20, the hop back swapped in a
+/// loopback item at 22.8 s, and its first fetch was seg5. The contiguity scan from there read the
+/// hole the cutter left at seg7 as a gap, asked for a restart, and the sequential origin's refusal
+/// published "Source cannot be repositioned" over a session that had every segment it needed.
+@Suite("A sequential origin serves a resident backward target from the cache")
+struct SequentialBackwardTargetTests {
+
+    private final class Recorder: @unchecked Sendable {
+        private let lock = NSLock()
+        private var _indices: [Int] = []
+        func record(_ i: Int) { lock.lock(); _indices.append(i); lock.unlock() }
+        var indices: [Int] { lock.lock(); defer { lock.unlock() }; return _indices }
+    }
+
+    @Test("a backward jump across a cutter hole restarts nothing")
+    func backwardAcrossHoleKeepsProducer() throws {
+        let cache = SegmentCache(forwardWindow: 60, backwardWindow: 60)
+        defer { cache.close() }
+        let recorder = Recorder()
+        let plan = (0..<30).map { i in
+            HLSVideoEngine.Segment(startPts: Int64(i) * 4000, endPts: Int64(i + 1) * 4000,
+                                   startSeconds: Double(i) * 4.0, durationSeconds: 4.0)
+        }
+        let provider = VideoSegmentProvider(
+            cache: cache, segments: plan, codecsString: "avc1.64001F,fLaC", supplementalCodecs: nil,
+            resolution: (1280, 720), videoRange: .sdr, frameRate: 23.976, hdcpLevel: nil,
+            sourceBitrate: 3_000_000, sequentialAppendPlaylist: true,
+            restartHandler: { recorder.record($0) })
+        for i in 0...20 {
+            let hole = i == 1 || i == 7
+            provider.appendSequentialSegmentDuration(index: i, durationSeconds: hole ? 0 : 4)
+            if !hole { cache.store(index: i, data: Data(repeating: 0x5A, count: 8)) }
+        }
+
+        _ = provider.mediaSegmentURL(at: 20)
+        let url = provider.mediaSegmentURL(at: 5)
+        #expect(url != nil)
+        #expect(recorder.indices.isEmpty, "restart requested at \(recorder.indices)")
+    }
+}

From a335be747437c4a4f63aa3b677654f137ed37860 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sun, 27 Sep 2026 17:43:40 +0200
Subject: [PATCH 128/359] chore(release): prep 7.20.0 - forward-only URL
 sources play natively and AirPlay with a picture

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mf4MXgM9bqugHoe5TW4BYf
---
 CHANGELOG.md                                    | 4 ++++
 Examples/README.md                              | 2 +-
 README.md                                       | 6 +++---
 Sources/AetherEngine/AetherEngine+Version.swift | 2 +-
 4 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 840a9babf..db9ec8da8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,10 @@ the public-API contract.
 
 ## [Unreleased]
 
+_Nothing yet._
+
+## [7.20.0] - 2026-09-27
+
 ### Added
 
 - **`airPlayPictureStaysLocal`.** iOS publishes true while a wireless AirPlay receiver holds the audio
diff --git a/Examples/README.md b/Examples/README.md
index b9d830add..d64ec47c6 100644
--- a/Examples/README.md
+++ b/Examples/README.md
@@ -18,7 +18,7 @@ Three samples covering different audiences:
    ```
    https://github.com/superuser404notfound/AetherEngine
    ```
-   Dependency Rule: Up to Next Major Version, starting from `7.19.0`. Add the `AetherEngine` library product to your app target.
+   Dependency Rule: Up to Next Major Version, starting from `7.20.0`. Add the `AetherEngine` library product to your app target.
 
 3. **Drop the file in.** Replace the Xcode template's default `App.swift` (or whatever the generated `@main` file is called) with the contents of [`MinimalPlayerApp.swift`](MinimalPlayer/MinimalPlayerApp.swift). The file is self-contained: it defines both the `@main App` struct and the `ContentView`.
 
diff --git a/README.md b/README.md
index f49ebfa66..e8ebe9ed5 100644
--- a/README.md
+++ b/README.md
@@ -384,7 +384,7 @@ Subtitle cues land in raw source PTS; render the overlay against `player.sourceT
 Install via Swift Package Manager:
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.19.0")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.20.0")
 ```
 
 Three samples ship in `Examples/`:
@@ -631,10 +631,10 @@ Browse all of this as a searchable site at **[aetherengine.superuser404.de](http
 AetherEngine uses [Semantic Versioning](https://semver.org). The public API surface, every `public` declaration in `Sources/AetherEngine/`, is the stability contract. **Major** removes / renames public symbols or breaks adopters; **Minor** adds public API or codec / format support; **Patch** fixes bugs with no public API change. `internal` types are not part of the contract.
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.19.0")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.20.0")
 ```
 
-Pin to `.upToNextMinor(from: "7.19.0")` for stricter teams that prefer to opt into minor bumps explicitly.
+Pin to `.upToNextMinor(from: "7.20.0")` for stricter teams that prefer to opt into minor bumps explicitly.
 
 ## Requirements
 
diff --git a/Sources/AetherEngine/AetherEngine+Version.swift b/Sources/AetherEngine/AetherEngine+Version.swift
index cd16dd4d4..35761b375 100644
--- a/Sources/AetherEngine/AetherEngine+Version.swift
+++ b/Sources/AetherEngine/AetherEngine+Version.swift
@@ -11,5 +11,5 @@ extension AetherEngine {
     ///
     /// Between releases, and in a consumer that pins an unreleased commit for a device test, this
     /// names the last PUBLISHED version the checkout descends from, not every patch in it.
-    public nonisolated static let version = "7.19.0"
+    public nonisolated static let version = "7.20.0"
 }

From e4bab713de19487e8c4396d8ee0c667cc5fc267a Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sun, 27 Sep 2026 18:06:49 +0200
Subject: [PATCH 129/359] fix(native): a reused host publishes paused at item
 handover

unloadCurrentItem invalidates the timeControlStatus observation before it
pauses the AVPlayer, so the pause was never published and the host kept
the outgoing item's `.playing`. The next load on the same engine (an
episode seam, no stop() in between) replayed that value on subscribe,
latched hasTransportRolled, and then published its own pre-roll `.paused`
as a real pause: `loading, playing, paused, playing` within a millisecond,
which a host reads as an external pause and raises its transport over the
next episode. A first load never saw it, because a fresh host starts at
`.paused`.

aetherctl gains `--host-calls reloadnext`, which reloads the URL in place
at t=4 and prints every published state. Before: `playing paused playing`
at the seam. After: `loading playing`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mf4MXgM9bqugHoe5TW4BYf
---
 .../Native/NativeAVPlayerHost.swift           |  4 ++++
 Sources/aetherctl/PlaybackCmd.swift           | 19 +++++++++++++++++--
 Sources/aetherctl/main.swift                  |  2 +-
 docs/cli.md                                   |  2 +-
 4 files changed, 23 insertions(+), 4 deletions(-)

diff --git a/Sources/AetherEngine/Native/NativeAVPlayerHost.swift b/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
index ab4b71253..61e192844 100644
--- a/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
+++ b/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
@@ -2119,6 +2119,10 @@ final class NativeAVPlayerHost {
         renderedTime = 0
         duration = 0
         rate = 0
+        // The observation was invalidated above, so the pause just issued is never published. Left at the
+        // outgoing item's `.playing`, the next session's sink reads a roll on subscribe and then publishes
+        // its own pre-roll `.paused` as a real pause (a host raises its transport on it).
+        timeControlStatus = .paused
         // The AVAudioSession is NOT released here. Teardown ordering is the engine's call, not the host's:
         // AetherEngine.stopInternal deactivates once every render path is quiesced (#215).
     }
diff --git a/Sources/aetherctl/PlaybackCmd.swift b/Sources/aetherctl/PlaybackCmd.swift
index 46559b532..47e9a0bbe 100644
--- a/Sources/aetherctl/PlaybackCmd.swift
+++ b/Sources/aetherctl/PlaybackCmd.swift
@@ -580,6 +580,14 @@ private func playSmokeTest(url: URL, seconds: Double, live: Bool, forceSoftware:
                      failure.kind.rawValue))
     }
     defer { escalationSub.cancel() }
+    // `reloadnext`: every published state, because what a host reacts to at an episode seam is a
+    // transition that lasts a millisecond and never shows up in the once-a-second status line.
+    let stateTraceStart = Date()
+    let stateTrace = hostCalls.contains("reloadnext") ? engine.$state.sink { state in
+        print(String(format: "  STATE %@ t=%.3f", String(describing: state),
+                     Date().timeIntervalSince(stateTraceStart)))
+    } : nil
+    defer { stateTrace?.cancel() }
     // #311: installed BEFORE the load on purpose. The engine holds it and arms the host it builds,
     // which is the documented usage and the part a host would otherwise have to re-do per load.
     let frameProbe = frameTimes ? FrameTimeProbe() : nil
@@ -614,6 +622,13 @@ private func playSmokeTest(url: URL, seconds: Double, live: Bool, forceSoftware:
             liveOptions.dvrWindowSeconds = 1800
             try await engine.load(url: url, options: liveOptions)
         }
+        // The host's episode seam: the next load on the same engine while the first is still playing,
+        // with no stop() in between, so the native host is reused.
+        if hostCalls.contains("reloadnext") {
+            try await Task.sleep(for: .seconds(4))
+            print("  HOSTCALL reload in place")
+            _ = try await engine.load(url: url, startPosition: startPosition, options: options)
+        }
     } catch {
         print("LOAD FAILED: \(error)")
         return 1
@@ -677,7 +692,7 @@ private func playSmokeTest(url: URL, seconds: Double, live: Bool, forceSoftware:
             // exists (the foreground retune's hold-paused policy). Resumed at tick 8.
             print("  HOSTCALL pause() right after load")
             engine.pause()
-        case "reloadlive", "seekback", "overlapseek", "ratehold-tail", "pauseseek", "pausehold", "still", "stallclock", "pausereload", "playreload", "extplayreload":
+        case "reloadlive", "reloadnext", "seekback", "overlapseek", "ratehold-tail", "pauseseek", "pausehold", "still", "stallclock", "pausereload", "playreload", "extplayreload":
             break  // reloadlive handled at load time, seekback/overlapseek/pauseseek in the telemetry loop
         case "nativesubs":
             break  // Sodalite#156, read at load time into LoadOptions.prepareNativeSubtitles
@@ -685,7 +700,7 @@ private func playSmokeTest(url: URL, seconds: Double, live: Bool, forceSoftware:
             || call.hasPrefix("subson") || call.hasPrefix("nativerender"):
             break  // #433 / Sodalite#156, all in the telemetry loop; `@N` picks the tick
         default:
-            print("  HOSTCALL unknown '\(call)' (use play,extractor,setrate,ratehold,pausestart,reloadlive,seekback,seekfar,overlapseek,pauseseek,pausehold,still,stallclock,pausereload,playreload,extplayreload,nativesubs,nativerender,subsoff,subson)")
+            print("  HOSTCALL unknown '\(call)' (use play,extractor,setrate,ratehold,pausestart,reloadlive,reloadnext,seekback,seekfar,overlapseek,pauseseek,pausehold,still,stallclock,pausereload,playreload,extplayreload,nativesubs,nativerender,subsoff,subson)")
         }
     }
     defer { if let frameExtractor { Task { await frameExtractor.shutdown() } } }
diff --git a/Sources/aetherctl/main.swift b/Sources/aetherctl/main.swift
index 60247ece8..4ebac48b5 100644
--- a/Sources/aetherctl/main.swift
+++ b/Sources/aetherctl/main.swift
@@ -79,7 +79,7 @@ func printUsage() {
                  [--drop-audio]
                  [--sequential-origin] [--declared-duration S]
              [--max-concurrent-requests N]
-                     [--audio-stats] [--host-calls play,extractor,setrate,pausestart,reloadlive,seekback,seekfar,pauseseek,pausereload,playreload,extplayreload] <url>
+                     [--audio-stats] [--host-calls play,extractor,setrate,pausestart,reloadlive,seekback,seekfar,pauseseek,pausereload,playreload,extplayreload,reloadnext] <url>
                      (full load+play session smoke test; --subs activates the first
                       matching embedded subtitle track and logs overlay cues;
                       --audio-stats taps decoded PCM and prints per-second audio lead
diff --git a/docs/cli.md b/docs/cli.md
index e0c0e748b..9c5121986 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -140,7 +140,7 @@ the same clock as `FIRSTFRAME`. The 1 Hz tick samples the phase, which is far to
 signal apart from the moment the rate rolls; a healthy native join is exactly two edges, `loading` at the
 load and `playing` at the roll (AE#440).
 
-`--subs <codec-or-lang>` matches against the track's libavcodec name or language and logs every overlay cue and cue trim as it lands. `--host-calls` replays host post-load behavior against the fresh session: `play`, `extractor` (`makeFrameExtractor`), `setrate` (`setRate(1.0)`), `pausestart` (Sodalite#104 round 4: `pause()` the instant load returns, before any frame exists, and `play()` at t=8; the shape of a host that holds a fresh load paused, and a software session used to answer it with eight ticks of `enq=+0 status=unknown r4d=n`, a black picture under a paused clock; now the `[SWHost] #104` lines show the first frame presented at a stopped clock and `startup 8/8 presenting` arrives while paused), `ratehold` (set 1.5, pause at tick 3, resume at tick 5, then read the rate back off the transport itself: the #436 drill, and it fails the run if the resume came back at 1.0), `reloadlive` (reload the URL on the live path when the probe flags it live, the AetherPlayer Open URL flow), `seekback` (rewind 20 s into the DVR window at t=15, return to the live edge at t=30), `overlapseek` (the #292 seek-window drills below), `pausehold` (Sodalite#104: pause at t=10 and HOLD until ten seconds before the end, printing the playhead, the edge and the resident depth every second, which is how a session paused for longer than its own DVR window is measured without waiting out a real one: pair it with `--dvr-window 30` and `--seconds 90` and the ninety minute question becomes a ninety second run), `still` (#544: asks for a scrub still at three aims, 20 s behind the playhead at t=15, 5 s behind at t=20 and at the edge at t=25, writing each to `aetherctl-still-<tick>.png` in the run's private temporary directory (the path is printed) and reporting hit or MISS with the decode time; pair it with `--sw --dvr-window N`, where the picture comes out of the DVR packet ring rather than a segment cache, and read the FILE as well as the count, because the bundled seed burns its own second into the frame so a still asked for 14.85 s showing `14` is the verdict that it decoded the right moment and not merely an image; exit 6 when nothing hit, 5 when the session ended before the first aim; on a VOD session (AE#605) the three aims are 10.5 s behind the playhead, 4.5 s ahead of it and 600 s past it, through `scrubThumbnail`, and the third is EXPECTED to miss, because a frame the cache does not hold yet must not be answered with the one before it: `--sw` against an HTTP source is the software packet-cache case, and the testsrc fixture's counter in the PNG is the verdict that the still decoded to the target rather than snapping to its keyframe), `stallclock` (AE#549: stop the master clock at t=4 behind the host's back, the way an interrupted audio session does, then call a plain `play()` at t=7 and read whether the playhead moves again; the interruption itself cannot be staged on macOS, its outcome can, and without the `RendererClockResume` branch the run ends with the clock standing exactly where the stall left it, which is the field log's shape; the drill drives DEBUG-only engine hooks, so a Release `aetherctl` prints a notice and ends inconclusive, build it with `swift build --product aetherctl`), `pausereload`, `playreload` and `extplayreload` (#623: force the #93/#65 stage-2 item reload at t=10, on a session paused at t=6, on one left playing, and on one paused through the engine at t=6 and resumed at t=8 straight on the `AVPlayer` the way AVKit's transport does, which leaves the engine's intent reading paused while the player runs; the run fails with exit 4 if the clock moves after the paused reload or stands still after either playing one, and before #623 `pausereload` ended `+7.20 s, state=playing`), and `pauseseek` (pause at t=12, seek at t=15 while paused, resume at t=20; with `--sw` the five paused ticks between landing and resume show what the `[SWDiag]` line reports while the pump is parked and has not heard of the seek, the AE#479 shape); this is how the pre-arming `setRate` wedge was isolated.
+`--subs <codec-or-lang>` matches against the track's libavcodec name or language and logs every overlay cue and cue trim as it lands. `--host-calls` replays host post-load behavior against the fresh session: `play`, `extractor` (`makeFrameExtractor`), `setrate` (`setRate(1.0)`), `pausestart` (Sodalite#104 round 4: `pause()` the instant load returns, before any frame exists, and `play()` at t=8; the shape of a host that holds a fresh load paused, and a software session used to answer it with eight ticks of `enq=+0 status=unknown r4d=n`, a black picture under a paused clock; now the `[SWHost] #104` lines show the first frame presented at a stopped clock and `startup 8/8 presenting` arrives while paused), `ratehold` (set 1.5, pause at tick 3, resume at tick 5, then read the rate back off the transport itself: the #436 drill, and it fails the run if the resume came back at 1.0), `reloadlive` (reload the URL on the live path when the probe flags it live, the AetherPlayer Open URL flow), `reloadnext` (a host's episode seam: the same URL loaded again at t=4 on the still-playing engine with no `stop()` in between, so the native host is reused, and every published `state` printed as `STATE <state> t=<s>`; the second load must go `loading`, `playing` with no `paused` between them, which it did not while the reused host still carried the outgoing item's `.playing` status and every host raised its transport over the next episode), `seekback` (rewind 20 s into the DVR window at t=15, return to the live edge at t=30), `overlapseek` (the #292 seek-window drills below), `pausehold` (Sodalite#104: pause at t=10 and HOLD until ten seconds before the end, printing the playhead, the edge and the resident depth every second, which is how a session paused for longer than its own DVR window is measured without waiting out a real one: pair it with `--dvr-window 30` and `--seconds 90` and the ninety minute question becomes a ninety second run), `still` (#544: asks for a scrub still at three aims, 20 s behind the playhead at t=15, 5 s behind at t=20 and at the edge at t=25, writing each to `aetherctl-still-<tick>.png` in the run's private temporary directory (the path is printed) and reporting hit or MISS with the decode time; pair it with `--sw --dvr-window N`, where the picture comes out of the DVR packet ring rather than a segment cache, and read the FILE as well as the count, because the bundled seed burns its own second into the frame so a still asked for 14.85 s showing `14` is the verdict that it decoded the right moment and not merely an image; exit 6 when nothing hit, 5 when the session ended before the first aim; on a VOD session (AE#605) the three aims are 10.5 s behind the playhead, 4.5 s ahead of it and 600 s past it, through `scrubThumbnail`, and the third is EXPECTED to miss, because a frame the cache does not hold yet must not be answered with the one before it: `--sw` against an HTTP source is the software packet-cache case, and the testsrc fixture's counter in the PNG is the verdict that the still decoded to the target rather than snapping to its keyframe), `stallclock` (AE#549: stop the master clock at t=4 behind the host's back, the way an interrupted audio session does, then call a plain `play()` at t=7 and read whether the playhead moves again; the interruption itself cannot be staged on macOS, its outcome can, and without the `RendererClockResume` branch the run ends with the clock standing exactly where the stall left it, which is the field log's shape; the drill drives DEBUG-only engine hooks, so a Release `aetherctl` prints a notice and ends inconclusive, build it with `swift build --product aetherctl`), `pausereload`, `playreload` and `extplayreload` (#623: force the #93/#65 stage-2 item reload at t=10, on a session paused at t=6, on one left playing, and on one paused through the engine at t=6 and resumed at t=8 straight on the `AVPlayer` the way AVKit's transport does, which leaves the engine's intent reading paused while the player runs; the run fails with exit 4 if the clock moves after the paused reload or stands still after either playing one, and before #623 `pausereload` ended `+7.20 s, state=playing`), and `pauseseek` (pause at t=12, seek at t=15 while paused, resume at t=20; with `--sw` the five paused ticks between landing and resume show what the `[SWDiag]` line reports while the pump is parked and has not heard of the seek, the AE#479 shape); this is how the pre-arming `setRate` wedge was isolated.
 
 `--seek-every N` seeks once every N ticks past tick 10, walking `--seek-pattern <abs,abs,...>` if one is given (a short backward hop otherwise), and `--seek-count K` stops after K seeks so a run can be a BURST and then play. Both halves are needed for anything about what a seek sequence leaves behind: the burst puts the store in the state under test, and only the playing half shows what the overlay carries through it. That pairing is what made AE#362's second mechanism reproducible (a hole between a restarted pump and the island the previous run left ahead of it, decoded across and then never re-read).
 

From 036e3b7993f75396f5e9fb2c48df68e275b32af0 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sun, 27 Sep 2026 18:38:16 +0200
Subject: [PATCH 130/359] chore(release): prep 7.20.1 - a reused native host
 publishes no pause at an episode seam

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mf4MXgM9bqugHoe5TW4BYf
---
 CHANGELOG.md                                    | 11 +++++++++++
 Examples/README.md                              |  2 +-
 README.md                                       |  6 +++---
 Sources/AetherEngine/AetherEngine+Version.swift |  2 +-
 4 files changed, 16 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index db9ec8da8..879923f5b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,17 @@ the public-API contract.
 
 _Nothing yet._
 
+## [7.20.1] - 2026-09-27
+
+### Fixed
+
+- **An in-place load on a reused native host no longer publishes a pause at the seam.** The host
+  stopped observing `timeControlStatus` before pausing the outgoing item, so it kept publishing
+  `.playing`; the next load replayed that on subscribe, treated the transport as already rolled, and
+  let its own pre-roll `.paused` through as a real pause (`loading, playing, paused, playing` within a
+  millisecond). A host raising its transport on an external pause showed it over every
+  auto-advanced episode. `aetherctl play --host-calls reloadnext` reproduces the seam (#661).
+
 ## [7.20.0] - 2026-09-27
 
 ### Added
diff --git a/Examples/README.md b/Examples/README.md
index d64ec47c6..caaf209e4 100644
--- a/Examples/README.md
+++ b/Examples/README.md
@@ -18,7 +18,7 @@ Three samples covering different audiences:
    ```
    https://github.com/superuser404notfound/AetherEngine
    ```
-   Dependency Rule: Up to Next Major Version, starting from `7.20.0`. Add the `AetherEngine` library product to your app target.
+   Dependency Rule: Up to Next Major Version, starting from `7.20.1`. Add the `AetherEngine` library product to your app target.
 
 3. **Drop the file in.** Replace the Xcode template's default `App.swift` (or whatever the generated `@main` file is called) with the contents of [`MinimalPlayerApp.swift`](MinimalPlayer/MinimalPlayerApp.swift). The file is self-contained: it defines both the `@main App` struct and the `ContentView`.
 
diff --git a/README.md b/README.md
index e8ebe9ed5..2f2d2c055 100644
--- a/README.md
+++ b/README.md
@@ -384,7 +384,7 @@ Subtitle cues land in raw source PTS; render the overlay against `player.sourceT
 Install via Swift Package Manager:
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.20.0")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.20.1")
 ```
 
 Three samples ship in `Examples/`:
@@ -631,10 +631,10 @@ Browse all of this as a searchable site at **[aetherengine.superuser404.de](http
 AetherEngine uses [Semantic Versioning](https://semver.org). The public API surface, every `public` declaration in `Sources/AetherEngine/`, is the stability contract. **Major** removes / renames public symbols or breaks adopters; **Minor** adds public API or codec / format support; **Patch** fixes bugs with no public API change. `internal` types are not part of the contract.
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.20.0")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.20.1")
 ```
 
-Pin to `.upToNextMinor(from: "7.20.0")` for stricter teams that prefer to opt into minor bumps explicitly.
+Pin to `.upToNextMinor(from: "7.20.1")` for stricter teams that prefer to opt into minor bumps explicitly.
 
 ## Requirements
 
diff --git a/Sources/AetherEngine/AetherEngine+Version.swift b/Sources/AetherEngine/AetherEngine+Version.swift
index 35761b375..5d2ead88a 100644
--- a/Sources/AetherEngine/AetherEngine+Version.swift
+++ b/Sources/AetherEngine/AetherEngine+Version.swift
@@ -11,5 +11,5 @@ extension AetherEngine {
     ///
     /// Between releases, and in a consumer that pins an unreleased commit for a device test, this
     /// names the last PUBLISHED version the checkout descends from, not every patch in it.
-    public nonisolated static let version = "7.20.0"
+    public nonisolated static let version = "7.20.1"
 }

From 1f2da8b210eb3e77592214e4b0297182248b161a Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sun, 27 Sep 2026 19:01:32 +0200
Subject: [PATCH 131/359] feat(api): publish the video and audio stream format
 for a stats panel (AE#658)

Pixel format, bit depth, colour primaries, transfer, matrix, range and profile of the
source video stream now arrive as `sourceVideoStreamFormat` (and on `SourceProbe` as
`videoStreamFormat`), in libav's names with viewer labels alongside. An unspecified
field stays nil instead of reading as BT.709.

`decodedVideoFormat` is what the engine's own decoder produced and the CoreVideo buffer
it was displayed from, republished on change. It is nil on the native routes by
design: AVPlayer decodes there and the frames never pass through the engine.

`TrackInfo` gains `sampleRate`, `bitsPerSample`, `sampleFormat`, `channelLayout` and
`profile`, the last being where DTS:X and TrueHD Atmos show up. `aetherctl probe` and
`aetherctl play` print all of it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mf4MXgM9bqugHoe5TW4BYf
---
 .../AetherEngine/AetherEngine+Loading.swift   |   6 +
 Sources/AetherEngine/AetherEngine+Probe.swift |   5 +-
 Sources/AetherEngine/AetherEngine.swift       |  20 ++
 .../Decoder/HardwareVideoDecoder.swift        |  26 +++
 .../Decoder/SoftwareVideoDecoder.swift        |  32 ++++
 .../Decoder/VideoDecoderTypes.swift           |   2 +
 Sources/AetherEngine/Demuxer/Demuxer.swift    |  21 ++-
 .../Native/SoftwarePlaybackHost.swift         |   6 +
 Sources/AetherEngine/PlayerState.swift        |  28 ++-
 Sources/AetherEngine/VideoStreamFormat.swift  | 173 ++++++++++++++++++
 Sources/aetherctl/PlaybackCmd.swift           |  11 ++
 Sources/aetherctl/Probe.swift                 |   7 +
 .../StreamFormatReportTests.swift             | 111 +++++++++++
 docs/api.md                                   |   6 +-
 14 files changed, 448 insertions(+), 6 deletions(-)
 create mode 100644 Sources/AetherEngine/VideoStreamFormat.swift
 create mode 100644 Tests/AetherEngineTests/StreamFormatReportTests.swift

diff --git a/Sources/AetherEngine/AetherEngine+Loading.swift b/Sources/AetherEngine/AetherEngine+Loading.swift
index f323f8773..ca0986f2f 100644
--- a/Sources/AetherEngine/AetherEngine+Loading.swift
+++ b/Sources/AetherEngine/AetherEngine+Loading.swift
@@ -1843,6 +1843,12 @@ extension AetherEngine {
         host.onFirstHDR10PlusDetected = { [weak self] in
             Task { @MainActor in self?.handleHDR10PlusDetected() }
         }
+        host.onDecodedVideoFormat = { [weak self, weak host] format in
+            Task { @MainActor in
+                guard let self, let host, self.softwareHost === host else { return }
+                self.decodedVideoFormat = format
+            }
+        }
         // SW host provides session-relative edge on each tick; publishLiveWindow is a no-op when liveWindow is nil.
         host.onLiveEdge = { [weak self] edge in
             self?.publishLiveWindow(edgeSessionTime: edge)
diff --git a/Sources/AetherEngine/AetherEngine+Probe.swift b/Sources/AetherEngine/AetherEngine+Probe.swift
index b8a390a2c..6bf174011 100644
--- a/Sources/AetherEngine/AetherEngine+Probe.swift
+++ b/Sources/AetherEngine/AetherEngine+Probe.swift
@@ -317,6 +317,7 @@ extension AetherEngine {
         var width: Int32 = 0
         var height: Int32 = 0
         var dvProfileNum: Int? = nil
+        var streamFormat: VideoStreamFormat? = nil
         let videoIdx = demuxer.videoStreamIndex
         if videoIdx >= 0, let stream = demuxer.stream(at: videoIdx) {
             detectedFormat = Self.detectVideoFormat(stream: stream)
@@ -325,6 +326,7 @@ extension AetherEngine {
             width = stream.pointee.codecpar.pointee.width
             height = stream.pointee.codecpar.pointee.height
             dvProfileNum = Self.dvProfile(stream: stream)
+            streamFormat = VideoStreamFormat(codecpar: stream.pointee.codecpar)
         }
         let codecName: String? = {
             guard detectedCodecID != AV_CODEC_ID_NONE,
@@ -352,7 +354,8 @@ extension AetherEngine {
             audioTracks: demuxer.audioTrackInfos(),
             subtitleTracks: demuxer.subtitleTrackInfos(),
             metadata: demuxer.mediaMetadata(),
-            isLive: isLive
+            isLive: isLive,
+            videoStreamFormat: streamFormat
         )
     }
 
diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index ae8c0537f..8980b7aa7 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -596,6 +596,18 @@ public final class AetherEngine: ObservableObject {
     /// different question (a codec has more than one decoder, and the answer changes with hardware).
     @Published public internal(set) var sourceVideoCodecName: String? = nil
 
+    /// AE#658: the source video stream's pixel format, bit depth, colour description and profile as the
+    /// container and the probe's decoder declared them, nil before load, on sources without video, and on
+    /// the probe-free native HLS bypass. Companion to `decodedVideoFormat`, which is what the engine's own
+    /// decoder actually produced.
+    @Published public internal(set) var sourceVideoStreamFormat: VideoStreamFormat? = nil
+
+    /// AE#658: the format the engine's software decoder produced and the display buffer it went into,
+    /// updated when either changes mid-stream. nil whenever the engine does not decode the picture
+    /// itself, which on the native path is always: AVPlayer decodes there, and its frames never pass
+    /// through the engine, so `sourceVideoStreamFormat` is the only description a host has.
+    @Published public internal(set) var decodedVideoFormat: DecodedVideoFormat? = nil
+
     /// Container libavformat opened ("matroska,webm", "mpegts", "mov,mp4,m4a,3gp,3g2,mj2"), nil before load
     /// and on the native HLS bypass (AVFoundation opens that one, there is no libav context to ask). This is
     /// the container that ARRIVED: on a remux or transcode session it differs from the one the host's library
@@ -3939,6 +3951,8 @@ public final class AetherEngine: ObservableObject {
         sessionObservedDisplayCaps = nil
         sourceVideoFrameRate = nil
         sourceVideoBitrate = 0
+        sourceVideoStreamFormat = nil
+        decodedVideoFormat = nil
         sourceVideoCodecName = nil
         sourceContainerFormat = nil
         sourceVideoWidth = 0
@@ -4002,6 +4016,7 @@ public final class AetherEngine: ObservableObject {
         var detectedDVBLCompatIDNum: Int? = nil
         var detectedRate: Double? = nil
         var detectedVideoBitrate: Int64 = 0
+        var detectedVideoStreamFormat: VideoStreamFormat? = nil
         var detectedDVProfile: Bool = false
         // `dolbyVisionHandling = .baseLayerOnly` resolved against this source: the two halves the
         // format clamp, the criteria request and the software-path guard below all read.
@@ -4153,6 +4168,7 @@ public final class AetherEngine: ObservableObject {
                     sourceVideoPixelAspectRatio = Double(sar.num) / Double(sar.den)
                 }
                 detectedVideoBitrate = probe.declaredBitrate(stream: stream)
+                detectedVideoStreamFormat = VideoStreamFormat(codecpar: stream.pointee.codecpar)
                 lastDetectedVideoCodec = detectedCodecID
             }
             probedAudioTracks = probe.audioTrackInfos()
@@ -4274,6 +4290,7 @@ public final class AetherEngine: ObservableObject {
         sourceDolbyVisionRPUProfile = detectedDVRPUProfile
         sourceVideoFrameRate = detectedRate
         sourceVideoBitrate = detectedVideoBitrate
+        sourceVideoStreamFormat = detectedVideoStreamFormat
         sourceVideoCodecName = detectedCodecID == AV_CODEC_ID_NONE
             ? nil
             : avcodec_get_name(detectedCodecID).map { String(cString: $0) }
@@ -6011,6 +6028,8 @@ public final class AetherEngine: ObservableObject {
         sessionObservedDisplayCaps = nil
         sourceVideoFrameRate = nil
         sourceVideoBitrate = 0
+        sourceVideoStreamFormat = nil
+        decodedVideoFormat = nil
         sourceVideoCodecName = nil
         sourceContainerFormat = nil
         sourceVideoWidth = 0
@@ -6975,6 +6994,7 @@ public final class AetherEngine: ObservableObject {
         // #353: the picture belongs to the session. Left standing, the next source would be laid out
         // against this one's rectangle for as long as it takes its own first frame to arrive.
         softwareDisplaySize = nil
+        decodedVideoFormat = nil
         // #314: same detach on the software path, where the outgoing renderer's decode thread is what
         // can still hand a frame over while the next host comes up.
         softwareHost?.setVideoFrameTimeObserver(nil)
diff --git a/Sources/AetherEngine/Decoder/HardwareVideoDecoder.swift b/Sources/AetherEngine/Decoder/HardwareVideoDecoder.swift
index 603bf34a1..74c76eb2a 100644
--- a/Sources/AetherEngine/Decoder/HardwareVideoDecoder.swift
+++ b/Sources/AetherEngine/Decoder/HardwareVideoDecoder.swift
@@ -25,6 +25,11 @@ final class HardwareVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
     /// mirror SoftwareVideoDecoder.extractHDR10PlusBytes). Flag kept so host wiring stays identical to SW path.
     var onFirstHDR10PlusDetected: (@Sendable () -> Void)?
     var onA53Captions: (@Sendable ([CCDataParser.CCTriplet], Double) -> Void)?
+    var onDecodedFormat: (@Sendable (DecodedVideoFormat) -> Void)?
+    private var streamColor = ColorDescription.unspecified
+    private var streamCodecID = AV_CODEC_ID_NONE
+    private var streamProfile = AV_PROFILE_UNKNOWN
+    private var reportedPixelBufferType: OSType = 0
 
     /// Skip pre-seek RASL frames to avoid the "fast forward" effect; decoded for reference but not delivered.
     /// Guarded by `skipLock` not `lock`: close() holds `lock` across VTDecompressionSessionWaitForAsynchronousFrames,
@@ -162,6 +167,9 @@ final class HardwareVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
         let isHDRTransfer = ColorAttachments.isHDRTransfer(codecpar.pointee.color_trc)
         let use10Bit = bitsPerSample > 8 || isHDRTransfer
 
+        streamColor = ColorDescription(codecpar: codecpar)
+        streamCodecID = codecpar.pointee.codec_id
+        streamProfile = codecpar.pointee.profile
         self.colorPrimaries = ColorAttachments.primaries(codecpar.pointee.color_primaries)
         self.colorTransfer = ColorAttachments.transfer(codecpar.pointee.color_trc)
         self.colorMatrix = ColorAttachments.matrix(codecpar.pointee.color_space)
@@ -413,8 +421,26 @@ final class HardwareVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
             CVBufferRemoveAttachment(imageBuffer, kCVImageBufferPixelAspectRatioKey)
         }
 
+        reportDecodedFormat(imageBuffer)
         onFrame?(imageBuffer, pts, nil)
     }
+
+    /// VideoToolbox decodes straight into the display buffer, so the buffer IS the decoded picture; its
+    /// colour is what this decoder attached, which is the stream's declaration.
+    private func reportDecodedFormat(_ buffer: CVImageBuffer) {
+        guard let onDecodedFormat else { return }
+        let type = CVPixelBufferGetPixelFormatType(buffer)
+        guard type != reportedPixelBufferType else { return }
+        reportedPixelBufferType = type
+        onDecodedFormat(DecodedVideoFormat(
+            frame: VideoStreamFormat(
+                pixelFormat: DecodedVideoFormat.libavPixelFormat(forPixelBufferType: type),
+                declaredBitDepth: 0,
+                color: streamColor,
+                codecID: streamCodecID,
+                profile: streamProfile),
+            pixelBufferFormat: DecodedVideoFormat.fourCC(type)))
+    }
 }
 
 // MARK: - C callback
diff --git a/Sources/AetherEngine/Decoder/SoftwareVideoDecoder.swift b/Sources/AetherEngine/Decoder/SoftwareVideoDecoder.swift
index e332a732d..747d59d91 100644
--- a/Sources/AetherEngine/Decoder/SoftwareVideoDecoder.swift
+++ b/Sources/AetherEngine/Decoder/SoftwareVideoDecoder.swift
@@ -22,6 +22,20 @@ final class SoftwareVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
     var onFirstHDR10PlusDetected: (@Sendable () -> Void)?
     var onA53Captions: (@Sendable ([CCDataParser.CCTriplet], Double) -> Void)?
 
+    /// AE#658: fires (decode thread) on the first displayed frame and whenever the decoded format or the
+    /// display buffer's format changes. Guarded by `lock`, like everything `emit` reads.
+    var onDecodedFormat: (@Sendable (DecodedVideoFormat) -> Void)?
+    private var decodedFormatKey: DecodedFormatKey?
+    private var reportedFormatKey: DecodedFormatKey?
+
+    /// The decoder's own output, taken before a deinterlace graph can rewrite the frame (the hardware
+    /// graph hands `emit` a VideoToolbox surface whose pixel format says nothing about the decode).
+    struct DecodedFormatKey: Equatable {
+        var pixelFormat: Int32
+        var color: ColorDescription
+        var pixelBufferType: OSType = 0
+    }
+
     /// True when the source is >8-bit (HDR10, AV1 HDR).
     private var use10Bit = false
 
@@ -271,6 +285,7 @@ final class SoftwareVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
             // AE#499: fill the fields the VUI left open from the container's declaration BEFORE any
             // consumer reads the frame, for the same reason the timestamp repair below runs here.
             ColorDescription.backfill(frame: f, container: containerColor)
+            decodedFormatKey = DecodedFormatKey(pixelFormat: f.pointee.format, color: ColorDescription(frame: f))
 
             // #407: repair the frame's own timestamp BEFORE anything reads it. A frame that reaches
             // the renderer with no PTS is unschedulable and gets dropped there, so every consumer
@@ -411,6 +426,8 @@ final class SoftwareVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
             pixelBuffer = converted
         }
 
+        reportDecodedFormat(pixelBuffer: pixelBuffer)
+
         let pts = f.pointee.pts
         let cmPTS: CMTime
         if pts != Int64.min {
@@ -560,6 +577,21 @@ final class SoftwareVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
         return out
     }
 
+    private func reportDecodedFormat(pixelBuffer: CVPixelBuffer) {
+        guard let onDecodedFormat, var key = decodedFormatKey else { return }
+        key.pixelBufferType = CVPixelBufferGetPixelFormatType(pixelBuffer)
+        guard key != reportedFormatKey else { return }
+        reportedFormatKey = key
+        onDecodedFormat(DecodedVideoFormat(
+            frame: VideoStreamFormat(
+                pixelFormat: AVPixelFormat(rawValue: key.pixelFormat),
+                declaredBitDepth: 0,
+                color: key.color,
+                codecID: codecContext?.pointee.codec_id ?? AV_CODEC_ID_NONE,
+                profile: codecContext?.pointee.profile ?? AV_PROFILE_UNKNOWN),
+            pixelBufferFormat: DecodedVideoFormat.fourCC(key.pixelBufferType)))
+    }
+
     // MARK: - AVFrame → CVPixelBuffer (sws_scale)
 
     private func convertFrameToPixelBuffer(_ frame: UnsafeMutablePointer<AVFrame>) -> CVPixelBuffer? {
diff --git a/Sources/AetherEngine/Decoder/VideoDecoderTypes.swift b/Sources/AetherEngine/Decoder/VideoDecoderTypes.swift
index f725890fb..a1a87601d 100644
--- a/Sources/AetherEngine/Decoder/VideoDecoderTypes.swift
+++ b/Sources/AetherEngine/Decoder/VideoDecoderTypes.swift
@@ -21,6 +21,8 @@ protocol VideoDecodingPipeline: AnyObject, Sendable {
     /// Only the software decoder produces it; VideoToolbox surfaces no A53 side data (H.264/HEVC
     /// never route through the SW host, so nothing is missed there).
     var onA53Captions: (@Sendable ([CCDataParser.CCTriplet], Double) -> Void)? { get set }
+    /// AE#658: the decoded format and its display buffer, reported on the first frame and on change.
+    var onDecodedFormat: (@Sendable (DecodedVideoFormat) -> Void)? { get set }
     var skipUntilPTS: CMTime? { get set }
 
     /// AE#492: the decoder's current feed epoch. A caller that decides a batch of packets is
diff --git a/Sources/AetherEngine/Demuxer/Demuxer.swift b/Sources/AetherEngine/Demuxer/Demuxer.swift
index 63c200dd2..622225556 100644
--- a/Sources/AetherEngine/Demuxer/Demuxer.swift
+++ b/Sources/AetherEngine/Demuxer/Demuxer.swift
@@ -1313,6 +1313,7 @@ public final class Demuxer: @unchecked Sendable {
         // [Events] format line). Surfaced for LoadOptions.preserveASSMarkup hosts.
         var assHeader: String? = nil
         let codecID = codecpar.pointee.codec_id
+        let isAudio = codecpar.pointee.codec_type == AVMEDIA_TYPE_AUDIO
         if codecID == AV_CODEC_ID_ASS || codecID == AV_CODEC_ID_SSA,
            let extradata = codecpar.pointee.extradata,
            codecpar.pointee.extradata_size > 0 {
@@ -1335,10 +1336,28 @@ public final class Demuxer: @unchecked Sendable {
             isHearingImpaired: isHearingImpaired,
             isCommentary: isCommentary,
             isAtmos: isAtmos,
-            assHeader: assHeader
+            assHeader: assHeader,
+            sampleRate: isAudio ? Int(codecpar.pointee.sample_rate) : 0,
+            bitsPerSample: isAudio ? Int(max(codecpar.pointee.bits_per_raw_sample, 0)) : 0,
+            sampleFormat: isAudio ? Self.sampleFormatName(codecpar.pointee.format) : nil,
+            channelLayout: isAudio ? Self.channelLayoutDescription(&codecpar.pointee.ch_layout) : nil,
+            profile: VideoStreamFormat.profileName(codecID: codecID, profile: codecpar.pointee.profile)
         )
     }
 
+    static func sampleFormatName(_ raw: Int32) -> String? {
+        let fmt = AVSampleFormat(rawValue: raw)
+        guard fmt != AV_SAMPLE_FMT_NONE else { return nil }
+        return av_get_sample_fmt_name(fmt).map { String(cString: $0) }
+    }
+
+    static func channelLayoutDescription(_ layout: UnsafePointer<AVChannelLayout>) -> String? {
+        guard layout.pointee.nb_channels > 0 else { return nil }
+        var buffer = [CChar](repeating: 0, count: 64)
+        guard av_channel_layout_describe(layout, &buffer, buffer.count) > 0 else { return nil }
+        return String(cString: buffer)
+    }
+
     /// The language to publish for a stream. A disc keeps its track languages in its navigation data
     /// rather than in the streams, so an m2ts / VOB demuxed on its own reports every track as
     /// undetermined and no preferred-language selection can match. `discLanguages` (empty for every
diff --git a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
index 19c95984a..0fb460390 100644
--- a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
+++ b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
@@ -93,6 +93,9 @@ final class SoftwarePlaybackHost {
     /// upgrade the published `videoFormat` from `.hdr10` → `.hdr10Plus`.
     nonisolated(unsafe) var onFirstHDR10PlusDetected: (@Sendable () -> Void)?
 
+    /// AE#658: forwarded from the video decoder, off-main.
+    nonisolated(unsafe) var onDecodedVideoFormat: (@Sendable (DecodedVideoFormat) -> Void)?
+
     /// #131: forwarded from the video decoder; decoded-frame A53 cc_data triplets, presentation order.
     nonisolated(unsafe) var onA53Captions: (@Sendable ([CCDataParser.CCTriplet], Double) -> Void)?
 
@@ -863,6 +866,9 @@ final class SoftwarePlaybackHost {
         videoDecoder.onFirstHDR10PlusDetected = { [weak self] in
             self?.onFirstHDR10PlusDetected?()
         }
+        videoDecoder.onDecodedFormat = { [weak self] format in
+            self?.onDecodedVideoFormat?(format)
+        }
         videoDecoder.onA53Captions = { [weak self] triplets, pts in
             self?.onA53Captions?(triplets, pts)
         }
diff --git a/Sources/AetherEngine/PlayerState.swift b/Sources/AetherEngine/PlayerState.swift
index 3c61a8813..5954fba61 100644
--- a/Sources/AetherEngine/PlayerState.swift
+++ b/Sources/AetherEngine/PlayerState.swift
@@ -995,6 +995,9 @@ public struct SourceProbe: Sendable {
     public let isDolbyVision: Bool
     /// Dolby Vision profile number (5, 7, 8, 10) read from the dvcC/dvvC configuration record; nil when not DV.
     public let dvProfile: Int?
+    /// AE#658: pixel format, bit depth, colour description and profile of the video stream; nil when
+    /// the source has no video.
+    public let videoStreamFormat: VideoStreamFormat?
     /// HDR10+ (ST 2094-40) dynamic metadata was SEEN in this source's video.
     ///
     /// Always `false` unless the probe was asked for `.hdr10Plus` (the container carries no such declaration,
@@ -1027,8 +1030,10 @@ public struct SourceProbe: Sendable {
         audioTracks: [TrackInfo],
         subtitleTracks: [TrackInfo],
         metadata: MediaMetadata = MediaMetadata(title: nil, artist: nil, album: nil, artworkData: nil),
-        isLive: Bool = false
+        isLive: Bool = false,
+        videoStreamFormat: VideoStreamFormat? = nil
     ) {
+        self.videoStreamFormat = videoStreamFormat
         self.url = url
         self.durationSeconds = durationSeconds
         self.videoFormat = videoFormat
@@ -1142,7 +1147,26 @@ public struct TrackInfo: Identifiable, Sendable, Equatable {
     /// track. Hosts can avoid presenting overlay controls that cannot affect it.
     public let isNativelyRenderedSubtitle: Bool
 
-    public init(id: Int, name: String, codec: String, language: String?, channels: Int = 0, bitrate: Int64 = 0, isDefault: Bool, isForced: Bool = false, isHearingImpaired: Bool = false, isCommentary: Bool = false, isAtmos: Bool = false, assHeader: String? = nil, isExternal: Bool = false, isNativelyRenderedSubtitle: Bool = false) {
+    /// AE#658, audio only: sample rate in Hz, 0 when undeclared.
+    public let sampleRate: Int
+    /// AE#658, audio only: bits per sample the stream carries (`bits_per_raw_sample`), 0 where the codec
+    /// has no fixed depth (AAC, AC-3, E-AC-3, Opus decode to float and have none to report).
+    public let bitsPerSample: Int
+    /// AE#658, audio only: the decoder's output sample format in libav's names ("fltp", "s32p", "s16"),
+    /// nil when the probe had no decoder for the stream.
+    public let sampleFormat: String?
+    /// AE#658, audio only: the channel layout as libav describes it ("stereo", "5.1(side)", "7.1").
+    public let channelLayout: String?
+    /// AE#658: codec profile as libavcodec names it ("LC", "DTS-HD MA + DTS:X", "Dolby TrueHD + Dolby Atmos"),
+    /// nil when undeclared. This is where DTS:X and TrueHD Atmos show up; `isAtmos` covers E-AC-3 JOC only.
+    public let profile: String?
+
+    public init(id: Int, name: String, codec: String, language: String?, channels: Int = 0, bitrate: Int64 = 0, isDefault: Bool, isForced: Bool = false, isHearingImpaired: Bool = false, isCommentary: Bool = false, isAtmos: Bool = false, assHeader: String? = nil, isExternal: Bool = false, isNativelyRenderedSubtitle: Bool = false, sampleRate: Int = 0, bitsPerSample: Int = 0, sampleFormat: String? = nil, channelLayout: String? = nil, profile: String? = nil) {
+        self.sampleRate = sampleRate
+        self.bitsPerSample = bitsPerSample
+        self.sampleFormat = sampleFormat
+        self.channelLayout = channelLayout
+        self.profile = profile
         self.id = id
         self.name = name
         self.codec = codec
diff --git a/Sources/AetherEngine/VideoStreamFormat.swift b/Sources/AetherEngine/VideoStreamFormat.swift
new file mode 100644
index 000000000..870ba61bc
--- /dev/null
+++ b/Sources/AetherEngine/VideoStreamFormat.swift
@@ -0,0 +1,173 @@
+import Foundation
+import CoreVideo
+import AetherLibavutil
+import AetherLibavcodec
+
+/// AE#658: a video picture's format in FFmpeg's vocabulary, for a host's stats panel.
+///
+/// The raw fields are libav names (`yuv420p10le`, `bt2020`, `smpte2084`, `bt2020nc`, `tv`), nil where
+/// the stream leaves a value unspecified. A gap stays a gap: an untagged source is not reported as
+/// BT.709 here, even though that is what the display layer is handed for it (AE#654). The `…Label`
+/// properties turn them into the names a viewer reads.
+public struct VideoStreamFormat: Sendable, Equatable {
+    public let pixelFormat: String?
+    /// Bits per luma sample, from the pixel format's descriptor (or the stream's declared sample depth
+    /// when the pixel format is unknown).
+    public let bitDepth: Int?
+    public let colorPrimaries: String?
+    public let transfer: String?
+    public let matrix: String?
+    public let range: String?
+    /// Codec profile as libavcodec names it ("Main 10", "High", "Main"), nil when undeclared.
+    public let profile: String?
+
+    public init(pixelFormat: String?, bitDepth: Int?, colorPrimaries: String?, transfer: String?,
+                matrix: String?, range: String?, profile: String?) {
+        self.pixelFormat = pixelFormat
+        self.bitDepth = bitDepth
+        self.colorPrimaries = colorPrimaries
+        self.transfer = transfer
+        self.matrix = matrix
+        self.range = range
+        self.profile = profile
+    }
+
+    init(pixelFormat: AVPixelFormat,
+         declaredBitDepth: Int32,
+         color: ColorDescription,
+         codecID: AVCodecID,
+         profile: Int32) {
+        let pixName = pixelFormat == AV_PIX_FMT_NONE ? nil : av_get_pix_fmt_name(pixelFormat).map { String(cString: $0) }
+        var depth: Int? = nil
+        if pixelFormat != AV_PIX_FMT_NONE, let desc = av_pix_fmt_desc_get(pixelFormat), desc.pointee.nb_components > 0 {
+            depth = Int(desc.pointee.comp.0.depth)
+        } else if declaredBitDepth > 0 {
+            depth = Int(declaredBitDepth)
+        }
+        self.init(
+            pixelFormat: pixName,
+            bitDepth: depth,
+            colorPrimaries: color.primaries == AVCOL_PRI_UNSPECIFIED
+                ? nil : av_color_primaries_name(color.primaries).map { String(cString: $0) },
+            transfer: color.transfer == AVCOL_TRC_UNSPECIFIED
+                ? nil : av_color_transfer_name(color.transfer).map { String(cString: $0) },
+            matrix: color.matrix == AVCOL_SPC_UNSPECIFIED
+                ? nil : av_color_space_name(color.matrix).map { String(cString: $0) },
+            range: color.range == AVCOL_RANGE_UNSPECIFIED
+                ? nil : av_color_range_name(color.range).map { String(cString: $0) },
+            profile: Self.profileName(codecID: codecID, profile: profile))
+    }
+
+    /// What the container and the probe's decoder declared for the stream.
+    init(codecpar: UnsafePointer<AVCodecParameters>) {
+        self.init(
+            pixelFormat: AVPixelFormat(rawValue: codecpar.pointee.format),
+            declaredBitDepth: codecpar.pointee.bits_per_raw_sample,
+            color: ColorDescription(codecpar: codecpar),
+            codecID: codecpar.pointee.codec_id,
+            profile: codecpar.pointee.profile)
+    }
+
+    static func profileName(codecID: AVCodecID, profile: Int32) -> String? {
+        guard profile != AV_PROFILE_UNKNOWN else { return nil }
+        return avcodec_profile_name(codecID, profile).map { String(cString: $0) }
+    }
+
+    public var colorPrimariesLabel: String? { colorPrimaries.map(Self.primariesLabel) }
+    public var transferLabel: String? { transfer.map(Self.transferLabel) }
+    public var matrixLabel: String? { matrix.map(Self.matrixLabel) }
+    public var rangeLabel: String? { range.map(Self.rangeLabel) }
+
+    static func primariesLabel(_ name: String) -> String {
+        switch name {
+        case "bt709": return "BT.709"
+        case "bt2020": return "BT.2020"
+        case "smpte432": return "Display P3"
+        case "smpte431": return "DCI-P3"
+        case "bt470bg": return "BT.601 PAL"
+        case "smpte170m": return "BT.601 NTSC"
+        case "bt470m": return "BT.470 M"
+        case "smpte240m": return "SMPTE 240M"
+        default: return name
+        }
+    }
+
+    static func transferLabel(_ name: String) -> String {
+        switch name {
+        case "bt709": return "BT.709 (SDR)"
+        case "smpte2084": return "PQ (SMPTE ST 2084)"
+        case "arib-std-b67": return "HLG"
+        case "smpte170m", "bt601": return "BT.601 (SDR)"
+        case "bt2020-10", "bt2020-12": return "BT.2020 (SDR)"
+        case "iec61966-2-1": return "sRGB"
+        case "linear": return "Linear"
+        default: return name
+        }
+    }
+
+    static func matrixLabel(_ name: String) -> String {
+        switch name {
+        case "bt709": return "BT.709"
+        case "bt2020nc": return "BT.2020 NCL"
+        case "bt2020c": return "BT.2020 CL"
+        case "bt470bg", "smpte170m": return "BT.601"
+        case "ictcp": return "ICtCp"
+        case "gbr": return "RGB"
+        default: return name
+        }
+    }
+
+    static func rangeLabel(_ name: String) -> String {
+        switch name {
+        case "tv": return "Limited"
+        case "pc": return "Full"
+        default: return name
+        }
+    }
+}
+
+/// AE#658: what the engine's own software decoder produced, as it produced it. Published only on the
+/// software path, because on the native path AVPlayer decodes and the frames never pass through the engine.
+public struct DecodedVideoFormat: Sendable, Equatable {
+    /// The decoded frame: libavcodec's output pixel format and the colour description after the
+    /// container filled the fields the bitstream left open.
+    public let frame: VideoStreamFormat
+    /// The CoreVideo buffer the frame was converted into for display, as its four-character code
+    /// (`420v` = NV12, `x420` = P010).
+    public let pixelBufferFormat: String
+
+    public init(frame: VideoStreamFormat, pixelBufferFormat: String) {
+        self.frame = frame
+        self.pixelBufferFormat = pixelBufferFormat
+    }
+
+    /// The display buffer in the names a viewer reads, "P010 (x420)".
+    public var pixelBufferLabel: String {
+        switch pixelBufferFormat {
+        case "420v": return "NV12 (420v)"
+        case "420f": return "NV12 full range (420f)"
+        case "x420": return "P010 (x420)"
+        case "xf20": return "P010 full range (xf20)"
+        default: return pixelBufferFormat
+        }
+    }
+
+    static func libavPixelFormat(forPixelBufferType type: OSType) -> AVPixelFormat {
+        switch type {
+        case kCVPixelFormatType_420YpCbCr8BiPlanarVideoRange,
+             kCVPixelFormatType_420YpCbCr8BiPlanarFullRange: return AV_PIX_FMT_NV12
+        case kCVPixelFormatType_420YpCbCr10BiPlanarVideoRange,
+             kCVPixelFormatType_420YpCbCr10BiPlanarFullRange: return AV_PIX_FMT_P010LE
+        default: return AV_PIX_FMT_NONE
+        }
+    }
+
+    static func fourCC(_ type: OSType) -> String {
+        let bytes = [UInt8((type >> 24) & 0xFF), UInt8((type >> 16) & 0xFF),
+                     UInt8((type >> 8) & 0xFF), UInt8(type & 0xFF)]
+        if bytes.allSatisfy({ $0 >= 0x20 && $0 < 0x7F }) {
+            return String(decoding: bytes, as: UTF8.self)
+        }
+        return "0x" + String(type, radix: 16)
+    }
+}
diff --git a/Sources/aetherctl/PlaybackCmd.swift b/Sources/aetherctl/PlaybackCmd.swift
index 47e9a0bbe..a9517dc3c 100644
--- a/Sources/aetherctl/PlaybackCmd.swift
+++ b/Sources/aetherctl/PlaybackCmd.swift
@@ -527,6 +527,17 @@ private func playSmokeTest(url: URL, seconds: Double, live: Bool, forceSoftware:
         }
         .store(in: &cancellables)
 
+    // AE#658: what the engine's own decoder produced; silent on the native path, where AVPlayer decodes.
+    engine.$decodedVideoFormat
+        .compactMap { $0 }
+        .removeDuplicates()
+        .sink { d in
+            print("  DECODED \(d.frame.pixelFormat ?? "?") depth=\(d.frame.bitDepth.map(String.init) ?? "?") "
+                  + "primaries=\(d.frame.colorPrimaries ?? "-") transfer=\(d.frame.transfer ?? "-") "
+                  + "matrix=\(d.frame.matrix ?? "-") range=\(d.frame.range ?? "-") -> \(d.pixelBufferLabel)")
+        }
+        .store(in: &cancellables)
+
     let options = LoadOptions(
         suppressDisplayCriteria: true,
         httpHeaders: httpHeaders,
diff --git a/Sources/aetherctl/Probe.swift b/Sources/aetherctl/Probe.swift
index ab9be45ce..7219a5686 100644
--- a/Sources/aetherctl/Probe.swift
+++ b/Sources/aetherctl/Probe.swift
@@ -29,6 +29,11 @@ func runProbe(url: URL, detecting: ProbeDetail = []) -> Int32 {
     print("Duration:    \(duration)s")
     print("Video:       codec=\(codec) resolution=\(res) fps=\(rate)")
     print("  format:    \(probe.videoFormat)")
+    if let f = probe.videoStreamFormat {
+        print("  pixels:    \(f.pixelFormat ?? "-") depth=\(f.bitDepth.map { "\($0)-bit" } ?? "-") profile=\(f.profile ?? "-")")
+        print("  colour:    primaries=\(f.colorPrimariesLabel ?? "-") transfer=\(f.transferLabel ?? "-") "
+              + "matrix=\(f.matrixLabel ?? "-") range=\(f.rangeLabel ?? "-")")
+    }
     if probe.isDolbyVision {
         print("  HDR/DV:    Dolby Vision signaled")
     }
@@ -47,6 +52,8 @@ func runProbe(url: URL, detecting: ProbeDetail = []) -> Int32 {
             let atmos = track.isAtmos ? " [Atmos]" : ""
             let def = track.isDefault ? " (default)" : ""
             print("  [\(track.id)] codec=\(track.codec) channels=\(track.channels) lang=\(lang)\(atmos)\(def)")
+            print("       rate=\(track.sampleRate) Hz bits=\(track.bitsPerSample) fmt=\(track.sampleFormat ?? "-") "
+                  + "layout=\(track.channelLayout ?? "-") profile=\(track.profile ?? "-")")
             print("       title=\(track.name)")
         }
     }
diff --git a/Tests/AetherEngineTests/StreamFormatReportTests.swift b/Tests/AetherEngineTests/StreamFormatReportTests.swift
new file mode 100644
index 000000000..2426b1950
--- /dev/null
+++ b/Tests/AetherEngineTests/StreamFormatReportTests.swift
@@ -0,0 +1,111 @@
+import Testing
+import CoreVideo
+import AetherLibavutil
+import AetherLibavcodec
+@testable import AetherEngine
+
+// AE#658: the stream facts a stats panel shows, in libav's names plus the labels a viewer reads.
+@Suite("Stream format report (AE#658)")
+struct StreamFormatReportTests {
+
+    @Test("HDR10 HEVC reads as 10-bit BT.2020 PQ, Main 10")
+    func hdr10() {
+        let f = VideoStreamFormat(
+            pixelFormat: AV_PIX_FMT_YUV420P10LE, declaredBitDepth: 0,
+            color: ColorDescription(primaries: AVCOL_PRI_BT2020, transfer: AVCOL_TRC_SMPTE2084,
+                                    matrix: AVCOL_SPC_BT2020_NCL, range: AVCOL_RANGE_MPEG),
+            codecID: AV_CODEC_ID_HEVC, profile: AV_PROFILE_HEVC_MAIN_10)
+        #expect(f.pixelFormat == "yuv420p10le")
+        #expect(f.bitDepth == 10)
+        #expect(f.profile == "Main 10")
+        #expect(f.colorPrimariesLabel == "BT.2020")
+        #expect(f.transferLabel == "PQ (SMPTE ST 2084)")
+        #expect(f.matrixLabel == "BT.2020 NCL")
+        #expect(f.rangeLabel == "Limited")
+    }
+
+    @Test("an untagged stream stays untagged instead of reading as BT.709")
+    func untagged() {
+        let f = VideoStreamFormat(
+            pixelFormat: AV_PIX_FMT_YUV420P, declaredBitDepth: 0, color: .unspecified,
+            codecID: AV_CODEC_ID_H264, profile: AV_PROFILE_UNKNOWN)
+        #expect(f.bitDepth == 8)
+        #expect(f.colorPrimaries == nil)
+        #expect(f.transfer == nil)
+        #expect(f.matrix == nil)
+        #expect(f.range == nil)
+        #expect(f.profile == nil)
+    }
+
+    @Test("HLG and full range get their viewer names")
+    func hlgFullRange() {
+        let f = VideoStreamFormat(
+            pixelFormat: AV_PIX_FMT_YUV420P10LE, declaredBitDepth: 0,
+            color: ColorDescription(primaries: AVCOL_PRI_BT2020, transfer: AVCOL_TRC_ARIB_STD_B67,
+                                    matrix: AVCOL_SPC_BT2020_NCL, range: AVCOL_RANGE_JPEG),
+            codecID: AV_CODEC_ID_HEVC, profile: AV_PROFILE_UNKNOWN)
+        #expect(f.transferLabel == "HLG")
+        #expect(f.rangeLabel == "Full")
+    }
+
+    @Test("an unknown pixel format falls back to the declared sample depth")
+    func declaredDepthFallback() {
+        let f = VideoStreamFormat(
+            pixelFormat: AV_PIX_FMT_NONE, declaredBitDepth: 12, color: .unspecified,
+            codecID: AV_CODEC_ID_HEVC, profile: AV_PROFILE_UNKNOWN)
+        #expect(f.pixelFormat == nil)
+        #expect(f.bitDepth == 12)
+    }
+
+    @Test("a name without a label passes through unchanged")
+    func unknownLabels() {
+        #expect(VideoStreamFormat.primariesLabel("film") == "film")
+        #expect(VideoStreamFormat.transferLabel("log100") == "log100")
+    }
+
+    @Test("display buffers read as their four-character codes")
+    func pixelBuffer() {
+        let nv12 = DecodedVideoFormat.fourCC(kCVPixelFormatType_420YpCbCr8BiPlanarVideoRange)
+        let p010 = DecodedVideoFormat.fourCC(kCVPixelFormatType_420YpCbCr10BiPlanarVideoRange)
+        #expect(nv12 == "420v")
+        #expect(p010 == "x420")
+        #expect(DecodedVideoFormat(frame: .init(pixelFormat: nil, bitDepth: nil, colorPrimaries: nil,
+                                                transfer: nil, matrix: nil, range: nil, profile: nil),
+                                   pixelBufferFormat: p010).pixelBufferLabel == "P010 (x420)")
+        #expect(DecodedVideoFormat.fourCC(0x0000_0001) == "0x1")
+    }
+
+    @Test("a VideoToolbox buffer maps back to the libav format it holds")
+    func libavMapping() {
+        #expect(DecodedVideoFormat.libavPixelFormat(
+            forPixelBufferType: kCVPixelFormatType_420YpCbCr8BiPlanarVideoRange) == AV_PIX_FMT_NV12)
+        #expect(DecodedVideoFormat.libavPixelFormat(
+            forPixelBufferType: kCVPixelFormatType_420YpCbCr10BiPlanarVideoRange) == AV_PIX_FMT_P010LE)
+        #expect(DecodedVideoFormat.libavPixelFormat(
+            forPixelBufferType: kCVPixelFormatType_32BGRA) == AV_PIX_FMT_NONE)
+    }
+
+    @Test("DTS:X and TrueHD Atmos surface through the profile name")
+    func immersiveProfiles() {
+        #expect(VideoStreamFormat.profileName(
+            codecID: AV_CODEC_ID_DTS, profile: AV_PROFILE_DTS_HD_MA_X) == "DTS-HD MA + DTS:X")
+        #expect(VideoStreamFormat.profileName(
+            codecID: AV_CODEC_ID_DTS, profile: AV_PROFILE_DTS_HD_MA) == "DTS-HD MA")
+        #expect(VideoStreamFormat.profileName(
+            codecID: AV_CODEC_ID_TRUEHD, profile: AV_PROFILE_TRUEHD_ATMOS) == "Dolby TrueHD + Dolby Atmos")
+        #expect(VideoStreamFormat.profileName(codecID: AV_CODEC_ID_AAC, profile: AV_PROFILE_UNKNOWN) == nil)
+    }
+
+    @Test("sample format and channel layout use libav's names")
+    func audioNames() {
+        #expect(Demuxer.sampleFormatName(AV_SAMPLE_FMT_FLTP.rawValue) == "fltp")
+        #expect(Demuxer.sampleFormatName(AV_SAMPLE_FMT_S32.rawValue) == "s32")
+        #expect(Demuxer.sampleFormatName(AV_SAMPLE_FMT_NONE.rawValue) == nil)
+
+        var layout = AVChannelLayout()
+        av_channel_layout_default(&layout, 6)
+        #expect(Demuxer.channelLayoutDescription(&layout) == "5.1")
+        av_channel_layout_uninit(&layout)
+        #expect(Demuxer.channelLayoutDescription(&layout) == nil)
+    }
+}
diff --git a/docs/api.md b/docs/api.md
index a8ca3dbfe..5304f0340 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -604,6 +604,8 @@ suppressing `AVPlayerItemLegibleOutput` to keep the measurement running.
 | `$dolbyVisionConversion` | A `DolbyVisionConversion?`: the Dolby Vision profile rewrite applied to the served stream, nil when the session serves the source's own profile or no Dolby Vision. `.profile7ToProfile81` is a Profile 7 source played on a display presenting Dolby Vision, where `$videoFormat` reads `.dolbyVision` and `$sourceDVProfile` keeps 7, so a label can say "P7 -> P8.1". The enhancement layer is dropped by that conversion. Set when the loopback session starts, cleared on stop. |
 | `$sourceVideoCodecName` | The source video codec in the libavcodec spelling ("hevc", "h264", "av1"), nil when the source carries no video. The probe-free remote-HLS bypass maps it back from the item's video sample type, so the field answers on every route rather than going quiet on one of them. Not the same question as `$activeVideoDecoder`: a codec has several decoders, and which one runs depends on the hardware. |
 | `$sourceContainerFormat` | The container libavformat opened ("matroska,webm", "mpegts"), nil on the remote-HLS bypass, where AVFoundation opens the source and there is no libav context to ask. This is the container that ARRIVED, which on a remux or transcode session is not the one a host's library metadata describes. |
+| `$sourceVideoStreamFormat` | A `VideoStreamFormat?` (AE#658): the source video stream's `pixelFormat` ("yuv420p10le"), `bitDepth`, `colorPrimaries`, `transfer`, `matrix`, `range` and `profile` ("Main 10"), in libav's names as the container and the probe's decoder declared them. A field the stream leaves unspecified is nil, never a guessed BT.709. `colorPrimariesLabel`, `transferLabel`, `matrixLabel` and `rangeLabel` give the names a viewer reads ("BT.2020", "PQ (SMPTE ST 2084)", "BT.2020 NCL", "Limited"). nil before load, without video, and on the probe-free remote-HLS bypass. |
+| `$decodedVideoFormat` | A `DecodedVideoFormat?` (AE#658): what the engine's own decoder actually produced. `frame` is a `VideoStreamFormat` for the decoded picture (libavcodec's output pixel format, or the libav name of the VideoToolbox buffer on the software host's hardware decoder), `pixelBufferFormat` the CoreVideo buffer it was displayed from (`420v`, `x420`; `pixelBufferLabel` reads "P010 (x420)"). Republished when either changes mid-stream. **nil on every native route**: AVPlayer decodes there and its frames never pass through the engine, so a panel shows `$sourceVideoStreamFormat` and names AVPlayer as the decoder instead of inferring a pixel format it never saw. |
 | `$activeVideoDecoder`, `$activeAudioDecoder` | The decoder names actually in use, for a stats overlay. This is the honest "what is decoding this" surface; `playbackBackend` is not. Show `$activeAudioDecoder`, classify on `$audioDelivery`: a label cannot separate a source without audio from a source whose audio was dropped. |
 | `$metadata` | `MediaMetadata` parsed at load (title / artist / album / cover). |
 | `$mediaChapters`, `$discChapters`, `$discTitles`, `$selectedDiscTitle` | Container chapters, and disc titles / chapters for DVD and Blu-ray ISO sources. |
@@ -986,8 +988,8 @@ All flags default to safe values; the table is the full set. Depth for the media
 
 | Type | Carries |
 | --- | --- |
-| `SourceProbe` | `url`, `durationSeconds`, `videoFormat`, `videoCodecID` / `videoCodecName`, `videoWidth` / `videoHeight`, `videoFrameRate`, `isDolbyVision`, `dvProfile`, `carriesHDR10PlusMetadata`, `audioTracks`, `subtitleTracks`, `metadata`, `isLive`. `carriesHDR10PlusMetadata` is `false` unless the probe was asked for `.hdr10Plus`, and a `false` means "not asked, or not seen inside the budget", never "proven absent". When it is true and the container said HDR10, `videoFormat` reads `.hdr10Plus`; a Dolby Vision source keeps `.dolbyVision` and carries the flag alongside. |
-| `TrackInfo` | `id`, `name`, `codec`, `language`, `channels`, `bitrate`, `isDefault`, `isForced`, `isHearingImpaired`, `isCommentary`, `isAtmos`, `assHeader`, `isExternal`, `isNativelyRenderedSubtitle`. The last one marks a subtitle the playback backend draws itself (a remote-HLS rendition AVFoundation renders), so no cue reaches `subtitleCues` and an overlay control (position, delay, styling) has nothing to act on. |
+| `SourceProbe` | `url`, `durationSeconds`, `videoFormat`, `videoCodecID` / `videoCodecName`, `videoWidth` / `videoHeight`, `videoFrameRate`, `isDolbyVision`, `dvProfile`, `carriesHDR10PlusMetadata`, `audioTracks`, `subtitleTracks`, `metadata`, `isLive`, `videoStreamFormat` (the same `VideoStreamFormat` a session publishes as `$sourceVideoStreamFormat`). `carriesHDR10PlusMetadata` is `false` unless the probe was asked for `.hdr10Plus`, and a `false` means "not asked, or not seen inside the budget", never "proven absent". When it is true and the container said HDR10, `videoFormat` reads `.hdr10Plus`; a Dolby Vision source keeps `.dolbyVision` and carries the flag alongside. |
+| `TrackInfo` | `id`, `name`, `codec`, `language`, `channels`, `bitrate`, `isDefault`, `isForced`, `isHearingImpaired`, `isCommentary`, `isAtmos`, `assHeader`, `isExternal`, `isNativelyRenderedSubtitle`, and for audio `sampleRate`, `bitsPerSample`, `sampleFormat`, `channelLayout`, plus `profile` for every track (AE#658). `bitsPerSample` is 0 where the codec has no fixed depth (AAC, AC-3, E-AC-3 and Opus decode to float); `sampleFormat` is the probe decoder's output in libav's names ("fltp", "s32"); `profile` is libavcodec's profile name and the place DTS:X ("DTS-HD MA + DTS:X") and TrueHD Atmos ("Dolby TrueHD + Dolby Atmos") show up, where `isAtmos` covers E-AC-3 JOC only. `isNativelyRenderedSubtitle` marks a subtitle the playback backend draws itself (a remote-HLS rendition AVFoundation renders), so no cue reaches `subtitleCues` and an overlay control (position, delay, styling) has nothing to act on. |
 | `MediaMetadata` | `title`, `artist`, `album`, `artworkData`, `hasDisplayMetadata`. There is no separate album-artist field: a container's album artist is a fallback the parser folds into `artist`. |
 | `SubtitleCue` | `id`, `startTime`, `endTime`, `body` (a `SubtitleCue.Body`: `.text`, `.richText`, `.image`), `placement`, plus `text` and `isForced` conveniences. |
 | `SubtitleTextRun` | `text`, `color`, `isBold`, `isItalic`, `isUnderlined`, `isStruckThrough`, `fontName`, `fontSize`, `isStyled`. |

From 3606c9eee4455d87286b66624a667202131def4a Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sun, 27 Sep 2026 19:16:18 +0200
Subject: [PATCH 132/359] chore(release): prep 7.21.0 - the stream format a
 stats panel needs, from the engine

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mf4MXgM9bqugHoe5TW4BYf
---
 CHANGELOG.md                                    | 14 ++++++++++++++
 Examples/README.md                              |  2 +-
 README.md                                       |  6 +++---
 Sources/AetherEngine/AetherEngine+Version.swift |  2 +-
 4 files changed, 19 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 879923f5b..0577bb48b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,20 @@ the public-API contract.
 
 _Nothing yet._
 
+## [7.21.0] - 2026-09-27
+
+### Added
+
+- **The stream format a stats panel needs, from the engine (#658).** `sourceVideoStreamFormat` (and
+  `SourceProbe.videoStreamFormat`) is a `VideoStreamFormat`: pixel format, bit depth, colour primaries,
+  transfer, matrix, range and profile in libav's names, with viewer labels alongside ("BT.2020",
+  "PQ (SMPTE ST 2084)", "Limited"). A field the stream leaves unspecified stays nil rather than reading
+  as BT.709. `decodedVideoFormat` is what the engine's own decoder produced and the CoreVideo buffer it
+  was displayed from ("P010 (x420)"), republished on change; it is nil on the native routes, where
+  AVPlayer decodes and no frame passes through the engine. `TrackInfo` gains `sampleRate`,
+  `bitsPerSample`, `sampleFormat`, `channelLayout` and `profile`, the last being where DTS:X and
+  TrueHD Atmos show up. `aetherctl probe` and `aetherctl play` print all of it.
+
 ## [7.20.1] - 2026-09-27
 
 ### Fixed
diff --git a/Examples/README.md b/Examples/README.md
index caaf209e4..389ac5a5a 100644
--- a/Examples/README.md
+++ b/Examples/README.md
@@ -18,7 +18,7 @@ Three samples covering different audiences:
    ```
    https://github.com/superuser404notfound/AetherEngine
    ```
-   Dependency Rule: Up to Next Major Version, starting from `7.20.1`. Add the `AetherEngine` library product to your app target.
+   Dependency Rule: Up to Next Major Version, starting from `7.21.0`. Add the `AetherEngine` library product to your app target.
 
 3. **Drop the file in.** Replace the Xcode template's default `App.swift` (or whatever the generated `@main` file is called) with the contents of [`MinimalPlayerApp.swift`](MinimalPlayer/MinimalPlayerApp.swift). The file is self-contained: it defines both the `@main App` struct and the `ContentView`.
 
diff --git a/README.md b/README.md
index 2f2d2c055..687c315bb 100644
--- a/README.md
+++ b/README.md
@@ -384,7 +384,7 @@ Subtitle cues land in raw source PTS; render the overlay against `player.sourceT
 Install via Swift Package Manager:
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.20.1")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.21.0")
 ```
 
 Three samples ship in `Examples/`:
@@ -631,10 +631,10 @@ Browse all of this as a searchable site at **[aetherengine.superuser404.de](http
 AetherEngine uses [Semantic Versioning](https://semver.org). The public API surface, every `public` declaration in `Sources/AetherEngine/`, is the stability contract. **Major** removes / renames public symbols or breaks adopters; **Minor** adds public API or codec / format support; **Patch** fixes bugs with no public API change. `internal` types are not part of the contract.
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.20.1")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.21.0")
 ```
 
-Pin to `.upToNextMinor(from: "7.20.1")` for stricter teams that prefer to opt into minor bumps explicitly.
+Pin to `.upToNextMinor(from: "7.21.0")` for stricter teams that prefer to opt into minor bumps explicitly.
 
 ## Requirements
 
diff --git a/Sources/AetherEngine/AetherEngine+Version.swift b/Sources/AetherEngine/AetherEngine+Version.swift
index 5d2ead88a..1f6506ef9 100644
--- a/Sources/AetherEngine/AetherEngine+Version.swift
+++ b/Sources/AetherEngine/AetherEngine+Version.swift
@@ -11,5 +11,5 @@ extension AetherEngine {
     ///
     /// Between releases, and in a consumer that pins an unreleased commit for a device test, this
     /// names the last PUBLISHED version the checkout descends from, not every patch in it.
-    public nonisolated static let version = "7.20.1"
+    public nonisolated static let version = "7.21.0"
 }

From 3c0530fa5634a8be524a96d5e6b4658fc511d604 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sun, 27 Sep 2026 21:38:27 +0200
Subject: [PATCH 133/359] fix(audio): a software host keeps a volume set before
 its audio output exists (AE#660)

The engine hands its stored volume to a freshly built host right away,
before load() runs. SoftwarePlaybackHost and AudioPlaybackHost only
forwarded it to their AudioOutput, which load() builds later, so the
write was dropped and every software session started at full volume.
The getter also reported 1.0 in that window.

Both hosts now hold the volume themselves and hand it to each output
they build.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mf4MXgM9bqugHoe5TW4BYf
---
 .../Audio/AudioPlaybackHost.swift             |  8 +--
 .../Native/SoftwarePlaybackHost.swift         |  7 +--
 .../Issue660SoftwareVolumeTests.swift         | 53 +++++++++++++++++++
 3 files changed, 62 insertions(+), 6 deletions(-)
 create mode 100644 Tests/AetherEngineTests/Issue660SoftwareVolumeTests.swift

diff --git a/Sources/AetherEngine/Audio/AudioPlaybackHost.swift b/Sources/AetherEngine/Audio/AudioPlaybackHost.swift
index cff1548fa..1cb47cc6e 100644
--- a/Sources/AetherEngine/Audio/AudioPlaybackHost.swift
+++ b/Sources/AetherEngine/Audio/AudioPlaybackHost.swift
@@ -145,6 +145,7 @@ final class AudioPlaybackHost {
         self.audioDecoder = aDec
         self.audioStreamIndex = resolvedAudioIdx
         self.audioOutput = AudioOutput()
+        self.audioOutput?.volume = volume
 
         if let start = startPosition, start > 0 {
             // #254: same off-main, deadline-bounded reposition the transport seek uses. Also load()'s
@@ -216,6 +217,7 @@ final class AudioPlaybackHost {
     }
 
     var clockRateForTesting: Float? { audioOutput?.rate }
+    var outputVolumeForTesting: Float? { audioOutput?.volume }
     #endif
 
     func pause() {
@@ -320,9 +322,9 @@ final class AudioPlaybackHost {
         isReady = false
     }
 
-    var volume: Float {
-        get { audioOutput?.volume ?? 1.0 }
-        set { audioOutput?.volume = newValue }
+    /// #660: held here, not only on the output, because the engine sets it before `load()` builds one.
+    var volume: Float = 1.0 {
+        didSet { audioOutput?.volume = volume }
     }
 
     // MARK: - Demux loop
diff --git a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
index 0fb460390..1a64784d4 100644
--- a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
+++ b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
@@ -933,6 +933,7 @@ final class SoftwarePlaybackHost {
 
         // AudioOutput owns the AVSampleBufferRenderSynchronizer (master clock). Created unconditionally: video-only previously got no clock (frozen frame, currentTime=0). Layer attached in play() after the engine hangs it in the view hierarchy (attaching free-floating fails FigVideoQueueRemote -12080 on tvOS 26+).
         self.audioOutput = AudioOutput()
+        self.audioOutput?.volume = volume
         self.audioOutput?.setPresentationOffset(seconds: audioDelaySeconds)   // AE#464
 
         // Reset the live feeder state for the new session.
@@ -1620,9 +1621,9 @@ final class SoftwarePlaybackHost {
         isVideoReadyForDisplay = false
     }
 
-    var volume: Float {
-        get { audioOutput?.volume ?? 1.0 }
-        set { audioOutput?.volume = newValue }
+    /// #660: held here, not only on the output, because the engine sets it before `load()` builds one.
+    var volume: Float = 1.0 {
+        didSet { audioOutput?.volume = volume }
     }
 
     // MARK: - Demux loop
diff --git a/Tests/AetherEngineTests/Issue660SoftwareVolumeTests.swift b/Tests/AetherEngineTests/Issue660SoftwareVolumeTests.swift
new file mode 100644
index 000000000..ab1c80459
--- /dev/null
+++ b/Tests/AetherEngineTests/Issue660SoftwareVolumeTests.swift
@@ -0,0 +1,53 @@
+import Testing
+import Foundation
+@testable import AetherEngine
+
+/// #660: the engine hands its stored volume to a host right after building it, before `load()`.
+/// The FFmpeg hosts forwarded that write to an `AudioOutput` that `load()` had not built yet, so it
+/// was dropped and every software session started at full volume. The host now keeps the volume
+/// itself and hands it to each output it builds.
+@Suite("Software hosts keep a volume set before their audio output exists (#660)")
+struct Issue660SoftwareVolumeTests {
+
+    @MainActor
+    @Test("a software host reports the volume it was given before load")
+    func softwareHostKeepsVolumeBeforeLoad() {
+        let host = SoftwarePlaybackHost()
+        host.volume = 0.25
+        #expect(host.volume == 0.25)
+    }
+
+    @MainActor
+    @Test("an audio host reports the volume it was given before load")
+    func audioHostKeepsVolumeBeforeLoad() {
+        let host = AudioPlaybackHost()
+        host.volume = 0.25
+        #expect(host.volume == 0.25)
+    }
+
+    @MainActor
+    @Test("an audio host plays at the volume it was given before load")
+    func audioHostAppliesVolumeOnLoad() async throws {
+        let host = AudioPlaybackHost()
+        host.volume = 0.25
+        let demuxer = Demuxer()
+        try demuxer.open(reader: DataIOReader(data: makeWAV(seconds: 1)))
+        try await host.load(demuxer: demuxer, startPosition: nil, audioSourceStreamIndex: nil)
+        defer { host.stop() }
+        #expect(host.outputVolumeForTesting == 0.25)
+    }
+
+    private func makeWAV(seconds: Double) -> Data {
+        let sampleRate = 48_000, channels = 2
+        let pcm = Data(count: Int(Double(sampleRate) * seconds) * channels * 2)
+        var d = Data()
+        func str(_ s: String) { d.append(s.data(using: .ascii)!) }
+        func u32(_ v: UInt32) { withUnsafeBytes(of: v.littleEndian) { d.append(contentsOf: $0) } }
+        func u16(_ v: UInt16) { withUnsafeBytes(of: v.littleEndian) { d.append(contentsOf: $0) } }
+        str("RIFF"); u32(UInt32(36 + pcm.count)); str("WAVE")
+        str("fmt "); u32(16); u16(1); u16(UInt16(channels)); u32(UInt32(sampleRate))
+        u32(UInt32(sampleRate * channels * 2)); u16(UInt16(channels * 2)); u16(16)
+        str("data"); u32(UInt32(pcm.count)); d.append(pcm)
+        return d
+    }
+}

From 228e8e0f4f92f160e7de0a974863dd6781761311 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sun, 27 Sep 2026 21:42:35 +0200
Subject: [PATCH 134/359] chore(release): prep 7.21.1 - a software session
 keeps the volume the host app set

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mf4MXgM9bqugHoe5TW4BYf
---
 CHANGELOG.md                                    | 10 ++++++++++
 Examples/README.md                              |  2 +-
 README.md                                       |  6 +++---
 Sources/AetherEngine/AetherEngine+Version.swift |  2 +-
 4 files changed, 15 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0577bb48b..31f294586 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,16 @@ the public-API contract.
 
 _Nothing yet._
 
+## [7.21.1] - 2026-09-27
+
+### Fixed
+
+- **A software session keeps the volume the host app set.** The engine applies its stored volume to a
+  new host before `load()`, and `SoftwarePlaybackHost` and `AudioPlaybackHost` forwarded that only to
+  the `AudioOutput` that `load()` builds later, so the write was dropped and every software session
+  started at full volume, with `volume` reading 1.0 until then. Both hosts now hold the volume and
+  hand it to each output they build (#660).
+
 ## [7.21.0] - 2026-09-27
 
 ### Added
diff --git a/Examples/README.md b/Examples/README.md
index 389ac5a5a..17813345c 100644
--- a/Examples/README.md
+++ b/Examples/README.md
@@ -18,7 +18,7 @@ Three samples covering different audiences:
    ```
    https://github.com/superuser404notfound/AetherEngine
    ```
-   Dependency Rule: Up to Next Major Version, starting from `7.21.0`. Add the `AetherEngine` library product to your app target.
+   Dependency Rule: Up to Next Major Version, starting from `7.21.1`. Add the `AetherEngine` library product to your app target.
 
 3. **Drop the file in.** Replace the Xcode template's default `App.swift` (or whatever the generated `@main` file is called) with the contents of [`MinimalPlayerApp.swift`](MinimalPlayer/MinimalPlayerApp.swift). The file is self-contained: it defines both the `@main App` struct and the `ContentView`.
 
diff --git a/README.md b/README.md
index 687c315bb..3577c3fee 100644
--- a/README.md
+++ b/README.md
@@ -384,7 +384,7 @@ Subtitle cues land in raw source PTS; render the overlay against `player.sourceT
 Install via Swift Package Manager:
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.21.0")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.21.1")
 ```
 
 Three samples ship in `Examples/`:
@@ -631,10 +631,10 @@ Browse all of this as a searchable site at **[aetherengine.superuser404.de](http
 AetherEngine uses [Semantic Versioning](https://semver.org). The public API surface, every `public` declaration in `Sources/AetherEngine/`, is the stability contract. **Major** removes / renames public symbols or breaks adopters; **Minor** adds public API or codec / format support; **Patch** fixes bugs with no public API change. `internal` types are not part of the contract.
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.21.0")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.21.1")
 ```
 
-Pin to `.upToNextMinor(from: "7.21.0")` for stricter teams that prefer to opt into minor bumps explicitly.
+Pin to `.upToNextMinor(from: "7.21.1")` for stricter teams that prefer to opt into minor bumps explicitly.
 
 ## Requirements
 
diff --git a/Sources/AetherEngine/AetherEngine+Version.swift b/Sources/AetherEngine/AetherEngine+Version.swift
index 1f6506ef9..7b72551f4 100644
--- a/Sources/AetherEngine/AetherEngine+Version.swift
+++ b/Sources/AetherEngine/AetherEngine+Version.swift
@@ -11,5 +11,5 @@ extension AetherEngine {
     ///
     /// Between releases, and in a consumer that pins an unreleased commit for a device test, this
     /// names the last PUBLISHED version the checkout descends from, not every patch in it.
-    public nonisolated static let version = "7.21.0"
+    public nonisolated static let version = "7.21.1"
 }

From 1a3750f7fbc358977ad8d0d448c2dfdc4ce16d0c Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Mon, 28 Sep 2026 15:30:58 +0200
Subject: [PATCH 135/359] feat(remote-hls): map AVPlayer's item format
 descriptions onto the probe vocabulary

Pure mapping for the nativeRemoteHLS bypass, which runs no libav probe: the
delivered video's dimensions, colour description (CoreMedia names to libav's)
and avcC / hvcC profile, depth and pixel format as a VideoStreamFormat, and
each audio track as a TrackInfo (codec, channels, rate, AAC profile, E-AC-3
JOC from the dec3 record). Synthetic audio ids from 400000.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mf4MXgM9bqugHoe5TW4BYf
---
 .../Native/RemoteHLSStreamDescription.swift   | 296 ++++++++++++++++++
 .../RemoteHLSStreamDescriptionTests.swift     | 264 ++++++++++++++++
 2 files changed, 560 insertions(+)
 create mode 100644 Sources/AetherEngine/Native/RemoteHLSStreamDescription.swift
 create mode 100644 Tests/AetherEngineTests/RemoteHLSStreamDescriptionTests.swift

diff --git a/Sources/AetherEngine/Native/RemoteHLSStreamDescription.swift b/Sources/AetherEngine/Native/RemoteHLSStreamDescription.swift
new file mode 100644
index 000000000..fa842248f
--- /dev/null
+++ b/Sources/AetherEngine/Native/RemoteHLSStreamDescription.swift
@@ -0,0 +1,296 @@
+import Foundation
+import CoreMedia
+import AudioToolbox
+import AetherLibavutil
+import AetherLibavcodec
+
+/// The `nativeRemoteHLS` bypass runs no libav probe, so the fields a stats panel reads (dimensions, colour
+/// description, audio tracks) had no source on it, and a host fell back to metadata of the ORIGINAL file:
+/// a capped 1280x720 H.264 transcode read "3840x2160, Main 10". AVPlayer has already parsed the delivered
+/// stream into its item tracks' format descriptions, so this maps those onto the probe path's vocabulary
+/// (libav names), without a second connection to the origin. Pure so it is unit-testable; the host does
+/// the async track reads.
+enum RemoteHLSStreamDescription {
+
+    /// First id of the audio tracks published on the bypass. Synthetic, like the legible range at
+    /// `RemoteHLSMediaSelection.subtitleTrackIDBase`: there is no AVStream index on this route, and a
+    /// small ordinal would collide with a host's own source stream numbering.
+    static let audioTrackIDBase = 400_000
+
+    // MARK: - Video
+
+    struct Video: Equatable, Sendable {
+        let width: Int32
+        let height: Int32
+        let codecName: String?
+        let format: VideoStreamFormat
+    }
+
+    static func video(from description: CMFormatDescription) -> Video? {
+        guard CMFormatDescriptionGetMediaType(description) == kCMMediaType_Video else { return nil }
+        let subType = CMFormatDescriptionGetMediaSubType(description)
+        let dims = CMVideoFormatDescriptionGetDimensions(description)
+        let ext = CMFormatDescriptionGetExtensions(description) as? [String: Any] ?? [:]
+        return Video(
+            width: dims.width, height: dims.height,
+            codecName: RemoteHLSFormatDetection.codecName(videoSubType: subType),
+            format: videoStreamFormat(extensions: ext))
+    }
+
+    static func videoStreamFormat(extensions ext: [String: Any]) -> VideoStreamFormat {
+        let atoms = ext[kCMFormatDescriptionExtension_SampleDescriptionExtensionAtoms as String] as? [String: Any] ?? [:]
+        let config: CodecConfiguration? =
+            (atoms["avcC"] as? Data).flatMap(avcConfiguration)
+            ?? (atoms["hvcC"] as? Data).flatMap(hevcConfiguration)
+        let declaredDepth = (ext[kCMFormatDescriptionExtension_BitsPerComponent as String] as? NSNumber)?.intValue
+        let range: String?
+        if let full = ext[kCMFormatDescriptionExtension_FullRangeVideo as String] as? Bool {
+            range = full ? "pc" : "tv"
+        } else {
+            range = nil
+        }
+        return VideoStreamFormat(
+            pixelFormat: config?.pixelFormat,
+            bitDepth: config?.bitDepth ?? declaredDepth,
+            colorPrimaries: (ext[kCMFormatDescriptionExtension_ColorPrimaries as String] as? String).map(primariesName),
+            transfer: (ext[kCMFormatDescriptionExtension_TransferFunction as String] as? String).map(transferName),
+            matrix: (ext[kCMFormatDescriptionExtension_YCbCrMatrix as String] as? String).map(matrixName),
+            range: range,
+            profile: config?.profileName)
+    }
+
+    /// CoreMedia's colour names onto libav's. An unknown name passes through: a value CoreMedia adds later
+    /// is still the stream's own declaration, and dropping it would read as "untagged".
+    static func primariesName(_ name: String) -> String { primariesNames[name] ?? name }
+    static func transferName(_ name: String) -> String { transferNames[name] ?? name }
+    static func matrixName(_ name: String) -> String { matrixNames[name] ?? name }
+
+    private static let primariesNames: [String: String] = [
+        kCMFormatDescriptionColorPrimaries_ITU_R_709_2 as String: "bt709",
+        kCMFormatDescriptionColorPrimaries_ITU_R_2020 as String: "bt2020",
+        kCMFormatDescriptionColorPrimaries_EBU_3213 as String: "bt470bg",
+        kCMFormatDescriptionColorPrimaries_SMPTE_C as String: "smpte170m",
+        kCMFormatDescriptionColorPrimaries_P3_D65 as String: "smpte432",
+        kCMFormatDescriptionColorPrimaries_DCI_P3 as String: "smpte431",
+    ]
+
+    private static let transferNames: [String: String] = [
+        kCMFormatDescriptionTransferFunction_ITU_R_709_2 as String: "bt709",
+        kCMFormatDescriptionTransferFunction_SMPTE_ST_2084_PQ as String: "smpte2084",
+        kCMFormatDescriptionTransferFunction_ITU_R_2100_HLG as String: "arib-std-b67",
+        kCMFormatDescriptionTransferFunction_ITU_R_2020 as String: "bt2020-10",
+        kCMFormatDescriptionTransferFunction_SMPTE_240M_1995 as String: "smpte240m",
+        kCMFormatDescriptionTransferFunction_Linear as String: "linear",
+        kCMFormatDescriptionTransferFunction_sRGB as String: "iec61966-2-1",
+    ]
+
+    private static let matrixNames: [String: String] = [
+        kCMFormatDescriptionYCbCrMatrix_ITU_R_709_2 as String: "bt709",
+        kCMFormatDescriptionYCbCrMatrix_ITU_R_601_4 as String: "smpte170m",
+        kCMFormatDescriptionYCbCrMatrix_ITU_R_2020 as String: "bt2020nc",
+        kCMFormatDescriptionYCbCrMatrix_SMPTE_240M_1995 as String: "smpte240m",
+    ]
+
+    /// What a decoder configuration record declares: libav's profile name, and where the record pins
+    /// them, chroma format and luma depth as a libav pixel format.
+    struct CodecConfiguration: Equatable {
+        let profileName: String?
+        let pixelFormat: String?
+        let bitDepth: Int?
+    }
+
+    /// ISO/IEC 14496-15 avcC. The chroma/depth extension exists only for the High family, and there only
+    /// when the muxer wrote it; the lower profiles are 8-bit 4:2:0 by definition, and so is plain High.
+    static func avcConfiguration(_ record: Data) -> CodecConfiguration? {
+        let b = [UInt8](record)
+        guard b.count >= 7, b[0] == 1 else { return nil }
+        let idc = Int32(b[1])
+        let compatibility = b[2]
+        var profile = idc
+        if idc == 66, compatibility & 0x40 != 0 { profile |= 1 << 9 }            // AV_PROFILE_H264_CONSTRAINED
+        if [110, 122, 244].contains(idc), compatibility & 0x10 != 0 { profile |= 1 << 11 }   // _INTRA
+        let highFamily: Set<Int32> = [100, 110, 122, 244, 44, 83, 86, 118, 128, 138, 139, 134, 135]
+
+        var chroma: Int?
+        var depth: Int?
+        if highFamily.contains(idc) {
+            // Skip the SPS and PPS arrays to reach the extension.
+            var i = 5
+            let spsCount = Int(b[i] & 0x1F); i += 1
+            var ok = true
+            for _ in 0..<spsCount {
+                guard i + 2 <= b.count else { ok = false; break }
+                i += 2 + (Int(b[i]) << 8 | Int(b[i + 1]))
+            }
+            if ok, i < b.count {
+                let ppsCount = Int(b[i]); i += 1
+                for _ in 0..<ppsCount {
+                    guard i + 2 <= b.count else { ok = false; break }
+                    i += 2 + (Int(b[i]) << 8 | Int(b[i + 1]))
+                }
+            }
+            if ok, i + 2 <= b.count {
+                chroma = Int(b[i] & 0x03)
+                depth = Int(b[i + 1] & 0x07) + 8
+            } else if idc == 100 {
+                chroma = 1
+                depth = 8
+            }
+        } else {
+            chroma = 1
+            depth = 8
+        }
+        return CodecConfiguration(
+            profileName: VideoStreamFormat.profileName(codecID: AV_CODEC_ID_H264, profile: profile),
+            pixelFormat: pixelFormatName(chroma: chroma, depth: depth),
+            bitDepth: depth)
+    }
+
+    /// ISO/IEC 14496-15 hvcC: general_profile_idc in byte 1, chroma_format_idc in byte 16, luma depth in 17.
+    static func hevcConfiguration(_ record: Data) -> CodecConfiguration? {
+        let b = [UInt8](record)
+        guard b.count >= 23, b[0] == 1 else { return nil }
+        let depth = Int(b[17] & 0x07) + 8
+        return CodecConfiguration(
+            profileName: VideoStreamFormat.profileName(codecID: AV_CODEC_ID_HEVC, profile: Int32(b[1] & 0x1F)),
+            pixelFormat: pixelFormatName(chroma: Int(b[16] & 0x03), depth: depth),
+            bitDepth: depth)
+    }
+
+    /// The pixel format libav's decoder reports for a chroma format and depth, checked against libav's own
+    /// table so a combination it has no name for stays nil instead of becoming a made-up one.
+    static func pixelFormatName(chroma: Int?, depth: Int?) -> String? {
+        guard let chroma, let depth else { return nil }
+        let base: String
+        switch chroma {
+        case 0: base = "gray"
+        case 1: base = "yuv420p"
+        case 2: base = "yuv422p"
+        case 3: base = "yuv444p"
+        default: return nil
+        }
+        let name = depth == 8 ? base : "\(base)\(depth)le"
+        return av_get_pix_fmt(name) == AV_PIX_FMT_NONE ? nil : name
+    }
+
+    // MARK: - Audio
+
+    /// One audio track as AVPlayer built it, reduced to values so the mapping below stays pure.
+    struct AudioReading: Equatable, Sendable {
+        let formatID: AudioFormatID
+        let sampleRate: Double
+        let channels: Int
+        let bitsPerChannel: Int
+        let carriesJOC: Bool
+        let isEnabled: Bool
+        let language: String?
+    }
+
+    static func audioReading(from description: CMFormatDescription, isEnabled: Bool, language: String?) -> AudioReading? {
+        guard CMFormatDescriptionGetMediaType(description) == kCMMediaType_Audio,
+              let asbd = CMAudioFormatDescriptionGetStreamBasicDescription(description)?.pointee else { return nil }
+        var joc = false
+        if asbd.mFormatID == kAudioFormatEnhancedAC3 {
+            var size = 0
+            if let cookie = CMAudioFormatDescriptionGetMagicCookie(description, sizeOut: &size), size > 0 {
+                joc = eac3CarriesJOC(dec3: Data(bytes: cookie, count: size))
+            }
+        }
+        return AudioReading(
+            formatID: asbd.mFormatID,
+            sampleRate: asbd.mSampleRate,
+            channels: Int(asbd.mChannelsPerFrame),
+            bitsPerChannel: Int(asbd.mBitsPerChannel),
+            carriesJOC: joc,
+            isEnabled: isEnabled,
+            language: language)
+    }
+
+    /// ETSI TS 102 366 Annex F dec3: `flag_ec3_extension_type_a` after the substream loop is the JOC
+    /// (Atmos) signal, the same one libav reads into E-AC-3 profile 30. Accepts the bare payload or the
+    /// whole box, since the magic cookie AVFoundation hands back has been seen both ways.
+    static func eac3CarriesJOC(dec3 record: Data) -> Bool {
+        var b = [UInt8](record)
+        if b.count >= 8, Array(b[4..<8]) == Array("dec3".utf8) { b.removeFirst(8) }
+        var reader = BitReader(bytes: b)
+        guard reader.skip(13), let indSubs = reader.read(3) else { return false }
+        for _ in 0...indSubs {
+            // fscod bsid reserved asvc bsmod acmod lfeon reserved
+            guard reader.skip(2 + 5 + 1 + 1 + 3 + 3 + 1 + 3), let depSubs = reader.read(4) else { return false }
+            guard reader.skip(depSubs > 0 ? 9 : 1) else { return false }
+        }
+        guard reader.skip(7), let flag = reader.read(1) else { return false }
+        return flag == 1
+    }
+
+    /// Audio format IDs onto the libavcodec name the probe path publishes, AAC's object type onto its profile.
+    static func audioCodec(formatID: AudioFormatID) -> (name: String, profile: String?) {
+        switch formatID {
+        case kAudioFormatMPEG4AAC:
+            return ("aac", VideoStreamFormat.profileName(codecID: AV_CODEC_ID_AAC, profile: 1))
+        case kAudioFormatMPEG4AAC_HE:
+            return ("aac", VideoStreamFormat.profileName(codecID: AV_CODEC_ID_AAC, profile: 4))
+        case kAudioFormatMPEG4AAC_HE_V2:
+            return ("aac", VideoStreamFormat.profileName(codecID: AV_CODEC_ID_AAC, profile: 28))
+        case kAudioFormatMPEG4AAC_LD: return ("aac", "LD")
+        case kAudioFormatMPEG4AAC_ELD: return ("aac", "ELD")
+        case kAudioFormatAC3: return ("ac3", nil)
+        case kAudioFormatEnhancedAC3: return ("eac3", nil)
+        case kAudioFormatMPEGLayer1: return ("mp1", nil)
+        case kAudioFormatMPEGLayer2: return ("mp2", nil)
+        case kAudioFormatMPEGLayer3: return ("mp3", nil)
+        case kAudioFormatFLAC: return ("flac", nil)
+        case kAudioFormatOpus: return ("opus", nil)
+        case kAudioFormatAppleLossless: return ("alac", nil)
+        case kAudioFormatLinearPCM: return ("pcm", nil)
+        case 0x61632D34: return ("ac4", nil)   // 'ac-4'
+        default:
+            let bytes = [UInt8((formatID >> 24) & 0xFF), UInt8((formatID >> 16) & 0xFF),
+                         UInt8((formatID >> 8) & 0xFF), UInt8(formatID & 0xFF)]
+            return (String(bytes: bytes, encoding: .macOSRoman) ?? "unknown", nil)
+        }
+    }
+
+    /// The published list: one entry per audio track AVPlayer built, ids from `audioTrackIDBase` in item
+    /// order, the enabled one as the active index. Named the way the probe path names an untitled track.
+    static func audioTracks(_ readings: [AudioReading]) -> (tracks: [TrackInfo], activeID: Int?) {
+        var tracks: [TrackInfo] = []
+        var activeID: Int?
+        for (i, reading) in readings.enumerated() {
+            let id = audioTrackIDBase + i
+            let codec = audioCodec(formatID: reading.formatID)
+            let language = reading.language.flatMap { $0.isEmpty || $0 == "und" ? nil : $0 }
+            let name = language.map { "\($0.uppercased()) (\(codec.name))" } ?? "Track \(i + 1) (\(codec.name))"
+            let profile = reading.carriesJOC
+                ? VideoStreamFormat.profileName(codecID: AV_CODEC_ID_EAC3, profile: 30)
+                : codec.profile
+            tracks.append(TrackInfo(
+                id: id, name: name, codec: codec.name, language: language,
+                channels: reading.channels, isDefault: reading.isEnabled, isAtmos: reading.carriesJOC,
+                sampleRate: reading.sampleRate.isFinite ? Int(reading.sampleRate) : 0,
+                bitsPerSample: reading.bitsPerChannel, profile: profile))
+            if reading.isEnabled, activeID == nil { activeID = id }
+        }
+        return (tracks, activeID)
+    }
+
+    private struct BitReader {
+        let bytes: [UInt8]
+        var position = 0
+
+        init(bytes: [UInt8]) { self.bytes = bytes }
+
+        mutating func read(_ count: Int) -> Int? {
+            guard position + count <= bytes.count * 8 else { return nil }
+            var value = 0
+            for _ in 0..<count {
+                let bit = (bytes[position / 8] >> (7 - UInt8(position % 8))) & 1
+                value = value << 1 | Int(bit)
+                position += 1
+            }
+            return value
+        }
+
+        mutating func skip(_ count: Int) -> Bool { read(count) != nil || count == 0 }
+    }
+}
diff --git a/Tests/AetherEngineTests/RemoteHLSStreamDescriptionTests.swift b/Tests/AetherEngineTests/RemoteHLSStreamDescriptionTests.swift
new file mode 100644
index 000000000..d14449672
--- /dev/null
+++ b/Tests/AetherEngineTests/RemoteHLSStreamDescriptionTests.swift
@@ -0,0 +1,264 @@
+import Foundation
+import Testing
+import CoreMedia
+import AudioToolbox
+@testable import AetherEngine
+
+/// The `nativeRemoteHLS` bypass runs no libav probe, so a stats panel had nothing but the host's own
+/// metadata of the ORIGINAL file to show: a capped 1280x720 H.264 transcode read "3840x2160, Main 10".
+/// AVPlayer's parsed item tracks already carry the delivered stream, so these pin the mapping from its
+/// format descriptions onto the fields the probe path publishes, in the probe path's vocabulary.
+@Suite("RemoteHLSStreamDescription")
+struct RemoteHLSStreamDescriptionTests {
+
+    // MARK: - Fixtures
+
+    private static let avc1: FourCharCode = 0x61766331
+    private static let hvc1: FourCharCode = 0x68766331
+
+    /// avcC with no SPS/PPS: version, profile_idc, constraint flags, level, lengthSizeMinusOne, 0 SPS, 0 PPS.
+    private static func avcC(profileIDC: UInt8, compatibility: UInt8 = 0, highExtension: (chroma: UInt8, lumaDepth: UInt8)? = nil) -> Data {
+        var bytes: [UInt8] = [1, profileIDC, compatibility, 31, 0xFF, 0xE0, 0x00]
+        if let ext = highExtension {
+            bytes += [0xFC | ext.chroma, 0xF8 | (ext.lumaDepth - 8), 0xF8 | (ext.lumaDepth - 8), 0x00]
+        }
+        return Data(bytes)
+    }
+
+    /// hvcC header (23 bytes) with no parameter-set arrays.
+    private static func hvcC(profileIDC: UInt8, chroma: UInt8 = 1, lumaDepth: UInt8 = 8) -> Data {
+        var bytes = [UInt8](repeating: 0, count: 23)
+        bytes[0] = 1
+        bytes[1] = profileIDC & 0x1F
+        bytes[12] = 150
+        bytes[16] = 0xFC | chroma
+        bytes[17] = 0xF8 | (lumaDepth - 8)
+        bytes[18] = 0xF8 | (lumaDepth - 8)
+        return Data(bytes)
+    }
+
+    private static func videoDescription(
+        subType: FourCharCode, width: Int32, height: Int32,
+        extensions: [CFString: Any]
+    ) throws -> CMFormatDescription {
+        var desc: CMFormatDescription?
+        let status = CMVideoFormatDescriptionCreate(
+            allocator: kCFAllocatorDefault, codecType: subType, width: width, height: height,
+            extensions: extensions as CFDictionary, formatDescriptionOut: &desc)
+        try #require(status == noErr)
+        return try #require(desc)
+    }
+
+    private static func audioDescription(formatID: AudioFormatID, sampleRate: Double, channels: UInt32,
+                                         bitsPerChannel: UInt32 = 0, cookie: Data? = nil) throws -> CMFormatDescription {
+        var asbd = AudioStreamBasicDescription(
+            mSampleRate: sampleRate, mFormatID: formatID, mFormatFlags: 0, mBytesPerPacket: 0,
+            mFramesPerPacket: 1536, mBytesPerFrame: 0, mChannelsPerFrame: channels,
+            mBitsPerChannel: bitsPerChannel, mReserved: 0)
+        var desc: CMFormatDescription?
+        let status: OSStatus
+        if let cookie {
+            status = cookie.withUnsafeBytes { raw in
+                CMAudioFormatDescriptionCreate(
+                    allocator: kCFAllocatorDefault, asbd: &asbd, layoutSize: 0, layout: nil,
+                    magicCookieSize: cookie.count, magicCookie: raw.baseAddress, extensions: nil,
+                    formatDescriptionOut: &desc)
+            }
+        } else {
+            status = CMAudioFormatDescriptionCreate(
+                allocator: kCFAllocatorDefault, asbd: &asbd, layoutSize: 0, layout: nil,
+                magicCookieSize: 0, magicCookie: nil, extensions: nil, formatDescriptionOut: &desc)
+        }
+        try #require(status == noErr)
+        return try #require(desc)
+    }
+
+    /// dec3 payload for one independent substream without dependents, JOC flag as given.
+    private static func dec3(joc: Bool) -> Data {
+        // data_rate(13)=640 num_ind_sub(3)=0 | fscod bsid reserved asvc bsmod acmod lfeon reserved
+        // num_dep_sub(4)=0 reserved(1) | reserved(7) flag_ec3_extension_type_a(1) | complexity_index(8)
+        Data([0x50, 0x00, 0x20, 0x0F, 0x00, joc ? 0x01 : 0x00, joc ? 16 : 0])
+    }
+
+    // MARK: - Delivered video
+
+    @Test("the device case: a 720p H.264 High transcode reads as what was delivered")
+    func deliveredH264Transcode() throws {
+        let desc = try Self.videoDescription(
+            subType: Self.avc1, width: 1280, height: 720,
+            extensions: [
+                kCMFormatDescriptionExtension_ColorPrimaries: kCMFormatDescriptionColorPrimaries_ITU_R_709_2,
+                kCMFormatDescriptionExtension_TransferFunction: kCMFormatDescriptionTransferFunction_ITU_R_709_2,
+                kCMFormatDescriptionExtension_YCbCrMatrix: kCMFormatDescriptionYCbCrMatrix_ITU_R_709_2,
+                kCMFormatDescriptionExtension_FullRangeVideo: false,
+                kCMFormatDescriptionExtension_SampleDescriptionExtensionAtoms: ["avcC": Self.avcC(profileIDC: 100)],
+            ])
+        let video = try #require(RemoteHLSStreamDescription.video(from: desc))
+        #expect(video.width == 1280)
+        #expect(video.height == 720)
+        #expect(video.codecName == "h264")
+        #expect(video.format == VideoStreamFormat(
+            pixelFormat: "yuv420p", bitDepth: 8, colorPrimaries: "bt709", transfer: "bt709",
+            matrix: "bt709", range: "tv", profile: "High"))
+    }
+
+    @Test("HEVC Main 10 PQ reads its profile, depth and BT.2020 description from hvcC and the extensions")
+    func hevcMain10PQ() throws {
+        let desc = try Self.videoDescription(
+            subType: Self.hvc1, width: 3840, height: 2160,
+            extensions: [
+                kCMFormatDescriptionExtension_ColorPrimaries: kCMFormatDescriptionColorPrimaries_ITU_R_2020,
+                kCMFormatDescriptionExtension_TransferFunction: kCMFormatDescriptionTransferFunction_SMPTE_ST_2084_PQ,
+                kCMFormatDescriptionExtension_YCbCrMatrix: kCMFormatDescriptionYCbCrMatrix_ITU_R_2020,
+                kCMFormatDescriptionExtension_SampleDescriptionExtensionAtoms: ["hvcC": Self.hvcC(profileIDC: 2, lumaDepth: 10)],
+            ])
+        let video = try #require(RemoteHLSStreamDescription.video(from: desc))
+        #expect(video.codecName == "hevc")
+        #expect(video.format.pixelFormat == "yuv420p10le")
+        #expect(video.format.bitDepth == 10)
+        #expect(video.format.profile == "Main 10")
+        #expect(video.format.colorPrimaries == "bt2020")
+        #expect(video.format.transfer == "smpte2084")
+        #expect(video.format.matrix == "bt2020nc")
+        #expect(video.format.range == nil)
+    }
+
+    /// Same rule as AE#658 on the probe path: an untagged stream is not reported as BT.709.
+    @Test("an untagged stream keeps its gaps")
+    func untaggedStaysNil() throws {
+        let desc = try Self.videoDescription(subType: Self.avc1, width: 640, height: 360, extensions: [:])
+        let video = try #require(RemoteHLSStreamDescription.video(from: desc))
+        #expect(video.format.colorPrimaries == nil)
+        #expect(video.format.transfer == nil)
+        #expect(video.format.matrix == nil)
+        #expect(video.format.range == nil)
+        #expect(video.format.profile == nil)
+        #expect(video.format.pixelFormat == nil)
+        #expect(video.format.bitDepth == nil)
+    }
+
+    @Test("CoreMedia colour names map onto libav's")
+    func colourNames() {
+        #expect(RemoteHLSStreamDescription.primariesName(kCMFormatDescriptionColorPrimaries_P3_D65 as String) == "smpte432")
+        #expect(RemoteHLSStreamDescription.primariesName(kCMFormatDescriptionColorPrimaries_DCI_P3 as String) == "smpte431")
+        #expect(RemoteHLSStreamDescription.primariesName(kCMFormatDescriptionColorPrimaries_EBU_3213 as String) == "bt470bg")
+        #expect(RemoteHLSStreamDescription.primariesName(kCMFormatDescriptionColorPrimaries_SMPTE_C as String) == "smpte170m")
+        #expect(RemoteHLSStreamDescription.transferName(kCMFormatDescriptionTransferFunction_ITU_R_2100_HLG as String) == "arib-std-b67")
+        #expect(RemoteHLSStreamDescription.transferName(kCMFormatDescriptionTransferFunction_ITU_R_2020 as String) == "bt2020-10")
+        #expect(RemoteHLSStreamDescription.transferName(kCMFormatDescriptionTransferFunction_Linear as String) == "linear")
+        #expect(RemoteHLSStreamDescription.transferName(kCMFormatDescriptionTransferFunction_sRGB as String) == "iec61966-2-1")
+        #expect(RemoteHLSStreamDescription.matrixName(kCMFormatDescriptionYCbCrMatrix_ITU_R_601_4 as String) == "smpte170m")
+        #expect(RemoteHLSStreamDescription.matrixName(kCMFormatDescriptionYCbCrMatrix_SMPTE_240M_1995 as String) == "smpte240m")
+        // A name CoreMedia adds later passes through rather than vanishing.
+        #expect(RemoteHLSStreamDescription.primariesName("Future_Primaries") == "Future_Primaries")
+    }
+
+    @Test("constraint flags in avcC reach the profile name")
+    func constrainedBaseline() {
+        let config = RemoteHLSStreamDescription.avcConfiguration(Self.avcC(profileIDC: 66, compatibility: 0x40))
+        #expect(config?.profileName == "Constrained Baseline")
+        let high10 = RemoteHLSStreamDescription.avcConfiguration(
+            Self.avcC(profileIDC: 110, highExtension: (chroma: 1, lumaDepth: 10)))
+        #expect(high10?.profileName == "High 10")
+        #expect(high10?.pixelFormat == "yuv420p10le")
+        #expect(high10?.bitDepth == 10)
+    }
+
+    @Test("a truncated configuration record yields nothing rather than a guess")
+    func truncatedRecords() {
+        #expect(RemoteHLSStreamDescription.avcConfiguration(Data([1, 100])) == nil)
+        #expect(RemoteHLSStreamDescription.hevcConfiguration(Data([1, 2, 0, 0])) == nil)
+    }
+
+    @Test("an audio description is not a video one")
+    func audioIsNotVideo() throws {
+        let desc = try Self.audioDescription(formatID: kAudioFormatEnhancedAC3, sampleRate: 48_000, channels: 6)
+        #expect(RemoteHLSStreamDescription.video(from: desc) == nil)
+    }
+
+    // MARK: - Audio tracks
+
+    @Test("the device case: E-AC-3 5.1 at 48 kHz becomes an eac3 TrackInfo")
+    func eac3Track() throws {
+        let desc = try Self.audioDescription(formatID: kAudioFormatEnhancedAC3, sampleRate: 48_000, channels: 6)
+        let reading = try #require(RemoteHLSStreamDescription.audioReading(from: desc, isEnabled: true, language: "eng"))
+        let (tracks, active) = RemoteHLSStreamDescription.audioTracks([reading])
+        let track = try #require(tracks.first)
+        #expect(tracks.count == 1)
+        #expect(track.id == RemoteHLSStreamDescription.audioTrackIDBase)
+        #expect(active == track.id)
+        #expect(track.codec == "eac3")
+        #expect(track.channels == 6)
+        #expect(track.sampleRate == 48_000)
+        #expect(track.bitsPerSample == 0)
+        #expect(track.language == "eng")
+        #expect(track.name == "ENG (eac3)")
+        #expect(track.isAtmos == false)
+        #expect(track.isDefault)
+    }
+
+    @Test("a dec3 cookie announcing JOC marks the track Atmos, as a box or as its payload")
+    func eac3JOC() throws {
+        let payload = Self.dec3(joc: true)
+        var box = Data([0, 0, 0, UInt8(8 + payload.count)])
+        box.append(contentsOf: Array("dec3".utf8))
+        box.append(payload)
+        for cookie in [payload, box] {
+            let desc = try Self.audioDescription(
+                formatID: kAudioFormatEnhancedAC3, sampleRate: 48_000, channels: 6, cookie: cookie)
+            let reading = try #require(RemoteHLSStreamDescription.audioReading(from: desc, isEnabled: true, language: nil))
+            let track = try #require(RemoteHLSStreamDescription.audioTracks([reading]).tracks.first)
+            #expect(track.isAtmos)
+            #expect(track.profile == "Dolby Digital Plus + Dolby Atmos")
+        }
+        #expect(RemoteHLSStreamDescription.eac3CarriesJOC(dec3: Self.dec3(joc: false)) == false)
+        #expect(RemoteHLSStreamDescription.eac3CarriesJOC(dec3: Data([0x50])) == false)
+    }
+
+    @Test("audio format IDs map onto libavcodec names, AAC with its profile")
+    func audioCodecNames() {
+        #expect(RemoteHLSStreamDescription.audioCodec(formatID: kAudioFormatMPEG4AAC).name == "aac")
+        #expect(RemoteHLSStreamDescription.audioCodec(formatID: kAudioFormatMPEG4AAC).profile == "LC")
+        #expect(RemoteHLSStreamDescription.audioCodec(formatID: kAudioFormatMPEG4AAC_HE).profile == "HE-AAC")
+        #expect(RemoteHLSStreamDescription.audioCodec(formatID: kAudioFormatMPEG4AAC_HE_V2).profile == "HE-AACv2")
+        #expect(RemoteHLSStreamDescription.audioCodec(formatID: kAudioFormatAC3).name == "ac3")
+        #expect(RemoteHLSStreamDescription.audioCodec(formatID: kAudioFormatEnhancedAC3).name == "eac3")
+        #expect(RemoteHLSStreamDescription.audioCodec(formatID: kAudioFormatMPEGLayer3).name == "mp3")
+        #expect(RemoteHLSStreamDescription.audioCodec(formatID: kAudioFormatFLAC).name == "flac")
+        #expect(RemoteHLSStreamDescription.audioCodec(formatID: kAudioFormatOpus).name == "opus")
+        #expect(RemoteHLSStreamDescription.audioCodec(formatID: kAudioFormatAppleLossless).name == "alac")
+        // An unmapped format still names itself, like the video side.
+        #expect(RemoteHLSStreamDescription.audioCodec(formatID: 0x7A7A7A7A).name == "zzzz")
+    }
+
+    @Test("ids are synthetic and ordinal, the enabled track is the active one, und is no language")
+    func multipleTracks() throws {
+        let a = try Self.audioDescription(formatID: kAudioFormatMPEG4AAC, sampleRate: 44_100, channels: 2)
+        let b = try Self.audioDescription(formatID: kAudioFormatAC3, sampleRate: 48_000, channels: 6)
+        let readings = [
+            try #require(RemoteHLSStreamDescription.audioReading(from: a, isEnabled: false, language: "und")),
+            try #require(RemoteHLSStreamDescription.audioReading(from: b, isEnabled: true, language: "deu")),
+        ]
+        let (tracks, active) = RemoteHLSStreamDescription.audioTracks(readings)
+        #expect(tracks.map(\.id) == [RemoteHLSStreamDescription.audioTrackIDBase, RemoteHLSStreamDescription.audioTrackIDBase + 1])
+        #expect(active == RemoteHLSStreamDescription.audioTrackIDBase + 1)
+        #expect(tracks[0].language == nil)
+        #expect(tracks[0].name == "Track 1 (aac)")
+        #expect(tracks[0].isDefault == false)
+        #expect(tracks[1].name == "DEU (ac3)")
+    }
+
+    @Test("no enabled track means no active index")
+    func nothingEnabled() throws {
+        let a = try Self.audioDescription(formatID: kAudioFormatMPEG4AAC, sampleRate: 48_000, channels: 2)
+        let reading = try #require(RemoteHLSStreamDescription.audioReading(from: a, isEnabled: false, language: nil))
+        #expect(RemoteHLSStreamDescription.audioTracks([reading]).activeID == nil)
+        #expect(RemoteHLSStreamDescription.audioTracks([]).tracks.isEmpty)
+    }
+
+    @Test("a video description is not an audio one")
+    func videoIsNotAudio() throws {
+        let desc = try Self.videoDescription(subType: Self.avc1, width: 16, height: 16, extensions: [:])
+        #expect(RemoteHLSStreamDescription.audioReading(from: desc, isEnabled: true, language: nil) == nil)
+    }
+}

From 5466b8e6acb66200efc56316bd1a8b732518fce4 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Mon, 28 Sep 2026 15:30:58 +0200
Subject: [PATCH 136/359] feat(telemetry): meter bitrates from AVPlayer's
 transfer on the remote-HLS bypass

The bypass has no demuxer, so both bitrate fields come from the access log's
session transfer total through TransferRateMeter (same 10 s window and
active-seconds average as the demuxer meter). The producer A/V gap and the
#169 tail-park synthesis stay with the loopback route.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mf4MXgM9bqugHoe5TW4BYf
---
 .../Diagnostics/LiveTelemetry.swift           |  5 +-
 .../Diagnostics/LiveTelemetrySampler.swift    | 82 ++++++++++++++++--
 .../RemoteHLSTelemetryTests.swift             | 85 +++++++++++++++++++
 3 files changed, 166 insertions(+), 6 deletions(-)
 create mode 100644 Tests/AetherEngineTests/RemoteHLSTelemetryTests.swift

diff --git a/Sources/AetherEngine/Diagnostics/LiveTelemetry.swift b/Sources/AetherEngine/Diagnostics/LiveTelemetry.swift
index a075d5783..953595c3f 100644
--- a/Sources/AetherEngine/Diagnostics/LiveTelemetry.swift
+++ b/Sources/AetherEngine/Diagnostics/LiveTelemetry.swift
@@ -9,9 +9,12 @@ import Foundation
 /// interpret a sub-second decoded queue as the size of the compressed packet cache.
 public struct LiveTelemetry: Equatable, Sendable {
     // Enthusiast section
+    /// Mean rate over the last 10 s of the bytes the session pulled from its source: the demuxer's count
+    /// on the loopback and software paths, AVPlayer's own transfer total on the remote-HLS bypass, which
+    /// has no demuxer. nil until the window spans two ticks.
     public let instantBitrateMbps: Double?
     /// Lifetime mean rate of the session, over the seconds it spent consuming media rather than over
-    /// wall-clock seconds since it started (AE#514). A pause therefore leaves this value standing
+    /// wall-clock seconds since it started (AE#514). Metered from the same counter as `instantBitrateMbps`. A pause therefore leaves this value standing
     /// still instead of dragging it toward zero for as long as the pause lasts, and so does the tail
     /// after end-of-media. nil until the session has both accrued active time and fetched something:
     /// like `networkThroughputMbps`, a value that cannot be measured yet is a gap, never a zero.
diff --git a/Sources/AetherEngine/Diagnostics/LiveTelemetrySampler.swift b/Sources/AetherEngine/Diagnostics/LiveTelemetrySampler.swift
index 45a121789..00b547503 100644
--- a/Sources/AetherEngine/Diagnostics/LiveTelemetrySampler.swift
+++ b/Sources/AetherEngine/Diagnostics/LiveTelemetrySampler.swift
@@ -44,6 +44,42 @@ struct RollingWindow<T: AdditiveArithmetic> {
     }
 }
 
+/// Rate of a cumulative session byte counter, in the shape the demuxer meter uses: a 10-second window
+/// of per-tick deltas for the instant rate, the lifetime total for the average. The remote-HLS bypass
+/// feeds it AVPlayer's own session transfer total, because that route has no demuxer to count.
+struct TransferRateMeter {
+    private var window = RollingWindow<Int64>(capacity: 10, zero: 0)
+    /// Highest total seen. A total that falls back (it should not, AE#443 folds retired items in) is
+    /// not counted a second time when it climbs again.
+    private(set) var lifetimeBytes: Int64 = 0
+
+    /// One tick. nil (no access-log entry yet) is a tick in which nothing arrived.
+    mutating func record(sessionBytes: Int64?) {
+        let total = sessionBytes ?? lifetimeBytes
+        window.push(max(0, total - lifetimeBytes))
+        lifetimeBytes = max(lifetimeBytes, total)
+    }
+
+    var windowBytes: Int64 { window.sum }
+
+    /// nil until the window spans time (two samples), like the demuxer-fed instant rate.
+    var instantMbps: Double? {
+        guard window.count >= 2 else { return nil }
+        return Double(window.sum) * 8.0 / Double(window.count) / 1_000_000.0
+    }
+
+    /// Same quotient and the same nil rule as `LiveTelemetrySampler.averageBitrateMbps` (AE#514).
+    func averageMbps(activeSeconds: Double) -> Double? {
+        guard activeSeconds > 0, lifetimeBytes > 0 else { return nil }
+        return Double(lifetimeBytes) * 8.0 / activeSeconds / 1_000_000.0
+    }
+
+    mutating func reset() {
+        window.reset()
+        lifetimeBytes = 0
+    }
+}
+
 /// Value snapshot of every AVFoundation property the native-path tick consumes. Each getter is a
 /// synchronous XPC round-trip to mediaserverd; a busy media server (display-mode change on an HDR
 /// start) turns any main-actor read into a fully blocked main thread and, past the watchdog
@@ -110,6 +146,8 @@ final class LiveTelemetrySampler {
     private var byteWindow = RollingWindow<Int64>(capacity: 10, zero: 0)   // 10-second rolling window
     private var frameWindow = RollingWindow<Int>(capacity: 10, zero: 0)
     private var bridgeByteWindow = RollingWindow<Int64>(capacity: 10, zero: 0)
+    /// Remote-HLS bypass: AVPlayer's session transfer total stands in for the demuxer counter.
+    private var consumerTransferMeter = TransferRateMeter()
 
     private var lastDemuxerBytes: Int64 = 0
     private var lastBridgeBytes: Int64 = 0
@@ -152,6 +190,7 @@ final class LiveTelemetrySampler {
         byteWindow.reset()
         frameWindow.reset()
         bridgeByteWindow.reset()
+        consumerTransferMeter.reset()
         // Seed from CURRENT counters: a zero seed pushes all pre-start prefetch bytes into tick 1, inflating instant bitrate for ~10 s.
         lastDemuxerBytes = engine?.demuxerBytesFetched ?? 0
         lastBridgeBytes = engine?.audioBridgeOutputBytesLifetime ?? 0
@@ -196,6 +235,26 @@ final class LiveTelemetrySampler {
         return Double(windowBytes) * 8.0 / Double(activeSeconds) / 1_000_000.0
     }
 
+    /// Which cumulative counter the two bitrate fields are metered from.
+    enum BitrateCounter: Equatable {
+        /// Bytes the engine's demuxer pulled from the source (loopback and software).
+        case demuxer
+        /// Bytes AVPlayer transferred, from its access log. The remote-HLS bypass has no demuxer, so this is
+        /// the only count of what the session pulled from the origin there.
+        case consumerTransfer
+    }
+
+    nonisolated static func bitrateCounter(for route: VideoRoute) -> BitrateCounter {
+        route == .remoteBypass ? .consumerTransfer : .demuxer
+    }
+
+    /// Whether the native branch has the loopback pipeline behind it. On the bypass the producer's A/V gap
+    /// does not exist (its getter reads 0, which would publish as a measured zero), and the #169 tail-park
+    /// synthesis stays with the route whose EXTINF overshoot it was built for.
+    nonisolated static func readsLoopbackPipeline(_ route: VideoRoute) -> Bool {
+        route != .remoteBypass
+    }
+
     /// AE#514: whether a tick's second belongs in the lifetime average's divisor.
     ///
     /// That average used to divide by wall-clock time since the session started, which made a pause
@@ -241,14 +300,16 @@ final class LiveTelemetrySampler {
         }
         lastTickTime = tickTime
 
-        // Instant + average bitrate from demuxer byte counters (both native and SW paths)
+        let route = engine.videoRoute
+
+        // Instant + average bitrate from demuxer byte counters (loopback and SW; the bypass overrides below)
         let demuxerBytes = engine.demuxerBytesFetched
         let bytesThisTick = max(0, demuxerBytes - lastDemuxerBytes)
         lastDemuxerBytes = demuxerBytes
         if sessionStartBytes == 0 { sessionStartBytes = demuxerBytes }
         byteWindow.push(bytesThisTick)
 
-        let instantBitrateMbps: Double?
+        var instantBitrateMbps: Double?
         if byteWindow.count >= 2 {
             let totalBytes = byteWindow.sum
             let seconds = Double(byteWindow.count)
@@ -262,7 +323,7 @@ final class LiveTelemetrySampler {
             activeSeconds: byteWindow.activeCount,
             samples: byteWindow.count)
 
-        let averageBitrateMbps = Self.averageBitrateMbps(
+        var averageBitrateMbps = Self.averageBitrateMbps(
             lifetimeBytes: max(0, demuxerBytes - sessionStartBytes),
             activeSeconds: activeSeconds)
 
@@ -298,7 +359,8 @@ final class LiveTelemetrySampler {
             observedFps = nil
             displayCushionSeconds = nil
             accumulatedFrameDelaySeconds = nil
-            avSyncGapMs = engine.lastAVGapMs  // HLSSegmentProducer audio-gate-open vs video-gate-open (native path only)
+            // HLSSegmentProducer audio-gate-open vs video-gate-open, loopback only.
+            avSyncGapMs = Self.readsLoopbackPipeline(route) ? engine.lastAVGapMs : nil
             if let player = engine.currentAVPlayer, let item = player.currentItem {
                 var readings = await readNativeOffMain(player: player, item: item)
                 // stop() may have cancelled this tick, or a reload seam may have swapped the
@@ -382,13 +444,23 @@ final class LiveTelemetrySampler {
             accumulatedFrameDelaySeconds = nil
         }
 
+        // Remote-HLS bypass: no demuxer, so both rates come from what AVPlayer itself transferred, over
+        // the same window and the same active-seconds divisor. networkTransferredBytes is that total too.
+        if Self.bitrateCounter(for: route) == .consumerTransfer {
+            consumerTransferMeter.record(sessionBytes: networkTransferredBytes)
+            instantBitrateMbps = consumerTransferMeter.instantMbps
+            averageBitrateMbps = consumerTransferMeter.averageMbps(activeSeconds: activeSeconds)
+        }
+
         // Feed the extractor yield gate (#93 startup): nil on non-native paths keeps the
         // gate conservative there, but those paths have no active session to gate anyway.
         engine.extractorYieldState.setForwardBuffer(forwardBufferSeconds)
 
         if let readings = nativeReadings {
             emitLagDiag(engine: engine, readings: readings, netMbps: instantBitrateMbps)
-            evaluateEndOfMediaPark(engine: engine, readings: readings)
+            if Self.readsLoopbackPipeline(route) {
+                evaluateEndOfMediaPark(engine: engine, readings: readings)
+            }
         }
 
         let softwareCache = engine.softwarePacketCacheSnapshot
diff --git a/Tests/AetherEngineTests/RemoteHLSTelemetryTests.swift b/Tests/AetherEngineTests/RemoteHLSTelemetryTests.swift
new file mode 100644
index 000000000..ce8449b96
--- /dev/null
+++ b/Tests/AetherEngineTests/RemoteHLSTelemetryTests.swift
@@ -0,0 +1,85 @@
+import Foundation
+import Testing
+@testable import AetherEngine
+
+/// On the `nativeRemoteHLS` bypass the sampler never ran, because its bitrate halves read the loopback's
+/// demuxer counter, and so `liveTelemetry` stayed nil for the whole session. AVPlayer's own access log is
+/// there on this route too; these pin how its session byte total becomes the same two bitrate fields.
+@Suite("RemoteHLSTelemetry")
+struct RemoteHLSTelemetryTests {
+
+    @Test("the bypass meters AVPlayer's transfer, every other route the demuxer")
+    func counterPerRoute() {
+        #expect(LiveTelemetrySampler.bitrateCounter(for: .remoteBypass) == .consumerTransfer)
+        #expect(LiveTelemetrySampler.bitrateCounter(for: .loopback) == .demuxer)
+        #expect(LiveTelemetrySampler.bitrateCounter(for: .software) == .demuxer)
+        #expect(LiveTelemetrySampler.bitrateCounter(for: .none) == .demuxer)
+    }
+
+    @Test("the loopback-only readings stay nil on the bypass")
+    func loopbackOnlyReadings() {
+        #expect(LiveTelemetrySampler.readsLoopbackPipeline(.remoteBypass) == false)
+        #expect(LiveTelemetrySampler.readsLoopbackPipeline(.loopback))
+    }
+
+    @Test("instant is the ten-second window of per-tick deltas, like the demuxer meter")
+    func instantOverWindow() {
+        var meter = TransferRateMeter()
+        meter.record(sessionBytes: 0)
+        #expect(meter.instantMbps == nil)   // one sample spans no time
+        meter.record(sessionBytes: 1_250_000)
+        meter.record(sessionBytes: 2_500_000)
+        // 2.5 MB over three one-second samples.
+        let expected: Double = 2_500_000.0 * 8.0 / 3.0 / 1_000_000.0
+        #expect(abs((meter.instantMbps ?? 0) - expected) < 0.0001)
+    }
+
+    @Test("the window forgets what is older than ten ticks")
+    func windowRolls() {
+        var meter = TransferRateMeter()
+        meter.record(sessionBytes: 50_000_000)   // startup burst
+        for i in 1...10 { meter.record(sessionBytes: 50_000_000 + Int64(i) * 125_000) }
+        #expect(abs((meter.instantMbps ?? 0) - 1.0) < 0.0001)
+    }
+
+    @Test("a tick with no access log yet adds nothing and keeps the last total")
+    func missingReadingIsNoDelta() {
+        var meter = TransferRateMeter()
+        meter.record(sessionBytes: 1_000_000)
+        meter.record(sessionBytes: nil)
+        meter.record(sessionBytes: 1_000_000)
+        #expect(meter.lifetimeBytes == 1_000_000)
+        meter.record(sessionBytes: 2_000_000)
+        #expect(meter.lifetimeBytes == 2_000_000)
+    }
+
+    /// The folded total never falls (AE#443), but a counter that did must not make the next rise count twice.
+    @Test("a total that falls back is not counted again when it recovers")
+    func fallingTotalIsNotRecounted() {
+        var meter = TransferRateMeter()
+        meter.record(sessionBytes: 3_000_000)
+        meter.record(sessionBytes: 1_000_000)
+        meter.record(sessionBytes: 3_000_000)
+        #expect(meter.lifetimeBytes == 3_000_000)
+        #expect(meter.windowBytes == 3_000_000)
+    }
+
+    @Test("the average is the lifetime transfer over the active seconds, nil until both exist")
+    func average() {
+        var meter = TransferRateMeter()
+        #expect(meter.averageMbps(activeSeconds: 10) == nil)
+        meter.record(sessionBytes: 2_500_000)
+        #expect(meter.averageMbps(activeSeconds: 0) == nil)
+        #expect(abs((meter.averageMbps(activeSeconds: 10) ?? 0) - 2.0) < 0.0001)
+    }
+
+    @Test("reset starts a new session from zero")
+    func reset() {
+        var meter = TransferRateMeter()
+        meter.record(sessionBytes: 5_000_000)
+        meter.record(sessionBytes: 6_000_000)
+        meter.reset()
+        #expect(meter.lifetimeBytes == 0)
+        #expect(meter.instantMbps == nil)
+    }
+}

From 660a0b50a05f04571149d30375f8e2c3918f7cf5 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Mon, 28 Sep 2026 15:30:58 +0200
Subject: [PATCH 137/359] feat(remote-hls): publish telemetry, audio tracks and
 delivered video format on the bypass

loadRemoteHLS now starts the telemetry sampler, and the host reads the item's
audio tracks (bypass only, via SessionLoadContract.readsBackAudioTracks) and
the delivered video's description next to the #168 format read. The engine
publishes them as audioTracks / activeAudioTrackIndex and sourceVideoWidth /
sourceVideoHeight / sourceVideoCodecName / sourceVideoStreamFormat, so a stats
panel shows the transcode actually playing instead of the library's file.
selectAudioTrack refuses .remoteBypass (AVPlayer owns the selection there).
aetherctl play prints the settled source and audio state plus inst/avg bitrate.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mf4MXgM9bqugHoe5TW4BYf
---
 .../AetherEngine/AetherEngine+Loading.swift   | 31 ++++++++++++-
 Sources/AetherEngine/AetherEngine.swift       | 35 +++++++++++++--
 .../Native/NativeAVPlayerHost.swift           | 45 ++++++++++++++++++-
 Sources/aetherctl/PlaybackCmd.swift           | 14 ++++++
 docs/api.md                                   | 12 ++---
 docs/architecture.md                          |  1 +
 6 files changed, 126 insertions(+), 12 deletions(-)

diff --git a/Sources/AetherEngine/AetherEngine+Loading.swift b/Sources/AetherEngine/AetherEngine+Loading.swift
index ca0986f2f..832b1b59c 100644
--- a/Sources/AetherEngine/AetherEngine+Loading.swift
+++ b/Sources/AetherEngine/AetherEngine+Loading.swift
@@ -415,6 +415,29 @@ extension AetherEngine {
                 self.applyRemoteHLSDisplayCriteria(format: fmt, options: options)
             }
             .store(in: &nativeCancellables)
+        // What was DELIVERED, which on a capped transcode is not what the host's library holds: without it
+        // a stats panel fell back to the original file's 3840x2160 for a 1280x720 stream. Its own sink,
+        // because a later read can refine the description without changing the dynamic range.
+        // dropFirst on both: a reused host replays the outgoing item's reading on subscribe, before load resets it.
+        host.$detectedVideoDescription
+            .dropFirst()
+            .compactMap { $0 }
+            .sink { [weak self] video in
+                guard let self else { return }
+                self.publishRemoteHLSVideoDescription(video)
+            }
+            .store(in: &nativeCancellables)
+        // No probe lists this route's audio, so AVPlayer's own tracks are the list. Informational: AVPlayer
+        // owns the audio selection here, and `selectAudioTrack` refuses the route rather than reload it.
+        host.$detectedAudioTracks
+            .dropFirst()
+            .sink { [weak self] readings in
+                guard let self else { return }
+                let (tracks, active) = RemoteHLSStreamDescription.audioTracks(readings)
+                self.audioTracks = tracks
+                self.activeAudioTrackIndex = active
+            }
+            .store(in: &nativeCancellables)
         // #168 follow-up: an advertised video rendition that never builds an item track means HEVC carried
         // in MPEG-TS segments, which AVFoundation's HLS demuxer does not support (audio-only, black). The
         // loopback ingest remuxes TS to fMP4 and plays the same stream, so reroute there transparently.
@@ -546,7 +569,9 @@ extension AetherEngine {
                       // #334: the ceiling on silence this path never had. AVPlayer's "gave up" covers an
                       // origin that stops answering; it does not cover one that answers everything while
                       // AVFoundation builds no track, where nothing terminal is ever published.
-                      readinessDeadline: RemoteHLSReadinessDeadline.defaultBudgetSeconds))
+                      readinessDeadline: RemoteHLSReadinessDeadline.defaultBudgetSeconds,
+                      // No probe lists this route's audio, so the item's own tracks are the list.
+                      readsBackAudioTracks: true))
 
         attachRemoteHLSCueClock(host: host, expectedGeneration: bypassGeneration)
 
@@ -562,7 +587,9 @@ extension AetherEngine {
             host.play()
         }
         startMemoryProbe()
-        // No startLiveTelemetrySampler: all sampler counters read the loopback pipeline (demuxer / producer / cache / server), none of which exists on this bypass.
+        // The sampler reads AVPlayer's access log on this route: both bitrates, network rate and transfer,
+        // dropped frames and forward buffer. The loopback counters (producer, muxer, server) read zero.
+        startLiveTelemetrySampler()
     }
 
     /// AE#616: on this bypass `sourceTime` would otherwise be item time, which an origin that restarts
diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index 8980b7aa7..7cad009fe 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -597,9 +597,13 @@ public final class AetherEngine: ObservableObject {
     @Published public internal(set) var sourceVideoCodecName: String? = nil
 
     /// AE#658: the source video stream's pixel format, bit depth, colour description and profile as the
-    /// container and the probe's decoder declared them, nil before load, on sources without video, and on
-    /// the probe-free native HLS bypass. Companion to `decodedVideoFormat`, which is what the engine's own
-    /// decoder actually produced.
+    /// container and the probe's decoder declared them, nil before load and on sources without video.
+    /// Companion to `decodedVideoFormat`, which is what the engine's own decoder actually produced.
+    ///
+    /// On the probe-free native HLS bypass it is read back from AVPlayer's item video track once that
+    /// resolves: colour from the format description's extensions, profile, bit depth and pixel format from
+    /// its avcC / hvcC record where it carries one (nil otherwise, AV1 and VP9 included). That is the
+    /// DELIVERED stream, which under a server-side transcode is not the file the host's library holds.
     @Published public internal(set) var sourceVideoStreamFormat: VideoStreamFormat? = nil
 
     /// AE#658: the format the engine's software decoder produced and the display buffer it went into,
@@ -2162,8 +2166,20 @@ public final class AetherEngine: ObservableObject {
 
     /// Source video dimensions from the probe. Used as a bitmap-subtitle canvas fallback before the first PCS
     /// is parsed. 0 before load or when source has no video (AetherEngine#28). Also available in SourceProbe.
+    /// On the probe-free native HLS bypass they are the delivered stream's, read back from AVPlayer's item
+    /// track once it resolves, so a capped transcode reports the resolution it is actually playing.
     @Published public private(set) var sourceVideoWidth: Int32 = 0
     @Published public private(set) var sourceVideoHeight: Int32 = 0
+
+    /// The remote-HLS bypass's stand-in for the probe: what AVPlayer parsed of the delivered video.
+    func publishRemoteHLSVideoDescription(_ video: RemoteHLSStreamDescription.Video) {
+        if video.width > 0, video.height > 0 {
+            sourceVideoWidth = video.width
+            sourceVideoHeight = video.height
+        }
+        if let codec = video.codecName { sourceVideoCodecName = codec }
+        sourceVideoStreamFormat = video.format
+    }
     /// Display-width multiplier for non-square source pixels: `sourceVideoWidth * this` is the width
     /// the picture presents at. 1 before load, on square-pixel sources, and whenever the declared
     /// ratio is one the engine refuses to believe (#290), so it is never a number the picture
@@ -6653,7 +6669,20 @@ public final class AetherEngine: ObservableObject {
     /// expects ~0.5-1 s black frame (AVPlayer.replaceCurrentItem tears the surface). Display-criteria handshake
     /// is suppressed (video unchanged). `index` is the container stream index (TrackInfo.id). No-op if
     /// out-of-range, pointing at a non-audio stream, or already active.
+    ///
+    /// Not available on `VideoRoute.remoteBypass`: there `audioTracks` lists what AVPlayer built and is
+    /// informational, the selection belongs to AVFoundation, and a pick is logged and ignored rather than
+    /// turned into a reload the bypass has no audio override for. A host that wants another language on
+    /// that route loads a URL that carries it.
     public func selectAudioTrack(index: Int) {
+        if videoRoute == .remoteBypass {
+            EngineLog.emit(
+                "[AetherEngine] selectAudioTrack(\(index)) ignored: AVPlayer owns the audio selection on "
+                + "the remote-HLS bypass; audioTracks is informational there",
+                category: .engine
+            )
+            return
+        }
         // Forward-only custom sources (incl. live HLS-ingest) can't rewind; rebuilding would re-consume a
         // drained FIFO and stall silently. Logged so a picker that does nothing is explainable.
         if isCustomSource && !customSourceIsSeekable {
diff --git a/Sources/AetherEngine/Native/NativeAVPlayerHost.swift b/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
index 61e192844..3a249b6c4 100644
--- a/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
+++ b/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
@@ -163,6 +163,12 @@ final class NativeAVPlayerHost {
     /// spelling the engine publishes elsewhere. Set beside `detectedVideoFormat`, which the engine's sink
     /// reads it with; nil while no video track resolves.
     @Published private(set) var detectedVideoCodecName: String?
+    /// Dimensions and colour description of the delivered video from the same read, for the bypass's
+    /// `sourceVideoWidth` / `sourceVideoHeight` / `sourceVideoStreamFormat`. Set before `detectedVideoFormat`.
+    @Published private(set) var detectedVideoDescription: RemoteHLSStreamDescription.Video?
+    /// The audio tracks AVPlayer built for the item, read at the same two points as the video format.
+    /// The engine publishes them as `audioTracks` on the bypass, where no probe lists them.
+    @Published private(set) var detectedAudioTracks: [RemoteHLSStreamDescription.AudioReading] = []
 
     /// AetherEngine#168 follow-up: fires once when the armed carriage watchdog concludes the master
     /// advertises a video rendition but AVPlayer never built a video track past the grace window
@@ -413,6 +419,9 @@ final class NativeAVPlayerHost {
         /// then tunnels it through a 2-channel MAT carrier, so the route's channel count is not a
         /// statement about the audio and the surround-downmix warning below must not read it as one.
         var audioIsAtmosStreamCopy: Bool = false
+        /// Read the item's audio tracks back into `detectedAudioTracks`. Only the remote-HLS bypass needs
+        /// them; the loopback's probe already listed its audio, and the reads are XPC round trips.
+        var readsBackAudioTracks: Bool = false
     }
 
     /// AE#446 round 5: a fresh item is about to attach, invoked before anything can fetch a playlist
@@ -638,6 +647,7 @@ final class NativeAVPlayerHost {
                     }
                     // #168: publish the item's real dynamic range for the probe-free remote-HLS badge.
                     await self.publishDetectedVideoFormat(from: item)
+                    await self.publishDetectedAudioTracks(from: item)
                     guard self.sessionID == sid else { return }
                     // #168 follow-up: watch for an advertised video rendition that never builds a track
                     // (HEVC-in-MPEG-TS carriage); anchored at readyToPlay so dead origins never arm it.
@@ -707,6 +717,7 @@ final class NativeAVPlayerHost {
                         // #168: the video track can be absent from item.tracks at readyToPlay for HLS;
                         // re-read once playing so the remote-HLS badge settles on the real dynamic range.
                         await self.publishDetectedVideoFormat(from: item)
+                        await self.publishDetectedAudioTracks(from: item)
                     }
                 }
             }
@@ -2085,6 +2096,8 @@ final class NativeAVPlayerHost {
         detectedVideoFormat = nil
         detectedVideoFrameRate = nil
         detectedVideoCodecName = nil
+        detectedVideoDescription = nil
+        detectedAudioTracks = []
         // #168 follow-up: the carriage verdict belongs to the outgoing item.
         carriageWatchdogTask?.cancel()
         carriageWatchdogTask = nil
@@ -2439,9 +2452,11 @@ final class NativeAVPlayerHost {
             let ext = CMFormatDescriptionGetExtensions(cm) as? [String: Any] ?? [:]
             let transfer = ext[kCMFormatDescriptionExtension_TransferFunction as String] as? String
             let fmt = RemoteHLSFormatDetection.videoFormat(transferFunction: transfer, videoSubType: subType)
-            // Rate and codec before format: the engine's format sink reads both when it fires.
+            // Rate, codec and description before format: the engine's format sink reads them when it fires.
             if let rate, rate > 0 { detectedVideoFrameRate = rate }
             detectedVideoCodecName = RemoteHLSFormatDetection.codecName(videoSubType: subType)
+            let description = RemoteHLSStreamDescription.video(from: cm)
+            if detectedVideoDescription != description { detectedVideoDescription = description }
             if detectedVideoFormat != fmt {
                 detectedVideoFormat = fmt
                 EngineLog.emit(
@@ -2455,6 +2470,34 @@ final class NativeAVPlayerHost {
         }
     }
 
+    /// The audio half of the read above, at the same two points. Language comes from the track, and where
+    /// the track has none (muxed HLS audio rarely does) from the audible option AVPlayer selected.
+    @MainActor
+    private func publishDetectedAudioTracks(from item: AVPlayerItem) async {
+        let sid = sessionID
+        guard sid != 0, playerItem === item, sessionContract.readsBackAudioTracks else { return }
+        var selectedOptionLanguage: String?
+        if let group = try? await item.asset.loadMediaSelectionGroup(for: .audible),
+           let option = item.currentMediaSelection.selectedMediaOption(in: group) {
+            selectedOptionLanguage = option.extendedLanguageTag
+        }
+        var readings: [RemoteHLSStreamDescription.AudioReading] = []
+        for itemTrack in item.tracks {
+            guard let assetTrack = itemTrack.assetTrack, assetTrack.mediaType == .audio else { continue }
+            guard let cm = try? await assetTrack.load(.formatDescriptions).first else { continue }
+            let extendedTag = try? await assetTrack.load(.extendedLanguageTag)
+            let languageCode = try? await assetTrack.load(.languageCode)
+            let language = [extendedTag ?? nil, languageCode ?? nil, selectedOptionLanguage]
+                .compactMap { $0 }.first { !$0.isEmpty && $0 != "und" }
+            if let reading = RemoteHLSStreamDescription.audioReading(
+                from: cm, isEnabled: itemTrack.isEnabled, language: language) {
+                readings.append(reading)
+            }
+        }
+        guard sessionID == sid, playerItem === item else { return }
+        if detectedAudioTracks != readings { detectedAudioTracks = readings }
+    }
+
     /// Compact video track summary: dimensions + color attachments (primaries/transfer/matrix). Mismatch vs source-side codecpar signals DV/HDR signaling didn't survive the muxer.
     /// Dump item.tracks on .failed (FourCC per track). Async: AVAssetTrack.formatDescriptions is
     /// load-based; assetTrack access is main-actor.
diff --git a/Sources/aetherctl/PlaybackCmd.swift b/Sources/aetherctl/PlaybackCmd.swift
index a9517dc3c..06963d07b 100644
--- a/Sources/aetherctl/PlaybackCmd.swift
+++ b/Sources/aetherctl/PlaybackCmd.swift
@@ -153,6 +153,8 @@ func runPlay(url: URL, seconds: Double, live: Bool, nativeHLS: Bool = false, liv
 private func networkTelemetryFragment(_ telemetry: LiveTelemetry?) -> String {
     guard let telemetry else { return "" }
     var out = ""
+    if let inst = telemetry.instantBitrateMbps { out += String(format: " inst=%.2fMbps", inst) }
+    if let avg = telemetry.averageBitrateMbps { out += String(format: " avg=%.2fMbps", avg) }
     if let mbps = telemetry.networkThroughputMbps { out += String(format: " net=%.2fMbps", mbps) }
     if let rx = telemetry.networkTransferredBytes { out += String(format: " rx=%.1fMB", Double(rx) / 1_048_576) }
     out += String(format: " origin=%.1fMB", Double(telemetry.demuxerBytesFetched) / 1_048_576)
@@ -1322,6 +1324,16 @@ private func playSmokeTest(url: URL, seconds: Double, live: Bool, forceSoftware:
     // one when the question is what a host's picker ends up showing.
     let finalSubtitleTracks = engine.subtitleTracks
     let finalActiveSubtitle = engine.activeSubtitleTrackIndex
+    // The settled stats-panel identity. The SOURCE line at load prints before the remote-HLS bypass has
+    // read anything back from AVPlayer's item, so it reads empty there by construction.
+    let settledSource = "SOURCE codec=\(engine.sourceVideoCodecName ?? "nil") "
+        + "\(engine.sourceVideoWidth)x\(engine.sourceVideoHeight) "
+        + "fmt=\(engine.sourceVideoFormat) stream=\(engine.sourceVideoStreamFormat.map { String(describing: $0) } ?? "nil")"
+    let settledAudio = engine.audioTracks.map {
+        "#\($0.id) \($0.name) codec=\($0.codec) ch=\($0.channels) sr=\($0.sampleRate)"
+            + "\($0.profile.map { " profile=\($0)" } ?? "")\($0.isAtmos ? " atmos" : "")"
+    }.joined(separator: ", ")
+    let settledActiveAudio = engine.activeAudioTrackIndex
     if record != nil {
         await engine.stopRecording()
         print("  RECORD final state: \(engine.recordingState)")
@@ -1364,6 +1376,8 @@ private func playSmokeTest(url: URL, seconds: Double, live: Bool, forceSoftware:
         print("subtitle tracks (* = external): \(listed)")
         print("active subtitle: \(finalActiveSubtitle.map(String.init) ?? "none")")
     }
+    print("settled \(settledSource)")
+    print("audio tracks: \(settledAudio.isEmpty ? "none" : settledAudio) active=\(settledActiveAudio.map(String.init) ?? "none")")
     print("final t=\(String(format: "%.2f", finalTime))s state=\(String(describing: endState)) cues=\(cueCount)")
     let closingWindow = await MainActor.run { lastCues }
     print("WINDOW \(closingWindow.count) cues in the last published window")
diff --git a/docs/api.md b/docs/api.md
index 5304f0340..390ace97c 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -604,7 +604,7 @@ suppressing `AVPlayerItemLegibleOutput` to keep the measurement running.
 | `$dolbyVisionConversion` | A `DolbyVisionConversion?`: the Dolby Vision profile rewrite applied to the served stream, nil when the session serves the source's own profile or no Dolby Vision. `.profile7ToProfile81` is a Profile 7 source played on a display presenting Dolby Vision, where `$videoFormat` reads `.dolbyVision` and `$sourceDVProfile` keeps 7, so a label can say "P7 -> P8.1". The enhancement layer is dropped by that conversion. Set when the loopback session starts, cleared on stop. |
 | `$sourceVideoCodecName` | The source video codec in the libavcodec spelling ("hevc", "h264", "av1"), nil when the source carries no video. The probe-free remote-HLS bypass maps it back from the item's video sample type, so the field answers on every route rather than going quiet on one of them. Not the same question as `$activeVideoDecoder`: a codec has several decoders, and which one runs depends on the hardware. |
 | `$sourceContainerFormat` | The container libavformat opened ("matroska,webm", "mpegts"), nil on the remote-HLS bypass, where AVFoundation opens the source and there is no libav context to ask. This is the container that ARRIVED, which on a remux or transcode session is not the one a host's library metadata describes. |
-| `$sourceVideoStreamFormat` | A `VideoStreamFormat?` (AE#658): the source video stream's `pixelFormat` ("yuv420p10le"), `bitDepth`, `colorPrimaries`, `transfer`, `matrix`, `range` and `profile` ("Main 10"), in libav's names as the container and the probe's decoder declared them. A field the stream leaves unspecified is nil, never a guessed BT.709. `colorPrimariesLabel`, `transferLabel`, `matrixLabel` and `rangeLabel` give the names a viewer reads ("BT.2020", "PQ (SMPTE ST 2084)", "BT.2020 NCL", "Limited"). nil before load, without video, and on the probe-free remote-HLS bypass. |
+| `$sourceVideoStreamFormat` | A `VideoStreamFormat?` (AE#658): the source video stream's `pixelFormat` ("yuv420p10le"), `bitDepth`, `colorPrimaries`, `transfer`, `matrix`, `range` and `profile` ("Main 10"), in libav's names as the container and the probe's decoder declared them. A field the stream leaves unspecified is nil, never a guessed BT.709. `colorPrimariesLabel`, `transferLabel`, `matrixLabel` and `rangeLabel` give the names a viewer reads ("BT.2020", "PQ (SMPTE ST 2084)", "BT.2020 NCL", "Limited"). nil before load and without video. On the probe-free remote-HLS bypass it is the DELIVERED stream, read back from AVPlayer's item video track once it resolves: colour and range from the format description, `profile`, `bitDepth` and `pixelFormat` from its avcC / hvcC record (nil where the codec has none of those, AV1 and VP9 included). Under a server-side transcode that is the transcode, not the library's file, which is the point of reading it there. |
 | `$decodedVideoFormat` | A `DecodedVideoFormat?` (AE#658): what the engine's own decoder actually produced. `frame` is a `VideoStreamFormat` for the decoded picture (libavcodec's output pixel format, or the libav name of the VideoToolbox buffer on the software host's hardware decoder), `pixelBufferFormat` the CoreVideo buffer it was displayed from (`420v`, `x420`; `pixelBufferLabel` reads "P010 (x420)"). Republished when either changes mid-stream. **nil on every native route**: AVPlayer decodes there and its frames never pass through the engine, so a panel shows `$sourceVideoStreamFormat` and names AVPlayer as the decoder instead of inferring a pixel format it never saw. |
 | `$activeVideoDecoder`, `$activeAudioDecoder` | The decoder names actually in use, for a stats overlay. This is the honest "what is decoding this" surface; `playbackBackend` is not. Show `$activeAudioDecoder`, classify on `$audioDelivery`: a label cannot separate a source without audio from a source whose audio was dropped. |
 | `$metadata` | `MediaMetadata` parsed at load (title / artist / album / cover). |
@@ -632,9 +632,9 @@ suppressing `AVPlayerItemLegibleOutput` to keep the measurement running.
 
 | Symbol | Notes |
 | --- | --- |
-| `$audioTracks` | `[TrackInfo]`. Republished when `LoadOptions.confirmAtmos` confirms a track. |
-| `$activeAudioTrackIndex` | The selected track's id. |
-| `selectAudioTrack(index:)` | Session-preserving reload, roughly 0.5 to 1 s of black. `index` is `TrackInfo.id`. A no-op when out of range, already active, or on a forward-only custom source (live ingest included), which cannot rebuild its pipeline: there a track change is a fresh `load` naming the stream. Every refusal is logged, so a picker that does nothing is explainable. |
+| `$audioTracks` | `[TrackInfo]`. Republished when `LoadOptions.confirmAtmos` confirms a track. On `.remoteBypass` it lists the audio tracks AVPlayer built for the item (normally just the one playing), read from their format descriptions: `codec` in libavcodec's spelling (`eac3`, `ac3`, `aac`), `channels`, `sampleRate`, `profile` (AAC's object type; "Dolby Digital Plus + Dolby Atmos" with `isAtmos` when the E-AC-3 dec3 record announces JOC) and `language` from the track or the selected audible option. The ids are synthetic (from 400000 up) because there is no stream index on that route; compare them only with `activeAudioTrackIndex`. |
+| `$activeAudioTrackIndex` | The selected track's id. On `.remoteBypass`, the enabled item track's. |
+| `selectAudioTrack(index:)` | Session-preserving reload, roughly 0.5 to 1 s of black. `index` is `TrackInfo.id`. A no-op when out of range, already active, or on a forward-only custom source (live ingest included), which cannot rebuild its pipeline: there a track change is a fresh `load` naming the stream. Every refusal is logged, so a picker that does nothing is explainable. Also a no-op on `.remoteBypass`, where AVPlayer owns the audio selection and the list above is informational; a different language there is a different URL. |
 | `installAudioTap()`, `removeAudioTap()`, `audioTapHasDeliverySource`, `AetherEngine.audioTapFormat` | Opt-in decoded PCM, mono Float32 48 kHz with source-PTS stamps, off the render path. See the contract above. |
 
 ## Subtitles
@@ -860,7 +860,7 @@ say so on the tracker rather than working around it.
 | `nativePlayerLayer` | The engine's own `AVPlayerLayer`, for a host building `AVPictureInPictureController` around a layer rather than around `currentAVPlayer`. |
 | `$softwarePiPSource` | `SoftwarePiPSource` for sample-buffer PiP on the software path: the display layer plus transport answers on the enqueued frames' axis. iOS only in practice; tvOS AVKit does not evaluate sample-buffer content sources (FB9751461). |
 | `$softwareDisplaySize` | The rectangle the software path's picture presents at: coded size under the decoder's pixel aspect. Mirrored, not latched, so a mid-stream resolution change re-shapes it. nil on every other path. |
-| `sourceVideoWidth`, `sourceVideoHeight`, `sourceVideoPixelAspectRatio` | The source's CODED size and the multiplier that turns it into the presented one (`width * ratio`), read once from the probe. The ratio is 1 on square pixels and on a declared ratio the engine refuses (#290), never a guess; on the paths that draw, prefer what is on screen (`softwareDisplaySize`, `AVPlayerLayer.videoRect`) over recomputing it here. |
+| `sourceVideoWidth`, `sourceVideoHeight`, `sourceVideoPixelAspectRatio` | The source's CODED size and the multiplier that turns it into the presented one (`width * ratio`), read once from the probe (on `.remoteBypass`, from AVPlayer's item video track once it resolves: the delivered size). The ratio is 1 on square pixels and on a declared ratio the engine refuses (#290), never a guess; on the paths that draw, prefer what is on screen (`softwareDisplaySize`, `AVPlayerLayer.videoRect`) over recomputing it here. |
 | `pictureInPictureActive` | Host-set. Keeps the pipeline and the loopback server alive across a background transition, and keeps the software path decoding video for the window. |
 | `backgroundPlaybackEnabled`, `backgroundTeardownGraceSeconds` | Background audio policy; the grace window (15 s default) is what lets a paused session survive a quick app switch. |
 | `presentationAxisMap` | `PresentationAxisMap`: `sourceSeconds(forItemSeconds:)`, `itemSeconds(forSourceSeconds:)`, `shiftSeconds(atItemSeconds:)`, `seams` (each a `PresentationAxisMap.Seam` of `itemSeconds` and `shiftSeconds`), `isEmpty`. Readable off the main actor. Cue times and `sourceTime` live on the source axis; `AVPlayerItem.currentTime()` lives on the item axis, and they differ by the producer shift. Returns nil rather than a guess where no axis is established. |
@@ -925,7 +925,7 @@ as well.
 | Symbol | Notes |
 | --- | --- |
 | `AetherEngine.version` | The engine release this source descends from, as the string a published tag carries. SwiftPM resolves a package to a revision rather than to a tag, so an About panel or the header of a diagnostic log has nothing else to name the engine with. Between releases, and under a pin on an unreleased commit, it names the last published version the checkout descends from. |
-| `diagnostics.liveTelemetry` | 1 Hz `LiveTelemetry?` snapshot while playing or paused, nil while idle. On a separate `ObservableObject` so its ticks cannot re-render a host observing the engine. |
+| `diagnostics.liveTelemetry` | 1 Hz `LiveTelemetry?` snapshot while playing or paused, nil while idle. On a separate `ObservableObject` so its ticks cannot re-render a host observing the engine. On `.remoteBypass` it is fed from AVPlayer's access log alone: `instantBitrateMbps` and `averageBitrateMbps` are metered from the bytes AVPlayer transferred (10 s window, and lifetime over active seconds, the same shape the demuxer meter has elsewhere), `networkThroughputMbps` is the access log's `observedBitrate`, `networkTransferredBytes` and `droppedFrameCount` its session totals, `forwardBufferSeconds` the loaded range ahead of the playhead. `avSyncGapMs` and `observedFps` are nil, and the loopback counters (`producerRestartCount`, `muxedBytesLifetime`, `serverBytesSentLifetime`, `serverRequestCount`, `demuxerBytesFetched`) read 0 because there is no loopback. |
 | `LiveTelemetry.softwareCacheSeekHits`, `softwareCacheSeekMisses`, `softwareCacheSourceEpoch` | Optional cumulative software-VOD packet-cache counters. A hit repositions the retained consumer cursor without changing the source epoch; a miss repositions the demuxer and advances it. `nil` on other paths. `cachedBytes` includes retained compressed packet records on software VOD, distinct from decoded `displayCushionSeconds` and the underlying byte-reader window. |
 | `EngineLog.handler` | Mirror every info-level line into a host capture path. Fires from whatever thread emitted it, so it must be thread-safe and non-blocking. |
 | `EngineLog.subsystem`, `EngineLog.Category` | `de.superuser404.AetherEngine`, one category per subsystem: `engine`, `ffmpeg`, `session`, `muxer`, `demux`, `hls.server`, `audio.bridge`, `sw.playback`, `scrub`. |
diff --git a/docs/architecture.md b/docs/architecture.md
index 3acb9764c..d0fb8ed2c 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -432,6 +432,7 @@ Sources/AetherEngine/
 │   ├── AirPlayPlaylistDecision.swift        Pure playlist choice for the wireless-AirPlay loopback rewrite: which of master / media a receiver is handed, kept separate and testable offline like `MasterFallbackDecision` (#86, #227)
 │   ├── NativeLegibleDeselectPin.swift       Keeps AVKit's ready-time legible auto-select from engaging a rendition the host never asked for (Sodalite#38), and publishes the caption requests the system makes on its own as `systemCaptionRequest`, by BCP 47 language rather than by ordinal (Sodalite#65)
 │   ├── RemoteHLSFormatDetection.swift       Dynamic-range classification for the `nativeRemoteHLS` bypass, read back from AVPlayer's own track format instead of a second origin probe, which that path exists to avoid (#168)
+│   ├── RemoteHLSStreamDescription.swift     The rest of that read-back for stats panels: delivered dimensions, colour description and avcC/hvcC profile as a `VideoStreamFormat`, and the item's audio tracks as `TrackInfo` (codec, channels, rate, dec3 JOC)
 │   ├── RemoteHLSIngestFallback.swift        Reroutes a bypass session onto the live-ingest loopback when the master advertises HEVC / DV / AV1 but delivers MPEG-TS, carriage AVFoundation builds no video track for (#168)
 │   ├── RemoteHLSMasterRewrite.swift         Declares host-supplied sidecar subtitles as legible renditions on the bypass by rewriting the origin master, since media selection on an HLS asset comes from the playlist and nowhere else (#316)
 │   ├── RemoteHLSSubtitleProxy.swift         Stands a loopback origin in front of that remote master: two playlist GETs, a rewrite and a socket, and anything that does not line up keeps the plain origin URL (#316)

From 66fe76ce7a4275656e081614f11f72c40b7974a5 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Mon, 28 Sep 2026 16:46:32 +0200
Subject: [PATCH 138/359] fix(telemetry): the bypass bitrate is what the
 variant declares, not the transfer

Metering the bitrate fields from AVPlayer's transfer total made them read
buffer fill at link speed: 22.6 Mbps instant and 15.8 average for a 3.7 Mbps
Jellyfin transcode on an iPhone right after a start. The fields name the
stream's rate, so on the bypass they are now the playing variant's declared
BANDWIDTH and AVERAGE-BANDWIDTH from the access log. The transfer stays in
the network fields. TransferRateMeter goes with it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mf4MXgM9bqugHoe5TW4BYf
---
 .../Diagnostics/LiveTelemetry.swift           |  9 +-
 .../Diagnostics/LiveTelemetrySampler.swift    | 77 +++++++----------
 .../RemoteHLSTelemetryTests.swift             | 84 ++++++-------------
 docs/api.md                                   |  2 +-
 4 files changed, 60 insertions(+), 112 deletions(-)

diff --git a/Sources/AetherEngine/Diagnostics/LiveTelemetry.swift b/Sources/AetherEngine/Diagnostics/LiveTelemetry.swift
index 953595c3f..35616425b 100644
--- a/Sources/AetherEngine/Diagnostics/LiveTelemetry.swift
+++ b/Sources/AetherEngine/Diagnostics/LiveTelemetry.swift
@@ -9,12 +9,13 @@ import Foundation
 /// interpret a sub-second decoded queue as the size of the compressed packet cache.
 public struct LiveTelemetry: Equatable, Sendable {
     // Enthusiast section
-    /// Mean rate over the last 10 s of the bytes the session pulled from its source: the demuxer's count
-    /// on the loopback and software paths, AVPlayer's own transfer total on the remote-HLS bypass, which
-    /// has no demuxer. nil until the window spans two ticks.
+    /// Mean rate over the last 10 s of the bytes the session pulled from its source, from the demuxer's
+    /// count on the loopback and software paths. nil until the window spans two ticks. The remote-HLS
+    /// bypass has no demuxer, and what AVPlayer transferred there is buffer fill at link speed rather than
+    /// the stream's rate, so on that route this is the playing variant's declared BANDWIDTH.
     public let instantBitrateMbps: Double?
     /// Lifetime mean rate of the session, over the seconds it spent consuming media rather than over
-    /// wall-clock seconds since it started (AE#514). Metered from the same counter as `instantBitrateMbps`. A pause therefore leaves this value standing
+    /// wall-clock seconds since it started (AE#514). Metered from the same counter as `instantBitrateMbps`; on the remote-HLS bypass it is the variant's declared AVERAGE-BANDWIDTH, or BANDWIDTH where the master omits it. A pause therefore leaves this value standing
     /// still instead of dragging it toward zero for as long as the pause lasts, and so does the tail
     /// after end-of-media. nil until the session has both accrued active time and fetched something:
     /// like `networkThroughputMbps`, a value that cannot be measured yet is a gap, never a zero.
diff --git a/Sources/AetherEngine/Diagnostics/LiveTelemetrySampler.swift b/Sources/AetherEngine/Diagnostics/LiveTelemetrySampler.swift
index 00b547503..7bc50ad64 100644
--- a/Sources/AetherEngine/Diagnostics/LiveTelemetrySampler.swift
+++ b/Sources/AetherEngine/Diagnostics/LiveTelemetrySampler.swift
@@ -44,42 +44,6 @@ struct RollingWindow<T: AdditiveArithmetic> {
     }
 }
 
-/// Rate of a cumulative session byte counter, in the shape the demuxer meter uses: a 10-second window
-/// of per-tick deltas for the instant rate, the lifetime total for the average. The remote-HLS bypass
-/// feeds it AVPlayer's own session transfer total, because that route has no demuxer to count.
-struct TransferRateMeter {
-    private var window = RollingWindow<Int64>(capacity: 10, zero: 0)
-    /// Highest total seen. A total that falls back (it should not, AE#443 folds retired items in) is
-    /// not counted a second time when it climbs again.
-    private(set) var lifetimeBytes: Int64 = 0
-
-    /// One tick. nil (no access-log entry yet) is a tick in which nothing arrived.
-    mutating func record(sessionBytes: Int64?) {
-        let total = sessionBytes ?? lifetimeBytes
-        window.push(max(0, total - lifetimeBytes))
-        lifetimeBytes = max(lifetimeBytes, total)
-    }
-
-    var windowBytes: Int64 { window.sum }
-
-    /// nil until the window spans time (two samples), like the demuxer-fed instant rate.
-    var instantMbps: Double? {
-        guard window.count >= 2 else { return nil }
-        return Double(window.sum) * 8.0 / Double(window.count) / 1_000_000.0
-    }
-
-    /// Same quotient and the same nil rule as `LiveTelemetrySampler.averageBitrateMbps` (AE#514).
-    func averageMbps(activeSeconds: Double) -> Double? {
-        guard activeSeconds > 0, lifetimeBytes > 0 else { return nil }
-        return Double(lifetimeBytes) * 8.0 / activeSeconds / 1_000_000.0
-    }
-
-    mutating func reset() {
-        window.reset()
-        lifetimeBytes = 0
-    }
-}
-
 /// Value snapshot of every AVFoundation property the native-path tick consumes. Each getter is a
 /// synchronous XPC round-trip to mediaserverd; a busy media server (display-mode change on an HDR
 /// start) turns any main-actor read into a fully blocked main thread and, past the watchdog
@@ -102,6 +66,10 @@ struct NativeAVFReadings: Sendable {
     var contiguousForwardBufferSeconds: Double? = nil
     /// Sum over all access-log events, for the [LagDiag] tick-over-tick drop delta.
     var droppedFramesLifetimeSum: Int = 0
+    /// The current variant's declared BANDWIDTH and AVERAGE-BANDWIDTH, in bits per second, from the
+    /// latest access-log entry. The log reports an undeclared value as negative.
+    var indicatedBitrate: Double = -1
+    var indicatedAverageBitrate: Double = -1
     var currentTimeSeconds: Double = .nan
     var timeControlStatus: AVPlayer.TimeControlStatus = .paused
     var rate: Float = 0
@@ -146,8 +114,6 @@ final class LiveTelemetrySampler {
     private var byteWindow = RollingWindow<Int64>(capacity: 10, zero: 0)   // 10-second rolling window
     private var frameWindow = RollingWindow<Int>(capacity: 10, zero: 0)
     private var bridgeByteWindow = RollingWindow<Int64>(capacity: 10, zero: 0)
-    /// Remote-HLS bypass: AVPlayer's session transfer total stands in for the demuxer counter.
-    private var consumerTransferMeter = TransferRateMeter()
 
     private var lastDemuxerBytes: Int64 = 0
     private var lastBridgeBytes: Int64 = 0
@@ -190,7 +156,6 @@ final class LiveTelemetrySampler {
         byteWindow.reset()
         frameWindow.reset()
         bridgeByteWindow.reset()
-        consumerTransferMeter.reset()
         // Seed from CURRENT counters: a zero seed pushes all pre-start prefetch bytes into tick 1, inflating instant bitrate for ~10 s.
         lastDemuxerBytes = engine?.demuxerBytesFetched ?? 0
         lastBridgeBytes = engine?.audioBridgeOutputBytesLifetime ?? 0
@@ -239,13 +204,24 @@ final class LiveTelemetrySampler {
     enum BitrateCounter: Equatable {
         /// Bytes the engine's demuxer pulled from the source (loopback and software).
         case demuxer
-        /// Bytes AVPlayer transferred, from its access log. The remote-HLS bypass has no demuxer, so this is
-        /// the only count of what the session pulled from the origin there.
-        case consumerTransfer
+        /// The bitrate the playing variant declares, from AVPlayer's access log. The remote-HLS bypass has no
+        /// demuxer, and what AVPlayer transferred is not the stream's rate: a buffer filling after a start or
+        /// a seek pulls at link speed (22.6 Mbps measured for a 3.7 Mbps transcode). The transfer stays in the
+        /// network fields.
+        case declaredVariant
     }
 
     nonisolated static func bitrateCounter(for route: VideoRoute) -> BitrateCounter {
-        route == .remoteBypass ? .consumerTransfer : .demuxer
+        route == .remoteBypass ? .declaredVariant : .demuxer
+    }
+
+    /// Both bitrate fields from the access log's declarations, in Mbps: instant is BANDWIDTH, average is
+    /// AVERAGE-BANDWIDTH, falling back to BANDWIDTH where the master omits it. Undeclared reads nil.
+    nonisolated static func declaredBitrates(indicated: Double, indicatedAverage: Double)
+        -> (instant: Double?, average: Double?) {
+        func mbps(_ bps: Double) -> Double? { bps.isFinite && bps > 0 ? bps / 1_000_000.0 : nil }
+        let instant = mbps(indicated)
+        return (instant, mbps(indicatedAverage) ?? instant)
     }
 
     /// Whether the native branch has the loopback pipeline behind it. On the bypass the producer's A/V gap
@@ -444,12 +420,13 @@ final class LiveTelemetrySampler {
             accumulatedFrameDelaySeconds = nil
         }
 
-        // Remote-HLS bypass: no demuxer, so both rates come from what AVPlayer itself transferred, over
-        // the same window and the same active-seconds divisor. networkTransferredBytes is that total too.
-        if Self.bitrateCounter(for: route) == .consumerTransfer {
-            consumerTransferMeter.record(sessionBytes: networkTransferredBytes)
-            instantBitrateMbps = consumerTransferMeter.instantMbps
-            averageBitrateMbps = consumerTransferMeter.averageMbps(activeSeconds: activeSeconds)
+        // Remote-HLS bypass: no demuxer, so both rates are what the playing variant declares.
+        if Self.bitrateCounter(for: route) == .declaredVariant {
+            let declared = Self.declaredBitrates(
+                indicated: nativeReadings?.indicatedBitrate ?? -1,
+                indicatedAverage: nativeReadings?.indicatedAverageBitrate ?? -1)
+            instantBitrateMbps = declared.instant
+            averageBitrateMbps = declared.average
         }
 
         // Feed the extractor yield gate (#93 startup): nil on non-native paths keeps the
@@ -626,6 +603,8 @@ final class LiveTelemetrySampler {
             let observed = event.observedBitrate
             readings.networkThroughputMbps = observed.isFinite && observed > 0
                 ? observed / 1_000_000.0 : nil
+            readings.indicatedBitrate = event.indicatedBitrate
+            readings.indicatedAverageBitrate = event.indicatedAverageBitrate
         }
         // AE#443: the counters are not. They are totals PER ENTRY, and AVFoundation opens a new entry
         // whenever the playback session changes under it, so reading `.last` publishes a number that
diff --git a/Tests/AetherEngineTests/RemoteHLSTelemetryTests.swift b/Tests/AetherEngineTests/RemoteHLSTelemetryTests.swift
index ce8449b96..308a80eb5 100644
--- a/Tests/AetherEngineTests/RemoteHLSTelemetryTests.swift
+++ b/Tests/AetherEngineTests/RemoteHLSTelemetryTests.swift
@@ -4,13 +4,18 @@ import Testing
 
 /// On the `nativeRemoteHLS` bypass the sampler never ran, because its bitrate halves read the loopback's
 /// demuxer counter, and so `liveTelemetry` stayed nil for the whole session. AVPlayer's own access log is
-/// there on this route too; these pin how its session byte total becomes the same two bitrate fields.
+/// there on this route too; these pin how it fills the same two bitrate fields.
+///
+/// The fields name the stream's bitrate, so on the bypass they come from what the variant declares, not
+/// from what AVPlayer transferred: a player filling its buffer after a start or a seek pulls at link
+/// speed, and a transfer-based figure read 22.6 Mbps for a 3.7 Mbps Jellyfin transcode (device, 2026-09-28).
+/// The transfer stays in the network fields, where it belongs.
 @Suite("RemoteHLSTelemetry")
 struct RemoteHLSTelemetryTests {
 
-    @Test("the bypass meters AVPlayer's transfer, every other route the demuxer")
+    @Test("the bypass reads the variant's declared bitrate, every other route the demuxer")
     func counterPerRoute() {
-        #expect(LiveTelemetrySampler.bitrateCounter(for: .remoteBypass) == .consumerTransfer)
+        #expect(LiveTelemetrySampler.bitrateCounter(for: .remoteBypass) == .declaredVariant)
         #expect(LiveTelemetrySampler.bitrateCounter(for: .loopback) == .demuxer)
         #expect(LiveTelemetrySampler.bitrateCounter(for: .software) == .demuxer)
         #expect(LiveTelemetrySampler.bitrateCounter(for: .none) == .demuxer)
@@ -22,64 +27,27 @@ struct RemoteHLSTelemetryTests {
         #expect(LiveTelemetrySampler.readsLoopbackPipeline(.loopback))
     }
 
-    @Test("instant is the ten-second window of per-tick deltas, like the demuxer meter")
-    func instantOverWindow() {
-        var meter = TransferRateMeter()
-        meter.record(sessionBytes: 0)
-        #expect(meter.instantMbps == nil)   // one sample spans no time
-        meter.record(sessionBytes: 1_250_000)
-        meter.record(sessionBytes: 2_500_000)
-        // 2.5 MB over three one-second samples.
-        let expected: Double = 2_500_000.0 * 8.0 / 3.0 / 1_000_000.0
-        #expect(abs((meter.instantMbps ?? 0) - expected) < 0.0001)
+    @Test("instant is BANDWIDTH, average is AVERAGE-BANDWIDTH")
+    func bothDeclared() {
+        let rates = LiveTelemetrySampler.declaredBitrates(indicated: 4_000_000, indicatedAverage: 3_700_000)
+        #expect(rates.instant == 4.0)
+        #expect(rates.average == 3.7)
     }
 
-    @Test("the window forgets what is older than ten ticks")
-    func windowRolls() {
-        var meter = TransferRateMeter()
-        meter.record(sessionBytes: 50_000_000)   // startup burst
-        for i in 1...10 { meter.record(sessionBytes: 50_000_000 + Int64(i) * 125_000) }
-        #expect(abs((meter.instantMbps ?? 0) - 1.0) < 0.0001)
+    /// AVERAGE-BANDWIDTH is optional in a master; without it the peak is the only declaration there is.
+    @Test("a master without AVERAGE-BANDWIDTH reports the peak for both")
+    func averageFallsBackToPeak() {
+        let rates = LiveTelemetrySampler.declaredBitrates(indicated: 4_000_000, indicatedAverage: 0)
+        #expect(rates.instant == 4.0)
+        #expect(rates.average == 4.0)
     }
 
-    @Test("a tick with no access log yet adds nothing and keeps the last total")
-    func missingReadingIsNoDelta() {
-        var meter = TransferRateMeter()
-        meter.record(sessionBytes: 1_000_000)
-        meter.record(sessionBytes: nil)
-        meter.record(sessionBytes: 1_000_000)
-        #expect(meter.lifetimeBytes == 1_000_000)
-        meter.record(sessionBytes: 2_000_000)
-        #expect(meter.lifetimeBytes == 2_000_000)
-    }
-
-    /// The folded total never falls (AE#443), but a counter that did must not make the next rise count twice.
-    @Test("a total that falls back is not counted again when it recovers")
-    func fallingTotalIsNotRecounted() {
-        var meter = TransferRateMeter()
-        meter.record(sessionBytes: 3_000_000)
-        meter.record(sessionBytes: 1_000_000)
-        meter.record(sessionBytes: 3_000_000)
-        #expect(meter.lifetimeBytes == 3_000_000)
-        #expect(meter.windowBytes == 3_000_000)
-    }
-
-    @Test("the average is the lifetime transfer over the active seconds, nil until both exist")
-    func average() {
-        var meter = TransferRateMeter()
-        #expect(meter.averageMbps(activeSeconds: 10) == nil)
-        meter.record(sessionBytes: 2_500_000)
-        #expect(meter.averageMbps(activeSeconds: 0) == nil)
-        #expect(abs((meter.averageMbps(activeSeconds: 10) ?? 0) - 2.0) < 0.0001)
-    }
-
-    @Test("reset starts a new session from zero")
-    func reset() {
-        var meter = TransferRateMeter()
-        meter.record(sessionBytes: 5_000_000)
-        meter.record(sessionBytes: 6_000_000)
-        meter.reset()
-        #expect(meter.lifetimeBytes == 0)
-        #expect(meter.instantMbps == nil)
+    /// The access log reports an unknown bitrate as a negative number or zero.
+    @Test("nothing declared is nil, not a measured zero")
+    func nothingDeclared() {
+        let rates = LiveTelemetrySampler.declaredBitrates(indicated: -1, indicatedAverage: -1)
+        #expect(rates.instant == nil)
+        #expect(rates.average == nil)
+        #expect(LiveTelemetrySampler.declaredBitrates(indicated: .nan, indicatedAverage: .infinity).instant == nil)
     }
 }
diff --git a/docs/api.md b/docs/api.md
index 390ace97c..9760f6f35 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -925,7 +925,7 @@ as well.
 | Symbol | Notes |
 | --- | --- |
 | `AetherEngine.version` | The engine release this source descends from, as the string a published tag carries. SwiftPM resolves a package to a revision rather than to a tag, so an About panel or the header of a diagnostic log has nothing else to name the engine with. Between releases, and under a pin on an unreleased commit, it names the last published version the checkout descends from. |
-| `diagnostics.liveTelemetry` | 1 Hz `LiveTelemetry?` snapshot while playing or paused, nil while idle. On a separate `ObservableObject` so its ticks cannot re-render a host observing the engine. On `.remoteBypass` it is fed from AVPlayer's access log alone: `instantBitrateMbps` and `averageBitrateMbps` are metered from the bytes AVPlayer transferred (10 s window, and lifetime over active seconds, the same shape the demuxer meter has elsewhere), `networkThroughputMbps` is the access log's `observedBitrate`, `networkTransferredBytes` and `droppedFrameCount` its session totals, `forwardBufferSeconds` the loaded range ahead of the playhead. `avSyncGapMs` and `observedFps` are nil, and the loopback counters (`producerRestartCount`, `muxedBytesLifetime`, `serverBytesSentLifetime`, `serverRequestCount`, `demuxerBytesFetched`) read 0 because there is no loopback. |
+| `diagnostics.liveTelemetry` | 1 Hz `LiveTelemetry?` snapshot while playing or paused, nil while idle. On a separate `ObservableObject` so its ticks cannot re-render a host observing the engine. On `.remoteBypass` it is fed from AVPlayer's access log alone: `instantBitrateMbps` and `averageBitrateMbps` are what the playing variant declares (BANDWIDTH, and AVERAGE-BANDWIDTH or BANDWIDTH where the master omits it), because the bytes AVPlayer transferred are buffer fill at link speed rather than the stream's rate, `networkThroughputMbps` is the access log's `observedBitrate`, `networkTransferredBytes` and `droppedFrameCount` its session totals, `forwardBufferSeconds` the loaded range ahead of the playhead. `avSyncGapMs` and `observedFps` are nil, and the loopback counters (`producerRestartCount`, `muxedBytesLifetime`, `serverBytesSentLifetime`, `serverRequestCount`, `demuxerBytesFetched`) read 0 because there is no loopback. |
 | `LiveTelemetry.softwareCacheSeekHits`, `softwareCacheSeekMisses`, `softwareCacheSourceEpoch` | Optional cumulative software-VOD packet-cache counters. A hit repositions the retained consumer cursor without changing the source epoch; a miss repositions the demuxer and advances it. `nil` on other paths. `cachedBytes` includes retained compressed packet records on software VOD, distinct from decoded `displayCushionSeconds` and the underlying byte-reader window. |
 | `EngineLog.handler` | Mirror every info-level line into a host capture path. Fires from whatever thread emitted it, so it must be thread-safe and non-blocking. |
 | `EngineLog.subsystem`, `EngineLog.Category` | `de.superuser404.AetherEngine`, one category per subsystem: `engine`, `ffmpeg`, `session`, `muxer`, `demux`, `hls.server`, `audio.bridge`, `sw.playback`, `scrub`. |

From d00d9dd2db1848214d3c025c14fa89e22909e204 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Mon, 28 Sep 2026 17:01:30 +0200
Subject: [PATCH 139/359] chore(release): prep 7.22.0 - the remote-HLS bypass
 publishes what a stats panel reads

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mf4MXgM9bqugHoe5TW4BYf
---
 CHANGELOG.md                                  | 19 +++++++++++++++++++
 Examples/README.md                            |  2 +-
 README.md                                     |  6 +++---
 .../AetherEngine/AetherEngine+Version.swift   |  2 +-
 4 files changed, 24 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 31f294586..44b65b10b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,25 @@ the public-API contract.
 
 _Nothing yet._
 
+## [7.22.0] - 2026-09-28
+
+### Changed
+
+- **The remote-HLS bypass publishes what a stats panel reads.** On `nativeRemoteHLS` (route
+  `.remoteBypass`) the engine published no `liveTelemetry`, an empty `audioTracks` and no delivered
+  video format, so a host fell back to its own metadata for the original file: a 1280x720 H.264 Jellyfin
+  transcode showed as "3840x2160, Main 10, 17 Mbps". Everything is now read from AVPlayer's own item, with
+  no second connection to the origin (#664):
+  - `diagnostics.liveTelemetry` runs on the bypass. The two bitrate fields are what the playing variant
+    declares (BANDWIDTH, and AVERAGE-BANDWIDTH or BANDWIDTH where the master omits it), because what
+    AVPlayer transferred is buffer fill at link speed. Network throughput, transferred bytes, dropped
+    frames and forward buffer come from the access log and the loaded ranges. The loopback counters read 0.
+  - `audioTracks` carries one `TrackInfo` per audio track AVPlayer built (codec, channels, sample rate,
+    profile, Atmos, language), ids from 400000. `selectAudioTrack` is informational on this route and
+    logs instead of acting.
+  - `sourceVideoWidth`, `sourceVideoHeight` and `sourceVideoStreamFormat` describe the stream AVPlayer
+    plays. Under a server-side transcode that is the transcode, not the library's file.
+
 ## [7.21.1] - 2026-09-27
 
 ### Fixed
diff --git a/Examples/README.md b/Examples/README.md
index 17813345c..4a4a97ffb 100644
--- a/Examples/README.md
+++ b/Examples/README.md
@@ -18,7 +18,7 @@ Three samples covering different audiences:
    ```
    https://github.com/superuser404notfound/AetherEngine
    ```
-   Dependency Rule: Up to Next Major Version, starting from `7.21.1`. Add the `AetherEngine` library product to your app target.
+   Dependency Rule: Up to Next Major Version, starting from `7.22.0`. Add the `AetherEngine` library product to your app target.
 
 3. **Drop the file in.** Replace the Xcode template's default `App.swift` (or whatever the generated `@main` file is called) with the contents of [`MinimalPlayerApp.swift`](MinimalPlayer/MinimalPlayerApp.swift). The file is self-contained: it defines both the `@main App` struct and the `ContentView`.
 
diff --git a/README.md b/README.md
index 3577c3fee..44beef23a 100644
--- a/README.md
+++ b/README.md
@@ -384,7 +384,7 @@ Subtitle cues land in raw source PTS; render the overlay against `player.sourceT
 Install via Swift Package Manager:
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.21.1")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.22.0")
 ```
 
 Three samples ship in `Examples/`:
@@ -631,10 +631,10 @@ Browse all of this as a searchable site at **[aetherengine.superuser404.de](http
 AetherEngine uses [Semantic Versioning](https://semver.org). The public API surface, every `public` declaration in `Sources/AetherEngine/`, is the stability contract. **Major** removes / renames public symbols or breaks adopters; **Minor** adds public API or codec / format support; **Patch** fixes bugs with no public API change. `internal` types are not part of the contract.
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.21.1")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.22.0")
 ```
 
-Pin to `.upToNextMinor(from: "7.21.1")` for stricter teams that prefer to opt into minor bumps explicitly.
+Pin to `.upToNextMinor(from: "7.22.0")` for stricter teams that prefer to opt into minor bumps explicitly.
 
 ## Requirements
 
diff --git a/Sources/AetherEngine/AetherEngine+Version.swift b/Sources/AetherEngine/AetherEngine+Version.swift
index 7b72551f4..e1cf164fa 100644
--- a/Sources/AetherEngine/AetherEngine+Version.swift
+++ b/Sources/AetherEngine/AetherEngine+Version.swift
@@ -11,5 +11,5 @@ extension AetherEngine {
     ///
     /// Between releases, and in a consumer that pins an unreleased commit for a device test, this
     /// names the last PUBLISHED version the checkout descends from, not every patch in it.
-    public nonisolated static let version = "7.21.1"
+    public nonisolated static let version = "7.22.0"
 }

From 7be84668b320417284232a972d65077d2d4427de Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Mon, 28 Sep 2026 19:38:06 +0200
Subject: [PATCH 140/359] test(relay): look for origin fragments long enough to
 mean something

localURLCarriesNoOriginText checked that the relay URL does not contain "jf",
but the reference in that URL is random base64 of about 190 characters, which
contains any given two-letter pair on roughly one run in twenty. It failed the
7.22.0 release run on main that way ("...BjyjfBTh..."), with the code
unchanged since its green PR run. The fragments are now the ones that would
actually give the origin away (jf.example, master.m3u8, api_key); 40 runs in a
row are green.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mf4MXgM9bqugHoe5TW4BYf
---
 Tests/AetherEngineTests/HLSOriginRelayTests.swift | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/Tests/AetherEngineTests/HLSOriginRelayTests.swift b/Tests/AetherEngineTests/HLSOriginRelayTests.swift
index 8c6ea1b8e..91f0f76e0 100644
--- a/Tests/AetherEngineTests/HLSOriginRelayTests.swift
+++ b/Tests/AetherEngineTests/HLSOriginRelayTests.swift
@@ -36,7 +36,9 @@ struct HLSOriginRelayAddressingTests {
             string: "https://jf.example.com/Videos/abc/master.m3u8?MediaSourceId=x&api_key=\(secret)")!
         let local = try #require(relay.localURL(for: origin, port: 51234, token: token))
         let text = local.absoluteString
-        for fragment in [secret, "jf", "example", "Videos", "master", "api", "MediaSourceId"] {
+        // Fragments long enough to mean something: the reference is random base64, and a two-letter
+        // fragment ("jf") turns up in it by chance on about one run in twenty (CI, 2026-09-28).
+        for fragment in [secret, "jf.example", "example", "Videos", "master.m3u8", "api_key", "MediaSourceId"] {
             #expect(!text.contains(fragment), "\(fragment) is readable in \(text)")
         }
         #expect(!text.contains("%"), "the reference should need no escaping: \(text)")

From c0a6917ad8dee280f9ee1ad00ccf2f6af1071e44 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Tue, 29 Sep 2026 16:52:35 +0200
Subject: [PATCH 141/359] fix(telemetry): meter both bitrate fields over the
 media played, not the transfer (#514)

Round one fixed the divisor of averageBitrateMbps; the reporter's retest
showed the numerator was the other half of the same defect. Both fields
were metered from demuxerBytesFetched, the reader's transfer counter,
which parts from playback on every route that reads ahead: VOD prefetch
and seek re-fetches counted as they arrived (a 20 Mbps stream read about
35), and a paused live session kept draining its origin into the DVR
window (AE#443) while the divisor stood still, so its average climbed
for as long as the pause ran.

The pumps now record the played video and audio packets by presentation
time into a PlayedMediaLedger (native producer next to the recording
tap, software host after its timeline fold), and PlayedBitrateMeter
charges what the playhead crossed on the same source axis: AVPlayer's
clock plus the playlist shift on native, the synchronizer's source clock
on software. A pause and a seek charge nothing, a re-fetched range is
held once, and a span the ledger holds nothing for stays unmeasured
(nil) rather than reading zero. The transfer stays in
networkThroughputMbps and [LagDiag]; the remote-HLS bypass keeps its
declared rates.

Measured with aetherctl over HTTP, pause at 12 s, seek at 15 s:
- native 18.2 Mbps H.264: main avg 723 -> 103 -> 52, fix 18.4 to 19.0
- software 8.9 Mbps VP9: main avg 385 -> 54 -> 26, fix 8.8 to 9.5
Live 8.17 Mbps TS, DVR 300 s, paused 50 s:
- main avg climbs 23 -> 64 (native), 29 -> 71 (software)
- fix holds 8.12 / 8.07 through the pause, 8.0 after

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                                  |  13 +-
 .../AetherEngine+Diagnostics.swift            |   6 +
 .../Diagnostics/LiveTelemetry.swift           |  22 +-
 .../Diagnostics/LiveTelemetrySampler.swift    | 113 +++----
 .../Diagnostics/PlayedMediaLedger.swift       | 171 ++++++++++
 .../Native/SoftwarePlaybackHost.swift         |  28 +-
 .../Video/HLSSegmentProducer.swift            |  33 +-
 .../AetherEngine/Video/HLSVideoEngine.swift   |   5 +
 .../Issue514AverageBitrateTests.swift         | 304 +++++++++++-------
 docs/api.md                                   |   2 +-
 10 files changed, 503 insertions(+), 194 deletions(-)
 create mode 100644 Sources/AetherEngine/Diagnostics/PlayedMediaLedger.swift

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 44b65b10b..29594328c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,7 +10,18 @@ the public-API contract.
 
 ## [Unreleased]
 
-_Nothing yet._
+### Fixed
+
+- **`LiveTelemetry`'s two bitrate fields measure the media played, not the bytes transferred** (#514).
+  Both were metered from the reader's transfer counter, which parts from playback on every route that
+  reads ahead: a 20 Mbps VOD stream read about 35 Mbps (prefetch and seek re-fetches counted as they
+  arrived), and a paused live session kept draining its origin into the DVR window while the divisor
+  stood still, so its average climbed for as long as the pause ran. The pumps now record the played
+  video and audio packets by presentation time, and the sampler charges what the playhead crossed:
+  `instantBitrateMbps` over about the last 10 s of playback, `averageBitrateMbps` over the session.
+  Both stand still through a pause on every route, live included, and a seek charges nothing for the
+  span it jumps. The transfer remains `networkThroughputMbps`. The remote-HLS bypass is unchanged (it
+  reports the variant's declared rates).
 
 ## [7.22.0] - 2026-09-28
 
diff --git a/Sources/AetherEngine/AetherEngine+Diagnostics.swift b/Sources/AetherEngine/AetherEngine+Diagnostics.swift
index ca97196f2..875dde213 100644
--- a/Sources/AetherEngine/AetherEngine+Diagnostics.swift
+++ b/Sources/AetherEngine/AetherEngine+Diagnostics.swift
@@ -506,6 +506,12 @@ extension AetherEngine {
                               native: nativeVideoSession?.demuxerBytesFetched)
     }
 
+    /// AE#514: the played-media ledger of whichever path owns the pump, same precedence as the byte
+    /// counter above. nil before a pipeline exists and on the paths with no pump to feed one.
+    var playedMediaLedger: PlayedMediaLedger? {
+        softwareHost?.playedMediaLedger ?? nativeVideoSession?.playedMediaLedger
+    }
+
     /// #306: the precedence itself, as a function, so the ordering is assertable without a live
     /// session on either path. Software first: only one of the two exists per session, and a
     /// software session's counter is the one that used to be dropped.
diff --git a/Sources/AetherEngine/Diagnostics/LiveTelemetry.swift b/Sources/AetherEngine/Diagnostics/LiveTelemetry.swift
index 35616425b..8c5b89554 100644
--- a/Sources/AetherEngine/Diagnostics/LiveTelemetry.swift
+++ b/Sources/AetherEngine/Diagnostics/LiveTelemetry.swift
@@ -9,16 +9,20 @@ import Foundation
 /// interpret a sub-second decoded queue as the size of the compressed packet cache.
 public struct LiveTelemetry: Equatable, Sendable {
     // Enthusiast section
-    /// Mean rate over the last 10 s of the bytes the session pulled from its source, from the demuxer's
-    /// count on the loopback and software paths. nil until the window spans two ticks. The remote-HLS
-    /// bypass has no demuxer, and what AVPlayer transferred there is buffer fill at link speed rather than
-    /// the stream's rate, so on that route this is the playing variant's declared BANDWIDTH.
+    /// Rate of the media the playhead crossed over about the last 10 s of playback: the bytes of the
+    /// played video and audio packets presented in that span, over the media seconds it covered
+    /// (AE#514). Not the transfer, which is `networkThroughputMbps`: a read-ahead, a re-fetch after a
+    /// seek and a live source draining into its DVR window while paused all move bytes that nobody
+    /// played. Stands still through a pause, on live too. nil until the playhead has crossed a span the
+    /// session has bytes for. The remote-HLS bypass has no demuxer, so on that route this is the playing
+    /// variant's declared BANDWIDTH.
     public let instantBitrateMbps: Double?
-    /// Lifetime mean rate of the session, over the seconds it spent consuming media rather than over
-    /// wall-clock seconds since it started (AE#514). Metered from the same counter as `instantBitrateMbps`; on the remote-HLS bypass it is the variant's declared AVERAGE-BANDWIDTH, or BANDWIDTH where the master omits it. A pause therefore leaves this value standing
-    /// still instead of dragging it toward zero for as long as the pause lasts, and so does the tail
-    /// after end-of-media. nil until the session has both accrued active time and fetched something:
-    /// like `networkThroughputMbps`, a value that cannot be measured yet is a gap, never a zero.
+    /// Lifetime mean of the same quotient: every played byte over every media second played this
+    /// session (AE#514). A seek charges nothing for the span it jumped, a pause and the tail after
+    /// end-of-media charge nothing at all, and the prefetch counts once it is played, not when it
+    /// arrives. On the remote-HLS bypass it is the variant's declared AVERAGE-BANDWIDTH, or BANDWIDTH
+    /// where the master omits it. nil until something was played: like `networkThroughputMbps`, a value
+    /// that cannot be measured yet is a gap, never a zero.
     public let averageBitrateMbps: Double?
     /// Live bitrate of the audio bridge's encoded output, or nil when no bridge is active (stream-copy /
     /// AVPlayer-native path) or before the first delta. Measured from the bridge's cumulative output-byte
diff --git a/Sources/AetherEngine/Diagnostics/LiveTelemetrySampler.swift b/Sources/AetherEngine/Diagnostics/LiveTelemetrySampler.swift
index 7bc50ad64..104f8e06b 100644
--- a/Sources/AetherEngine/Diagnostics/LiveTelemetrySampler.swift
+++ b/Sources/AetherEngine/Diagnostics/LiveTelemetrySampler.swift
@@ -118,16 +118,16 @@ final class LiveTelemetrySampler {
     private var lastDemuxerBytes: Int64 = 0
     private var lastBridgeBytes: Int64 = 0
     private var lastFramesEnqueued: Int = 0
-    private var sessionStartBytes: Int64 = 0
 
-    /// AE#514: wall-clock seconds this session spent in a phase that consumes media, accumulated one
-    /// tick at a time. The divisor of the lifetime average, in place of the wall clock since start.
-    /// Readable so a test can pin that the tick charges it, not only that the fold over it is right.
-    private(set) var activeSeconds: Double = 0
+    /// AE#514: both bitrate fields, metered over what the playhead crossed. Readable so a test can pin
+    /// that the tick feeds it, not only that the meter is right.
+    private(set) var playedMeter = PlayedBitrateMeter()
 
-    /// Timestamp of the previous tick, anchoring the delta charged above. nil until the first tick,
-    /// which therefore charges nothing: that is also the tick which seeds `sessionStartBytes`, so the
-    /// numerator and the divisor start counting at the same instant.
+    /// The ledger the meter was last advanced against. A different one is a different session, whose
+    /// playhead and bytes have nothing to do with the old meter's.
+    private var meterLedger: ObjectIdentifier?
+
+    /// Timestamp of the previous tick: the wall time the playhead had to cover its step in.
     private var lastTickTime: Date?
 
     /// [LagDiag] tick-over-tick state (#93 post-recovery lag diagnosis).
@@ -160,9 +160,9 @@ final class LiveTelemetrySampler {
         lastDemuxerBytes = engine?.demuxerBytesFetched ?? 0
         lastBridgeBytes = engine?.audioBridgeOutputBytesLifetime ?? 0
         lastFramesEnqueued = 0
-        activeSeconds = 0
+        playedMeter = PlayedBitrateMeter()
+        meterLedger = nil
         lastTickTime = nil
-        sessionStartBytes = 0
         lagLastClock = nil
         lagLastDroppedSum = 0
         eomParkFrozenTicks = 0
@@ -231,78 +231,48 @@ final class LiveTelemetrySampler {
         route != .remoteBypass
     }
 
-    /// AE#514: whether a tick's second belongs in the lifetime average's divisor.
-    ///
-    /// That average used to divide by wall-clock time since the session started, which made a pause
-    /// permanently wrong in one direction. `demuxerBytesFetched` stops advancing once the forward
-    /// buffer is full, the wall clock does not, so a 2.8 Mbps file left paused for three minutes
-    /// reported 0.4 Mbps and afterwards climbed back only asymptotically: the paused seconds never
-    /// left the divisor again. Same shape at the end of a source, where the sampler keeps ticking
-    /// until the host tears the session down.
-    ///
-    /// The line is drawn at "is the session consuming media", not at "is the picture moving". A seek
-    /// and a rebuffer are where the bytes arrive hardest, and a stalled reader is a real part of what
-    /// this session averaged, so charging their seconds is what keeps the quotient equal to the rate
-    /// the session pulled at. Only a pause and the three phases with no live session behind them
-    /// stand outside it.
-    static func chargesActiveTime(_ phase: PlaybackPhase) -> Bool {
-        switch phase {
-        case .paused, .idle, .ended, .error:
-            return false
-        case .loading, .playing, .seeking, .rebuffering, .stalled:
-            return true
+    /// AE#514: where the playhead stands on the axis the played-media ledger is keyed on, the source
+    /// axis the pumps read packets on. Native folds AVPlayer's clock back with the producer's shift
+    /// (`source_pts - playlistShiftSeconds`) rather than reading `sourceTime`, which publishes the item
+    /// axis on a sequential origin (#368). nil where there is no ledger-fed pipeline to read it off.
+    nonisolated static func ledgerPlayhead(backend: PlaybackBackend, nativeClock: Double?, playlistShift: Double,
+                               softwareSourceClock: Double?) -> Double? {
+        switch backend {
+        case .native:
+            guard let nativeClock, nativeClock.isFinite else { return nil }
+            return nativeClock + playlistShift
+        case .software:
+            return softwareSourceClock
+        case .aether, .none, .audio:
+            return nil
         }
     }
 
-    /// Lifetime mean of the bytes the session fetched over the seconds it spent consuming them (AE#514).
-    ///
-    /// nil rather than zero until both halves are measurable, mirroring `observedTransferMbps`: a host
-    /// cannot tell a confident 0.00 Mbps from a session that has not fetched anything yet. The old
-    /// wall-clock form published exactly that on its first tick, where the lifetime delta is zero by
-    /// construction because the same tick seeds the baseline it then subtracts.
-    static func averageBitrateMbps(lifetimeBytes: Int64, activeSeconds: Double) -> Double? {
-        guard activeSeconds > 0, lifetimeBytes > 0 else { return nil }
-        return Double(lifetimeBytes) * 8.0 / activeSeconds / 1_000_000.0
-    }
-
     private func tick() async {
         guard let engine = engine else { return }
 
-        // AE#514: this tick's wall-clock second goes into the lifetime average's divisor only if the
-        // session was consuming media in it. See `chargesActiveTime` for where the line runs.
         let tickTime = Date()
-        if let previous = lastTickTime, Self.chargesActiveTime(engine.playbackPhase) {
-            activeSeconds += tickTime.timeIntervalSince(previous)
-        }
+        let wallSeconds = lastTickTime.map { tickTime.timeIntervalSince($0) } ?? 0
         lastTickTime = tickTime
 
         let route = engine.videoRoute
 
-        // Instant + average bitrate from demuxer byte counters (loopback and SW; the bypass overrides below)
+        // What the reader pulled from the source. Transfer, not media rate: it feeds the network fields
+        // and [LagDiag], never the bitrate fields (AE#514, see `playedMeter`).
         let demuxerBytes = engine.demuxerBytesFetched
         let bytesThisTick = max(0, demuxerBytes - lastDemuxerBytes)
         lastDemuxerBytes = demuxerBytes
-        if sessionStartBytes == 0 { sessionStartBytes = demuxerBytes }
         byteWindow.push(bytesThisTick)
 
-        var instantBitrateMbps: Double?
-        if byteWindow.count >= 2 {
-            let totalBytes = byteWindow.sum
-            let seconds = Double(byteWindow.count)
-            instantBitrateMbps = Double(totalBytes) * 8.0 / seconds / 1_000_000.0
-        } else {
-            instantBitrateMbps = nil
-        }
+        let transferMbps: Double? = byteWindow.count >= 2
+            ? Double(byteWindow.sum) * 8.0 / Double(byteWindow.count) / 1_000_000.0
+            : nil
 
         let observedTransferMbps = Self.observedTransferMbps(
             windowBytes: byteWindow.sum,
             activeSeconds: byteWindow.activeCount,
             samples: byteWindow.count)
 
-        var averageBitrateMbps = Self.averageBitrateMbps(
-            lifetimeBytes: max(0, demuxerBytes - sessionStartBytes),
-            activeSeconds: activeSeconds)
-
         // Live audio-bridge output bitrate from the bridge's cumulative encoded-byte counter. 0 on the
         // stream-copy / AVPlayer-native / video-only paths (no bridge), which surfaces as nil.
         let bridgeBytes = engine.audioBridgeOutputBytesLifetime
@@ -420,6 +390,27 @@ final class LiveTelemetrySampler {
             accumulatedFrameDelaySeconds = nil
         }
 
+        // AE#514: the bitrate fields are the media the playhead crossed, never the transfer.
+        var instantBitrateMbps: Double?
+        var averageBitrateMbps: Double?
+        if let ledger = engine.playedMediaLedger {
+            let identity = ObjectIdentifier(ledger)
+            if meterLedger != identity {
+                meterLedger = identity
+                playedMeter = PlayedBitrateMeter()
+            }
+            playedMeter.advance(
+                to: Self.ledgerPlayhead(
+                    backend: engine.playbackBackend,
+                    nativeClock: nativeReadings?.currentTimeSeconds,
+                    playlistShift: engine.playlistShiftSeconds,
+                    softwareSourceClock: engine.softwareHost?.sourceClockSeconds),
+                wallSeconds: wallSeconds,
+                ledger: ledger)
+            instantBitrateMbps = playedMeter.instantMbps
+            averageBitrateMbps = playedMeter.averageMbps
+        }
+
         // Remote-HLS bypass: no demuxer, so both rates are what the playing variant declares.
         if Self.bitrateCounter(for: route) == .declaredVariant {
             let declared = Self.declaredBitrates(
@@ -434,7 +425,7 @@ final class LiveTelemetrySampler {
         engine.extractorYieldState.setForwardBuffer(forwardBufferSeconds)
 
         if let readings = nativeReadings {
-            emitLagDiag(engine: engine, readings: readings, netMbps: instantBitrateMbps)
+            emitLagDiag(engine: engine, readings: readings, netMbps: transferMbps)
             if Self.readsLoopbackPipeline(route) {
                 evaluateEndOfMediaPark(engine: engine, readings: readings)
             }
diff --git a/Sources/AetherEngine/Diagnostics/PlayedMediaLedger.swift b/Sources/AetherEngine/Diagnostics/PlayedMediaLedger.swift
new file mode 100644
index 000000000..c6585e05e
--- /dev/null
+++ b/Sources/AetherEngine/Diagnostics/PlayedMediaLedger.swift
@@ -0,0 +1,171 @@
+import Foundation
+
+/// AE#514 round 2: the bytes of the media the session plays, keyed by presentation time on the source
+/// axis, so the bitrate fields can be metered from what the playhead crossed rather than from what the
+/// reader transferred.
+///
+/// The transfer counter and playback part ways on every route that reads ahead: VOD prefetches minutes
+/// in front of the playhead, a seek discards a buffer and fetches it again, and a paused live session
+/// keeps draining the origin into its DVR window (AE#443). A rate metered off that counter reported the
+/// prefetch (35 Mbps for a 20 Mbps stream) and climbed without bound through a live pause.
+///
+/// The pump records every packet of the played video and audio streams as it hands them on; the
+/// sampler consumes the span the playhead crossed since its last tick. Thread-safe: the pump records
+/// on its read thread, the sampler consumes on the main actor.
+final class PlayedMediaLedger: @unchecked Sendable {
+
+    enum Track: Int, CaseIterable {
+        case video = 0
+        case audio = 1
+    }
+
+    private struct Entry {
+        let pts: Double
+        var bytes: Int
+    }
+
+    /// A packet this far behind the newest one on its track is a re-read (a seek replaying a range the
+    /// reader already delivered), not B-frame reorder, which stays well under a second.
+    static let rereadThresholdSeconds: Double = 2.0
+
+    /// Entries held across both tracks. A VOD read-ahead of several minutes stays far below it; past
+    /// it the farthest-ahead packets go unrecorded, so the span they cover later reads as unmeasured
+    /// rather than as a lower rate.
+    static let maxEntries = 262_144
+
+    private let lock = NSLock()
+    private var tracks: [[Entry]] = Array(repeating: [], count: Track.allCases.count)
+    private var count = 0
+
+    /// Records one played packet. `pts` is in seconds on the source axis, the axis the playhead the
+    /// sampler hands `consume` is on.
+    func record(_ track: Track, pts: Double, bytes: Int) {
+        guard pts.isFinite, bytes > 0 else { return }
+        lock.lock()
+        defer { lock.unlock() }
+        var entries = tracks[track.rawValue]
+        tracks[track.rawValue] = []
+        defer { tracks[track.rawValue] = entries }
+
+        if let newest = entries.last?.pts, pts < newest - Self.rereadThresholdSeconds {
+            let cut = Self.lowerBound(entries, pts)
+            count -= entries.count - cut
+            entries.removeSubrange(cut...)
+        }
+        var index = entries.count
+        while index > 0, entries[index - 1].pts > pts { index -= 1 }
+        if index > 0, entries[index - 1].pts == pts {
+            entries[index - 1].bytes = bytes
+            return
+        }
+        guard count < Self.maxEntries else { return }
+        entries.insert(Entry(pts: pts, bytes: bytes), at: index)
+        count += 1
+    }
+
+    /// Bytes of every packet presented in `[from, to)`, which leave the ledger with everything before `to`.
+    func consume(from: Double, to: Double) -> Int64 {
+        lock.lock()
+        defer { lock.unlock() }
+        var total: Int64 = 0
+        for track in tracks.indices {
+            let start = Self.lowerBound(tracks[track], from)
+            let end = Self.lowerBound(tracks[track], to)
+            if start < end {
+                for entry in tracks[track][start..<end] { total += Int64(entry.bytes) }
+            }
+            dropLocked(track, below: end)
+        }
+        return total
+    }
+
+    /// Forgets everything presented before `pts` without charging it: the playhead jumped over it.
+    func discard(below pts: Double) {
+        lock.lock()
+        defer { lock.unlock() }
+        for track in tracks.indices {
+            dropLocked(track, below: Self.lowerBound(tracks[track], pts))
+        }
+    }
+
+    var entryCount: Int {
+        lock.lock()
+        defer { lock.unlock() }
+        return count
+    }
+
+    private func dropLocked(_ track: Int, below end: Int) {
+        guard end > 0 else { return }
+        tracks[track].removeFirst(end)
+        count -= end
+    }
+
+    private static func lowerBound(_ entries: [Entry], _ pts: Double) -> Int {
+        var low = 0, high = entries.count
+        while low < high {
+            let mid = (low + high) / 2
+            if entries[mid].pts < pts { low = mid + 1 } else { high = mid }
+        }
+        return low
+    }
+}
+
+/// AE#514 round 2: both bitrate fields over the media the playhead crossed. Advanced once per sampler
+/// tick with the playhead on the ledger's axis.
+///
+/// A step forward no larger than playback could have covered in the tick is charged: its bytes from the
+/// ledger, its media seconds as the divisor. Anything else is a seek or a jump and charges nothing, and a
+/// paused playhead does not move, so both values stand still through a pause on every route, live
+/// included. A step whose span the ledger holds no bytes for is left out too (the ledger was not fed
+/// there, or its axis does not line up with this playhead): an unmeasured span is a gap, never a zero.
+struct PlayedBitrateMeter {
+
+    /// Fastest playback the charge accepts, as media seconds per wall second, plus a fixed slack for
+    /// tick jitter. Past that the playhead jumped.
+    static let maxRate: Double = 4.0
+    static let stepSlackSeconds: Double = 0.5
+
+    /// Charged ticks the instant value averages over, about the last ten seconds of playback.
+    static let windowTicks = 10
+
+    private var lastPlayhead: Double?
+    private var window: [(bytes: Int64, seconds: Double)] = []
+    private(set) var lifetimeBytes: Int64 = 0
+    private(set) var lifetimeSeconds: Double = 0
+
+    mutating func advance(to playhead: Double?, wallSeconds: Double, ledger: PlayedMediaLedger) {
+        guard let playhead, playhead.isFinite else { return }
+        defer { lastPlayhead = playhead }
+        guard let last = lastPlayhead else {
+            ledger.discard(below: playhead)
+            return
+        }
+        let step = playhead - last
+        guard step != 0 else { return }
+        guard step > 0, step <= max(0, wallSeconds) * Self.maxRate + Self.stepSlackSeconds else {
+            ledger.discard(below: playhead)
+            return
+        }
+        let bytes = ledger.consume(from: last, to: playhead)
+        guard bytes > 0 else { return }
+        lifetimeBytes += bytes
+        lifetimeSeconds += step
+        window.append((bytes, step))
+        if window.count > Self.windowTicks { window.removeFirst(window.count - Self.windowTicks) }
+    }
+
+    /// Mean rate of the last `windowTicks` charged ticks. nil before the first one.
+    var instantMbps: Double? {
+        let seconds = window.reduce(0) { $0 + $1.seconds }
+        let bytes = window.reduce(Int64(0)) { $0 + $1.bytes }
+        return Self.mbps(bytes: bytes, seconds: seconds)
+    }
+
+    /// Mean rate of everything played this session. nil before the first charged tick.
+    var averageMbps: Double? { Self.mbps(bytes: lifetimeBytes, seconds: lifetimeSeconds) }
+
+    private static func mbps(bytes: Int64, seconds: Double) -> Double? {
+        guard seconds > 0, bytes > 0 else { return nil }
+        return Double(bytes) * 8.0 / seconds / 1_000_000.0
+    }
+}
diff --git a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
index 1a64784d4..b16f70c84 100644
--- a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
+++ b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
@@ -54,6 +54,10 @@ final class SoftwarePlaybackHost {
         demuxer?.avioBytesFetched
     }
 
+    /// AE#514: bytes of the played streams by presentation time on the source axis (the axis of
+    /// `sourceClockSeconds`), fed by the read loops once the timeline fold has been applied.
+    nonisolated let playedMediaLedger = PlayedMediaLedger()
+
     @Published private(set) var isReady: Bool = false
     @Published private(set) var currentTime: Double = 0
     /// Raw synchronizer clock in the SOURCE axis (same axis as demuxed packet PTS and
@@ -1675,6 +1679,7 @@ final class SoftwarePlaybackHost {
         let getSubtitleTapSink: @Sendable () -> ((@Sendable (Int32, UnsafeMutablePointer<AVPacket>, AVRational, Bool) -> Void)?) = { [weak self] in
             self?.subtitleTapSink
         }
+        let playedMediaLedger = playedMediaLedger
         // AE#560: both read loops hand every source packet to this before any branching.
         let recordingTap: @Sendable (UnsafeMutablePointer<AVPacket>) -> Void = { [weak self] pkt in
             self?.tapForRecording(pkt)
@@ -1780,7 +1785,8 @@ final class SoftwarePlaybackHost {
                     subtitleTimeBases: subTimeBases,
                     splitDisplaySetSubtitleStreamIndices: subSplitSetIndices,
                     subtitleTapSink: getSubtitleTapSink,
-                    recordingTap: recordingTap
+                    recordingTap: recordingTap,
+                    playedMedia: playedMediaLedger
                 )
             }
             let lookahead = audioLookahead
@@ -1855,7 +1861,8 @@ final class SoftwarePlaybackHost {
                 subtitleTimeBases: subTimeBases,
                 splitDisplaySetSubtitleStreamIndices: subSplitSetIndices,
                 subtitleTapSink: getSubtitleTapSink,
-                recordingTap: recordingTap
+                recordingTap: recordingTap,
+                playedMedia: playedMediaLedger
             )
         }
     }
@@ -1879,7 +1886,8 @@ final class SoftwarePlaybackHost {
         subtitleTimeBases: [Int32: AVRational] = [:],
         splitDisplaySetSubtitleStreamIndices: Set<Int32> = [],
         subtitleTapSink: @Sendable () -> ((@Sendable (Int32, UnsafeMutablePointer<AVPacket>, AVRational, Bool) -> Void)?) = { nil },
-        recordingTap: @escaping @Sendable (UnsafeMutablePointer<AVPacket>) -> Void = { _ in }
+        recordingTap: @escaping @Sendable (UnsafeMutablePointer<AVPacket>) -> Void = { _ in },
+        playedMedia: PlayedMediaLedger? = nil
     ) {
         let discontinuityThresholdSeconds = 10.0
         var prevRawVideoPtsSec = Double.nan
@@ -1993,6 +2001,7 @@ final class SoftwarePlaybackHost {
                 if rawPts != Int64.min, tbSec > 0 {
                     let ptsSec = Double(rawPts) * tbSec
                     noteEdge(ptsSec)
+                    playedMedia?.record(isVideo ? .video : .audio, pts: ptsSec, bytes: Int(packet.pointee.size))
                     if let data = packet.pointee.data, packet.pointee.size > 0 {
                         let bytes = Data(bytes: data, count: Int(packet.pointee.size))
                         let isKey = isVideo && (packet.pointee.flags & AV_PKT_FLAG_KEY) != 0
@@ -2363,7 +2372,8 @@ final class SoftwarePlaybackHost {
         subtitleTimeBases: [Int32: AVRational] = [:],
         splitDisplaySetSubtitleStreamIndices: Set<Int32> = [],
         subtitleTapSink: @Sendable () -> ((@Sendable (Int32, UnsafeMutablePointer<AVPacket>, AVRational, Bool) -> Void)?) = { nil },
-        recordingTap: @escaping @Sendable (UnsafeMutablePointer<AVPacket>) -> Void = { _ in }
+        recordingTap: @escaping @Sendable (UnsafeMutablePointer<AVPacket>) -> Void = { _ in },
+        playedMedia: PlayedMediaLedger? = nil
     ) {
         // Clock arming: one-shot latch (seekClock is not idempotent -- re-calling snaps clock back to initialClockTime). Shared with host so a seek before first audio isn't overridden by a late re-arm.
 
@@ -2746,6 +2756,16 @@ final class SoftwarePlaybackHost {
                 }
             }
 
+            // AE#514: on the folded axis the clock runs on, which is what the sampler reads the playhead off.
+            if let playedMedia, streamIdx == videoStreamIndex || streamIdx == audioStreamIndex {
+                let tbSec = streamIdx == videoStreamIndex ? videoTimeBaseSeconds : audioTimeBaseSeconds
+                let ticks = packet.pointee.pts != Int64.min ? packet.pointee.pts : packet.pointee.dts
+                if ticks != Int64.min, tbSec > 0 {
+                    playedMedia.record(streamIdx == videoStreamIndex ? .video : .audio,
+                                       pts: Double(ticks) * tbSec, bytes: Int(packet.pointee.size))
+                }
+            }
+
             // Fill ring before decode so the ring holds every packet. Audio appended for sync; only video keyframes tagged for eviction alignment.
             if isLive {
                 let isVideo = streamIdx == videoStreamIndex
diff --git a/Sources/AetherEngine/Video/HLSSegmentProducer.swift b/Sources/AetherEngine/Video/HLSSegmentProducer.swift
index 1b00d2757..7eca8b7c4 100644
--- a/Sources/AetherEngine/Video/HLSSegmentProducer.swift
+++ b/Sources/AetherEngine/Video/HLSSegmentProducer.swift
@@ -510,6 +510,11 @@ final class HLSSegmentProducer: @unchecked Sendable {
     /// before `start()`; nil for hosts that drive the engine without one (`aetherctl`, tests).
     var sideReaderLinkGate: SideReaderLinkGate?
 
+    /// AE#514: the session's ledger of played-stream packet bytes, which the bitrate fields read at the
+    /// playhead. Set once before `start()`, like the gate above; nil for hosts that drive the engine
+    /// without a session (`aetherctl` probes, tests).
+    var playedMediaLedger: PlayedMediaLedger?
+
     /// Forward-only producer restart counter; surfaced in live telemetry. Written on pump thread, read under packetCounterLock.
     var restartCount: Int {
         packetCounterLock.lock()
@@ -2719,10 +2724,36 @@ final class HLSSegmentProducer: @unchecked Sendable {
     /// while playback listens to the bridged rendition.
     private func readNextSourcePacketMergedTapped() throws -> (packet: UnsafeMutablePointer<AVPacket>, origin: PacketOrigin)? {
         let read = try readNextSourcePacketMerged()
-        if let read { tapForRecording(read.packet) }
+        if let read {
+            tapForRecording(read.packet)
+            recordPlayedMedia(read.packet, origin: read.origin)
+        }
         return read
     }
 
+    /// AE#514: the video stream and the audio stream this session plays, on the source axis the engine
+    /// folds AVPlayer's clock back onto (`source_pts - playlistShiftSeconds`).
+    private func recordPlayedMedia(_ packet: UnsafeMutablePointer<AVPacket>, origin: PacketOrigin) {
+        guard let ledger = playedMediaLedger, packet.pointee.size > 0 else { return }
+        let index = packet.pointee.stream_index
+        let track: PlayedMediaLedger.Track
+        let timeBase: AVRational
+        if origin == .main, index == videoStreamIndex {
+            track = .video
+            timeBase = sourceVideoTimeBase
+        } else if let audio = audioConfig, index == audio.sourceStreamIndex,
+                  (origin == .side) == (sideAudioDemuxer != nil) {
+            track = .audio
+            timeBase = audio.sourceTimeBase
+        } else {
+            return
+        }
+        let ticks = packet.pointee.pts != Int64.min ? packet.pointee.pts : packet.pointee.dts
+        guard ticks != Int64.min, timeBase.num > 0, timeBase.den > 0 else { return }
+        ledger.record(track, pts: Double(ticks) * Double(timeBase.num) / Double(timeBase.den),
+                      bytes: Int(packet.pointee.size))
+    }
+
     private func readNextSourcePacketMerged() throws -> (packet: UnsafeMutablePointer<AVPacket>, origin: PacketOrigin)? {
         guard let side = sideAudioDemuxer else {
             guard let packet = try demuxer.readPacket() else { return nil }
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine.swift b/Sources/AetherEngine/Video/HLSVideoEngine.swift
index 2fda1e338..96fae4225 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine.swift
@@ -2268,6 +2268,10 @@ public final class HLSVideoEngine: @unchecked Sendable {
         return (producer, cache, server, demuxer, audioBridge)
     }
 
+    /// AE#514: bytes of the played streams by presentation time, fed by every producer of the session
+    /// (initial, seek restart, live reopen, revive), read by the telemetry sampler at the playhead.
+    let playedMediaLedger = PlayedMediaLedger()
+
     /// Bytes this session pulled from the SOURCE, across every demuxer it has had (see
     /// `retiredDemuxerBytes`). Not the same link as `LiveTelemetry.networkTransferredBytes`, which on
     /// the native path counts what AVPlayer pulled from the loopback server.
@@ -2629,6 +2633,7 @@ public final class HLSVideoEngine: @unchecked Sendable {
         // below. The side readers read one gate for the whole session, so a restart must not leave
         // a gap where nobody claims the link.
         prod.sideReaderLinkGate = sideReaderLinkGate
+        prod.playedMediaLedger = playedMediaLedger
         prod.onFirstHDR10PlusDetected = { [weak self] in
             self?.notifyHDR10PlusOnce()
         }
diff --git a/Tests/AetherEngineTests/Issue514AverageBitrateTests.swift b/Tests/AetherEngineTests/Issue514AverageBitrateTests.swift
index 340f2293b..8d2ceb2b0 100644
--- a/Tests/AetherEngineTests/Issue514AverageBitrateTests.swift
+++ b/Tests/AetherEngineTests/Issue514AverageBitrateTests.swift
@@ -1,140 +1,210 @@
 import Foundation
 import Testing
-import AVFoundation
 @testable import AetherEngine
 
-/// AE#514: `LiveTelemetry.averageBitrateMbps` divided the session's lifetime bytes by pure wall-clock
-/// time. Bytes stop arriving while the transport is paused (the forward buffer is already full), the
-/// divisor does not, so the reported average decayed toward zero for as long as the pause lasted and
-/// never came back: the paused seconds stayed in the divisor for the rest of the session. The fix
-/// charges a tick's second only when the session is in a phase that consumes media.
-@MainActor
+/// AE#514: both bitrate fields in `LiveTelemetry` were metered from the reader's transfer counter.
+/// Round one fixed the divisor (a pause dragged the average toward zero); round two, from the
+/// reporter's retest, fixes the numerator: transfer and playback part ways on every route that reads
+/// ahead. VOD prefetch put a 20 Mbps stream at ~35 Mbps, and a paused live session kept draining the
+/// origin into its DVR window while the divisor stood still, so its average climbed for as long as the
+/// pause ran. Both fields now meter the bytes of the packets the playhead crossed over the media
+/// seconds it crossed.
 struct Issue514AverageBitrateTests {
 
-    // MARK: - Which seconds belong in the divisor
-
-    /// A pause and the three terminal phases are the session standing still. Everything else is the
-    /// session working, and the bytes it did or did not get in those seconds are part of its average.
-    @Test("only the phases that consume media charge a second to the divisor")
-    func pausedAndTerminalPhasesDoNotCharge() {
-        #expect(LiveTelemetrySampler.chargesActiveTime(.paused) == false)
-        #expect(LiveTelemetrySampler.chargesActiveTime(.idle) == false)
-        #expect(LiveTelemetrySampler.chargesActiveTime(.ended) == false)
-        #expect(LiveTelemetrySampler.chargesActiveTime(.error("boom")) == false)
-
-        #expect(LiveTelemetrySampler.chargesActiveTime(.playing))
-        #expect(LiveTelemetrySampler.chargesActiveTime(.loading))
-        #expect(LiveTelemetrySampler.chargesActiveTime(.rebuffering))
-        #expect(LiveTelemetrySampler.chargesActiveTime(.stalled(reconnecting: true)))
-        #expect(LiveTelemetrySampler.chargesActiveTime(.stalled(reconnecting: false)))
+    /// 20 Mbps split over a 25 fps video track and a ~47 Hz audio track, recorded as a pump would.
+    private static let videoBytesPerSecond = 2_400_000
+    private static let audioBytesPerSecond = 100_000
+    private static let mbps = Double(videoBytesPerSecond + audioBytesPerSecond) * 8 / 1_000_000
+
+    private static func feed(_ ledger: PlayedMediaLedger, from start: Double, to end: Double) {
+        var pts = start
+        while pts < end - 1e-9 {
+            ledger.record(.video, pts: pts, bytes: videoBytesPerSecond / 25)
+            pts += 1.0 / 25
+        }
+        pts = start
+        while pts < end - 1e-9 {
+            ledger.record(.audio, pts: pts, bytes: audioBytesPerSecond * 1024 / 48_000)
+            pts += 1024.0 / 48_000
+        }
     }
 
-    /// Deliberately NOT excluded, against the report's own suggestion: a seek is where the session
-    /// fetches hardest (the buffer is discarded and a new range pulled). Dropping those seconds while
-    /// keeping their bytes would push the average above the media's real rate on every scrub.
-    @Test("a seek charges its seconds, because it is also where the bytes arrive")
-    func seekingCharges() {
-        #expect(LiveTelemetrySampler.chargesActiveTime(.seeking))
+    private static func play(_ meter: inout PlayedBitrateMeter, _ ledger: PlayedMediaLedger,
+                             from start: Double, seconds: Int) -> Double {
+        var playhead = start
+        for _ in 0..<seconds {
+            playhead += 1
+            meter.advance(to: playhead, wallSeconds: 1, ledger: ledger)
+        }
+        return playhead
     }
 
-    // MARK: - The quotient
+    private static func near(_ value: Double?, _ expected: Double, tolerance: Double = 0.05) -> Bool {
+        guard let value else { return false }
+        return abs(value - expected) <= tolerance * expected
+    }
 
-    @Test("the average is the lifetime bytes over the active seconds")
-    func averageIsBytesOverActiveSeconds() {
-        // 2 Mbps for ten active seconds: 2 500 000 bytes.
-        let rate = LiveTelemetrySampler.averageBitrateMbps(lifetimeBytes: 2_500_000, activeSeconds: 10)
-        #expect(abs((rate ?? 0) - 2.0) < 0.001)
+    // MARK: - The reporter's table
+
+    /// VOD, playing: minutes of read-ahead sit in the ledger the moment they are fetched, and count
+    /// only once the playhead crosses them.
+    @Test("VOD read-ahead does not inflate either field")
+    func vodReadAheadIsNotCounted() {
+        let ledger = PlayedMediaLedger()
+        Self.feed(ledger, from: 0, to: 240)
+        var meter = PlayedBitrateMeter()
+        meter.advance(to: 0, wallSeconds: 0, ledger: ledger)
+        _ = Self.play(&meter, ledger, from: 0, seconds: 30)
+        #expect(Self.near(meter.averageMbps, Self.mbps))
+        #expect(Self.near(meter.instantMbps, Self.mbps))
     }
 
-    /// Same rule as `observedTransferMbps` one field over: "not measurable yet" is a gap, never a
-    /// confident zero. Before the fix the very first tick published 0.00 Mbps, because it seeds
-    /// `sessionStartBytes` from the same counter it then subtracts.
-    @Test("a session with no active time and no bytes publishes nil, not zero")
-    func unmeasurableSessionPublishesNil() {
-        #expect(LiveTelemetrySampler.averageBitrateMbps(lifetimeBytes: 0, activeSeconds: 0) == nil)
-        #expect(LiveTelemetrySampler.averageBitrateMbps(lifetimeBytes: 350_000, activeSeconds: 0) == nil)
-        #expect(LiveTelemetrySampler.averageBitrateMbps(lifetimeBytes: 0, activeSeconds: 30) == nil)
+    /// VOD, paused: the reader keeps topping up the buffer, the playhead does not move.
+    @Test("a VOD pause leaves both fields standing")
+    func vodPauseFreezes() {
+        let ledger = PlayedMediaLedger()
+        Self.feed(ledger, from: 0, to: 60)
+        var meter = PlayedBitrateMeter()
+        meter.advance(to: 0, wallSeconds: 0, ledger: ledger)
+        let playhead = Self.play(&meter, ledger, from: 0, seconds: 30)
+        let average = meter.averageMbps, instant = meter.instantMbps
+        Self.feed(ledger, from: 60, to: 120)
+        for _ in 0..<180 { meter.advance(to: playhead, wallSeconds: 1, ledger: ledger) }
+        #expect(meter.averageMbps == average)
+        #expect(meter.instantMbps == instant)
     }
 
-    // MARK: - The reported session shape
-
-    /// The reporter's steps, folded tick by tick: 30 s of a 2.8 Mbps file, a three-minute pause during
-    /// which the demuxer counter stands still, then playback again.
-    @Test("a three-minute pause leaves the average flat instead of collapsing it")
-    func pauseDoesNotDragTheAverageDown() {
-        let bytesPerSecond: Int64 = 350_000        // 2.8 Mbps
-        var lifetimeBytes: Int64 = 0
-        var activeSeconds: Double = 0
-        var wallClockSeconds: Double = 0
-
-        func tick(_ phase: PlaybackPhase, bytes: Int64) {
-            lifetimeBytes += bytes
-            wallClockSeconds += 1
-            if LiveTelemetrySampler.chargesActiveTime(phase) { activeSeconds += 1 }
+    /// Live, paused: the pump keeps draining the origin at the broadcast rate for the whole pause
+    /// (AE#443). Nothing is played, so nothing may move; on resume the backlog counts as it plays.
+    @Test("a live pause does not climb, and the backlog counts at its real rate once played")
+    func livePauseDoesNotClimb() {
+        let ledger = PlayedMediaLedger()
+        var meter = PlayedBitrateMeter()
+        var edge = 1_000.0
+        Self.feed(ledger, from: edge, to: edge + 2)
+        meter.advance(to: edge, wallSeconds: 0, ledger: ledger)
+        var playhead = edge
+        for _ in 0..<30 {
+            edge += 1
+            Self.feed(ledger, from: edge + 1, to: edge + 2)
+            playhead += 1
+            meter.advance(to: playhead, wallSeconds: 1, ledger: ledger)
         }
+        let average = meter.averageMbps
+        #expect(Self.near(average, Self.mbps))
 
-        for _ in 0..<30 { tick(.playing, bytes: bytesPerSecond) }
-        let beforePause = LiveTelemetrySampler.averageBitrateMbps(
-            lifetimeBytes: lifetimeBytes, activeSeconds: activeSeconds)
-        #expect(abs((beforePause ?? 0) - 2.8) < 0.001)
-
-        // Paused: the forward buffer is full, so the demuxer counter does not move.
-        for _ in 0..<180 { tick(.paused, bytes: 0) }
-        let duringPause = LiveTelemetrySampler.averageBitrateMbps(
-            lifetimeBytes: lifetimeBytes, activeSeconds: activeSeconds)
-        #expect(duringPause == beforePause, "the pause must not move the average at all")
-
-        // What used to ship, for the record: the same bytes over wall-clock time.
-        let wallClockAverage = Double(lifetimeBytes) * 8.0 / wallClockSeconds / 1_000_000.0
-        #expect(wallClockAverage < 0.5, "the old divisor collapsed a 2.8 Mbps session to \(wallClockAverage)")
-
-        // And on resume it is still the media's rate, not a value climbing back out of a hole.
-        for _ in 0..<30 { tick(.playing, bytes: bytesPerSecond) }
-        let afterResume = LiveTelemetrySampler.averageBitrateMbps(
-            lifetimeBytes: lifetimeBytes, activeSeconds: activeSeconds)
-        #expect(abs((afterResume ?? 0) - 2.8) < 0.001)
-    }
+        for _ in 0..<300 {
+            edge += 1
+            Self.feed(ledger, from: edge + 1, to: edge + 2)
+            meter.advance(to: playhead, wallSeconds: 1, ledger: ledger)
+        }
+        #expect(meter.averageMbps == average, "five minutes of paused live must not move the average")
 
-    /// End of media is the other unbounded divisor: the sampler runs until the host tears the session
-    /// down, so a snapshot left on screen after the last frame used to decay exactly like a pause.
-    @Test("the average stops moving once the source has ended")
-    func endedSessionFreezesTheAverage() {
-        var activeSeconds: Double = 0
-        for _ in 0..<30 where LiveTelemetrySampler.chargesActiveTime(.playing) { activeSeconds += 1 }
-        let atEnd = activeSeconds
-        for _ in 0..<120 where LiveTelemetrySampler.chargesActiveTime(.ended) { activeSeconds += 1 }
-        #expect(activeSeconds == atEnd)
+        _ = Self.play(&meter, ledger, from: playhead, seconds: 60)
+        #expect(Self.near(meter.averageMbps, Self.mbps))
+        #expect(Self.near(meter.instantMbps, Self.mbps))
     }
 
-    // MARK: - Wiring
-
-    /// The two functions above are only right if the tick actually asks them. A paused session accrues
-    /// no active time however long its sampler runs; the same sampler starts accruing on play.
-    @Test("the running sampler charges no active time while the transport is paused")
-    func samplerAccruesNoActiveTimeWhilePaused() async throws {
-        let engine = try AetherEngine()
-        engine.playbackBackend = .native
-        let item = AVPlayerItem(url: URL(fileURLWithPath: "/nonexistent-514.mp4"))
-        engine.currentAVPlayer = AVPlayer(playerItem: item)
-        engine.state = .paused
-        #expect(engine.playbackPhase == .paused)
-
-        let sampler = LiveTelemetrySampler(engine: engine, nativeRead: { _, _ in
-            NativeAVFReadings(forwardBufferSeconds: 12.0)
-        })
-        sampler.start()
-        defer { sampler.stop() }
-
-        // Long enough for several 1 Hz ticks to have run and charged nothing.
-        try await Task.sleep(for: .milliseconds(2_500))
-        #expect(sampler.activeSeconds == 0)
-
-        engine.state = .playing
-        let started = ContinuousClock().now
-        while sampler.activeSeconds == 0 {
-            if ContinuousClock().now - started > .seconds(30) { break }
-            try await Task.sleep(for: .milliseconds(50))
+    /// Live, playing: this was right before by accident of the clock, and must stay right.
+    @Test("live at the edge reads the broadcast rate")
+    func livePlayingReadsTheRate() {
+        let ledger = PlayedMediaLedger()
+        var meter = PlayedBitrateMeter()
+        Self.feed(ledger, from: 50, to: 53)
+        meter.advance(to: 50, wallSeconds: 0, ledger: ledger)
+        var playhead = 50.0
+        for _ in 0..<60 {
+            Self.feed(ledger, from: playhead + 3, to: playhead + 4)
+            playhead += 1
+            meter.advance(to: playhead, wallSeconds: 1, ledger: ledger)
         }
-        #expect(sampler.activeSeconds > 0)
+        #expect(Self.near(meter.averageMbps, Self.mbps))
+        #expect(Self.near(meter.instantMbps, Self.mbps))
+    }
+
+    // MARK: - Seeks
+
+    /// The span a seek jumps over was never played, and the buffer the seek discarded is fetched again:
+    /// neither may land in the fields.
+    @Test("a seek charges nothing for the jump, and a re-fetched range counts once")
+    func seekAndRefetch() {
+        let ledger = PlayedMediaLedger()
+        Self.feed(ledger, from: 0, to: 120)
+        var meter = PlayedBitrateMeter()
+        meter.advance(to: 0, wallSeconds: 0, ledger: ledger)
+        _ = Self.play(&meter, ledger, from: 0, seconds: 20)
+        let secondsBefore = meter.lifetimeSeconds
+
+        // Forward seek to 600: a new range is fetched from there.
+        Self.feed(ledger, from: 600, to: 700)
+        meter.advance(to: 600, wallSeconds: 1, ledger: ledger)
+        #expect(meter.lifetimeSeconds == secondsBefore)
+        _ = Self.play(&meter, ledger, from: 600, seconds: 10)
+
+        // Back to 100: the reader delivers 100..200 again, over entries it already held.
+        Self.feed(ledger, from: 100, to: 200)
+        meter.advance(to: 100, wallSeconds: 1, ledger: ledger)
+        _ = Self.play(&meter, ledger, from: 100, seconds: 30)
+
+        #expect(abs(meter.lifetimeSeconds - 60) < 1e-6)
+        #expect(Self.near(meter.averageMbps, Self.mbps))
+    }
+
+    /// A playhead the ledger holds nothing for (not fed there, or on another axis) is unmeasured.
+    @Test("a playhead off the ledger's span publishes nil, never zero")
+    func unmeasuredSpanIsNil() {
+        let ledger = PlayedMediaLedger()
+        Self.feed(ledger, from: 5_000, to: 5_100)
+        var meter = PlayedBitrateMeter()
+        meter.advance(to: 0, wallSeconds: 0, ledger: ledger)
+        _ = Self.play(&meter, ledger, from: 0, seconds: 30)
+        #expect(meter.averageMbps == nil)
+        #expect(meter.instantMbps == nil)
+    }
+
+    // MARK: - The ledger
+
+    @Test("the same packet delivered twice is held once")
+    func duplicatePacketOverwrites() {
+        let ledger = PlayedMediaLedger()
+        ledger.record(.video, pts: 1.0, bytes: 100)
+        ledger.record(.video, pts: 1.04, bytes: 100)
+        ledger.record(.video, pts: 1.0, bytes: 100)
+        #expect(ledger.entryCount == 2)
+        #expect(ledger.consume(from: 0, to: 2) == 200)
+    }
+
+    @Test("B-frame reorder inserts in place, a re-read from far behind drops what lies ahead")
+    func reorderAndReread() {
+        let ledger = PlayedMediaLedger()
+        for pts in [0.0, 0.12, 0.04, 0.08, 0.24, 0.16, 0.20] { ledger.record(.video, pts: pts, bytes: 10) }
+        #expect(ledger.consume(from: 0.04, to: 0.20) == 40)
+        ledger.record(.video, pts: 10, bytes: 10)
+        ledger.record(.video, pts: 11, bytes: 10)
+        ledger.record(.video, pts: 5, bytes: 10)
+        #expect(ledger.consume(from: 5, to: 12) == 10, "10 and 11 lie ahead of the re-read and are gone")
+    }
+
+    @Test("consuming a span forgets everything before it")
+    func consumePrunes() {
+        let ledger = PlayedMediaLedger()
+        Self.feed(ledger, from: 0, to: 10)
+        _ = ledger.consume(from: 4, to: 5)
+        #expect(ledger.consume(from: 0, to: 5) == 0)
+        #expect(ledger.consume(from: 5, to: 10) > 0)
+    }
+
+    // MARK: - The playhead
+
+    @Test("native folds AVPlayer's clock back with the producer's shift; routes without a pump read nil")
+    func ledgerPlayheadPerBackend() {
+        #expect(LiveTelemetrySampler.ledgerPlayhead(
+            backend: .native, nativeClock: 12, playlistShift: 3_600, softwareSourceClock: nil) == 3_612)
+        #expect(LiveTelemetrySampler.ledgerPlayhead(
+            backend: .native, nativeClock: nil, playlistShift: 3_600, softwareSourceClock: nil) == nil)
+        #expect(LiveTelemetrySampler.ledgerPlayhead(
+            backend: .software, nativeClock: 12, playlistShift: 3_600, softwareSourceClock: 90) == 90)
+        #expect(LiveTelemetrySampler.ledgerPlayhead(
+            backend: .audio, nativeClock: 12, playlistShift: 0, softwareSourceClock: 12) == nil)
     }
 }
diff --git a/docs/api.md b/docs/api.md
index 9760f6f35..78714e884 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -925,7 +925,7 @@ as well.
 | Symbol | Notes |
 | --- | --- |
 | `AetherEngine.version` | The engine release this source descends from, as the string a published tag carries. SwiftPM resolves a package to a revision rather than to a tag, so an About panel or the header of a diagnostic log has nothing else to name the engine with. Between releases, and under a pin on an unreleased commit, it names the last published version the checkout descends from. |
-| `diagnostics.liveTelemetry` | 1 Hz `LiveTelemetry?` snapshot while playing or paused, nil while idle. On a separate `ObservableObject` so its ticks cannot re-render a host observing the engine. On `.remoteBypass` it is fed from AVPlayer's access log alone: `instantBitrateMbps` and `averageBitrateMbps` are what the playing variant declares (BANDWIDTH, and AVERAGE-BANDWIDTH or BANDWIDTH where the master omits it), because the bytes AVPlayer transferred are buffer fill at link speed rather than the stream's rate, `networkThroughputMbps` is the access log's `observedBitrate`, `networkTransferredBytes` and `droppedFrameCount` its session totals, `forwardBufferSeconds` the loaded range ahead of the playhead. `avSyncGapMs` and `observedFps` are nil, and the loopback counters (`producerRestartCount`, `muxedBytesLifetime`, `serverBytesSentLifetime`, `serverRequestCount`, `demuxerBytesFetched`) read 0 because there is no loopback. |
+| `diagnostics.liveTelemetry` | 1 Hz `LiveTelemetry?` snapshot while playing or paused, nil while idle. On a separate `ObservableObject` so its ticks cannot re-render a host observing the engine. On the loopback and software routes `instantBitrateMbps` and `averageBitrateMbps` are the rate of the MEDIA played, not of the transfer (AE#514): the bytes of the played video and audio packets the playhead crossed, over the media seconds it crossed, about the last 10 s for the first and the whole session for the second. Read-ahead, a re-fetch after a seek and a paused live source draining into its DVR window do not move them, and both stand still through a pause; the transfer is `networkThroughputMbps`. On `.remoteBypass` it is fed from AVPlayer's access log alone: `instantBitrateMbps` and `averageBitrateMbps` are what the playing variant declares (BANDWIDTH, and AVERAGE-BANDWIDTH or BANDWIDTH where the master omits it), because the bytes AVPlayer transferred are buffer fill at link speed rather than the stream's rate, `networkThroughputMbps` is the access log's `observedBitrate`, `networkTransferredBytes` and `droppedFrameCount` its session totals, `forwardBufferSeconds` the loaded range ahead of the playhead. `avSyncGapMs` and `observedFps` are nil, and the loopback counters (`producerRestartCount`, `muxedBytesLifetime`, `serverBytesSentLifetime`, `serverRequestCount`, `demuxerBytesFetched`) read 0 because there is no loopback. |
 | `LiveTelemetry.softwareCacheSeekHits`, `softwareCacheSeekMisses`, `softwareCacheSourceEpoch` | Optional cumulative software-VOD packet-cache counters. A hit repositions the retained consumer cursor without changing the source epoch; a miss repositions the demuxer and advances it. `nil` on other paths. `cachedBytes` includes retained compressed packet records on software VOD, distinct from decoded `displayCushionSeconds` and the underlying byte-reader window. |
 | `EngineLog.handler` | Mirror every info-level line into a host capture path. Fires from whatever thread emitted it, so it must be thread-safe and non-blocking. |
 | `EngineLog.subsystem`, `EngineLog.Category` | `de.superuser404.AetherEngine`, one category per subsystem: `engine`, `ffmpeg`, `session`, `muxer`, `demux`, `hls.server`, `audio.bridge`, `sw.playback`, `scrub`. |

From d06f3eb017171cb911a1650f6a99384a0344f39a Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Tue, 29 Sep 2026 17:00:51 +0200
Subject: [PATCH 142/359] chore(release): prep 7.22.1 - the bitrate fields
 measure the media played

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                    | 4 ++++
 Examples/README.md                              | 2 +-
 README.md                                       | 6 +++---
 Sources/AetherEngine/AetherEngine+Version.swift | 2 +-
 4 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 29594328c..82fcb2d61 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,10 @@ the public-API contract.
 
 ## [Unreleased]
 
+_Nothing yet._
+
+## [7.22.1] - 2026-09-29
+
 ### Fixed
 
 - **`LiveTelemetry`'s two bitrate fields measure the media played, not the bytes transferred** (#514).
diff --git a/Examples/README.md b/Examples/README.md
index 4a4a97ffb..bae450031 100644
--- a/Examples/README.md
+++ b/Examples/README.md
@@ -18,7 +18,7 @@ Three samples covering different audiences:
    ```
    https://github.com/superuser404notfound/AetherEngine
    ```
-   Dependency Rule: Up to Next Major Version, starting from `7.22.0`. Add the `AetherEngine` library product to your app target.
+   Dependency Rule: Up to Next Major Version, starting from `7.22.1`. Add the `AetherEngine` library product to your app target.
 
 3. **Drop the file in.** Replace the Xcode template's default `App.swift` (or whatever the generated `@main` file is called) with the contents of [`MinimalPlayerApp.swift`](MinimalPlayer/MinimalPlayerApp.swift). The file is self-contained: it defines both the `@main App` struct and the `ContentView`.
 
diff --git a/README.md b/README.md
index 44beef23a..efe78f85e 100644
--- a/README.md
+++ b/README.md
@@ -384,7 +384,7 @@ Subtitle cues land in raw source PTS; render the overlay against `player.sourceT
 Install via Swift Package Manager:
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.22.0")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.22.1")
 ```
 
 Three samples ship in `Examples/`:
@@ -631,10 +631,10 @@ Browse all of this as a searchable site at **[aetherengine.superuser404.de](http
 AetherEngine uses [Semantic Versioning](https://semver.org). The public API surface, every `public` declaration in `Sources/AetherEngine/`, is the stability contract. **Major** removes / renames public symbols or breaks adopters; **Minor** adds public API or codec / format support; **Patch** fixes bugs with no public API change. `internal` types are not part of the contract.
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.22.0")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.22.1")
 ```
 
-Pin to `.upToNextMinor(from: "7.22.0")` for stricter teams that prefer to opt into minor bumps explicitly.
+Pin to `.upToNextMinor(from: "7.22.1")` for stricter teams that prefer to opt into minor bumps explicitly.
 
 ## Requirements
 
diff --git a/Sources/AetherEngine/AetherEngine+Version.swift b/Sources/AetherEngine/AetherEngine+Version.swift
index e1cf164fa..1bb180a2c 100644
--- a/Sources/AetherEngine/AetherEngine+Version.swift
+++ b/Sources/AetherEngine/AetherEngine+Version.swift
@@ -11,5 +11,5 @@ extension AetherEngine {
     ///
     /// Between releases, and in a consumer that pins an unreleased commit for a device test, this
     /// names the last PUBLISHED version the checkout descends from, not every patch in it.
-    public nonisolated static let version = "7.22.0"
+    public nonisolated static let version = "7.22.1"
 }

From bdda5d577bf9d3944245b988b1e74f04c6c3a3cf Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Tue, 29 Sep 2026 20:55:54 +0200
Subject: [PATCH 143/359] test(server): leave the keep-alive test's stranger
 deadline room for a late worker

The deadline runs from accept. On a loaded CI runner the connection worker
started more than 0.5 s late, so the server dropped the first request before
reading it and the 7.22.1 push run failed on that test alone.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 Tests/AetherEngineTests/HLSLocalServerSlowPeerTests.swift | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/Tests/AetherEngineTests/HLSLocalServerSlowPeerTests.swift b/Tests/AetherEngineTests/HLSLocalServerSlowPeerTests.swift
index 92d779b5e..0136fadd7 100644
--- a/Tests/AetherEngineTests/HLSLocalServerSlowPeerTests.swift
+++ b/Tests/AetherEngineTests/HLSLocalServerSlowPeerTests.swift
@@ -44,7 +44,9 @@ struct HLSLocalServerSlowPeerTests {
 
     @Test("A connection that presented the token keeps its keep-alive idle past the stranger deadline")
     func authenticatedKeepAliveSurvives() async throws {
-        let server = HLSLocalServer(provider: StubProvider(), unauthenticatedHeadSeconds: 0.5)
+        // The stranger deadline runs from accept, so it must leave room for a worker thread that a
+        // loaded runner schedules late, or the first request is dropped before it is read.
+        let server = HLSLocalServer(provider: StubProvider(), unauthenticatedHeadSeconds: 2)
         try server.start()
         defer { server.stop() }
 
@@ -52,7 +54,7 @@ struct HLSLocalServerSlowPeerTests {
         defer { close(fd) }
         let path = "/\(server.pathToken)/media.m3u8"
         #expect(await Self.onOwnThread { Self.requestStatus(fd: fd, path: path) } == 200)
-        try await Task.sleep(for: .milliseconds(1500))
+        try await Task.sleep(for: .milliseconds(3000))
         #expect(await Self.onOwnThread { Self.requestStatus(fd: fd, path: path) } == 200,
                 "the second request on an authenticated keep-alive connection was not answered")
     }

From 3a0a5fbe4b0e54a8d2727281120fb0d238ae2fdb Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Tue, 29 Sep 2026 21:34:09 +0200
Subject: [PATCH 144/359] fix(display): serve an unproven HDR master after the
 mode switch, not during it (#667)

The pre-flight gate releases the load at its 2 s cap while an HDR switch is
still running (#348). On a panel whose headroom never proves HDR (#459) the
route then offers the master and lets AVPlayer's acceptance answer, but
mid-switch AVPlayer answers for the mode the panel is leaving: on tvOS 27
the master failed with -11868 660 ms before the switch ended, and the
refusal latched (#588), so every HDR title went media-direct.

That route now waits for a switch it saw start to end, re-reads the panel
and routes then. A switch nobody saw start is not waited on, so an
unobservable DV switch cannot hold the load. A refusal raised while the
system reports a switch in progress still falls back for the item but no
longer latches.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                  | 12 +++-
 Sources/AetherEngine/AetherEngine+Probe.swift | 21 ++++++
 Sources/AetherEngine/AetherEngine.swift       | 41 +++++++++--
 .../Display/DisplayCriteriaController.swift   | 33 +++++++++
 .../Native/MasterFallbackDecision.swift       |  8 ++-
 ...Issue535RefusalNeedsEligibilityTests.swift | 12 ++--
 .../Issue667MasterAfterSwitchTests.swift      | 69 +++++++++++++++++++
 7 files changed, 181 insertions(+), 15 deletions(-)
 create mode 100644 Tests/AetherEngineTests/Issue667MasterAfterSwitchTests.swift

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 82fcb2d61..ad718745e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,7 +10,17 @@ the public-API contract.
 
 ## [Unreleased]
 
-_Nothing yet._
+### Fixed
+
+- **An unproven HDR master is served after the display mode switch, not during it** (#667). The
+  pre-flight releases the load at its 2 s cap while an HDR switch is still running, which is what keeps
+  the load overlapping the switch (#348). On a panel whose EDR headroom never proves HDR (#459) the
+  engine then offers the master and lets AVPlayer's acceptance answer, and mid-switch AVPlayer answers
+  for the mode the panel is leaving: measured on tvOS 27, `-11868` 80 ms after the serve and 660 ms
+  before the switch ended. The refusal latched (#588), so every HDR title went media-direct and lost its
+  subtitle and audio renditions. That route now waits for a switch it saw start to end, re-reads the
+  panel, and routes then; the play gate held the first frame until that end anyway. A refusal raised
+  while a switch is in progress still earns the item its media fallback but no longer sets the latch.
 
 ## [7.22.1] - 2026-09-29
 
diff --git a/Sources/AetherEngine/AetherEngine+Probe.swift b/Sources/AetherEngine/AetherEngine+Probe.swift
index 6bf174011..e4040421c 100644
--- a/Sources/AetherEngine/AetherEngine+Probe.swift
+++ b/Sources/AetherEngine/AetherEngine+Probe.swift
@@ -921,6 +921,27 @@ extension AetherEngine {
         return attemptWhenUnproven && displayEligibleForHDR && !panelRefusedHDRMaster
     }
 
+    /// AE#667: whether an unproven master has to wait for the running switch before it is served.
+    ///
+    /// The pre-flight releases the load at its 2 s cap while an HDR switch is still in flight, on purpose:
+    /// the overlap is what #348 kept, and a proven or media route has nothing to lose by it. The unproven
+    /// master is the one route that does, because its whole point is to let AVPlayer's acceptance stand in
+    /// for the readout, and AVPlayer answers for the mode the panel is in NOW. Measured on an Apple TV 4K
+    /// (tvOS 27.0, HDR10 panel): master served 140 ms after the cap, `-11868` 80 ms later, the switch
+    /// ending 660 ms after that, and the refusal latched, so every later HDR title went media-direct.
+    ///
+    /// Only a switch seen to START counts. A DV switch that never reports would make this an unbounded wait
+    /// for an end that cannot arrive, and a proven panel is excluded because it already answered. What the
+    /// wait costs is the prep that used to overlap the switch's tail; the play gate held the first frame
+    /// until that end anyway.
+    nonisolated static func unprovenMasterAwaitsSwitchEnd(
+        routesAsHDR: Bool,
+        panelPresentsHDR: Bool,
+        switchRunning: Bool
+    ) -> Bool {
+        routesAsHDR && !panelPresentsHDR && switchRunning
+    }
+
     /// AE#541: the HDR route of an in-place rebuild, composed from the same two decisions the load makes.
     ///
     /// The readout and the display's eligibility are the load's, because the rebuild runs no handshake to
diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index 7cad009fe..db53863a3 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -2599,8 +2599,10 @@ public final class AetherEngine: ObservableObject {
         // AE#535: and only while the display is eligible for HDR, or the answer is about the window.
         if MasterFallbackDecision.isDisplayRejectionCode(rejection.code), !Self.panelRefusedHDRMaster {
             let eligibleNow = AVPlayer.eligibleForHDRPlayback
+            let switching = displayCriteria.displayModeSwitchInProgress
             if MasterFallbackDecision.shouldLatchPanelRefusal(
-                code: rejection.code, displayEligibleForHDRNow: eligibleNow) {
+                code: rejection.code, displayEligibleForHDRNow: eligibleNow,
+                displaySwitchInProgress: switching) {
                 Self.panelRefusedHDRMaster = true
                 EngineLog.emit(
                     "[DisplayCriteria] panel refused an HDR master (code=\(rejection.code)); this process "
@@ -2608,8 +2610,9 @@ public final class AetherEngine: ObservableObject {
                     category: .engine)
             } else {
                 EngineLog.emit(
-                    "[DisplayCriteria] AE#535 HDR master refused (code=\(rejection.code)) while the display "
-                    + "reads hdrEligible=no; this item falls back, the process does not latch the refusal",
+                    "[DisplayCriteria] HDR master refused (code=\(rejection.code)) while the display reads "
+                    + "hdrEligible=\(eligibleNow ? "yes" : "no") switching=\(switching ? "yes" : "no") "
+                    + "(#535, #667); this item falls back, the process does not latch the refusal",
                     category: .engine)
             }
         }
@@ -4511,20 +4514,46 @@ public final class AetherEngine: ObservableObject {
         //      where criteria are suppressed. The readout answers only around a dynamic-range transition,
         //      so a panel parked in HDR never proves itself and one tvOS 27 box stopped answering at all;
         //      a host that knows better says so, and a wrong claim costs the -11848 fallback, not the item.
-        let criteriaPanelReadout: Bool? =
+        var criteriaPanelReadout: Bool? =
             options.suppressDisplayCriteria ? nil : displayCriteria.currentPanelIsHDR()
-        let panelHDRAfterHandshake = Self.sessionPanelPresentsHDR(
+        var panelHDRAfterHandshake = Self.sessionPanelPresentsHDR(
             hostAsserts: options.panelIsInHDRMode, criteriaReadout: criteriaPanelReadout)
         // AE#459: the ROUTE may assume more than the LABEL may claim. `panelHDRAfterHandshake` stays the
         // label's answer, conservative by design; the route additionally offers an unproven but
         // HDR-eligible display the master and lets AVFoundation's acceptance be the readout `UIScreen`
         // has been measured getting wrong on a panel that was demonstrably presenting HDR. Live is excluded: its fallback is a rejoin at
         // the edge rather than a restored position, and that cost has not been measured.
-        let routingPanelHDR = Self.sessionRoutesAsHDRPanel(
+        var routingPanelHDR = Self.sessionRoutesAsHDRPanel(
             panelPresentsHDR: panelHDRAfterHandshake,
             attemptWhenUnproven: options.attemptsHDRMasterOnUnprovenPanel && !options.isLive,
             displayEligibleForHDR: observedDisplayCaps.supportsHDR,
             panelRefusedHDRMaster: Self.panelRefusedHDRMaster)
+        // AE#667: that acceptance only answers once the panel has arrived. See `unprovenMasterAwaitsSwitchEnd`.
+        if Self.unprovenMasterAwaitsSwitchEnd(
+            routesAsHDR: routingPanelHDR,
+            panelPresentsHDR: panelHDRAfterHandshake,
+            switchRunning: displayCriteria.observedSwitchIsRunning()) {
+            EngineLog.emit(
+                "[DisplayCriteria] unproven HDR master waits for the running switch to end before it is "
+                + "served (#667)",
+                category: .session)
+            await displayCriteria.waitForSwitch(consumesRecord: false, settleCap: .awaitObservedEnd)
+            if loadGeneration != gen {
+                probe.markClosed()
+                if probeOpened {
+                    Task.detached { [probe] in probe.close() }
+                }
+                try checkLoadCurrent(gen)
+            }
+            criteriaPanelReadout = options.suppressDisplayCriteria ? nil : displayCriteria.currentPanelIsHDR()
+            panelHDRAfterHandshake = Self.sessionPanelPresentsHDR(
+                hostAsserts: options.panelIsInHDRMode, criteriaReadout: criteriaPanelReadout)
+            routingPanelHDR = Self.sessionRoutesAsHDRPanel(
+                panelPresentsHDR: panelHDRAfterHandshake,
+                attemptWhenUnproven: options.attemptsHDRMasterOnUnprovenPanel && !options.isLive,
+                displayEligibleForHDR: observedDisplayCaps.supportsHDR,
+                panelRefusedHDRMaster: Self.panelRefusedHDRMaster)
+        }
         sessionPanelHDRReadout = criteriaPanelReadout
         sessionObservedDisplayCaps = observedDisplayCaps
         if routingPanelHDR != panelHDRAfterHandshake {
diff --git a/Sources/AetherEngine/Display/DisplayCriteriaController.swift b/Sources/AetherEngine/Display/DisplayCriteriaController.swift
index 9a6f14f5e..f5751b3ac 100644
--- a/Sources/AetherEngine/Display/DisplayCriteriaController.swift
+++ b/Sources/AetherEngine/Display/DisplayCriteriaController.swift
@@ -826,6 +826,39 @@ final class DisplayCriteriaController {
         #endif
     }
 
+    /// AE#667: whether a switch this load was armed for has been seen to start and not yet to end.
+    ///
+    /// Read from the notifications, not from `isDisplayModeSwitchInProgress` alone, because the flag is
+    /// documented as unreliable around a write and sticks `true` on panels whose DV switch never reports.
+    /// A switch nobody saw start answers false, so a caller waiting on this never waits for an end that
+    /// cannot be announced.
+    func observedSwitchIsRunning() -> Bool {
+        #if os(tvOS)
+        guard let window = resolveWindow() else { return false }
+        let snapshot = observation.snapshot()
+        guard Self.recordIsFreshEvidence(recordGeneration: snapshot.generation,
+                                         lastSpentGeneration: spentArmGeneration) else { return false }
+        let observed = Self.observedSwitch(
+            startedAtNanos: snapshot.startedAt,
+            endedAtNanos: snapshot.endedAt,
+            gateEntryNanos: DispatchTime.now().uptimeNanoseconds,
+            switchInProgress: window.avDisplayManager.isDisplayModeSwitchInProgress)
+        if case .running = observed { return true }
+        return false
+        #else
+        return false
+        #endif
+    }
+
+    /// AE#667: the system's in-progress flag, for a decision that may only be made more cautious by it.
+    var displayModeSwitchInProgress: Bool {
+        #if os(tvOS)
+        resolveWindow()?.avDisplayManager.isDisplayModeSwitchInProgress ?? false
+        #else
+        false
+        #endif
+    }
+
     /// Block until the panel settles its HDR mode negotiation, bounded so an
     /// unobservable switch can't stall the first frame.
     ///
diff --git a/Sources/AetherEngine/Native/MasterFallbackDecision.swift b/Sources/AetherEngine/Native/MasterFallbackDecision.swift
index 0bb3ef810..0e9d57817 100644
--- a/Sources/AetherEngine/Native/MasterFallbackDecision.swift
+++ b/Sources/AetherEngine/Native/MasterFallbackDecision.swift
@@ -39,8 +39,12 @@ enum MasterFallbackDecision {
     /// fully explained by the window, so it earns this item its media fallback and nothing more.
     /// Latching it cost the rest of the viewing session its master, and in a process that never
     /// backgrounds the AE#588 clear never came.
-    static func shouldLatchPanelRefusal(code: Int, displayEligibleForHDRNow: Bool) -> Bool {
-        isDisplayRejectionCode(code) && displayEligibleForHDRNow
+    ///
+    /// AE#667: nor while a display mode switch is in progress. AVPlayer answers for the mode the panel is
+    /// in at that moment, which mid-switch is the one it is leaving, so the refusal is about the moment.
+    static func shouldLatchPanelRefusal(code: Int, displayEligibleForHDRNow: Bool,
+                                        displaySwitchInProgress: Bool) -> Bool {
+        isDisplayRejectionCode(code) && displayEligibleForHDRNow && !displaySwitchInProgress
     }
 
     /// Any code that means "AVPlayer rejected the served master itself": the display-rejection pair
diff --git a/Tests/AetherEngineTests/Issue535RefusalNeedsEligibilityTests.swift b/Tests/AetherEngineTests/Issue535RefusalNeedsEligibilityTests.swift
index 688ea64d1..200bb906e 100644
--- a/Tests/AetherEngineTests/Issue535RefusalNeedsEligibilityTests.swift
+++ b/Tests/AetherEngineTests/Issue535RefusalNeedsEligibilityTests.swift
@@ -13,21 +13,21 @@ struct Issue535RefusalNeedsEligibilityTests {
 
     @Test("A display rejection while the display is ineligible for HDR does not latch")
     func ineligibleWindowDoesNotLatch() {
-        #expect(!MasterFallbackDecision.shouldLatchPanelRefusal(code: -11868, displayEligibleForHDRNow: false))
-        #expect(!MasterFallbackDecision.shouldLatchPanelRefusal(code: -11848, displayEligibleForHDRNow: false))
+        #expect(!MasterFallbackDecision.shouldLatchPanelRefusal(code: -11868, displayEligibleForHDRNow: false, displaySwitchInProgress: false))
+        #expect(!MasterFallbackDecision.shouldLatchPanelRefusal(code: -11848, displayEligibleForHDRNow: false, displaySwitchInProgress: false))
     }
 
     @Test("A display rejection on an eligible display still latches")
     func eligibleRefusalStillLatches() {
-        #expect(MasterFallbackDecision.shouldLatchPanelRefusal(code: -11868, displayEligibleForHDRNow: true))
-        #expect(MasterFallbackDecision.shouldLatchPanelRefusal(code: -11848, displayEligibleForHDRNow: true))
+        #expect(MasterFallbackDecision.shouldLatchPanelRefusal(code: -11868, displayEligibleForHDRNow: true, displaySwitchInProgress: false))
+        #expect(MasterFallbackDecision.shouldLatchPanelRefusal(code: -11848, displayEligibleForHDRNow: true, displaySwitchInProgress: false))
     }
 
     /// -1002 is a manifest filtered at parse time (#130), a statement about the playlist, never the display.
     @Test("The parse-time rejection never latches, eligible or not")
     func parseRejectionNeverLatches() {
-        #expect(!MasterFallbackDecision.shouldLatchPanelRefusal(code: -1002, displayEligibleForHDRNow: true))
-        #expect(!MasterFallbackDecision.shouldLatchPanelRefusal(code: -1002, displayEligibleForHDRNow: false))
+        #expect(!MasterFallbackDecision.shouldLatchPanelRefusal(code: -1002, displayEligibleForHDRNow: true, displaySwitchInProgress: false))
+        #expect(!MasterFallbackDecision.shouldLatchPanelRefusal(code: -1002, displayEligibleForHDRNow: false, displaySwitchInProgress: false))
     }
 
     /// The fallback itself is unaffected: the item still reloads the media playlist whatever the latch does.
diff --git a/Tests/AetherEngineTests/Issue667MasterAfterSwitchTests.swift b/Tests/AetherEngineTests/Issue667MasterAfterSwitchTests.swift
new file mode 100644
index 000000000..dd759490e
--- /dev/null
+++ b/Tests/AetherEngineTests/Issue667MasterAfterSwitchTests.swift
@@ -0,0 +1,69 @@
+import Foundation
+import Testing
+@testable import AetherEngine
+
+/// AE#667: an unproven HDR master served while the display mode switch is still running is refused for the
+/// mode the panel is leaving, and that refusal was latched as a fact about the panel.
+///
+/// Measured by the reporter on an Apple TV 4K (3rd gen, tvOS 27.0, HDR10 panel, Match Content on): the
+/// pre-flight released at its 2 s cap, the master was served 140 ms later, AVPlayer failed it with `-11868`
+/// after 80 ms, and the switch ended 660 ms after the refusal. Every HDR title on that box lost its master.
+struct Issue667MasterAfterSwitchTests {
+
+    @Test("An unproven master waits while a switch it saw start is still running")
+    func unprovenMasterWaitsForRunningSwitch() {
+        #expect(AetherEngine.unprovenMasterAwaitsSwitchEnd(
+            routesAsHDR: true, panelPresentsHDR: false, switchRunning: true))
+    }
+
+    @Test("No running switch, no wait: the #348 overlap stays where nothing is pending")
+    func noRunningSwitchNoWait() {
+        #expect(!AetherEngine.unprovenMasterAwaitsSwitchEnd(
+            routesAsHDR: true, panelPresentsHDR: false, switchRunning: false))
+    }
+
+    @Test("A proven panel already answered, so its master does not wait")
+    func provenPanelDoesNotWait() {
+        #expect(!AetherEngine.unprovenMasterAwaitsSwitchEnd(
+            routesAsHDR: true, panelPresentsHDR: true, switchRunning: true))
+    }
+
+    @Test("A media route has no acceptance to wait for")
+    func mediaRouteDoesNotWait() {
+        #expect(!AetherEngine.unprovenMasterAwaitsSwitchEnd(
+            routesAsHDR: false, panelPresentsHDR: false, switchRunning: true))
+    }
+
+    @Test("A refusal raised mid-switch does not latch, even on an eligible display")
+    func midSwitchRefusalDoesNotLatch() {
+        #expect(!MasterFallbackDecision.shouldLatchPanelRefusal(
+            code: -11868, displayEligibleForHDRNow: true, displaySwitchInProgress: true))
+        #expect(!MasterFallbackDecision.shouldLatchPanelRefusal(
+            code: -11848, displayEligibleForHDRNow: true, displaySwitchInProgress: true))
+    }
+
+    @Test("A refusal after the switch settled still latches")
+    func settledRefusalStillLatches() {
+        #expect(MasterFallbackDecision.shouldLatchPanelRefusal(
+            code: -11868, displayEligibleForHDRNow: true, displaySwitchInProgress: false))
+    }
+
+    /// A policy test cannot see the call site, so this one reads it: the wait sits between the route and the
+    /// serve, and re-reads the panel afterwards so the route is decided on the arrived mode.
+    @Test("The load waits for the switch before routing, then routes again")
+    func loadSiteWaitsThenReroutes() throws {
+        let source = URL(fileURLWithPath: #filePath)
+            .deletingLastPathComponent()
+            .deletingLastPathComponent()
+            .deletingLastPathComponent()
+            .appendingPathComponent("Sources/AetherEngine/AetherEngine.swift")
+        let text = try #require(try? String(contentsOf: source, encoding: .utf8))
+        let gate = try #require(text.range(of: "Self.unprovenMasterAwaitsSwitchEnd("))
+        let after = text[gate.upperBound...]
+        let wait = try #require(after.range(of: "waitForSwitch(consumesRecord: false, settleCap: .awaitObservedEnd)"))
+        let reroute = try #require(after.range(of: "routingPanelHDR = Self.sessionRoutesAsHDRPanel("))
+        let serve = try #require(after.range(of: "panelIsInHDRMode: routingPanelHDR"))
+        #expect(wait.lowerBound < reroute.lowerBound)
+        #expect(reroute.lowerBound < serve.lowerBound)
+    }
+}

From 0e2f5c967b5f92e692e03edf612f2753289029cf Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Tue, 29 Sep 2026 22:25:45 +0200
Subject: [PATCH 145/359] chore(release): prep 7.22.2 - an unproven HDR master
 waits for the mode switch

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                    | 4 ++++
 Examples/README.md                              | 2 +-
 README.md                                       | 6 +++---
 Sources/AetherEngine/AetherEngine+Version.swift | 2 +-
 4 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index ad718745e..981b09cd4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,10 @@ the public-API contract.
 
 ## [Unreleased]
 
+_Nothing yet._
+
+## [7.22.2] - 2026-09-29
+
 ### Fixed
 
 - **An unproven HDR master is served after the display mode switch, not during it** (#667). The
diff --git a/Examples/README.md b/Examples/README.md
index bae450031..ec4c13a80 100644
--- a/Examples/README.md
+++ b/Examples/README.md
@@ -18,7 +18,7 @@ Three samples covering different audiences:
    ```
    https://github.com/superuser404notfound/AetherEngine
    ```
-   Dependency Rule: Up to Next Major Version, starting from `7.22.1`. Add the `AetherEngine` library product to your app target.
+   Dependency Rule: Up to Next Major Version, starting from `7.22.2`. Add the `AetherEngine` library product to your app target.
 
 3. **Drop the file in.** Replace the Xcode template's default `App.swift` (or whatever the generated `@main` file is called) with the contents of [`MinimalPlayerApp.swift`](MinimalPlayer/MinimalPlayerApp.swift). The file is self-contained: it defines both the `@main App` struct and the `ContentView`.
 
diff --git a/README.md b/README.md
index efe78f85e..fcc1fe52c 100644
--- a/README.md
+++ b/README.md
@@ -384,7 +384,7 @@ Subtitle cues land in raw source PTS; render the overlay against `player.sourceT
 Install via Swift Package Manager:
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.22.1")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.22.2")
 ```
 
 Three samples ship in `Examples/`:
@@ -631,10 +631,10 @@ Browse all of this as a searchable site at **[aetherengine.superuser404.de](http
 AetherEngine uses [Semantic Versioning](https://semver.org). The public API surface, every `public` declaration in `Sources/AetherEngine/`, is the stability contract. **Major** removes / renames public symbols or breaks adopters; **Minor** adds public API or codec / format support; **Patch** fixes bugs with no public API change. `internal` types are not part of the contract.
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.22.1")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.22.2")
 ```
 
-Pin to `.upToNextMinor(from: "7.22.1")` for stricter teams that prefer to opt into minor bumps explicitly.
+Pin to `.upToNextMinor(from: "7.22.2")` for stricter teams that prefer to opt into minor bumps explicitly.
 
 ## Requirements
 
diff --git a/Sources/AetherEngine/AetherEngine+Version.swift b/Sources/AetherEngine/AetherEngine+Version.swift
index 1bb180a2c..6e4fe77b3 100644
--- a/Sources/AetherEngine/AetherEngine+Version.swift
+++ b/Sources/AetherEngine/AetherEngine+Version.swift
@@ -11,5 +11,5 @@ extension AetherEngine {
     ///
     /// Between releases, and in a consumer that pins an unreleased commit for a device test, this
     /// names the last PUBLISHED version the checkout descends from, not every patch in it.
-    public nonisolated static let version = "7.22.1"
+    public nonisolated static let version = "7.22.2"
 }

From 937564659e9ef1db6ff50653e33f867e209ff2e9 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 06:05:19 +0200
Subject: [PATCH 146/359] fix(network): scrub credential headers on redirects
 in every engine session (audit NET-108, NAT-105)

URLSession's default redirect copies every custom header except
Authorization to the new host, so X-Emby-Token and Cookie followed a
cross-origin 302 on the ingest readers, the carriage probe, the disc
reader, the relay, the subtitle proxy, the audio tap and the live
rendition fetch. EngineTLS's session delegate now applies
RedirectHeaderPolicy.redirectRequest as the session-level redirect
handler, which also covers per-task delegates without their own
redirect method (the relay's pump). Task-level handlers (AVIOReader,
SourcePrewarmFetcher) still win. The system-trust probe gets a
redirect-only base delegate, so it keeps measuring system trust.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../Demuxer/RedirectHeaderPolicy.swift        |   9 +-
 Sources/AetherEngine/Network/EngineTLS.swift  |  30 +++-
 .../AetherEngine/Network/HLSOriginRelay.swift |  10 +-
 ...EngineSessionRedirectCredentialTests.swift | 128 ++++++++++++++++++
 docs/architecture.md                          |   2 +-
 5 files changed, 169 insertions(+), 10 deletions(-)
 create mode 100644 Tests/AetherEngineTests/EngineSessionRedirectCredentialTests.swift

diff --git a/Sources/AetherEngine/Demuxer/RedirectHeaderPolicy.swift b/Sources/AetherEngine/Demuxer/RedirectHeaderPolicy.swift
index 9a68ee751..8bc96e24b 100644
--- a/Sources/AetherEngine/Demuxer/RedirectHeaderPolicy.swift
+++ b/Sources/AetherEngine/Demuxer/RedirectHeaderPolicy.swift
@@ -38,10 +38,11 @@ enum RedirectHeaderPolicy {
     }
 
     /// Builds the request actually handed back to URLSession on redirect: re-applies the
-    /// original Range (URLSession drops custom headers on cross-host redirect, and
-    /// Range-dependent proxies 400 without it), replays the policy-filtered extra
-    /// headers, and scrubs any credential header URLSession itself carried over when
-    /// the target is not credential-worthy.
+    /// original Range (Range-dependent proxies 400 without it), replays the policy-filtered
+    /// extra headers, and scrubs any credential header URLSession itself carried over when
+    /// the target is not credential-worthy. URLSession's default redirect copies every custom
+    /// header except `Authorization` to the new host (measured on CFNetwork 3896, audit
+    /// NET-108), so the scrub is what keeps a token and a cookie off a cross-origin target.
     static func redirectRequest(
         _ request: URLRequest,
         originalURL: URL?,
diff --git a/Sources/AetherEngine/Network/EngineTLS.swift b/Sources/AetherEngine/Network/EngineTLS.swift
index 35a477bcc..61a74e8af 100644
--- a/Sources/AetherEngine/Network/EngineTLS.swift
+++ b/Sources/AetherEngine/Network/EngineTLS.swift
@@ -37,6 +37,10 @@ public enum EngineTLS {
     /// for tasks that missed a per-task delegate.
     static let sessionDelegate = SessionTrustDelegate()
 
+    /// The redirect rule without the trust answer, for a session that must see
+    /// system trust alone (`HLSOriginRelay.systemTrustRefuses`).
+    static let redirectDelegate = RedirectScrubbingDelegate()
+
     /// Single disposition shared by the session-level delegate and the
     /// per-task delegates in AVIOReader. Anything other than a server-trust
     /// challenge the host accepted is left to default handling, so client
@@ -58,7 +62,31 @@ public enum EngineTLS {
         completionHandler(.useCredential, URLCredential(trust: trust))
     }
 
-    final class SessionTrustDelegate: NSObject, URLSessionDelegate, @unchecked Sendable {
+    /// Audit NET-108: URLSession's own redirect copies every custom header
+    /// except `Authorization` to the new request (measured on CFNetwork 3896:
+    /// `X-Emby-Token`, `Cookie`, `Range` and `Referer` all reached a cross-host
+    /// target), so without this a 302 took the host's token wherever it
+    /// pointed. A task delegate that implements its own redirect method
+    /// (AVIOReader, SourcePrewarmFetcher) still answers for its task; one that
+    /// does not (the relay's pump) falls back to this.
+    class RedirectScrubbingDelegate: NSObject, URLSessionTaskDelegate, @unchecked Sendable {
+        func urlSession(
+            _ session: URLSession,
+            task: URLSessionTask,
+            willPerformHTTPRedirection response: HTTPURLResponse,
+            newRequest request: URLRequest,
+            completionHandler: @escaping (URLRequest?) -> Void
+        ) {
+            let original = task.originalRequest
+            completionHandler(RedirectHeaderPolicy.redirectRequest(
+                request,
+                originalURL: original?.url,
+                originalRange: original?.value(forHTTPHeaderField: "Range"),
+                extraHeaders: [:]))
+        }
+    }
+
+    final class SessionTrustDelegate: RedirectScrubbingDelegate, @unchecked Sendable {
         func urlSession(
             _ session: URLSession,
             didReceive challenge: URLAuthenticationChallenge,
diff --git a/Sources/AetherEngine/Network/HLSOriginRelay.swift b/Sources/AetherEngine/Network/HLSOriginRelay.swift
index 10fb27471..5d7cdd808 100644
--- a/Sources/AetherEngine/Network/HLSOriginRelay.swift
+++ b/Sources/AetherEngine/Network/HLSOriginRelay.swift
@@ -114,10 +114,12 @@ final class HLSOriginRelay: @unchecked Sendable {
         config.urlCache = nil
         config.timeoutIntervalForRequest = trustProbeSeconds
         config.timeoutIntervalForResource = trustProbeSeconds
-        // No delegate on purpose. This session must answer the way AVPlayer's own networking does,
-        // which is system trust and nothing else; handing it `EngineTLS.sessionDelegate` would ask
-        // the host and get back the answer that hides what is being measured.
-        let session = URLSession(configuration: config)
+        // No trust delegate on purpose. This session must answer the way AVPlayer's own networking
+        // does, which is system trust and nothing else; handing it `EngineTLS.sessionDelegate` would
+        // ask the host and get back the answer that hides what is being measured. The redirect rule
+        // still applies (audit NET-108).
+        let session = URLSession(
+            configuration: config, delegate: EngineTLS.redirectDelegate, delegateQueue: nil)
         defer { session.invalidateAndCancel() }
 
         var request = URLRequest(url: origin)
diff --git a/Tests/AetherEngineTests/EngineSessionRedirectCredentialTests.swift b/Tests/AetherEngineTests/EngineSessionRedirectCredentialTests.swift
new file mode 100644
index 000000000..76f809a98
--- /dev/null
+++ b/Tests/AetherEngineTests/EngineSessionRedirectCredentialTests.swift
@@ -0,0 +1,128 @@
+import Foundation
+import Testing
+@testable import AetherEngine
+
+/// Audit NET-108: URLSession's own redirect carries every custom header except `Authorization` to the
+/// new host (measured: `X-Emby-Token`, `Cookie`, `Range` and `Referer` all arrived at a cross-host
+/// target). The engine's owned sessions had no redirect handler, so a 302 on a playlist, segment, key
+/// or disc range took the host's token wherever it pointed. The session-level delegate now applies the
+/// same rule a per-task redirect handler does.
+@Suite("Engine sessions keep credentials off a redirect target", .serialized, .timeLimit(.minutes(2)))
+struct EngineSessionRedirectCredentialTests {
+
+    private let credentialFields = ["X-Emby-Token": "SOURCE-ONLY", "Cookie": "sid=SOURCE-ONLY",
+                                    "Authorization": "Bearer SOURCE-ONLY"]
+
+    private func request(to url: URL) -> URLRequest {
+        var request = URLRequest(url: url)
+        for (field, value) in credentialFields { request.setValue(value, forHTTPHeaderField: field) }
+        request.setValue("bytes=0-1023", forHTTPHeaderField: "Range")
+        request.setValue("https://portal.example/", forHTTPHeaderField: "Referer")
+        return request
+    }
+
+    private func redirectingPair() throws -> (source: ThrottledOriginServer, target: ThrottledOriginServer) {
+        let target = try #require(ThrottledOriginServer(totalSize: 1024))
+        let targetPort = target.port
+        let sourceMaybe = ThrottledOriginServer(
+            totalSize: 1024,
+            respond: { _, _, _ in .redirect(to: "http://127.0.0.1:\(targetPort)/cdn/seg.ts") })
+        let source = try #require(sourceMaybe)
+        return (source, target)
+    }
+
+    private func expectScrubbed(_ seen: [String: String], sourceLocation: SourceLocation = #_sourceLocation) {
+        for field in credentialFields.keys {
+            #expect(seen[field.lowercased()] == nil, "\(field) reached the redirect target",
+                    sourceLocation: sourceLocation)
+        }
+        #expect(seen["range"] == "bytes=0-1023", sourceLocation: sourceLocation)
+        #expect(seen["referer"] == "https://portal.example/", sourceLocation: sourceLocation)
+    }
+
+    @Test("a data(for:) fetch on an engine session arrives at a cross-origin target without credentials")
+    func sessionLevelFetch() async throws {
+        let (source, target) = try redirectingPair()
+        defer { source.stop(); target.stop() }
+        let session = URLSession(
+            configuration: .ephemeral, delegate: EngineTLS.sessionDelegate, delegateQueue: nil)
+        defer { session.invalidateAndCancel() }
+
+        let url = try #require(URL(string: "http://127.0.0.1:\(source.port)/Videos/seg.ts"))
+        _ = try await session.data(for: request(to: url))
+
+        let seen = try #require(target.requestHeaders.last)
+        expectScrubbed(seen)
+    }
+
+    /// The relay's `UpstreamPump` shape: a per-task delegate that answers the body callbacks and has
+    /// no redirect method of its own, so the session-level one has to answer for it.
+    @Test("a task delegate without a redirect method falls back to the session's rule")
+    func taskDelegateWithoutRedirect() async throws {
+        let (source, target) = try redirectingPair()
+        defer { source.stop(); target.stop() }
+        let session = URLSession(
+            configuration: .ephemeral, delegate: EngineTLS.sessionDelegate, delegateQueue: nil)
+        defer { session.invalidateAndCancel() }
+
+        let url = try #require(URL(string: "http://127.0.0.1:\(source.port)/Videos/seg.ts"))
+        _ = try await session.data(for: request(to: url), delegate: BodyOnlyTaskDelegate())
+
+        let seen = try #require(target.requestHeaders.last)
+        expectScrubbed(seen)
+    }
+
+    @Test("a same-origin hop and an http to https upgrade keep the credentials, a downgrade loses them",
+          arguments: [
+              ("https://media.example/a.m3u8", "https://media.example/b.m3u8", true),
+              ("http://media.example:8096/a.m3u8", "https://media.example:8920/a.m3u8", true),
+              ("https://media.example/a.m3u8", "http://media.example/a.m3u8", false),
+              ("https://media.example/a.m3u8", "https://cdn.other/a.m3u8", false),
+              ("https://media.example/a.m3u8", "https://media.example:8443/a.m3u8", false),
+          ])
+    func redirectDecision(from: String, to: String, keeps: Bool) async throws {
+        let fromURL = try #require(URL(string: from))
+        let toURL = try #require(URL(string: to))
+        let session = URLSession(configuration: .ephemeral)
+        defer { session.invalidateAndCancel() }
+        let task = session.dataTask(with: request(to: fromURL))
+        // What URLSession hands the delegate: the new URL with the old request's headers copied over.
+        var carried = request(to: toURL)
+        carried.setValue(nil, forHTTPHeaderField: "Authorization")
+        let response = try #require(HTTPURLResponse(
+            url: fromURL, statusCode: 302, httpVersion: "HTTP/1.1", headerFields: ["Location": to]))
+
+        let box = RequestBox()
+        EngineTLS.sessionDelegate.urlSession(
+            session, task: task, willPerformHTTPRedirection: response, newRequest: carried,
+            completionHandler: { box.set($0) })
+        let next = try #require(box.get())
+
+        for field in ["X-Emby-Token", "Cookie"] {
+            #expect((next.value(forHTTPHeaderField: field) != nil) == keeps, "\(field) \(from) -> \(to)")
+        }
+        #expect(next.value(forHTTPHeaderField: "Range") == "bytes=0-1023")
+        #expect(next.value(forHTTPHeaderField: "Referer") == "https://portal.example/")
+    }
+
+    /// The system-trust probe must keep running without the host's evaluator, which is what it
+    /// measures, while still scrubbing a redirect like every other engine session.
+    @Test("the redirect-only delegate answers no trust challenge")
+    func redirectOnlyDelegateHasNoChallengeMethod() {
+        let delegate: NSObject = EngineTLS.redirectDelegate
+        let challenge = #selector(URLSessionDelegate.urlSession(_:didReceive:completionHandler:))
+        #expect(!delegate.responds(to: challenge))
+        #expect(EngineTLS.sessionDelegate.responds(to: challenge))
+    }
+}
+
+private final class BodyOnlyTaskDelegate: NSObject, URLSessionTaskDelegate, @unchecked Sendable {
+    func urlSession(_ session: URLSession, task: URLSessionTask, didFinishCollecting metrics: URLSessionTaskMetrics) {}
+}
+
+private final class RequestBox: @unchecked Sendable {
+    private let lock = NSLock()
+    private var value: URLRequest?
+    func set(_ request: URLRequest?) { lock.withLock { value = request } }
+    func get() -> URLRequest? { lock.withLock { value } }
+}
diff --git a/docs/architecture.md b/docs/architecture.md
index d0fb8ed2c..c0c8b947d 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -358,7 +358,7 @@ Sources/AetherEngine/
 │   ├── ResidentSpan.swift                   Bytes already in memory that a read can be served from without a round trip: the open window parked across a parse seek, and the speculative tail fetch. Not a cache (no fetch-on-miss, no eviction, no block alignment); it either covers an offset or it does not (#281)
 │   ├── CustomIOReaderBridge.swift           Bridges a host-supplied IOReader into avio_alloc_context read / seek callbacks, with the same read deadline and reversible read abort as AVIOReader so bounded seeks also bound (and unwedge) disc-adapter sources
 │   ├── Demuxer.swift                        libavformat wrapper; seek + bounded seek (deadline-capped) + byte-estimate positioning fallback for index-less containers (origin-corrected onto the file-relative time axis, fixed early bias in seconds, landing verified by a packet-PTS probe with proportional correction, and a sticky per-demuxer timestamp-seek lockout once the mechanism proves broken, #112). Per-open `DemuxerOpenProfile` budgets `find_stream_info` (probesize / max_analyze_duration), caller-overridable on the main playback open via `LoadOptions.probesize` / `maxAnalyzeDuration`. The native text readers' side demuxer sets `skipStreamInfo` to drop the `find_stream_info` pass entirely (codec_id / codec_type come from the container header / PMT at open); the reader runs a bounded `resolveStreamInfo()` on demand only if its target stream's codec is genuinely unresolved at open (#87)
-│   ├── RedirectHeaderPolicy.swift           Per-header redirect replay policy for AVIOReader's URLSession delegates: Range and non-credential extra headers survive cross-host redirects (header-dependent proxies, #8), credential headers (Authorization, Cookie, Emby/Jellyfin tokens) are replayed only to a same-host target with no TLS downgrade and scrubbed otherwise, so presigned redirect targets neither 400 on conflicting auth nor see the media-server token (#126)
+│   ├── RedirectHeaderPolicy.swift           Per-header redirect replay policy for AVIOReader's URLSession delegates and, through `EngineTLS`'s session-level delegate, for every other engine session (audit NET-108): Range and non-credential extra headers survive cross-host redirects (header-dependent proxies, #8), credential headers (Authorization, Cookie, Emby/Jellyfin tokens) are replayed only to a same-host target with no TLS downgrade and scrubbed otherwise, so presigned redirect targets neither 400 on conflicting auth nor see the media-server token (#126)
 │   ├── SlowReadDiagnostics.swift            One-shot localization of a pathologically slow AVIOReader.read() (detour fetch / connStall / reconnect / backoff / dropped-generation bytes), #93 restart latency
 │   ├── SourceThrottle.swift                 Pure virtual-clock leaky-bucket rate limiter on the source read path (slow-CDN simulation for aetherctl --throttle); unit-testable without sleeping
 │   └── SourceContentLengthCache.swift       Memoizes a source URL's resolved total byte length across demuxer opens, so a subtitle side demuxer opening the same origin later inherits the size the video producer already resolved (#112)

From 2391a8e3dc6651fa7cb56dc455e71268bfb0679b Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 06:08:16 +0200
Subject: [PATCH 147/359] perf(core): publish the active playlist shift only
 when it changes (audit PERF-106)

The native clock tick and the shift callback assigned the published
`playlistShiftSeconds` on every pass, so the engine's `objectWillChange`
fired at 10 Hz again, which is what `player.clock` exists to prevent
(docs/api.md, Time). Both sites now write only a different value.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../AetherEngine/AetherEngine+Loading.swift   |  6 ++-
 .../ClockTickEngineChangeTests.swift          | 47 +++++++++++++++++++
 2 files changed, 51 insertions(+), 2 deletions(-)
 create mode 100644 Tests/AetherEngineTests/ClockTickEngineChangeTests.swift

diff --git a/Sources/AetherEngine/AetherEngine+Loading.swift b/Sources/AetherEngine/AetherEngine+Loading.swift
index 832b1b59c..a4da8941f 100644
--- a/Sources/AetherEngine/AetherEngine+Loading.swift
+++ b/Sources/AetherEngine/AetherEngine+Loading.swift
@@ -28,7 +28,9 @@ extension AetherEngine {
         // just left, and the window's edge is a running maximum a single wrong sample latches.
         if liveItemPlacementPending { return }
         // Newest seam at or before the raw clock wins: activates seams on forward play, re-applies pre-seam shift on backward DVR seeks.
-        if let active = presentationAxis.shiftSeconds(atItemSeconds: value) {
+        // Audit PERF-106: published on the engine, so an unchanged write would fire its
+        // objectWillChange on every 10 Hz tick (the reason `clock` exists).
+        if let active = presentationAxis.shiftSeconds(atItemSeconds: value), active != playlistShiftSeconds {
             playlistShiftSeconds = active
         }
         if pendingRecoverySeekClockTarget == nil {
@@ -891,7 +893,7 @@ extension AetherEngine {
                 // Fold with the shift in effect AT the raw clock, not with the newest one: while old-epoch buffer
                 // is still on screen those differ, and the picture is what the clock has to describe.
                 let activeShift = self.presentationAxis.shiftSeconds(atItemSeconds: self.nativeClockSeconds) ?? seconds
-                self.playlistShiftSeconds = activeShift
+                if activeShift != self.playlistShiftSeconds { self.playlistShiftSeconds = activeShift }
                 // The cache did not move, but the fold onto the display axis did. Re-publish the band
                 // from the raw spans so it does not carry the retired epoch's offset until the next
                 // segment lands (AE#468 follow-up).
diff --git a/Tests/AetherEngineTests/ClockTickEngineChangeTests.swift b/Tests/AetherEngineTests/ClockTickEngineChangeTests.swift
new file mode 100644
index 000000000..a083cb478
--- /dev/null
+++ b/Tests/AetherEngineTests/ClockTickEngineChangeTests.swift
@@ -0,0 +1,47 @@
+import Combine
+import Testing
+@testable import AetherEngine
+
+/// `player.clock` exists so the ~10 Hz ticks never fire `objectWillChange` on the engine (docs/api.md,
+/// Time). `playlistShiftSeconds` is published on the engine, and the tick assigned it on every pass
+/// whether it had moved or not, so every SwiftUI view observing the engine re-rendered at 10 Hz again.
+@Suite("The clock tick leaves the engine's objectWillChange quiet")
+@MainActor
+struct ClockTickEngineChangeTests {
+
+    @Test("A shift that did not move is not published again on the next tick (audit PERF-106)")
+    func steadyShiftIsNotRepublished() throws {
+        let engine = try AetherEngine()
+        engine.setPresentationAxis(.anchored(shiftSeconds: 12.5))
+        engine.applyNativeHostClockTick(1.0)
+        #expect(engine.playlistShiftSeconds == 12.5)
+
+        var changes = 0
+        let sub = engine.objectWillChange.sink { changes += 1 }
+        defer { sub.cancel() }
+        for tick in 1...20 {
+            engine.applyNativeHostClockTick(1.0 + Double(tick) * 0.1)
+        }
+
+        #expect(changes == 0)
+        #expect(engine.playlistShiftSeconds == 12.5)
+    }
+
+    @Test("A shift that did move is still published")
+    func movedShiftIsPublished() throws {
+        let engine = try AetherEngine()
+        var map = PresentationAxisMap.anchored(shiftSeconds: 12.5)
+        map.appendSeam(shiftSeconds: 30, activatingAtItemSeconds: 5)
+        engine.setPresentationAxis(map)
+        engine.applyNativeHostClockTick(1.0)
+        #expect(engine.playlistShiftSeconds == 12.5)
+
+        var changes = 0
+        let sub = engine.objectWillChange.sink { changes += 1 }
+        defer { sub.cancel() }
+        engine.applyNativeHostClockTick(6.0)
+
+        #expect(changes == 1)
+        #expect(engine.playlistShiftSeconds == 30)
+    }
+}

From 20ba80fc80ebc22b077fad56a016925fd399b328 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 06:08:54 +0200
Subject: [PATCH 148/359] fix(hls): refuse non-finite or week-plus playlist
 durations at the parser (audit NET-101, FEA-102, SUB-102, HLS-102)

`Double(_:)` accepts `inf`, `nan` and any magnitude, and `HLSPlaylistParser.parseMedia` stored
EXTINF and TARGETDURATION unchecked. The live ingest's join log trapped on `Int(inf)`, the live
subtitle poll on `UInt64(inf * 1e9)`, and the VOD ingest's EXTINF sum reached the segment-plan
builders unbounded (2e14 s trapped `buildSegmentedSourcePlan`).

The parser now throws `playlistInvalid` for a non-finite value or one above one week, the ceiling
the subtitle proxy already used for whole-program playlists (hoisted into `MediaDurationCeiling`
and shared). The VOD ingest also refuses a total above a week, because a tiny entry after a large
sum vanishes in the Double sum and sends the uniform fallback over the whole sum. The live
subtitle poll interval is clamped to [1, 30] s and the join log formats the backlog as a Double.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../AetherEngine+LiveSubtitleRenditions.swift |  9 +-
 .../IO/HLSIngest/HLSLiveIngestReader.swift    |  2 +-
 .../IO/HLSIngest/HLSPlaylist.swift            | 18 +++-
 .../IO/HLSIngest/HLSVODIngestReader.swift     | 27 ++++--
 .../AetherEngine/MediaDurationCeiling.swift   |  8 ++
 .../Native/RemoteHLSSubtitleProxy.swift       |  2 +-
 .../HLSDurationCeilingTests.swift             | 92 +++++++++++++++++++
 7 files changed, 145 insertions(+), 13 deletions(-)
 create mode 100644 Sources/AetherEngine/MediaDurationCeiling.swift
 create mode 100644 Tests/AetherEngineTests/HLSDurationCeilingTests.swift

diff --git a/Sources/AetherEngine/AetherEngine+LiveSubtitleRenditions.swift b/Sources/AetherEngine/AetherEngine+LiveSubtitleRenditions.swift
index bbc86702d..cf7c2af0e 100644
--- a/Sources/AetherEngine/AetherEngine+LiveSubtitleRenditions.swift
+++ b/Sources/AetherEngine/AetherEngine+LiveSubtitleRenditions.swift
@@ -113,7 +113,7 @@ extension AetherEngine {
             do {
                 let text = try await Self.fetchText(rendition.playlistURL, headers: headers)
                 guard case .media(let media) = try HLSPlaylistParser.parse(text) else { return }
-                pollInterval = max(1, media.targetDuration)
+                pollInterval = Self.liveSubtitlePollInterval(targetDuration: media.targetDuration)
                 // Anchor the work at the playhead, not at the start of the playlist. A rendition
                 // playlist is not a handful of segments: MDR publishes its whole two hour DVR window,
                 // 3600 entries, and walking it from the front means thousands of fetches for content
@@ -172,6 +172,13 @@ extension AetherEngine {
         }
     }
 
+    /// Audit FEA-102: a week-long TARGETDURATION would put the loop to sleep for a week and end the
+    /// subtitles; past about 2e10 s it trapped `UInt64(_:)` outright.
+    nonisolated static func liveSubtitlePollInterval(targetDuration: Double) -> Double {
+        guard !targetDuration.isNaN else { return 1 }
+        return min(max(1, targetDuration), 30)
+    }
+
     /// Keep the published array bounded: a channel left running for hours would otherwise carry every
     /// line it ever showed, and #271 is the standing reminder that this array is paid for per publish.
     private func pruned(_ cues: [SubtitleCue]) -> [SubtitleCue] {
diff --git a/Sources/AetherEngine/IO/HLSIngest/HLSLiveIngestReader.swift b/Sources/AetherEngine/IO/HLSIngest/HLSLiveIngestReader.swift
index 783269ee7..7c1376936 100644
--- a/Sources/AetherEngine/IO/HLSIngest/HLSLiveIngestReader.swift
+++ b/Sources/AetherEngine/IO/HLSIngest/HLSLiveIngestReader.swift
@@ -291,7 +291,7 @@ public final class HLSLiveIngestReader: IOReader, LiveIngestSourceInfo, @uncheck
                     }
                     let backlog = fresh.reduce(0.0) { $0 + $1.duration }
                     EngineLog.emit(
-                        "[HLSIngest] joined \(fresh.count) segment(s), ~\(Int(backlog))s behind the live edge"
+                        "[HLSIngest] joined \(fresh.count) segment(s), ~\(String(format: "%.0f", backlog))s behind the live edge"
                         + " pdt=\(fresh.first?.programDateTime.map { "\($0)" } ?? "nil")",
                         category: .engine
                     )
diff --git a/Sources/AetherEngine/IO/HLSIngest/HLSPlaylist.swift b/Sources/AetherEngine/IO/HLSIngest/HLSPlaylist.swift
index 6e2070fc9..1a31be72c 100644
--- a/Sources/AetherEngine/IO/HLSIngest/HLSPlaylist.swift
+++ b/Sources/AetherEngine/IO/HLSIngest/HLSPlaylist.swift
@@ -178,7 +178,8 @@ enum HLSPlaylistParser {
 
         for line in lines {
             if line.hasPrefix("#EXT-X-TARGETDURATION:") {
-                targetDuration = Double(line.dropFirst("#EXT-X-TARGETDURATION:".count))
+                targetDuration = try boundedDuration(line.dropFirst("#EXT-X-TARGETDURATION:".count),
+                                                     tag: "TARGETDURATION")
             } else if line.hasPrefix("#EXT-X-MEDIA-SEQUENCE:") {
                 // A hostile or MITM value near Int.max makes `mediaSequence + segments.count`
                 // overflow and trap downstream (audit NET-3); reject it here instead. A merely
@@ -191,7 +192,7 @@ enum HLSPlaylistParser {
                 }
             } else if line.hasPrefix("#EXTINF:") {
                 let payload = line.dropFirst("#EXTINF:".count)
-                pendingDuration = Double(payload.split(separator: ",").first.map(String.init) ?? "")
+                pendingDuration = try boundedDuration(payload.split(separator: ",").first ?? "", tag: "EXTINF")
             } else if line.hasPrefix("#EXT-X-DISCONTINUITY") && !line.hasPrefix("#EXT-X-DISCONTINUITY-SEQUENCE") {
                 pendingDiscontinuity = true
             } else if line.hasPrefix("#EXT-X-KEY:") {
@@ -261,6 +262,19 @@ enum HLSPlaylistParser {
         )
     }
 
+    /// A duration tag's value; nil when it does not parse, which keeps the pre-existing fallbacks.
+    /// `Double(_:)` accepts `inf`, `nan` and any magnitude, and every consumer converts to an integer
+    /// somewhere downstream (audit NET-101), so a non-finite value or one past the program ceiling is
+    /// refused here. Negatives are left to the consumers: they trap nothing, and a sloppy live origin
+    /// should not lose its channel over one.
+    private static func boundedDuration(_ text: Substring, tag: String) throws -> Double? {
+        guard let value = Double(text) else { return nil }
+        guard value.isFinite, value <= MediaDurationCeiling.seconds else {
+            throw HLSIngestError.playlistInvalid(reason: "\(tag) out of range")
+        }
+        return value
+    }
+
     /// Parse a `0x`-prefixed hex EXT-X-KEY IV into 16-byte big-endian Data. Returns nil on malformed length (caller falls back to sequence-number IV).
     /// ISO 8601 with fractional seconds is what every broadcaster emits; the plain form is accepted
     /// because the spec allows it.
diff --git a/Sources/AetherEngine/IO/HLSIngest/HLSVODIngestReader.swift b/Sources/AetherEngine/IO/HLSIngest/HLSVODIngestReader.swift
index 86b6f8429..31bd2bce4 100644
--- a/Sources/AetherEngine/IO/HLSIngest/HLSVODIngestReader.swift
+++ b/Sources/AetherEngine/IO/HLSIngest/HLSVODIngestReader.swift
@@ -481,22 +481,33 @@ final class HLSVODIngestReader: TimeSeekableIOReader, @unchecked Sendable {
         guard !media.hasUnsupportedEncryption else {
             throw HLSIngestError.encryptedNotSupported
         }
+        let timeline = try Self.segmentTimeline(media.segments)
+        return ResolvedMedia(
+            url: mediaURL,
+            segments: media.segments,
+            starts: timeline.starts,
+            duration: timeline.duration
+        )
+    }
+
+    static func segmentTimeline(_ segments: [HLSMediaSegment]) throws -> (starts: [Double], duration: Double) {
         var starts: [Double] = []
-        starts.reserveCapacity(media.segments.count)
+        starts.reserveCapacity(segments.count)
         var duration = 0.0
-        for segment in media.segments {
+        for segment in segments {
             guard segment.duration.isFinite, segment.duration > 0 else {
                 throw HLSIngestError.playlistInvalid(reason: "segment duration must be positive")
             }
             starts.append(duration)
             duration += segment.duration
         }
-        return ResolvedMedia(
-            url: mediaURL,
-            segments: media.segments,
-            starts: starts,
-            duration: duration
-        )
+        // Audit HLS-102: each entry is inside the parser's ceiling, the sum need not be. A tiny entry
+        // after a large sum also leaves the total unmoved, the starts stop being monotonic, and the
+        // uniform fallback plans the whole sum.
+        guard duration <= MediaDurationCeiling.seconds else {
+            throw HLSIngestError.playlistInvalid(reason: "program duration exceeds \(MediaDurationCeiling.seconds)s")
+        }
+        return (starts, duration)
     }
 
     /// Credentials only where the host's playlist is (audit NET-7).
diff --git a/Sources/AetherEngine/MediaDurationCeiling.swift b/Sources/AetherEngine/MediaDurationCeiling.swift
new file mode 100644
index 000000000..854ebe7b5
--- /dev/null
+++ b/Sources/AetherEngine/MediaDurationCeiling.swift
@@ -0,0 +1,8 @@
+import Foundation
+
+/// Longest program the engine parses, plans or serves (audit NET-101, HLS-102). One week: a whole-program
+/// subtitle playlist puts a whole film in one EXTINF, so the per-entry ceiling has to equal the program
+/// ceiling, and a 30 h marathon must parse under the same rule the subtitle proxy serves it by.
+enum MediaDurationCeiling {
+    static let seconds: Double = 7 * 24 * 3600
+}
diff --git a/Sources/AetherEngine/Native/RemoteHLSSubtitleProxy.swift b/Sources/AetherEngine/Native/RemoteHLSSubtitleProxy.swift
index b369f27d7..2cd2ddea5 100644
--- a/Sources/AetherEngine/Native/RemoteHLSSubtitleProxy.swift
+++ b/Sources/AetherEngine/Native/RemoteHLSSubtitleProxy.swift
@@ -242,7 +242,7 @@ enum RemoteHLSSubtitleProxy {
     }
 
     /// Longest program this proxy will serve as a whole-program WebVTT rendition.
-    static let maxProgramDurationSeconds: Double = 7 * 24 * 3600
+    static let maxProgramDurationSeconds: Double = MediaDurationCeiling.seconds
 
     /// A hostile or malformed EXTINF (`inf`, negative, or a huge total) reaches `Int(Double)` in
     /// `wholeSecondsCovering` downstream and traps (audit NAT-1); refuse it here instead. Internal
diff --git a/Tests/AetherEngineTests/HLSDurationCeilingTests.swift b/Tests/AetherEngineTests/HLSDurationCeilingTests.swift
new file mode 100644
index 000000000..e4537efac
--- /dev/null
+++ b/Tests/AetherEngineTests/HLSDurationCeilingTests.swift
@@ -0,0 +1,92 @@
+import Testing
+@testable import AetherEngine
+
+/// Audit NET-101, FEA-102, HLS-102: `Double(_:)` accepts `inf`, `nan` and any magnitude, and the playlist
+/// parser stored the result unchecked. The live join log traps on `Int(inf)`, the live subtitle poll on
+/// `UInt64(inf * 1e9)`, and the VOD ingest's EXTINF sum reaches the segment-plan builders unbounded.
+@Suite("HLS durations stay inside the one-week program ceiling")
+struct HLSDurationCeilingTests {
+
+    private func media(targetDuration: String = "6", extinf: String) -> String {
+        """
+        #EXTM3U
+        #EXT-X-TARGETDURATION:\(targetDuration)
+        #EXTINF:\(extinf),
+        seg0.ts
+        #EXT-X-ENDLIST
+        """
+    }
+
+    private func isPlaylistInvalid(_ text: String) -> Bool {
+        do {
+            _ = try HLSPlaylistParser.parse(text)
+            return false
+        } catch HLSIngestError.playlistInvalid {
+            return true
+        } catch {
+            return false
+        }
+    }
+
+    @Test("A non-finite or absurd EXTINF is refused", arguments: [
+        "inf", "infinity", "nan", "1e300", "604801", "200000000000000",
+    ])
+    func rejectsHostileExtinf(value: String) {
+        #expect(isPlaylistInvalid(media(extinf: value)))
+    }
+
+    @Test("A non-finite or absurd TARGETDURATION is refused", arguments: ["inf", "nan", "1e300", "20000000000"])
+    func rejectsHostileTargetDuration(value: String) {
+        #expect(isPlaylistInvalid(media(targetDuration: value, extinf: "6")))
+    }
+
+    @Test("A whole program in one EXTINF, up to a week, still parses")
+    func weekLongEntryParses() throws {
+        guard case .media(let playlist) = try HLSPlaylistParser.parse(media(extinf: "604800")) else {
+            Issue.record("expected a media playlist")
+            return
+        }
+        #expect(playlist.segments.first?.duration == 604_800)
+    }
+
+    @Test("The subtitle proxy's program ceiling is the parser's")
+    func proxySharesTheCeiling() {
+        #expect(RemoteHLSSubtitleProxy.maxProgramDurationSeconds == MediaDurationCeiling.seconds)
+        #expect(MediaDurationCeiling.seconds == 604_800)
+    }
+
+    private func segments(_ durations: [Double]) -> [HLSMediaSegment] {
+        durations.enumerated().map { HLSMediaSegment(uri: "s\($0.offset).ts", duration: $0.element,
+                                                    discontinuityBefore: false) }
+    }
+
+    @Test("A VOD playlist summing past a week is refused, however small its entries")
+    func vodTotalCeiling() {
+        // Each entry passes the parser's per-entry ceiling; the sum does not.
+        #expect(throws: HLSIngestError.self) {
+            _ = try HLSVODIngestReader.segmentTimeline(segments([604_800, 604_800]))
+        }
+        // The Double-sum vanish case: a tiny entry after a large sum does not move the total, so the
+        // starts stop being monotonic and the plan falls back to a uniform grid over the whole sum.
+        #expect(throws: HLSIngestError.self) {
+            _ = try HLSVODIngestReader.segmentTimeline(segments(Array(repeating: 604_800, count: 1000) + [1e-9]))
+        }
+    }
+
+    @Test("An ordinary VOD playlist keeps its starts and total")
+    func vodTimelineUnchanged() throws {
+        let timeline = try HLSVODIngestReader.segmentTimeline(segments([6, 6, 4.5]))
+        #expect(timeline.starts == [0, 6, 12])
+        #expect(timeline.duration == 16.5)
+        #expect(throws: HLSIngestError.self) {
+            _ = try HLSVODIngestReader.segmentTimeline(segments([6, 0, 6]))
+        }
+    }
+
+    @Test("The live subtitle poll interval stays between one and thirty seconds", arguments: [
+        (6.0, 6.0), (0.2, 1.0), (604_800.0, 30.0), (Double.infinity, 30.0), (Double.nan, 1.0), (-5.0, 1.0),
+    ])
+    func liveSubtitlePollInterval(targetDuration: Double, expected: Double) {
+        #expect(AetherEngine.liveSubtitlePollInterval(targetDuration: targetDuration) == expected)
+    }
+}

From 6f99bd0b84f4099f03ec078ffa582b50666b9381 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 06:10:12 +0200
Subject: [PATCH 149/359] fix(core): an audio or title rebuild honours the
 media services reset (audit LIF-104)

Only `load()` consumed the AE#597 flag. `reloadWithAudioOverride` (audio
pick, custom disc-title pick, the custom-source reload) kept the native
host and left the flag up, so the first such rebuild after a reset
mounted its item on the invalidated AVPlayer. It now consumes the flag,
drops the native host and the audio-only player like `load()` does.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../AetherEngine/AetherEngine+Loading.swift   |  8 +++-
 .../Issue597MediaServicesResetTests.swift     | 38 +++++++++++++++++++
 2 files changed, 45 insertions(+), 1 deletion(-)

diff --git a/Sources/AetherEngine/AetherEngine+Loading.swift b/Sources/AetherEngine/AetherEngine+Loading.swift
index a4da8941f..4d7c001f1 100644
--- a/Sources/AetherEngine/AetherEngine+Loading.swift
+++ b/Sources/AetherEngine/AetherEngine+Loading.swift
@@ -2296,8 +2296,14 @@ extension AetherEngine {
         // It follows the TARGET route, not the previous one: a rebuild that flips to software renders
         // into its own layer, and a preserved host would leave AVKit bound to a stale player with
         // audio still flowing into the next load (the release `load()` does by hand on that branch).
+        // Audit LIF-104: the AE#597 reset outranks the #15 reuse here exactly as it does in `load`,
+        // or the first rebuild after a reset mounts its item on the invalidated AVPlayer.
+        let mediaServicesWereReset = consumeMediaServicesReset()
         claimSoftwarePathTakeover()   // AE#629
-        stopInternal(resetDisplayCriteria: false, keepNativeHost: !targetSoftwarePath, keepCustomReader: true)
+        stopInternal(resetDisplayCriteria: false,
+                     keepNativeHost: !targetSoftwarePath && !mediaServicesWereReset,
+                     keepCustomReader: true)
+        if mediaServicesWereReset { dropAudioPlayerHostAfterMediaServicesReset() }
         EngineLog.emit("[AetherEngine] reload: stopInternal done (\(elapsedMs(since: reloadStart))ms)", category: .engine)
         let gen = loadGeneration
         loadedURL = url
diff --git a/Tests/AetherEngineTests/Issue597MediaServicesResetTests.swift b/Tests/AetherEngineTests/Issue597MediaServicesResetTests.swift
index 64e2708dd..78fe43ed6 100644
--- a/Tests/AetherEngineTests/Issue597MediaServicesResetTests.swift
+++ b/Tests/AetherEngineTests/Issue597MediaServicesResetTests.swift
@@ -49,6 +49,44 @@ struct Issue597MediaServicesResetTests {
         #expect(!engine.consumeMediaServicesReset())
     }
 
+    /// Audit LIF-104: `reloadWithAudioOverride` (the audio pick, the disc-title pick, the custom-source
+    /// reload) keeps the native host on the native route, and it never read the flag, so the first
+    /// rebuild after a reset mounted the item on the invalidated AVPlayer while the flag stayed up.
+    @Test("a custom-source rebuild after a reset builds a fresh native player and consumes the reset",
+          .timeLimit(.minutes(2)))
+    @MainActor
+    func customRebuildConsumesTheReset() async throws {
+        let engine = try AetherEngine()
+        defer { engine.stop() }
+        _ = try await engine.load(
+            source: .custom(DataIOReader(data: try ProbeTestFixtures.hdr10Plus()), formatHint: "mp4"))
+        let invalidated = try #require(engine.nativeHost)
+        engine.audioAVPlayerHost = AudioAVPlayerHost()
+        engine.noteMediaServicesReset(lost: false)
+
+        try await engine.reloadAtCurrentPosition()
+
+        #expect(engine.nativeHost != nil)
+        #expect(engine.nativeHost !== invalidated)
+        #expect(engine.audioAVPlayerHost == nil)
+        #expect(!engine.consumeMediaServicesReset())
+    }
+
+    @Test("without a reset a custom-source rebuild keeps its native player (issue #15)",
+          .timeLimit(.minutes(2)))
+    @MainActor
+    func customRebuildKeepsTheHostWithoutAReset() async throws {
+        let engine = try AetherEngine()
+        defer { engine.stop() }
+        _ = try await engine.load(
+            source: .custom(DataIOReader(data: try ProbeTestFixtures.hdr10Plus()), formatHint: "mp4"))
+        let host = try #require(engine.nativeHost)
+
+        try await engine.reloadAtCurrentPosition()
+
+        #expect(engine.nativeHost === host)
+    }
+
     @Test("without a reset the audio-only player survives a load, as its Now Playing session must")
     @MainActor
     func audioOnlyPlayerSurvivesWithoutAReset() async throws {

From 9f77ab8eddd9e03b04ea4b5b1268845e6e6fe273 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 06:12:56 +0200
Subject: [PATCH 150/359] fix(network): separate allowing a fetch from granting
 credentials (audit NET-109, NAT-105, DEC-103, Vcred-101)

HLSOriginRelay.admit both allowed an origin and made it a credential
anchor, and the #316 build admitted the post-redirect URL, so after a
cross-host redirect the edge got the host's token and the host's own
origin lost it. admit is split into allow(_:) and
grantCredentials(to:httpHeaders:); the proxy grants the URL the host
handed over and only allows the redirect target, and relayURL(for:)
only allows.

The playlist-driven fetchers that still sent every host header to
every URI a playlist named now share one CredentialScope type (the
NET-7 rule the ingest readers already follow): the #316 proxy's
variant fetch (anchor: the host's origin URL), the remote-HLS audio
tap (anchor: the loaded URL) and the live subtitle rendition fetch
(anchor: the live ingest reader's credential origin).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../AetherEngine/AetherEngine+AudioTap.swift  |   3 +-
 .../AetherEngine+LiveSubtitleRenditions.swift |  17 +-
 .../Audio/Tap/AudioTapHLSFetcher.swift        |  12 +-
 .../Demuxer/RedirectHeaderPolicy.swift        |  26 ++++
 .../IO/HLSIngest/HLSLiveIngestReader.swift    |   2 +-
 .../IO/HLSIngest/LiveIngestSourceInfo.swift   |   4 +
 .../Native/RemoteHLSSubtitleProxy.swift       |  18 ++-
 .../AetherEngine/Network/HLSLocalServer.swift |   9 +-
 .../AetherEngine/Network/HLSOriginRelay.swift |  70 +++++----
 .../HLSOriginRelayTests.swift                 |   8 +-
 .../Issue119RemoteHLSHeaderTests.swift        |   3 +-
 .../PlaylistNamedHostCredentialTests.swift    | 143 ++++++++++++++++-
 .../Support/CannedHTTPOrigin.swift            | 146 ++++++++++++++++++
 docs/architecture.md                          |   2 +-
 14 files changed, 405 insertions(+), 58 deletions(-)
 create mode 100644 Tests/AetherEngineTests/Support/CannedHTTPOrigin.swift

diff --git a/Sources/AetherEngine/AetherEngine+AudioTap.swift b/Sources/AetherEngine/AetherEngine+AudioTap.swift
index 5c18a20dd..b337ec374 100644
--- a/Sources/AetherEngine/AetherEngine+AudioTap.swift
+++ b/Sources/AetherEngine/AetherEngine+AudioTap.swift
@@ -130,7 +130,8 @@ extension AetherEngine {
         guard let masterURL = loadedURL, let yield = controller.makeYield() else { return nil }
         // Same headers the player's AVURLAsset sends (#119); header-enforcing IPTV origins 403
         // the tap's own playlist / segment fetches without them.
-        let fetcher = AudioTapHLSFetcher(httpHeaders: loadedOptions.httpHeaders)
+        let fetcher = AudioTapHLSFetcher(
+            httpHeaders: loadedOptions.httpHeaders, credentialOrigin: masterURL)
         let decoder = AudioTapSegmentDecoder()
         let base = AudioTapBaseBox(masterURL)
         // renderedPositionMirror is fed by loadRemoteHLS's $currentTime sink (shift 0 here, so it
diff --git a/Sources/AetherEngine/AetherEngine+LiveSubtitleRenditions.swift b/Sources/AetherEngine/AetherEngine+LiveSubtitleRenditions.swift
index bbc86702d..0157dcf5a 100644
--- a/Sources/AetherEngine/AetherEngine+LiveSubtitleRenditions.swift
+++ b/Sources/AetherEngine/AetherEngine+LiveSubtitleRenditions.swift
@@ -22,6 +22,15 @@ extension AetherEngine {
         id >= liveSubtitleRenditionTrackIDBase && id < liveSubtitleRenditionTrackIDBase + 1_000
     }
 
+    /// Audit Vcred-101: the rendition playlist and every segment it lists are URIs the master named,
+    /// on any host or scheme, so the host's credentials go only to the ingest's own origin, as on the
+    /// ingest's other fetches. No live ingest reader, no anchor, no credentials.
+    nonisolated static func liveSubtitleRenditionCredentials(headers: [String: String], source: IOReader?)
+        -> CredentialScope
+    {
+        CredentialScope(headers: headers, anchor: (source as? LiveIngestSourceInfo)?.credentialOrigin)
+    }
+
     /// Publish the renditions the live ingest resolved. Called once per load, before playback settles;
     /// the master's declaration is proof enough that the track exists, so unlike the caption tap there
     /// is nothing to wait for.
@@ -95,7 +104,8 @@ extension AetherEngine {
         // The state line is worth having but not every two seconds: LogTap is a ring buffer, and a
         // line that repeats 30 times a minute pushes out everything a reader came for.
         var pollsSinceStateLine = 0
-        let headers = loadedOptions.httpHeaders
+        let credentials = Self.liveSubtitleRenditionCredentials(
+            headers: loadedOptions.httpHeaders, source: customReader)
         while !Task.isCancelled {
             guard activeSubtitleTrackIndex == trackID else { return }
             // The source axis can be re-anchored under a running session (a producer seam republishes
@@ -111,7 +121,8 @@ extension AetherEngine {
             }
             var pollInterval = 2.0
             do {
-                let text = try await Self.fetchText(rendition.playlistURL, headers: headers)
+                let text = try await Self.fetchText(
+                    rendition.playlistURL, headers: credentials.headers(for: rendition.playlistURL))
                 guard case .media(let media) = try HLSPlaylistParser.parse(text) else { return }
                 pollInterval = max(1, media.targetDuration)
                 // Anchor the work at the playhead, not at the start of the playlist. A rendition
@@ -134,7 +145,7 @@ extension AetherEngine {
                           let url = HLSPlaylistParser.resolve(uri: segment.uri, against: rendition.playlistURL)
                     else { continue }
                     seen.insert(segment.uri)
-                    guard let body = try? await Self.fetchText(url, headers: headers),
+                    guard let body = try? await Self.fetchText(url, headers: credentials.headers(for: url)),
                           let parsed = WebVTTSegmentParser.parse(body) else { continue }
                     guard activeSubtitleTrackIndex == trackID else { return }
                     let fresh = WebVTTSegmentParser.cues(from: parsed, segmentWallStart: wallStart,
diff --git a/Sources/AetherEngine/Audio/Tap/AudioTapHLSFetcher.swift b/Sources/AetherEngine/Audio/Tap/AudioTapHLSFetcher.swift
index d66211c34..fc407aff5 100644
--- a/Sources/AetherEngine/Audio/Tap/AudioTapHLSFetcher.swift
+++ b/Sources/AetherEngine/Audio/Tap/AudioTapHLSFetcher.swift
@@ -21,12 +21,14 @@ final class AudioTapHLSFetcher: @unchecked Sendable {
 
     private let session: URLSession
     /// Same per-stream headers the player's AVURLAsset sends (#119); header-enforcing origins
-    /// 403 the tap's playlist / segment / key fetches without them.
-    private let httpHeaders: [String: String]
+    /// 403 the tap's playlist / segment / key fetches without them. The credential headers go only
+    /// to the origin of `credentialOrigin`, the URL the host loaded: every other URL here is one a
+    /// playlist named, on any host or scheme (audit DEC-103, the NET-7 rule).
+    private let credentials: CredentialScope
     private let keyCacheLock = NSLock()
     private var keyCache: [String: Data] = [:]
 
-    init(session: URLSession? = nil, httpHeaders: [String: String] = [:]) {
+    init(session: URLSession? = nil, httpHeaders: [String: String] = [:], credentialOrigin: URL? = nil) {
         if let session {
             self.session = session
         } else {
@@ -36,12 +38,12 @@ final class AudioTapHLSFetcher: @unchecked Sendable {
             self.session = URLSession(
                 configuration: cfg, delegate: EngineTLS.sessionDelegate, delegateQueue: nil)
         }
-        self.httpHeaders = httpHeaders
+        credentials = CredentialScope(headers: httpHeaders, anchor: credentialOrigin)
     }
 
     private func get(_ url: URL) async throws -> (Data, URLResponse) {
         var request = URLRequest(url: url)
-        for (field, value) in httpHeaders {
+        for (field, value) in credentials.headers(for: url) {
             request.setValue(value, forHTTPHeaderField: field)
         }
         return try await session.data(for: request)
diff --git a/Sources/AetherEngine/Demuxer/RedirectHeaderPolicy.swift b/Sources/AetherEngine/Demuxer/RedirectHeaderPolicy.swift
index 8bc96e24b..36b731f2f 100644
--- a/Sources/AetherEngine/Demuxer/RedirectHeaderPolicy.swift
+++ b/Sources/AetherEngine/Demuxer/RedirectHeaderPolicy.swift
@@ -88,3 +88,29 @@ enum RedirectHeaderPolicy {
         url.port ?? (scheme == "https" ? 443 : 80)
     }
 }
+
+/// Audit NET-109: which URLs may receive the headers a host handed over. Being allowed to fetch a
+/// URL (a playlist named it, a redirect landed there) and being granted the host's credentials are
+/// separate decisions: only the URLs the host itself passed in are anchors, and every other target
+/// gets the same headers minus the credentials, the rule a redirect follows. One type so the relay,
+/// the subtitle proxy, the audio tap and the live rendition fetch cannot each decide differently.
+struct CredentialScope: Sendable {
+    let headers: [String: String]
+    let anchors: [URL]
+
+    init(headers: [String: String], anchors: [URL]) {
+        self.headers = headers
+        self.anchors = anchors
+    }
+
+    init(headers: [String: String], anchor: URL?) {
+        self.init(headers: headers, anchors: anchor.map { [$0] } ?? [])
+    }
+
+    func headers(for target: URL) -> [String: String] {
+        if anchors.contains(where: { RedirectHeaderPolicy.credentialsAllowed(from: $0, to: target) }) {
+            return headers
+        }
+        return RedirectHeaderPolicy.scoped(headers, grantedFor: nil, sentTo: target)
+    }
+}
diff --git a/Sources/AetherEngine/IO/HLSIngest/HLSLiveIngestReader.swift b/Sources/AetherEngine/IO/HLSIngest/HLSLiveIngestReader.swift
index 783269ee7..b53965065 100644
--- a/Sources/AetherEngine/IO/HLSIngest/HLSLiveIngestReader.swift
+++ b/Sources/AetherEngine/IO/HLSIngest/HLSLiveIngestReader.swift
@@ -20,7 +20,7 @@ public final class HLSLiveIngestReader: IOReader, LiveIngestSourceInfo, @uncheck
     private let httpHeaders: [String: String]
     /// The URL the host gave `httpHeaders` for. A companion inherits its parent's, since its own
     /// playlist URL is one the master named (audit NET-7).
-    private let credentialOrigin: URL
+    let credentialOrigin: URL
     private let role: Role
     private let fifo = ByteFIFO(capacity: 16 * 1024 * 1024)
     /// Wider than the VOD reader's 2 MB: a live window with hours of DVR at short segments is a
diff --git a/Sources/AetherEngine/IO/HLSIngest/LiveIngestSourceInfo.swift b/Sources/AetherEngine/IO/HLSIngest/LiveIngestSourceInfo.swift
index c6118d234..9bc7fe827 100644
--- a/Sources/AetherEngine/IO/HLSIngest/LiveIngestSourceInfo.swift
+++ b/Sources/AetherEngine/IO/HLSIngest/LiveIngestSourceInfo.swift
@@ -46,6 +46,10 @@ protocol LiveIngestSourceInfo: AnyObject, Sendable {
     /// flows, like `companionAudioReader`, so it is final once the load reads it.
     var subtitleRenditions: [LiveSubtitleRenditionInfo] { get }
 
+    /// The URL the host gave the reader's headers for. A sibling rendition fetch sends the credential
+    /// headers only to this origin, like the reader's own fetches (audit Vcred-101).
+    var credentialOrigin: URL { get }
+
     /// EXT-X-PROGRAM-DATE-TIME of the segment this reader joined at, nil when the upstream carries no
     /// PDT. Together with the engine's clock at session start this is the wall-to-player mapping a
     /// sibling rendition needs (AE#359).
diff --git a/Sources/AetherEngine/Native/RemoteHLSSubtitleProxy.swift b/Sources/AetherEngine/Native/RemoteHLSSubtitleProxy.swift
index b369f27d7..58a8ace8a 100644
--- a/Sources/AetherEngine/Native/RemoteHLSSubtitleProxy.swift
+++ b/Sources/AetherEngine/Native/RemoteHLSSubtitleProxy.swift
@@ -82,7 +82,7 @@ enum RemoteHLSSubtitleProxy {
     /// pointed at the relay's own address for the origin.
     private static func relayOnly(originURL: URL, httpHeaders: [String: String]) -> Prepared? {
         let relay = HLSOriginRelay()
-        relay.admit(originURL, httpHeaders: httpHeaders)
+        relay.grantCredentials(to: originURL, httpHeaders: httpHeaders)
         let server = HLSLocalServer(relay: relay)
         do {
             try server.start()
@@ -123,11 +123,14 @@ enum RemoteHLSSubtitleProxy {
                               needsRelay: Bool) async throws -> Prepared {
         let session = makeSession()
         defer { session.finishTasksAndInvalidate() }
+        // Audit NAT-105: the variant is whatever the master names, on any host or scheme, so the
+        // host's credentials go only where the host sent them.
+        let credentials = CredentialScope(headers: httpHeaders, anchor: originURL)
 
         let (body, finalURL) = try await fetchPlaylist(originURL, session: session, headers: httpHeaders)
         let parsed = try parse(body, at: finalURL)
         let duration = try await programDuration(of: parsed, at: finalURL,
-                                                 session: session, headers: httpHeaders)
+                                                 session: session, credentials: credentials)
 
         let rewritten = try RemoteHLSMasterRewrite.rewriteDeclaringNames(
             originPlaylist: body,
@@ -139,7 +142,11 @@ enum RemoteHLSSubtitleProxy {
                                                  programDuration: duration,
                                                  defaultHeaders: httpHeaders)
         let relay: HLSOriginRelay? = needsRelay ? HLSOriginRelay() : nil
-        relay?.admit(finalURL, httpHeaders: httpHeaders)
+        // Audit NET-109: the grant belongs to the URL the host handed over. A redirect target is
+        // only allowed, or a cross-host redirect would move the token to the edge and leave the
+        // host's own origin without it.
+        relay?.grantCredentials(to: originURL, httpHeaders: httpHeaders)
+        relay?.allow(finalURL)
         let server = HLSLocalServer(provider: provider, relay: relay)
         do {
             try server.start()
@@ -222,7 +229,7 @@ enum RemoteHLSSubtitleProxy {
     private static func programDuration(of playlist: HLSPlaylist,
                                         at url: URL,
                                         session: URLSession,
-                                        headers: [String: String]) async throws -> Double {
+                                        credentials: CredentialScope) async throws -> Double {
         switch playlist {
         case .media(let media):
             guard media.hasEndList else { throw Refusal.notVOD }
@@ -232,7 +239,8 @@ enum RemoteHLSSubtitleProxy {
                   let variantURL = HLSPlaylistParser.resolve(uri: variant.uri, against: url) else {
                 throw Refusal.unusablePlaylist("master declares no resolvable variant")
             }
-            let (body, finalURL) = try await fetchPlaylist(variantURL, session: session, headers: headers)
+            let (body, finalURL) = try await fetchPlaylist(
+                variantURL, session: session, headers: credentials.headers(for: variantURL))
             guard case .media(let media) = try parse(body, at: finalURL) else {
                 throw Refusal.unusablePlaylist("variant is not a media playlist")
             }
diff --git a/Sources/AetherEngine/Network/HLSLocalServer.swift b/Sources/AetherEngine/Network/HLSLocalServer.swift
index 1cab21b78..4dbd48806 100644
--- a/Sources/AetherEngine/Network/HLSLocalServer.swift
+++ b/Sources/AetherEngine/Network/HLSLocalServer.swift
@@ -453,11 +453,12 @@ final class HLSLocalServer: @unchecked Sendable {
 
     private let unauthenticatedHeadDeadline: TimeInterval
 
-    /// Admits `origin` to the relay and returns the address standing in for it, for a player
-    /// pointed at the relay rather than at a provider's playlists. Nil before `start()` or with
-    /// no relay mounted.
+    /// Allows `origin` on the relay and returns the address standing in for it, for a player
+    /// pointed at the relay rather than at a provider's playlists. Grants no credentials: that is
+    /// the caller's decision, for a URL the host handed over (audit NET-109). Nil before `start()`
+    /// or with no relay mounted.
     func relayURL(for origin: URL) -> URL? {
-        guard let relay, relay.admit(origin) != nil else { return nil }
+        guard let relay, relay.allow(origin) != nil else { return nil }
         stateLock.lock()
         let listeningPort = port
         stateLock.unlock()
diff --git a/Sources/AetherEngine/Network/HLSOriginRelay.swift b/Sources/AetherEngine/Network/HLSOriginRelay.swift
index 5d7cdd808..88affd755 100644
--- a/Sources/AetherEngine/Network/HLSOriginRelay.swift
+++ b/Sources/AetherEngine/Network/HLSOriginRelay.swift
@@ -43,20 +43,19 @@ final class HLSOriginRelay: @unchecked Sendable {
 
     private let stateLock = NSLock()
 
-    /// Origins this relay will fetch, as scheme://host:port. Seeded by `admit(_:)` and grown
-    /// as playlists reveal where their own sub-resources live, so a stream split across hosts
-    /// keeps working while a request naming somewhere nobody advertised is still refused.
+    /// Origins this relay will fetch, as scheme://host:port. Seeded by `allow(_:)` and
+    /// `grantCredentials(to:httpHeaders:)` and grown as playlists reveal where their own
+    /// sub-resources live, so a stream split across hosts keeps working while a request naming
+    /// somewhere nobody advertised is still refused.
     private var allowedOrigins = Set<String>()
 
-    /// Sent upstream on every fetch. Origins that gate on Referer, User-Agent or
-    /// Authorization need these, and they can no longer ride on the asset because the asset
-    /// now points at the local server.
-    private var upstreamHeaders: [String: String] = [:]
-
-    /// The URLs the host itself pointed the relay at. Credential headers follow a fetch only to
-    /// one of these origins with no TLS downgrade; an origin a playlist revealed gets the rest of
-    /// the headers but not the token (audit NET-7).
-    private var credentialOrigins: [URL] = []
+    /// Sent upstream on every fetch. Origins that gate on Referer, User-Agent or Authorization need
+    /// these, and they can no longer ride on the asset because the asset now points at the local
+    /// server. The anchors are the URLs the host itself pointed the relay at: credential headers
+    /// follow a fetch only to one of those origins with no TLS downgrade, and an origin a playlist
+    /// revealed or a redirect landed on gets the rest of the headers but not the token (audit NET-7,
+    /// NET-109).
+    private var credentials = CredentialScope(headers: [:], anchors: [])
 
     /// The NSURLError code of the last upstream handshake this relay lost to system trust, if any.
     ///
@@ -144,19 +143,45 @@ final class HLSOriginRelay: @unchecked Sendable {
 
     // MARK: - Admission
 
-    /// Lets this relay fetch `origin`, and adopts the headers a load carries. Returns the
+    /// Lets this relay fetch `origin` without granting it the host's credentials. Returns the
     /// origin key, or nil for a URL with no host to fetch from.
     @discardableResult
-    func admit(_ origin: URL, httpHeaders: [String: String] = [:]) -> String? {
+    func allow(_ origin: URL) -> String? {
+        guard let key = Self.originKey(for: origin) else { return nil }
+        stateLock.lock()
+        allowedOrigins.insert(key)
+        stateLock.unlock()
+        return key
+    }
+
+    /// Lets this relay fetch `origin` AND send it the credential headers, and adopts the headers a
+    /// load carries. Only for a URL the host itself handed over (audit NET-109): anything a
+    /// playlist or a redirect produced goes through `allow(_:)`.
+    @discardableResult
+    func grantCredentials(to origin: URL, httpHeaders: [String: String] = [:]) -> String? {
         guard let key = Self.originKey(for: origin) else { return nil }
         stateLock.lock()
         allowedOrigins.insert(key)
-        if !httpHeaders.isEmpty { upstreamHeaders = httpHeaders }
-        if !credentialOrigins.contains(origin) { credentialOrigins.append(origin) }
+        let anchors = credentials.anchors.contains(origin)
+            ? credentials.anchors : credentials.anchors + [origin]
+        credentials = CredentialScope(
+            headers: httpHeaders.isEmpty ? credentials.headers : httpHeaders, anchors: anchors)
         stateLock.unlock()
         return key
     }
 
+    /// The URLs whose origins receive the host's credentials.
+    var credentialAnchors: [URL] {
+        stateLock.lock(); defer { stateLock.unlock() }
+        return credentials.anchors
+    }
+
+    /// The headers a relayed fetch of `target` carries upstream.
+    func upstreamHeaders(for target: URL) -> [String: String] {
+        stateLock.lock(); defer { stateLock.unlock() }
+        return credentials.headers(for: target)
+    }
+
     /// scheme://host:port for `url`, which is the granularity the allow list works at.
     static func originKey(for url: URL) -> String? {
         guard let scheme = url.scheme?.lowercased(), let host = url.host?.lowercased() else {
@@ -289,7 +314,7 @@ final class HLSOriginRelay: @unchecked Sendable {
 
         stateLock.lock()
         let permitted = allowedOrigins.contains(key)
-        let headers = Self.headers(upstreamHeaders, for: origin, grantedFor: credentialOrigins)
+        let headers = credentials.headers(for: origin)
         stateLock.unlock()
         guard permitted else {
             EngineLog.emit(
@@ -332,17 +357,6 @@ final class HLSOriginRelay: @unchecked Sendable {
         }
     }
 
-    /// Everything the host sent, with the credentials only when `target` is one of the host's own
-    /// origins (same host, same port, no downgrade).
-    static func headers(_ headers: [String: String], for target: URL, grantedFor anchors: [URL])
-        -> [String: String]
-    {
-        if anchors.contains(where: { RedirectHeaderPolicy.credentialsAllowed(from: $0, to: target) }) {
-            return headers
-        }
-        return RedirectHeaderPolicy.scoped(headers, grantedFor: nil, sentTo: target)
-    }
-
     private static func looksLikePlaylist(url: URL, contentType: String?) -> Bool {
         if let type = contentType?.lowercased(), type.contains("mpegurl") || type.contains("m3u") {
             return true
diff --git a/Tests/AetherEngineTests/HLSOriginRelayTests.swift b/Tests/AetherEngineTests/HLSOriginRelayTests.swift
index 91f0f76e0..0f5816147 100644
--- a/Tests/AetherEngineTests/HLSOriginRelayTests.swift
+++ b/Tests/AetherEngineTests/HLSOriginRelayTests.swift
@@ -104,7 +104,7 @@ struct HLSOriginRelayAddressingTests {
     func rewritesMediaPlaylist() throws {
         let relay = HLSOriginRelay()
         let origin = URL(string: "https://media.example.com/hls/media.m3u8?ApiKey=k")!
-        relay.admit(origin)
+        relay.grantCredentials(to: origin)
 
         let playlist = """
             #EXTM3U
@@ -152,7 +152,7 @@ struct HLSOriginRelayAddressingTests {
         // engine has.
         let relay = HLSOriginRelay()
         let origin = URL(string: "https://media.example.com/hls/master.m3u8")!
-        relay.admit(origin)
+        relay.grantCredentials(to: origin)
 
         let master = """
             #EXTM3U
@@ -180,7 +180,7 @@ struct HLSOriginRelayAddressingTests {
         // fetch to time out. Nothing here waits on a name resolving, and the three
         // differ only by port, which the allow list treats as part of the origin.
         let origin = URL(string: "https://127.0.0.1:9/hls/media.m3u8")!
-        relay.admit(origin)
+        relay.grantCredentials(to: origin)
 
         _ = relay.rewritePlaylist(
             "#EXTM3U\n#EXTINF:6.0,\nhttps://127.0.0.1:10/seg1.ts\n", relativeTo: origin,
@@ -202,7 +202,7 @@ struct HLSOriginRelayAddressingTests {
         try server.start()
         defer { server.stop(); relay.stop() }
         let origin = URL(string: "https://127.0.0.1:9/hls/media.m3u8")!
-        relay.admit(origin)
+        relay.grantCredentials(to: origin)
 
         let stranger = try #require(relay.localURL(
             for: origin, port: server.port, token: String(repeating: "cd", count: 16)))
diff --git a/Tests/AetherEngineTests/Issue119RemoteHLSHeaderTests.swift b/Tests/AetherEngineTests/Issue119RemoteHLSHeaderTests.swift
index 495fe015a..d9daaa9ec 100644
--- a/Tests/AetherEngineTests/Issue119RemoteHLSHeaderTests.swift
+++ b/Tests/AetherEngineTests/Issue119RemoteHLSHeaderTests.swift
@@ -37,7 +37,8 @@ struct Issue119RemoteHLSHeaderTests {
         let cfg = URLSessionConfiguration.ephemeral
         cfg.protocolClasses = [HeaderCaptureURLProtocol.self]
         return AudioTapHLSFetcher(session: URLSession(configuration: cfg),
-                                  httpHeaders: httpHeaders)
+                                  httpHeaders: httpHeaders,
+                                  credentialOrigin: URL(string: "https://origin.test/live/channel.m3u8"))
     }
 
     @Test("fetchPlaylist sends the configured headers")
diff --git a/Tests/AetherEngineTests/PlaylistNamedHostCredentialTests.swift b/Tests/AetherEngineTests/PlaylistNamedHostCredentialTests.swift
index 9950e7c63..836524151 100644
--- a/Tests/AetherEngineTests/PlaylistNamedHostCredentialTests.swift
+++ b/Tests/AetherEngineTests/PlaylistNamedHostCredentialTests.swift
@@ -55,17 +55,73 @@ struct PlaylistNamedHostCredentialTests {
 
     @Test("The relay sends credentials to the host's origins only, not to one a playlist revealed")
     func relayHeaders() throws {
-        let anchors = [origin]
-        let own = HLSOriginRelay.headers(
-            headers, for: try #require(URL(string: "https://media.example/hls/seg.ts")), grantedFor: anchors)
+        let scope = CredentialScope(headers: headers, anchors: [origin])
+        let own = scope.headers(for: try #require(URL(string: "https://media.example/hls/seg.ts")))
         #expect(own == headers)
-        let discovered = HLSOriginRelay.headers(
-            headers, for: try #require(URL(string: "http://cdn.other/seg.ts")), grantedFor: anchors)
+        let discovered = scope.headers(for: try #require(URL(string: "http://cdn.other/seg.ts")))
         for name in credentialNames { #expect(discovered[name] == nil, "\(name) reached a discovered origin") }
         #expect(discovered["Referer"] == "https://portal.example/")
         #expect(discovered["User-Agent"] == "UA/1")
     }
 
+    /// Audit NET-109: allowing a fetch and granting the token were one call, so anything the relay
+    /// was told it may fetch also received the credentials.
+    @Test("An origin the relay is only allowed to fetch gets no credentials")
+    func relayAllowIsNotGrant() throws {
+        let relay = HLSOriginRelay()
+        defer { relay.stop() }
+        let edge = try #require(URL(string: "https://edge.cdn/v.m3u8"))
+        relay.grantCredentials(to: origin, httpHeaders: headers)
+        relay.allow(edge)
+
+        #expect(relay.credentialAnchors == [origin])
+        let onEdge = relay.upstreamHeaders(for: try #require(URL(string: "https://edge.cdn/seg.ts")))
+        for name in credentialNames { #expect(onEdge[name] == nil, "\(name) reached an allowed origin") }
+        #expect(onEdge["Referer"] == "https://portal.example/")
+        let onOrigin = relay.upstreamHeaders(for: try #require(URL(string: "https://media.example/seg.ts")))
+        #expect(onOrigin == headers)
+    }
+
+    @Test("Asking the server for a relay address grants nothing")
+    func relayURLOnlyAllows() throws {
+        let relay = HLSOriginRelay()
+        let server = HLSLocalServer(relay: relay)
+        try server.start()
+        defer { server.stop(); relay.stop() }
+        relay.grantCredentials(to: origin, httpHeaders: headers)
+        let other = try #require(URL(string: "https://cdn.other/v/index.m3u8"))
+
+        _ = try #require(server.relayURL(for: other))
+
+        #expect(relay.credentialAnchors == [origin])
+        let onOther = relay.upstreamHeaders(for: other)
+        for name in credentialNames { #expect(onOther[name] == nil, "\(name) reached \(other)") }
+    }
+
+    /// Audit Vcred-101: the live rendition fetch set every host header on the rendition playlist and
+    /// every WebVTT segment the master named.
+    @Test("The live subtitle rendition fetch judges by the ingest's origin", arguments: [
+        ("https://media.example/subs/en.m3u8", true),
+        ("https://subs.other/en.m3u8", false),
+        ("http://media.example/subs/en.m3u8", false),
+    ])
+    func liveSubtitleRendition(target: String, keepsCredentials: Bool) throws {
+        let reader = HLSLiveIngestReader(playlistURL: origin, httpHeaders: headers)
+        let scope = AetherEngine.liveSubtitleRenditionCredentials(headers: headers, source: reader)
+        let sent = scope.headers(for: try #require(URL(string: target)))
+        for name in credentialNames {
+            #expect((sent[name] != nil) == keepsCredentials, "\(name) on \(target)")
+        }
+        #expect(sent["Referer"] == "https://portal.example/")
+    }
+
+    @Test("Without a live ingest reader the rendition fetch carries no credentials at all")
+    func liveSubtitleRenditionWithoutAnIngest() throws {
+        let scope = AetherEngine.liveSubtitleRenditionCredentials(headers: headers, source: nil)
+        let sent = scope.headers(for: origin)
+        for name in credentialNames { #expect(sent[name] == nil, "\(name) went out with no anchor") }
+    }
+
     @Test("The carriage probe does not carry the token to a variant on another host")
     func carriageProbeVariant() async throws {
         CredentialCaptureProtocol.reset()
@@ -99,6 +155,83 @@ struct PlaylistNamedHostCredentialTests {
         #expect(onVariant["Referer"] == "https://portal.example/")
     }
 
+    /// Audit NAT-105 / NET-109: the #316 build fetched the master's first variant with every host
+    /// header, whatever host the master named, and anchored the relay's grant on the redirect target.
+    @Test("The subtitle proxy keeps the token off an edge the master redirected to",
+          .timeLimit(.minutes(2)))
+    func subtitleProxyAfterACrossOriginRedirect() async throws {
+        let originMaybe = CannedHTTPOrigin()
+        let edgeMaybe = CannedHTTPOrigin()
+        let originServer = try #require(originMaybe)
+        let edge = try #require(edgeMaybe)
+        defer { originServer.stop(); edge.stop() }
+        originServer.route("/master.m3u8", .redirect(to: "\(edge.baseURL)/master.m3u8"))
+        edge.route("/master.m3u8", .body("""
+            #EXTM3U
+            #EXT-X-STREAM-INF:BANDWIDTH=1000000
+            v/index.m3u8
+            """, contentType: "application/vnd.apple.mpegurl"))
+        edge.route("/v/index.m3u8", .body("""
+            #EXTM3U
+            #EXT-X-TARGETDURATION:6
+            #EXTINF:6.0,
+            seg0.ts
+            #EXT-X-ENDLIST
+            """, contentType: "application/vnd.apple.mpegurl"))
+        let originURL = try #require(URL(string: "\(originServer.baseURL)/master.m3u8"))
+        let sidecar = try #require(URL(string: "\(originServer.baseURL)/en.vtt"))
+
+        let prepared = try #require(await RemoteHLSSubtitleProxy.prepare(
+            originURL: originURL,
+            tracks: [.init(externalID: 100_000, source: ExternalSubtitleTrack(url: sidecar, language: "en"))],
+            httpHeaders: headers, needsRelay: true))
+        defer { prepared.tearDown() }
+        #expect(prepared.servesSubtitleRenditions)
+        let relay = try #require(prepared.server.relay)
+        #expect(relay.credentialAnchors == [originURL], "the grant moved to the redirect target")
+        let backHome = try #require(URL(string: "\(originServer.baseURL)/seg0.ts"))
+        #expect(relay.upstreamHeaders(for: backHome)["X-Emby-Token"] == "t0k3n",
+                "a relayed request to the host's own origin lost its token")
+        let atEdge = try #require(URL(string: "\(edge.baseURL)/v/seg0.ts"))
+        #expect(relay.upstreamHeaders(for: atEdge)["X-Emby-Token"] == nil)
+
+        let onOrigin = try #require(originServer.requests(to: "/master.m3u8").first)
+        #expect(onOrigin.headers["x-emby-token"] == "t0k3n")
+        for path in ["/master.m3u8", "/v/index.m3u8"] {
+            let seen = try #require(edge.requests(to: path).first, "\(path) was never fetched")
+            for name in credentialNames {
+                #expect(seen.headers[name.lowercased()] == nil, "\(name) reached the edge on \(path)")
+            }
+            #expect(seen.headers["referer"] == "https://portal.example/")
+        }
+    }
+
+    /// Audit DEC-103: the remote-HLS audio tap put every host header on every playlist, segment and
+    /// key a playlist named.
+    @Test("The audio tap keeps the token on the loaded origin", arguments: [
+        ("https://media.example/live/seg1.ts", true),
+        ("https://cdn.other/seg1.ts", false),
+        ("http://media.example/live/seg1.ts", false),
+    ])
+    func audioTapSegment(target: String, keepsCredentials: Bool) async throws {
+        CredentialCaptureProtocol.reset()
+        CredentialCaptureProtocol.bodies[target] = Data([0x47, 0x40, 0x11, 0x10])
+        let configuration = URLSessionConfiguration.ephemeral
+        configuration.protocolClasses = [CredentialCaptureProtocol.self]
+        let session = URLSession(configuration: configuration)
+        defer { session.invalidateAndCancel() }
+        let fetcher = AudioTapHLSFetcher(session: session, httpHeaders: headers, credentialOrigin: origin)
+        let url = try #require(URL(string: target))
+
+        _ = try await fetcher.fetchSegment(url, crypt: nil, base: origin)
+
+        let seen = try #require(CredentialCaptureProtocol.seen[target])
+        for name in credentialNames {
+            #expect((seen[name] != nil) == keepsCredentials, "\(name) on \(target)")
+        }
+        #expect(seen["Referer"] == "https://portal.example/")
+    }
+
     private func expect(_ request: URLRequest, keepsCredentials: Bool,
                         sourceLocation: SourceLocation = #_sourceLocation) {
         for name in credentialNames {
diff --git a/Tests/AetherEngineTests/Support/CannedHTTPOrigin.swift b/Tests/AetherEngineTests/Support/CannedHTTPOrigin.swift
new file mode 100644
index 000000000..9df0920f7
--- /dev/null
+++ b/Tests/AetherEngineTests/Support/CannedHTTPOrigin.swift
@@ -0,0 +1,146 @@
+import Darwin
+import Foundation
+
+/// A loopback origin that answers each path from a table and records the headers every request
+/// arrived with (names lowercased), so a credential that must not reach a host is checked where it
+/// would have landed. One request per connection; the table can be filled after start, so two of
+/// these can point at each other.
+final class CannedHTTPOrigin: @unchecked Sendable {
+    enum Answer: Sendable {
+        case body(String, contentType: String)
+        case redirect(to: String)
+        case status(Int)
+    }
+
+    struct Request: Sendable {
+        let path: String
+        let headers: [String: String]
+    }
+
+    let port: UInt16
+    private let listenFD: Int32
+    private let lock = NSLock()
+    private var _routes: [String: Answer] = [:]
+    private var _requests: [Request] = []
+    private var _connections: Set<Int32> = []
+    private var _stopped = false
+
+    init?() {
+        let fd = socket(AF_INET, SOCK_STREAM, 0)
+        guard fd >= 0 else { return nil }
+        var one: Int32 = 1
+        setsockopt(fd, SOL_SOCKET, SO_REUSEADDR, &one, socklen_t(MemoryLayout<Int32>.size))
+        var address = sockaddr_in()
+        address.sin_family = sa_family_t(AF_INET)
+        address.sin_port = 0
+        address.sin_addr.s_addr = inet_addr("127.0.0.1")
+        let bound = withUnsafePointer(to: &address) {
+            $0.withMemoryRebound(to: sockaddr.self, capacity: 1) {
+                bind(fd, $0, socklen_t(MemoryLayout<sockaddr_in>.size))
+            }
+        }
+        guard bound == 0, listen(fd, 16) == 0 else {
+            close(fd)
+            return nil
+        }
+        var length = socklen_t(MemoryLayout<sockaddr_in>.size)
+        let named = withUnsafeMutablePointer(to: &address) {
+            $0.withMemoryRebound(to: sockaddr.self, capacity: 1) { getsockname(fd, $0, &length) }
+        }
+        guard named == 0 else {
+            close(fd)
+            return nil
+        }
+        listenFD = fd
+        port = UInt16(bigEndian: address.sin_port)
+        Thread.detachNewThread { [self] in acceptLoop() }
+    }
+
+    var baseURL: String { "http://127.0.0.1:\(port)" }
+
+    func route(_ path: String, _ answer: Answer) {
+        lock.withLock { _routes[path] = answer }
+    }
+
+    var requests: [Request] { lock.withLock { _requests } }
+
+    func requests(to path: String) -> [Request] { requests.filter { $0.path == path } }
+
+    func stop() {
+        lock.lock()
+        let alreadyStopped = _stopped
+        _stopped = true
+        for fd in _connections { shutdown(fd, SHUT_RDWR) }
+        lock.unlock()
+        guard !alreadyStopped else { return }
+        shutdown(listenFD, SHUT_RDWR)
+        close(listenFD)
+    }
+
+    private func acceptLoop() {
+        while true {
+            let fd = accept(listenFD, nil, nil)
+            if fd < 0 { return }
+            var one: Int32 = 1
+            setsockopt(fd, SOL_SOCKET, SO_NOSIGPIPE, &one, socklen_t(MemoryLayout<Int32>.size))
+            lock.lock()
+            if _stopped {
+                lock.unlock()
+                close(fd)
+                return
+            }
+            _connections.insert(fd)
+            lock.unlock()
+            Thread.detachNewThread { [self] in serve(fd) }
+        }
+    }
+
+    private func serve(_ fd: Int32) {
+        defer {
+            lock.lock()
+            _connections.remove(fd)
+            close(fd)
+            lock.unlock()
+        }
+        var buffer = Data()
+        var chunk = [UInt8](repeating: 0, count: 4096)
+        while buffer.range(of: Data("\r\n\r\n".utf8)) == nil {
+            let n = recv(fd, &chunk, chunk.count, 0)
+            guard n > 0, buffer.count < 65_536 else { return }
+            buffer.append(chunk, count: n)
+        }
+        let lines = String(decoding: buffer, as: UTF8.self).components(separatedBy: "\r\n")
+        let target = lines.first?.split(separator: " ").dropFirst().first.map(String.init) ?? "/"
+        let path = String(target.split(separator: "?", maxSplits: 1).first ?? "/")
+        var headers: [String: String] = [:]
+        for line in lines.dropFirst() {
+            guard let colon = line.firstIndex(of: ":") else { continue }
+            headers[line[..<colon].lowercased()] =
+                line[line.index(after: colon)...].trimmingCharacters(in: .whitespaces)
+        }
+        let answer = lock.withLock { () -> Answer? in
+            _requests.append(Request(path: path, headers: headers))
+            return _routes[path]
+        }
+        let response: String
+        switch answer {
+        case .body(let body, let contentType):
+            response = "HTTP/1.1 200 OK\r\nContent-Type: \(contentType)\r\n"
+                + "Content-Length: \(body.utf8.count)\r\nConnection: close\r\n\r\n\(body)"
+        case .redirect(let location):
+            response = "HTTP/1.1 302 Found\r\nLocation: \(location)\r\n"
+                + "Content-Length: 0\r\nConnection: close\r\n\r\n"
+        case .status(let code):
+            response = "HTTP/1.1 \(code) Status\r\nContent-Length: 0\r\nConnection: close\r\n\r\n"
+        case nil:
+            response = "HTTP/1.1 404 Not Found\r\nContent-Length: 0\r\nConnection: close\r\n\r\n"
+        }
+        let bytes = Array(response.utf8)
+        var sent = 0
+        while sent < bytes.count {
+            let n = bytes[sent...].withUnsafeBytes { send(fd, $0.baseAddress, $0.count, 0) }
+            guard n > 0 else { return }
+            sent += n
+        }
+    }
+}
diff --git a/docs/architecture.md b/docs/architecture.md
index c0c8b947d..a97e02700 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -358,7 +358,7 @@ Sources/AetherEngine/
 │   ├── ResidentSpan.swift                   Bytes already in memory that a read can be served from without a round trip: the open window parked across a parse seek, and the speculative tail fetch. Not a cache (no fetch-on-miss, no eviction, no block alignment); it either covers an offset or it does not (#281)
 │   ├── CustomIOReaderBridge.swift           Bridges a host-supplied IOReader into avio_alloc_context read / seek callbacks, with the same read deadline and reversible read abort as AVIOReader so bounded seeks also bound (and unwedge) disc-adapter sources
 │   ├── Demuxer.swift                        libavformat wrapper; seek + bounded seek (deadline-capped) + byte-estimate positioning fallback for index-less containers (origin-corrected onto the file-relative time axis, fixed early bias in seconds, landing verified by a packet-PTS probe with proportional correction, and a sticky per-demuxer timestamp-seek lockout once the mechanism proves broken, #112). Per-open `DemuxerOpenProfile` budgets `find_stream_info` (probesize / max_analyze_duration), caller-overridable on the main playback open via `LoadOptions.probesize` / `maxAnalyzeDuration`. The native text readers' side demuxer sets `skipStreamInfo` to drop the `find_stream_info` pass entirely (codec_id / codec_type come from the container header / PMT at open); the reader runs a bounded `resolveStreamInfo()` on demand only if its target stream's codec is genuinely unresolved at open (#87)
-│   ├── RedirectHeaderPolicy.swift           Per-header redirect replay policy for AVIOReader's URLSession delegates and, through `EngineTLS`'s session-level delegate, for every other engine session (audit NET-108): Range and non-credential extra headers survive cross-host redirects (header-dependent proxies, #8), credential headers (Authorization, Cookie, Emby/Jellyfin tokens) are replayed only to a same-host target with no TLS downgrade and scrubbed otherwise, so presigned redirect targets neither 400 on conflicting auth nor see the media-server token (#126)
+│   ├── RedirectHeaderPolicy.swift           Per-header redirect replay policy for AVIOReader's URLSession delegates and, through `EngineTLS`'s session-level delegate, for every other engine session (audit NET-108): Range and non-credential extra headers survive cross-host redirects (header-dependent proxies, #8), credential headers (Authorization, Cookie, Emby/Jellyfin tokens) are replayed only to a same-host target with no TLS downgrade and scrubbed otherwise, so presigned redirect targets neither 400 on conflicting auth nor see the media-server token (#126). `CredentialScope` applies the same rule to every URI a playlist names: the relay, the #316 subtitle proxy, the audio tap and the live rendition fetch send the credentials only to the URL the host handed over, and allowing a fetch never grants them (audit NET-109)
 │   ├── SlowReadDiagnostics.swift            One-shot localization of a pathologically slow AVIOReader.read() (detour fetch / connStall / reconnect / backoff / dropped-generation bytes), #93 restart latency
 │   ├── SourceThrottle.swift                 Pure virtual-clock leaky-bucket rate limiter on the source read path (slow-CDN simulation for aetherctl --throttle); unit-testable without sleeping
 │   └── SourceContentLengthCache.swift       Memoizes a source URL's resolved total byte length across demuxer opens, so a subtitle side demuxer opening the same origin later inherits the size the video producer already resolved (#112)

From 9af630b6e92f88d3e9d1fa08adbb24fbe8550c1f Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 06:16:34 +0200
Subject: [PATCH 151/359] fix(core): an audio or custom rebuild keeps the
 session's transport (audit LIF-102)

`reloadWithAudioOverride` ended in an unconditional `play()` and
`.playing`, so an audio-track pick on a paused session resumed it, and
on a custom source every `reloadAtCurrentPosition` (the audio-delay
nudge, a #460 correction, the AE#561 rebuild) did the same, including
a mount with `autoplay = false`. The transport is now resolved before
`.loading` (`sessionRebuildResumesPlaying`, or the value
`reloadAtCurrentPosition` passes, which is the mount flag after a
background teardown) and drives the stacking park, `play()` and the
final state; a rebuild that does not resume is settled `.paused` by the
host's readiness, like a paused mount (#124).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../AetherEngine/AetherEngine+Loading.swift   | 24 ++++--
 Sources/AetherEngine/AetherEngine.swift       |  4 +-
 .../Issue464ReloadPreservesSessionTests.swift | 76 +++++++++++++++++++
 docs/api.md                                   |  2 +-
 4 files changed, 96 insertions(+), 10 deletions(-)

diff --git a/Sources/AetherEngine/AetherEngine+Loading.swift b/Sources/AetherEngine/AetherEngine+Loading.swift
index 4d7c001f1..872e48825 100644
--- a/Sources/AetherEngine/AetherEngine+Loading.swift
+++ b/Sources/AetherEngine/AetherEngine+Loading.swift
@@ -2177,13 +2177,17 @@ extension AetherEngine {
     /// This path publishes its failure and used to return silently either way, so a caller could
     /// not tell a rebuilt session from a dead one; `reloadAtCurrentPosition(applying:)` is built on
     /// exactly that distinction. Callers that only drive UI keep discarding it.
+    ///
+    /// `resumePlaying` is the transport the rebuild comes back in; nil reads the session's own
+    /// (`sessionRebuildResumesPlaying`, AE#464 round 2), which is what an audio or title pick wants.
     @discardableResult
     func reloadWithAudioOverride(
         url: URL,
         audioStreamIndex: Int32?,
         expectedGeneration: UInt64,
         discTitleIDOverride: Int? = nil,
-        resumeOverride: Double? = nil
+        resumeOverride: Double? = nil,
+        resumePlaying: Bool? = nil
     ) async -> Error? {
         // Liveness guard: a stop()/load() between scheduling and here would resurrect a dismissed session or kill the successor. Generation captured at schedule time; both stop() and load() invalidate it.
         guard loadGeneration == expectedGeneration, loadedURL != nil else {
@@ -2256,13 +2260,16 @@ extension AetherEngine {
             category: .engine
         )
 
+        // Audit LIF-102: read before `.loading`, which is the state this rebuild is about to hide the
+        // session's transport behind. The audio pick never wrote it into `loadedOptions.autoplay`
+        // (that is the mount flag there), so the rebuild used to end in an unconditional `play()`.
+        let resumesPlaying = resumePlaying ?? sessionRebuildResumesPlaying
         state = .loading
         // AE#464 round 2: this branch reaches `loadSoftware` / `loadNative` rather than `load`, so it
         // parks its own rebuild position for anything that stacks behind it. Round 3 parks the
-        // transport beside it; this branch reads `loadedOptions` field by field, and the caller has
-        // already written the session's own transport into it.
+        // transport beside it.
         positionUnderReconstruction = resumeAt
-        transportIntentUnderReconstruction = loadedOptions.autoplay
+        transportIntentUnderReconstruction = resumesPlaying
         let previousAudioIndex = activeAudioTrackIndex
         // Snapshot before stopInternal wipes state. Must reload on the same backend: loadNative on a SW-routed AV1 source throws unsupportedCodec (HLSVideoEngine only accepts HEVC / H.264 / VP9 / probed-AV1).
         let wasOnSoftwarePath = (playbackBackend == .software)
@@ -2419,7 +2426,8 @@ extension AetherEngine {
                     audioTracks: audioTracks, activeIndex: softwareHost?.audioStreamIndex ?? -1
                 )
                 presentCurrentLayer()
-                softwareHost?.play()
+                // #124: not resuming leaves the host paused; its readiness settles `.loading -> .paused`.
+                if resumesPlaying { softwareHost?.play() }
             } else {
                 EngineLog.emit("[AetherEngine] reload: loadNative enter audio=\(audioStreamIndex.map(String.init) ?? "nil") resumeAt=\(String(format: "%.2f", resumeAt))s", category: .engine)
                 // #339: the only write this reload can still produce is a sole-writer host's re-write on the
@@ -2507,10 +2515,10 @@ extension AetherEngine {
                     ),
                     settleCap: loadedOptions.isLive ? .standard : .awaitObservedEnd)
                 try checkLoadCurrent(gen)
-                nativeHost?.play()
+                if resumesPlaying { nativeHost?.play() }
             }
             try checkLoadCurrent(gen)
-            state = .playing
+            if resumesPlaying { state = .playing }
             // Re-arm samplers: stopInternal nilled them, and the reload path bypasses public load() that normally restarts them. Without this, liveTelemetry stays nil and the stats overlay shows "-" after every audio switch.
             startMemoryProbe()
             startLiveTelemetrySampler()
@@ -2522,7 +2530,7 @@ extension AetherEngine {
             if loadedOptions.isLive, !targetSoftwarePath {
                 armLiveReloadWatchdog(generation: gen)
             }
-            EngineLog.emit("[AetherEngine] reload: state=.playing total=\(elapsedMs(since: reloadStart))ms", category: .engine)
+            EngineLog.emit("[AetherEngine] reload: state=\(resumesPlaying ? ".playing" : "paused on readiness") total=\(elapsedMs(since: reloadStart))ms", category: .engine)
         } catch is CancellationError {
             // Superseded by a newer load/stop: it owns the engine state.
             return nil
diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index db53863a3..5d08801d6 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -5178,11 +5178,13 @@ public final class AetherEngine: ObservableObject {
                 )
                 throw AetherEngineError.sessionNotReloadable(refusal)
             }
+            // Audit LIF-102: the value written above, or the mount flag after a background teardown.
             let failure = await reloadWithAudioOverride(
                 url: placeholderURL,
                 audioStreamIndex: selection.audioTrackIndex.map { Int32($0) },
                 expectedGeneration: loadGeneration,
-                discTitleIDOverride: selection.discTitleID
+                discTitleIDOverride: selection.discTitleID,
+                resumePlaying: loadedOptions.autoplay
             )
             // AE#460 follow-up: a rebuild that died leaves the session in `.error`, and this branch
             // used to return as if it had come back, so `reloadAtCurrentPosition(applying:)`
diff --git a/Tests/AetherEngineTests/Issue464ReloadPreservesSessionTests.swift b/Tests/AetherEngineTests/Issue464ReloadPreservesSessionTests.swift
index 90b0297d6..b4fce693e 100644
--- a/Tests/AetherEngineTests/Issue464ReloadPreservesSessionTests.swift
+++ b/Tests/AetherEngineTests/Issue464ReloadPreservesSessionTests.swift
@@ -137,3 +137,79 @@ struct Issue464StackedRebuildTransportTests {
             state: .playing, nativeTransportIntent: nil, underReconstruction: false))
     }
 }
+
+/// Audit LIF-102: `reloadWithAudioOverride` is the rebuild behind every audio-track pick, the custom
+/// disc-title pick and `reloadAtCurrentPosition` on a custom source, and it ended in an unconditional
+/// `play()`. The pure answer above was right and the call site ignored it: pause, pick another
+/// language, and the film started behind the menu.
+@Suite("Audit LIF-102: the audio-switch and custom-source rebuild comes back in the session's transport",
+       .timeLimit(.minutes(2)))
+@MainActor
+struct Issue464RebuildCallSiteTransportTests {
+
+    private static func customSource() throws -> MediaSource {
+        .custom(DataIOReader(data: try ProbeTestFixtures.hdr10Plus()), formatHint: "mp4")
+    }
+
+    @Test("an audio-track rebuild of a paused session leaves it paused")
+    func audioSwitchKeepsAPausedSessionPaused() async throws {
+        let engine = try AetherEngine()
+        defer { engine.stop() }
+        _ = try await engine.load(source: Self.customSource())
+        engine.pause()
+        #expect(engine.state == .paused)
+        let url = try #require(engine.loadedURL)
+
+        let failure = await engine.reloadWithAudioOverride(
+            url: url, audioStreamIndex: nil, expectedGeneration: engine.loadGeneration)
+
+        #expect(failure == nil)
+        #expect(engine.state != .playing)
+        #expect(engine.nativeHost?.transportIntentIsPlaying == false)
+        try await waitFor { engine.state == .paused }
+    }
+
+    @Test("a rebuild stacked behind that audio switch reads the paused transport, not the mount flag")
+    func stackedRebuildReadsThePausedTransport() async throws {
+        let engine = try AetherEngine()
+        defer { engine.stop() }
+        _ = try await engine.load(source: Self.customSource())
+        engine.pause()
+        let url = try #require(engine.loadedURL)
+
+        let rebuild = Task { @MainActor in
+            await engine.reloadWithAudioOverride(
+                url: url, audioStreamIndex: nil, expectedGeneration: engine.loadGeneration)
+        }
+        try await waitFor { engine.state == .loading }
+        #expect(!engine.sessionRebuildResumesPlaying)
+        _ = await rebuild.value
+    }
+
+    @Test("a mount with autoplay off stays paused across a custom-source reload")
+    func pausedMountStaysPausedAcrossACustomReload() async throws {
+        let engine = try AetherEngine()
+        defer { engine.stop() }
+        _ = try await engine.load(source: Self.customSource(), options: LoadOptions(autoplay: false))
+        try await waitFor { engine.state == .paused }
+
+        try await engine.reloadAtCurrentPosition()
+
+        #expect(engine.state != .playing)
+        #expect(engine.nativeHost?.transportIntentIsPlaying == false)
+        try await waitFor { engine.state == .paused }
+    }
+
+    @Test("a playing session still comes back playing")
+    func playingSessionComesBackPlaying() async throws {
+        let engine = try AetherEngine()
+        defer { engine.stop() }
+        _ = try await engine.load(source: Self.customSource())
+        #expect(engine.state == .playing)
+
+        try await engine.reloadAtCurrentPosition()
+
+        #expect(engine.state == .playing)
+        #expect(engine.nativeHost?.transportIntentIsPlaying == true)
+    }
+}
diff --git a/docs/api.md b/docs/api.md
index 78714e884..324cece56 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -634,7 +634,7 @@ suppressing `AVPlayerItemLegibleOutput` to keep the measurement running.
 | --- | --- |
 | `$audioTracks` | `[TrackInfo]`. Republished when `LoadOptions.confirmAtmos` confirms a track. On `.remoteBypass` it lists the audio tracks AVPlayer built for the item (normally just the one playing), read from their format descriptions: `codec` in libavcodec's spelling (`eac3`, `ac3`, `aac`), `channels`, `sampleRate`, `profile` (AAC's object type; "Dolby Digital Plus + Dolby Atmos" with `isAtmos` when the E-AC-3 dec3 record announces JOC) and `language` from the track or the selected audible option. The ids are synthetic (from 400000 up) because there is no stream index on that route; compare them only with `activeAudioTrackIndex`. |
 | `$activeAudioTrackIndex` | The selected track's id. On `.remoteBypass`, the enabled item track's. |
-| `selectAudioTrack(index:)` | Session-preserving reload, roughly 0.5 to 1 s of black. `index` is `TrackInfo.id`. A no-op when out of range, already active, or on a forward-only custom source (live ingest included), which cannot rebuild its pipeline: there a track change is a fresh `load` naming the stream. Every refusal is logged, so a picker that does nothing is explainable. Also a no-op on `.remoteBypass`, where AVPlayer owns the audio selection and the list above is informational; a different language there is a different URL. |
+| `selectAudioTrack(index:)` | Session-preserving reload, roughly 0.5 to 1 s of black. It comes back in the session's transport like `reloadAtCurrentPosition()`: a paused session stays paused. `index` is `TrackInfo.id`. A no-op when out of range, already active, or on a forward-only custom source (live ingest included), which cannot rebuild its pipeline: there a track change is a fresh `load` naming the stream. Every refusal is logged, so a picker that does nothing is explainable. Also a no-op on `.remoteBypass`, where AVPlayer owns the audio selection and the list above is informational; a different language there is a different URL. |
 | `installAudioTap()`, `removeAudioTap()`, `audioTapHasDeliverySource`, `AetherEngine.audioTapFormat` | Opt-in decoded PCM, mono Float32 48 kHz with source-PTS stamps, off the render path. See the contract above. |
 
 ## Subtitles

From bd0600a79b230c46c94cdf2fe1c00fd2211abced Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 06:17:41 +0200
Subject: [PATCH 152/359] fix(live): wire replacement live producers into the
 playlist (audit HLS-101)

Only the session's first producer got onLiveSegmentFinalized and
liveResidentCapProvider (and the sequential twin), set in start() after
the provider was built. The live reopen, the in-place muxerFailed rebuild
and the AE#222 live rebuild all build through makeProducer, which wired
neither, so every in-engine live recovery cut segments the playlist never
listed: the media playlist froze at the dead producer's last segment
while "live reopen succeeded" was logged.

The wiring moves into wireProviderCallbacks. start() calls it once the
provider exists, and makeProducer calls it for every producer built while
a provider is installed, so no rebuild site can forget it. A live producer
started without its report now trips an assert.

Tests: a live session over an embedded 8 s MPEG-TS whose reader ends after
one pass keeps growing its playlist after the reopen, and a producer
rebuilt in place reports into the same provider.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../Video/HLSSegmentProducer.swift            |   2 +
 .../AetherEngine/Video/HLSVideoEngine.swift   |  43 +++--
 .../LiveRecoveryPlaylistGrowthTests.swift     |  92 +++++++++++
 .../TinyTransportStreamFixture.swift          | 152 ++++++++++++++++++
 4 files changed, 273 insertions(+), 16 deletions(-)
 create mode 100644 Tests/AetherEngineTests/LiveRecoveryPlaylistGrowthTests.swift
 create mode 100644 Tests/AetherEngineTests/TinyTransportStreamFixture.swift

diff --git a/Sources/AetherEngine/Video/HLSSegmentProducer.swift b/Sources/AetherEngine/Video/HLSSegmentProducer.swift
index 7eca8b7c4..e0f37d8a3 100644
--- a/Sources/AetherEngine/Video/HLSSegmentProducer.swift
+++ b/Sources/AetherEngine/Video/HLSSegmentProducer.swift
@@ -2617,6 +2617,8 @@ final class HLSSegmentProducer: @unchecked Sendable {
     // MARK: - Public API
 
     func start() {
+        assert(!isLive || onLiveSegmentFinalized != nil,
+               "a live producer started without its provider reports cuts segments no playlist lists (audit HLS-101)")
         stateLock.lock()
         guard !pumpStarted else { stateLock.unlock(); return }
         pumpStarted = true
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine.swift b/Sources/AetherEngine/Video/HLSVideoEngine.swift
index 96fae4225..fc014c519 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine.swift
@@ -1951,22 +1951,7 @@ public final class HLSVideoEngine: @unchecked Sendable {
         // AE#520 round 2: the close reads it on the playlist-build thread, so it is a closure over a
         // mirror rather than a read of the item.
         prov.consumerBufferedSecondsProvider = consumerBufferedSecondsProvider
-        if isLiveSession {
-            prod.onLiveSegmentFinalized = { [weak prov] index, durationSeconds, startPtsSeconds, discontinuous in
-                prov?.appendLiveSegment(index: index,
-                                        startSeconds: startPtsSeconds,
-                                        durationSeconds: durationSeconds,
-                                        discontinuous: discontinuous)
-            }
-            // AE#443: the runaway park has to sit above the window this session actually serves, or it
-            // bounds the window instead of backstopping it, and its enforcement (a sleeping read
-            // thread) stops the origin from being drained.
-            prod.liveResidentCapProvider = { [weak prov] in prov?.liveResidentParkCap() ?? 0 }
-        } else if sequentialOrigin {
-            prod.onSequentialSegmentFinalized = { [weak prov] index, durationSeconds in
-                prov?.appendSequentialSegmentDuration(index: index, durationSeconds: durationSeconds)
-            }
-        }
+        wireProviderCallbacks(prod, to: prov)
 
         EngineLog.emit(
             "[HLSVideoEngine] prepared: codec=\(manifestCodecs)"
@@ -2681,9 +2666,35 @@ public final class HLSVideoEngine: @unchecked Sendable {
             rebuildSubtitleTapRoutes()
         }
         armSubtitleTap(on: prod)
+        // Audit HLS-101: the first producer is built before the provider exists and `start()` wires
+        // it; every later one (live reopen, in-place rebuild, AE#222 rebuild) is wired here.
+        if let prov = provider {
+            wireProviderCallbacks(prod, to: prov)
+        }
         return prod
     }
 
+    /// The producer-to-provider reports the playlist is built from. A live producer without them
+    /// cuts segments the playlist never lists (audit HLS-101).
+    func wireProviderCallbacks(_ prod: HLSSegmentProducer, to prov: VideoSegmentProvider) {
+        if isLiveSession {
+            prod.onLiveSegmentFinalized = { [weak prov] index, durationSeconds, startPtsSeconds, discontinuous in
+                prov?.appendLiveSegment(index: index,
+                                        startSeconds: startPtsSeconds,
+                                        durationSeconds: durationSeconds,
+                                        discontinuous: discontinuous)
+            }
+            // AE#443: the runaway park has to sit above the window this session actually serves, or it
+            // bounds the window instead of backstopping it, and its enforcement (a sleeping read
+            // thread) stops the origin from being drained.
+            prod.liveResidentCapProvider = { [weak prov] in prov?.liveResidentParkCap() ?? 0 }
+        } else if sequentialOrigin {
+            prod.onSequentialSegmentFinalized = { [weak prov] index, durationSeconds in
+                prov?.appendSequentialSegmentDuration(index: index, durationSeconds: durationSeconds)
+            }
+        }
+    }
+
     // MARK: - Live source-loss recovery
 
     /// Max reopen attempts per lost-source event (AVIO absorbs transient drops internally;
diff --git a/Tests/AetherEngineTests/LiveRecoveryPlaylistGrowthTests.swift b/Tests/AetherEngineTests/LiveRecoveryPlaylistGrowthTests.swift
new file mode 100644
index 000000000..b912569aa
--- /dev/null
+++ b/Tests/AetherEngineTests/LiveRecoveryPlaylistGrowthTests.swift
@@ -0,0 +1,92 @@
+import Foundation
+import Testing
+@testable import AetherEngine
+
+/// Audit HLS-101: only the session's first live producer was wired to the provider, so a producer
+/// that replaced a dead one (live reopen, the in-place muxerFailed rebuild, the AE#222 live rebuild)
+/// cut segments into the cache that the playlist never listed. The playlist ended where the dead
+/// producer stopped, and "live reopen succeeded" was logged over a frozen picture.
+@Suite("A live playlist keeps growing after an in-engine recovery", .serialized)
+struct LiveRecoveryPlaylistGrowthTests {
+
+    private final class Observed: @unchecked Sendable {
+        private let lock = NSLock()
+        private weak var _engine: HLSVideoEngine?
+        private var _countAtFirstReopen: Int?
+        private var _sourceResets = 0
+
+        func watch(_ engine: HLSVideoEngine) { lock.withLock { _engine = engine } }
+
+        /// Runs inside the reopen, after the dead pump's own segments were reported.
+        func noteReopen() {
+            let engine = lock.withLock { _engine }
+            let count = engine?.liveSegmentCountSnapshot
+            lock.withLock { if _countAtFirstReopen == nil { _countAtFirstReopen = count } }
+        }
+
+        func noteSourceReset() { lock.withLock { _sourceResets += 1 } }
+
+        var countAtFirstReopen: Int? { lock.withLock { _countAtFirstReopen } }
+        var sourceResets: Int { lock.withLock { _sourceResets } }
+    }
+
+    private static func openLiveDemuxer() throws -> Demuxer {
+        let dem = Demuxer()
+        try dem.open(reader: TinyTransportStreamFixture.LiveReader(),
+                     formatHint: "mpegts", isLive: true)
+        return dem
+    }
+
+    @Test("segments a reopened live producer cuts reach the playlist", .timeLimit(.minutes(1)))
+    func reopenedProducerGrowsThePlaylist() async throws {
+        let observed = Observed()
+        let engine = HLSVideoEngine(
+            url: URL(string: "aether-custom://source")!,
+            dvModeAvailable: false,
+            isLiveSession: true,
+            liveCutTargetSeconds: 1,
+            preopenedDemuxer: try Self.openLiveDemuxer(),
+            sourceReopenableByURL: false,
+            customSourceReopenFactory: {
+                observed.noteReopen()
+                return (reader: TinyTransportStreamFixture.LiveReader(), formatHint: "mpegts")
+            })
+        observed.watch(engine)
+        _ = try engine.start()
+        defer { engine.stop() }
+
+        // The reader ends after one pass, which is the source loss; the factory is the reconnect.
+        try await waitFor { observed.countAtFirstReopen != nil }
+        let beforeLoss = try #require(observed.countAtFirstReopen)
+        #expect(beforeLoss > 0, "the first producer never reported a segment")
+
+        try await waitFor { (engine.liveSegmentCountSnapshot ?? 0) > beforeLoss }
+    }
+
+    @Test("a producer rebuilt in place reports into the same playlist", .timeLimit(.minutes(1)))
+    func rebuiltProducerReportsIntoThePlaylist() async throws {
+        let observed = Observed()
+        let engine = HLSVideoEngine(
+            url: URL(string: "aether-custom://source")!,
+            dvModeAvailable: false,
+            isLiveSession: true,
+            liveCutTargetSeconds: 1,
+            preopenedDemuxer: try Self.openLiveDemuxer(),
+            sourceReopenableByURL: false)
+        engine.onLiveSourceReset = { observed.noteSourceReset() }
+        _ = try engine.start()
+        defer { engine.stop() }
+
+        try await waitFor { observed.sourceResets > 0 }
+        let failed = try #require(engine.producer)
+        engine.rebuildLiveProducerInPlace(failed: failed)
+        let rebuilt = try #require(engine.producer)
+        #expect(rebuilt !== failed)
+        #expect(rebuilt.liveResidentCapProvider != nil)
+
+        let continuation = try #require(engine.provider?.liveContinuationPoint())
+        let report = try #require(rebuilt.onLiveSegmentFinalized, "the rebuilt producer reports to nobody")
+        report(continuation.nextIndex, 1.0, continuation.outputEndSeconds, true)
+        #expect(engine.liveSegmentCountSnapshot == continuation.nextIndex + 1)
+    }
+}
diff --git a/Tests/AetherEngineTests/TinyTransportStreamFixture.swift b/Tests/AetherEngineTests/TinyTransportStreamFixture.swift
new file mode 100644
index 000000000..530d28f76
--- /dev/null
+++ b/Tests/AetherEngineTests/TinyTransportStreamFixture.swift
@@ -0,0 +1,152 @@
+import Foundation
+@testable import AetherEngine
+
+/// An 8 s H.264 MPEG-TS (16x16, 2 fps, an IDR with in-band SPS/PPS every second, PTS from 1.4 s),
+/// small enough to embed so the live and pump tests run on CI without a fixture fetch. Regenerate with:
+///
+///     ffmpeg -f lavfi -i "color=c=black:s=16x16:r=2:d=8" -c:v libx264 -preset ultrafast \
+///       -profile:v baseline -crf 51 -g 2 -keyint_min 2 -sc_threshold 0 \
+///       -x264-params "bframes=0:repeat-headers=1" -pix_fmt yuv420p -f mpegts \
+///       -mpegts_service_type digital_tv -pat_period 60 -sdt_period 60 tiny-live.ts
+enum TinyTransportStreamFixture {
+
+    /// Video keyframes in the stream, one per second.
+    static let keyframeCount = 8
+
+    static var data: Data { Data(base64Encoded: base64.joined())! }
+
+    /// The stream as a live source serves it: from byte 0 to its end, then EOF, with no length and
+    /// no disc probe (a disc probe reads ahead, and a live open does not rewind after it).
+    final class LiveReader: IOReader, @unchecked Sendable {
+        private let bytes = TinyTransportStreamFixture.data
+        private let lock = NSLock()
+        private var position = 0
+
+        func read(_ buffer: UnsafeMutablePointer<UInt8>?, size: Int32) -> Int32 {
+            guard let buffer, size > 0 else { return -1 }
+            return lock.withLock {
+                let n = min(Int(size), bytes.count - position)
+                guard n > 0 else { return 0 }
+                bytes.withUnsafeBytes { raw in
+                    _ = memcpy(buffer, raw.baseAddress! + position, n)
+                }
+                position += n
+                return Int32(n)
+            }
+        }
+
+        func seek(offset: Int64, whence: Int32) -> Int64 {
+            lock.withLock {
+                switch whence {
+                case SEEK_SET where offset >= 0 && offset <= Int64(bytes.count):
+                    position = Int(offset)
+                case SEEK_CUR where offset == 0:
+                    break
+                default:
+                    return -1
+                }
+                return Int64(position)
+            }
+        }
+
+        func close() {}
+        var discImageProbeEnabled: Bool { false }
+    }
+
+    private static let base64 = [
+        "R0AREABC8CUAAcEAAP8B/wAB/IAUSBIBBkZGbXBlZwlTZXJ2aWNlMDF3fEPK////////////////////////////////////",
+        "////////////////////////////////////////////////////////////////////////////////////////////////",
+        "//////////////////////////////////////////////////////////9HQAAQAACwDQABwQAAAAHwACqxBLL/////////",
+        "////////////////////////////////////////////////////////////////////////////////////////////////",
+        "////////////////////////////////////////////////////////////////////////////////////////////////",
+        "/////////////////////0dQABAAArASAAHBAADhAPAAG+EA8AAVvU1W////////////////////////////////////////",
+        "////////////////////////////////////////////////////////////////////////////////////////////////",
+        "////////////////////////////////////////////////////////////////////////////////R0EAMAdQAAB7DH4A",
+        "AAAB4AAAgIAFIQAH2GEAAAABCfAAAAABZ0LACtp7ARAAAAMAEAAAAwBA8SJqAAAAAWjOAZcgAAABBgX//03cRem95tlIt5Ys",
+        "2CDZI+7veDI2NCAtIGNvcmUgMTY1IHIzMjIyIGIzNTYwNWEgLSBILjI2NC9NUEVHLTQgQVZDIGNvZGVjIC0gQ29weWxlZnQg",
+        "MjAwMy0yMDI1IC0gaHR0cDovL3d3dy52aWRlb2xhbi5HAQARb3JnL3gyNjQuaHRtbCAtIG9wdGlvbnM6IGNhYmFjPTAgcmVm",
+        "PTEgZGVibG9jaz0wOjA6MCBhbmFseXNlPTA6MCBtZT1kaWEgc3VibWU9MCBwc3k9MSBwc3lfcmQ9MS4wMDowLjAwIG1peGVk",
+        "X3JlZj0wIG1lX3JhbmdlPTE2IGNocm9tYV9tZT0xIHRyZWxsaXM9MCA4eDhkY3Q9MCBjcW09MCBkZWFkem9uZT0yMSwxMSBm",
+        "YXN0X0cBABJwc2tpcD0xIGNocm9tYV9xcF9vZmZzZXQ9MCB0aHJlYWRzPTEgbG9va2FoZWFkX3RocmVhZHM9MSBzbGljZWRf",
+        "dGhyZWFkcz0wIG5yPTAgZGVjaW1hdGU9MSBpbnRlcmxhY2VkPTAgYmx1cmF5X2NvbXBhdD0wIGNvbnN0cmFpbmVkX2ludHJh",
+        "PTAgYmZyYW1lcz0wIHdlaWdodHA9MCBrZXlpbnQ9MiBrZXlpbnRfbWluPTIgc2NlRwEAM0EA////////////////////////",
+        "/////////////////////////////////////////////////////////////25lY3V0PTAgaW50cmFfcmVmcmVzaD0wIHJj",
+        "PWNyZiBtYnRyZWU9MCBjcmY9NTEuMCBxY29tcD0wLjYwIHFwbWluPTAgcXBtYXg9NjkgcXBzdGVwPTQgaXBfcmF0aW89MS40",
+        "MCBhcT0wAIAAAAFliIQ6JigAFcBHQQA0mhAAANLwfgD/////////////////////////////////////////////////////",
+        "////////////////////////////////////////////////////////////////////////////////////////////////",
+        "//////////////////////////////////////////////8AAAHgAACAgAUhAAs38QAAAAEJ8AAAAAFBmiASpUdAABEAALAN",
+        "AAHBAAAAAfAAKrEEsv//////////////////////////////////////////////////////////////////////////////",
+        "////////////////////////////////////////////////////////////////////////////////////////////////",
+        "////////////////////////////////////////////////R1AAEQACsBIAAcEAAOEA8AAb4QDwABW9TVb/////////////",
+        "////////////////////////////////////////////////////////////////////////////////////////////////",
+        "////////////////////////////////////////////////////////////////////////////////////////////////",
+        "//////////9HQQA1c1AAASrUfgD/////////////////////////////////////////////////////////////////////",
+        "//////////////////////////////////////////////////////////////////////////8AAAHgAACAgAUhAA2XgQAA",
+        "AAEJ8AAAAAFnQsAK2nsBEAAAAwAQAAADAEDxImoAAAABaM4BlyAAAAFliIIDKJigACA/gEdBADaaEAABgrh+AP//////////",
+        "////////////////////////////////////////////////////////////////////////////////////////////////",
+        "/////////////////////////////////////////////////////////////////////////////////////////wAAAeAA",
+        "AICABSEAD/cRAAAAAQnwAAAAAUGaIBKlR0AAEgAAsA0AAcEAAAAB8AAqsQSy////////////////////////////////////",
+        "////////////////////////////////////////////////////////////////////////////////////////////////",
+        "//////////////////////////////////////////////////////////////////////////////////////////9HUAAS",
+        "AAKwEgABwQAA4QDwABvhAPAAFb1NVv//////////////////////////////////////////////////////////////////",
+        "////////////////////////////////////////////////////////////////////////////////////////////////",
+        "/////////////////////////////////////////////////////0dBADd0UAAB2px+AP//////////////////////////",
+        "////////////////////////////////////////////////////////////////////////////////////////////////",
+        "//////////////////////8AAAHgAACAgAUhABNWoQAAAAEJ8AAAAAFnQsAK2nsBEAAAAwAQAAADAEDxImoAAAABaM4BlyAA",
+        "AAFliIQOomKAAIGOR0EAOJoQAAIygH4A////////////////////////////////////////////////////////////////",
+        "////////////////////////////////////////////////////////////////////////////////////////////////",
+        "////////////////////////////////////AAAB4AAAgIAFIQAVtjEAAAABCfAAAAABQZogEqVHQAATAACwDQABwQAAAAHw",
+        "ACqxBLL/////////////////////////////////////////////////////////////////////////////////////////",
+        "////////////////////////////////////////////////////////////////////////////////////////////////",
+        "/////////////////////////////////////0dQABMAArASAAHBAADhAPAAG+EA8AAVvU1W////////////////////////",
+        "////////////////////////////////////////////////////////////////////////////////////////////////",
+        "////////////////////////////////////////////////////////////////////////////////////////////////",
+        "R0EAOXNQAAKKZH4A////////////////////////////////////////////////////////////////////////////////",
+        "////////////////////////////////////////////////////////////////AAAB4AAAgIAFIQAZFcEAAAABCfAAAAAB",
+        "Z0LACtp7ARAAAAMAEAAAAwBA8SJqAAAAAWjOAZcgAAABZYiCAQomKAAIIOBHQQA6mhAAAuJIfgD/////////////////////",
+        "////////////////////////////////////////////////////////////////////////////////////////////////",
+        "//////////////////////////////////////////////////////////////////////////////8AAAHgAACAgAUhABt1",
+        "UQAAAAEJ8AAAAAFBmiASpUdAABQAALANAAHBAAAAAfAAKrEEsv//////////////////////////////////////////////",
+        "////////////////////////////////////////////////////////////////////////////////////////////////",
+        "////////////////////////////////////////////////////////////////////////////////R1AAFAACsBIAAcEA",
+        "AOEA8AAb4QDwABW9TVb/////////////////////////////////////////////////////////////////////////////",
+        "////////////////////////////////////////////////////////////////////////////////////////////////",
+        "//////////////////////////////////////////9HQQA7c1AAAzosfgD/////////////////////////////////////",
+        "////////////////////////////////////////////////////////////////////////////////////////////////",
+        "//////////8AAAHgAACAgAUhAB3U4QAAAAEJ8AAAAAFnQsAK2nsBEAAAAwAQAAADAEDxImoAAAABaM4BlyAAAAFliIQEKJig",
+        "ACCDgEdBADyaEAADkhB+AP//////////////////////////////////////////////////////////////////////////",
+        "////////////////////////////////////////////////////////////////////////////////////////////////",
+        "/////////////////////////wAAAeAAAICABSEAITRxAAAAAQnwAAAAAUGaIBKlR0AAFQAAsA0AAcEAAAAB8AAqsQSy////",
+        "////////////////////////////////////////////////////////////////////////////////////////////////",
+        "////////////////////////////////////////////////////////////////////////////////////////////////",
+        "//////////////////////////9HUAAVAAKwEgABwQAA4QDwABvhAPAAFb1NVv//////////////////////////////////",
+        "////////////////////////////////////////////////////////////////////////////////////////////////",
+        "/////////////////////////////////////////////////////////////////////////////////////0dBAD1zUAAD",
+        "6fR+AP//////////////////////////////////////////////////////////////////////////////////////////",
+        "/////////////////////////////////////////////////////wAAAeAAAICABSEAI5QBAAAAAQnwAAAAAWdCwAraewEQ",
+        "AAADABAAAAMAQPEiagAAAAFozgGXIAAAAWWIggEaJigACCfgR0EAPpoQAARB2H4A////////////////////////////////",
+        "////////////////////////////////////////////////////////////////////////////////////////////////",
+        "////////////////////////////////////////////////////////////////////AAAB4AAAgIAFIQAl85EAAAABCfAA",
+        "AAABQZogEqVHQAAWAACwDQABwQAAAAHwACqxBLL/////////////////////////////////////////////////////////",
+        "////////////////////////////////////////////////////////////////////////////////////////////////",
+        "/////////////////////////////////////////////////////////////////////0dQABYAArASAAHBAADhAPAAG+EA",
+        "8AAVvU1W////////////////////////////////////////////////////////////////////////////////////////",
+        "////////////////////////////////////////////////////////////////////////////////////////////////",
+        "////////////////////////////////R0EAP3NQAASZvH4A////////////////////////////////////////////////",
+        "////////////////////////////////////////////////////////////////////////////////////////////////",
+        "AAAB4AAAgIAFIQApUyEAAAABCfAAAAABZ0LACtp7ARAAAAMAEAAAAwBA8SJqAAAAAWjOAZcgAAABZYiEBGiYoAAgn4BHQQAw",
+        "mhAABPGgfgD/////////////////////////////////////////////////////////////////////////////////////",
+        "////////////////////////////////////////////////////////////////////////////////////////////////",
+        "//////////////8AAAHgAACAgAUhACuysQAAAAEJ8AAAAAFBmiASpUdAABcAALANAAHBAAAAAfAAKrEEsv//////////////",
+        "////////////////////////////////////////////////////////////////////////////////////////////////",
+        "////////////////////////////////////////////////////////////////////////////////////////////////",
+        "////////////////R1AAFwACsBIAAcEAAOEA8AAb4QDwABW9TVb/////////////////////////////////////////////",
+        "////////////////////////////////////////////////////////////////////////////////////////////////",
+        "//////////////////////////////////////////////////////////////////////////9HQQAxc1AABUmEfgD/////",
+        "////////////////////////////////////////////////////////////////////////////////////////////////",
+        "//////////////////////////////////////////8AAAHgAACAgAUhAC8SQQAAAAEJ8AAAAAFnQsAK2nsBEAAAAwAQAAAD",
+        "AEDxImoAAAABaM4BlyAAAAFliIIBKiYoAAgv4EdBADKaEAAFoWh+AP//////////////////////////////////////////",
+        "////////////////////////////////////////////////////////////////////////////////////////////////",
+        "/////////////////////////////////////////////////////////wAAAeAAAICABSEAMXHRAAAAAQnwAAAAAUGaIBKl",
+    ]
+}

From 6f7e1bf963a6f1cf0c183f5ebad52777f9e94438 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 06:18:33 +0200
Subject: [PATCH 153/359] fix(plan): bound the segment plan's duration and
 index inputs (audit HLS-102)

The three plan builders converted durations and index timestamps with trapping `Int64(_:)` /
`Int(_:)` and sized arrays from the duration. A container header can state about 9.2e12 s and a
Matroska index can carry entries near both `Int64` extremes, so a hostile file trapped the plan
(1 ns timebase), asked the uniform builder for 2.3e12 segments, or overflowed the trust check.

- `Demuxer.effectiveDurationSeconds` clamps to one week, non-finite to 0.
- `indexedKeyframes` and `firstIndexedTimestamp` drop entries past 2^62 ticks or 4e9 s, and do
  the AE#105 fold and the #409 offset with checked arithmetic, dropping an entry that overflows.
- The builders compute the trust-check spread in Double, go through a checked `planPts` helper
  that returns an empty plan on overflow, and the uniform builder widens its stride so a plan
  never exceeds 200,000 segments.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 Sources/AetherEngine/Demuxer/Demuxer.swift    |  80 ++++++++---
 .../HLSVideoEngine+SegmentPlanning.swift      |  55 ++++++--
 .../SegmentPlanHostileInputTests.swift        | 131 ++++++++++++++++++
 3 files changed, 234 insertions(+), 32 deletions(-)
 create mode 100644 Tests/AetherEngineTests/SegmentPlanHostileInputTests.swift

diff --git a/Sources/AetherEngine/Demuxer/Demuxer.swift b/Sources/AetherEngine/Demuxer/Demuxer.swift
index 622225556..d41315a79 100644
--- a/Sources/AetherEngine/Demuxer/Demuxer.swift
+++ b/Sources/AetherEngine/Demuxer/Demuxer.swift
@@ -406,14 +406,44 @@ public final class Demuxer: @unchecked Sendable {
 
     /// Fold a raw timestamp onto the contiguous presentation timeline given its byte position and time base.
     /// Must be called under `accessLock`.
-    private func normalizedTimestamp(_ ts: Int64, pos: Int64, timeBase: AVRational) -> Int64 {
+    private func normalizedTimestamp(_ ts: Int64, pos: Int64, timeBase: AVRational) -> Int64? {
         guard ts != Int64.min, !clipTimeline.isEmpty else { return ts }
-        let sub = clipSubtractSeconds(forPos: pos)
+        return Self.foldedIndexTimestamp(ts, subtractSeconds: clipSubtractSeconds(forPos: pos), timeBase: timeBase)
+    }
+
+    /// The AE#105 fold of one index entry, nil when the shift or the result leaves the tick range. The
+    /// shift comes from the disc's own playlist, and a wrapped entry is worse than a missing one: the
+    /// plan built from it lands wherever the wrap put it (audit HLS-102).
+    static func foldedIndexTimestamp(_ ts: Int64, subtractSeconds sub: Double, timeBase: AVRational) -> Int64? {
         guard sub != 0, timeBase.num > 0, timeBase.den > 0 else { return ts }
-        let subTicks = Int64((sub * Double(timeBase.den) / Double(timeBase.num)).rounded())
-        return ts &- subTicks
+        let subTicks = (sub * Double(timeBase.den) / Double(timeBase.num)).rounded()
+        guard subTicks.isFinite, abs(subTicks) < Self.maxPlausibleIndexTicks else { return nil }
+        let (folded, overflow) = ts.subtractingReportingOverflow(Int64(subTicks))
+        return overflow ? nil : folded
+    }
+
+    /// The #409 decode-ladder offset applied to one index entry, nil on overflow (audit HLS-102).
+    static func offsetIndexTimestamp(_ ts: Int64, by offset: Int64?) -> Int64? {
+        guard let offset else { return ts }
+        let (placed, overflow) = ts.addingReportingOverflow(offset)
+        return overflow ? nil : placed
+    }
+
+    /// Whether an index entry can be a real position (audit HLS-102): under 2^62 ticks, so any
+    /// difference of two entries fits `Int64`, and under 4e9 s on its own time base. libavformat
+    /// rejects only NOPTS and the relative-timestamp band near `Int64.max`; entries near `Int64.min`
+    /// and just below the band reach the plan builders otherwise. Epoch-anchored sources stay inside
+    /// both limits (1.79e18 ns in 2026 is under 2^62 until about 2116, 1.79e9 epoch seconds under 4e9
+    /// until about 2096).
+    static func isPlausibleIndexTimestamp(_ ts: Int64, timeBase: AVRational) -> Bool {
+        guard ts != Int64.min, ts.magnitude < UInt64(1) << 62,
+              timeBase.num > 0, timeBase.den > 0 else { return false }
+        return abs(Double(ts) * Double(timeBase.num) / Double(timeBase.den)) < maxPlausibleIndexSeconds
     }
 
+    static let maxPlausibleIndexTicks: Double = 0x1p62
+    static let maxPlausibleIndexSeconds: Double = 4e9
+
     /// True once a disc structure (BD/DVD/UDF) was recognized at open. Disc sources concat
     /// MPEG-TS / VOB clips and have no EOF cue index, so the MKV cue-index prewarm seek is
     /// useless there and a cold mid-disc range read is expensive on a remote ISO (#76).
@@ -451,12 +481,23 @@ public final class Demuxer: @unchecked Sendable {
     /// everything - the non-seekable pb ran no tail estimate, so the container value is 0 or
     /// garbage from fabricated range data - then a custom time-seekable reader's own duration,
     /// then the disc/container resolution above.
+    ///
+    /// The result is clamped to `[0, MediaDurationCeiling.seconds]` (audit HLS-102): a corrupt header
+    /// can state about 9.2e12 s, which the segment plan turned into a trapping tick conversion or a
+    /// multi-terabyte reservation. Clamped rather than zeroed, so a slightly broken header still plays.
     static func effectiveDurationSeconds(
         declared: Double?, readerDuration: Double?, discTitle: Double?, container: Double
     ) -> Double {
-        if let declared, declared > 0 { return declared }
-        if let readerDuration, readerDuration > 0 { return readerDuration }
-        return effectiveDurationSeconds(discTitle: discTitle, container: container)
+        let resolved: Double
+        if let declared, declared > 0 {
+            resolved = declared
+        } else if let readerDuration, readerDuration > 0 {
+            resolved = readerDuration
+        } else {
+            resolved = effectiveDurationSeconds(discTitle: discTitle, container: container)
+        }
+        guard resolved.isFinite, resolved > 0 else { return 0 }
+        return min(resolved, MediaDurationCeiling.seconds)
     }
 
     /// Open a media URL and probe its streams.
@@ -1510,18 +1551,17 @@ public final class Demuxer: @unchecked Sendable {
         guard count > 0 else { return [] }
         let tb = stream.pointee.time_base
         var result: [Int64] = []
-        result.reserveCapacity(Int(count))
         for i in 0..<count {
-            guard let entry = avformat_index_get_entry(stream, i) else { continue }
-            // AVINDEX_KEYFRAME = 0x0001
-            if entry.pointee.flags & 0x0001 != 0,
-               entry.pointee.timestamp != Int64.min {
-                // Fold each entry onto the contiguous timeline (multi-clip disc) so the segment plan
-                // built from these IRAP positions matches the normalized packets (AE#105), then onto
-                // the repaired decode ladder if #409 moved it.
-                let folded = normalizedTimestamp(entry.pointee.timestamp, pos: entry.pointee.pos, timeBase: tb)
-                result.append(compositionOffset.map { folded &+ $0 } ?? folded)
-            }
+            // AVINDEX_KEYFRAME = 0x0001. Fold each entry onto the contiguous timeline (multi-clip disc)
+            // so the segment plan built from these IRAP positions matches the normalized packets
+            // (AE#105), then onto the repaired decode ladder if #409 moved it.
+            guard let entry = avformat_index_get_entry(stream, i),
+                  entry.pointee.flags & 0x0001 != 0,
+                  Self.isPlausibleIndexTimestamp(entry.pointee.timestamp, timeBase: tb),
+                  let folded = normalizedTimestamp(entry.pointee.timestamp, pos: entry.pointee.pos, timeBase: tb),
+                  let placed = Self.offsetIndexTimestamp(folded, by: compositionOffset)
+            else { continue }
+            result.append(placed)
         }
         return result
     }
@@ -1618,7 +1658,9 @@ public final class Demuxer: @unchecked Sendable {
     /// when this demuxer opened mid-file. Int64.min when the container has no index yet.
     private func firstIndexedTimestamp(of stream: UnsafeMutablePointer<AVStream>) -> Int64 {
         guard avformat_index_get_entries_count(stream) > 0,
-              let entry = avformat_index_get_entry(stream, 0) else { return Int64.min }
+              let entry = avformat_index_get_entry(stream, 0),
+              Self.isPlausibleIndexTimestamp(entry.pointee.timestamp, timeBase: stream.pointee.time_base)
+        else { return Int64.min }
         return entry.pointee.timestamp
     }
 
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine+SegmentPlanning.swift b/Sources/AetherEngine/Video/HLSVideoEngine+SegmentPlanning.swift
index fa3e16bb5..315142afd 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine+SegmentPlanning.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine+SegmentPlanning.swift
@@ -76,11 +76,12 @@ extension HLSVideoEngine {
               videoTimeBase.num > 0, videoTimeBase.den > 0 else { return false }
         let tb = Double(videoTimeBase.num) / Double(videoTimeBase.den)
         let sorted = keyframes.sorted()
-        let coverageSeconds = Double(sorted[sorted.count - 1] - sorted[0]) * tb
+        // In Double: an index spanning both Int64 extremes overflows the integer difference (audit HLS-102).
+        let coverageSeconds = (Double(sorted[sorted.count - 1]) - Double(sorted[0])) * tb
         guard coverageSeconds >= minCoverageSeconds else { return false }
         var largestGapSeconds = 0.0
         for i in 1..<sorted.count {
-            let gapSeconds = Double(sorted[i] - sorted[i - 1]) * tb
+            let gapSeconds = (Double(sorted[i]) - Double(sorted[i - 1])) * tb
             if gapSeconds > largestGapSeconds { largestGapSeconds = gapSeconds }
         }
         return largestGapSeconds <= maxTrustedGapSeconds
@@ -182,6 +183,19 @@ extension HLSVideoEngine {
         return firstKeyframe != nil ? .singleKeyframeInSource(budget) : .unknown
     }
 
+    /// Most segments any plan builder emits (audit HLS-102). A week at the 4 s target is 151,200.
+    static let maxPlanSegments = 200_000
+
+    /// `base + seconds / tb` in ticks, nil when the result leaves the tick range (audit HLS-102): the
+    /// builders are fed container durations and manifest sums, and `Int64(_:)` traps on NaN, infinity
+    /// and anything past `Int64`. Truncates like the plain conversion it replaces.
+    static func planPts(_ base: Int64, plusSeconds seconds: Double, timeBase tb: Double) -> Int64? {
+        let ticks = seconds / tb
+        guard ticks.isFinite, abs(ticks) < Demuxer.maxPlausibleIndexTicks else { return nil }
+        let (pts, overflow) = base.addingReportingOverflow(Int64(ticks))
+        return overflow ? nil : pts
+    }
+
     /// Uniform-duration fallback plan when the keyframe index is too sparse. Source-axis boundaries are
     /// anchored at `startPts0` (the first keyframe PTS), exactly like the keyframe-aligned plan, so segment 0
     /// begins at the content start rather than at source PTS 0. A title whose content starts late (e.g. a
@@ -196,9 +210,14 @@ extension HLSVideoEngine {
         startPts0: Int64 = 0,
         strideSeconds: Double = HLSVideoEngine.targetSegmentDuration
     ) -> [Segment] {
-        guard sourceDurationSeconds > 0 else { return [] }
-        let stride = strideSeconds.isFinite && strideSeconds > 0 ? strideSeconds : Self.targetSegmentDuration
-        let count = max(1, Int(ceil(sourceDurationSeconds / stride)))
+        guard sourceDurationSeconds > 0, sourceDurationSeconds.isFinite else { return [] }
+        var stride = strideSeconds.isFinite && strideSeconds > 0 ? strideSeconds : Self.targetSegmentDuration
+        // Audit HLS-102: a stride this fine over a header-stated duration asked for trillions of
+        // segments. Widen it instead, so the plan still covers the whole duration.
+        if sourceDurationSeconds / stride > Double(maxPlanSegments) {
+            stride = sourceDurationSeconds / Double(maxPlanSegments)
+        }
+        let count = min(maxPlanSegments, max(1, Int(ceil(sourceDurationSeconds / stride))))
         let tb = Double(videoTimeBase.num) / Double(videoTimeBase.den)
         guard tb > 0 else { return [] }
 
@@ -206,9 +225,10 @@ extension HLSVideoEngine {
         plan.reserveCapacity(count)
         for i in 0..<count {
             let startSeconds = Double(i) * stride
-            let endSeconds = min(sourceDurationSeconds, Double(i + 1) * stride)
-            let startPts = startPts0 + Int64(startSeconds / tb)
-            let endPts = startPts0 + Int64(endSeconds / tb)
+            let endSeconds = i + 1 == count
+                ? sourceDurationSeconds : min(sourceDurationSeconds, Double(i + 1) * stride)
+            guard let startPts = planPts(startPts0, plusSeconds: startSeconds, timeBase: tb),
+                  let endPts = planPts(startPts0, plusSeconds: endSeconds, timeBase: tb) else { return [] }
             plan.append(Segment(
                 startPts: startPts,
                 endPts: endPts,
@@ -274,17 +294,21 @@ extension HLSVideoEngine {
 
         // Segment 0 keeps the content start itself: there is nothing below it to back off toward, and
         // the head-of-stream gate has no restart target anyway.
-        func boundaryPts(_ i: Int) -> Int64 {
-            i == 0 ? startPts0 : startPts0 + Int64((starts[i] - backoff) / tb)
+        func boundaryPts(_ i: Int) -> Int64? {
+            i == 0 ? startPts0 : planPts(startPts0, plusSeconds: starts[i] - backoff, timeBase: tb)
         }
 
         var plan: [Segment] = []
         plan.reserveCapacity(starts.count)
         for i in 0..<starts.count {
             let endSeconds = i + 1 < starts.count ? starts[i + 1] : end
+            guard let startPts = boundaryPts(i),
+                  let endPts = i + 1 < starts.count
+                    ? boundaryPts(i + 1) : planPts(startPts0, plusSeconds: end, timeBase: tb)
+            else { return [] }
             plan.append(Segment(
-                startPts: boundaryPts(i),
-                endPts: i + 1 < starts.count ? boundaryPts(i + 1) : startPts0 + Int64(end / tb),
+                startPts: startPts,
+                endPts: endPts,
                 startSeconds: starts[i],
                 durationSeconds: Swift.max(0.001, endSeconds - starts[i])
             ))
@@ -310,6 +334,8 @@ extension HLSVideoEngine {
         plan.reserveCapacity(sorted.count)
         var i = 0
         var segIdx = 0
+        // Audit HLS-102: the index spread must fit `Int64` for the offsets below.
+        guard !sorted[sorted.count - 1].subtractingReportingOverflow(startPts0).overflow else { return [] }
         while i < sorted.count {
             let segStartPts = sorted[i]
             let segStartSeconds = Double(segStartPts - startPts0) * tb
@@ -330,7 +356,10 @@ extension HLSVideoEngine {
             } else {
                 segEndSeconds = sourceDurationSeconds
                 // GOTCHA: final endPts is startPts0-anchored; consumers must not use it raw: segmentIndex() clamps past-the-end PTS into the last segment.
-                segEndPts = startPts0 + Int64(sourceDurationSeconds / tb)
+                guard let finalEndPts = planPts(startPts0, plusSeconds: sourceDurationSeconds, timeBase: tb) else {
+                    return []
+                }
+                segEndPts = finalEndPts
             }
 
             plan.append(Segment(
diff --git a/Tests/AetherEngineTests/SegmentPlanHostileInputTests.swift b/Tests/AetherEngineTests/SegmentPlanHostileInputTests.swift
new file mode 100644
index 000000000..a413c7349
--- /dev/null
+++ b/Tests/AetherEngineTests/SegmentPlanHostileInputTests.swift
@@ -0,0 +1,131 @@
+import Foundation
+import Testing
+import AetherLibavutil
+@testable import AetherEngine
+
+/// Audit HLS-102: the segment-plan builders converted durations and index timestamps to `Int64` / `Int`
+/// with trapping conversions and sized arrays from the duration. A container header can state about
+/// 9.2e12 s, and a Matroska index can carry entries near both `Int64` extremes (libavformat rejects only
+/// the relative-timestamp band), so nothing upstream bounded either.
+@Suite("Segment-plan inputs from a hostile header or index")
+struct SegmentPlanHostileInputTests {
+
+    private let ts90k = AVRational(num: 1, den: 90_000)
+    private let nanos = AVRational(num: 1, den: 1_000_000_000)
+
+    // MARK: - Container duration
+
+    @Test("A container duration past a week is clamped to a week, not zeroed")
+    func containerDurationClamps() {
+        #expect(Demuxer.effectiveDurationSeconds(
+            declared: nil, readerDuration: nil, discTitle: nil, container: 9.2e12) == 604_800)
+        #expect(Demuxer.effectiveDurationSeconds(
+            declared: 1e13, readerDuration: nil, discTitle: nil, container: 7508) == 604_800)
+        #expect(Demuxer.effectiveDurationSeconds(
+            declared: nil, readerDuration: 1e13, discTitle: nil, container: 7508) == 604_800)
+    }
+
+    @Test("A non-finite duration resolves to zero")
+    func nonFiniteDurationIsZero() {
+        #expect(Demuxer.effectiveDurationSeconds(
+            declared: .infinity, readerDuration: nil, discTitle: nil, container: 7508) == 0)
+        #expect(Demuxer.effectiveDurationSeconds(
+            declared: nil, readerDuration: nil, discTitle: .infinity, container: 7508) == 0)
+    }
+
+    @Test("An ordinary duration keeps the precedence chain")
+    func ordinaryDurationUnchanged() {
+        #expect(Demuxer.effectiveDurationSeconds(
+            declared: nil, readerDuration: nil, discTitle: 42, container: 91_843.97) == 42)
+        #expect(Demuxer.effectiveDurationSeconds(
+            declared: nil, readerDuration: nil, discTitle: nil, container: 7508.93) == 7508.93)
+    }
+
+    // MARK: - Index entries
+
+    @Test("Index entries past 2^62 ticks or 4e9 seconds are implausible")
+    func implausibleIndexEntries() {
+        #expect(Demuxer.isPlausibleIndexTimestamp(Int64.max - (1 << 49), timeBase: ts90k) == false)
+        #expect(Demuxer.isPlausibleIndexTimestamp(Int64.min + 1, timeBase: ts90k) == false)
+        #expect(Demuxer.isPlausibleIndexTimestamp(Int64.min, timeBase: ts90k) == false)
+        // 2^61 ticks at 90 kHz is 2.56e13 s, far past the seconds limit.
+        #expect(Demuxer.isPlausibleIndexTimestamp(1 << 61, timeBase: ts90k) == false)
+        #expect(Demuxer.isPlausibleIndexTimestamp(1 << 62, timeBase: nanos) == false)
+    }
+
+    @Test("Real index entries, epoch-anchored ones included, stay plausible")
+    func plausibleIndexEntries() {
+        #expect(Demuxer.isPlausibleIndexTimestamp(0, timeBase: ts90k))
+        #expect(Demuxer.isPlausibleIndexTimestamp(-3003, timeBase: ts90k))
+        #expect(Demuxer.isPlausibleIndexTimestamp(Int64(7508.9 * 90_000), timeBase: ts90k))
+        // Epoch nanoseconds in 2026 (1.79e18) and epoch at 10 MHz.
+        #expect(Demuxer.isPlausibleIndexTimestamp(1_790_000_000_000_000_000, timeBase: nanos))
+        #expect(Demuxer.isPlausibleIndexTimestamp(17_900_000_000_000_000, timeBase: AVRational(num: 1, den: 10_000_000)))
+    }
+
+    @Test("The multi-clip fold and the composition offset drop an entry that would overflow")
+    func foldAndOffsetAreChecked() {
+        // A disc playlist stating a shift of 2e14 s is 1.8e19 ticks at 90 kHz.
+        #expect(Demuxer.foldedIndexTimestamp(90_000, subtractSeconds: 2e14, timeBase: ts90k) == nil)
+        #expect(Demuxer.foldedIndexTimestamp(90_000, subtractSeconds: .nan, timeBase: ts90k) == nil)
+        #expect(Demuxer.foldedIndexTimestamp(Int64.min + 5, subtractSeconds: 1, timeBase: ts90k) == nil)
+        #expect(Demuxer.foldedIndexTimestamp(900_000, subtractSeconds: 1.5, timeBase: ts90k) == 765_000)
+        #expect(Demuxer.foldedIndexTimestamp(900_000, subtractSeconds: 0, timeBase: ts90k) == 900_000)
+        #expect(Demuxer.offsetIndexTimestamp(Int64.max - 10, by: 20) == nil)
+        #expect(Demuxer.offsetIndexTimestamp(1000, by: -3003) == -2003)
+        #expect(Demuxer.offsetIndexTimestamp(1000, by: nil) == 1000)
+    }
+
+    // MARK: - Builders
+
+    @Test("The trust check survives an index spanning both Int64 extremes")
+    func trustCheckSpread() {
+        #expect(HLSVideoEngine.keyframeIndexIsTrustworthy(
+            keyframes: [Int64.max - (1 << 49), Int64.min + 1],
+            videoTimeBase: ts90k, sourceDurationSeconds: 7200) == false)
+    }
+
+    @Test("A segmented plan over a manifest sum past Int64 ticks is empty instead of trapping")
+    func segmentedPlanHugeDuration() {
+        let plan = HLSVideoEngine.buildSegmentedSourcePlan(
+            segmentStartsSeconds: [0, 4, 8], videoTimeBase: ts90k,
+            sourceDurationSeconds: 2e14, startPts0: 0)
+        #expect(plan.isEmpty)
+        let hugeStart = HLSVideoEngine.buildSegmentedSourcePlan(
+            segmentStartsSeconds: [0, 4, 2e14], videoTimeBase: ts90k,
+            sourceDurationSeconds: 2e14 + 4, startPts0: 0)
+        #expect(hugeStart.isEmpty)
+    }
+
+    @Test("A uniform plan over a huge duration stays bounded")
+    func uniformPlanBounded() {
+        let plan = HLSVideoEngine.buildUniformSegmentPlan(
+            videoTimeBase: ts90k, sourceDurationSeconds: 1e12)
+        #expect(plan.count <= HLSVideoEngine.maxPlanSegments)
+        #expect(plan.last.map { $0.startSeconds + $0.durationSeconds } == 1e12)
+        #expect(HLSVideoEngine.buildUniformSegmentPlan(
+            videoTimeBase: ts90k, sourceDurationSeconds: .infinity).isEmpty)
+    }
+
+    @Test("A uniform plan whose ticks leave Int64 is empty instead of trapping")
+    func uniformPlanTickOverflow() {
+        #expect(HLSVideoEngine.buildUniformSegmentPlan(
+            videoTimeBase: ts90k, sourceDurationSeconds: 1e14).isEmpty)
+    }
+
+    @Test("A keyframe plan whose final end leaves Int64 at a fine time base is empty instead of trapping")
+    func keyframePlanTickOverflow() {
+        #expect(HLSVideoEngine.buildKeyframeSegmentPlan(
+            keyframes: [0, 4_000_000_000, 8_000_000_000], videoTimeBase: nanos,
+            sourceDurationSeconds: 1e10).isEmpty)
+    }
+
+    @Test("A week-long uniform plan at the target stride is unchanged by the cap")
+    func weekLongPlanUnchanged() {
+        let plan = HLSVideoEngine.buildUniformSegmentPlan(
+            videoTimeBase: ts90k, sourceDurationSeconds: 604_800)
+        #expect(plan.count == 151_200)
+        #expect(plan[1].startSeconds == 4)
+        #expect(plan.last.map { $0.startSeconds + $0.durationSeconds } == 604_800)
+    }
+}

From 55d4579210e9e7757ba6cbe38be3e6fb34edf587 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 06:22:24 +0200
Subject: [PATCH 154/359] fix(core): a backgrounding owed during a load waits
 for the load to return (audit LIF-101, LIF-105)

The CORE-2 owed decision settled on any move out of `.loading`. A native
load passes through `.paused` (item readiness, inside the tvOS play gate)
seconds before it returns, so on tvOS the teardown ran under the load and
the host's `load()` threw `CancellationError`, the signal for "a newer
load or stop took over". Sodalite takes that as a supersede and skips its
observers and the Jellyfin start report, leaving a spinner up.

`loadSession` and `reloadWithAudioOverride` now mark the generation in
flight and settle the owed decision from their own exit. The decision
still hops through a Task, so the host's continuation after `load()`
wires its observers first, then the teardown runs. A decision made at
didEnterBackground, on the settle hop or at the iOS grace expiry while a
load is in flight is owed instead. The tvOS PiP close goes through the
same funnel, so a window closed during an in-PiP load or seek is torn
down once it settles instead of never (LIF-105). The bookkeeping is
platform-neutral so the settle timing is testable on macOS.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../AetherEngine/AetherEngine+Loading.swift   |   3 +
 Sources/AetherEngine/AetherEngine.swift       | 188 ++++++++++++------
 .../BackgroundDecisionWaitsForLoadTests.swift | 136 +++++++++++++
 3 files changed, 264 insertions(+), 63 deletions(-)
 create mode 100644 Tests/AetherEngineTests/BackgroundDecisionWaitsForLoadTests.swift

diff --git a/Sources/AetherEngine/AetherEngine+Loading.swift b/Sources/AetherEngine/AetherEngine+Loading.swift
index 872e48825..0314793f0 100644
--- a/Sources/AetherEngine/AetherEngine+Loading.swift
+++ b/Sources/AetherEngine/AetherEngine+Loading.swift
@@ -2313,6 +2313,9 @@ extension AetherEngine {
         if mediaServicesWereReset { dropAudioPlayerHostAfterMediaServicesReset() }
         EngineLog.emit("[AetherEngine] reload: stopInternal done (\(elapsedMs(since: reloadStart))ms)", category: .engine)
         let gen = loadGeneration
+        // Audit LIF-101: the same settle point as `load`, for the same readiness waypoint.
+        beginLoadInFlight(gen)
+        defer { endLoadInFlight(gen) }
         loadedURL = url
         lastDetectedVideoCodec = preservedVideoCodec
 
diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index 5d08801d6..bf98a8880 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -61,9 +61,7 @@ public final class AetherEngine: ObservableObject {
             if case .error = state {} else { errorInfo = nil }
             recomputePlaybackPhase()
             resolveLoadingStashedSeek(from: oldValue)
-            #if os(iOS) || os(tvOS)
             settleOwedBackgroundAction()
-            #endif
         }
     }
 
@@ -743,12 +741,10 @@ public final class AetherEngine: ObservableObject {
             // window and never double-draw under the fullscreen host overlay.
             softwareHost?.updateSubtitleCompositor(cues: subtitleCues + secondarySubtitleCues, enabled: pictureInPictureActive)
             #if os(tvOS)
-            // PiP window closed while backgrounded: nothing keeps the app running anymore, so run the
-            // wedge-safe teardown now, before idle suspension (mirrors the iOS pause-while-backgrounded path).
-            if oldValue && !pictureInPictureActive && isBackgrounded,
-               !audioAVPlayerActive, audioHost == nil, softwareHost == nil,
-               state == .playing || state == .paused {
-                Task { @MainActor in await self.teardownVideoForBackground() }
+            // PiP window closed while backgrounded: nothing keeps the app running anymore, so the
+            // wedge-safe teardown is due before idle suspension (mirrors the iOS pause-while-backgrounded path).
+            if oldValue && !pictureInPictureActive {
+                settleBackgroundDecisionAfterPictureInPictureClosed()
             }
             #endif
         }
@@ -917,13 +913,17 @@ public final class AetherEngine: ObservableObject {
     /// a fresh layer. A host driving PiP must still set `pictureInPictureActive`, which arms both the
     /// keepalive policy and that in-place handover.
     public var nativePlayerLayer: AVPlayerLayer? { nativeHost?.playerLayer }
-    #if os(iOS) || os(tvOS)
     /// True between didEnterBackground and didBecomeActive; gates the pause-while-backgrounded teardown
-    /// (iOS) and the PiP-closed-while-backgrounded teardown (tvOS).
+    /// (iOS) and the PiP-closed-while-backgrounded teardown (tvOS). Never set on macOS.
     private var isBackgrounded = false
-    /// Audit CORE-2: didEnterBackground ran while a load or seek was in flight.
+    /// Audit CORE-2: didEnterBackground (or a background PiP close) ran while a load or seek was in flight.
     private var backgroundActionOwed = false
-    #endif
+    /// Audit LIF-101: the generation of the `load()` or `reloadWithAudioOverride` still running. A
+    /// load passes through `.paused` long before it returns (native readiness during the play gate),
+    /// so its state cannot say whether it settled; this can.
+    private var loadInFlightGeneration: UInt64?
+    /// Test seam for the owed background decision on a platform without an app lifecycle.
+    var owedBackgroundPolicyForTesting: (@MainActor (AetherEngine) async -> Void)?
     #if os(iOS)
     /// #127: pending grace-window teardown (sleep task + the background-task assertion holding it).
     private var backgroundGraceTask: Task<Void, Never>?
@@ -3852,6 +3852,9 @@ public final class AetherEngine: ObservableObject {
         let gen = loadGeneration
         attempt.generation = gen
         waitingLoadGenerations.insert(gen)
+        // Audit LIF-101: an owed background decision is settled from here, not from a waypoint.
+        beginLoadInFlight(gen)
+        defer { endLoadInFlight(gen) }
         // #361: open the host-visible startup sequence. A reroute re-entering load() continues the
         // one already running rather than starting a second.
         let startupGen = beginStartupProgress()
@@ -7211,11 +7214,7 @@ public final class AetherEngine: ObservableObject {
         ) { [weak self] _ in
             Task { @MainActor in
                 guard let self = self else { return }
-                self.isBackgrounded = true
-                // Audit CORE-2: a load or seek in flight has a pipeline (loopback server, AVIO
-                // connection, the item) but no settled state to judge it by, and it settles into
-                // `.playing` in the background with nothing left to look again. Owe it the decision.
-                self.backgroundActionOwed = Self.backgroundActionIsOwed(state: self.state)
+                self.noteDidEnterBackground()
                 await self.applyBackgroundPolicy()
             }
         }
@@ -7335,17 +7334,101 @@ public final class AetherEngine: ObservableObject {
         #endif
     }
 
-    #if os(iOS) || os(tvOS)
-    /// Release the video pipeline before tvOS suspension.
-    ///
-    /// stopInternal's replaceCurrentItem(nil) + VTDecompressionSession invalidation frees the shared
-    /// mediaserverd decode session synchronously. keepNativeHost=true preserves the NativeAVPlayerHost shell
-    /// for AVKit's Now-Playing registration (issue #15); keepCustomReader=true retains the byte-source reader.
+    // MARK: Owed background decision (audit CORE-2, LIF-101)
+
+    /// Audit LIF-101: whether a background decision can be made now. Not while a load is in flight:
+    /// a teardown there unwinds the host's `load()` with the `CancellationError` that means "a newer
+    /// load or stop took over", and the host treats it as a supersede (no observers, no start report,
+    /// a spinner that never clears).
+    nonisolated static func backgroundDecisionSettles(state: PlaybackState, loadInFlight: Bool) -> Bool {
+        !loadInFlight && !backgroundActionIsOwed(state: state)
+    }
+
+    private var backgroundDecisionMustWait: Bool {
+        !Self.backgroundDecisionSettles(state: state, loadInFlight: loadInFlightGeneration == loadGeneration)
+    }
+
+    func beginLoadInFlight(_ generation: UInt64) {
+        loadInFlightGeneration = generation
+    }
+
+    /// Called from the load's own exit, which is the settle point a state it passes through is not.
+    func endLoadInFlight(_ generation: UInt64) {
+        guard loadInFlightGeneration == generation else { return }
+        loadInFlightGeneration = nil
+        settleOwedBackgroundAction()
+    }
+
+    /// didEnterBackground's bookkeeping. Audit CORE-2: a load or seek in flight has a pipeline
+    /// (loopback server, AVIO connection, the item) but no settled state to judge it by, and it
+    /// settles into `.playing` in the background with nothing left to look again. Owe it the decision.
+    func noteDidEnterBackground() {
+        isBackgrounded = true
+        backgroundActionOwed = backgroundDecisionMustWait
+    }
+
+    /// Audit LIF-105: the PiP window closed while backgrounded, so nothing keeps the app running and
+    /// the wedge-safe teardown is due. Through the owed funnel, so a load or seek in flight in the
+    /// window is torn down once it settles instead of never.
+    func settleBackgroundDecisionAfterPictureInPictureClosed() {
+        guard isBackgrounded, !audioAVPlayerActive, audioHost == nil, softwareHost == nil else { return }
+        backgroundActionOwed = true
+        settleOwedBackgroundAction()
+    }
+
+    /// Called from the `state` didSet and from a load's exit. A decision owed since the app went to
+    /// the background is made once the session has settled into a transport state.
+    private func settleOwedBackgroundAction() {
+        guard backgroundActionOwed, !backgroundDecisionMustWait else { return }
+        backgroundActionOwed = false
+        guard isBackgrounded, state == .playing || state == .paused else { return }
+        EngineLog.emit(
+            "[AetherEngine] background: the decision owed while a load or seek was in flight settled "
+            + "(state=\(state)); applying the background policy now (audit CORE-2)",
+            category: .engine)
+        Task { @MainActor [weak self] in await self?.runOwedBackgroundPolicy() }
+    }
+
+    private func runOwedBackgroundPolicy() async {
+        if let policy = owedBackgroundPolicyForTesting {
+            await policy(self)
+            return
+        }
+        #if os(iOS) || os(tvOS)
+        await applyBackgroundPolicy()
+        #endif
+    }
+
+    /// The synchronous half of the background teardown. stopInternal's replaceCurrentItem(nil) +
+    /// VTDecompressionSession invalidation frees the shared mediaserverd decode session.
+    /// keepNativeHost=true preserves the NativeAVPlayerHost shell for AVKit's Now-Playing registration
+    /// (issue #15); keepCustomReader=true retains the byte-source reader.
     /// clock.currentTime/loadedURL/loadedOptions are preserved so reloadAtCurrentPosition() resumes correctly.
-    ///
-    /// A UIApplication background-task assertion is held across teardown so the loopback server's detached
-    /// socket close (HLSVideoEngine.stop drains the producer up to 3 s) completes before suspension.
-    @MainActor
+    func releaseVideoPipelineForBackground() {
+        // #357: park the selection first. The foreground reload snapshots at reload time, which on
+        // this path is long after stopInternal wiped what it wants.
+        captureBackgroundTeardownSelection()
+        // AE#597: this path emitted nothing at all, so a field log could not say whether the
+        // session was released before a suspension or carried through it whole. Which of the two
+        // happened is the first question every wake-from-sleep report asks.
+        EngineLog.emit(
+            "[AetherEngine] #597 background teardown: releasing the video pipeline "
+            + "(backend=\(playbackBackend), state=\(state))",
+            category: .engine)
+        let teardownStart = DispatchTime.now()
+        stopInternal(resetDisplayCriteria: false, keepNativeHost: true, keepCustomReader: true)
+        releaseSubtitleProxyForBackground()
+        // Session torn down; host will reload + repause on foreground return.
+        state = .paused
+        let teardownMs = Double(
+            DispatchTime.now().uptimeNanoseconds - teardownStart.uptimeNanoseconds) / 1_000_000
+        EngineLog.emit(
+            "[AetherEngine] #597 background teardown done in "
+            + "\(String(format: "%.0f", teardownMs))ms; the audio session and the native host "
+            + "shell stay",
+            category: .engine)
+    }
+
     /// AE#597: `stopInternal` does not touch the proxy, so without this its loopback socket rides
     /// the suspension. Both background teardowns call it, the awaited one and the synchronous
     /// backstop the system takes when it reclaims the grace assertion early.
@@ -7361,10 +7444,16 @@ public final class AetherEngine: ObservableObject {
             category: .engine)
     }
 
+    #if os(iOS) || os(tvOS)
     /// What didEnterBackground does with the running session. Runs again when a load or seek that
     /// was in flight at that moment settles while the app is still in the background (audit CORE-2).
     private func applyBackgroundPolicy() async {
         guard isBackgrounded else { return }
+        // Audit LIF-101: a load in flight settles this from its own exit (`endLoadInFlight`).
+        if backgroundDecisionMustWait {
+            backgroundActionOwed = true
+            return
+        }
         #if os(iOS)
         // Keep the video pipeline alive for PiP / background audio while the app stays running.
         // Wedge-safe: a pause while backgrounded tears down via pause(), so nothing crosses
@@ -7407,44 +7496,14 @@ public final class AetherEngine: ObservableObject {
         }
     }
 
-    /// Audit CORE-2: called from the `state` didSet. A load or seek that was in flight when the app
-    /// went to the background gets the background decision once it settles into a transport state.
-    private func settleOwedBackgroundAction() {
-        guard backgroundActionOwed, !Self.backgroundActionIsOwed(state: state) else { return }
-        backgroundActionOwed = false
-        guard isBackgrounded, state == .playing || state == .paused else { return }
-        EngineLog.emit(
-            "[AetherEngine] background: the load or seek in flight at didEnterBackground settled "
-            + "(state=\(state)); applying the background policy now (audit CORE-2)",
-            category: .engine)
-        Task { @MainActor [weak self] in await self?.applyBackgroundPolicy() }
-    }
-
+    /// Release the video pipeline before tvOS suspension (`releaseVideoPipelineForBackground`).
+    ///
+    /// A UIApplication background-task assertion is held across teardown so the loopback server's detached
+    /// socket close (HLSVideoEngine.stop drains the producer up to 3 s) completes before suspension.
     private func teardownVideoForBackground() async {
         let app = UIApplication.shared
         let bgTask = app.beginBackgroundTask(withName: "AetherEngine.bgVideoTeardown")
-        // #357: park the selection first. The foreground reload snapshots at reload time, which on
-        // this path is long after stopInternal wiped what it wants.
-        captureBackgroundTeardownSelection()
-        // AE#597: this path emitted nothing at all, so a field log could not say whether the
-        // session was released before a suspension or carried through it whole. Which of the two
-        // happened is the first question every wake-from-sleep report asks.
-        EngineLog.emit(
-            "[AetherEngine] #597 background teardown: releasing the video pipeline "
-            + "(backend=\(playbackBackend), state=\(state))",
-            category: .engine)
-        let teardownStart = DispatchTime.now()
-        stopInternal(resetDisplayCriteria: false, keepNativeHost: true, keepCustomReader: true)
-        releaseSubtitleProxyForBackground()
-        // Session torn down; host will reload + repause on foreground return.
-        state = .paused
-        let teardownMs = Double(
-            DispatchTime.now().uptimeNanoseconds - teardownStart.uptimeNanoseconds) / 1_000_000
-        EngineLog.emit(
-            "[AetherEngine] #597 background teardown done in "
-            + "\(String(format: "%.0f", teardownMs))ms; the audio session and the native host "
-            + "shell stay",
-            category: .engine)
+        releaseVideoPipelineForBackground()
         // Wait for the loopback server's detached cleanup (<=3 s producer drain + socket shutdown) before releasing.
         try? await Task.sleep(nanoseconds: 3_500_000_000)
         if bgTask != .invalid { app.endBackgroundTask(bgTask) }
@@ -7486,7 +7545,10 @@ public final class AetherEngine: ObservableObject {
     /// mid-window) and perform it without further deferral.
     private func fireBackgroundGraceTeardown() async {
         backgroundGraceTask = nil
-        if isBackgrounded {
+        if isBackgrounded, backgroundDecisionMustWait {
+            // Audit LIF-101: a load the host started inside the window gets the decision at its exit.
+            backgroundActionOwed = true
+        } else if isBackgrounded {
             switch currentBackgroundAction() {
             case .teardownVideo:
                 EngineLog.emit("[AetherEngine] background grace window expired, tearing down paused pipeline (#127)", category: .engine)
diff --git a/Tests/AetherEngineTests/BackgroundDecisionWaitsForLoadTests.swift b/Tests/AetherEngineTests/BackgroundDecisionWaitsForLoadTests.swift
new file mode 100644
index 000000000..7b16d1c1e
--- /dev/null
+++ b/Tests/AetherEngineTests/BackgroundDecisionWaitsForLoadTests.swift
@@ -0,0 +1,136 @@
+import Foundation
+import Testing
+@testable import AetherEngine
+
+/// Audit LIF-101: the CORE-2 owed background decision settled on any move out of `.loading`, and a
+/// native load passes through `.paused` (the item's readiness, landing inside the tvOS play gate)
+/// seconds before it returns. The tvOS teardown that followed bumped the generation under the load,
+/// and the host's `load()` threw the `CancellationError` that means "a newer load or stop took
+/// over". Sodalite reads it exactly that way: no observers, no start report, a spinner forever.
+///
+/// The lifecycle itself is iOS / tvOS only; the owed funnel is not, so these drive it through
+/// `noteDidEnterBackground()` and a policy seam that performs the same synchronous teardown.
+@Suite("A background decision owed during a load waits for the load to return", .timeLimit(.minutes(2)))
+@MainActor
+struct BackgroundDecisionWaitsForLoadTests {
+
+    /// A fixture served from memory whose first read parks until the test lets it through, so a
+    /// load can be held in flight for as long as a test needs.
+    final class HeldDataReader: IOReader, @unchecked Sendable {
+        private let data: DataIOReader
+        private let condition = NSCondition()
+        private var released = false
+        private var arrivals = 0
+
+        init(_ bytes: Data) { data = DataIOReader(data: bytes) }
+
+        var entered: Bool { condition.withLock { arrivals > 0 } }
+        func release() { condition.withLock { released = true; condition.broadcast() } }
+
+        func read(_ buffer: UnsafeMutablePointer<UInt8>?, size: Int32) -> Int32 {
+            condition.lock()
+            arrivals += 1
+            while !released { condition.wait() }
+            condition.unlock()
+            return data.read(buffer, size: size)
+        }
+        func seek(offset: Int64, whence: Int32) -> Int64 { data.seek(offset: offset, whence: whence) }
+        func close() { release() }
+        func cancel() { release() }
+        func makeIndependentReader() -> IOReader? { nil }
+        var discImageProbeEnabled: Bool { false }
+    }
+
+    /// The states the owed decision was made in, one per decision.
+    final class PolicyRuns {
+        var states: [PlaybackState] = []
+    }
+
+    private static func installPolicy(on engine: AetherEngine) -> PolicyRuns {
+        let runs = PolicyRuns()
+        engine.owedBackgroundPolicyForTesting = { engine in
+            runs.states.append(engine.state)
+            engine.releaseVideoPipelineForBackground()
+        }
+        return runs
+    }
+
+    private static func fixture() throws -> Data { try ProbeTestFixtures.hdr10Plus() }
+
+    @Test("A load in flight holds the decision whatever state it passes through")
+    func settleMatrix() {
+        #expect(!AetherEngine.backgroundDecisionSettles(state: .paused, loadInFlight: true))
+        #expect(!AetherEngine.backgroundDecisionSettles(state: .playing, loadInFlight: true))
+        #expect(AetherEngine.backgroundDecisionSettles(state: .paused, loadInFlight: false))
+        #expect(AetherEngine.backgroundDecisionSettles(state: .playing, loadInFlight: false))
+        #expect(!AetherEngine.backgroundDecisionSettles(state: .loading, loadInFlight: false))
+        #expect(!AetherEngine.backgroundDecisionSettles(state: .seeking, loadInFlight: false))
+    }
+
+    @Test("load() returns normally when the app backgrounds mid-load, and the teardown follows it (audit LIF-101)")
+    func loadReturnsThenTheTeardownRuns() async throws {
+        let engine = try AetherEngine()
+        defer { engine.stop() }
+        let runs = Self.installPolicy(on: engine)
+        let reader = HeldDataReader(try Self.fixture())
+        let load = Task { @MainActor in
+            try await engine.load(source: .custom(reader, formatHint: "mp4"))
+        }
+        try await waitFor { reader.entered }
+
+        engine.noteDidEnterBackground()
+        // The readiness waypoint `.loading -> .paused` the native load passes through mid-flight.
+        engine.state = .paused
+        let decidedMidLoad = try await waitFor(upTo: .milliseconds(300)) { !runs.states.isEmpty }
+        #expect(!decidedMidLoad)
+        reader.release()
+
+        let probe = try await load.value
+        #expect(probe != nil)
+        try await waitFor { !runs.states.isEmpty }
+        #expect(runs.states == [.playing])
+        #expect(engine.state == .paused)
+        #expect(engine.loadedURL != nil)
+    }
+
+    @Test("With no load in flight an owed decision still settles on the state edge (audit CORE-2)")
+    func owedSeekStillSettlesOnTheState() async throws {
+        let engine = try AetherEngine()
+        defer { engine.stop() }
+        _ = try await engine.load(source: .custom(DataIOReader(data: try Self.fixture()), formatHint: "mp4"))
+        let runs = Self.installPolicy(on: engine)
+        engine.state = .seeking
+
+        engine.noteDidEnterBackground()
+        engine.state = .playing
+
+        try await waitFor { !runs.states.isEmpty }
+        #expect(runs.states == [.playing])
+        #expect(engine.state == .paused)
+    }
+
+    @Test("A PiP window closed in the background during a load tears the session down once it settles (audit LIF-105)")
+    func pictureInPictureClosedMidLoadIsOwed() async throws {
+        let engine = try AetherEngine()
+        defer { engine.stop() }
+        _ = try await engine.load(source: .custom(DataIOReader(data: try Self.fixture()), formatHint: "mp4"))
+        let runs = Self.installPolicy(on: engine)
+        // Backgrounded with a PiP window keeping the session alive, so nothing was owed.
+        engine.noteDidEnterBackground()
+
+        let reader = HeldDataReader(try Self.fixture())
+        let load = Task { @MainActor in
+            try await engine.load(source: .custom(reader, formatHint: "mp4"))
+        }
+        try await waitFor { reader.entered }
+        engine.settleBackgroundDecisionAfterPictureInPictureClosed()
+        let decidedMidLoad = try await waitFor(upTo: .milliseconds(300)) { !runs.states.isEmpty }
+        #expect(!decidedMidLoad)
+        reader.release()
+
+        _ = try await load.value
+        try await waitFor { !runs.states.isEmpty }
+        #expect(runs.states == [.playing])
+        #expect(engine.state == .paused)
+    }
+}

From f2d8f8fe80803befde9aa7da3313070cea11f8fb Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 06:23:50 +0200
Subject: [PATCH 155/359] fix(demux): convert seek targets and byte estimates
 through checked helpers (audit DMX-113, BIT-105, DMX-103)

`Int64(seconds * 1e6)` and the stream-time-base form in `Demuxer.seek(to:)` and `seekBounded`
trapped on NaN, infinity and anything past about 9.2e12 s, and several public entry points pass
host values through unvalidated (`FrameExtractor.thumbnail/snapshot(at:)`, the SW and audio
hosts' `load(startPosition:)`, `seek(to:)` during `.loading`). `byteEstimateTarget` and
`byteEstimateCorrection` converted before their `min(fileSize, ...)` clamp, so an origin that
inflated its `Content-Range` total trapped the subtitle side reader's byte-estimate fallback.

- New `Demuxer.ticks(forSeconds:timeBase:)`: nil unless finite and under 2^62 ticks; both seeks
  and `FrameDecodeContext`'s target PTS go through it, and the seeks return false on nil.
- The byte estimates compare the raw Double against the total before converting.
- API boundary: `FrameExtractor` returns nil for a non-finite or negative time, `FrameCache`
  saturates its bucket, the SW and audio hosts ignore a non-finite start position, and the
  public `seek(to:)` ignores a non-finite target.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 Sources/AetherEngine/AetherEngine.swift       |  6 ++
 .../Audio/AudioPlaybackHost.swift             |  2 +-
 Sources/AetherEngine/Demuxer/Demuxer.swift    | 50 +++++++---
 .../FrameExtractor/FrameCache.swift           |  3 +-
 .../FrameExtractor/FrameDecodeContext.swift   |  4 +-
 .../FrameExtractor/FrameExtractor.swift       |  3 +-
 .../Native/SoftwarePlaybackHost.swift         |  2 +-
 .../SeekTargetConversionTests.swift           | 91 +++++++++++++++++++
 8 files changed, 141 insertions(+), 20 deletions(-)
 create mode 100644 Tests/AetherEngineTests/SeekTargetConversionTests.swift

diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index db53863a3..b83f41380 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -5242,6 +5242,12 @@ public final class AetherEngine: ObservableObject {
     }
 
     public func seek(to seconds: Double) async {
+        // Audit DMX-113: the `.loading` branch below would otherwise publish a NaN or infinite
+        // position into the clock, and the hosts' seeks hand it to the Demuxer as ticks.
+        guard seconds.isFinite else {
+            EngineLog.emit("[AetherEngine] seek(to:\(seconds)) ignored: not a finite position", category: .engine)
+            return
+        }
         await seek(to: seconds, origin: .host)
     }
 
diff --git a/Sources/AetherEngine/Audio/AudioPlaybackHost.swift b/Sources/AetherEngine/Audio/AudioPlaybackHost.swift
index 1cb47cc6e..4340190b7 100644
--- a/Sources/AetherEngine/Audio/AudioPlaybackHost.swift
+++ b/Sources/AetherEngine/Audio/AudioPlaybackHost.swift
@@ -147,7 +147,7 @@ final class AudioPlaybackHost {
         self.audioOutput = AudioOutput()
         self.audioOutput?.volume = volume
 
-        if let start = startPosition, start > 0 {
+        if let start = startPosition, start.isFinite, start > 0 {
             // #254: same off-main, deadline-bounded reposition the transport seek uses. Also load()'s
             // only suspension point, so the only place a stop() can land mid-load.
             _ = await dem.seekBounded(to: start, timeout: Self.seekBudgetSeconds, on: seekQueue)
diff --git a/Sources/AetherEngine/Demuxer/Demuxer.swift b/Sources/AetherEngine/Demuxer/Demuxer.swift
index d41315a79..776b61c89 100644
--- a/Sources/AetherEngine/Demuxer/Demuxer.swift
+++ b/Sources/AetherEngine/Demuxer/Demuxer.swift
@@ -444,6 +444,19 @@ public final class Demuxer: @unchecked Sendable {
     static let maxPlausibleIndexTicks: Double = 0x1p62
     static let maxPlausibleIndexSeconds: Double = 4e9
 
+    /// Seconds as ticks on `timeBase`, nil unless the result is finite and under 2^62 ticks (audit
+    /// DMX-113, BIT-105). This is where every seconds-based reposition becomes an integer, and
+    /// `Int64(_:)` traps on NaN, infinity and anything past `Int64`; every caller already treats a
+    /// failed seek as one. Truncates like the plain conversion it replaces.
+    nonisolated static func ticks(forSeconds seconds: Double, timeBase: AVRational) -> Int64? {
+        guard timeBase.num > 0, timeBase.den > 0 else { return nil }
+        let ticks = seconds * Double(timeBase.den) / Double(timeBase.num)
+        guard ticks.isFinite, abs(ticks) < maxPlausibleIndexTicks else { return nil }
+        return Int64(ticks)
+    }
+
+    nonisolated static let avTimeBase = AVRational(num: 1, den: AV_TIME_BASE)
+
     /// True once a disc structure (BD/DVD/UDF) was recognized at open. Disc sources concat
     /// MPEG-TS / VOB clips and have no EOF cue index, so the MKV cue-index prewarm seek is
     /// useless there and a cold mid-disc range read is expensive on a remote ISO (#76).
@@ -1810,7 +1823,8 @@ public final class Demuxer: @unchecked Sendable {
     func seek(to seconds: Double) -> Bool {
         accessLock.lock()
         defer { accessLock.unlock() }
-        guard let ctx = formatContext else { return false }
+        guard let ctx = formatContext,
+              let timestamp = Self.ticks(forSeconds: seconds, timeBase: Self.avTimeBase) else { return false }
         // #409: the read position moves, so the repair drops its picture-order anchor and
         // re-anchors on the next keyframe (a seek always lands on one).
         compositionRepair?.noteSeek()
@@ -1819,7 +1833,6 @@ public final class Demuxer: @unchecked Sendable {
             resetAfterTimeSeek(ctx)
             return true
         }
-        let timestamp = Int64(seconds * Double(AV_TIME_BASE))
         let ret = avformat_seek_file(ctx, -1, Int64.min, timestamp, Int64.max, 0)
         if ret < 0 {
             #if DEBUG
@@ -1966,6 +1979,17 @@ public final class Demuxer: @unchecked Sendable {
         defer { accessLock.unlock() }
         guard let ctx = formatContext else { return false }
         guard probeControl?.isStopped != true else { return false }
+        // A stream-anchored seek carries the target in that stream's own time base; only the -1
+        // form is expressed in AV_TIME_BASE units.
+        var anchor: Int32 = -1
+        var timeBase = Self.avTimeBase
+        if anchorStreamIndex >= 0, anchorStreamIndex < Int32(ctx.pointee.nb_streams),
+           let tb = ctx.pointee.streams[Int(anchorStreamIndex)]?.pointee.time_base,
+           tb.num > 0, tb.den > 0 {
+            anchor = anchorStreamIndex
+            timeBase = tb
+        }
+        guard let timestamp = Self.ticks(forSeconds: seconds, timeBase: timeBase) else { return false }
         // #409: the read position moves, so the repair drops its picture-order anchor and
         // re-anchors on the next keyframe (a seek always lands on one).
         compositionRepair?.noteSeek()
@@ -1985,16 +2009,6 @@ public final class Demuxer: @unchecked Sendable {
         // seek on a remote ISO sat wedged ~230 s and every later re-arm queued behind it.
         avioProvider?.beginReadDeadline(secondsFromNow: timeout)
         defer { avioProvider?.endReadDeadline() }
-        // A stream-anchored seek carries the target in that stream's own time base; only the -1
-        // form is expressed in AV_TIME_BASE units.
-        var anchor: Int32 = -1
-        var timestamp = Int64(seconds * Double(AV_TIME_BASE))
-        if anchorStreamIndex >= 0, anchorStreamIndex < Int32(ctx.pointee.nb_streams),
-           let tb = ctx.pointee.streams[Int(anchorStreamIndex)]?.pointee.time_base,
-           tb.num > 0, tb.den > 0 {
-            anchor = anchorStreamIndex
-            timestamp = Int64(seconds * Double(tb.den) / Double(tb.num))
-        }
         let ret = avformat_seek_file(ctx, anchor, Int64.min, timestamp, Int64.max, 0)
         avformat_flush(ctx)
         resetSubpictureAssembly()  // #651: libavformat just dropped the parsers this stands in for
@@ -2114,7 +2128,15 @@ public final class Demuxer: @unchecked Sendable {
     ) -> Int64? {
         guard fileSize > 0, duration > 0, target >= 0 else { return nil }
         let fraction = min(1.0, max(0.0, (target - startOrigin - earlyBiasSeconds) / duration))
-        return Int64(Double(fileSize) * fraction)
+        return clampedByteOffset(Double(fileSize) * fraction, fileSize: fileSize)
+    }
+
+    /// `raw` as a byte offset in `[0, fileSize]` (audit DMX-103). The compare runs on the Double:
+    /// the total is whatever the origin wrote in `Content-Range`, and a `min(fileSize, ...)` after
+    /// `Int64(_:)` comes too late for a product that rounds up to 2^63 or past it.
+    nonisolated static func clampedByteOffset(_ raw: Double, fileSize: Int64) -> Int64 {
+        guard raw > 0 else { return 0 }
+        return raw >= Double(fileSize) ? fileSize : Int64(raw)
     }
 
     /// Landing verdict for one byte-estimate probe (#112 round 10).
@@ -2139,7 +2161,7 @@ public final class Demuxer: @unchecked Sendable {
         let late = landed > target
         let farEarly = landed < target - byteEstimateAcceptEarlyWindowSeconds
         guard late || farEarly else { return .accept }
-        let corrected = min(fileSize, max(0, Int64(Double(currentByte) * (targetRel / landedRel))))
+        let corrected = clampedByteOffset(Double(currentByte) * (targetRel / landedRel), fileSize: fileSize)
         guard corrected != currentByte else { return .accept }
         return .probe(corrected)
     }
diff --git a/Sources/AetherEngine/FrameExtractor/FrameCache.swift b/Sources/AetherEngine/FrameExtractor/FrameCache.swift
index e8391587e..8a44738b7 100644
--- a/Sources/AetherEngine/FrameExtractor/FrameCache.swift
+++ b/Sources/AetherEngine/FrameExtractor/FrameCache.swift
@@ -34,7 +34,8 @@ final class FrameCache {
         // Thumbnails floor to grid; snapshots round to nearest so a value within
         // half a bucket of a stored position resolves to the same entry.
         let rounded = mode == .thumbnail ? scaled.rounded(.down) : scaled.rounded()
-        return Int(rounded)
+        // Audit BIT-105: `Int(_:)` traps past `Int.max`; every such position shares the last bucket.
+        return rounded < 0x1p62 ? Int(rounded) : 1 << 62
     }
 
     func get(mode: FrameMode, seconds: Double) -> CGImage? {
diff --git a/Sources/AetherEngine/FrameExtractor/FrameDecodeContext.swift b/Sources/AetherEngine/FrameExtractor/FrameDecodeContext.swift
index cb7bf67b8..4a3e99346 100644
--- a/Sources/AetherEngine/FrameExtractor/FrameDecodeContext.swift
+++ b/Sources/AetherEngine/FrameExtractor/FrameDecodeContext.swift
@@ -405,8 +405,8 @@ final class FrameDecodeContext: @unchecked Sendable {
 
         demuxer.seek(to: seekSeconds)
 
-        guard timeBase.num > 0 else { return nil }
-        let targetPTS = Int64((seekSeconds * Double(timeBase.den)) / Double(timeBase.num))
+        // A target the stream's own time base cannot hold is no position in it (audit BIT-105).
+        guard let targetPTS = Demuxer.ticks(forSeconds: seekSeconds, timeBase: timeBase) else { return nil }
 
         var frame: UnsafeMutablePointer<AVFrame>? = av_frame_alloc()
         guard frame != nil else { return nil }
diff --git a/Sources/AetherEngine/FrameExtractor/FrameExtractor.swift b/Sources/AetherEngine/FrameExtractor/FrameExtractor.swift
index 01a53904d..83c8e3be1 100644
--- a/Sources/AetherEngine/FrameExtractor/FrameExtractor.swift
+++ b/Sources/AetherEngine/FrameExtractor/FrameExtractor.swift
@@ -119,7 +119,8 @@ public actor FrameExtractor {
     // MARK: - Core
 
     private func produce(at seconds: Double, mode: FrameMode, targetWidth: Int, maxSize: CGSize?) async -> CGImage? {
-        guard !isShutDown else { return nil }
+        // Audit BIT-105: a 0/0 scrub fraction or `CMTime.indefinite.seconds` is a host bug, not a position.
+        guard !isShutDown, seconds.isFinite, seconds >= 0 else { return nil }
         if let hit = cache.get(mode: mode, seconds: seconds) {
             scheduleIdleClose()
             return hit
diff --git a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
index b16f70c84..c09331886 100644
--- a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
+++ b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
@@ -943,7 +943,7 @@ final class SoftwarePlaybackHost {
         // Reset the live feeder state for the new session.
         resetFeederState()
 
-        if let start = startPosition, start > 0 {
+        if let start = startPosition, start.isFinite, start > 0 {
             // #254: same off-main, deadline-bounded reposition the transport seek uses. A resume into a
             // remote source that has to scan for its landing would otherwise block the main thread here.
             _ = await dem.seekBounded(to: start, timeout: Self.seekBudgetSeconds, on: seekQueue)
diff --git a/Tests/AetherEngineTests/SeekTargetConversionTests.swift b/Tests/AetherEngineTests/SeekTargetConversionTests.swift
new file mode 100644
index 000000000..7ae6b21a5
--- /dev/null
+++ b/Tests/AetherEngineTests/SeekTargetConversionTests.swift
@@ -0,0 +1,91 @@
+import Foundation
+import Testing
+import AetherLibavutil
+@testable import AetherEngine
+
+/// Audit DMX-113, BIT-105, DMX-103: every seconds-based reposition becomes integer ticks in the Demuxer,
+/// and `Int64(_:)` traps on NaN, infinity and anything past `Int64`. Host values (a 0/0 scrub fraction,
+/// `.infinity` as "resume at the end") and an origin that inflates its `Content-Range` total reached it.
+@Suite("Seek targets that do not fit a tick count fail instead of trapping")
+struct SeekTargetConversionTests {
+
+    private static let microseconds = AVRational(num: 1, den: AV_TIME_BASE)
+
+    private static func fixture() -> Data {
+        Data(base64Encoded: AtmosDetectionProbeIntegrationTests.videoOnlyBase64,
+             options: .ignoreUnknownCharacters) ?? Data()
+    }
+
+    // MARK: - The conversion
+
+    @Test("Non-finite and out-of-range seconds convert to nil", arguments: [
+        Double.nan, .infinity, -.infinity, 1e300, 4.7e12, -4.7e12,
+    ])
+    func unconvertible(seconds: Double) {
+        #expect(Demuxer.ticks(forSeconds: seconds, timeBase: Self.microseconds) == nil)
+    }
+
+    @Test("Ordinary seconds convert exactly as before")
+    func convertible() {
+        #expect(Demuxer.ticks(forSeconds: 1.5, timeBase: Self.microseconds) == 1_500_000)
+        #expect(Demuxer.ticks(forSeconds: -2, timeBase: Self.microseconds) == -2_000_000)
+        #expect(Demuxer.ticks(forSeconds: 7508.9, timeBase: AVRational(num: 1, den: 90_000))
+                == Int64(7508.9 * 90_000.0 / 1.0))
+        #expect(Demuxer.ticks(forSeconds: 1, timeBase: AVRational(num: 0, den: 1)) == nil)
+    }
+
+    // MARK: - The Demuxer's seeks
+
+    @Test("seek(to:) refuses NaN, infinity and a target past Int64", arguments: [
+        Double.nan, .infinity, 1e300,
+    ])
+    func demuxerSeekRefuses(seconds: Double) throws {
+        let demuxer = Demuxer()
+        defer { demuxer.close() }
+        try demuxer.open(reader: DataIOReader(data: Self.fixture()), formatHint: "mp4")
+        #expect(demuxer.seek(to: seconds) == false)
+        #expect(demuxer.seek(to: 0))
+    }
+
+    @Test("seekBounded refuses NaN, infinity and a target past Int64, stream-anchored or not", arguments: [
+        Double.nan, .infinity, 1e300,
+    ])
+    func demuxerSeekBoundedRefuses(seconds: Double) throws {
+        let demuxer = Demuxer()
+        defer { demuxer.close() }
+        try demuxer.open(reader: DataIOReader(data: Self.fixture()), formatHint: "mp4")
+        #expect(demuxer.seekBounded(to: seconds, timeout: 2) == false)
+        #expect(demuxer.seekBounded(to: seconds, anchorStreamIndex: demuxer.videoStreamIndex, timeout: 2) == false)
+    }
+
+    // MARK: - Byte estimate
+
+    @Test("A byte estimate against an inflated total saturates at the total")
+    func byteEstimateSaturates() {
+        #expect(Demuxer.byteEstimateTarget(fileSize: .max, duration: 10, target: 100) == .max)
+        #expect(Demuxer.byteEstimateCorrection(
+            landed: 1.5, target: 3600, startOrigin: 0, duration: 3600,
+            fileSize: 1_000_000_000_000_000_000, currentByte: 997_000_000_000_000_000, attempt: 0)
+                == .probe(1_000_000_000_000_000_000))
+    }
+
+    // MARK: - FrameExtractor boundary
+
+    @Test("A thumbnail at a non-finite or negative time is nil", arguments: [
+        Double.infinity, .nan, -1,
+    ])
+    func thumbnailRefuses(seconds: Double) async {
+        let extractor = FrameExtractor(reader: DataIOReader(data: Self.fixture()), formatHint: "mp4")
+        #expect(await extractor.thumbnail(at: seconds) == nil)
+        #expect(await extractor.snapshot(at: seconds) == nil)
+        await extractor.shutdown()
+    }
+
+    @Test("A thumbnail far past the end is clamped to the source, not a trap")
+    func thumbnailFarPastTheEnd() async {
+        let extractor = FrameExtractor(reader: DataIOReader(data: Self.fixture()), formatHint: "mp4")
+        _ = await extractor.thumbnail(at: 1e300)
+        _ = await extractor.snapshot(at: 1e300)
+        await extractor.shutdown()
+    }
+}

From 1891ca21de75e5f761a90f7157fa3010799091c7 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 06:24:53 +0200
Subject: [PATCH 156/359] fix(hls): a superseded producer's report or delayed
 revive leaves the session alone (audit HLS-104, HLS-105, SEG-104)

One identity rule for three ways a producer the session already replaced
still acted on it.

SEG-104 (B): a restart replaced while its first post-seek read was in
flight could open its gate afterwards, record its EpochAxis (dropping
the table at and above its index) and wake re-cut waiters with an epoch
whose bytes are never stored. The installed producer's epoch is now
mirrored under anchorShiftLock on every assignment of `producer`, and the
gate-open and live rebase handlers are passed their producer's epoch and
ignore any other.

HLS-104: the #377 metered revive slept 3 to 45 s and then re-anchored
whatever producer was current, typically the working one a
segment-driven restart had installed during the backoff. It now captures
its dead producer weakly plus the session epoch and restarts only if
both are still current.

HLS-105: the AE#412 re-cut mark was dropped when the seek's 2 s gate wait
timed out, while the restart it marked kept running; its late gate then
recorded isRecut false and composed the backoff into the axis. The mark
is now a RecutMark owned by the restart: performRestart binds it to the
producer it installs at the marked index, a restart elsewhere keeps a
pending mark and drops a bound one, the wait's timeout no longer touches
it, and a newer seek drops a mark whose restart never installed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../Video/HLSVideoEngine+LiveReopen.swift     |  37 +++-
 .../AetherEngine/Video/HLSVideoEngine.swift   | 106 +++++++++--
 .../SupersededProducerReportTests.swift       | 180 ++++++++++++++++++
 3 files changed, 298 insertions(+), 25 deletions(-)
 create mode 100644 Tests/AetherEngineTests/SupersededProducerReportTests.swift

diff --git a/Sources/AetherEngine/Video/HLSVideoEngine+LiveReopen.swift b/Sources/AetherEngine/Video/HLSVideoEngine+LiveReopen.swift
index 0bbc3b580..c8ed5580b 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine+LiveReopen.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine+LiveReopen.swift
@@ -282,7 +282,7 @@ extension HLSVideoEngine {
                 packetsWritten: prod.packetsWrittenCount,
                 cachedSegments: cache?.count ?? 0
             ) {
-                handleVODReadErrorExit(code)
+                handleVODReadErrorExit(code, deadProducer: prod)
             } else {
                 EngineLog.emit(
                     "[HLSVideoEngine] VOD pump died before producing anything "
@@ -429,7 +429,7 @@ extension HLSVideoEngine {
     /// AVPlayer's real position, authoritative so it wins the coalescer's pending slot. The
     /// demuxer whose read just threw is marked suspect so performRestart replaces it via the #79
     /// fresh-demuxer path instead of seeking the failed connection.
-    func handleVODReadErrorExit(_ code: Int32) {
+    func handleVODReadErrorExit(_ code: Int32, deadProducer: HLSSegmentProducer? = nil) {
         // #377: the reader knows the difference between a source that is gone and one that is
         // metering us, and loses it on the way here: the give-up arm returns a bare `-1`, FFmpeg
         // renders that as "Operation not permitted", and this is what arrives. Ask the budget,
@@ -518,13 +518,34 @@ extension HLSVideoEngine {
             + "\(String(format: "%.0f", spent))s of \(String(format: "%.0f", budget))s spent)",
             category: .session
         )
-        Task.detached(priority: .userInitiated) { [weak self] in
+        let sessionEpoch = sessionEpochSnapshot()
+        Task.detached(priority: .userInitiated) { [weak self, weak deadProducer] in
             try? await Task.sleep(nanoseconds: UInt64(delay * 1_000_000_000))
             guard let self else { return }
-            self.requestRestart(at: idx, authoritative: true)
+            self.fireMeteredRevive(at: idx, deadProducer: deadProducer, sessionEpoch: sessionEpoch)
         }
     }
 
+    /// Audit HLS-104: the backoff runs 3 to 45 s, and in that time a segment-driven restart, a seek or
+    /// a stop may already have replaced the dead producer. Whichever did has the better position.
+    static func meteredReviveStillOwed(sessionUnchanged: Bool, deadProducerInstalled: Bool) -> Bool {
+        sessionUnchanged && deadProducerInstalled
+    }
+
+    func fireMeteredRevive(at idx: Int, deadProducer: HLSSegmentProducer?, sessionEpoch: UInt64) {
+        let sessionUnchanged = isSessionEpochCurrent(sessionEpoch)
+        let owed = Self.meteredReviveStillOwed(
+            sessionUnchanged: sessionUnchanged, deadProducerInstalled: currentProducerIs(deadProducer))
+        guard owed else {
+            EngineLog.emit(
+                "[HLSVideoEngine] #377 metered revive at seg\(idx) skipped: the dead producer was "
+                + "already replaced or the session stopped during the backoff",
+                category: .session)
+            return
+        }
+        requestRestart(at: idx, authoritative: true)
+    }
+
     /// #377: how long a refusal keeps classifying a read error as metering. The reader's give-up
     /// arm exits within seconds of the last refused status (its own backoff is spent before it
     /// returns), so this only has to cover that gap, not a whole session.
@@ -767,8 +788,9 @@ extension HLSVideoEngine {
                 liveReopenOutputEndSeconds: outputEnd
             )
             newProd.firstSegmentDiscontinuous = true
+            let newEpoch = newProd.epoch
             newProd.onVideoShiftKnown = { [weak self] shiftPts, _, _ in
-                self?.handleLiveTimelineRebase(shiftPts, seamOutputSeconds: outputEnd)
+                self?.handleLiveTimelineRebase(shiftPts, seamOutputSeconds: outputEnd, producerEpoch: newEpoch)
             }
             producer = newProd
             restartLock.unlock()
@@ -1016,7 +1038,7 @@ extension HLSVideoEngine {
     }
 
     /// NSLock unavailable from async contexts; this synchronous helper wraps the check.
-    private func currentProducerIs(_ p: HLSSegmentProducer) -> Bool {
+    private func currentProducerIs(_ p: HLSSegmentProducer?) -> Bool {
         restartLock.lock()
         defer { restartLock.unlock() }
         return producer === p
@@ -1067,8 +1089,9 @@ extension HLSVideoEngine {
             )
             // Fresh connection joins the broadcast at "now"; source clock jumps, so the seam carries #EXT-X-DISCONTINUITY. Shift handoff deferred to seam to avoid jumping the host clock while pre-loss content is on screen.
             newProd.firstSegmentDiscontinuous = true
+            let newEpoch = newProd.epoch
             newProd.onVideoShiftKnown = { [weak self] shiftPts, _, _ in
-                self?.handleLiveTimelineRebase(shiftPts, seamOutputSeconds: outputEnd)
+                self?.handleLiveTimelineRebase(shiftPts, seamOutputSeconds: outputEnd, producerEpoch: newEpoch)
             }
             producer = newProd
             // #199: the new demuxer reads from the factory-vended reader; take ownership so stop()
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine.swift b/Sources/AetherEngine/Video/HLSVideoEngine.swift
index fc014c519..3411bf6b7 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine.swift
@@ -86,7 +86,15 @@ public final class HLSVideoEngine: @unchecked Sendable {
     /// restart counters, and a fresh instance starts them at zero.
     var demuxer: Demuxer?
     var cache: SegmentCache?   // internal for the teardown-partial witness test
-    var producer: HLSSegmentProducer?
+    var producer: HLSSegmentProducer? {
+        didSet {
+            // Audit SEG-104: a gate open is checked against this under `anchorShiftLock`, atomically
+            // with what it records, so a producer that was replaced cannot record after.
+            anchorShiftLock.lock()
+            installedProducerEpoch = producer?.epoch
+            anchorShiftLock.unlock()
+        }
+    }
     private var server: HLSLocalServer?
     var provider: VideoSegmentProvider?
 
@@ -480,7 +488,7 @@ public final class HLSVideoEngine: @unchecked Sendable {
     /// AE#418 round 2 + PR #533: what each epoch left at the index it opened on, both what its first
     /// segment adds to the axis and what all of its bytes carry. See `EpochAxisTable`.
     private let anchorShiftLock = NSLock()
-    private var epochAxisByIndex = EpochAxisTable()
+    private(set) var epochAxisByIndex = EpochAxisTable()   // internal read for the superseded-producer tests
     /// PR #533 round 2: how far AVPlayer's OWN timeline is displaced from the playlist, which is the
     /// quantity every AE#418 rule is about.
     ///
@@ -532,7 +540,9 @@ public final class HLSVideoEngine: @unchecked Sendable {
     /// `play --picture-probe`: `axisErr` 0.000 at offsets of 1, 5 and 9 s), so its distance to its
     /// advertised start is not an axis offset and must not compose into one. Guarded by
     /// `anchorShiftLock`, alongside the table it keeps entries out of.
-    private var recutIndices: Set<Int> = []
+    private var recutMark: RecutMark?
+    /// Epoch of `producer`, mirrored under `anchorShiftLock` (audit SEG-104).
+    private var installedProducerEpoch: UInt64?
     private let shiftLock = NSLock()
     private var _playlistShiftSeconds: Double = 0
 
@@ -2573,6 +2583,7 @@ public final class HLSVideoEngine: @unchecked Sendable {
             segmentBoundaries.append(last.endPts)
         }
 
+        let producerEpoch = nextProducerEpoch()
         let prod = try HLSSegmentProducer(
             demuxer: dem,
             videoStreamIndex: videoStreamIndex,
@@ -2612,7 +2623,7 @@ public final class HLSVideoEngine: @unchecked Sendable {
             // AE#464: read here rather than pushed, so every producer this session builds (seek
             // restart, live reopen, #99 revive) cuts with the offset currently in force.
             audioDelaySeconds: audioDelaySeconds,
-            epoch: nextProducerEpoch()
+            epoch: producerEpoch
         )
         // #240: threaded onto every producer (initial + restart), like the wedge-detector providers
         // below. The side readers read one gate for the whole session, so a restart must not leave
@@ -2625,10 +2636,11 @@ public final class HLSVideoEngine: @unchecked Sendable {
         prod.onVideoShiftKnown = { [weak self] shiftPts, firstItemTfdtPts, normalizationShiftPts in
             self?.handleVideoShiftKnown(
                 shiftPts, firstItemTfdtPts: firstItemTfdtPts,
-                normalizationShiftPts: normalizationShiftPts)
+                normalizationShiftPts: normalizationShiftPts, producerEpoch: producerEpoch)
         }
         prod.onLiveTimelineRebase = { [weak self] shiftPts, seamOutputSeconds in
-            self?.handleLiveTimelineRebase(shiftPts, seamOutputSeconds: seamOutputSeconds)
+            self?.handleLiveTimelineRebase(shiftPts, seamOutputSeconds: seamOutputSeconds,
+                                           producerEpoch: producerEpoch)
         }
         prod.onPumpFinished = { [weak self, weak prod] reason in
             guard let self, let prod else { return }
@@ -2715,12 +2727,13 @@ public final class HLSVideoEngine: @unchecked Sendable {
     static let maxLiveMuxerRebuildCycles = 3
 
     private func handleVideoShiftKnown(_ shiftPts: Int64, firstItemTfdtPts: Int64,
-                                      normalizationShiftPts: Int64) {
+                                      normalizationShiftPts: Int64, producerEpoch: UInt64) {
         let seconds = shiftPts == Int64.min ? 0 : Double(shiftPts) * sourceVideoTbSeconds
         let seamItemSeconds = Double(firstItemTfdtPts) * sourceVideoTbSeconds
         // Live rebases the whole timeline at a program boundary and nothing older comes back on
         // screen, so its axis is the epoch's own and it publishes here as it always has.
         guard !isLiveSession else {
+            guard isInstalledProducer(producerEpoch) else { return }
             // Live has no placement model: the epoch's shift IS the axis, so the displacement this
             // session tracks for VOD stays where it is (nothing below reads it on a live session).
             publishPlaylistShift(seconds, seamItemSeconds: seamItemSeconds)
@@ -2731,10 +2744,21 @@ public final class HLSVideoEngine: @unchecked Sendable {
         // epoch AVPlayer never fetches from must not move the clock at all.
         let index = segmentIndexForPlaylistTime(seamItemSeconds)
         anchorShiftLock.lock()
+        // Audit SEG-104: a restart that was replaced while its first read was in flight can still
+        // open its gate. Its epoch describes bytes nobody will store, and recording it would drop
+        // the entries at and above its index.
+        guard installedProducerEpoch == producerEpoch else {
+            anchorShiftLock.unlock()
+            EngineLog.emit(
+                "[HLSVideoEngine] gate open at seg\(index) from a superseded producer, ignored",
+                category: .session)
+            return
+        }
         // AE#412: a re-cut opens below its boundary on purpose, and AVPlayer places what it produces
         // at its own tfdt, so the epoch is worth nothing to the axis. Recording zero still drops the
         // entries at and above it, which is what the rewrite calls for.
-        let isRecut = recutIndices.remove(index) != nil
+        let isRecut = recutMark?.isOpened(byProducerEpoch: producerEpoch, at: index) == true
+        if isRecut { recutMark = nil }
         // PR #533: the run keeps the source-to-item normalization its bytes were written with, even
         // where its opening segment has no placement offset left to carry. Those are the same number
         // only on a source whose timestamps start at zero.
@@ -3507,6 +3531,7 @@ public final class HLSVideoEngine: @unchecked Sendable {
     /// already within reach below the target, or a re-cut whose gate did not open in time.
     func preparedSeekLanding(itemSeconds: Double) -> Double {
         guard !isLiveSession, let provider else { return itemSeconds }
+        dropUnstartedRecut()
         let index = segmentIndexForPlaylistTime(itemSeconds)
         guard let reach = provider.videoReach(at: index) else { return itemSeconds }
         guard let advertised = advertisedStartSeconds(index) else { return itemSeconds }
@@ -3522,22 +3547,15 @@ public final class HLSVideoEngine: @unchecked Sendable {
             + "and no random-access point is within reach below it; re-cutting from the covering one",
             category: .session
         )
-        gateOpenCondition.lock()
-        lastGateOpen = nil
-        gateOpenCondition.unlock()
-        anchorShiftLock.lock()
-        recutIndices.insert(index)
-        anchorShiftLock.unlock()
+        markRecut(at: index)
         // Audit HLS-4: off this task, so the gate wait below bounds the whole re-cut. Inline, an idle
         // coalescer ran the restart here (a 5 s stop wait, a #79 reopen, the demuxer seek) before the
         // wait began, all outside the seek's 8 s landing bound.
         DispatchQueue.global(qos: .userInitiated).async { [weak self] in
             self?.requestRestart(at: index, authoritative: true)
         }
+        // Audit HLS-105: a timeout leaves the mark with the restart, whose gate may open later.
         guard let opened = awaitGateOpen(forIndex: index, timeout: Self.recutGateWaitSeconds) else {
-            anchorShiftLock.lock()
-            recutIndices.remove(index)
-            anchorShiftLock.unlock()
             EngineLog.emit(
                 "[HLSVideoEngine] #412 seg\(index) re-cut did not open a gate within "
                 + "\(String(format: "%.1f", Self.recutGateWaitSeconds))s; seeking on the uncorrected position",
@@ -3557,6 +3575,54 @@ public final class HLSVideoEngine: @unchecked Sendable {
         return itemSeconds
     }
 
+    /// Audit HLS-105: an AE#412 re-cut, owned by the restart that performs it rather than by the seek
+    /// waiting on it. The restart binds its producer's epoch at install, and only that producer's gate
+    /// open is the re-cut; the seek's wait timing out leaves it alone.
+    struct RecutMark: Equatable {
+        let index: Int
+        private(set) var producerEpoch: UInt64?
+
+        init(index: Int) { self.index = index }
+
+        /// The mark that survives a restart installing `producerEpoch` at `restartIndex`: bound when
+        /// it is the marked index, kept while the marked restart has yet to run, dropped once the
+        /// restart it was bound to has been replaced by one elsewhere.
+        func installing(producerEpoch epoch: UInt64, at restartIndex: Int) -> RecutMark? {
+            guard restartIndex == index else { return producerEpoch == nil ? self : nil }
+            var bound = self
+            bound.producerEpoch = epoch
+            return bound
+        }
+
+        func isOpened(byProducerEpoch epoch: UInt64, at gateIndex: Int) -> Bool {
+            producerEpoch == epoch && gateIndex == index
+        }
+    }
+
+    func markRecut(at index: Int) {
+        gateOpenCondition.lock()
+        lastGateOpen = nil
+        gateOpenCondition.unlock()
+        anchorShiftLock.lock()
+        recutMark = RecutMark(index: index)
+        anchorShiftLock.unlock()
+    }
+
+    /// A newer seek supersedes a re-cut whose restart never installed a producer (dropped with the
+    /// coalescer's superseded slot, or failed), so a later unrelated restart at that index does not
+    /// inherit the mark.
+    private func dropUnstartedRecut() {
+        anchorShiftLock.lock()
+        if recutMark?.producerEpoch == nil { recutMark = nil }
+        anchorShiftLock.unlock()
+    }
+
+    private func isInstalledProducer(_ epoch: UInt64) -> Bool {
+        anchorShiftLock.lock()
+        defer { anchorShiftLock.unlock() }
+        return installedProducerEpoch == epoch
+    }
+
     /// AE#412 pure decision: whether the segment a cold seek lands in has to be re-cut before the
     /// seek goes out.
     ///
@@ -3654,7 +3720,8 @@ public final class HLSVideoEngine: @unchecked Sendable {
     /// AVPlayer renders at ~buffer+holdback behind the producer edge, so the host must keep the OLD shift
     /// until playback crosses `seamOutputSeconds`. Internal `playlistShiftSeconds` tracks the edge immediately.
     /// #368: sequential chunk-seam rebases arrive here too, deliberately; same deferred-shift contract.
-    func handleLiveTimelineRebase(_ shiftPts: Int64, seamOutputSeconds: Double) {
+    func handleLiveTimelineRebase(_ shiftPts: Int64, seamOutputSeconds: Double, producerEpoch: UInt64) {
+        guard isInstalledProducer(producerEpoch) else { return }
         let seconds = shiftPts == Int64.min ? 0 : Double(shiftPts) * sourceVideoTbSeconds
         setPlaylistShiftSeconds(seconds)
         onPlaylistShiftRebased?(seconds, seamOutputSeconds)
@@ -4032,6 +4099,9 @@ public final class HLSVideoEngine: @unchecked Sendable {
         do {
             let newProd = try makeProducer(baseIndex: idx)
             producer = newProd
+            anchorShiftLock.lock()
+            recutMark = recutMark?.installing(producerEpoch: newProd.epoch, at: idx)
+            anchorShiftLock.unlock()
             restartLock.unlock()
             newProd.start()
         } catch {
diff --git a/Tests/AetherEngineTests/SupersededProducerReportTests.swift b/Tests/AetherEngineTests/SupersededProducerReportTests.swift
new file mode 100644
index 000000000..8abe27041
--- /dev/null
+++ b/Tests/AetherEngineTests/SupersededProducerReportTests.swift
@@ -0,0 +1,180 @@
+import Foundation
+import Testing
+import AetherLibavcodec
+import AetherLibavutil
+@testable import AetherEngine
+
+/// Audit HLS-104, HLS-105, SEG-104 (B): a producer the session has already replaced, or an action
+/// scheduled on its behalf, used to act on whatever producer was current by then. A gate open from a
+/// superseded restart rewrote the epoch table, the delayed #377 revive re-anchored the producer that
+/// had replaced the dead one, and a re-cut lost its mark to the seek's 2 s wait while the restart it
+/// marked was still running.
+@Suite("A superseded producer leaves the current session alone", .serialized)
+struct SupersededProducerReportTests {
+
+    private final class Session {
+        let engine: HLSVideoEngine
+        private var codecpar: UnsafeMutablePointer<AVCodecParameters>?
+        private let cache = SegmentCache(forwardWindow: 20, backwardWindow: 20)
+
+        init() throws {
+            engine = HLSVideoEngine(url: URL(fileURLWithPath: "/nonexistent/superseded.mkv"),
+                                    dvModeAvailable: false)
+            codecpar = try #require(avcodec_parameters_alloc())
+            codecpar!.pointee.codec_id = AV_CODEC_ID_H264
+            codecpar!.pointee.codec_type = AVMEDIA_TYPE_VIDEO
+            let plan = (0..<10).map { i in
+                HLSVideoEngine.Segment(startPts: Int64(i) * 4000, endPts: Int64(i + 1) * 4000,
+                                       startSeconds: Double(i) * 4.0, durationSeconds: 4.0)
+            }
+            engine.segmentPlan = plan
+            engine.cache = cache
+            engine.demuxer = Demuxer()
+            engine.savedVideoConfig = .init(codecpar: UnsafePointer(codecpar!),
+                                            timeBase: AVRational(num: 1, den: 1000),
+                                            codecTagOverride: nil)
+            engine.provider = VideoSegmentProvider(
+                cache: cache, segments: plan, codecsString: "avc1.42C00A", supplementalCodecs: nil,
+                resolution: (16, 16), videoRange: .sdr, frameRate: 2, hdcpLevel: nil,
+                sourceBitrate: 100_000)
+        }
+
+        deinit {
+            engine.stop()
+            avcodec_parameters_free(&codecpar)
+        }
+
+        /// A stored segment that opens on no random-access point, so a seek into it has to re-cut.
+        func storeWithoutSyncSample(_ index: Int) throws {
+            let staging = cache.sessionDir.appendingPathComponent("staging-\(index).tmp")
+            try Data(repeating: 0xAA, count: 64).write(to: staging)
+            cache.adopt(index: index, stagingPath: staging, byteCount: 64, videoReach: SegmentCache.VideoReach.none)
+        }
+
+        /// The producer reports its gate open, as the pump does: the item-axis tfdt of its first frame
+        /// is the start of the segment it was anchored at (plan time base 1/1000).
+        func openGate(of producer: HLSSegmentProducer, at index: Int, backoffMs: Int64 = 3000) {
+            producer.onVideoShiftKnown?(backoffMs, Int64(index) * 4000, 0)
+        }
+    }
+
+    private final class Restarts: @unchecked Sendable {
+        private let lock = NSLock()
+        private var _began = 0
+        func note(_ began: Bool) { if began { lock.withLock { _began += 1 } } }
+        var began: Int { lock.withLock { _began } }
+    }
+
+    // MARK: - The gate open of a replaced producer (SEG-104 B)
+
+    @Test("a gate open from a producer the session replaced records nothing")
+    func supersededGateOpenRecordsNothing() throws {
+        let session = try Session()
+        let engine = session.engine
+        let stale = try engine.makeProducer(baseIndex: 2)
+        engine.producer = stale
+        engine.producer = nil   // performRestart tears it down before building the next one
+
+        session.openGate(of: stale, at: 2)
+        #expect(engine.epochAxisByIndex.opening(at: 2) == nil,
+                "the stale epoch dropped the table at and above its own index")
+
+        let current = try engine.makeProducer(baseIndex: 5)
+        engine.producer = current
+        session.openGate(of: stale, at: 2)
+        session.openGate(of: current, at: 5)
+        #expect(engine.epochAxisByIndex.opening(at: 2) == nil)
+        #expect(engine.epochAxisByIndex.opening(at: 5) != nil, "the installed producer's gate still records")
+    }
+
+    // MARK: - The re-cut mark (HLS-105)
+
+    @Test("a re-cut whose gate opens after the seek stopped waiting is still recorded as a re-cut",
+          .timeLimit(.minutes(1)))
+    func lateRecutGateKeepsItsMark() async throws {
+        let session = try Session()
+        let engine = session.engine
+        for i in 0...4 { try session.storeWithoutSyncSample(i) }
+
+        // Nothing here ever opens a gate on its own, so the seek's wait runs out.
+        let landing = await Task.detached { engine.preparedSeekLanding(itemSeconds: 14) }.value
+        #expect(landing == 14)
+        try await waitFor { engine.producer?.anchoredBaseIndex == 3 }
+        let recut = try #require(engine.producer)
+
+        session.openGate(of: recut, at: 3)
+        #expect(engine.epochAxisByIndex.opening(at: 3)?.isRecut == true,
+                "the late gate open composed the re-cut's backoff into the axis")
+    }
+
+    @Test("a mark belongs to the restart it asked for, not to whatever restart runs next")
+    func markBindsOnlyItsOwnRestart() throws {
+        let session = try Session()
+        let engine = session.engine
+
+        engine.markRecut(at: 3)
+        engine.requestRestart(at: 6, authoritative: true)
+        let other = try #require(engine.producer)
+        session.openGate(of: other, at: 6)
+        #expect(engine.epochAxisByIndex.opening(at: 6)?.isRecut == false)
+
+        engine.requestRestart(at: 3, authoritative: true)
+        let recut = try #require(engine.producer)
+        engine.requestRestart(at: 7, authoritative: true)   // supersedes the re-cut before its gate opened
+        let next = try #require(engine.producer)
+        session.openGate(of: recut, at: 3)
+        session.openGate(of: next, at: 7)
+        #expect(engine.epochAxisByIndex.opening(at: 3) == nil)
+        #expect(engine.epochAxisByIndex.opening(at: 7)?.isRecut == false)
+    }
+
+    @Test("the mark's lifecycle: bound by its own restart, kept past others, dropped once superseded")
+    func recutMarkLifecycle() {
+        let mark = HLSVideoEngine.RecutMark(index: 3)
+        #expect(!mark.isOpened(byProducerEpoch: 7, at: 3), "unbound, no gate can claim it")
+
+        let pending = mark.installing(producerEpoch: 5, at: 6)
+        #expect(pending == mark, "a restart elsewhere ran first; the marked one is still to come")
+
+        let bound = pending?.installing(producerEpoch: 7, at: 3)
+        #expect(bound?.isOpened(byProducerEpoch: 7, at: 3) == true)
+        #expect(bound?.isOpened(byProducerEpoch: 5, at: 3) == false)
+        #expect(bound?.installing(producerEpoch: 8, at: 3)?.isOpened(byProducerEpoch: 8, at: 3) == true,
+                "a second restart at the same index re-cuts the same landing")
+        #expect(bound?.installing(producerEpoch: 9, at: 6) == nil)
+    }
+
+    // MARK: - The delayed #377 revive (HLS-104)
+
+    @Test("the metered revive is owed only while its session and its dead producer are both still current")
+    func meteredReviveOwedMatrix() {
+        #expect(HLSVideoEngine.meteredReviveStillOwed(sessionUnchanged: true, deadProducerInstalled: true))
+        #expect(!HLSVideoEngine.meteredReviveStillOwed(sessionUnchanged: true, deadProducerInstalled: false))
+        #expect(!HLSVideoEngine.meteredReviveStillOwed(sessionUnchanged: false, deadProducerInstalled: true))
+        #expect(!HLSVideoEngine.meteredReviveStillOwed(sessionUnchanged: false, deadProducerInstalled: false))
+    }
+
+    @Test("a revive that woke after another restart replaced its dead producer restarts nothing",
+          .timeLimit(.minutes(1)))
+    func meteredReviveYieldsToAReplacement() async throws {
+        let session = try Session()
+        let engine = session.engine
+        let restarts = Restarts()
+        engine.onSeekStateChanged = { began, _ in restarts.note(began) }
+        let dead = try engine.makeProducer(baseIndex: 2)
+        engine.producer = dead
+        dead.start()
+        try await waitFor { dead.didFinish }
+        let epoch = engine.sessionEpochSnapshot()
+
+        // A segment-driven restart during the backoff already put a working producer in.
+        engine.producer = try engine.makeProducer(baseIndex: 6)
+        engine.fireMeteredRevive(at: 2, deadProducer: dead, sessionEpoch: epoch)
+        #expect(restarts.began == 0, "the revive re-anchored the producer that replaced the dead one")
+
+        // Its own dead producer still in place, it runs.
+        engine.producer = dead
+        engine.fireMeteredRevive(at: 2, deadProducer: dead, sessionEpoch: epoch)
+        #expect(restarts.began == 1)
+    }
+}

From 4d8157b2f06458dca09d3e5f1dcf819b674a9cbb Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 06:27:07 +0200
Subject: [PATCH 157/359] fix(disc): cap a DVD subpicture unit at 1 MiB and
 join it in place (audit NET-104, DMX-106)

A first fragment starting `00 00` takes its size from the next 32 bits, and
`DVDSubpictureAssembler` reserved all of it, up to 4 GiB, then appended every later fragment of
the stream until that size was reached. FFmpeg's `dvdsub_parser` would bound this, but the #651
declared stream bypasses it. `Demuxer.readPacketLocked` also copied the assembler out of its
dictionary before mutating it, so each fragment's append copied the partial unit at full capacity.

The assembler now drops a unit stated above 1 MiB (a DVD SPU is at most 53,220 bytes; the cap
keeps the HD-DVD units `dvdsubdec` decodes and the 70 KB unit the #651 tests pin) and reserves at
most 64 KiB up front. The demuxer mutates the assembler in place and sizes the joined packet with
`Int32(exactly:)`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 Sources/AetherEngine/Demuxer/Demuxer.swift    | 10 +++---
 .../Disc/DVDSubpictureAssembler.swift         | 12 +++++--
 .../Issue651DeclaredSubpictureTests.swift     | 36 +++++++++++++++++++
 3 files changed, 52 insertions(+), 6 deletions(-)

diff --git a/Sources/AetherEngine/Demuxer/Demuxer.swift b/Sources/AetherEngine/Demuxer/Demuxer.swift
index 776b61c89..d8e4d8963 100644
--- a/Sources/AetherEngine/Demuxer/Demuxer.swift
+++ b/Sources/AetherEngine/Demuxer/Demuxer.swift
@@ -1684,14 +1684,15 @@ public final class Demuxer: @unchecked Sendable {
             guard let read = try readDemuxedPacketLocked() else { return nil }
             var packet: UnsafeMutablePointer<AVPacket>? = read
             let index = read.pointee.stream_index
-            guard var assembler = subpictureAssemblers[index] else { return read }
+            guard subpictureAssemblers[index] != nil else { return read }
             let timing = DVDSubpictureAssembler.Timing(
                 pts: read.pointee.pts, dts: read.pointee.dts,
                 pos: read.pointee.pos, duration: read.pointee.duration)
-            let unit = assembler.ingest(
+            // In place (audit DMX-106): a copied-out assembler shares the dictionary's buffer, so
+            // every fragment's append copied the whole partial unit.
+            let unit = subpictureAssemblers[index]?.ingest(
                 UnsafeRawBufferPointer(start: read.pointee.data, count: Int(max(0, read.pointee.size))),
                 timing: timing)
-            subpictureAssemblers[index] = assembler
             guard let unit else {
                 trackedPacketFree(&packet)
                 continue
@@ -1700,7 +1701,8 @@ public final class Demuxer: @unchecked Sendable {
             guard let joined = trackedPacketAlloc() else { trackedPacketFree(&packet); return nil }
             var out: UnsafeMutablePointer<AVPacket>? = joined
             // `av_new_packet` resets every prop, so the copy comes after it.
-            guard av_new_packet(joined, Int32(unit.data.count)) >= 0,
+            guard let joinedSize = Int32(exactly: unit.data.count),
+                  av_new_packet(joined, joinedSize) >= 0,
                   av_packet_copy_props(joined, read) >= 0 else {
                 trackedPacketFree(&out)
                 trackedPacketFree(&packet)
diff --git a/Sources/AetherEngine/Disc/DVDSubpictureAssembler.swift b/Sources/AetherEngine/Disc/DVDSubpictureAssembler.swift
index 6175d3285..c70225745 100644
--- a/Sources/AetherEngine/Disc/DVDSubpictureAssembler.swift
+++ b/Sources/AetherEngine/Disc/DVDSubpictureAssembler.swift
@@ -30,6 +30,11 @@ struct DVDSubpictureAssembler {
 
     var isAssembling: Bool { timing != nil }
 
+    var reservedCapacity: Int { buffer.capacity }
+
+    static let maxUnitBytes = 1 << 20
+    static let initialReservationBytes = 64 * 1024
+
     /// Feed one demuxed fragment. Returns the unit once it is complete, nil while it is not (or when
     /// the fragment was dropped).
     mutating func ingest(_ fragment: UnsafeRawBufferPointer, timing fragmentTiming: Timing) -> Unit? {
@@ -43,11 +48,14 @@ struct DVDSubpictureAssembler {
             } else if bytes.count < 6 {
                 return nil
             }
-            guard size > 0 else { return nil }
+            // Audit NET-104: the 32-bit form stated up to 4 GiB, all of it reserved up front, and the
+            // unit then swallowed every later fragment of the stream. A DVD SPU is at most 53,220
+            // bytes; 1 MiB leaves room for the HD-DVD units `dvdsubdec` decodes.
+            guard size > 0, size <= Self.maxUnitBytes else { return nil }
             expected = size
             timing = fragmentTiming
             buffer.removeAll(keepingCapacity: true)
-            buffer.reserveCapacity(size)
+            buffer.reserveCapacity(min(size, Self.initialReservationBytes))
         }
         guard buffer.count + fragment.count <= expected, let unitTiming = timing else {
             reset()
diff --git a/Tests/AetherEngineTests/Issue651DeclaredSubpictureTests.swift b/Tests/AetherEngineTests/Issue651DeclaredSubpictureTests.swift
index d91a6c399..c7d8c4b3a 100644
--- a/Tests/AetherEngineTests/Issue651DeclaredSubpictureTests.swift
+++ b/Tests/AetherEngineTests/Issue651DeclaredSubpictureTests.swift
@@ -77,6 +77,42 @@ struct Issue651DeclaredSubpictureTests {
         #expect(!a.isAssembling)
     }
 
+    // Audit NET-104 / DMX-106: the 32-bit form reserved whatever it stated, up to 4 GiB, and then
+    // swallowed every later fragment of the stream.
+    @Test("a 32-bit size past 1 MiB drops the unit without reserving it")
+    func hostileThirtyTwoBitSizeDrops() {
+        var a = DVDSubpictureAssembler()
+        let bytes: [UInt8] = [0, 0, 0xFF, 0xFF, 0xFF, 0xFF] + [UInt8](repeating: 0xAB, count: 2000)
+        #expect(ingest(&a, bytes, 1) == nil)
+        #expect(!a.isAssembling)
+        #expect(a.reservedCapacity < 128 * 1024)
+        #expect(ingest(&a, unit(40), 2)?.timing.pts == 2)
+    }
+
+    @Test("a unit of exactly 1 MiB still joins, reserving about 64 KiB up front")
+    func megabyteUnitJoins() {
+        var a = DVDSubpictureAssembler()
+        let size = 1 << 20
+        var bytes: [UInt8] = [0, 0, 0x00, 0x10, 0x00, 0x00]
+        bytes += [UInt8](repeating: 0x5A, count: size - bytes.count)
+        #expect(ingest(&a, Array(bytes[0..<2048]), 1) == nil)
+        // The allocator rounds a 64 KiB request up; the point is that 1 MiB is not reserved.
+        #expect(a.reservedCapacity < 128 * 1024)
+        #expect(ingest(&a, Array(bytes[2048...]), Int64.min)?.data.count == size)
+    }
+
+    @Test("a 60 KB unit across 30 fragments yields one unit")
+    func sixtyKilobytesInThirtyFragments() {
+        var a = DVDSubpictureAssembler()
+        let bytes = unit(60_000)
+        var units: [DVDSubpictureAssembler.Unit] = []
+        for k in 0..<30 {
+            let fragment = Array(bytes[(k * 2000)..<((k + 1) * 2000)])
+            if let joined = ingest(&a, fragment, k == 0 ? 5 : Int64.min) { units.append(joined) }
+        }
+        #expect(units == [.init(data: bytes, timing: timing(5))])
+    }
+
     // MARK: - IFO
 
     /// A VTS IFO without a PGCIT declaring `count` subpictures, the first `withLanguage` of them with

From 9440d09ef1e971a3f252846b313ff1de11bbaf12 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 06:29:39 +0200
Subject: [PATCH 158/359] fix(producer): cap the pre-gate audio buffer by
 entries as well as bytes (audit SEG-102)

While the video gate waits, every selected-audio packet is buffered with its own `AVPacket`, and
the only bound was 8 MiB of payload. A zero-size packet was charged nothing and a 1-byte one one
byte, so a crafted Matroska of EBML-laced 1-byte frames behind a video track that never flags a
keyframe pinned about 8.4 million packets (1.3 to 1.5 GB of heap) while the VOD gate waited
without a time bound.

`shouldBufferPregateAudio` gains a defaulted `bufferedCount` / `maxEntries` (65,536) and the
call site passes the buffer's count. The cap sits above what the byte cap admits for AAC or AC-3
and still covers about 22 minutes of 20 ms Opus frames.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../Video/HLSSegmentProducer.swift             | 18 ++++++++++++++----
 .../PregateAudioBufferTests.swift              | 17 +++++++++++++++++
 2 files changed, 31 insertions(+), 4 deletions(-)

diff --git a/Sources/AetherEngine/Video/HLSSegmentProducer.swift b/Sources/AetherEngine/Video/HLSSegmentProducer.swift
index 7eca8b7c4..0dd3f788f 100644
--- a/Sources/AetherEngine/Video/HLSSegmentProducer.swift
+++ b/Sources/AetherEngine/Video/HLSSegmentProducer.swift
@@ -2829,12 +2829,20 @@ final class HLSSegmentProducer: @unchecked Sendable {
         isLive: Bool,
         bufferedBytes: Int,
         packetSize: Int,
-        capBytes: Int
+        capBytes: Int,
+        bufferedCount: Int = 0,
+        maxEntries: Int = HLSSegmentProducer.maxPregateAudioBufferEntries
     ) -> Bool {
         guard isAudioPkt, audioWaitForVideo, isHeadOfStream || !isLive else { return false }
-        return bufferedBytes + max(packetSize, 0) <= capBytes
+        return bufferedCount < maxEntries && bufferedBytes + max(packetSize, 0) <= capBytes
     }
 
+    /// Audit SEG-102: the byte cap charges payload only, and each entry costs an `AVPacket`, a buffer
+    /// ref and an array slot besides, so 1-byte laced packets pinned about 1.4 GB under the 8 MiB cap
+    /// while the VOD gate waited unbounded. Above what the byte cap admits for AAC or AC-3, and still
+    /// about 22 minutes of 20 ms Opus frames.
+    static let maxPregateAudioBufferEntries = 65_536
+
     /// Overwrite packed side-audio timestamps with the synthesized program clock.
     /// KNOWN LIMITATION: free-running clock does NOT follow a live video rebase; A/V sync is lost from that boundary on.
     private func stampPackedSideAudio(_ packet: UnsafeMutablePointer<AVPacket>) {
@@ -3182,7 +3190,8 @@ final class HLSSegmentProducer: @unchecked Sendable {
                     isLive: isLive,
                     bufferedBytes: pregateAudioBufferBytes,
                     packetSize: Int(packet.pointee.size),
-                    capBytes: Self.maxPregateAudioBufferBytes
+                    capBytes: Self.maxPregateAudioBufferBytes,
+                    bufferedCount: pregateAudioBuffer.count
                 ) {
                     pregateAudioBuffer.append((packet, origin))
                     pregateAudioBufferBytes += Int(packet.pointee.size)
@@ -3194,7 +3203,8 @@ final class HLSSegmentProducer: @unchecked Sendable {
                     pregateAudioOverflowLogged = true
                     EngineLog.emit(
                         "[HLSSegmentProducer] pre-gate audio buffer hit the "
-                        + "\(Self.maxPregateAudioBufferBytes)-byte cap; dropping further leading audio "
+                        + "\(Self.maxPregateAudioBufferBytes)-byte / \(Self.maxPregateAudioBufferEntries)-entry "
+                        + "cap; dropping further leading audio "
                         + "(wide interleave beyond cap)",
                         category: .session
                     )
diff --git a/Tests/AetherEngineTests/PregateAudioBufferTests.swift b/Tests/AetherEngineTests/PregateAudioBufferTests.swift
index e9f896004..96faf7570 100644
--- a/Tests/AetherEngineTests/PregateAudioBufferTests.swift
+++ b/Tests/AetherEngineTests/PregateAudioBufferTests.swift
@@ -74,4 +74,21 @@ struct PregateAudioBufferTests {
             isAudioPkt: true, audioWaitForVideo: true, isHeadOfStream: false, isLive: false,
             bufferedBytes: cap - 1024, packetSize: 1025, capBytes: cap) == false)
     }
+
+    // Audit SEG-102: the byte cap counts payload only, so 1-byte (or empty) laced packets let the
+    // buffer pin about 8.4 million AVPackets, 1.4 GB of heap, while the VOD gate waits unbounded.
+    @Test("Tiny packets are refused once the entry cap is reached, however few bytes they carry")
+    func entryCapBindsTinyPackets() {
+        let entries = HLSSegmentProducer.maxPregateAudioBufferEntries
+        #expect(entries == 65_536)
+        #expect(HLSSegmentProducer.shouldBufferPregateAudio(
+            isAudioPkt: true, audioWaitForVideo: true, isHeadOfStream: true, isLive: false,
+            bufferedBytes: entries - 1, packetSize: 1, capBytes: cap, bufferedCount: entries - 1) == true)
+        #expect(HLSSegmentProducer.shouldBufferPregateAudio(
+            isAudioPkt: true, audioWaitForVideo: true, isHeadOfStream: true, isLive: false,
+            bufferedBytes: entries, packetSize: 1, capBytes: cap, bufferedCount: entries) == false)
+        #expect(HLSSegmentProducer.shouldBufferPregateAudio(
+            isAudioPkt: true, audioWaitForVideo: true, isHeadOfStream: false, isLive: false,
+            bufferedBytes: 0, packetSize: 0, capBytes: cap, bufferedCount: entries) == false)
+    }
 }

From c71bdc1e10103f15c2fc951d64c92221961ac5b3 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 06:30:47 +0200
Subject: [PATCH 159/359] fix(segments): a stopped pump drops the read it had
 in flight (audit SEG-104)

The pump checked shouldStop only at the top of its loop, before it read.
A read already parked when the session stopped the producer (the #79
restart aborts it with markClosed, which Matroska, MPEG-TS and fMP4
report as end of file) came back as source EOF: the pump exited with
.eof, flushed the bridge and adopted its half-written segment into the
shared cache under the full index, where a later backward seek hit a
short segment.

The pump now re-checks right after every source read (after both reads
of the side-audio merge) and frees the packet, and an .eof exit with a
stop pending is remapped to .stopRequested. Making the closed demuxer
itself refuse to report EOF is left to the demuxer package.

Test: a Matroska pump parked mid-file, stopped, and then answered with
end of file exits as a stop and adopts nothing (it exited .eof and
cached the partial segment before).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../Video/HLSSegmentProducer.swift            |  13 ++
 .../StoppedPumpInFlightReadTests.swift        | 116 ++++++++++++++++++
 2 files changed, 129 insertions(+)
 create mode 100644 Tests/AetherEngineTests/StoppedPumpInFlightReadTests.swift

diff --git a/Sources/AetherEngine/Video/HLSSegmentProducer.swift b/Sources/AetherEngine/Video/HLSSegmentProducer.swift
index e0f37d8a3..53b88e3ed 100644
--- a/Sources/AetherEngine/Video/HLSSegmentProducer.swift
+++ b/Sources/AetherEngine/Video/HLSSegmentProducer.swift
@@ -3011,6 +3011,14 @@ final class HLSSegmentProducer: @unchecked Sendable {
                     guard let read = try readNextSourcePacket() else {
                         break readLoop
                     }
+                    // Audit SEG-104: a stop that landed while this read was parked means the session
+                    // has already replaced this pump, so what the read returned is not its to act on.
+                    if checkShouldStop() {
+                        var stale: UnsafeMutablePointer<AVPacket>? = read.packet
+                        trackedPacketFree(&stale)
+                        exitReason = .stopRequested
+                        break readLoop
+                    }
                     packet = read.packet
                     origin = read.origin
                     packetsRead += 1
@@ -4177,6 +4185,11 @@ final class HLSSegmentProducer: @unchecked Sendable {
             if case .stopRequested = exitReason {} else { exitReason = .segmentStall }
         }
 
+        // Audit SEG-104: the abort of a parked read surfaces as end of file, which is not the source's.
+        if case .eof = exitReason, checkShouldStop() {
+            exitReason = .stopRequested
+        }
+
         // muxerFailed from a backpressure break is a wedge (host re-anchors) or a stop (teardown), not a real failure.
         if case .muxerFailed = exitReason {
             stateLock.lock()
diff --git a/Tests/AetherEngineTests/StoppedPumpInFlightReadTests.swift b/Tests/AetherEngineTests/StoppedPumpInFlightReadTests.swift
new file mode 100644
index 000000000..b001b8c1e
--- /dev/null
+++ b/Tests/AetherEngineTests/StoppedPumpInFlightReadTests.swift
@@ -0,0 +1,116 @@
+import Foundation
+import Testing
+@testable import AetherEngine
+
+/// Audit SEG-104 (A): the pump checked for a stop only before it read. A read already in flight when
+/// the session stopped the producer (the #79 restart aborts it with `markClosed`, which Matroska, TS
+/// and fMP4 report as end of file) came back as source EOF, and the abandoned pump adopted its
+/// half-written segment into the cache under the full index, where a later backward seek hits it.
+@Suite("A stopped pump does not act on its in-flight read", .serialized)
+struct StoppedPumpInFlightReadTests {
+
+    /// Serves the fixture a few bytes at a time and, once armed, parks the read that reaches
+    /// `blockAt` until released, then answers it with end of file.
+    private final class ParkingReader: IOReader, @unchecked Sendable {
+        private let bytes: Data
+        private let condition = NSCondition()
+        private var position = 0
+        private var blockAt: Int?
+        private var parked = false
+        private var released = false
+
+        init(_ bytes: Data) { self.bytes = bytes }
+
+        func arm(blockAt offset: Int) { condition.withLock { blockAt = offset } }
+        var isParked: Bool { condition.withLock { parked } }
+        func release() {
+            condition.lock()
+            released = true
+            condition.broadcast()
+            condition.unlock()
+        }
+
+        func read(_ buffer: UnsafeMutablePointer<UInt8>?, size: Int32) -> Int32 {
+            guard let buffer, size > 0 else { return -1 }
+            condition.lock()
+            defer { condition.unlock() }
+            if let blockAt, position >= blockAt {
+                parked = true
+                while !released { condition.wait() }
+                return 0
+            }
+            var n = min(Int(size), 64, bytes.count - position)
+            if let blockAt { n = min(n, blockAt - position) }
+            guard n > 0 else { return 0 }
+            bytes.withUnsafeBytes { raw in _ = memcpy(buffer, raw.baseAddress! + position, n) }
+            position += n
+            return Int32(n)
+        }
+
+        func seek(offset: Int64, whence: Int32) -> Int64 {
+            condition.withLock {
+                switch whence {
+                case 65536: return Int64(bytes.count)
+                case SEEK_SET: position = Int(max(0, min(offset, Int64(bytes.count))))
+                case SEEK_CUR: position = max(0, min(position + Int(offset), bytes.count))
+                case SEEK_END: position = max(0, min(bytes.count + Int(offset), bytes.count))
+                default: return -1
+                }
+                return Int64(position)
+            }
+        }
+
+        func close() {}
+        var discImageProbeEnabled: Bool { false }
+    }
+
+    private final class Exit: @unchecked Sendable {
+        private let lock = NSLock()
+        private var _reason: HLSSegmentProducer.PumpExitReason?
+        func set(_ r: HLSSegmentProducer.PumpExitReason) { lock.withLock { _reason = r } }
+        var reason: HLSSegmentProducer.PumpExitReason? { lock.withLock { _reason } }
+    }
+
+    /// Start of the SimpleBlock element carrying the 7.2 s frame of the Issue234 fixture (15 s of
+    /// H.264 at 5 fps in Matroska): past everything the open's stream probe reads, and on an element
+    /// boundary, so the parked read comes back as a clean end of file rather than a torn element.
+    private static let parkOffset = 2237
+
+    @Test("a read that returns end of file after stop() exits as a stop and adopts nothing",
+          .timeLimit(.minutes(1)))
+    func eofAfterStopAdoptsNothing() async throws {
+        let data = try #require(Data(base64Encoded: Issue234SideReaderSeekAnchorTests.fixtureBase64,
+                                     options: .ignoreUnknownCharacters))
+        let reader = ParkingReader(data)
+        let demuxer = Demuxer()
+        try demuxer.open(reader: reader, formatHint: "matroska")
+        defer { demuxer.close() }
+        reader.arm(blockAt: Self.parkOffset)
+
+        let videoIndex = demuxer.videoStreamIndex
+        let stream = try #require(demuxer.stream(at: videoIndex))
+        let cache = SegmentCache(forwardWindow: 4, backwardWindow: 4)
+        defer { cache.close() }
+        let producer = try HLSSegmentProducer(
+            demuxer: demuxer, videoStreamIndex: videoIndex,
+            video: .init(codecpar: UnsafePointer(stream.pointee.codecpar),
+                         timeBase: stream.pointee.time_base, codecTagOverride: nil),
+            cache: cache, videoFallbackDurationPts: 200, desiredFirstVideoTfdtPts: 0,
+            segmentBoundaries: [0, 15_000])
+        let exit = Exit()
+        producer.onPumpFinished = { exit.set($0) }
+        producer.start()
+
+        try await waitFor { reader.isParked }
+        #expect(producer.packetsWrittenCount > 0, "the segment in flight has to be partly written")
+        producer.stop()
+        reader.release()
+        try await waitFor { exit.reason != nil }
+
+        let reason = try #require(exit.reason)
+        var exitedAsStop = false
+        if case .stopRequested = reason { exitedAsStop = true }
+        #expect(exitedAsStop, "a stopped pump exited as \(reason)")
+        #expect(cache.count == 0, "the abandoned pump adopted its partial segment")
+    }
+}

From f609a544f99389810bff0f7db68bceb5110842e3 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 06:31:21 +0200
Subject: [PATCH 160/359] fix(core): a callback from an ended session no longer
 reaches its successor (audit LIF-103, Vcore-101, Vcore-102)

Session callbacks hop onto the main actor, and a hop that landed after
the session ended acted on whatever owned the engine by then. The item
death escalation queued behind a `stop()` spent the budget, sent an
escalation event and flipped the stopped engine to `.error` through its
rebuild's `sessionNotReloadable`; a load in that turn was rebuilt on the
software path with the old failure. The HLS callbacks (shift, seek state,
network phase, consumer re-engage, rebase, HDR10+) and the software and
audio network-phase sinks wrote a torn-down session's state into the next.

One generation-stamped hop (`hop(for:)`, `loadGeneration` is the session's
identity on every path) now carries all of them, the escalation and the
master fallback take the generation they were raised under, and the
escalation's absorbed-failure decision asks the generation instead of
`state`. A reused native host clears its pending display rejection and
escalation at unload, since `@Published` replayed them into the next
load's sinks.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../AetherEngine/AetherEngine+Loading.swift   | 31 ++++---
 .../AetherEngine+SoftwarePathEscalation.swift | 16 +++-
 Sources/AetherEngine/AetherEngine.swift       | 15 +++-
 .../Native/NativeAVPlayerHost.swift           |  3 +
 .../SoftwarePathEscalationTests.swift         | 11 +--
 .../StaleSessionCallbackTests.swift           | 84 +++++++++++++++++++
 6 files changed, 139 insertions(+), 21 deletions(-)
 create mode 100644 Tests/AetherEngineTests/StaleSessionCallbackTests.swift

diff --git a/Sources/AetherEngine/AetherEngine+Loading.swift b/Sources/AetherEngine/AetherEngine+Loading.swift
index 0314793f0..53dfa3910 100644
--- a/Sources/AetherEngine/AetherEngine+Loading.swift
+++ b/Sources/AetherEngine/AetherEngine+Loading.swift
@@ -859,11 +859,12 @@ extension AetherEngine {
         session.sideReaderLinkGate = sideReaderLinkGate
         // #260: an observer installed before load has to reach this session's producers too.
         session.setNativeVideoFrameTimeObserver(nativeVideoFrameTimeObserver)
+        // Audit Vcore-101: every hop below is dropped once this session has ended (`hop(for:)`).
         session.onFirstHDR10PlusDetected = { [weak self] in
-            Task { @MainActor in self?.handleHDR10PlusDetected() }
+            self?.hop(for: generation) { [weak self] in self?.handleHDR10PlusDetected() }
         }
         session.onPlaylistShiftChanged = { [weak self] seconds, seamItemSeconds in
-            Task { @MainActor in
+            self?.hop(for: generation) { [weak self] in
                 guard let self = self else { return }
                 let prevShift = self.playlistShiftSeconds
                 let delta = seconds - prevShift
@@ -927,7 +928,7 @@ extension AetherEngine {
             }
         }
         session.onSeekStateChanged = { [weak self] inFlight, playlistTime in
-            Task { @MainActor in
+            self?.hop(for: generation) { [weak self] in
                 guard let self = self else { return }
                 // Fold playlist-axis segment time onto the published display axis (#38); the origin keeps a disc
                 // scrub target 0-based like currentTime (0 off disc). nil clears without disturbing the last value.
@@ -943,7 +944,7 @@ extension AetherEngine {
             }
         }
         session.onNetworkPhaseChanged = { [weak self] phase in
-            Task { @MainActor in self?.setReaderNetworkPhase(phase) }
+            self?.hop(for: generation) { [weak self] in self?.setReaderNetworkPhase(phase) }
         }
         // #65: let the producer read AVPlayer's real position off-main when it re-anchors on a backpressure wedge.
         session.currentPlaybackPositionProvider = { [renderedPositionMirror] in renderedPositionMirror.get() }
@@ -966,7 +967,7 @@ extension AetherEngine {
         // pipeline (the effect a manual back-out had). Opens the spurious-pause window too, since
         // the nudge can bounce the transport state.
         session.onConsumerReengageNeeded = { [weak self] position in
-            Task { @MainActor [weak self] in
+            self?.hop(for: generation) { [weak self] in
                 guard let self else { return }
                 self.reengageStalledConsumer(position: position, trigger: "wedge re-anchor")
                 // #93 startup: a loader that died BEFORE the first frame never posts
@@ -993,7 +994,7 @@ extension AetherEngine {
             }
         }
         session.onPlaylistShiftRebased = { [weak self] seconds, seamOutputSeconds in
-            Task { @MainActor in
+            self?.hop(for: generation) { [weak self] in
                 guard let self = self else { return }
                 // Program boundary: producer rebased but AVPlayer is still rendering old program (buffer + holdback). Record the seam so $currentTime resolves the active shift from history, keeping currentTime/sourceTime behind what is on screen. Backward DVR seeks re-apply the pre-seam shift. Seams append in output-timeline order (continuation dts is monotonic).
                 var map = self.presentationAxis
@@ -1061,7 +1062,7 @@ extension AetherEngine {
                     session.giveUpLiveJoinWithoutEntryPoint()
                     return
                 }
-                await self.escalateToSoftwarePath(request)
+                await self.escalateToSoftwarePath(request, expectedGeneration: generation)
             }
         }
         // AE#641: the live bridge decoded nothing, so the served media carries an audio track that
@@ -1691,7 +1692,9 @@ extension AetherEngine {
                             self.publishError(Self.absorbedFailure(request))
                             return
                         }
-                        Task { @MainActor [weak self] in await self?.escalateToSoftwarePath(request) }
+                        self.hop(for: generation) { [weak self] in
+                            await self?.escalateToSoftwarePath(request, expectedGeneration: generation)
+                        }
                         return
                     }
                     EngineLog.emit(
@@ -1709,7 +1712,9 @@ extension AetherEngine {
         host.$pendingDisplayRejection
             .compactMap { $0 }
             .sink { [weak self] rejection in
-                Task { @MainActor [weak self] in self?.fallBackToMediaPlaylist(rejection) }
+                self?.hop(for: generation) { [weak self] in
+                    self?.fallBackToMediaPlaylist(rejection, expectedGeneration: generation)
+                }
             }
             .store(in: &nativeCancellables)
 
@@ -1733,7 +1738,9 @@ extension AetherEngine {
         host.$pendingSoftwarePathEscalation
             .compactMap { $0 }
             .sink { [weak self] request in
-                Task { @MainActor [weak self] in await self?.escalateToSoftwarePath(request) }
+                self?.hop(for: generation) { [weak self] in
+                    await self?.escalateToSoftwarePath(request, expectedGeneration: generation)
+                }
             }
             .store(in: &nativeCancellables)
 
@@ -1978,7 +1985,7 @@ extension AetherEngine {
         let declaredDuration = loadedOptions.declaredDurationSeconds
         // Built on the main actor, captured into the detach: surfaces source stall/reconnect to playbackPhase (#85).
         let networkPhaseSink: @Sendable (ReaderNetworkPhase) -> Void = { [weak self] phase in
-            Task { @MainActor in self?.setReaderNetworkPhase(phase) }
+            self?.hop(for: generation) { [weak self] in self?.setReaderNetworkPhase(phase) }   // audit Vcore-101
         }
         if loadGeneration == generation { recordStartupCheckpoint(.sessionConstructed) }   // #361
         let forwardBufferSegments = loadedOptions.forwardBufferSegments
@@ -2056,7 +2063,7 @@ extension AetherEngine {
         let declaredDuration = loadedOptions.declaredDurationSeconds
         // Built on the main actor, captured into the detach: surfaces source stall/reconnect to playbackPhase (#85).
         let networkPhaseSink: @Sendable (ReaderNetworkPhase) -> Void = { [weak self] phase in
-            Task { @MainActor in self?.setReaderNetworkPhase(phase) }
+            self?.hop(for: generation) { [weak self] in self?.setReaderNetworkPhase(phase) }   // audit Vcore-101
         }
         if loadGeneration == generation { recordStartupCheckpoint(.sessionConstructed) }   // #361
         try await Task.detached(priority: .userInitiated) {
diff --git a/Sources/AetherEngine/AetherEngine+SoftwarePathEscalation.swift b/Sources/AetherEngine/AetherEngine+SoftwarePathEscalation.swift
index 61c8ddad7..784152394 100644
--- a/Sources/AetherEngine/AetherEngine+SoftwarePathEscalation.swift
+++ b/Sources/AetherEngine/AetherEngine+SoftwarePathEscalation.swift
@@ -17,8 +17,17 @@ import Foundation
 extension AetherEngine {
 
     /// Rebuild this session on the software path, once, because the native one refused the media.
+    /// `expectedGeneration` is the session the failure was raised under (audit LIF-103).
     @MainActor
-    func escalateToSoftwarePath(_ request: SoftwarePathEscalation.Request) async {
+    func escalateToSoftwarePath(_ request: SoftwarePathEscalation.Request, expectedGeneration: UInt64) async {
+        // Audit LIF-103: a stop() or a new load() between the failure and this job ended that session;
+        // its options and budget now belong to whatever replaced it.
+        guard loadGeneration == expectedGeneration else {
+            EngineLog.emit(
+                "[AetherEngine] #561 escalation dropped: the session it was raised for has ended",
+                category: .engine)
+            return
+        }
         guard SoftwarePathEscalation.shouldEscalate(
             errorDomain: request.domain,
             availability: SoftwarePathEscalation.Availability(
@@ -71,8 +80,9 @@ extension AetherEngine {
             // AE#629: a rebuild that failed after its teardown has already surfaced its own failure,
             // and a load() that followed it threw that same error. Publishing the absorbed one on top
             // would hand the host two `.error`s for one failure, the second contradicting the throw.
-            // The absorbed failure is not lost: `softwarePathEscalations` carried it.
-            if case .error = state {
+            // The absorbed failure is not lost: `softwarePathEscalations` carried it. Audit LIF-103:
+            // asked of the generation, not of `state`, which does not say whose failure it holds.
+            guard loadGeneration == expectedGeneration else {
                 EngineLog.emit(
                     "[AetherEngine] #561 the software rebuild failed after its teardown (\(error)); "
                     + "its own failure is the one surfaced",
diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index bf98a8880..5383ec0cf 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -2046,6 +2046,17 @@ public final class AetherEngine: ObservableObject {
         }
     }
 
+    /// Audit LIF-103, Vcore-101: a session callback's hop onto the main actor, dropped when the session
+    /// that raised it has ended by the time it lands. Only `stopInternal` bumps `loadGeneration` and it
+    /// always ends the session, so the generation is the session's identity on every path, the software
+    /// one included, which has no session object to compare.
+    nonisolated func hop(for generation: UInt64, _ body: @escaping @Sendable @MainActor () async -> Void) {
+        Task { @MainActor [weak self] in
+            guard let self, self.loadGeneration == generation else { return }
+            await body()
+        }
+    }
+
     /// Shift seam history on the item axis. The producer rebases immediately (live program boundary) or starts a
     /// fresh epoch (VOD restart); AVPlayer renders that content ~buffer+holdback later. The currentTime sink
     /// resolves the active shift by looking up the newest seam at or before the raw clock (a history, not a
@@ -2581,7 +2592,9 @@ public final class AetherEngine: ObservableObject {
     /// React to AVPlayer rejecting the served master (#98, #130): if eligible, reload the media
     /// playlist in place (single-variant); otherwise surface the failure normally.
     @MainActor
-    func fallBackToMediaPlaylist(_ rejection: DisplayRejection) {
+    func fallBackToMediaPlaylist(_ rejection: DisplayRejection, expectedGeneration: UInt64) {
+        // Audit LIF-103: a rejection of an ended session's item is not the running session's to act on.
+        guard loadGeneration == expectedGeneration else { return }
         guard let host = nativeHost, let session = nativeVideoSession else {
             publishError(PlaybackErrorInfo(kind: .masterPlaylistRejected, message: rejection.message, underlyingDomain: rejection.domain, underlyingCode: rejection.code))
             return
diff --git a/Sources/AetherEngine/Native/NativeAVPlayerHost.swift b/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
index 3a249b6c4..68cc98842 100644
--- a/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
+++ b/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
@@ -2082,6 +2082,9 @@ final class NativeAVPlayerHost {
         notificationObservers.removeAll()
         // Clear terminal flags: keepNativeHost reload reuses the host and @Published replays on subscribe; stale failure/didReachEnd corrupt the new session (issue #15).
         failure = nil
+        // Audit Vcore-102: the same replay would hand the successor's sinks this item's refusal.
+        pendingDisplayRejection = nil
+        pendingSoftwarePathEscalation = nil
         didReachEnd = false
         // #315: same reason. The layer itself still reads true for a few tens of ms past this point
         // (AVFoundation clears it after the swap), so the published value leads the layer here on
diff --git a/Tests/AetherEngineTests/SoftwarePathEscalationTests.swift b/Tests/AetherEngineTests/SoftwarePathEscalationTests.swift
index 069ce81a0..4453115d6 100644
--- a/Tests/AetherEngineTests/SoftwarePathEscalationTests.swift
+++ b/Tests/AetherEngineTests/SoftwarePathEscalationTests.swift
@@ -92,7 +92,8 @@ struct SoftwarePathEscalationTests {
         let escalation = Task { @MainActor in
             await engine.escalateToSoftwarePath(SoftwarePathEscalation.Request(
                 domain: SoftwarePathEscalation.mediaErrorDomain, code: 0,
-                message: "item death at a frozen position", positionSeconds: 0))
+                message: "item death at a frozen position", positionSeconds: 0),
+                expectedGeneration: engine.loadGeneration)
         }
         // The rebuild's probe is parked on the origin, so the stop lands inside the load.
         try await waitFor { origin.blocked.entered }
@@ -132,7 +133,7 @@ struct SoftwarePathEscalationTests {
         let sub = engine.softwarePathEscalations.sink { events.append($0) }
         defer { sub.cancel() }
 
-        await engine.escalateToSoftwarePath(Self.mediaFailure)
+        await engine.escalateToSoftwarePath(Self.mediaFailure, expectedGeneration: engine.loadGeneration)
 
         #expect(events.isEmpty)
         #expect(!engine.softwarePathEscalationBudget.isSpent)
@@ -157,7 +158,7 @@ struct SoftwarePathEscalationTests {
         let sub = engine.softwarePathEscalations.sink { events.append($0) }
         defer { sub.cancel() }
 
-        let escalation = Task { @MainActor in await engine.escalateToSoftwarePath(Self.mediaFailure) }
+        let escalation = Task { @MainActor in await engine.escalateToSoftwarePath(Self.mediaFailure, expectedGeneration: engine.loadGeneration) }
         try await waitFor { origin.blocked.entered }
         engine.stop()
         origin.stop()
@@ -186,7 +187,7 @@ struct SoftwarePathEscalationTests {
         }
         defer { sub.cancel() }
 
-        await engine.escalateToSoftwarePath(Self.mediaFailure)
+        await engine.escalateToSoftwarePath(Self.mediaFailure, expectedGeneration: engine.loadGeneration)
 
         #expect(errors.count == 1)
         #expect(errors.first??.kind != .nativeItemFailed)
@@ -267,7 +268,7 @@ struct SoftwarePathEscalationTests {
         }
         try await waitFor { reader.entered }
 
-        await engine.escalateToSoftwarePath(Self.mediaFailure)
+        await engine.escalateToSoftwarePath(Self.mediaFailure, expectedGeneration: engine.loadGeneration)
         #expect(events.map(\.duringStartup) == [true])
         #expect(engine.softwarePathTakeover == nil)
         #expect(engine.softwarePathTakeoverArm == nil)
diff --git a/Tests/AetherEngineTests/StaleSessionCallbackTests.swift b/Tests/AetherEngineTests/StaleSessionCallbackTests.swift
new file mode 100644
index 000000000..13fda7e65
--- /dev/null
+++ b/Tests/AetherEngineTests/StaleSessionCallbackTests.swift
@@ -0,0 +1,84 @@
+import Foundation
+import Testing
+@testable import AetherEngine
+
+/// Audit LIF-103, Vcore-101, Vcore-102: callbacks a session raises reach the engine through a hop onto
+/// the main actor, and a hop that lands after the session ended used to act on whatever owned the
+/// engine by then: a stopped engine, or the next load.
+@Suite("A callback from an ended session does not reach its successor", .timeLimit(.minutes(2)))
+@MainActor
+struct StaleSessionCallbackTests {
+
+    private static func customSource() throws -> MediaSource {
+        .custom(DataIOReader(data: try ProbeTestFixtures.hdr10Plus()), formatHint: "mp4")
+    }
+
+    private static let mediaFailure = SoftwarePathEscalation.Request(
+        domain: SoftwarePathEscalation.mediaErrorDomain, code: -19602,
+        message: "item death at a frozen position", positionSeconds: 12)
+
+    /// LIF-103: Back pressed in the turn between an item death and its escalation job. `stop()`
+    /// resets neither the options nor the budget, so the escalation ran against a gone session, and
+    /// its rebuild's `sessionNotReloadable(.noActiveSession)` flipped the stopped engine to `.error`.
+    @Test("An escalation raised before stop() and run after it does nothing")
+    func escalationAfterStopIsDropped() async throws {
+        let engine = try AetherEngine()
+        engine.loadedURL = try #require(URL(string: "http://127.0.0.1:9/source.mkv"))
+        let raisedUnder = engine.loadGeneration
+        var events: [SoftwarePathEscalationEvent] = []
+        let sub = engine.softwarePathEscalations.sink { events.append($0) }
+        defer { sub.cancel() }
+
+        engine.stop()
+        await engine.escalateToSoftwarePath(Self.mediaFailure, expectedGeneration: raisedUnder)
+
+        #expect(engine.state == .idle)
+        #expect(engine.errorInfo == nil)
+        #expect(events.isEmpty)
+        #expect(!engine.softwarePathEscalationBudget.isSpent)
+    }
+
+    /// Vcore-102: `@Published` replays its value on subscribe, and the next load subscribes before the
+    /// fresh item's attach clears it, so a reused host handed the previous item's rejection to the
+    /// successor's fallback. `-1002` is how AVFoundation fails an item whose URL it cannot load, and a
+    /// master rejection code at startup.
+    @Test("A torn-down host replays no master rejection to the next load's subscriber")
+    func tearDownDropsTheRejection() async throws {
+        let host = NativeAVPlayerHost()
+        defer { host.tearDown() }
+        host.load(url: try #require(URL(string: "aether-unloadable://origin/master.m3u8")),
+                  startPosition: nil, contract: .init())
+        try await waitFor { host.pendingDisplayRejection != nil }
+
+        host.tearDown()
+        var replayed = 0
+        let sub = host.$pendingDisplayRejection.compactMap { $0 }.sink { _ in replayed += 1 }
+        defer { sub.cancel() }
+
+        #expect(replayed == 0)
+        #expect(host.pendingSoftwarePathEscalation == nil)
+    }
+
+    /// Vcore-101: the HLS session's callbacks captured only the engine, so a late emitter of a
+    /// session that had ended wrote its reader stall and its scrub state into the next one.
+    @Test("A stale session's network phase and scrub state leave the successor alone")
+    func staleSessionCallbacksAreDropped() async throws {
+        let engine = try AetherEngine()
+        defer { engine.stop() }
+        _ = try await engine.load(source: Self.customSource())
+        let ended = try #require(engine.nativeVideoSession)
+        let networkPhase = try #require(ended.onNetworkPhaseChanged)
+        let seekState = try #require(ended.onSeekStateChanged)
+
+        _ = try await engine.load(source: Self.customSource())
+        #expect(engine.nativeVideoSession !== ended)
+        networkPhase(.exhausted)
+        seekState(true, 3)
+
+        let touched = try await waitFor(upTo: .milliseconds(300)) {
+            if case .stalled = engine.playbackPhase { return true }
+            return engine.isSeeking
+        }
+        #expect(!touched)
+    }
+}

From 90acbac4b1c1e2b0f4dacf0bb041a2ced3a4e997 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 06:31:54 +0200
Subject: [PATCH 161/359] fix(live): make the live window sizing total over the
 host's DVR window (audit SEG-107)

`LoadOptions.dvrWindowSeconds` reached `Int(ceil(window / cadence))` in
`LiveWindowSizing.requestedSegmentCount` unvalidated, so a host that expressed "keep
everything" as `.infinity` (or passed NaN, or anything past about 4.6e18 s) trapped on the first
live manifest request and on the pump's resident park cap. The same class 078f1be5 fixed in
`wholeSecondsCovering`.

The sizing now reads the window through `effectiveWindowSeconds`: NaN or nil is the live-only
floor, the rest is clamped to [0, one day], which is far deeper than the 900-entry playlist
ceiling ever serves and keeps the clamp log's `requested x cadence` product in range.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../Video/VideoSegmentProvider.swift          | 12 +++++--
 .../LiveWindowSizingTotalityTests.swift       | 34 +++++++++++++++++++
 2 files changed, 44 insertions(+), 2 deletions(-)
 create mode 100644 Tests/AetherEngineTests/LiveWindowSizingTotalityTests.swift

diff --git a/Sources/AetherEngine/Video/VideoSegmentProvider.swift b/Sources/AetherEngine/Video/VideoSegmentProvider.swift
index 098149882..46cc5f726 100644
--- a/Sources/AetherEngine/Video/VideoSegmentProvider.swift
+++ b/Sources/AetherEngine/Video/VideoSegmentProvider.swift
@@ -16,7 +16,7 @@ struct NativeSubtitleRenditionInfo: Sendable, Equatable {
 
 /// Single source of truth for sliding live window size. Playlist firstVisible and cache evictBelow
 /// both read this so they can never drift (drift = playlist lists a segment the cache deleted, or vice versa).
-/// effectiveWindowSeconds = dvrWindowSeconds ?? liveOnlyFloorSeconds;
+/// effectiveWindowSeconds = dvrWindowSeconds clamped to [0, 1 day] ?? liveOnlyFloorSeconds;
 /// windowSegmentCount = max(minSafeSegments, ceil(effective / targetSegmentDurationSeconds)).
 struct LiveWindowSizing {
     /// Live-only floor: 60 s so disk and playlist stay finite even without DVR seek.
@@ -58,11 +58,19 @@ struct LiveWindowSizing {
     /// has to: comparing the served count against a value that already carries the clamps would report
     /// every clamped window as unclamped.
     func requestedSegmentCount(observedSegmentDurationSeconds: Double?) -> Int {
-        let effective = dvrWindowSeconds ?? Self.liveOnlyFloorSeconds
+        let effective = Self.effectiveWindowSeconds(dvrWindowSeconds)
         let divisor = max(max(0.5, targetSegmentDurationSeconds), observedSegmentDurationSeconds ?? 0)
         return Int(ceil(effective / divisor))
     }
 
+    /// Audit SEG-107: the window is a host value, and `.infinity` ("keep everything"), NaN or anything
+    /// past `Int` trapped the conversion above. A day is far deeper than the playlist ceiling ever
+    /// serves, and keeps the log's `requested x cadence` product in range.
+    static func effectiveWindowSeconds(_ dvrWindowSeconds: Double?) -> Double {
+        guard let window = dvrWindowSeconds, !window.isNaN else { return liveOnlyFloorSeconds }
+        return min(max(window, 0), Double(LiveEdgePolicy.maxCoveredWholeSeconds))
+    }
+
     /// AE#443: how many segments of the observed size the session's disk allowance holds.
     ///
     /// The window a host asks for is a promise in SECONDS and the disk is a fact in BYTES, and until
diff --git a/Tests/AetherEngineTests/LiveWindowSizingTotalityTests.swift b/Tests/AetherEngineTests/LiveWindowSizingTotalityTests.swift
new file mode 100644
index 000000000..57cf995cf
--- /dev/null
+++ b/Tests/AetherEngineTests/LiveWindowSizingTotalityTests.swift
@@ -0,0 +1,34 @@
+import Testing
+@testable import AetherEngine
+
+/// Audit SEG-107: `LoadOptions.dvrWindowSeconds` reached `Int(ceil(window / cadence))` unvalidated, so a
+/// host expressing "keep everything" as `.infinity` trapped on the first live manifest request.
+@Suite("Live window sizing is total over the host's DVR window")
+struct LiveWindowSizingTotalityTests {
+
+    @Test("An unbounded window serves the playlist ceiling", arguments: [
+        Double.infinity, 1e300, Double.greatestFiniteMagnitude, 5e18,
+    ])
+    func unboundedWindow(window: Double) {
+        let sizing = LiveWindowSizing(targetSegmentDurationSeconds: 4, dvrWindowSeconds: window)
+        #expect(sizing.windowSegmentCount == LiveWindowSizing.maxWindowSegments)
+        #expect(sizing.requestedSegmentCount(observedSegmentDurationSeconds: 2) > LiveWindowSizing.maxWindowSegments)
+    }
+
+    @Test("A NaN window sizes like no window, a negative one like the smallest")
+    func nanAndNegativeWindows() {
+        let nan = LiveWindowSizing(targetSegmentDurationSeconds: 4, dvrWindowSeconds: .nan)
+        let none = LiveWindowSizing(targetSegmentDurationSeconds: 4, dvrWindowSeconds: nil)
+        #expect(nan.windowSegmentCount == none.windowSegmentCount)
+        let negative = LiveWindowSizing(targetSegmentDurationSeconds: 4, dvrWindowSeconds: -.infinity)
+        #expect(negative.windowSegmentCount == LiveWindowSizing.minSafeSegments)
+    }
+
+    @Test("Ordinary windows are unchanged")
+    func ordinaryWindows() {
+        #expect(LiveWindowSizing(targetSegmentDurationSeconds: 4, dvrWindowSeconds: 1800)
+            .requestedSegmentCount(observedSegmentDurationSeconds: nil) == 450)
+        #expect(LiveWindowSizing(targetSegmentDurationSeconds: 4, dvrWindowSeconds: 86_400)
+            .requestedSegmentCount(observedSegmentDurationSeconds: 6) == 14_400)
+    }
+}

From bbbefd0c153c8359dd55e8149446c43ca585a3ce Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 06:34:29 +0200
Subject: [PATCH 162/359] fix(demux): bound every demuxed timestamp once, at
 the Demuxer (audit NAT-101, DEC-101, FEA-101, SUB-105)

SEG-1 sanitized packet timestamps inside the loopback segment producer
only. The software host, the audio-only host, the still extractor, the
recording tap, the subtitle stores and every probe read the same Demuxer
and got matroskadec's raw uint64 cluster times and INT64_MAX block
durations, so a crafted file still trapped the process in the SW-host
fold, the DVR feeder, the decoders' `pts * num` and the subtitle drain.

`SourceTimestampBounds.sanitize(_:timeBase:)` unsets pts/dts (and zeroes
the duration) at |ticks| >= 2^62 or |seconds| >= 4e9.
`readDemuxedPacketLocked` applies it right after `av_read_frame`, before
the #407 clearing, the AE#105 fold, the #651 join and the #409 repair, and
`readPacket` applies it again at every exit, because #409 rewrites pts/dts
after the funnel with wrapping arithmetic. The sidecar `SubtitleDecoder`
runs its own read loop and gets one call there. Epoch-anchored 1 GHz
timestamps stay under 2^62 until about 2116 and epoch seconds under 4e9
until about 2096. The producer keeps its own 2^60 bound unchanged.

Since 4e9 x (2^31 - 1) < 2^63, a bounded tick times any AVRational
numerator fits Int64. Values made after the funnel still get local checks:
the decoders build their CMTimes through one checked helper (.invalid on
overflow), the SW-host fold converts and applies its offset with checked
arithmetic (unset on failure), and the DVR feeder and the still extractor
turn ring seconds back into ticks through a checked conversion.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 Sources/AetherEngine/Audio/AudioDecoder.swift |   5 +-
 .../Decoder/HardwareVideoDecoder.swift        |  19 +-
 .../Decoder/SoftwareVideoDecoder.swift        |  20 +-
 .../Decoder/SubtitleDecoder.swift             |   8 +-
 Sources/AetherEngine/Demuxer/Demuxer.swift    |  37 ++-
 .../Native/SoftwarePlaybackHost.swift         |  18 +-
 .../Native/SoftwareStillExtractor.swift       |   2 +-
 .../Video/SourceTimestampBounds.swift         |  69 +++++
 .../DemuxedTimestampBoundsTests.swift         | 256 ++++++++++++++++++
 .../Issue220SoftwareDecoderDrainTests.swift   |   2 +-
 .../SourceTimestampBoundsTests.swift          | 128 +++++++++
 11 files changed, 515 insertions(+), 49 deletions(-)
 create mode 100644 Tests/AetherEngineTests/DemuxedTimestampBoundsTests.swift

diff --git a/Sources/AetherEngine/Audio/AudioDecoder.swift b/Sources/AetherEngine/Audio/AudioDecoder.swift
index dafe84b1e..225345fa1 100644
--- a/Sources/AetherEngine/Audio/AudioDecoder.swift
+++ b/Sources/AetherEngine/Audio/AudioDecoder.swift
@@ -355,10 +355,7 @@ final class AudioDecoder: @unchecked Sendable {
 
         // First frame in a new accumulator captures the PTS; subsequent frames only extend the buffer.
         if pendingSampleCount == 0 {
-            let pts = frame.pointee.pts
-            pendingStartPTS = (pts != Int64.min)
-                ? CMTimeMake(value: pts * Int64(timeBase.num), timescale: Int32(timeBase.den))
-                : .invalid
+            pendingStartPTS = SourceTimestampBounds.cmTime(ticks: frame.pointee.pts, timeBase: timeBase)
         }
 
         pendingBytes.append(tempBuffer, count: Int(convertedSamples) * bytesPerSample)
diff --git a/Sources/AetherEngine/Decoder/HardwareVideoDecoder.swift b/Sources/AetherEngine/Decoder/HardwareVideoDecoder.swift
index 74c76eb2a..1893ca627 100644
--- a/Sources/AetherEngine/Decoder/HardwareVideoDecoder.swift
+++ b/Sources/AetherEngine/Decoder/HardwareVideoDecoder.swift
@@ -261,19 +261,10 @@ final class HardwareVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
             copied.deallocate()
             return
         }
-        let ptsRaw = packet.pointee.pts
-        let dtsRaw = packet.pointee.dts
-        let durRaw = packet.pointee.duration
-        let timescale = max(timeBase.den, 1)
-
-        let pts = (ptsRaw != Int64.min)
-            ? CMTimeMake(value: ptsRaw * Int64(timeBase.num), timescale: timescale)
-            : CMTime.invalid
-        let dts = (dtsRaw != Int64.min)
-            ? CMTimeMake(value: dtsRaw * Int64(timeBase.num), timescale: timescale)
-            : CMTime.invalid
-        let dur = (durRaw > 0)
-            ? CMTimeMake(value: durRaw * Int64(timeBase.num), timescale: timescale)
+        let pts = SourceTimestampBounds.cmTime(ticks: packet.pointee.pts, timeBase: timeBase)
+        let dts = SourceTimestampBounds.cmTime(ticks: packet.pointee.dts, timeBase: timeBase)
+        let dur = packet.pointee.duration > 0
+            ? SourceTimestampBounds.cmTime(ticks: packet.pointee.duration, timeBase: timeBase)
             : CMTime.invalid
 
         var timing = CMSampleTimingInfo(duration: dur, presentationTimeStamp: pts, decodeTimeStamp: dts)
@@ -330,7 +321,7 @@ final class HardwareVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
         lock.unlock()
         if decodeStatus != noErr {
             EngineLog.emit(
-                "[HardwareVideoDecoder] decode error \(decodeStatus) at pts=\(ptsRaw)",
+                "[HardwareVideoDecoder] decode error \(decodeStatus) at pts=\(packet.pointee.pts)",
                 category: .swPlayback
             )
         }
diff --git a/Sources/AetherEngine/Decoder/SoftwareVideoDecoder.swift b/Sources/AetherEngine/Decoder/SoftwareVideoDecoder.swift
index 747d59d91..ea63e0054 100644
--- a/Sources/AetherEngine/Decoder/SoftwareVideoDecoder.swift
+++ b/Sources/AetherEngine/Decoder/SoftwareVideoDecoder.swift
@@ -385,12 +385,9 @@ final class SoftwareVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
     }
 
     private func emitInner(_ f: UnsafeMutablePointer<AVFrame>, timeBase tb: AVRational) {
-        if let threshold = skipUntilPTS, f.pointee.pts != Int64.min {
-            let framePTS = CMTimeMake(
-                value: f.pointee.pts * Int64(tb.num),
-                timescale: Int32(tb.den)
-            )
-            if CMTimeCompare(framePTS, threshold) < 0 {
+        let cmPTS = SourceTimestampBounds.cmTime(ticks: f.pointee.pts, timeBase: tb)
+        if let threshold = skipUntilPTS, cmPTS.isValid {
+            if CMTimeCompare(cmPTS, threshold) < 0 {
                 return
             }
             // Compare-and-clear: a concurrent seek can install a new threshold; blindly nil-ing would discard it.
@@ -428,17 +425,6 @@ final class SoftwareVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
 
         reportDecodedFormat(pixelBuffer: pixelBuffer)
 
-        let pts = f.pointee.pts
-        let cmPTS: CMTime
-        if pts != Int64.min {
-            cmPTS = CMTimeMake(
-                value: pts * Int64(tb.num),
-                timescale: Int32(tb.den)
-            )
-        } else {
-            cmPTS = .invalid
-        }
-
         // HDR10+: read dynamic metadata from post-decode AVFrame side data (T.35 SEI bytes).
         // Can't reuse the VT path's packet-side stash; this decoder owns its own packet flow.
         let hdr10PlusData = extractHDR10PlusBytes(from: f)
diff --git a/Sources/AetherEngine/Decoder/SubtitleDecoder.swift b/Sources/AetherEngine/Decoder/SubtitleDecoder.swift
index bdbb8c4d0..574834cb9 100644
--- a/Sources/AetherEngine/Decoder/SubtitleDecoder.swift
+++ b/Sources/AetherEngine/Decoder/SubtitleDecoder.swift
@@ -451,7 +451,13 @@ enum SubtitleDecoder {
                 break
             }
 
-            decodersByStream[pkt.pointee.stream_index]?.decode(packet: pkt)
+            if let decoder = decodersByStream[pkt.pointee.stream_index] {
+                // Audit FEA-101 / SUB-105: this loop reads libavformat directly, past Demuxer's bound.
+                if let stream = fmt.pointee.streams[Int(pkt.pointee.stream_index)] {
+                    SourceTimestampBounds.sanitize(pkt, timeBase: stream.pointee.time_base)
+                }
+                decoder.decode(packet: pkt)
+            }
 
             av_packet_unref(pkt)
             trackedPacketFree(&pktPtr)
diff --git a/Sources/AetherEngine/Demuxer/Demuxer.swift b/Sources/AetherEngine/Demuxer/Demuxer.swift
index 622225556..e24db3191 100644
--- a/Sources/AetherEngine/Demuxer/Demuxer.swift
+++ b/Sources/AetherEngine/Demuxer/Demuxer.swift
@@ -1537,16 +1537,18 @@ public final class Demuxer: @unchecked Sendable {
             // new read, so the container's own order survives the verdict. Checked every pass, not
             // once on entry: the packet that completes the sample flips the phase, and the queue
             // behind it has to drain before the read that follows it is emitted.
-            if let held = compositionRepair?.dequeue() { return held }
+            // Every exit is bounded again: #409 rewrites pts/dts after the funnel in
+            // `readDemuxedPacketLocked`, with wrapping arithmetic.
+            if let held = compositionRepair?.dequeue() { return boundTimestampsLocked(held) }
             guard let packet = try readPacketLocked() else {
                 // EOF can arrive mid-sample on a very short source; the verdict has to be reached
                 // now or the held packets would never be delivered.
                 compositionRepair?.endOfStream()
-                if let held = compositionRepair?.dequeue() { return held }
+                if let held = compositionRepair?.dequeue() { return boundTimestampsLocked(held) }
                 return nil
             }
-            guard let repair = armCompositionRepairIfNeeded() else { return packet }
-            if !repair.ingest(packet) { return packet }
+            guard let repair = armCompositionRepairIfNeeded() else { return boundTimestampsLocked(packet) }
+            if !repair.ingest(packet) { return boundTimestampsLocked(packet) }
         }
     }
 
@@ -1667,6 +1669,32 @@ public final class Demuxer: @unchecked Sendable {
         for key in subpictureAssemblers.keys { subpictureAssemblers[key]?.reset() }
     }
 
+    /// An out-of-range source timestamp was logged once for this demuxer. Guarded by `accessLock`.
+    private var implausibleTimestampLogged = false
+
+    /// Audit NAT-101 / DEC-101 / FEA-101 / SUB-105 / SEG-101: libavformat hands back whatever the
+    /// container wrote (matroskadec stores a uint64 cluster time into an int64 pts and clamps
+    /// BlockDuration to INT64_MAX, a live fMP4 tfdt is the origin's choice), and every consumer of
+    /// this demuxer does tick arithmetic on it. One bound here covers them all. Caller holds
+    /// `accessLock`.
+    @discardableResult
+    private func boundTimestampsLocked(_ packet: UnsafeMutablePointer<AVPacket>) -> UnsafeMutablePointer<AVPacket> {
+        guard let ctx = formatContext else { return packet }
+        let index = Int(packet.pointee.stream_index)
+        let timeBase = index >= 0 && index < Int(ctx.pointee.nb_streams)
+            ? ctx.pointee.streams[index]?.pointee.time_base : nil
+        let pts = packet.pointee.pts, dts = packet.pointee.dts, duration = packet.pointee.duration
+        guard SourceTimestampBounds.sanitize(packet, timeBase: timeBase ?? AVRational(num: 0, den: 0)),
+              !implausibleTimestampLogged else { return packet }
+        implausibleTimestampLogged = true
+        EngineLog.emit(
+            "[Demuxer] stream \(index) carries an out-of-range timestamp "
+            + "(pts=\(pts) dts=\(dts) duration=\(duration)), treated as unset",
+            category: .demux
+        )
+        return packet
+    }
+
     /// One `av_read_frame`, as libavformat delivers it. Caller holds `accessLock`.
     private func readDemuxedPacketLocked() throws -> UnsafeMutablePointer<AVPacket>? {
         guard let ctx = formatContext else { return nil }
@@ -1690,6 +1718,7 @@ public final class Demuxer: @unchecked Sendable {
             }
             throw DemuxerError.readFailed(code: ret)
         }
+        if let pkt = packet { boundTimestampsLocked(pkt) }
         // #407: before anything reads a timestamp off this packet. The PTS on these streams was
         // invented by `+genpts` out of decode order and transposes every B/P pair; dropping it leaves
         // the decoder's own reorder to place the picture. See `VFWDecodeOrderPTSRepair`.
diff --git a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
index b16f70c84..4c4a82ff6 100644
--- a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
+++ b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
@@ -1559,7 +1559,7 @@ final class SoftwarePlaybackHost {
                 memcpy(dst, base, pkt.bytes.count)
             }
         }
-        p.pointee.pts = Int64((pkt.pts / tbSec).rounded())
+        p.pointee.pts = SourceTimestampBounds.roundedTicks(pkt.pts / tbSec) ?? Int64.min
         p.pointee.dts = p.pointee.pts
         p.pointee.flags = pkt.isKeyframe ? AV_PKT_FLAG_KEY : 0
         p.pointee.stream_index = pkt.isVideo ? videoStreamIndex : audioStreamIndex
@@ -1987,9 +1987,11 @@ final class SoftwarePlaybackHost {
                 let tbSec = (streamIdx == videoStreamIndex)
                     ? videoTimeBaseSeconds : audioTimeBaseSeconds
                 if tbSec > 0 {
-                    let offsetTicks = Int64((discontinuityOffsetSec / tbSec).rounded())
-                    if packet.pointee.pts != Int64.min { packet.pointee.pts -= offsetTicks }
-                    if packet.pointee.dts != Int64.min { packet.pointee.dts -= offsetTicks }
+                    // Audit NAT-101: the offset spans twice the input range and converts per stream
+                    // base, so a packet on the far side of a seam can still leave Int64.
+                    let offsetTicks = SourceTimestampBounds.roundedTicks(discontinuityOffsetSec / tbSec)
+                    packet.pointee.pts = SourceTimestampBounds.shifted(packet.pointee.pts, back: offsetTicks)
+                    packet.pointee.dts = SourceTimestampBounds.shifted(packet.pointee.dts, back: offsetTicks)
                 }
             }
 
@@ -2750,9 +2752,11 @@ final class SoftwarePlaybackHost {
                 let tbSec = (streamIdx == videoStreamIndex)
                     ? videoTimeBaseSeconds : audioTimeBaseSeconds
                 if tbSec > 0 {
-                    let offsetTicks = Int64((discontinuityOffsetSec / tbSec).rounded())
-                    if packet.pointee.pts != Int64.min { packet.pointee.pts -= offsetTicks }
-                    if packet.pointee.dts != Int64.min { packet.pointee.dts -= offsetTicks }
+                    // Audit NAT-101: the offset spans twice the input range and converts per stream
+                    // base, so a packet on the far side of a seam can still leave Int64.
+                    let offsetTicks = SourceTimestampBounds.roundedTicks(discontinuityOffsetSec / tbSec)
+                    packet.pointee.pts = SourceTimestampBounds.shifted(packet.pointee.pts, back: offsetTicks)
+                    packet.pointee.dts = SourceTimestampBounds.shifted(packet.pointee.dts, back: offsetTicks)
                 }
             }
 
diff --git a/Sources/AetherEngine/Native/SoftwareStillExtractor.swift b/Sources/AetherEngine/Native/SoftwareStillExtractor.swift
index 609f15e17..ab9d28d21 100644
--- a/Sources/AetherEngine/Native/SoftwareStillExtractor.swift
+++ b/Sources/AetherEngine/Native/SoftwareStillExtractor.swift
@@ -128,7 +128,7 @@ final class SoftwareStillExtractor: @unchecked Sendable {
                 memcpy(dst, base, packet.bytes.count)
             }
         }
-        p.pointee.pts = Int64((packet.pts / timeBaseSeconds).rounded())
+        p.pointee.pts = SourceTimestampBounds.roundedTicks(packet.pts / timeBaseSeconds) ?? Int64.min
         p.pointee.dts = p.pointee.pts
         p.pointee.flags = packet.isKeyframe ? AV_PKT_FLAG_KEY : 0
         p.pointee.stream_index = videoStreamIndex
diff --git a/Sources/AetherEngine/Video/SourceTimestampBounds.swift b/Sources/AetherEngine/Video/SourceTimestampBounds.swift
index fbb61fee2..90e2c1a29 100644
--- a/Sources/AetherEngine/Video/SourceTimestampBounds.swift
+++ b/Sources/AetherEngine/Video/SourceTimestampBounds.swift
@@ -1,4 +1,5 @@
 import Foundation
+import CoreMedia
 import AetherLibavcodec
 
 /// Audit SEG-1: demuxed timestamps reach the pump unchecked (matroskadec stores a uint64 cluster
@@ -17,6 +18,42 @@ enum SourceTimestampBounds {
         return ticks > -plausibleMagnitude && ticks < plausibleMagnitude ? ticks : Int64.min
     }
 
+    /// Audit NAT-101 / DEC-101 / FEA-101 / SUB-105: the demuxer-wide bound, applied to every packet
+    /// the engine reads. 2^62 keeps any difference of two bounded values inside Int64 and holds an
+    /// epoch-anchored nanosecond timestamp (1.79e18 in 2026) until about 2116.
+    static let demuxedMagnitude: Int64 = 1 << 62
+
+    /// Epoch seconds pass until about 2096. `ticks * num == seconds * den` and
+    /// `4e9 * (2^31 - 1) < 2^63`, so a tick inside this bound times any AVRational numerator stays
+    /// inside Int64, and a bounded time scaled to milliseconds or centiseconds stays inside Int.
+    static let maxPlausibleSeconds: Double = 4e9
+
+    /// AV_NOPTS_VALUE for a tick at or past `demuxedMagnitude`, or one whose time on `timeBase` is at
+    /// or past `maxPlausibleSeconds`. A degenerate time base leaves only the tick rule.
+    static func plausible(_ ticks: Int64, timeBase: AVRational) -> Int64 {
+        guard ticks != Int64.min else { return ticks }
+        guard ticks > -demuxedMagnitude, ticks < demuxedMagnitude else { return Int64.min }
+        guard timeBase.num > 0, timeBase.den > 0 else { return ticks }
+        let seconds = Double(ticks) * Double(timeBase.num) / Double(timeBase.den)
+        return abs(seconds) < maxPlausibleSeconds ? ticks : Int64.min
+    }
+
+    /// The demuxer's funnel: implausible pts / dts become AV_NOPTS_VALUE, an implausible or negative
+    /// duration becomes 0. Idempotent, so a second pass over repaired output is free. Returns whether
+    /// any field was replaced.
+    @discardableResult
+    static func sanitize(_ packet: UnsafeMutablePointer<AVPacket>, timeBase: AVRational) -> Bool {
+        let pts = plausible(packet.pointee.pts, timeBase: timeBase)
+        let dts = plausible(packet.pointee.dts, timeBase: timeBase)
+        let duration = packet.pointee.duration
+        let durationOK = duration >= 0 && plausible(duration, timeBase: timeBase) == duration
+        guard pts != packet.pointee.pts || dts != packet.pointee.dts || !durationOK else { return false }
+        packet.pointee.pts = pts
+        packet.pointee.dts = dts
+        if !durationOK { packet.pointee.duration = 0 }
+        return true
+    }
+
     /// Returns whether any field was out of range and got replaced.
     @discardableResult
     static func sanitize(_ packet: UnsafeMutablePointer<AVPacket>) -> Bool {
@@ -43,4 +80,36 @@ enum SourceTimestampBounds {
         guard overflow else { return max(value, Int64.min + 1) }
         return lhs < 0 ? Int64.min + 1 : Int64.max
     }
+
+    /// Audit DEC-101: `ticks * num` as a CMTime, `.invalid` for AV_NOPTS_VALUE, a degenerate time
+    /// base or a product outside Int64. Decoder-computed frame timestamps and the software host's
+    /// folded ones never pass the demuxer's bound, so the conversion itself has to be total.
+    static func cmTime(ticks: Int64, timeBase: AVRational) -> CMTime {
+        guard ticks != Int64.min, timeBase.den > 0 else { return .invalid }
+        let (value, overflow) = ticks.multipliedReportingOverflow(by: Int64(timeBase.num))
+        guard !overflow else { return .invalid }
+        return CMTimeMake(value: value, timescale: timeBase.den)
+    }
+
+    /// A tick count computed in Double, rounded to the nearest tick. nil when it is not finite or
+    /// falls outside Int64, Int64.min included (it reads as AV_NOPTS_VALUE).
+    static func roundedTicks(_ value: Double) -> Int64? {
+        guard let ticks = Int64(exactly: value.rounded()), ticks != Int64.min else { return nil }
+        return ticks
+    }
+
+    /// Audit NAT-101: moves a timestamp back by `offset` ticks. AV_NOPTS_VALUE when the timestamp or
+    /// the offset is unset, or when the result leaves Int64.
+    static func shifted(_ ticks: Int64, back offset: Int64?) -> Int64 {
+        guard ticks != Int64.min, let offset else { return Int64.min }
+        let (value, overflow) = ticks.subtractingReportingOverflow(offset)
+        return overflow ? Int64.min : value
+    }
+
+    /// Audit SUB-105: a cue or display time about to be scaled into an integer. NaN reads as 0 and
+    /// anything past `maxPlausibleSeconds` pins to it.
+    static func clampedSeconds(_ seconds: Double) -> Double {
+        guard !seconds.isNaN else { return 0 }
+        return min(max(seconds, -maxPlausibleSeconds), maxPlausibleSeconds)
+    }
 }
diff --git a/Tests/AetherEngineTests/DemuxedTimestampBoundsTests.swift b/Tests/AetherEngineTests/DemuxedTimestampBoundsTests.swift
new file mode 100644
index 000000000..887b9d05c
--- /dev/null
+++ b/Tests/AetherEngineTests/DemuxedTimestampBoundsTests.swift
@@ -0,0 +1,256 @@
+import CoreMedia
+import Foundation
+import Testing
+import AetherLibavcodec
+import AetherLibavformat
+import AetherLibavutil
+@testable import AetherEngine
+
+/// A minimal Matroska file with one S_TEXT/UTF8 track, one Cluster per block, built by hand because
+/// the pinned FFmpeg carries no Matroska muxer. Every field is written verbatim, which is the point:
+/// matroskadec stores a uint64 Cluster Timestamp into an int64 pts unchecked, clamps BlockDuration to
+/// INT64_MAX, and derives the stream time base from TimestampScale, so a crafted file reaches any
+/// magnitude and a time base whose numerator is above one.
+enum HostileTimestampMatroska {
+    struct Block {
+        var cluster: UInt64
+        var duration: UInt64?
+    }
+
+    private static func vintSize(_ n: Int) -> [UInt8] {
+        var bytes: [UInt8] = [0x01]
+        for shift in stride(from: 48, through: 0, by: -8) {
+            bytes.append(UInt8((n >> shift) & 0xFF))
+        }
+        return bytes
+    }
+
+    private static func element(_ id: [UInt8], _ payload: [UInt8]) -> [UInt8] {
+        id + vintSize(payload.count) + payload
+    }
+
+    private static func uint(_ value: UInt64) -> [UInt8] {
+        var bytes: [UInt8] = []
+        var v = value
+        repeat {
+            bytes.insert(UInt8(v & 0xFF), at: 0)
+            v >>= 8
+        } while v > 0
+        return bytes
+    }
+
+    static func make(timestampScale: UInt64 = 1_000_000, blocks: [Block]) -> Data {
+        let header = element([0x1A, 0x45, 0xDF, 0xA3],
+                             element([0x42, 0x86], uint(1)) +
+                             element([0x42, 0xF7], uint(1)) +
+                             element([0x42, 0xF2], uint(4)) +
+                             element([0x42, 0xF3], uint(8)) +
+                             element([0x42, 0x82], Array("matroska".utf8)) +
+                             element([0x42, 0x87], uint(4)) +
+                             element([0x42, 0x85], uint(2)))
+        let info = element([0x15, 0x49, 0xA9, 0x66],
+                           element([0x2A, 0xD7, 0xB1], uint(timestampScale)) +
+                           element([0x4D, 0x80], Array("aether-audit".utf8)) +
+                           element([0x57, 0x41], Array("aether-audit".utf8)))
+        let track = element([0xD7], uint(1)) +
+            element([0x73, 0xC5], uint(1)) +
+            element([0x83], uint(0x11)) +
+            element([0x9C], uint(0)) +
+            element([0x86], Array("S_TEXT/UTF8".utf8))
+        let tracks = element([0x16, 0x54, 0xAE, 0x6B], element([0xAE], track))
+        var clusters: [UInt8] = []
+        for (index, block) in blocks.enumerated() {
+            let payload: [UInt8] = [0x81, 0x00, 0x00, 0x00] + Array("line \(index)".utf8)
+            var group = element([0xA1], payload)
+            if let duration = block.duration { group += element([0x9B], uint(duration)) }
+            clusters += element([0x1F, 0x43, 0xB6, 0x75],
+                                element([0xE7], uint(block.cluster)) + element([0xA0], group))
+        }
+        return Data(header + element([0x18, 0x53, 0x80, 0x67], info + tracks + clusters))
+    }
+
+    /// Every packet the engine's demuxer hands out, as (pts, dts, duration), with the stream's time base.
+    static func readBack(_ data: Data) throws -> (timeBase: AVRational, packets: [(pts: Int64, dts: Int64, duration: Int64)]) {
+        let demuxer = Demuxer()
+        defer { demuxer.close() }
+        try demuxer.open(reader: DataIOReader(data: data), formatHint: "matroska")
+        let stream = try #require(demuxer.stream(at: 0))
+        var packets: [(pts: Int64, dts: Int64, duration: Int64)] = []
+        while let packet = try demuxer.readPacket() {
+            var owned: UnsafeMutablePointer<AVPacket>? = packet
+            defer { trackedPacketFree(&owned) }
+            packets.append((packet.pointee.pts, packet.pointee.dts, packet.pointee.duration))
+        }
+        return (stream.pointee.time_base, packets)
+    }
+}
+
+@Suite("Demuxed timestamps are bounded before any consumer does arithmetic on them")
+struct DemuxedTimestampBoundsTests {
+
+    private static let unset = Int64.min
+
+    /// matroskadec derives 3/1e9 from TimestampScale 3, so the seconds rule and the tick rule both
+    /// have something to catch: 2^61 ticks are 6.9e9 s, 2^62 ticks fail on their own.
+    @Test("out-of-range timestamps leave the demuxer unset, and an INT64_MAX duration leaves it 0")
+    func outOfRangeTimestampsLeaveTheDemuxerUnset() throws {
+        let read = try HostileTimestampMatroska.readBack(HostileTimestampMatroska.make(
+            timestampScale: 3,
+            blocks: [.init(cluster: 1000, duration: 500),
+                     .init(cluster: 1 << 61, duration: 500),
+                     .init(cluster: 1 << 62, duration: 500),
+                     .init(cluster: 2000, duration: UInt64.max),
+                     .init(cluster: 3000, duration: 1)]))
+        #expect(read.timeBase.num == 3 && read.timeBase.den == 1_000_000_000)
+        try #require(read.packets.count == 5)
+        #expect(read.packets[0] == (1000, 1000, 500))
+        #expect(read.packets[1] == (Self.unset, Self.unset, 500))
+        #expect(read.packets[2] == (Self.unset, Self.unset, 500))
+        #expect(read.packets[3] == (2000, 2000, 0))
+        #expect(read.packets[4] == (3000, 3000, 1))
+    }
+
+    /// The bound must not cost a real source its clock: epoch-anchored wall-clock timestamps at
+    /// 1 GHz and 10 MHz are what live fMP4 and some Matroska writers emit.
+    @Test("epoch-anchored nanosecond and 100 ns timestamps pass untouched")
+    func epochAnchoredTimestampsSurvive() throws {
+        let nanos: UInt64 = 1_790_000_000_000_000_000
+        let atNanos = try HostileTimestampMatroska.readBack(HostileTimestampMatroska.make(
+            timestampScale: 1, blocks: [.init(cluster: nanos, duration: 40_000_000)]))
+        #expect(atNanos.timeBase.num == 1 && atNanos.timeBase.den == 1_000_000_000)
+        #expect(atNanos.packets.map(\.pts) == [Int64(nanos)])
+        #expect(atNanos.packets.map(\.duration) == [40_000_000])
+
+        let hundreds: UInt64 = 17_900_000_000_000_000
+        let atHundreds = try HostileTimestampMatroska.readBack(HostileTimestampMatroska.make(
+            timestampScale: 100, blocks: [.init(cluster: hundreds, duration: 400_000)]))
+        #expect(atHundreds.timeBase.num == 1 && atHundreds.timeBase.den == 10_000_000)
+        #expect(atHundreds.packets.map(\.pts) == [Int64(hundreds)])
+    }
+
+    /// Audit FEA-101 / SUB-105: the sidecar decoder runs its own `av_read_frame` loop, a second raw
+    /// channel next to the Demuxer.
+    @Test("the sidecar subtitle reader bounds its own read loop")
+    func sidecarReaderBoundsItsReadLoop() async throws {
+        let data = HostileTimestampMatroska.make(blocks: [
+            .init(cluster: 1000, duration: 500),
+            .init(cluster: 2000, duration: UInt64.max),
+            .init(cluster: 5_000_000_000_000, duration: 500),
+        ])
+        let url = URL(fileURLWithPath: FileManager.default.currentDirectoryPath, isDirectory: true)
+            .appendingPathComponent(".hostile-timestamps-\(UUID().uuidString).mkv")
+        defer { try? FileManager.default.removeItem(at: url) }
+        try data.write(to: url)
+        let cues = try await SubtitleDecoder.decodeFile(url: url).cues
+        #expect(cues.count == 3)
+        for cue in cues {
+            #expect(cue.startTime.isFinite && cue.endTime.isFinite)
+            #expect(abs(cue.startTime) < SourceTimestampBounds.maxPlausibleSeconds)
+            #expect(abs(cue.endTime) < SourceTimestampBounds.maxPlausibleSeconds)
+        }
+        #expect(cues.contains { $0.startTime == 1 && $0.endTime == 1.5 })
+    }
+
+    /// Audit FEA-101, the software-route vector: the SW host's subtitle tap harvests what the demuxer
+    /// hands it, and the drain rebuilt the packet with `Int64(durationSeconds * 1000)`. matroskadec
+    /// clamps an all-ones BlockDuration to INT64_MAX, which at 1 ms is exactly 2^63 after the round
+    /// trip through seconds.
+    @Test("a subtitle block whose duration matroskadec clamps to INT64_MAX drains without trapping")
+    func clampedBlockDurationDrains() throws {
+        let data = HostileTimestampMatroska.make(blocks: [.init(cluster: 1000, duration: UInt64.max)])
+        let demuxer = Demuxer()
+        defer { demuxer.close() }
+        try demuxer.open(reader: DataIOReader(data: data), formatHint: "matroska")
+        let stream = try #require(demuxer.stream(at: 0))
+        let decoder = try #require(EmbeddedSubtitleDecoder(stream: stream, sourceVideoWidth: 16, sourceVideoHeight: 16))
+        let store = SubtitlePacketStore()
+        while let packet = try demuxer.readPacket() {
+            var owned: UnsafeMutablePointer<AVPacket>? = packet
+            defer { trackedPacketFree(&owned) }
+            store.harvest(streamIndex: 0, packet: packet, timeBase: stream.pointee.time_base, writer: .pump)
+        }
+        let entries = store.entries(streamIndex: 0, from: 0, through: 10)
+        try #require(entries.count == 1)
+        #expect(entries[0].durationSeconds == 0)
+        let event = AetherEngine.decodeStoredSubtitlePacket(entries[0], with: decoder)
+        #expect(event?.cues.first?.startTime == 1)
+    }
+
+    /// Audit DEC-101: the decoders turn a frame timestamp into a CMTime as `pts * num`. A value the
+    /// demuxer bound would already have unset still reaches them through the fold and through
+    /// decoder-computed frame timestamps, so the conversion itself has to be total.
+    @Test("the software decoder survives a frame timestamp whose product with the numerator overflows")
+    func softwareDecoderSurvivesNumeratorOverflow() throws {
+        let data = try #require(Data(base64Encoded: Issue220SoftwareDecoderDrainTests.fixtureBase64,
+                                     options: .ignoreUnknownCharacters))
+        let demuxer = Demuxer()
+        try demuxer.open(reader: DataIOReader(data: data), formatHint: "mp4")
+        defer { demuxer.close() }
+        let videoIndex = demuxer.videoStreamIndex
+        let stream = try #require(demuxer.stream(at: videoIndex))
+        stream.pointee.time_base = AVRational(num: 3, den: 1_000_000_000)
+        let frames = FrameTimes()
+        let decoder = SoftwareVideoDecoder()
+        try decoder.open(stream: stream) { _, pts, _ in frames.append(pts) }
+        defer { decoder.close() }
+
+        let base = (Int64(1) << 62) - 1_000_000
+        var index: Int64 = 0
+        while let packet = try? demuxer.readPacket() {
+            if packet.pointee.stream_index == videoIndex {
+                packet.pointee.pts = base + index * 1000
+                packet.pointee.dts = packet.pointee.pts
+                index += 1
+                decoder.decode(packet: packet)
+            }
+            var owned: UnsafeMutablePointer<AVPacket>? = packet
+            trackedPacketFree(&owned)
+        }
+        let delivered = frames.values
+        #expect(!delivered.isEmpty)
+        #expect(delivered.allSatisfy { !$0.isValid })
+    }
+
+    @Test("the audio decoder survives a frame timestamp whose product with the numerator overflows")
+    func audioDecoderSurvivesNumeratorOverflow() throws {
+        let demuxer = Demuxer()
+        defer { demuxer.close() }
+        try demuxer.open(reader: DataIOReader(data: ProbeTestFixtures.eac3()), formatHint: "mp4")
+        let audioIndex = demuxer.audioStreamIndex
+        let stream = try #require(demuxer.stream(at: audioIndex))
+        stream.pointee.time_base = AVRational(num: 3, den: 1_000_000_000)
+        let decoder = AudioDecoder()
+        try decoder.open(stream: stream)
+        defer { decoder.close() }
+
+        let base = (Int64(1) << 62) - 1_000_000
+        var index: Int64 = 0
+        var buffers = 0
+        while let packet = try demuxer.readPacket() {
+            var owned: UnsafeMutablePointer<AVPacket>? = packet
+            defer { trackedPacketFree(&owned) }
+            guard packet.pointee.stream_index == audioIndex else { continue }
+            packet.pointee.pts = base + index * 1000
+            packet.pointee.dts = packet.pointee.pts
+            index += 1
+            buffers += decoder.decode(packet: packet).count
+        }
+        #expect(index > 0)
+        #expect(buffers > 0)
+    }
+
+    private final class FrameTimes: @unchecked Sendable {
+        private let lock = NSLock()
+        private var storage: [CMTime] = []
+        func append(_ time: CMTime) {
+            lock.lock()
+            storage.append(time)
+            lock.unlock()
+        }
+        var values: [CMTime] {
+            lock.lock()
+            defer { lock.unlock() }
+            return storage
+        }
+    }
+}
diff --git a/Tests/AetherEngineTests/Issue220SoftwareDecoderDrainTests.swift b/Tests/AetherEngineTests/Issue220SoftwareDecoderDrainTests.swift
index cccd6c2f7..da5f0fdf0 100644
--- a/Tests/AetherEngineTests/Issue220SoftwareDecoderDrainTests.swift
+++ b/Tests/AetherEngineTests/Issue220SoftwareDecoderDrainTests.swift
@@ -91,7 +91,7 @@ struct Issue220SoftwareDecoderDrainTests {
     ///   ffmpeg -f lavfi -i "color=c=red:s=128x96:r=10:d=4" -c:v libx264 -preset ultrafast \
     ///     -tune zerolatency -bf 0 -pix_fmt yuv420p -x264-params keyint=10 -movflags +faststart swdec.mp4
     ///   base64 -i swdec.mp4
-    private static let fixtureBase64 = """
+    static let fixtureBase64 = """
         AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1wNDEAAAPPbW9vdgAAAGxtdmhkAAAAAAAAAAAAAAAAAAAD6AAAD6AAAQAA
         AQAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAAAAABAAAAAAAAAAAAAAAAAABAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
         AAAAAgAAAvl0cmFrAAAAXHRraGQAAAADAAAAAAAAAAAAAAABAAAAAAAAD6AAAAAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAAAAA
diff --git a/Tests/AetherEngineTests/SourceTimestampBoundsTests.swift b/Tests/AetherEngineTests/SourceTimestampBoundsTests.swift
index 28bcb5c5f..777127e96 100644
--- a/Tests/AetherEngineTests/SourceTimestampBoundsTests.swift
+++ b/Tests/AetherEngineTests/SourceTimestampBoundsTests.swift
@@ -1,3 +1,4 @@
+import CoreMedia
 import Testing
 import AetherLibavcodec
 @testable import AetherEngine
@@ -61,4 +62,131 @@ struct SourceTimestampBoundsTests {
         #expect(HLSSegmentProducer.resolveVideoSampleDuration(
             existingDuration: 0, dts: big, nextDts: -big, fallback: 1800, capTicks: 90_000) == 1800)
     }
+
+    // MARK: - The demuxer funnel (audit NAT-101 / DEC-101 / FEA-101 / SUB-105)
+
+    private func sanitized(pts: Int64, dts: Int64, duration: Int64 = 0, _ timeBase: AVRational)
+        throws -> (changed: Bool, pts: Int64, dts: Int64, duration: Int64) {
+        var result: (Bool, Int64, Int64, Int64) = (false, 0, 0, 0)
+        try withPacket(pts: pts, dts: dts, duration: duration) { packet in
+            let changed = SourceTimestampBounds.sanitize(packet, timeBase: timeBase)
+            result = (changed, packet.pointee.pts, packet.pointee.dts, packet.pointee.duration)
+        }
+        return result
+    }
+
+    @Test func epochAnchoredTimestampsPassTheFunnel() throws {
+        let nanos = try sanitized(pts: 1_790_000_000_000_000_000, dts: 1_790_000_000_000_000_000,
+                                  duration: 40_000_000, AVRational(num: 1, den: 1_000_000_000))
+        #expect(!nanos.changed)
+        #expect(nanos.pts == 1_790_000_000_000_000_000)
+        let hundreds = try sanitized(pts: 18_000_000_000_000_000, dts: 18_000_000_000_000_000,
+                                     duration: 400_000, AVRational(num: 1, den: 10_000_000))
+        #expect(!hundreds.changed)
+        let mpegts = try sanitized(pts: 8_589_934_591, dts: 8_589_934_590, duration: 3003,
+                                   AVRational(num: 1, den: 90_000))
+        #expect(!mpegts.changed)
+    }
+
+    @Test func secondsRuleCatchesWhatTheTickRuleLetsThrough() throws {
+        let nonUnit = try sanitized(pts: (Int64(1) << 62) - 1, dts: 1000, AVRational(num: 3, den: 1_000_000_000))
+        #expect(nonUnit.changed)
+        #expect(nonUnit.pts == Int64.min)
+        #expect(nonUnit.dts == 1000)
+        let ninety = try sanitized(pts: Int64(1) << 61, dts: Int64(1) << 61, AVRational(num: 1, den: 90_000))
+        #expect(ninety.pts == Int64.min && ninety.dts == Int64.min)
+        let coarse = try sanitized(pts: 5_000_000_000, dts: -5_000_000_000, AVRational(num: 1, den: 1))
+        #expect(coarse.pts == Int64.min && coarse.dts == Int64.min)
+    }
+
+    @Test func tickRuleHoldsOnADegenerateTimeBase() throws {
+        let fine = try sanitized(pts: Int64(1) << 62, dts: (Int64(1) << 62) - 1, AVRational(num: 0, den: 0))
+        #expect(fine.pts == Int64.min)
+        #expect(fine.dts == (Int64(1) << 62) - 1)
+        let extremes = try sanitized(pts: Int64.max, dts: Int64.min + 1, duration: Int64.max,
+                                     AVRational(num: 1, den: 1_000_000_000))
+        #expect(extremes.pts == Int64.min && extremes.dts == Int64.min && extremes.duration == 0)
+    }
+
+    @Test func durationFollowsTheSameRulesAndNeverGoesNegative() throws {
+        let negative = try sanitized(pts: 0, dts: 0, duration: -1, AVRational(num: 1, den: 1000))
+        #expect(negative.duration == 0)
+        let huge = try sanitized(pts: 0, dts: 0, duration: 10_000_000_000_000, AVRational(num: 1, den: 1000))
+        #expect(huge.duration == 0)
+        let kept = try sanitized(pts: 0, dts: 0, duration: 1_000_000, AVRational(num: 1, den: 1000))
+        #expect(!kept.changed && kept.duration == 1_000_000)
+    }
+
+    @Test func secondPassIsIdempotent() throws {
+        try withPacket(pts: Int64(1) << 61, dts: 1000, duration: Int64.max) { packet in
+            let tb = AVRational(num: 1, den: 90_000)
+            #expect(SourceTimestampBounds.sanitize(packet, timeBase: tb))
+            #expect(!SourceTimestampBounds.sanitize(packet, timeBase: tb))
+            #expect(packet.pointee.dts == 1000)
+        }
+    }
+
+    /// `ticks * num == seconds * den` and 4e9 x (2^31 - 1) < 2^63: the largest tick that passes, times
+    /// the numerator, stays inside Int64 for every time base libavformat can report.
+    @Test func noPassingTickOverflowsTheNumerator() {
+        let values: [Int32] = [1, 3, 1000, 1001, 90_000, 1_000_000_000, Int32.max]
+        for num in values {
+            for den in values {
+                let tb = AVRational(num: num, den: den)
+                var passing: Int64 = 0
+                var failing = SourceTimestampBounds.demuxedMagnitude
+                while failing - passing > 1 {
+                    let mid = passing + (failing - passing) / 2
+                    if SourceTimestampBounds.plausible(mid, timeBase: tb) == mid { passing = mid } else { failing = mid }
+                }
+                #expect(!passing.multipliedReportingOverflow(by: Int64(num)).overflow, "\(num)/\(den)")
+                #expect(!(-passing).multipliedReportingOverflow(by: Int64(num)).overflow, "\(num)/\(den)")
+                #expect(SourceTimestampBounds.plausible(-passing, timeBase: tb) == -passing)
+            }
+        }
+    }
+
+    // MARK: - Checked helpers for values produced after the funnel
+
+    @Test func cmTimeIsInvalidInsteadOfTrapping() {
+        let nonUnit = AVRational(num: 3, den: 1_000_000_000)
+        #expect(!SourceTimestampBounds.cmTime(ticks: Int64(1) << 62, timeBase: nonUnit).isValid)
+        #expect(!SourceTimestampBounds.cmTime(ticks: Int64.min, timeBase: nonUnit).isValid)
+        #expect(!SourceTimestampBounds.cmTime(ticks: 1, timeBase: AVRational(num: 1, den: 0)).isValid)
+        let ok = SourceTimestampBounds.cmTime(ticks: 1001, timeBase: nonUnit)
+        #expect(ok.value == 3003 && ok.timescale == 1_000_000_000)
+    }
+
+    @Test func roundedTicksRefusesWhatInt64CannotHold() {
+        #expect(SourceTimestampBounds.roundedTicks(.nan) == nil)
+        #expect(SourceTimestampBounds.roundedTicks(.infinity) == nil)
+        #expect(SourceTimestampBounds.roundedTicks(-.infinity) == nil)
+        #expect(SourceTimestampBounds.roundedTicks(1e300) == nil)
+        #expect(SourceTimestampBounds.roundedTicks(9.223372036854775807e18) == nil)
+        #expect(SourceTimestampBounds.roundedTicks(-9.223372036854775808e18) == nil)
+        #expect(SourceTimestampBounds.roundedTicks(4_999.5) == 5_000)
+        #expect(SourceTimestampBounds.roundedTicks(-1.4) == -1)
+    }
+
+    /// Audit NAT-101: the software host's fold. Video at 5 s on 1/1000, then a seam whose offset
+    /// no stream base can hold, and an offset that converts but walks a far-side packet out of Int64.
+    @Test func foldShiftDegradesToUnsetInsteadOfTrapping() {
+        let offsetSeconds = Double(Int64.min + 256) * 0.001 - 5
+        let offsetTicks = SourceTimestampBounds.roundedTicks(offsetSeconds / 0.001)
+        #expect(offsetTicks == nil)
+        #expect(SourceTimestampBounds.shifted(5000, back: offsetTicks) == Int64.min)
+
+        let audioOffset = SourceTimestampBounds.roundedTicks(8e9 / 1e-9)
+        #expect(audioOffset == 8_000_000_000_000_000_000)
+        #expect(SourceTimestampBounds.shifted(-(Int64(1) << 62), back: audioOffset) == Int64.min)
+        #expect(SourceTimestampBounds.shifted(Int64.min, back: 0) == Int64.min)
+        #expect(SourceTimestampBounds.shifted(90_000, back: 45_000) == 45_000)
+    }
+
+    @Test func clampedSecondsPinsNonFiniteAndHugeTimes() {
+        #expect(SourceTimestampBounds.clampedSeconds(.nan) == 0)
+        #expect(SourceTimestampBounds.clampedSeconds(.infinity) == SourceTimestampBounds.maxPlausibleSeconds)
+        #expect(SourceTimestampBounds.clampedSeconds(-.infinity) == -SourceTimestampBounds.maxPlausibleSeconds)
+        #expect(SourceTimestampBounds.clampedSeconds(12.5) == 12.5)
+    }
 }

From 6b3951fffce9480fe7041e0eb8932f177ed00969 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 06:34:41 +0200
Subject: [PATCH 163/359] fix(native): range-check the parsed audio sample rate
 before converting it (audit NAT-106)

`mSampleRate` is a Float64 AVFoundation fills from the container, and a QuickTime
SoundDescriptionV2 carries it verbatim, so on the remote-HLS bypass the origin controls it.
`RemoteHLSStreamDescription.audioTracks` checked only `isFinite` before `Int(_:)`, and the
readyToPlay track dump in `NativeAVPlayerHost.audioFormatDescription` checked nothing, so NaN,
infinity or a rate past `Int.max` trapped at every native readyToPlay.

One helper, `RemoteHLSStreamDescription.wholeSampleRate`, returns the rate as an Int when it is
finite and in [0, 1e9), else 0, and both sites use it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../Native/NativeAVPlayerHost.swift           |  2 +-
 .../Native/RemoteHLSStreamDescription.swift   |  9 ++++++++-
 .../RemoteHLSStreamDescriptionTests.swift     | 20 +++++++++++++++++++
 3 files changed, 29 insertions(+), 2 deletions(-)

diff --git a/Sources/AetherEngine/Native/NativeAVPlayerHost.swift b/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
index 3a249b6c4..78475fd04 100644
--- a/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
+++ b/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
@@ -2666,7 +2666,7 @@ final class NativeAVPlayerHost {
         var parts: [String] = []
         if let asbdPtr = CMAudioFormatDescriptionGetStreamBasicDescription(fmt) {
             let asbd = asbdPtr.pointee
-            parts.append("sr=\(Int(asbd.mSampleRate))")
+            parts.append("sr=\(RemoteHLSStreamDescription.wholeSampleRate(asbd.mSampleRate))")
             parts.append("ch=\(asbd.mChannelsPerFrame)")
             parts.append(String(format: "bits=%d", asbd.mBitsPerChannel))
             parts.append("fmt=\(fourccString(asbd.mFormatID))")
diff --git a/Sources/AetherEngine/Native/RemoteHLSStreamDescription.swift b/Sources/AetherEngine/Native/RemoteHLSStreamDescription.swift
index fa842248f..7cb05cc1a 100644
--- a/Sources/AetherEngine/Native/RemoteHLSStreamDescription.swift
+++ b/Sources/AetherEngine/Native/RemoteHLSStreamDescription.swift
@@ -253,6 +253,13 @@ enum RemoteHLSStreamDescription {
 
     /// The published list: one entry per audio track AVPlayer built, ids from `audioTrackIDBase` in item
     /// order, the enabled one as the active index. Named the way the probe path names an untitled track.
+    /// A parsed `mSampleRate` as a whole number, 0 when it cannot be one (audit NAT-106). A QuickTime
+    /// SoundDescriptionV2 carries the rate as a Float64 verbatim, so on the bypass the origin controls
+    /// it, and `Int(_:)` traps on NaN, infinity and anything past `Int`.
+    static func wholeSampleRate(_ rate: Double) -> Int {
+        rate.isFinite && rate >= 0 && rate < 1e9 ? Int(rate) : 0
+    }
+
     static func audioTracks(_ readings: [AudioReading]) -> (tracks: [TrackInfo], activeID: Int?) {
         var tracks: [TrackInfo] = []
         var activeID: Int?
@@ -267,7 +274,7 @@ enum RemoteHLSStreamDescription {
             tracks.append(TrackInfo(
                 id: id, name: name, codec: codec.name, language: language,
                 channels: reading.channels, isDefault: reading.isEnabled, isAtmos: reading.carriesJOC,
-                sampleRate: reading.sampleRate.isFinite ? Int(reading.sampleRate) : 0,
+                sampleRate: wholeSampleRate(reading.sampleRate),
                 bitsPerSample: reading.bitsPerChannel, profile: profile))
             if reading.isEnabled, activeID == nil { activeID = id }
         }
diff --git a/Tests/AetherEngineTests/RemoteHLSStreamDescriptionTests.swift b/Tests/AetherEngineTests/RemoteHLSStreamDescriptionTests.swift
index d14449672..b4e03a103 100644
--- a/Tests/AetherEngineTests/RemoteHLSStreamDescriptionTests.swift
+++ b/Tests/AetherEngineTests/RemoteHLSStreamDescriptionTests.swift
@@ -261,4 +261,24 @@ struct RemoteHLSStreamDescriptionTests {
         let desc = try Self.videoDescription(subType: Self.avc1, width: 16, height: 16, extensions: [:])
         #expect(RemoteHLSStreamDescription.audioReading(from: desc, isEnabled: true, language: nil) == nil)
     }
+
+    // Audit NAT-106: a QuickTime SoundDescriptionV2 carries its rate as a Float64 verbatim, so on the
+    // bypass the origin controls it, and `Int(_:)` trapped past `Int.max` (the log site on NaN too).
+    @Test("a non-finite, negative or absurd sample rate reads as unknown", arguments: [
+        Double.nan, .infinity, -48_000, 1e300, 1e9,
+    ])
+    func hostileSampleRate(rate: Double) {
+        let reading = RemoteHLSStreamDescription.AudioReading(
+            formatID: kAudioFormatLinearPCM, sampleRate: rate, channels: 2, bitsPerChannel: 24,
+            carriesJOC: false, isEnabled: true, language: nil)
+        #expect(RemoteHLSStreamDescription.audioTracks([reading]).tracks.first?.sampleRate == 0)
+        #expect(RemoteHLSStreamDescription.wholeSampleRate(rate) == 0)
+    }
+
+    @Test("an ordinary sample rate is kept")
+    func ordinarySampleRate() {
+        #expect(RemoteHLSStreamDescription.wholeSampleRate(48_000) == 48_000)
+        #expect(RemoteHLSStreamDescription.wholeSampleRate(44_100.0) == 44_100)
+        #expect(RemoteHLSStreamDescription.wholeSampleRate(768_000) == 768_000)
+    }
 }

From 53b6010bd59ad57cd8fbcbdea17e7029490fbace Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 06:34:46 +0200
Subject: [PATCH 164/359] fix(subtitles): make every cue-time conversion total
 (audit FEA-101, SUB-105)

The demuxer bound covers packets, but cue times also arrive from live
WebVTT renditions, external stores and a host calling the public
`ASSScriptBuilder.timestamp`, and each of them scaled a Double into an
Int with a trapping conversion.

`SubtitlePacketStore.harvestChunk`, which the pump, the software-host tap
and the prefetcher all store through, now applies the demuxer's rule:
a non-finite or implausible time is unset, such a duration is 0. The
drain's packet rebuild converts through a checked helper, and the cue
store's dedupe key, the ASS and the WebVTT formatters pin NaN to 0 and
anything past 4e9 s to that edge.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../AetherEngine/AetherEngine+Subtitles.swift |  5 +-
 .../Subtitles/ASSScriptBuilder.swift          |  6 +-
 .../Subtitles/NativeSubtitleCueStore.swift    |  3 +-
 .../Subtitles/SubtitlePacketStore.swift       |  6 ++
 .../Subtitles/WebVTTBuilder.swift             |  2 +-
 .../SubtitleTimeBackstopTests.swift           | 90 +++++++++++++++++++
 6 files changed, 105 insertions(+), 7 deletions(-)
 create mode 100644 Tests/AetherEngineTests/SubtitleTimeBackstopTests.swift

diff --git a/Sources/AetherEngine/AetherEngine+Subtitles.swift b/Sources/AetherEngine/AetherEngine+Subtitles.swift
index 307344d74..d03640aed 100644
--- a/Sources/AetherEngine/AetherEngine+Subtitles.swift
+++ b/Sources/AetherEngine/AetherEngine+Subtitles.swift
@@ -1017,9 +1017,10 @@ extension AetherEngine {
                 memcpy(dst, base, size)
             }
         }
-        pkt.pointee.pts = Int64((entry.ptsSeconds * 1000).rounded())
+        // Audit FEA-101: the store bounds these, but an entry is a plain value and the conversion traps.
+        pkt.pointee.pts = SourceTimestampBounds.roundedTicks(entry.ptsSeconds * 1000) ?? Int64.min
         pkt.pointee.dts = pkt.pointee.pts
-        pkt.pointee.duration = Int64((entry.durationSeconds * 1000).rounded())
+        pkt.pointee.duration = max(0, SourceTimestampBounds.roundedTicks(entry.durationSeconds * 1000) ?? 0)
         pkt.pointee.flags = entry.flags
         // #233: WebVTT placement lives in side data, not in the payload, so it has to be put back.
         if let settings = entry.webvttSettings {
diff --git a/Sources/AetherEngine/Subtitles/ASSScriptBuilder.swift b/Sources/AetherEngine/Subtitles/ASSScriptBuilder.swift
index b82d7cf1e..c364fef02 100644
--- a/Sources/AetherEngine/Subtitles/ASSScriptBuilder.swift
+++ b/Sources/AetherEngine/Subtitles/ASSScriptBuilder.swift
@@ -70,10 +70,10 @@ public final class ASSScriptBuilder {
         seen.removeAll(keepingCapacity: true)
     }
 
-    /// ASS timestamp `H:MM:SS.cc` (centiseconds). Negative input
-    /// clamps to zero.
+    /// ASS timestamp `H:MM:SS.cc` (centiseconds). Negative input and NaN clamp to zero, and a
+    /// time past 4e9 s (infinity included) pins there.
     public static func timestamp(_ seconds: Double) -> String {
-        let total = max(0, seconds)
+        let total = max(0, SourceTimestampBounds.clampedSeconds(seconds))
         var centis = Int((total * 100).rounded())
         let h = centis / 360_000
         centis %= 360_000
diff --git a/Sources/AetherEngine/Subtitles/NativeSubtitleCueStore.swift b/Sources/AetherEngine/Subtitles/NativeSubtitleCueStore.swift
index 7c813cd61..79224452e 100644
--- a/Sources/AetherEngine/Subtitles/NativeSubtitleCueStore.swift
+++ b/Sources/AetherEngine/Subtitles/NativeSubtitleCueStore.swift
@@ -30,7 +30,8 @@ final class NativeSubtitleCueStore: @unchecked Sendable {
     init() {}
 
     private static func key(start: Double, end: Double, text: String) -> String {
-        "\(Int((start * 1000).rounded()))|\(Int((end * 1000).rounded()))|\(text)"
+        let start = SourceTimestampBounds.clampedSeconds(start), end = SourceTimestampBounds.clampedSeconds(end)
+        return "\(Int((start * 1000).rounded()))|\(Int((end * 1000).rounded()))|\(text)"
     }
 
     func setShiftSeconds(_ s: Double) { lock.lock(); shiftSeconds = s; lock.unlock() }
diff --git a/Sources/AetherEngine/Subtitles/SubtitlePacketStore.swift b/Sources/AetherEngine/Subtitles/SubtitlePacketStore.swift
index e16602cd2..1374cd9e2 100644
--- a/Sources/AetherEngine/Subtitles/SubtitlePacketStore.swift
+++ b/Sources/AetherEngine/Subtitles/SubtitlePacketStore.swift
@@ -305,6 +305,12 @@ final class SubtitlePacketStore: @unchecked Sendable {
     func harvestChunk(streamIndex: Int32, ptsSeconds: Double?, durationSeconds: Double,
                       flags: Int32, payload: Data, assembleSplitDisplaySets: Bool,
                       writer: Writer = .pump, webvttSettings: String? = nil) {
+        // Audit FEA-101: the pump, the software-host tap and the prefetcher all store through here,
+        // and the drain scales these seconds back into Int64 milliseconds. Same rule as the
+        // demuxer's bound: an implausible time is unset, an implausible duration is 0.
+        let bound = SourceTimestampBounds.maxPlausibleSeconds
+        let ptsSeconds = ptsSeconds.flatMap { $0.isFinite && abs($0) < bound ? $0 : nil }
+        let durationSeconds = durationSeconds.isFinite && durationSeconds < bound ? Swift.max(0, durationSeconds) : 0
         lock.lock(); defer { lock.unlock() }
         // #416: a harvested packet is a position its writer demonstrably read, so the run reaches
         // it. This is what gives the pump the forward lookahead its playhead-based note cannot
diff --git a/Sources/AetherEngine/Subtitles/WebVTTBuilder.swift b/Sources/AetherEngine/Subtitles/WebVTTBuilder.swift
index fa106b36f..af4938802 100644
--- a/Sources/AetherEngine/Subtitles/WebVTTBuilder.swift
+++ b/Sources/AetherEngine/Subtitles/WebVTTBuilder.swift
@@ -41,7 +41,7 @@ enum WebVTTBuilder {
     }
 
     private static func timestamp(_ seconds: Double) -> String {
-        let total = max(0, seconds)
+        let total = max(0, SourceTimestampBounds.clampedSeconds(seconds))
         let whole = Int(total)
         let h = whole / 3600
         let m = (whole % 3600) / 60
diff --git a/Tests/AetherEngineTests/SubtitleTimeBackstopTests.swift b/Tests/AetherEngineTests/SubtitleTimeBackstopTests.swift
new file mode 100644
index 000000000..51bdf0a40
--- /dev/null
+++ b/Tests/AetherEngineTests/SubtitleTimeBackstopTests.swift
@@ -0,0 +1,90 @@
+import Foundation
+import Testing
+import AetherLibavcodec
+@testable import AetherEngine
+
+/// Audit FEA-101 / SUB-105: cue times reach the stores and formatters from more than the demuxer
+/// (live WebVTT renditions, external stores, a host calling the public builder), so every Double to
+/// integer conversion on a cue time is total: a huge, infinite or NaN time degrades, it never traps.
+@Suite("Hostile cue times never trap a subtitle store or formatter")
+struct SubtitleTimeBackstopTests {
+
+    private func subripDecoder() throws -> (Demuxer, EmbeddedSubtitleDecoder) {
+        let demuxer = Demuxer()
+        try demuxer.open(reader: DataIOReader(data: HostileTimestampMatroska.make(
+            blocks: [.init(cluster: 0, duration: 1000)])), formatHint: "matroska")
+        let stream = try #require(demuxer.stream(at: 0))
+        let decoder = try #require(EmbeddedSubtitleDecoder(stream: stream, sourceVideoWidth: 16, sourceVideoHeight: 16))
+        return (demuxer, decoder)
+    }
+
+    @Test("the drain rebuilds a stored packet whose seconds do not fit Int64 milliseconds")
+    func drainDecodeOfOutOfRangeSeconds() throws {
+        let (demuxer, decoder) = try subripDecoder()
+        defer { demuxer.close() }
+        let payload = Data("line".utf8)
+        let hugeDuration = StoredSubtitlePacket(ptsSeconds: 1, durationSeconds: 9.3e15, flags: 0, payload: payload)
+        #expect(AetherEngine.decodeStoredSubtitlePacket(hugeDuration, with: decoder)?.cues.first?.startTime == 1)
+        let hugePTS = StoredSubtitlePacket(ptsSeconds: Double(Int64.max) * 1e-3 * 1000, durationSeconds: 1,
+                                           flags: 0, payload: payload)
+        _ = AetherEngine.decodeStoredSubtitlePacket(hugePTS, with: decoder)
+        let infinite = StoredSubtitlePacket(ptsSeconds: .infinity, durationSeconds: .nan, flags: 0, payload: payload)
+        _ = AetherEngine.decodeStoredSubtitlePacket(infinite, with: decoder)
+    }
+
+    @Test("the store unsets implausible times and zeroes implausible durations for every writer")
+    func harvestBoundsTimes() throws {
+        let (demuxer, decoder) = try subripDecoder()
+        defer { demuxer.close() }
+        let store = SubtitlePacketStore()
+        let payload = Data("line".utf8)
+        store.harvestChunk(streamIndex: 0, ptsSeconds: 1, durationSeconds: 9.2e15, flags: 0,
+                           payload: payload, assembleSplitDisplaySets: false, writer: .prefetch)
+        store.harvestChunk(streamIndex: 0, ptsSeconds: 2, durationSeconds: .infinity, flags: 0,
+                           payload: payload, assembleSplitDisplaySets: false)
+        store.harvestChunk(streamIndex: 0, ptsSeconds: 3, durationSeconds: 0.5, flags: 0,
+                           payload: payload, assembleSplitDisplaySets: false)
+        store.harvestChunk(streamIndex: 0, ptsSeconds: .infinity, durationSeconds: 1, flags: 0,
+                           payload: payload, assembleSplitDisplaySets: false)
+        store.harvestChunk(streamIndex: 0, ptsSeconds: Double(Int64.max) * 1e-3, durationSeconds: 1, flags: 0,
+                           payload: payload, assembleSplitDisplaySets: false)
+        let entries = store.entries(streamIndex: 0, from: -.infinity, through: .infinity)
+        #expect(entries.map(\.ptsSeconds) == [1, 2, 3])
+        #expect(entries.map(\.durationSeconds) == [0, 0, 0.5])
+        for entry in entries {
+            #expect(AetherEngine.decodeStoredSubtitlePacket(entry, with: decoder) != nil)
+        }
+    }
+
+    @Test("the native cue store dedupes cues at huge and non-finite times")
+    func cueStoreKeys() {
+        let store = NativeSubtitleCueStore()
+        store.appendCues([
+            SubtitleCue(id: 1, startTime: 1e16, endTime: 1e16 + 1, body: .text("far")),
+            SubtitleCue(id: 2, startTime: .infinity, endTime: .infinity, body: .text("inf")),
+            SubtitleCue(id: 3, startTime: .nan, endTime: .nan, body: .text("nan")),
+            SubtitleCue(id: 4, startTime: 1, endTime: 2, body: .text("near")),
+        ])
+        #expect(store.cueCount == 4)
+    }
+
+    @Test("the public ASS timestamp formatter pins huge and non-finite input")
+    func assTimestamp() {
+        #expect(ASSScriptBuilder.timestamp(3661.5) == "1:01:01.50")
+        #expect(ASSScriptBuilder.timestamp(-3) == "0:00:00.00")
+        #expect(ASSScriptBuilder.timestamp(.nan) == "0:00:00.00")
+        #expect(ASSScriptBuilder.timestamp(.infinity) == ASSScriptBuilder.timestamp(1e300))
+        #expect(ASSScriptBuilder.timestamp(1e17) == ASSScriptBuilder.timestamp(4e9))
+    }
+
+    @Test("the WebVTT body survives cues at huge and non-finite times")
+    func webVTTTimestamps() {
+        let vtt = WebVTTBuilder.body(cues: [
+            (start: 1, end: 2, text: "near"),
+            (start: 1e19, end: .infinity, text: "far"),
+            (start: .nan, end: .nan, text: "nan"),
+        ])
+        #expect(vtt.contains("00:00:01.000 --> 00:00:02.000\nnear"))
+        #expect(vtt.contains("far"))
+    }
+}

From 844d5e4330601998030cce8ed96b0f9a5eb246a0 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 06:34:46 +0200
Subject: [PATCH 165/359] fix(h264): refuse a #409 re-anchor whose arithmetic
 leaves Int64 (audit BIT-101)

After a seek the landing keyframe re-anchored the sequence with a plain
`dts - landingIndex * plan.step`. In fragmented MP4 the step comes from
the 64-bit `tfdt` and the landing picture order can sit near -2^31
through `delta_pic_order_cnt_bottom`, so a crafted file trapped the demux
thread on seek or resume. The product and the difference are now checked;
on overflow the picture stays unrepaired and the next keyframe re-anchors.
`presentationShift` subtracts with the same check and falls back to no
shift.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../Video/H264CompositionOffsetRepair.swift   | 12 ++++++++--
 .../H264CompositionOffsetRepairTests.swift    | 23 +++++++++++++++++++
 2 files changed, 33 insertions(+), 2 deletions(-)

diff --git a/Sources/AetherEngine/Video/H264CompositionOffsetRepair.swift b/Sources/AetherEngine/Video/H264CompositionOffsetRepair.swift
index 780ef5080..5a3ba7aa8 100644
--- a/Sources/AetherEngine/Video/H264CompositionOffsetRepair.swift
+++ b/Sources/AetherEngine/Video/H264CompositionOffsetRepair.swift
@@ -195,7 +195,8 @@ enum H264CompositionOffsetRepair {
         decodeLead: Int64
     ) -> Int64 {
         guard streamStartTime != Int64.min, ladderStart != Int64.min, decodeLead > 0 else { return 0 }
-        let raw = streamStartTime - ladderStart
+        let (raw, overflow) = streamStartTime.subtractingReportingOverflow(ladderStart)
+        guard !overflow else { return 0 }
         return min(max(raw, 0), decodeLead)
     }
 
@@ -463,7 +464,14 @@ enum H264CompositionOffsetRepair {
                     return nil
                 }
                 let landingIndex = pictureOrderCount / plan.pocStep
-                sequenceAnchorDTS = dts - landingIndex * plan.step
+                // Audit BIT-101: a 64-bit `tfdt` step and a landing order near -2^31 leave Int64.
+                let (landingTicks, productOverflow) = landingIndex.multipliedReportingOverflow(by: plan.step)
+                let (anchor, anchorOverflow) = dts.subtractingReportingOverflow(landingTicks)
+                guard !productOverflow, !anchorOverflow else {
+                    unrepairedPictures += 1
+                    return nil
+                }
+                sequenceAnchorDTS = anchor
                 sequenceBaseOrdinal = plan.presentationOrdinal(ladderTimestamp: dts)
                     .flatMap { ordinal -> Int64? in
                         let (base, overflow) = ordinal.subtractingReportingOverflow(landingIndex)
diff --git a/Tests/AetherEngineTests/H264CompositionOffsetRepairTests.swift b/Tests/AetherEngineTests/H264CompositionOffsetRepairTests.swift
index 322edeccb..d01688edd 100644
--- a/Tests/AetherEngineTests/H264CompositionOffsetRepairTests.swift
+++ b/Tests/AetherEngineTests/H264CompositionOffsetRepairTests.swift
@@ -177,6 +177,29 @@ struct H264CompositionOffsetRepairTests {
         #expect(landingDTS == 498498)
     }
 
+    /// Audit BIT-101: in fragmented MP4 the step comes from `tfdt` (64-bit) and a landing picture
+    /// order can sit near -2^31 through `delta_pic_order_cnt_bottom`, so the re-anchor product
+    /// leaves Int64. The picture stays unrepaired and the next keyframe gets another chance.
+    @Test("a re-anchor whose arithmetic leaves Int64 is refused, not trapped on")
+    func reanchorOverflowIsRefused() {
+        var rewriter = H264CompositionOffsetRepair.Rewriter(
+            plan: H264CompositionOffsetRepair.Plan(step: 1 << 34, decodeLead: 1 << 35, shift: 0, pocStep: 2))
+        rewriter.noteSeek()
+        #expect(rewriter.rewrite(dts: 1 << 40, pictureOrderCount: -2_147_482_646, isKeyframe: true) == nil)
+        #expect(rewriter.unrepairedPictures == 1)
+        #expect(rewriter.sequenceAnchorDTS == nil)
+        let landing = rewriter.rewrite(dts: 1 << 40, pictureOrderCount: 0, isKeyframe: true)
+        #expect(landing?.pts == 1 << 40)
+    }
+
+    @Test("a presentation shift between opposite ends of Int64 falls back to no shift")
+    func presentationShiftOverflow() {
+        #expect(H264CompositionOffsetRepair.presentationShift(
+            streamStartTime: Int64.max - 1, ladderStart: -(Int64.max - 1), decodeLead: 2002) == 0)
+        #expect(H264CompositionOffsetRepair.presentationShift(
+            streamStartTime: -(Int64.max - 1), ladderStart: Int64.max - 1, decodeLead: 2002) == 0)
+    }
+
     @Test("without an anchor a picture is emitted untouched rather than guessed at")
     func passesThroughWithoutAnchor() {
         var rewriter = H264CompositionOffsetRepair.Rewriter(plan: plan)

From 4ff033cc93d63e115ca96ee51cfef7391179ce32 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 06:34:46 +0200
Subject: [PATCH 166/359] fix(segment): cap the NOPTS walk and make the output
 timestamp guards total (audit SEG-101)

A packet with neither dts nor pts advanced by its own duration with no
cap, so nine crafted BlockDurations just under the producer's 2^60 bound
walked the synthesized dts to Int64.max, and `OutputTimestampSanitizer`
trapped on the next `last + 1`.

`repairStrideTicks` caps every arm at one second of ticks, the cap
`updatedStrideTicks` already applies to a learned stride, and a packet
whose synthesized dts would leave the plausible range is dropped until a
genuine timestamp re-anchors the stream. The sanitizer returns nil when no
dts after the last one exists and the muxer drops that packet. The dts
bumps, the buffered-fragment bound and the no-cut watchdog's advance use
checked or saturating arithmetic.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../Video/HLSSegmentProducer.swift            | 35 +++++++++++----
 .../AetherEngine/Video/MP4SegmentMuxer.swift  | 10 +++--
 .../Video/NoCutStallWatchdog.swift            |  2 +-
 .../Video/OutputTimestampSanitizer.swift      |  8 +++-
 .../Issue406NoCutWatchdogTests.swift          | 16 +++++++
 ...ue432SynthesizedTimestampStrideTests.swift | 35 +++++++++++++++
 .../Issue464AudioDelayTests.swift             |  5 ++-
 .../MuxerBufferBoundTests.swift               |  8 ++++
 .../OutputTimestampSanitizerTests.swift       | 44 ++++++++++++-------
 9 files changed, 129 insertions(+), 34 deletions(-)

diff --git a/Sources/AetherEngine/Video/HLSSegmentProducer.swift b/Sources/AetherEngine/Video/HLSSegmentProducer.swift
index 7eca8b7c4..a3132e90b 100644
--- a/Sources/AetherEngine/Video/HLSSegmentProducer.swift
+++ b/Sources/AetherEngine/Video/HLSSegmentProducer.swift
@@ -709,15 +709,27 @@ final class HLSSegmentProducer: @unchecked Sendable {
     /// Cascade, most specific first: the demuxer's own claim for this packet, then the last genuine
     /// delta this stream showed, then the frame duration the producer already carries for the last
     /// trun sample, then the historical single tick for a stream that has never carried a usable
-    /// timestamp at all.
+    /// timestamp at all. Each arm is capped at `maxStrideTicks` (audit SEG-101: a crafted
+    /// BlockDuration near the source bound walked nine packets to Int64.max), the same second
+    /// `updatedStrideTicks` already applies to a learned stride.
     static func repairStrideTicks(packetDuration: Int64, observedStride: Int64,
-                                  fallbackDuration: Int64) -> Int64 {
-        if packetDuration > 0 { return packetDuration }
-        if observedStride > 0 { return observedStride }
-        if fallbackDuration > 0 { return fallbackDuration }
+                                  fallbackDuration: Int64, maxStrideTicks: Int64 = .max) -> Int64 {
+        let cap = Swift.max(maxStrideTicks, 1)
+        if packetDuration > 0 { return Swift.min(packetDuration, cap) }
+        if observedStride > 0 { return Swift.min(observedStride, cap) }
+        if fallbackDuration > 0 { return Swift.min(fallbackDuration, cap) }
         return 1
     }
 
+    /// Audit SEG-101: the dts a packet with neither timestamp gets, or nil when the walk would leave
+    /// the plausible source range. The packet is then dropped, and the next genuine timestamp
+    /// re-anchors the stream.
+    static func synthesizedDts(anchor: Int64, stride: Int64) -> Int64? {
+        let (dts, overflow) = anchor.addingReportingOverflow(stride)
+        guard !overflow, SourceTimestampBounds.plausible(dts) == dts else { return nil }
+        return dts
+    }
+
     /// Adopts `dts - previousDts` as the stream's stride when it is forward and inside
     /// `maxStrideTicks`. A backward, standing or multi-second delta is a boundary or a replay, so
     /// the stride learned before it survives.
@@ -3156,11 +3168,16 @@ final class HLSSegmentProducer: @unchecked Sendable {
                     } else {
                         // Neither timestamp survived. One tick per packet is not a presentation time,
                         // it is a frozen clock; advance by this stream's frame interval instead.
+                        let strideTb = isVideoPkt ? sourceVideoTbSeconds : audioSourceTbSeconds
                         let stride = Self.repairStrideTicks(
                             packetDuration: packet.pointee.duration,
                             observedStride: isVideoPkt ? videoSourceStrideTicks : audioSourceStrideTicks,
-                            fallbackDuration: isVideoPkt ? videoFallbackDurationPts : audioFallbackDurationPts)
-                        packet.pointee.dts = anchor &+ stride
+                            fallbackDuration: isVideoPkt ? videoFallbackDurationPts : audioFallbackDurationPts,
+                            maxStrideTicks: strideTb > 0 ? Int64(Self.maxSynthesizedStrideSeconds / strideTb) : .max)
+                        guard let synthesized = Self.synthesizedDts(anchor: anchor, stride: stride) else {
+                            continue
+                        }
+                        packet.pointee.dts = synthesized
                         packet.pointee.pts = packet.pointee.dts
                         timestampsSynthesized = true
                         noteSynthesizedTimestamp(strideTicks: stride, isVideo: isVideoPkt)
@@ -3431,7 +3448,7 @@ final class HLSSegmentProducer: @unchecked Sendable {
                    packet.pointee.dts <= lastVideoSourceDts,
                    SourceTimestampBounds.difference(lastVideoSourceDts, packet.pointee.dts) <= monoGlitchVideoTicks {
                     let original = packet.pointee.dts
-                    let bumped = lastVideoSourceDts + 1
+                    let bumped = SourceTimestampBounds.sum(lastVideoSourceDts, 1)
                     let ptsValid = packet.pointee.pts != Int64.min
                     if !ptsValid || bumped <= packet.pointee.pts {
                         packet.pointee.dts = bumped
@@ -3472,7 +3489,7 @@ final class HLSSegmentProducer: @unchecked Sendable {
                     // pts/dts skew so dts <= pts isn't a useful gate;
                     // just bump.
                     let original = packet.pointee.dts
-                    packet.pointee.dts = lastAudioSourceDts + 1
+                    packet.pointee.dts = SourceTimestampBounds.sum(lastAudioSourceDts, 1)
                     if !loggedFirstAudioDtsBump {
                         loggedFirstAudioDtsBump = true
                         EngineLog.emit(
diff --git a/Sources/AetherEngine/Video/MP4SegmentMuxer.swift b/Sources/AetherEngine/Video/MP4SegmentMuxer.swift
index 04c77d85f..bdcce0839 100644
--- a/Sources/AetherEngine/Video/MP4SegmentMuxer.swift
+++ b/Sources/AetherEngine/Video/MP4SegmentMuxer.swift
@@ -421,7 +421,8 @@ final class MP4SegmentMuxer {
     /// (a DTS reset) never triggers; boundTicks <= 0 disables the bound.
     static func bufferedTicksExceedsBound(firstDts: Int64, currentDts: Int64, boundTicks: Int64) -> Bool {
         guard boundTicks > 0, firstDts != Int64.min, currentDts >= firstDts else { return false }
-        return (currentDts - firstDts) >= boundTicks
+        let (span, overflow) = currentDts.subtractingReportingOverflow(firstDts)
+        return overflow || span >= boundTicks
     }
 
     // MARK: - Diagnostic probes
@@ -598,11 +599,14 @@ final class MP4SegmentMuxer {
             if packet.pointee.dts != Int64.min { packet.pointee.dts &+= audioDelayTicks }
         }
 
-        let clean = timestampSanitizer.sanitize(
+        guard let clean = timestampSanitizer.sanitize(
             streamIndex: packet.pointee.stream_index,
             pts: packet.pointee.pts,
             dts: packet.pointee.dts
-        )
+        ) else {
+            av_packet_unref(packet)
+            return (0, .none)
+        }
         packet.pointee.pts = clean.pts
         packet.pointee.dts = clean.dts
 
diff --git a/Sources/AetherEngine/Video/NoCutStallWatchdog.swift b/Sources/AetherEngine/Video/NoCutStallWatchdog.swift
index ce749db3a..32ca5cbfb 100644
--- a/Sources/AetherEngine/Video/NoCutStallWatchdog.swift
+++ b/Sources/AetherEngine/Video/NoCutStallWatchdog.swift
@@ -192,7 +192,7 @@ final class NoCutStallWatchdog: @unchecked Sendable {
         let readRate = stalledFor > 0 ? Double(progress) / stalledFor : 0
         let ptsAdvance = (firstVideoPts != Int64.min && lastVideoPts != Int64.min
                           && videoTimeBaseSeconds > 0)
-            ? Double(lastVideoPts - firstVideoPts) * videoTimeBaseSeconds
+            ? Double(SourceTimestampBounds.difference(lastVideoPts, firstVideoPts)) * videoTimeBaseSeconds
             : -1
         switch HLSSegmentProducer.noCutStallAction(
             stalledFor: stalledFor,
diff --git a/Sources/AetherEngine/Video/OutputTimestampSanitizer.swift b/Sources/AetherEngine/Video/OutputTimestampSanitizer.swift
index fd3ebf18d..56db506fd 100644
--- a/Sources/AetherEngine/Video/OutputTimestampSanitizer.swift
+++ b/Sources/AetherEngine/Video/OutputTimestampSanitizer.swift
@@ -4,12 +4,16 @@ import Foundation
 struct OutputTimestampSanitizer {
     private var lastDtsByStream: [Int32: Int64] = [:]
 
-    mutating func sanitize(streamIndex: Int32, pts: Int64, dts: Int64) -> (pts: Int64, dts: Int64) {
+    /// nil when no dts after the stream's last one exists (it already sits at Int64.max, audit
+    /// SEG-101); the caller drops the packet.
+    mutating func sanitize(streamIndex: Int32, pts: Int64, dts: Int64) -> (pts: Int64, dts: Int64)? {
         guard dts != Int64.min else { return (pts, dts) }  // NOPTS: nothing to enforce
 
         var outDts = dts
         if let last = lastDtsByStream[streamIndex], outDts <= last {
-            outDts = last + 1
+            let (bumped, overflow) = last.addingReportingOverflow(1)
+            guard !overflow else { return nil }
+            outDts = bumped
         }
         let outPts = pts == Int64.min ? outDts : max(pts, outDts)  // NOPTS pts collapses to dts (safe floor for audio and video)
 
diff --git a/Tests/AetherEngineTests/Issue406NoCutWatchdogTests.swift b/Tests/AetherEngineTests/Issue406NoCutWatchdogTests.swift
index 66083f210..09719fa04 100644
--- a/Tests/AetherEngineTests/Issue406NoCutWatchdogTests.swift
+++ b/Tests/AetherEngineTests/Issue406NoCutWatchdogTests.swift
@@ -200,6 +200,22 @@ struct Issue406NoCutWatchdogTests {
         #expect(abs(window.videoPtsAdvanceSeconds - 0.36) < 0.001)  // 9 * 3600 ticks at 90 kHz
     }
 
+    @Test("a PTS advance across opposite ends of Int64 saturates instead of trapping (audit SEG-101)")
+    func ptsAdvanceSaturates() {
+        let w = makeWatchdog()
+        w.noteFinalize(at: t0)
+        w.notePacketRead()
+        w.noteVideoPacket(pts: Int64.min + 1, isKeyframe: true)
+        w.notePacketRead()
+        w.noteVideoPacket(pts: Int64.max, isKeyframe: false)
+        guard case .exitForRetune(let window)? = w.evaluate(now: t0.addingTimeInterval(36)) else {
+            Issue.record("expected an exit")
+            return
+        }
+        #expect(window.videoPtsAdvanceSeconds > 0)
+        #expect(window.videoPtsAdvanceSeconds.isFinite)
+    }
+
     @Test("a video packet without a PTS does not open the advance window")
     func noptsVideoIsNotAnAdvance() {
         let w = makeWatchdog()
diff --git a/Tests/AetherEngineTests/Issue432SynthesizedTimestampStrideTests.swift b/Tests/AetherEngineTests/Issue432SynthesizedTimestampStrideTests.swift
index 8757a90a8..f085244ef 100644
--- a/Tests/AetherEngineTests/Issue432SynthesizedTimestampStrideTests.swift
+++ b/Tests/AetherEngineTests/Issue432SynthesizedTimestampStrideTests.swift
@@ -51,6 +51,41 @@ struct Issue432SynthesizedTimestampStrideTests {
             packetDuration: -1, observedStride: -5, fallbackDuration: -40) == 1)
     }
 
+    /// Audit SEG-101: the packet-duration arm was the one left uncapped, so a crafted BlockDuration
+    /// just under the source bound walked nine packets to Int64.max.
+    @Test("every arm of the cascade is capped at one second of ticks")
+    func strideIsCapped() {
+        let cap: Int64 = 90_000
+        #expect(HLSSegmentProducer.repairStrideTicks(
+            packetDuration: (1 << 60) - 1, observedStride: 0, fallbackDuration: 0, maxStrideTicks: cap) == cap)
+        #expect(HLSSegmentProducer.repairStrideTicks(
+            packetDuration: 0, observedStride: 1 << 40, fallbackDuration: 0, maxStrideTicks: cap) == cap)
+        #expect(HLSSegmentProducer.repairStrideTicks(
+            packetDuration: 0, observedStride: 0, fallbackDuration: 1 << 40, maxStrideTicks: cap) == cap)
+        #expect(HLSSegmentProducer.repairStrideTicks(
+            packetDuration: 1800, observedStride: 0, fallbackDuration: 0, maxStrideTicks: cap) == 1800)
+        #expect(HLSSegmentProducer.repairStrideTicks(
+            packetDuration: 1800, observedStride: 0, fallbackDuration: 0, maxStrideTicks: 0) == 1)
+    }
+
+    @Test("a synthesized timestamp that would leave the source range drops the packet instead")
+    func synthesizedWalkStaysInRange() {
+        #expect(HLSSegmentProducer.synthesizedDts(anchor: 1000, stride: 1800) == 2800)
+        #expect(HLSSegmentProducer.synthesizedDts(anchor: (1 << 60) - 10, stride: 90_000) == nil)
+        #expect(HLSSegmentProducer.synthesizedDts(anchor: Int64.max - 5, stride: 10) == nil)
+        var anchor: Int64 = 0
+        for _ in 0..<9 {
+            let stride = HLSSegmentProducer.repairStrideTicks(
+                packetDuration: (1 << 60) - 1, observedStride: 0, fallbackDuration: 0, maxStrideTicks: 90_000)
+            guard let next = HLSSegmentProducer.synthesizedDts(anchor: anchor, stride: stride) else {
+                Issue.record("a one-second stride from 0 cannot leave the range")
+                return
+            }
+            anchor = next
+        }
+        #expect(anchor == 9 * 90_000)
+    }
+
     // MARK: - Learning the stride from the source
 
     @Test("a forward delta inside the cap becomes the stride")
diff --git a/Tests/AetherEngineTests/Issue464AudioDelayTests.swift b/Tests/AetherEngineTests/Issue464AudioDelayTests.swift
index 281ef0ae4..cdb432bb8 100644
--- a/Tests/AetherEngineTests/Issue464AudioDelayTests.swift
+++ b/Tests/AetherEngineTests/Issue464AudioDelayTests.swift
@@ -111,7 +111,7 @@ struct Issue464PlacementRationaleTests {
     }
 
     @Test("a backwards audio step is clamped away, so a smaller offset cannot be spliced mid-track")
-    func sanitizerEatsABackwardsStep() {
+    func sanitizerEatsABackwardsStep() throws {
         // The naive loopback implementation lowers the muxer's offset and keeps cutting into the same
         // output track. OutputTimestampSanitizer enforces strictly increasing DTS per stream, so the
         // overlap the change creates is not delivered: it is clamped to last+1 and the audio stays
@@ -119,7 +119,8 @@ struct Issue464PlacementRationaleTests {
         var sanitizer = OutputTimestampSanitizer()
         let audio: Int32 = 1
         _ = sanitizer.sanitize(streamIndex: audio, pts: 48000, dts: 48000)
-        let stepBack = sanitizer.sanitize(streamIndex: audio, pts: 43200, dts: 43200)   // -100 ms @48k
+        let clamped = sanitizer.sanitize(streamIndex: audio, pts: 43200, dts: 43200)   // -100 ms @48k
+        let stepBack = try #require(clamped)
         #expect(stepBack.dts == 48001, "the backwards step was clamped, not honoured")
         #expect(stepBack.pts >= stepBack.dts)
     }
diff --git a/Tests/AetherEngineTests/MuxerBufferBoundTests.swift b/Tests/AetherEngineTests/MuxerBufferBoundTests.swift
index ccfd756b8..15d1fbb8a 100644
--- a/Tests/AetherEngineTests/MuxerBufferBoundTests.swift
+++ b/Tests/AetherEngineTests/MuxerBufferBoundTests.swift
@@ -60,4 +60,12 @@ struct MuxerBufferBoundTests {
         #expect(MP4SegmentMuxer.bufferedTicksExceedsBound(
             firstDts: 0, currentDts: 10_000_000, boundTicks: 0) == false)
     }
+
+    @Test("A span wider than Int64 counts as past the bound instead of trapping (audit SEG-101)")
+    func spanOverflow() {
+        #expect(MP4SegmentMuxer.bufferedTicksExceedsBound(
+            firstDts: Int64.min + 1, currentDts: Int64.max, boundTicks: 128_000))
+        #expect(MP4SegmentMuxer.bufferedTicksExceedsBound(
+            firstDts: -(Int64(1) << 62), currentDts: Int64(1) << 62, boundTicks: Int64.max))
+    }
 }
diff --git a/Tests/AetherEngineTests/OutputTimestampSanitizerTests.swift b/Tests/AetherEngineTests/OutputTimestampSanitizerTests.swift
index 539647045..fd2fec9df 100644
--- a/Tests/AetherEngineTests/OutputTimestampSanitizerTests.swift
+++ b/Tests/AetherEngineTests/OutputTimestampSanitizerTests.swift
@@ -5,56 +5,56 @@ final class OutputTimestampSanitizerTests: XCTestCase {
 
     // MARK: - Healthy content is untouched
 
-    func testMonotonicAudioPassThroughUnchanged() {
+    func testMonotonicAudioPassThroughUnchanged() throws {
         var s = OutputTimestampSanitizer()
         for i in 0..<5 {
             let t = Int64(1000 + i * 1024)
-            let out = s.sanitize(streamIndex: 1, pts: t, dts: t)
+            let out = try XCTUnwrap(s.sanitize(streamIndex: 1, pts: t, dts: t))
             XCTAssertEqual(out.dts, t)
             XCTAssertEqual(out.pts, t)
         }
     }
 
-    func testVideoBFramePtsAboveDtsPreserved() {
+    func testVideoBFramePtsAboveDtsPreserved() throws {
         var s = OutputTimestampSanitizer()
-        let out = s.sanitize(streamIndex: 0, pts: 2000, dts: 1000)
+        let out = try XCTUnwrap(s.sanitize(streamIndex: 0, pts: 2000, dts: 1000))
         XCTAssertEqual(out.dts, 1000)
         XCTAssertEqual(out.pts, 2000)
     }
 
     // MARK: - The SSAI ad-boundary failure (exact device-log values)
 
-    func testAudioPtsBelowDtsIsLiftedToDts() {
+    func testAudioPtsBelowDtsIsLiftedToDts() throws {
         // Device log (Beverly Hills 90210 Pluto ad boundary):
         //   pts (6391809) < dts (6679426) in stream 1
         // Audio carries no reordering, so the fix is pts := dts.
         var s = OutputTimestampSanitizer()
         _ = s.sanitize(streamIndex: 1, pts: 6679425, dts: 6679425) // prior packet
-        let out = s.sanitize(streamIndex: 1, pts: 6391809, dts: 6679426)
+        let out = try XCTUnwrap(s.sanitize(streamIndex: 1, pts: 6391809, dts: 6679426))
         XCTAssertEqual(out.dts, 6679426)
         XCTAssertEqual(out.pts, 6679426, "audio pts must be lifted to dts (no reordering)")
         XCTAssertGreaterThanOrEqual(out.pts, out.dts)
     }
 
-    func testEqualDtsCollisionIsBumped() {
+    func testEqualDtsCollisionIsBumped() throws {
         // Device log: "non monotonically increasing dts ... 6679425 >= 6679425"
         var s = OutputTimestampSanitizer()
         _ = s.sanitize(streamIndex: 1, pts: 6679425, dts: 6679425)
-        let out = s.sanitize(streamIndex: 1, pts: 6679425, dts: 6679425)
+        let out = try XCTUnwrap(s.sanitize(streamIndex: 1, pts: 6679425, dts: 6679425))
         XCTAssertEqual(out.dts, 6679426, "colliding dts must be bumped past the last written")
         XCTAssertEqual(out.pts, 6679426)
     }
 
-    func testBackwardDtsResetIsForcedMonotonic() {
+    func testBackwardDtsResetIsForcedMonotonic() throws {
         // SSAI creative restarts source clock at 2^33; rescaled dts can land far below the last written value.
         var s = OutputTimestampSanitizer()
         _ = s.sanitize(streamIndex: 1, pts: 10_000, dts: 10_000)
-        let out = s.sanitize(streamIndex: 1, pts: 2_000, dts: 2_000)
+        let out = try XCTUnwrap(s.sanitize(streamIndex: 1, pts: 2_000, dts: 2_000))
         XCTAssertEqual(out.dts, 10_001)
         XCTAssertEqual(out.pts, 10_001)
     }
 
-    func testWholeAdBurstStaysMonotonicAndPtsGEDts() {
+    func testWholeAdBurstStaysMonotonicAndPtsGEDts() throws {
         // Replays the Beverly Hills 90210 / Pluto stall shape: dts collides/regresses, pts trails dts; both pathologies at once.
         var s = OutputTimestampSanitizer()
         _ = s.sanitize(streamIndex: 1, pts: 6679425, dts: 6679425)
@@ -62,7 +62,7 @@ final class OutputTimestampSanitizerTests: XCTestCase {
         for i in 0..<200 {
             let pts = Int64(6391809 + i * 1024)
             let dts = Int64(6679425) // constant, colliding
-            let out = s.sanitize(streamIndex: 1, pts: pts, dts: dts)
+            let out = try XCTUnwrap(s.sanitize(streamIndex: 1, pts: pts, dts: dts))
             XCTAssertGreaterThan(out.dts, lastDts, "dts must strictly increase")
             XCTAssertGreaterThanOrEqual(out.pts, out.dts, "pts must be >= dts")
             lastDts = out.dts
@@ -71,17 +71,27 @@ final class OutputTimestampSanitizerTests: XCTestCase {
 
     // MARK: - Per-stream independence
 
-    func testStreamsTrackedIndependently() {
+    func testStreamsTrackedIndependently() throws {
         var s = OutputTimestampSanitizer()
-        let a = s.sanitize(streamIndex: 1, pts: 5000, dts: 5000)
-        let v = s.sanitize(streamIndex: 0, pts: 100, dts: 100)
+        let a = try XCTUnwrap(s.sanitize(streamIndex: 1, pts: 5000, dts: 5000))
+        let v = try XCTUnwrap(s.sanitize(streamIndex: 0, pts: 100, dts: 100))
         XCTAssertEqual(a.dts, 5000)
         XCTAssertEqual(v.dts, 100, "video stream is independent of audio's high-water mark")
     }
 
-    func testNoptsDtsPassedThrough() {
+    // MARK: - Hostile input (audit SEG-101)
+
+    func testDtsAtInt64MaxCannotBeBumpedAndIsDropped() {
+        var s = OutputTimestampSanitizer()
+        _ = s.sanitize(streamIndex: 0, pts: Int64.max, dts: Int64.max)
+        XCTAssertNil(s.sanitize(streamIndex: 0, pts: 0, dts: 0), "no dts after Int64.max exists, so the packet is dropped")
+        XCTAssertNil(s.sanitize(streamIndex: 0, pts: Int64.max, dts: Int64.max))
+        XCTAssertEqual(s.sanitize(streamIndex: 1, pts: 5, dts: 5)?.dts, 5, "the other stream keeps its own high-water mark")
+    }
+
+    func testNoptsDtsPassedThrough() throws {
         var s = OutputTimestampSanitizer()
-        let out = s.sanitize(streamIndex: 0, pts: 123, dts: Int64.min)
+        let out = try XCTUnwrap(s.sanitize(streamIndex: 0, pts: 123, dts: Int64.min))
         XCTAssertEqual(out.dts, Int64.min)
         XCTAssertEqual(out.pts, 123)
     }

From b8cecf8c8a50d51a67e6a59fba3a4da392af8073 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 06:35:47 +0200
Subject: [PATCH 167/359] fix(display): switch waits end with their load and
 share one observed-end budget (audit LIF-106, DEC-105)

Both `waitForSwitch` loops polled with `try? await Task.sleep`, so a load
whose task the host cancelled (Sodalite on Back and on every zap) spun
the main actor until the switch cap, and a superseded load kept polling
to its end. Each tick now goes through `gateTick`, which returns on
cancellation or when the caller's `isCurrent` (the load generation at
all four call sites: pre-flight, the #667 wait, the play gate and the
reload play gate) says the load is gone, and logs the abandonment.

The 6 s observed-end cap was per gate. The #667 wait leaves the record
unspent for the play gate, so on a panel whose end is never announced or
whose in-progress flag sticks both spent the full cap on one switch. The
first gate that waits on an armed switch now sets a deadline, and a later
gate on the same arm gets what is left of it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../AetherEngine/AetherEngine+Loading.swift   |  3 +-
 Sources/AetherEngine/AetherEngine.swift       |  9 +-
 .../Display/DisplayCriteriaController.swift   | 63 ++++++++++++--
 .../DisplaySwitchWaitBudgetTests.swift        | 84 +++++++++++++++++++
 .../Issue667MasterAfterSwitchTests.swift      |  2 +-
 5 files changed, 150 insertions(+), 11 deletions(-)
 create mode 100644 Tests/AetherEngineTests/DisplaySwitchWaitBudgetTests.swift

diff --git a/Sources/AetherEngine/AetherEngine+Loading.swift b/Sources/AetherEngine/AetherEngine+Loading.swift
index 53dfa3910..8cd100ee4 100644
--- a/Sources/AetherEngine/AetherEngine+Loading.swift
+++ b/Sources/AetherEngine/AetherEngine+Loading.swift
@@ -2523,7 +2523,8 @@ extension AetherEngine {
                         formatKnown: true,
                         effectiveFormat: videoFormat
                     ),
-                    settleCap: loadedOptions.isLive ? .standard : .awaitObservedEnd)
+                    settleCap: loadedOptions.isLive ? .standard : .awaitObservedEnd,
+                    isCurrent: { self.loadGeneration == gen })
                 try checkLoadCurrent(gen)
                 if resumesPlaying { nativeHost?.play() }
             }
diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index 5383ec0cf..78a403a49 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -4488,7 +4488,8 @@ public final class AetherEngine: ObservableObject {
                 didSwitchPanel = true
                 // #339: consumesRecord: false, the play gate after loadNative is entitled to the same
                 // start/end timestamps; spending them here made it pay Stage 1's grace for a settled switch.
-                await displayCriteria.waitForSwitch(consumesRecord: false)
+                await displayCriteria.waitForSwitch(consumesRecord: false,
+                                                    isCurrent: { self.loadGeneration == gen })
                 // Superseded during panel handshake: close local probe and unwind.
                 if loadGeneration != gen {
                     probe.markClosed()
@@ -4553,7 +4554,8 @@ public final class AetherEngine: ObservableObject {
                 "[DisplayCriteria] unproven HDR master waits for the running switch to end before it is "
                 + "served (#667)",
                 category: .session)
-            await displayCriteria.waitForSwitch(consumesRecord: false, settleCap: .awaitObservedEnd)
+            await displayCriteria.waitForSwitch(consumesRecord: false, settleCap: .awaitObservedEnd,
+                                                isCurrent: { self.loadGeneration == gen })
             if loadGeneration != gen {
                 probe.markClosed()
                 if probeOpened {
@@ -4992,7 +4994,8 @@ public final class AetherEngine: ObservableObject {
                     // Sodalite#49: this gate runs after the item is ready, so waiting out an observed switch
                     // blocks nothing else, and the panel is dark until it ends either way. Live keeps the
                     // standard cap: a zap must not sit behind a panel handshake.
-                    settleCap: options.isLive ? .standard : .awaitObservedEnd)
+                    settleCap: options.isLive ? .standard : .awaitObservedEnd,
+                    isCurrent: { self.loadGeneration == gen })
                 try checkLoadCurrent(gen)
                 // automaticallyWaitsToMinimizeStalling=true (default) handles play-before-ready.
                 // #35: on a real SDR->HDR switch while serving a VOD master, drive the bounded
diff --git a/Sources/AetherEngine/Display/DisplayCriteriaController.swift b/Sources/AetherEngine/Display/DisplayCriteriaController.swift
index f5751b3ac..0b0bb5504 100644
--- a/Sources/AetherEngine/Display/DisplayCriteriaController.swift
+++ b/Sources/AetherEngine/Display/DisplayCriteriaController.swift
@@ -44,6 +44,8 @@ final class DisplayCriteriaController {
     /// #339: armed at the criteria write, not when the play gate opens, so an engine-written switch is
     /// observable end to end instead of having to be guessed at from the in-progress flag.
     private let observation = SwitchObservation()
+    /// DEC-105: what is left of the observed-end wait for the armed switch (`observedEndCap`).
+    private var observedEndBudget: ObservedEndBudget?
     #endif
 
     /// The arm generation whose record has been spent. Only a gate that ends the load's wait spends it, so
@@ -156,6 +158,40 @@ final class DisplayCriteriaController {
         return observedEndCapMs
     }
 
+    /// The observed-end wait left for one armed switch, shared by every gate that waits on it.
+    struct ObservedEndBudget: Equatable {
+        let armGeneration: Int
+        let deadlineNanos: UInt64
+    }
+
+    /// DEC-105: `observedEndCapMs` is one budget per armed switch, not per gate. The #667 wait leaves the
+    /// record unspent for the play gate, so on a panel whose end is never announced (or whose in-progress
+    /// flag sticks) both read the same `.running`, and each used to spend the whole cap on one switch.
+    /// The first gate to wait sets the deadline; a later gate on the same arm gets what is left of it.
+    nonisolated static func observedEndCap(settleCap: SettleCap, startRecorded: Bool, armGeneration: Int,
+                                           nowNanos: UInt64, budget: ObservedEndBudget?)
+        -> (capMs: Int, budget: ObservedEndBudget?) {
+        let capMs = settleCapMs(cap: settleCap, startRecorded: startRecorded)
+        guard capMs == observedEndCapMs, armGeneration != 0 else { return (capMs, budget) }
+        if let budget, budget.armGeneration == armGeneration {
+            return (min(capMs, elapsedMs(fromNanos: nowNanos, toNanos: budget.deadlineNanos)), budget)
+        }
+        let deadline = nowNanos &+ UInt64(capMs) * 1_000_000
+        return (capMs, ObservedEndBudget(armGeneration: armGeneration, deadlineNanos: deadline))
+    }
+
+    /// Audit LIF-106: one poll of a switch wait. False once the load waiting on it is gone: its task
+    /// was cancelled (a cancelled `Task.sleep` returns at once, so the `try?` these loops used turned
+    /// them into a hot spin on the main actor until the cap) or a newer load or stop superseded it.
+    static func gateTick(milliseconds: Int, isCurrent: () -> Bool) async -> Bool {
+        do {
+            try await Task.sleep(for: .milliseconds(milliseconds))
+        } catch {
+            return false
+        }
+        return isCurrent()
+    }
+
     /// Both stages spend a deadline, not a poll count. `n` sleeps of `m` ms is only `n * m` on an idle
     /// scheduler: the same 40 x 50 ms Stage 2 ran 2082 ms in one of the reporter's runs and 2862 ms in
     /// another, on a device reporting `thermal=serious` throughout. A budget that stretches 40 % under the
@@ -881,9 +917,13 @@ final class DisplayCriteriaController {
     /// `consumesRecord: false` leaves the observation readable for the load's second gate. The pre-flight
     /// passes it: it waits an HDR switch out before the item is built, and the play gate that follows is
     /// entitled to the same start/end timestamps (#339).
+    ///
+    /// `isCurrent` answers whether the load this gate holds is still the engine's; the wait is abandoned
+    /// at the next tick once it is not, or once its task is cancelled (audit LIF-106).
     func waitForSwitch(startGrace: StartGrace = .full,
                        consumesRecord: Bool = true,
-                       settleCap: SettleCap = .standard) async {
+                       settleCap: SettleCap = .standard,
+                       isCurrent: () -> Bool = { true }) async {
         #if os(tvOS)
         guard startGrace != .skip else { return }
         guard let window = resolveWindow() else { return }
@@ -987,7 +1027,10 @@ final class DisplayCriteriaController {
                     break
                 }
                 isFirstPoll = false
-                try? await Task.sleep(for: .milliseconds(10))
+                guard await Self.gateTick(milliseconds: 10, isCurrent: isCurrent) else {
+                    EngineLog.emit("[DisplayCriteria] gate abandoned in the start phase after \(Self.elapsedMs(since: entry))ms: the load it held was cancelled or superseded", category: .engine)
+                    return
+                }
             }
             // Time spent, not the budget: the polls carry scheduler overhead, and everything downstream is
             // reported relative to this (#49).
@@ -1006,10 +1049,15 @@ final class DisplayCriteriaController {
         // switch is unobservable to the app can't gate the first frame the way the
         // old fixed 5s poll did.
         // What this gate may spend waiting for the end, given who is waiting on it (`settleCapMs`).
-        let capMs = Self.settleCapMs(
-            cap: settleCap,
-            startRecorded: gateSnapshot.startedAt != nil || observation.hasNewStart(since: gateSnapshot))
         let stage2Entry = DispatchTime.now()
+        let cap = Self.observedEndCap(
+            settleCap: settleCap,
+            startRecorded: gateSnapshot.startedAt != nil || observation.hasNewStart(since: gateSnapshot),
+            armGeneration: gateSnapshot.generation,
+            nowNanos: stage2Entry.uptimeNanoseconds,
+            budget: observedEndBudget)
+        observedEndBudget = cap.budget
+        let capMs = cap.capMs
         func timing() -> String {
             // The panel's own switch duration whenever both notifications were seen. This is the number the
             // `.brief` premise ("engine rate-only writes settle sub-second") has never been checked against
@@ -1027,7 +1075,10 @@ final class DisplayCriteriaController {
         // multiple after a dwell can be asked how long it has actually held it.
         var cadenceHistory = PanelCadenceHistory()
         while !Self.isBudgetSpent(elapsedMs: Self.elapsedMs(since: stage2Entry), budgetMs: capMs) {
-            try? await Task.sleep(for: .milliseconds(50))
+            guard await Self.gateTick(milliseconds: 50, isCurrent: isCurrent) else {
+                EngineLog.emit("[DisplayCriteria] gate abandoned while waiting for the end (\(timing())): the load it held was cancelled or superseded", category: .engine)
+                return
+            }
             let stage2Ms = Self.elapsedMs(since: stage2Entry)
             let relation = panelRelation()
             cadenceHistory = Self.extendCadenceHistory(cadenceHistory, relation: relation, nowMs: stage2Ms)
diff --git a/Tests/AetherEngineTests/DisplaySwitchWaitBudgetTests.swift b/Tests/AetherEngineTests/DisplaySwitchWaitBudgetTests.swift
new file mode 100644
index 000000000..c71621e7b
--- /dev/null
+++ b/Tests/AetherEngineTests/DisplaySwitchWaitBudgetTests.swift
@@ -0,0 +1,84 @@
+import Foundation
+import Testing
+@testable import AetherEngine
+
+/// The switch waits a load runs are tvOS only, so their two defects are pinned on the parts they are
+/// built from: the poll that ends them and the budget that bounds them.
+@Suite("Display switch waits: they end with their load and share one observed-end budget")
+@MainActor
+struct DisplaySwitchWaitBudgetTests {
+
+    /// Audit LIF-106: a `Task.sleep` in a cancelled task throws at once, and the deadline loops wrapped
+    /// it in `try?`, so Back during an HDR start spun the main actor until the switch cap (measured at
+    /// ~77,000 iterations per second on the loop's shape).
+    @Test("A cancelled wait stops at its next tick instead of spinning")
+    func cancelledWaitStops() async {
+        let wait = Task { @MainActor in
+            var ticks = 0
+            while ticks < 10_000,
+                  await DisplayCriteriaController.gateTick(milliseconds: 50, isCurrent: { true }) {
+                ticks += 1
+            }
+            return ticks
+        }
+        wait.cancel()
+        #expect(await wait.value == 0)
+    }
+
+    @Test("A wait whose load was superseded stops at its next tick")
+    func supersededWaitStops() async {
+        #expect(!(await DisplayCriteriaController.gateTick(milliseconds: 1, isCurrent: { false })))
+        #expect(await DisplayCriteriaController.gateTick(milliseconds: 1, isCurrent: { true }))
+    }
+
+    private static let second: UInt64 = 1_000_000_000
+
+    /// DEC-105: the #667 wait leaves the record unspent for the play gate, and on a panel that never
+    /// announces the end (or whose flag sticks) both read the same `.running` and each spent the full
+    /// 6 s on the one switch.
+    @Test("Two gates on one armed switch spend one observed-end cap between them")
+    func oneBudgetPerArm() {
+        let start = 10 * Self.second
+        let first = DisplayCriteriaController.observedEndCap(
+            settleCap: .awaitObservedEnd, startRecorded: true, armGeneration: 3,
+            nowNanos: start, budget: nil)
+        #expect(first.capMs == DisplayCriteriaController.observedEndCapMs)
+
+        let afterPartialWait = DisplayCriteriaController.observedEndCap(
+            settleCap: .awaitObservedEnd, startRecorded: true, armGeneration: 3,
+            nowNanos: start + 2_500_000_000, budget: first.budget)
+        #expect(afterPartialWait.capMs == 3500)
+
+        let afterFullWait = DisplayCriteriaController.observedEndCap(
+            settleCap: .awaitObservedEnd, startRecorded: true, armGeneration: 3,
+            nowNanos: start + 7 * Self.second, budget: first.budget)
+        #expect(afterFullWait.capMs == 0)
+        #expect(afterFullWait.budget == first.budget)
+    }
+
+    @Test("A newly armed switch gets a budget of its own")
+    func newArmNewBudget() {
+        let spent = DisplayCriteriaController.ObservedEndBudget(armGeneration: 3, deadlineNanos: Self.second)
+        let next = DisplayCriteriaController.observedEndCap(
+            settleCap: .awaitObservedEnd, startRecorded: true, armGeneration: 4,
+            nowNanos: 30 * Self.second, budget: spent)
+        #expect(next.capMs == DisplayCriteriaController.observedEndCapMs)
+        #expect(next.budget?.armGeneration == 4)
+    }
+
+    @Test("The standard cap is per gate as before and never touches the budget")
+    func standardCapIsUntouched() {
+        let spent = DisplayCriteriaController.ObservedEndBudget(armGeneration: 3, deadlineNanos: Self.second)
+        let preflight = DisplayCriteriaController.observedEndCap(
+            settleCap: .standard, startRecorded: true, armGeneration: 3,
+            nowNanos: 30 * Self.second, budget: spent)
+        #expect(preflight.capMs == DisplayCriteriaController.stage2CapMs)
+        #expect(preflight.budget == spent)
+
+        let unobserved = DisplayCriteriaController.observedEndCap(
+            settleCap: .awaitObservedEnd, startRecorded: false, armGeneration: 3,
+            nowNanos: 30 * Self.second, budget: spent)
+        #expect(unobserved.capMs == DisplayCriteriaController.stage2CapMs)
+        #expect(unobserved.budget == spent)
+    }
+}
diff --git a/Tests/AetherEngineTests/Issue667MasterAfterSwitchTests.swift b/Tests/AetherEngineTests/Issue667MasterAfterSwitchTests.swift
index dd759490e..37350a8fa 100644
--- a/Tests/AetherEngineTests/Issue667MasterAfterSwitchTests.swift
+++ b/Tests/AetherEngineTests/Issue667MasterAfterSwitchTests.swift
@@ -60,7 +60,7 @@ struct Issue667MasterAfterSwitchTests {
         let text = try #require(try? String(contentsOf: source, encoding: .utf8))
         let gate = try #require(text.range(of: "Self.unprovenMasterAwaitsSwitchEnd("))
         let after = text[gate.upperBound...]
-        let wait = try #require(after.range(of: "waitForSwitch(consumesRecord: false, settleCap: .awaitObservedEnd)"))
+        let wait = try #require(after.range(of: "waitForSwitch(consumesRecord: false, settleCap: .awaitObservedEnd"))
         let reroute = try #require(after.range(of: "routingPanelHDR = Self.sessionRoutesAsHDRPanel("))
         let serve = try #require(after.range(of: "panelIsInHDRMode: routingPanelHDR"))
         #expect(wait.lowerBound < reroute.lowerBound)

From 34625543b1a8c00d0abfc12a766a3d1cfa068e84 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 06:37:26 +0200
Subject: [PATCH 168/359] fix(cli): bound aetherctl's numeric flags so huge or
 negative values exit 64 (audit OPS-110)

`takeDoubleFlag` rejected NaN and infinity only, so `play --seconds 1e30` loaded and then trapped
in the run loop's `Int(seconds)`; negative counts reached `0..<n` (`seektest --seeks -1`,
`smbtest --reads -1`, `hlslive --seconds -1`), `hlslive --segments ""` built `1..<0`, and the
host-call delays (`--switch-audio 0@<ms>`, `--reload-applying-at`) overflowed
`UInt64(ms) * 1_000_000`.

New bounded variants `takeDoubleFlag(_:in:from:)` and `takeIntFlag(_:in:from:)` exit 64 with a
message outside their range (duration flags up to a week, counts up to a million), `hlslive`
refuses an empty segment list, and the delays go through a saturating `sleepNanoseconds`.
Verified by running each case: every one now exits 64, and the saturated delay no longer traps.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 Sources/aetherctl/ArgParsing.swift   | 32 ++++++++++++++++++++++++++++
 Sources/aetherctl/HLSLiveRepro.swift |  8 +++++--
 Sources/aetherctl/PlaybackCmd.swift  |  8 +++----
 Sources/aetherctl/main.swift         | 20 ++++++++---------
 4 files changed, 52 insertions(+), 16 deletions(-)

diff --git a/Sources/aetherctl/ArgParsing.swift b/Sources/aetherctl/ArgParsing.swift
index f4e2818aa..e65aec6c6 100644
--- a/Sources/aetherctl/ArgParsing.swift
+++ b/Sources/aetherctl/ArgParsing.swift
@@ -43,6 +43,38 @@ func takeDoubleFlag(_ name: String, from rest: inout [String]) -> Double? {
     return value
 }
 
+/// Longest run a duration flag accepts: a week. `isFinite` alone let `--seconds 1e30` through to the
+/// run loop's `Int(_:)`, which trapped after the session was up (audit OPS-110).
+let maxRunSeconds: Double = 7 * 24 * 3600
+
+/// `takeDoubleFlag`, and the value must lie in `range`. Exits 64 otherwise.
+func takeDoubleFlag(_ name: String, in range: ClosedRange<Double>, from rest: inout [String]) -> Double? {
+    guard let value = takeDoubleFlag(name, from: &rest) else { return nil }
+    guard range.contains(value) else {
+        print("ERROR: \(name) expects a value in \(range.lowerBound)...\(range.upperBound), got \(value)")
+        exit(64)
+    }
+    return value
+}
+
+/// `takeIntFlag`, and the value must lie in `range`. Exits 64 otherwise: a negative count reached
+/// `0..<n` and trapped (audit OPS-110).
+func takeIntFlag(_ name: String, in range: ClosedRange<Int>, from rest: inout [String]) -> Int? {
+    guard let value = takeIntFlag(name, from: &rest) else { return nil }
+    guard range.contains(value) else {
+        print("ERROR: \(name) expects an integer in \(range.lowerBound)...\(range.upperBound), got \(value)")
+        exit(64)
+    }
+    return value
+}
+
+/// A host-call delay in milliseconds as a sleep, saturating: `UInt64(ms) * 1_000_000` overflowed past
+/// about 1.8e13 ms (audit OPS-110).
+func sleepNanoseconds(milliseconds: Int) -> UInt64 {
+    let (nanoseconds, overflow) = UInt64(max(0, milliseconds)).multipliedReportingOverflow(by: 1_000_000)
+    return overflow ? .max : nanoseconds
+}
+
 /// Exit 64 with an error message if any `--flag` remains in `rest` after plucking known flags (typos would silently become the URL positional otherwise).
 func rejectStrayFlags(_ rest: [String], subcommand: String) {
     if let stray = rest.first(where: { $0.hasPrefix("--") }) {
diff --git a/Sources/aetherctl/HLSLiveRepro.swift b/Sources/aetherctl/HLSLiveRepro.swift
index 03692b3ac..868e082f7 100644
--- a/Sources/aetherctl/HLSLiveRepro.swift
+++ b/Sources/aetherctl/HLSLiveRepro.swift
@@ -23,8 +23,12 @@ func runHLSLiveRepro(args: [String]) -> Int32 {
         return 64
     }
     let paths = segList.split(separator: ",").map(String.init)
-    let seconds = takeIntFlag("--seconds", from: &rest) ?? 40
-    let segSeconds = takeIntFlag("--segment-seconds", from: &rest) ?? 5
+    guard !paths.isEmpty else {
+        print("ERROR: hlslive requires at least one segment in --segments")
+        return 64
+    }
+    let seconds = takeIntFlag("--seconds", in: 0...Int(maxRunSeconds), from: &rest) ?? 40
+    let segSeconds = takeIntFlag("--segment-seconds", in: 1...3600, from: &rest) ?? 5
     let discFlag = takeStringFlag("--disc", from: &rest)
 
     var slices: [[UInt8]] = []
diff --git a/Sources/aetherctl/PlaybackCmd.swift b/Sources/aetherctl/PlaybackCmd.swift
index 06963d07b..fedc13bbe 100644
--- a/Sources/aetherctl/PlaybackCmd.swift
+++ b/Sources/aetherctl/PlaybackCmd.swift
@@ -759,7 +759,7 @@ private func playSmokeTest(url: URL, seconds: Double, live: Bool, forceSoftware:
     for (delay, group) in Dictionary(grouping: audioDelaySwitches, by: \.delayMilliseconds)
         .sorted(by: { $0.key < $1.key }) {
         Task { @MainActor in
-            try? await Task.sleep(nanoseconds: UInt64(max(0, delay)) * 1_000_000)
+            try? await Task.sleep(nanoseconds: sleepNanoseconds(milliseconds: delay))
             for audioDelaySwitch in group {
                 print("  HOSTCALL setAudioDelay(\(audioDelaySwitch.milliseconds) ms) at "
                       + "+\(delay) ms "
@@ -772,7 +772,7 @@ private func playSmokeTest(url: URL, seconds: Double, live: Bool, forceSoftware:
 
     if let teletextSwitch {
         Task { @MainActor in
-            try? await Task.sleep(nanoseconds: UInt64(max(0, teletextSwitch.delayMilliseconds)) * 1_000_000)
+            try? await Task.sleep(nanoseconds: sleepNanoseconds(milliseconds: teletextSwitch.delayMilliseconds))
             let target = teletextSwitch.page.map(String.init) ?? "auto"
             print("  HOSTCALL setTeletextPage(\(target)) at +\(teletextSwitch.delayMilliseconds) ms "
                   + "(was \(engine.teletextPage.map(String.init) ?? "auto"))")
@@ -786,7 +786,7 @@ private func playSmokeTest(url: URL, seconds: Double, live: Bool, forceSoftware:
     // exactly the pair a host's recovery ladder has to tell apart.
     if let optionCorrection {
         Task { @MainActor in
-            try? await Task.sleep(nanoseconds: UInt64(max(0, optionCorrection.delayMilliseconds)) * 1_000_000)
+            try? await Task.sleep(nanoseconds: sleepNanoseconds(milliseconds: optionCorrection.delayMilliseconds))
             let labels = optionCorrection.changes.map(\.label).joined(separator: ", ")
             let before = engine.currentTime
             print("  HOSTCALL reloadAtCurrentPosition(applying: \(labels)) at +\(optionCorrection.delayMilliseconds) ms "
@@ -825,7 +825,7 @@ private func playSmokeTest(url: URL, seconds: Double, live: Bool, forceSoftware:
     if let audioSwitch {
         let mon = monitor
         Task { @MainActor in
-            try? await Task.sleep(nanoseconds: UInt64(max(0, audioSwitch.delayMilliseconds)) * 1_000_000)
+            try? await Task.sleep(nanoseconds: sleepNanoseconds(milliseconds: audioSwitch.delayMilliseconds))
             print("  HOSTCALL selectAudioTrack(index: \(audioSwitch.index)) "
                   + "at +\(audioSwitch.delayMilliseconds) ms (was \(engine.activeAudioTrackIndex.map(String.init) ?? "none"))")
             engine.selectAudioTrack(index: audioSwitch.index)
diff --git a/Sources/aetherctl/main.swift b/Sources/aetherctl/main.swift
index 4ebac48b5..1f2bad5da 100644
--- a/Sources/aetherctl/main.swift
+++ b/Sources/aetherctl/main.swift
@@ -322,7 +322,7 @@ if first == "--help" || first == "-h" || first == "help" {
 if first == "dvr" {
     var rest = Array(args.dropFirst(2))
     let path    = takeStringFlag("--path",       from: &rest) ?? "both"
-    let seconds = takeDoubleFlag("--seconds",    from: &rest) ?? 120.0
+    let seconds = takeDoubleFlag("--seconds",    in: 0...maxRunSeconds, from: &rest) ?? 120.0
     let dvrWin  = takeDoubleFlag("--dvr-window", from: &rest) ?? 60.0
     guard ["native", "sw", "both"].contains(path) else {
         print("ERROR: --path must be native, sw, or both (got '\(path)')")
@@ -335,8 +335,8 @@ if first == "dvr" {
 // #92 verifier: SW-decode each segment in isolation; framesDecoded==0 => not independently decodable.
 if first == "segverify" {
     var rest = Array(args.dropFirst(2))
-    let fromIdx = takeIntFlag("--from", from: &rest) ?? 0
-    let count   = takeIntFlag("--count", from: &rest) ?? 12
+    let fromIdx = takeIntFlag("--from", in: 0...1_000_000, from: &rest) ?? 0
+    let count   = takeIntFlag("--count", in: 0...1_000_000, from: &rest) ?? 12
     let noDV    = takeFlag("--no-dv", from: &rest)
     let forceDV = takeFlag("--force-dv", from: &rest)
     let dvBaseLayer = takeFlag("--dv-base-layer", from: &rest)
@@ -356,7 +356,7 @@ if first == "segverify" {
 // Rapid-seek burst repro (issue #35).
 if first == "seektest" {
     var rest = Array(args.dropFirst(2))
-    let seeks   = takeIntFlag("--seeks", from: &rest) ?? 40
+    let seeks   = takeIntFlag("--seeks", in: 0...1_000_000, from: &rest) ?? 40
     let gapMs   = takeIntFlag("--gap-ms", from: &rest) ?? 60
     let settle  = takeDoubleFlag("--settle", from: &rest) ?? 5.0
     let throttleKbps = takeIntFlag("--throttle-kbps", from: &rest)
@@ -376,8 +376,8 @@ if first == "seektest" {
 // SW-path background-audio keepalive harness (iOS background audio on the software decode path).
 if first == "bgaudio" {
     var rest = Array(args.dropFirst(2))
-    let fg = takeDoubleFlag("--fg", from: &rest) ?? 3.0
-    let bg = takeDoubleFlag("--bg", from: &rest) ?? 6.0
+    let fg = takeDoubleFlag("--fg", in: 0...maxRunSeconds, from: &rest) ?? 3.0
+    let bg = takeDoubleFlag("--bg", in: 0...maxRunSeconds, from: &rest) ?? 6.0
     guard let urlArg = rest.first(where: { !$0.hasPrefix("--") }) else {
         print("ERROR: bgaudio requires a <url> argument")
         print("Usage: aetherctl bgaudio [--fg N] [--bg N] <url>")
@@ -390,7 +390,7 @@ if first == "bgaudio" {
 
 if first == "smbtest" {
     var rest = Array(args.dropFirst(2))
-    let reads = takeIntFlag("--reads", from: &rest) ?? 64
+    let reads = takeIntFlag("--reads", in: 0...1_000_000, from: &rest) ?? 64
     guard let urlArg = rest.first(where: { !$0.hasPrefix("--") }) else {
         print("ERROR: smbtest requires a <smb-url> argument")
         exit(64)
@@ -502,7 +502,7 @@ if first == "hlslive" {
 
 if first == "live" {
     var rest = Array(args.dropFirst(2))
-    let seconds = takeDoubleFlag("--seconds", from: &rest) ?? 20.0
+    let seconds = takeDoubleFlag("--seconds", in: 0...maxRunSeconds, from: &rest) ?? 20.0
     let dvrWindow = takeDoubleFlag("--dvr-window", from: &rest)
     let seed = takeStringFlag("--seed", from: &rest)
     let serveOnly = takeFlag("--serve-only", from: &rest)
@@ -592,7 +592,7 @@ if first == "live" {
 
 if first == "play" {
     var rest = Array(args.dropFirst(2))
-    let seconds = takeDoubleFlag("--seconds", from: &rest) ?? 30.0
+    let seconds = takeDoubleFlag("--seconds", in: 0...maxRunSeconds, from: &rest) ?? 30.0
     let live = takeFlag("--live", from: &rest)
     // AE#293: the nativeRemoteHLS bypass, the path the #168 carriage watchdog and the carriage probe
     // live on. Pair with --live; without it the m3u8 goes to the raw live path, which rejects it.
@@ -967,7 +967,7 @@ if ["probe", "serve", "validate", "swdecode", "extract", "audio", "customio"].co
     let switchAudioFlag = takeFlag("--switch-audio", from: &rest)
     let selectSubsFlag = takeFlag("--select-subs", from: &rest)
     let extractFlag = takeFlag("--extract", from: &rest)
-    let secondsFlag = takeDoubleFlag("--seconds", from: &rest)
+    let secondsFlag = takeDoubleFlag("--seconds", in: 0...maxRunSeconds, from: &rest)
     let audioSeconds = secondsFlag ?? 10
     // --native-subs: diagnostics affordance for mov_text subtitle track (#55); serve only.
     let nativeSubsIndex = takeIntFlag("--native-subs", from: &rest)

From 7e9f349c0acfa39ba9deae1bcbf1f1fb89d37bae Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 06:38:48 +0200
Subject: [PATCH 169/359] fix(subs): drop a non-finite ASS position or play
 resolution (audit SUB-112)

`SubtitleRectText.parsePositionTag` and `playRes(fromASSHeader:)` parse with `Double(_:)`,
which accepts `nan`, `inf` and `1e999`. `\pos(nan,nan)` published a NaN
`SubtitleTextPlacement.position` and `PlayResX: inf` normalized every position to NaN, breaking
the documented [0, 1] placement contract; a UIKit host that lays out with it raises
`CALayer position contains NaN` (Sodalite filters it, AetherPlayer ignores placement).

Both now require finite values: a non-finite tag yields no position, so the cue falls back to its
alignment, and a non-finite play resolution is no declaration, so the default applies.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../AetherEngine/Subtitles/SubtitleRectText.swift | 10 ++++++++--
 .../Issue233ASSOverrideStyleTests.swift           | 15 +++++++++++++++
 2 files changed, 23 insertions(+), 2 deletions(-)

diff --git a/Sources/AetherEngine/Subtitles/SubtitleRectText.swift b/Sources/AetherEngine/Subtitles/SubtitleRectText.swift
index 6147be571..041852bca 100644
--- a/Sources/AetherEngine/Subtitles/SubtitleRectText.swift
+++ b/Sources/AetherEngine/Subtitles/SubtitleRectText.swift
@@ -88,7 +88,9 @@ enum SubtitleRectText {
             }
             return nil
         }
-        guard let x = value("PlayResX"), let y = value("PlayResY"), x > 0, y > 0 else { return nil }
+        // `Double(_:)` accepts `inf` and `nan` (audit SUB-112).
+        guard let x = value("PlayResX"), let y = value("PlayResY"), x > 0, y > 0,
+              x.isFinite, y.isFinite else { return nil }
         return CGSize(width: x, height: y)
     }
 
@@ -248,7 +250,11 @@ enum SubtitleRectText {
             Double($0.trimmingCharacters(in: .whitespaces))
         }
         guard parts.count == 2, let x = parts[0], let y = parts[1] else { return nil }
-        return CGPoint(x: x / playRes.width, y: y / playRes.height)
+        // Audit SUB-112: a NaN or infinite tag (`Double(_:)` accepts both) breaks the [0, 1]
+        // contract, and a host laying out with it raises; the cue falls back to its alignment.
+        let normalized = CGPoint(x: x / playRes.width, y: y / playRes.height)
+        guard normalized.x.isFinite, normalized.y.isFinite else { return nil }
+        return normalized
     }
 
     /// Trim whitespace and newlines across the edges of a run sequence, so a styled cue matches
diff --git a/Tests/AetherEngineTests/Issue233ASSOverrideStyleTests.swift b/Tests/AetherEngineTests/Issue233ASSOverrideStyleTests.swift
index 3e97e4443..1d1638d8f 100644
--- a/Tests/AetherEngineTests/Issue233ASSOverrideStyleTests.swift
+++ b/Tests/AetherEngineTests/Issue233ASSOverrideStyleTests.swift
@@ -149,6 +149,21 @@ struct Issue233ASSOverrideStyleTests {
         #expect(SubtitleRectText.playRes(fromASSHeader: "[Script Info]\nScriptType: v4.00+") == nil)
     }
 
+    // Audit SUB-112: `Double(_:)` accepts `nan`, `inf` and `1e999`, and a NaN position breaks the
+    // published [0, 1] placement contract (a UIKit host raises `CALayer position contains NaN`).
+    @Test("a non-finite position tag yields no position", arguments: [
+        #"{\pos(nan,nan)}x"#, #"{\pos(1e999,5)}x"#, #"{\pos(5,-inf)}x"#,
+    ])
+    func nonFinitePositionIgnored(body: String) {
+        #expect(placement("0,0,Default,,0,0,0,,\(body)")?.position == nil)
+    }
+
+    @Test("a non-finite play resolution is no play resolution")
+    func nonFinitePlayResIgnored() {
+        #expect(SubtitleRectText.playRes(fromASSHeader: "[Script Info]\nPlayResX: inf\nPlayResY: 1080") == nil)
+        #expect(SubtitleRectText.playRes(fromASSHeader: "[Script Info]\nPlayResX: 1920\nPlayResY: nan") == nil)
+    }
+
     // MARK: - The formats this actually serves
 
     /// What `ff_htmlmarkup_to_ass` emits for `<i>ciao</i> <font color="#FF0000">rosso</font>`.

From a4dcba8b85348be0492e201ef9c6f82b12fd9e9c Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 06:39:00 +0200
Subject: [PATCH 170/359] fix(diagnostics): redact credentials through percent
 escapes and inside query values (audit SUB-104, SUB-108, SUB-109, NET-114)

The nameless matchers (registered secrets, encoded payloads, userinfo,
Xtream paths) only matched raw bytes, so an upstream URL carried
percent-encoded inside a wrapper's query (IPTV proxy, debrid) leaked
its password in load url=, asset.url= and URLError dumps. A line that
holds a valid escape now also runs them over a decoded view built
once, and each hit maps back to whole escapes. The key matcher stays
raw-only, so the NET-1 terminator rule is unchanged. A base64 blob may
now start after - or _ (/v1-eyJ...).

After = the terminators : ; , ) > end a value only where prose follows
them, so a query password holding one goes whole; the header form
keeps the wide set. Added the other backends' names (api-key, cookie,
passwd, pwd, sessionid, session_id, authtoken, auth_token,
refreshtoken, sessiontoken), Bearer and Basic credentials with a
16-byte floor, JSON and dictionary keys whose quote closes before the
separator, and counted secret registrations. The key-initial check is
a table instead of a Set, which keeps an escape-free line at the old
cost despite the extra matchers.

The four NET-114 sites log the URL error code and host instead of the
NSError dump with its failing URL.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../AetherEngine/Diagnostics/EngineLog.swift  |  16 +-
 .../Diagnostics/LogRedaction.swift            | 254 +++++++++++++++---
 .../IO/HLSIngest/HLSCarriageProbe.swift       |   8 +-
 .../IO/HLSIngest/HLSVODIngestReader.swift     |   4 +-
 .../AetherEngineTests/LogRedactionTests.swift | 129 ++++++++-
 docs/api.md                                   |   2 +-
 6 files changed, 375 insertions(+), 38 deletions(-)

diff --git a/Sources/AetherEngine/Diagnostics/EngineLog.swift b/Sources/AetherEngine/Diagnostics/EngineLog.swift
index 3f1d91ac9..e37d70143 100644
--- a/Sources/AetherEngine/Diagnostics/EngineLog.swift
+++ b/Sources/AetherEngine/Diagnostics/EngineLog.swift
@@ -40,7 +40,8 @@ public enum EngineLog {
         LogRedaction.register(value)
     }
 
-    /// Stops redacting a value passed to `registerSecret(_:)`, for example on logout.
+    /// Stops redacting a value passed to `registerSecret(_:)`, for example on logout. Registrations are
+    /// counted, so a value two owners registered stays redacted until both have unregistered it.
     public static func unregisterSecret(_ value: String) {
         LogRedaction.unregister(value)
     }
@@ -93,3 +94,16 @@ public enum EngineLog {
         }
     }
 }
+
+extension EngineLog {
+    /// Audit NET-114: `"\(error)"` of a URLError prints its userInfo, which is the failing URL twice
+    /// with its whole query. The code and the host say what failed without handing the log the URL.
+    /// Any other error keeps its own description.
+    static func summary(of error: Error) -> String {
+        let bridged = error as NSError
+        guard bridged.domain == NSURLErrorDomain else { return "\(error)" }
+        let failing = (bridged.userInfo[NSURLErrorFailingURLErrorKey] as? URL)
+            ?? (bridged.userInfo[NSURLErrorFailingURLStringErrorKey] as? String).flatMap(URL.init(string:))
+        return "NSURLError \(bridged.code)" + (failing?.host.map { " from \($0)" } ?? "")
+    }
+}
diff --git a/Sources/AetherEngine/Diagnostics/LogRedaction.swift b/Sources/AetherEngine/Diagnostics/LogRedaction.swift
index 5767b7cba..dfb1ea3d1 100644
--- a/Sources/AetherEngine/Diagnostics/LogRedaction.swift
+++ b/Sources/AetherEngine/Diagnostics/LogRedaction.swift
@@ -33,10 +33,14 @@ enum LogRedaction {
     /// Generic credential parameter and header names; the engine is not tied to one server product.
     /// Held as lowercase ASCII bytes and matched longest first, so `x-mediabrowser-token` wins over its
     /// `token` suffix. `token` alone is deliberately broad and only fires on a boundary, so identifiers
-    /// such as `hasToken` and `refreshTokenAt` are left alone.
+    /// such as `hasToken` and `refreshTokenAt` are left alone. Audit SUB-109 added the names other
+    /// backends use as whole keys (`api-key` covers `X-Api-Key` through the `-` boundary, `cookie` covers
+    /// `Set-Cookie`); bare `pass`, `key`, `auth` and `sid` stay out, because prose carries them.
     private static let keys: [[UInt8]] = [
-        "x-mediabrowser-token", "x-emby-token", "access_token", "accesstoken", "connect.sid",
-        "signature", "password", "api_key", "apikey", "secret", "token",
+        "x-mediabrowser-token", "x-emby-token", "access_token", "accesstoken", "refreshtoken",
+        "sessiontoken", "auth_token", "authtoken", "connect.sid", "session_id", "sessionid",
+        "signature", "password", "api_key", "api-key", "apikey", "passwd", "secret", "cookie",
+        "token", "pwd",
     ].map { Array($0.utf8) }
 
     private static let placeholderBytes = Array(placeholder.utf8)
@@ -49,22 +53,65 @@ enum LogRedaction {
     static func redact(_ line: String) -> String {
         let bytes = Array(line.utf8)
         let secrets = registeredSecrets
+        guard let view = DecodedView(bytes) else { return streamingRedact(line, bytes, secrets) }
+
+        // Audit SUB-104: a URL carried percent-encoded inside another URL's query hides every shape
+        // that needs no key (`%2F` is not a `/`, `%40` is not an `@`, `%2F` ends in a base64 letter).
+        // The nameless matchers therefore also run over the decoded view, and each hit maps back to
+        // whole escapes. The key matcher stays raw-only: its depth-aware terminators are the NET-1
+        // rule, and the view is produced once and never decoded again.
+        var spans: [Range<Int>] = []
+        var i = 0
+        while i < bytes.count {
+            guard let value = match(in: bytes, at: i, secrets: secrets, keys: true) else {
+                i += 1
+                continue
+            }
+            spans.append(value)
+            i = value.upperBound
+        }
+        let decoded = view.decoded
+        var j = 0
+        while j < decoded.count {
+            guard let value = match(in: decoded, at: j, secrets: secrets, keys: false) else {
+                j += 1
+                continue
+            }
+            spans.append(view.rawStart[value.lowerBound] ..< view.rawStart[value.upperBound])
+            j = value.upperBound
+        }
+        guard !spans.isEmpty else { return line }
+
+        spans.sort { $0.lowerBound < $1.lowerBound }
+        var out: [UInt8] = []
+        out.reserveCapacity(bytes.count)
+        var copiedUpTo = 0
+        var current = spans[0]
+        for span in spans.dropFirst() {
+            if span.lowerBound <= current.upperBound {
+                current = current.lowerBound ..< max(current.upperBound, span.upperBound)
+                continue
+            }
+            out.append(contentsOf: bytes[copiedUpTo ..< current.lowerBound])
+            out.append(contentsOf: placeholderBytes)
+            copiedUpTo = current.upperBound
+            current = span
+        }
+        out.append(contentsOf: bytes[copiedUpTo ..< current.lowerBound])
+        out.append(contentsOf: placeholderBytes)
+        out.append(contentsOf: bytes[current.upperBound...])
+        return String(decoding: out, as: UTF8.self)
+    }
+
+    /// A line without a percent escape, which is nearly every line: one pass, and the output is
+    /// allocated only once something matches.
+    private static func streamingRedact(_ line: String, _ bytes: [UInt8], _ secrets: [[UInt8]]) -> String {
         var out: [UInt8]?
         var copiedUpTo = 0
         var i = 0
 
         while i < bytes.count {
-            // Three shapes, because a credential does not always arrive next to a name. The key
-            // matcher covers `api_key=…`, `X-Emby-Token: …` and the cookie; the payload matcher covers
-            // an encoded blob that no name points at, which is how a path segment carries one; the
-            // userinfo matcher covers `smb://user:secret@host`, where it sits in the authority; the
-            // path matcher covers the Xtream layout; a registered secret is found wherever it sits.
-            guard let value = registeredSecretRange(in: bytes, at: i, secrets: secrets)
-                    ?? matchedKeyLength(in: bytes, at: i)
-                    .flatMap({ valueRange(in: bytes, after: i + $0) })
-                    ?? encodedPayloadRange(in: bytes, at: i)
-                    ?? userInfoSecretRange(in: bytes, at: i)
-                    ?? xtreamPathSecretRange(in: bytes, at: i) else {
+            guard let value = match(in: bytes, at: i, secrets: secrets, keys: true) else {
                 i += 1
                 continue
             }
@@ -83,6 +130,66 @@ enum LogRedaction {
         return String(decoding: out, as: UTF8.self)
     }
 
+    /// Several shapes, because a credential does not always arrive next to a name. The key matcher
+    /// covers `api_key=…`, `X-Emby-Token: …` and the cookie; the scheme matcher covers
+    /// `Authorization: Bearer …` / `Basic …`; the payload matcher covers an encoded blob that no name
+    /// points at, which is how a path segment carries one; the userinfo matcher covers
+    /// `smb://user:secret@host`, where it sits in the authority; the path matcher covers the Xtream
+    /// layout; a registered secret is found wherever it sits.
+    @inline(__always)
+    private static func match(in bytes: [UInt8], at index: Int, secrets: [[UInt8]], keys: Bool)
+        -> Range<Int>?
+    {
+        if let secret = registeredSecretRange(in: bytes, at: index, secrets: secrets) { return secret }
+        if keys, let value = matchedKeyLength(in: bytes, at: index)
+            .flatMap({ valueRange(in: bytes, keyStart: index, keyEnd: index + $0) }) {
+            return value
+        }
+        return authorizationSchemeRange(in: bytes, at: index)
+            ?? encodedPayloadRange(in: bytes, at: index)
+            ?? userInfoSecretRange(in: bytes, at: index)
+            ?? xtreamPathSecretRange(in: bytes, at: index)
+    }
+
+    /// Every logical character of a line once, escapes followed through `%25` layers by
+    /// `logicalByte`, with the raw offset each one starts at, so a range found in `decoded` maps back
+    /// to whole escapes. Nil for a line without a valid escape, which keeps the streaming pass.
+    private struct DecodedView {
+        let decoded: [UInt8]
+        /// `decoded.count + 1` entries; the last is the raw length.
+        let rawStart: [Int]
+
+        init?(_ bytes: [UInt8]) {
+            guard bytes.withUnsafeBufferPointer({ memchr($0.baseAddress, 0x25, $0.count) }) != nil
+            else { return nil }
+            var k = 0
+            var found = false
+            while k + 2 < bytes.count {
+                if bytes[k] == LogRedaction.percent, LogRedaction.hexValue(bytes[k + 1]) != nil,
+                   LogRedaction.hexValue(bytes[k + 2]) != nil {
+                    found = true
+                    break
+                }
+                k += 1
+            }
+            guard found else { return nil }
+            var decoded: [UInt8] = []
+            decoded.reserveCapacity(bytes.count)
+            var rawStart: [Int] = []
+            rawStart.reserveCapacity(bytes.count + 1)
+            var i = 0
+            while i < bytes.count {
+                let char = LogRedaction.logicalByte(in: bytes, at: i)
+                decoded.append(char.byte)
+                rawStart.append(i)
+                i += char.width
+            }
+            rawStart.append(bytes.count)
+            self.decoded = decoded
+            self.rawStart = rawStart
+        }
+    }
+
     /// Raw length of the key starting here, or nil. The key must start on a boundary, else `token`
     /// would fire inside `hasToken`. A separator such as the `-` in `X-Emby-Token` or the `_` in
     /// `api_key` is a boundary; an ASCII letter or digit is not, unless it closes a percent escape
@@ -92,7 +199,7 @@ enum LogRedaction {
     /// (`%26api%5Fkey%3D…`, or `%2526api%255Fkey%253D…` encoded twice) is matched like the plain form.
     private static func matchedKeyLength(in bytes: [UInt8], at index: Int) -> Int? {
         let first = logicalByte(in: bytes, at: index)
-        guard keyInitials.contains(lowercased(first.byte)) else { return nil }
+        guard keyInitials[Int(lowercased(first.byte))] else { return nil }
         if precededByWordCharacter(bytes, at: index) { return nil }
         for key in keys {
             var j = index
@@ -108,7 +215,13 @@ enum LogRedaction {
         return nil
     }
 
-    private static let keyInitials = Set(keys.map { $0[0] })
+    /// A table rather than a `Set`: this is asked at every position of every line, and hashing the
+    /// byte cost more than the rest of an escape-free line's pass put together (measured).
+    private static let keyInitials: [Bool] = {
+        var table = [Bool](repeating: false, count: 256)
+        for key in keys { table[Int(key[0])] = true }
+        return table
+    }()
 
     /// The span holding the secret, given the index just past the key. Covers the query form
     /// (`api_key=abc&next=1`), both header forms (`Token="abc"`, `X-Emby-Token: abc`) and the cookie
@@ -118,8 +231,14 @@ enum LogRedaction {
     /// Characters are read through `logicalByte`. A terminator ends the value only when it sits under
     /// no more encoding layers than the `=` did: inside a plain query `%26` is part of the value, inside
     /// an encoded one it is the `&` that ends it. With no escape in sight this is the byte scan it was.
-    private static func valueRange(in bytes: [UInt8], after keyEnd: Int) -> Range<Int>? {
+    private static func valueRange(in bytes: [UInt8], keyStart: Int, keyEnd: Int) -> Range<Int>? {
         var i = keyEnd
+        // Audit SUB-109: a JSON member or a dictionary description closes the key's quote before its
+        // separator (`{"api_key":"…"}`, `["X-Emby-Token": "…"]`).
+        if keyStart > 0, bytes[keyStart - 1] == UInt8(ascii: "\"") || bytes[keyStart - 1] == UInt8(ascii: "'"),
+           i < bytes.count, bytes[i] == bytes[keyStart - 1] {
+            i += 1
+        }
         while i < bytes.count, case let char = logicalByte(in: bytes, at: i), char.byte == space {
             i += char.width
         }
@@ -154,16 +273,32 @@ enum LogRedaction {
             let char = logicalByte(in: bytes, at: i)
             if char.depth <= depth {
                 if let quote, char.byte == quote { break }
-                if quote == nil, isValueTerminator(char.byte) { break }
+                if quote == nil, isValueTerminator(char.byte),
+                   endsValue(char, at: i, in: bytes, afterHeaderSeparator: isHeaderSeparator) {
+                    break
+                }
             }
             i += char.width
         }
         return start < i ? start ..< i : nil
     }
 
+    /// Audit SUB-108: `: ; , ) >` are legal unescaped inside a query value, and a user-chosen
+    /// password holds them, so after `=` one of them ends the value only where prose follows it (a
+    /// terminator, a blank or the end of the line): `…&api_key=abc: timeout` and
+    /// `connect.sid=abc; Path=/` still give their text back, `password=Pa:ss,word&…` goes whole. The
+    /// header form keeps the wide set, since a header value is not a query value.
+    private static func endsValue(_ char: (byte: UInt8, width: Int, depth: Int), at index: Int,
+                                  in bytes: [UInt8], afterHeaderSeparator: Bool) -> Bool {
+        guard !afterHeaderSeparator, isSoftTerminator(char.byte) else { return true }
+        let next = index + char.width
+        guard next < bytes.count else { return true }
+        return isValueTerminator(logicalByte(in: bytes, at: next).byte)
+    }
+
     // MARK: Percent escapes
 
-    private static let percent = UInt8(ascii: "%")
+    fileprivate static let percent = UInt8(ascii: "%")
     private static let space = UInt8(ascii: " ")
 
     /// A value encoded more often than this is not one a URL builder produces by accident.
@@ -171,7 +306,7 @@ enum LogRedaction {
 
     /// One character as a URL decoder would see it: a raw byte, or a `%XX` escape, followed through
     /// `%25` when the value was encoded more than once. `depth` is the number of layers (0 = raw).
-    private static func logicalByte(in bytes: [UInt8], at index: Int)
+    fileprivate static func logicalByte(in bytes: [UInt8], at index: Int)
         -> (byte: UInt8, width: Int, depth: Int)
     {
         let raw = bytes[index]
@@ -209,7 +344,7 @@ enum LogRedaction {
         return isLetterOrDigit(hi << 4 | lo)
     }
 
-    private static func hexValue(_ b: UInt8) -> UInt8? {
+    fileprivate static func hexValue(_ b: UInt8) -> UInt8? {
         switch b {
         case UInt8(ascii: "0")...UInt8(ascii: "9"): return b - UInt8(ascii: "0")
         case UInt8(ascii: "a")...UInt8(ascii: "f"): return b - UInt8(ascii: "a") + 10
@@ -251,36 +386,46 @@ enum LogRedaction {
     static let minimumSecretLength = 4
 
     private static let secretsLock = NSLock()
-    nonisolated(unsafe) private static var _secrets: [String: [UInt8]] = [:]
+    nonisolated(unsafe) private static var _secrets: [String: (bytes: [UInt8], registrations: Int)] = [:]
 
     /// Snapshot taken once per line, so a register racing a redact sees the old set or the new one,
     /// never half of it. Sorted longest first, so a secret that contains another goes whole.
     private static var registeredSecrets: [[UInt8]] {
         secretsLock.lock(); defer { secretsLock.unlock() }
-        return _secrets.isEmpty ? [] : _secrets.values.sorted { $0.count > $1.count }
+        return _secrets.isEmpty ? [] : _secrets.values.map(\.bytes).sorted { $0.count > $1.count }
     }
 
     /// Registers the value and its percent-encoded form, which is how it appears inside a URL path or
     /// query when it holds a character a URL cannot carry raw. Returns false for a value too short to
     /// match literally.
+    ///
+    /// Counted (audit SUB-109): two owners of the same value, two profiles sharing a password or two
+    /// live servers, each unregister their own registration, and the value stays redacted until the
+    /// last one has.
     @discardableResult
     static func register(_ secret: String) -> Bool {
         let forms = literalForms(of: secret)
         guard !forms.isEmpty else { return false }
         secretsLock.lock(); defer { secretsLock.unlock() }
-        for form in forms { _secrets[form] = Array(form.utf8) }
+        for form in forms {
+            _secrets[form] = (Array(form.utf8), (_secrets[form]?.registrations ?? 0) + 1)
+        }
         return true
     }
 
     static func unregister(_ secret: String) {
         let forms = literalForms(of: secret)
         secretsLock.lock(); defer { secretsLock.unlock() }
-        for form in forms { _secrets[form] = nil }
+        for form in forms {
+            guard let entry = _secrets[form] else { continue }
+            _secrets[form] = entry.registrations > 1 ? (entry.bytes, entry.registrations - 1) : nil
+        }
     }
 
-    static func unregisterAll() {
+    /// Whether `secret` is currently redacted as a registered literal.
+    static func isRegistered(_ secret: String) -> Bool {
         secretsLock.lock(); defer { secretsLock.unlock() }
-        _secrets.removeAll()
+        return _secrets[secret] != nil
     }
 
     private static func literalForms(of secret: String) -> Set<String> {
@@ -392,7 +537,9 @@ enum LogRedaction {
     /// very nearly every position, and only a run that survives that is ever decoded.
     private static func encodedPayloadRange(in bytes: [UInt8], at index: Int) -> Range<Int>? {
         guard bytes[index] == UInt8(ascii: "e") || bytes[index] == UInt8(ascii: "W") else { return nil }
-        if index > 0, isBase64URL(bytes[index - 1]) { return nil }
+        // A letter or digit in front means the run started earlier. A `-` or `_` does not: a blob
+        // glued to a version prefix (`/v1-eyJ…`) is still a blob (audit SUB-104).
+        if index > 0, isLetterOrDigit(bytes[index - 1]) { return nil }
 
         var end = index
         while end < bytes.count, isBase64URL(bytes[end]) { end += 1 }
@@ -428,8 +575,55 @@ enum LogRedaction {
         isLetterOrDigit(b) || b == UInt8(ascii: "-") || b == UInt8(ascii: "_")
     }
 
-    /// `:` counts, so `…&api_key=abc: timeout` gives the token back and keeps the error text. None of
-    /// the credential shapes here (hex, base64url, percent-encoded cookie) contain a literal colon.
+    // MARK: Authorization schemes
+
+    private static let authorizationSchemes: [[UInt8]] = ["bearer", "basic"].map { Array($0.utf8) }
+
+    /// A credential after an `Authorization` scheme shorter than this is prose ("bearer token",
+    /// "basic realm"), not a credential. Sodalite's copy uses the same floor.
+    private static let minimumSchemeCredentialLength = 16
+
+    /// The credential after `Bearer ` or `Basic `, or nil (audit SUB-109). The scheme has no `=` or
+    /// `:` of its own, so the key matcher cannot see it, and `Authorization` is not a key: the
+    /// Jellyfin form of that header carries readable fields around its token.
+    private static func authorizationSchemeRange(in bytes: [UInt8], at index: Int) -> Range<Int>? {
+        let first = lowercased(bytes[index])
+        guard first == UInt8(ascii: "b") else { return nil }
+        if index > 0, isLetterOrDigit(bytes[index - 1]) { return nil }
+        for scheme in authorizationSchemes where index + scheme.count < bytes.count {
+            var matched = true
+            for offset in 1 ..< scheme.count where lowercased(bytes[index + offset]) != scheme[offset] {
+                matched = false
+                break
+            }
+            guard matched else { continue }
+            var i = index + scheme.count
+            guard isBlank(bytes[i]) else { continue }
+            while i < bytes.count, isBlank(bytes[i]) { i += 1 }
+            let start = i
+            while i < bytes.count, isToken68(bytes[i]) { i += 1 }
+            if i - start >= minimumSchemeCredentialLength { return start ..< i }
+        }
+        return nil
+    }
+
+    private static func isToken68(_ b: UInt8) -> Bool {
+        isBase64URL(b) || b == UInt8(ascii: ".") || b == UInt8(ascii: "~") || b == UInt8(ascii: "+")
+            || b == UInt8(ascii: "/") || b == UInt8(ascii: "=")
+    }
+
+    private static func isBlank(_ b: UInt8) -> Bool {
+        b == space || b == 0x09
+    }
+
+    /// Audit SUB-108: the terminators that are also legal inside a query value.
+    private static func isSoftTerminator(_ b: UInt8) -> Bool {
+        b == UInt8(ascii: ":") || b == UInt8(ascii: ";") || b == UInt8(ascii: ",")
+            || b == UInt8(ascii: ")") || b == UInt8(ascii: ">")
+    }
+
+    /// `:` counts, so `…&api_key=abc: timeout` gives the token back and keeps the error text, though
+    /// after `=` only where prose follows it (`endsValue`).
     private static func isValueTerminator(_ b: UInt8) -> Bool {
         switch b {
         case UInt8(ascii: "&"), UInt8(ascii: ";"), UInt8(ascii: ","), UInt8(ascii: ")"),
diff --git a/Sources/AetherEngine/IO/HLSIngest/HLSCarriageProbe.swift b/Sources/AetherEngine/IO/HLSIngest/HLSCarriageProbe.swift
index 42fb804f8..8550a127e 100644
--- a/Sources/AetherEngine/IO/HLSIngest/HLSCarriageProbe.swift
+++ b/Sources/AetherEngine/IO/HLSIngest/HLSCarriageProbe.swift
@@ -66,7 +66,9 @@ enum HLSCarriageProbe {
                 session: session ?? sharedSession
             )
         } catch {
-            EngineLog.emit("[HLSCarriageProbe] carriage probe inconclusive: \(error)", category: .engine)
+            EngineLog.emit(
+                "[HLSCarriageProbe] carriage probe inconclusive: \(EngineLog.summary(of: error))",
+                category: .engine)
             return .settled(.inconclusive)
         }
     }
@@ -90,7 +92,9 @@ enum HLSCarriageProbe {
                 session: session ?? sharedSession
             )
         } catch {
-            EngineLog.emit("[HLSCarriageProbe] carriage probe inconclusive: \(error)", category: .engine)
+            EngineLog.emit(
+                "[HLSCarriageProbe] carriage probe inconclusive: \(EngineLog.summary(of: error))",
+                category: .engine)
             return .inconclusive
         }
     }
diff --git a/Sources/AetherEngine/IO/HLSIngest/HLSVODIngestReader.swift b/Sources/AetherEngine/IO/HLSIngest/HLSVODIngestReader.swift
index 86b6f8429..2926ae72c 100644
--- a/Sources/AetherEngine/IO/HLSIngest/HLSVODIngestReader.swift
+++ b/Sources/AetherEngine/IO/HLSIngest/HLSVODIngestReader.swift
@@ -111,7 +111,7 @@ final class HLSVODIngestReader: TimeSeekableIOReader, @unchecked Sendable {
         } catch {
             if Task.isCancelled { throw CancellationError() }
             EngineLog.emit(
-                "[HLSVODIngest] carriage probe inconclusive: \(error)",
+                "[HLSVODIngest] carriage probe inconclusive: \(EngineLog.summary(of: error))",
                 category: .engine
             )
             return nil
@@ -449,7 +449,7 @@ final class HLSVODIngestReader: TimeSeekableIOReader, @unchecked Sendable {
         producer = nil
         condition.broadcast()
         condition.unlock()
-        EngineLog.emit("[HLSVODIngest] terminal: \(error)", category: .engine)
+        EngineLog.emit("[HLSVODIngest] terminal: \(EngineLog.summary(of: error))", category: .engine)
     }
 
     private func resolveMedia() async throws -> ResolvedMedia {
diff --git a/Tests/AetherEngineTests/LogRedactionTests.swift b/Tests/AetherEngineTests/LogRedactionTests.swift
index c082c2fac..ce24704c8 100644
--- a/Tests/AetherEngineTests/LogRedactionTests.swift
+++ b/Tests/AetherEngineTests/LogRedactionTests.swift
@@ -243,7 +243,6 @@ struct LogRedactionTests {
 
     @Test("a registered secret goes wherever it sits, raw or percent-encoded, until unregistered")
     func registeredSecret() {
-        defer { LogRedaction.unregisterAll() }
         #expect(EngineLog.registerSecret("p@ss w0rd"))
         let raw = LogRedaction.redact("[x] http://h:8080/john/p%40ss%20w0rd/123 alt=p@ss w0rd.")
         #expect(raw == "[x] http://h:8080/john/<redacted>/123 alt=<redacted>.")
@@ -253,11 +252,137 @@ struct LogRedactionTests {
 
     @Test("a value too short to match literally is refused")
     func shortSecretRefused() {
-        defer { LogRedaction.unregisterAll() }
         #expect(!EngineLog.registerSecret("abc"))
         #expect(LogRedaction.redact("[x] abc") == "[x] abc")
     }
 
+    /// Audit SUB-109: `registerSecret` was a set, so the second owner of a value unregistering it
+    /// (logout of one of two profiles sharing a password) unmasked it for the first.
+    @Test("a secret registered twice stays redacted until both registrations are gone")
+    func registrationsAreCounted() {
+        let secret = "sh4redPassw0rd"
+        #expect(EngineLog.registerSecret(secret))
+        #expect(EngineLog.registerSecret(secret))
+        EngineLog.unregisterSecret(secret)
+        #expect(LogRedaction.redact("[x] pw=\(secret)x") == "[x] pw=<redacted>x")
+        EngineLog.unregisterSecret(secret)
+        #expect(LogRedaction.redact("[x] v=\(secret)x") == "[x] v=\(secret)x")
+    }
+
+    // MARK: - Nameless shapes inside a percent-encoded URL (audit SUB-104)
+
+    /// An IPTV proxy or a debrid wrapper carries the upstream URL percent-encoded in its own query.
+    /// The key forms of that were covered by NET-1; the shapes that need no key only matched raw.
+    @Test("a nameless credential inside a percent-encoded URL goes", arguments: [
+        ("url=http://proxy/x?u=http%3A%2F%2Fiptv.example%2Flive%2Falice%2FSECRETpass%2F1234.ts",
+         "url=http://proxy/x?u=http%3A%2F%2Fiptv.example%2Flive%2Falice%2F<redacted>%2F1234.ts"),
+        ("u=http%3A%2F%2Faddon%2FeyJzdG9yZXMiOlsiYSJdLCJjIjoiU0VDUkVUeHl6IiwidCI6InQifQ%2Fmanifest.json",
+         "u=http%3A%2F%2Faddon%2F<redacted>%2Fmanifest.json"),
+        ("u=smb%3A%2F%2Fbob%3ASECRETpw%40nas%2Fshare", "u=smb%3A%2F%2Fbob%3A<redacted>%40nas%2Fshare"),
+        ("http://addon/v1-eyJzdG9yZXMiOlsiYSJdLCJjIjoiU0VDUkVUeHl6IiwidCI6InQifQ/manifest.json",
+         "http://addon/v1-<redacted>/manifest.json"),
+    ])
+    func namelessShapesThroughEscapes(input: String, expected: String) {
+        #expect(LogRedaction.redact(input) == expected)
+    }
+
+    @Test("the same shapes encoded twice go too", arguments: [
+        "http://iptv.example/live/alice/SECRETpass/1234.ts",
+        "http://addon/eyJzdG9yZXMiOlsiYSJdLCJjIjoiU0VDUkVUeHl6IiwidCI6InQifQ/manifest.json",
+        "smb://bob:SECRETpw@nas/share",
+    ])
+    func namelessShapesEncodedTwice(upstream: String) {
+        let once = upstream.addingPercentEncoding(withAllowedCharacters: .alphanumerics)!
+        let twice = once.addingPercentEncoding(withAllowedCharacters: .alphanumerics)!
+        let out = LogRedaction.redact("[NativeAVPlayerHost] #1 load url=https://mfp.example/p?d=\(twice) startPos=nil")
+        for secret in ["SECRETpass", "SECRETpw", "U0VDUkVUeHl6"] { #expect(!out.contains(secret), "\(out)") }
+        #expect(out.contains("<redacted>"))
+        #expect(out.hasSuffix(" startPos=nil"))
+    }
+
+    /// NET-114: `"\(error)"` of a URLError prints the failing URL twice through its userInfo.
+    @Test("an interpolated URLError loses the encoded upstream credential of its failing URL")
+    func urlErrorDescription() {
+        let upstream = "http://iptv/live/alice/SECRETpass/1.ts"
+            .addingPercentEncoding(withAllowedCharacters: .alphanumerics)!
+        let failing = "http://127.0.0.1:1/live/playlist.m3u8?u=\(upstream)"
+        let error = NSError(domain: NSURLErrorDomain, code: NSURLErrorTimedOut,
+                            userInfo: [NSURLErrorFailingURLStringErrorKey: failing,
+                                       NSURLErrorFailingURLErrorKey: URL(string: failing)!])
+        let out = LogRedaction.redact("[HLSVODIngest] carriage probe inconclusive: \(error)")
+        #expect(!out.contains("SECRETpass"), "\(out)")
+    }
+
+    @Test("an error summary names the URL error code and host, never the failing URL")
+    func errorSummaryDropsTheURL() throws {
+        let failing = try #require(URL(string: "http://iptv.example:8080/get.php?username=u&password=Pa:ss"))
+        let urlError = URLError(.timedOut, userInfo: [NSURLErrorFailingURLErrorKey: failing,
+                                                      NSURLErrorFailingURLStringErrorKey: failing.absoluteString])
+        let summary = EngineLog.summary(of: urlError)
+        #expect(summary == "NSURLError \(NSURLErrorTimedOut) from iptv.example")
+        #expect(EngineLog.summary(of: HLSIngestError.playlistUnreachable(status: 403))
+                == "playlistUnreachable(403)")
+    }
+
+    @Test("an escape-heavy line with nothing secret in it comes back unchanged", arguments: [
+        "[ffmpeg] Opening 'https://s/Videos/My%20Movie%20(2009)/stream.mkv' for reading",
+        "[x] url=https://s/Shows/Show%20Name/Season%2001/Show%20Name%20-%20S01E01.mkv ok",
+        "[x] path=%2Fmedia%2Flive%2Fchannel1%2Findex.m3u8 ok",
+        "[HLSLocalServer] GET /0123/aether-origin-relay?ref=eW91IGNhbm5vdCByZWFkIHRoaXM_3kJ-qZ HTTP/1.1 fd=9",
+    ])
+    func escapesWithoutSecretsSurvive(line: String) {
+        #expect(LogRedaction.redact(line) == line)
+    }
+
+    // MARK: - Query values that hold a terminator (audit SUB-108)
+
+    @Test("a query password holding : ; , ) or > goes whole", arguments: [":", ";", ",", ")", ">"])
+    func queryPasswordWithPunctuation(mark: String) {
+        let out = LogRedaction.redact("https://h/get.php?username=u&password=SECRET\(mark)tail123&type=m3u")
+        #expect(out == "https://h/get.php?username=u&password=<redacted>&type=m3u")
+    }
+
+    @Test("punctuation that prose puts after a value still ends it")
+    func proseAfterAValue() {
+        #expect(LogRedaction.redact("[x] fetch failed (api_key=abc), retrying")
+                == "[x] fetch failed (api_key=<redacted>), retrying")
+        #expect(LogRedaction.redact("[x] seen <token=abc>") == "[x] seen <token=<redacted>>")
+    }
+
+    // MARK: - Credential names outside Jellyfin and Xtream (audit SUB-109)
+
+    @Test("the other backends' credential names are covered", arguments: [
+        ("Authorization: Bearer SECRETopaque12345", "Authorization: Bearer <redacted>"),
+        ("Authorization: Basic dmluY2VudDpzZWNyZXQxMjM0", "Authorization: Basic <redacted>"),
+        ("Cookie: PHPSESSID=SECRETsess123; other=1", "Cookie: <redacted>; other=1"),
+        ("Set-Cookie: session=SECRETsess123; Path=/", "Set-Cookie: <redacted>; Path=/"),
+        ("X-Api-Key: SECRETkey123", "X-Api-Key: <redacted>"),
+        ("https://h/a?api-key=SECRETkey123&x=1", "https://h/a?api-key=<redacted>&x=1"),
+        (#"{"api_key":"SECRETjson123"}"#, #"{"api_key":"<redacted>"}"#),
+        (#"["X-Emby-Token": "SECRETjson123"]"#, #"["X-Emby-Token": "<redacted>"]"#),
+        ("https://h/p.php?user=u&pwd=SECRETkey123", "https://h/p.php?user=u&pwd=<redacted>"),
+        ("https://h/p.php?user=u&passwd=SECRETkey123", "https://h/p.php?user=u&passwd=<redacted>"),
+        ("authToken=SECRETrt123 done", "authToken=<redacted> done"),
+        ("refreshToken=SECRETrt123 done", "refreshToken=<redacted> done"),
+        ("sessionToken=SECRETrt123 done", "sessionToken=<redacted> done"),
+        ("auth_token=SECRETrt123 done", "auth_token=<redacted> done"),
+        ("https://h/a?sessionid=SECRETsid123&session_id=SECRETsid456", "https://h/a?sessionid=<redacted>&session_id=<redacted>"),
+    ])
+    func otherBackendNames(input: String, expected: String) {
+        #expect(LogRedaction.redact(input) == expected)
+    }
+
+    @Test("prose around the new names is left alone", arguments: [
+        "[http] 401 with WWW-Authenticate: Bearer realm=\"fixture\"",
+        "[auth] a bearer token was sent",
+        "[auth] basic auth failed",
+        "[x] X-Playback-Session-Id: 5A0C2D7E-1234",
+        "[x] no cookie was set",
+    ])
+    func proseAroundNewNames(line: String) {
+        #expect(LogRedaction.redact(line) == line)
+    }
+
     /// The point of putting this in EngineLog rather than in each host: the handler a host installs
     /// must never see the raw token, whether or not that host scrubs its own log.
     @Test("the host handler receives the redacted line")
diff --git a/docs/api.md b/docs/api.md
index 78714e884..5f38c8fe8 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -930,7 +930,7 @@ as well.
 | `EngineLog.handler` | Mirror every info-level line into a host capture path. Fires from whatever thread emitted it, so it must be thread-safe and non-blocking. |
 | `EngineLog.subsystem`, `EngineLog.Category` | `de.superuser404.AetherEngine`, one category per subsystem: `engine`, `ffmpeg`, `session`, `muxer`, `demux`, `hls.server`, `audio.bridge`, `sw.playback`, `scrub`. |
 | `EngineLog.Level` | `.info` reaches os_log and the host handler; `.verbose` is per-segment trace and reaches os_log's debug level **only**, never the handler, which is what keeps a mirrored stream readable. Read the verbose ones with `log stream --level debug`. |
-| `EngineLog.registerSecret(_:)`, `EngineLog.unregisterSecret(_:)` | Name a value that must never be logged, such as an IPTV password the host holds. Every line reaching os_log or the handler has it replaced, raw or percent-encoded, wherever it sits. The engine already strips named parameters, userinfo, encoded payloads and the Xtream Codes path layout on its own; this covers what only the host can know, such as a provider URL carrying the password as a bare path segment. Returns false for a value under four bytes. |
+| `EngineLog.registerSecret(_:)`, `EngineLog.unregisterSecret(_:)` | Name a value that must never be logged, such as an IPTV password the host holds. Every line reaching os_log or the handler has it replaced, raw or percent-encoded, wherever it sits. The engine already strips named parameters, `Bearer` / `Basic` credentials, userinfo, encoded payloads and the Xtream Codes path layout on its own, also inside a URL carried percent-encoded in another URL's query; this covers what only the host can know, such as a provider URL carrying the password as a bare path segment. Registrations are counted: a value registered twice stays redacted until it is unregistered twice. Returns false for a value under four bytes. |
 | `EngineLog.emit(_:category:level:)` | Emit a host line into the same stream, for a host that wants its own events interleaved with the engine's. |
 | `segmentCacheDiskBytes`, `softwareHostFramesEnqueued` | Point reads for a stats overlay. |
 | `activeProducerShiftSeconds`, `frameAhead`, `clockLeadSeconds` | Divergence diagnostics for tracing a clock that disagrees with the picture. Not for production playback logic. |

From f12d5821f1be583ea78af5eb14eb1ce77fe098a2 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 06:40:01 +0200
Subject: [PATCH 171/359] fix(native): an in-place swap waits for the fresh
 item's own roll (audit NAT-103)

An in-place swap reuses a player that is still `.playing`, and that
status reaches the fresh item about 1 ms after the load, before it is
ready. The timeControlStatus sink took it for the item rolling: it
released the AE#629 clock hold before the mount seek landed, so the
pre-landing readings reached the published clock, and it latched
`hasEverPlayed`, so a swapped item failing at startup took the
post-playback branch. Both now wait for `.playing` on a ready item (the
predicate the AE#440 one-shot already used, renamed
`playingIsThisItemsRoll`), and the readyToPlay sink re-asks when the
mirror already reads `.playing`. The mount-seek and host-seek releases
stay. `aetherctl play --host-calls playreload|pausereload` still ends
`VERDICT: OK`, with the carried edge visible before readiness.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../Native/NativeAVPlayerHost.swift           | 18 ++++++---
 .../InPlaceSwapRollTests.swift                | 37 +++++++++++++++++++
 .../Issue440LiveJoinRollTests.swift           |  4 +-
 3 files changed, 52 insertions(+), 7 deletions(-)
 create mode 100644 Tests/AetherEngineTests/InPlaceSwapRollTests.swift

diff --git a/Sources/AetherEngine/Native/NativeAVPlayerHost.swift b/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
index 68cc98842..facd97ea2 100644
--- a/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
+++ b/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
@@ -643,6 +643,10 @@ final class NativeAVPlayerHost {
                         self.avPlayer.play()
                     }
                     if self.timeControlStatus == .playing {
+                        // Audit NAT-103: a carried `.playing` that never changes status on its way to
+                        // motion is this item's roll from here, as for the AE#440 one-shot.
+                        self.hasEverPlayed = true
+                        self.inPlaceSwapMountPending = false
                         self.startLiveJoinImmediatelyIfHolding(waitingReason: "-")
                     }
                     // #168: publish the item's real dynamic range for the probe-free remote-HLS badge.
@@ -701,7 +705,11 @@ final class NativeAVPlayerHost {
                 self.timeControlStatus = status
                 self.startLiveJoinImmediatelyIfHolding(waitingReason: reason)
                 // First .playing: re-sample route after 2.5s settle -- AVKit only negotiates HDMI format on playback start (issue #24).
-                if status == .playing {
+                // Audit NAT-103: an in-place swap reuses a player that is still `.playing`, and that status
+                // reaches the fresh item before it is ready. Taken as a roll it released the AE#629 hold
+                // before the mount seek landed and latched #50's "has played" for an item that had not.
+                if status == .playing,
+                   Self.playingIsThisItemsRoll(itemIsReadyToPlay: self.playerItem?.status == .readyToPlay) {
                     self.hasEverPlayed = true
                     self.inPlaceSwapMountPending = false
                 }
@@ -1292,7 +1300,7 @@ final class NativeAVPlayerHost {
     private func startLiveJoinImmediatelyIfHolding(waitingReason: String) {
         guard liveJoinStartsImmediately, !liveJoinImmediateStartSpent else { return }
         if timeControlStatus == .playing {
-            if Self.playingSpendsLiveJoinOneShot(itemIsReadyToPlay: playerItem?.status == .readyToPlay) {
+            if Self.playingIsThisItemsRoll(itemIsReadyToPlay: playerItem?.status == .readyToPlay) {
                 liveJoinImmediateStartSpent = true
             }
             return
@@ -1380,15 +1388,15 @@ final class NativeAVPlayerHost {
         }
     }
 
-    /// Whether a `.playing` transport status is this item's rate rolling, the event that spends the
-    /// AE#440 one-shot.
+    /// Whether a `.playing` transport status is this item's rate rolling: the event that spends the
+    /// AE#440 one-shot, latches #50's `hasEverPlayed` and releases the AE#629 swap hold (audit NAT-103).
     ///
     /// An in-place swap reuses a player that is still `.playing`, and that status reaches the fresh
     /// item as its first edge, before the item can play anything. Spent there, the one-shot was gone
     /// before the join's own `ToMinimizeStalls` hold began, so a #446 rejoin produced no decision and no
     /// line. An item cannot roll before it is ready, so readiness is what separates the carry from the
     /// roll. The readyToPlay sink asks again, for a carry that never changes status on its way to motion.
-    nonisolated static func playingSpendsLiveJoinOneShot(itemIsReadyToPlay: Bool) -> Bool {
+    nonisolated static func playingIsThisItemsRoll(itemIsReadyToPlay: Bool) -> Bool {
         itemIsReadyToPlay
     }
 
diff --git a/Tests/AetherEngineTests/InPlaceSwapRollTests.swift b/Tests/AetherEngineTests/InPlaceSwapRollTests.swift
new file mode 100644
index 000000000..8f3c81fe9
--- /dev/null
+++ b/Tests/AetherEngineTests/InPlaceSwapRollTests.swift
@@ -0,0 +1,37 @@
+import Foundation
+import Testing
+@testable import AetherEngine
+
+/// Audit NAT-103: an in-place item swap (AE#629) reuses a player that is still `.playing`, and that
+/// status reaches the fresh item about 1 ms after the load, long before it is ready. The swap's clock
+/// hold and #50's `hasEverPlayed` both took it for the item rolling: the hold let AVPlayer's
+/// pre-landing readings through to the published clock (15.97 s, then 12.00 s, then up again on the
+/// AE#629 harness), and a swapped item that failed at startup took the post-playback branch.
+@Suite("An in-place swap waits for the fresh item's own roll")
+struct InPlaceSwapRollTests {
+
+    @Test("A playing status carried onto an item that is not ready is not its roll")
+    func carriedPlayingIsNotARoll() {
+        #expect(!NativeAVPlayerHost.playingIsThisItemsRoll(itemIsReadyToPlay: false))
+        #expect(NativeAVPlayerHost.playingIsThisItemsRoll(itemIsReadyToPlay: true))
+    }
+
+    /// A host-level test cannot put AVFoundation's carried edge on a fresh item, so this one reads the
+    /// sink, as the #98 placement test does.
+    @Test("The status sink releases the hold and latches has-played only on the item's roll")
+    func statusSinkGatesOnTheRoll() throws {
+        let source = URL(fileURLWithPath: #filePath)
+            .deletingLastPathComponent()
+            .deletingLastPathComponent()
+            .deletingLastPathComponent()
+            .appendingPathComponent("Sources/AetherEngine/Native/NativeAVPlayerHost.swift")
+        let text = try #require(try? String(contentsOf: source, encoding: .utf8))
+        let sink = try #require(text.range(of: "timeControlObservation = avPlayer.observe(\\.timeControlStatus"))
+        let body = String(text[sink.upperBound...].prefix(3000))
+        let gate = try #require(body.range(of: "Self.playingIsThisItemsRoll(itemIsReadyToPlay:"))
+        let latch = try #require(body.range(of: "self.hasEverPlayed = true"))
+        let release = try #require(body.range(of: "self.inPlaceSwapMountPending = false"))
+        #expect(gate.lowerBound < latch.lowerBound)
+        #expect(gate.lowerBound < release.lowerBound)
+    }
+}
diff --git a/Tests/AetherEngineTests/Issue440LiveJoinRollTests.swift b/Tests/AetherEngineTests/Issue440LiveJoinRollTests.swift
index e67c13e88..0ba7358d7 100644
--- a/Tests/AetherEngineTests/Issue440LiveJoinRollTests.swift
+++ b/Tests/AetherEngineTests/Issue440LiveJoinRollTests.swift
@@ -459,14 +459,14 @@ struct Issue440LiveJoinRollTests {
     /// that followed 15 ms later reached no decision and no line.
     @Test("a playing status carried onto an item that is not ready yet does not spend the one-shot")
     func carriedPlayingDoesNotSpend() {
-        #expect(!NativeAVPlayerHost.playingSpendsLiveJoinOneShot(itemIsReadyToPlay: false))
+        #expect(!NativeAVPlayerHost.playingIsThisItemsRoll(itemIsReadyToPlay: false))
     }
 
     /// The reason the spend exists stays intact: once the item's own rate has rolled, every later hold
     /// is a mid-stream rebuffer and keeps AVPlayer's stall policy.
     @Test("a playing status on a ready item is the roll, and spends it")
     func realRollSpends() {
-        #expect(NativeAVPlayerHost.playingSpendsLiveJoinOneShot(itemIsReadyToPlay: true))
+        #expect(NativeAVPlayerHost.playingIsThisItemsRoll(itemIsReadyToPlay: true))
     }
 
     // MARK: - What `ahead 0.00s` was hiding (AE#447 follow-up)

From c42457bfc841b916a1356fd1628695821245c7d6 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 06:40:03 +0200
Subject: [PATCH 172/359] fix(diag): check the pktdump dts delta for overflow
 (audit SUB-112)

`PacketTimingProbe.run` (behind `aetherctl pktdump`) subtracted consecutive dts from the probed
file with a plain `-`, so a hostile file whose dts sit on opposite sides near 2^62 trapped the
probe. The delta now goes through `subtractingReportingOverflow`; a step that does not fit is
counted as non-monotonic and kept out of the histogram.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../Diagnostics/PacketTimingProbe.swift       | 16 ++++++++++++---
 .../PacketTimingDeltaTests.swift              | 20 +++++++++++++++++++
 2 files changed, 33 insertions(+), 3 deletions(-)
 create mode 100644 Tests/AetherEngineTests/PacketTimingDeltaTests.swift

diff --git a/Sources/AetherEngine/Diagnostics/PacketTimingProbe.swift b/Sources/AetherEngine/Diagnostics/PacketTimingProbe.swift
index fde11c6af..33e12f976 100644
--- a/Sources/AetherEngine/Diagnostics/PacketTimingProbe.swift
+++ b/Sources/AetherEngine/Diagnostics/PacketTimingProbe.swift
@@ -26,6 +26,12 @@ public enum PacketTimingProbe {
         public var errorDescription: String? { description }
     }
 
+    /// nil when the step does not fit `Int64` (audit SUB-112): the timestamps are the probed file's own.
+    static func dtsDelta(_ dts: Int64, after last: Int64) -> Int64? {
+        let (delta, overflow) = dts.subtractingReportingOverflow(last)
+        return overflow ? nil : delta
+    }
+
     public static func run(
         url: URL,
         seekSeconds: Double,
@@ -107,9 +113,13 @@ public enum PacketTimingProbe {
             if isKey { keyCount += 1 }
             if dts != Int64.min {
                 if let last = lastDts {
-                    let d = dts - last
-                    dtsDeltaHist[d, default: 0] += 1
-                    if d <= 0 { nonMonotonicDts += 1 }
+                    if let d = dtsDelta(dts, after: last) {
+                        dtsDeltaHist[d, default: 0] += 1
+                        if d <= 0 { nonMonotonicDts += 1 }
+                    } else {
+                        // A step no Int64 holds is a broken timeline, not a delta worth a bucket.
+                        nonMonotonicDts += 1
+                    }
                 }
                 lastDts = dts
             }
diff --git a/Tests/AetherEngineTests/PacketTimingDeltaTests.swift b/Tests/AetherEngineTests/PacketTimingDeltaTests.swift
new file mode 100644
index 000000000..28add33c8
--- /dev/null
+++ b/Tests/AetherEngineTests/PacketTimingDeltaTests.swift
@@ -0,0 +1,20 @@
+import Testing
+@testable import AetherEngine
+
+/// Audit SUB-112 item 4: `aetherctl pktdump` (the public `PacketTimingProbe.run`) subtracted packet
+/// timestamps from the probed file unchecked, so dts on opposite sides near 2^62 trapped the probe.
+@Suite("Packet timing probe dts deltas")
+struct PacketTimingDeltaTests {
+
+    @Test("A delta no Int64 can hold is nil instead of a trap")
+    func overflowingDelta() {
+        #expect(PacketTimingProbe.dtsDelta(Int64.max - 1, after: -(1 << 62)) == nil)
+        #expect(PacketTimingProbe.dtsDelta(-(1 << 62) - 10, after: Int64.max - 1) == nil)
+    }
+
+    @Test("Ordinary deltas are unchanged, backward ones included")
+    func ordinaryDelta() {
+        #expect(PacketTimingProbe.dtsDelta(4004, after: 3003) == 1001)
+        #expect(PacketTimingProbe.dtsDelta(3003, after: 4004) == -1001)
+    }
+}

From 2ac8828da4dfff7787a72fc478d9fedb0126abd4 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 06:43:31 +0200
Subject: [PATCH 173/359] fix(network): keep the local server's session token
 out of the log (audit SUB-107, NET-114)

The 128-bit path token is the capability that keeps LAN hosts off the
0.0.0.0 listener, yet every request line, the #227 first-request line,
NativeAVPlayerHost's load url= and asset.url= and the #316 serving line
logged it verbatim. HLSLocalServer registers the token with the log
redactor in start() and unregisters it in stop() (registrations are
counted, so two servers never release each other's), and the request
line is now composed from the route after the token.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../AetherEngine/Network/HLSLocalServer.swift | 31 +++++++++++++-
 .../HLSLocalServerSessionTokenTests.swift     | 42 +++++++++++++++++++
 2 files changed, 71 insertions(+), 2 deletions(-)

diff --git a/Sources/AetherEngine/Network/HLSLocalServer.swift b/Sources/AetherEngine/Network/HLSLocalServer.swift
index 4dbd48806..7908fb63b 100644
--- a/Sources/AetherEngine/Network/HLSLocalServer.swift
+++ b/Sources/AetherEngine/Network/HLSLocalServer.swift
@@ -241,6 +241,16 @@ final class HLSLocalServer: @unchecked Sendable {
         return rest
     }
 
+    /// The request line as it is logged: the route after the session token, never the token itself
+    /// (audit SUB-107).
+    static func requestLineForLog(method: Substring, routePath: String, query: String,
+                                  version: Substring?) -> String {
+        var line = "\(method) \(routePath)"
+        if !query.isEmpty { line += "?\(query)" }
+        if let version { line += " \(version)" }
+        return line
+    }
+
     /// Kernel-assigned ephemeral port. Zero until start() succeeds.
     private(set) var port: UInt16 = 0
 
@@ -330,6 +340,12 @@ final class HLSLocalServer: @unchecked Sendable {
     private var shouldStop = false
     private var clientFds = Set<Int32>()
 
+    /// Audit SUB-107: whether `pathToken` is registered with the log redactor. The token is the
+    /// capability that keeps LAN strangers off the stream, and every line that prints a server URL
+    /// (`load url=`, `asset.url=`, the #316 serving line) would otherwise hand it to a shared log
+    /// for as long as the session lives.
+    private var tokenRegistered = false
+
     /// Active connection count; engine memory probe watches for unexpectedly rising accumulation (AVPlayer normally holds 1-3 connections).
     var activeConnectionCount: Int {
         stateLock.lock()
@@ -536,6 +552,9 @@ final class HLSLocalServer: @unchecked Sendable {
         listenFd = fd
         port = assignedPort
         shouldStop = false
+        if !tokenRegistered {
+            tokenRegistered = LogRedaction.register(pathToken)
+        }
         stateLock.unlock()
 
         EngineLog.emit("[HLSLocalServer] Listening on port \(assignedPort)",
@@ -560,7 +579,12 @@ final class HLSLocalServer: @unchecked Sendable {
         mediaPlaylistBuildCount = 0
         let clients = clientFds
         clientFds.removeAll()
+        let unregisterToken = tokenRegistered
+        tokenRegistered = false
         stateLock.unlock()
+        // Last, so a line still in flight from a connection being shut down is redacted too; the
+        // token opens nothing once the listener is gone.
+        defer { if unregisterToken { LogRedaction.unregister(pathToken) } }
         // AE#597: the one line that says a listener went away. Without it a log cannot tell a
         // server that was released from one that outlived its session on a port of its own.
         EngineLog.emit(
@@ -832,12 +856,15 @@ final class HLSLocalServer: @unchecked Sendable {
             return false
         }
         let normalizedPath = (routePath == "/audio.m3u8") ? "/media.m3u8" : routePath
+        let loggedRequest = Self.requestLineForLog(
+            method: parts[0], routePath: routePath, query: query,
+            version: parts.count > 2 ? parts[2] : nil)
 
         // #50 diag: promoted to .info so the host mirror names the failing path without a verbose build. Revert once #50 is root-caused.
         // AE#446: the fd is what says whether a blocking-reload hold is parking the connection the
         // next segment request needs. Same fd on both, and the segment could not be read until the
         // hold returned; different fds, and the client chose not to fetch.
-        EngineLog.emit("[HLSLocalServer] \(firstLine) fd=\(fd)", category: .hlsServer)
+        EngineLog.emit("[HLSLocalServer] \(loggedRequest) fd=\(fd)", category: .hlsServer)
         // #227 diag: name each distinct client once, so an AirPlay session shows whether the receiver fetches
         // for itself (its own LAN address appears) or the sender pulls everything (only 127.0.0.1 / own IP).
         if let peer = Self.peerAddress(of: fd) {
@@ -845,7 +872,7 @@ final class HLSLocalServer: @unchecked Sendable {
             let isNewPeer = loggedPeers.insert(peer).inserted
             stateLock.unlock()
             if isNewPeer {
-                EngineLog.emit("[HLSLocalServer] #227 client \(peer) first request: \(firstLine)", category: .hlsServer)
+                EngineLog.emit("[HLSLocalServer] #227 client \(peer) first request: \(loggedRequest)", category: .hlsServer)
             }
         }
         // Dump request headers once per session; AVPlayer capability headers (Accept, Range, X-Playback-Session-Id) can influence silent variant rejection.
diff --git a/Tests/AetherEngineTests/HLSLocalServerSessionTokenTests.swift b/Tests/AetherEngineTests/HLSLocalServerSessionTokenTests.swift
index 21234fb16..241657bfd 100644
--- a/Tests/AetherEngineTests/HLSLocalServerSessionTokenTests.swift
+++ b/Tests/AetherEngineTests/HLSLocalServerSessionTokenTests.swift
@@ -69,6 +69,48 @@ struct HLSLocalServerSessionTokenTests {
         #expect(Self.status(port: server.port, path: "/seg0.mp4") == 404)
     }
 
+    // MARK: - The token in the log (audit SUB-107)
+
+    @Test("A running server's token is redacted from every log line, and released on stop")
+    func tokenIsRedactedWhileTheServerRuns() throws {
+        let server = HLSLocalServer(provider: StubProvider())
+        try server.start()
+        let token = server.pathToken
+        let line = "[NativeAVPlayerHost] #2 load url=http://127.0.0.1:\(server.port)/\(token)/master.m3u8"
+        #expect(LogRedaction.isRegistered(token))
+        #expect(!LogRedaction.redact(line).contains(token))
+        #expect(LogRedaction.redact("[HLSLocalServer] GET /\(token)/seg_1.m4s HTTP/1.1")
+                == "[HLSLocalServer] GET /<redacted>/seg_1.m4s HTTP/1.1")
+
+        server.stop()
+        #expect(!LogRedaction.isRegistered(token))
+        server.stop()
+        #expect(!LogRedaction.isRegistered(token))
+    }
+
+    @Test("Stopping one server leaves the other's token redacted")
+    func twoServersKeepTheirOwnRegistration() throws {
+        let first = HLSLocalServer(provider: StubProvider())
+        let second = HLSLocalServer(provider: StubProvider())
+        try first.start()
+        try second.start()
+        defer { second.stop() }
+
+        first.stop()
+        #expect(!LogRedaction.isRegistered(first.pathToken))
+        #expect(LogRedaction.isRegistered(second.pathToken))
+    }
+
+    @Test("The logged request line names the route, not the token")
+    func requestLineOmitsTheToken() {
+        #expect(HLSLocalServer.requestLineForLog(
+            method: "GET", routePath: "/seg_1.m4s", query: "", version: "HTTP/1.1")
+                == "GET /seg_1.m4s HTTP/1.1")
+        #expect(HLSLocalServer.requestLineForLog(
+            method: "GET", routePath: "/media.m3u8", query: "_HLS_msn=12", version: "HTTP/1.1")
+                == "GET /media.m3u8?_HLS_msn=12 HTTP/1.1")
+    }
+
     // MARK: - Helpers
 
     /// Status line of a plain GET, or 0 when the request could not be completed.

From 8f5b6c62b90ec91f9907676b4cb2d449cc80def0 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 06:44:00 +0200
Subject: [PATCH 174/359] fix(core): the probe publishes the source geometry
 after its generation check (audit LIF-107)

The probe block wrote `sourceVideoWidth`, `sourceVideoHeight`,
`sourceVideoPixelAspectRatio` and `lastDetectedVideoCodec` before the
post-probe generation check. The AE#532 RPU audit is a second read that
`stopInternal` cannot abort, so a load superseded inside it came back
after its successor's prologue and wrote its own values over the reset;
a successor that never probes (the remote-HLS bypass) kept them, and
Sodalite reads a non-zero width as "has video". The values are now
collected in the block and published after the check.

The test origin can hold every request after a point, which is how the
test parks the audit of a synthesized Dolby Vision Profile 5 over HDR10
source while the successor loads.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 Sources/AetherEngine/AetherEngine.swift       |  26 ++--
 .../SupersededProbeGeometryTests.swift        | 119 ++++++++++++++++++
 .../Support/ProbeHTTPTestOrigin.swift         |   8 ++
 3 files changed, 144 insertions(+), 9 deletions(-)
 create mode 100644 Tests/AetherEngineTests/SupersededProbeGeometryTests.swift

diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index 78a403a49..3614af369 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -4066,6 +4066,10 @@ public final class AetherEngine: ObservableObject {
         var probedAudioTracks: [TrackInfo] = []
         var probedSubtitleTracks: [TrackInfo] = []
         var probedDefaultAudioIndex: Int32 = -1
+        // Audit LIF-107: published only after the post-probe generation check below. The AE#532 audit
+        // is a second read `stopInternal` cannot abort, so a superseded load can return from it after
+        // its successor's prologue and would write this source's geometry over the reset.
+        var probedGeometry: (width: Int32, height: Int32, pixelAspect: Double?)?
         // AE#493: what this session takes the display to be. The observed table is what the platform
         // could answer; the session table adds what the host asserted, because Dolby Vision has no
         // public capability API on macOS and eligibility deliberately does not claim it. Composed once,
@@ -4192,19 +4196,17 @@ public final class AetherEngine: ObservableObject {
                 // The base-layer route is the one exception: it serves hvc1 and asks for hvc1.
                 detectedDVProfile = (detectedFormat == .dolbyVision) && !presentsDolbyVisionBaseLayer
                 detectedFieldOrder = stream.pointee.codecpar.pointee.field_order
-                sourceVideoWidth = stream.pointee.codecpar.pointee.width
-                sourceVideoHeight = stream.pointee.codecpar.pointee.height
-                if let sar = PixelAspectPolicy.declaredPixelAspect(
+                let width = stream.pointee.codecpar.pointee.width
+                let height = stream.pointee.codecpar.pointee.height
+                let sar = PixelAspectPolicy.declaredPixelAspect(
                     bitstream: stream.pointee.codecpar.pointee.sample_aspect_ratio,
                     container: stream.pointee.sample_aspect_ratio,
-                    width: sourceVideoWidth,
-                    height: sourceVideoHeight
-                ) {
-                    sourceVideoPixelAspectRatio = Double(sar.num) / Double(sar.den)
-                }
+                    width: width,
+                    height: height
+                )
+                probedGeometry = (width, height, sar.map { Double($0.num) / Double($0.den) })
                 detectedVideoBitrate = probe.declaredBitrate(stream: stream)
                 detectedVideoStreamFormat = VideoStreamFormat(codecpar: stream.pointee.codecpar)
-                lastDetectedVideoCodec = detectedCodecID
             }
             probedAudioTracks = probe.audioTrackInfos()
             probedSubtitleTracks = probe.subtitleTrackInfos()
@@ -4224,6 +4226,12 @@ public final class AetherEngine: ObservableObject {
             }
             try checkLoadCurrent(gen)
         }
+        if let probedGeometry {
+            sourceVideoWidth = probedGeometry.width
+            sourceVideoHeight = probedGeometry.height
+            if let pixelAspect = probedGeometry.pixelAspect { sourceVideoPixelAspectRatio = pixelAspect }
+            lastDetectedVideoCodec = detectedCodecID
+        }
 
         // Custom sources have no URL to reopen from: a failed probe is fatal.
         if case .custom = source, !probeOpened {
diff --git a/Tests/AetherEngineTests/SupersededProbeGeometryTests.swift b/Tests/AetherEngineTests/SupersededProbeGeometryTests.swift
new file mode 100644
index 000000000..c5690f3d9
--- /dev/null
+++ b/Tests/AetherEngineTests/SupersededProbeGeometryTests.swift
@@ -0,0 +1,119 @@
+import Combine
+import Foundation
+import Testing
+import AetherLibavcodec
+import AetherLibavformat
+import AetherLibavutil
+@testable import AetherEngine
+
+/// Audit LIF-107: the probe block wrote the source geometry and codec into engine state before its
+/// post-probe generation check. The AE#532 RPU audit (a Dolby Vision Profile 5 record over an HDR10
+/// VUI) is a second network read `stopInternal` cannot abort, so a load superseded inside it came
+/// back after its successor's prologue and wrote its own width, height and codec over the reset.
+/// A successor that never probes (the remote-HLS bypass) then kept them for the session.
+@Suite("A superseded probe leaves its successor's geometry alone", .timeLimit(.minutes(2)))
+@MainActor
+struct SupersededProbeGeometryTests {
+
+    /// The 64x64 HDR10 fixture with a Dolby Vision Profile 5 record added: the one pairing the
+    /// AE#532 audit reads the bitstream for.
+    static func dolbyVisionProfile5OverHDR10() throws -> Data {
+        let video = Demuxer()
+        defer { video.close() }
+        try video.open(reader: DataIOReader(data: ProbeTestFixtures.hdr10Plus()), formatHint: "mp4")
+        let source = try #require(video.stream(at: video.videoStreamIndex))
+
+        var output: UnsafeMutablePointer<AVFormatContext>?
+        try #require(avformat_alloc_output_context2(&output, nil, "mp4", nil) >= 0)
+        let context = try #require(output)
+        defer { avformat_free_context(context) }
+        // movenc writes the dvcC box only when unofficial extensions are allowed.
+        context.pointee.strict_std_compliance = FF_COMPLIANCE_UNOFFICIAL
+
+        var io: UnsafeMutablePointer<AVIOContext>?
+        try #require(avio_open_dyn_buf(&io) >= 0)
+        let buffer = try #require(io)
+        context.pointee.pb = buffer
+        var bytes: UnsafeMutablePointer<UInt8>?
+        var bufferClosed = false
+        defer {
+            if !bufferClosed { _ = avio_close_dyn_buf(buffer, &bytes) }
+            av_free(bytes)
+        }
+
+        let target = try #require(avformat_new_stream(context, nil))
+        let codecpar = try #require(target.pointee.codecpar)
+        try #require(avcodec_parameters_copy(codecpar, source.pointee.codecpar) >= 0)
+        target.pointee.time_base = source.pointee.time_base
+        var recordSize = 0
+        let record = try #require(av_dovi_alloc(&recordSize))
+        record.pointee.dv_version_major = 1
+        record.pointee.dv_profile = 5
+        record.pointee.dv_level = 1
+        record.pointee.rpu_present_flag = 1
+        record.pointee.bl_present_flag = 1
+        record.pointee.dv_bl_signal_compatibility_id = 0
+        guard av_packet_side_data_add(&codecpar.pointee.coded_side_data, &codecpar.pointee.nb_coded_side_data,
+                                      AV_PKT_DATA_DOVI_CONF, UnsafeMutableRawPointer(record), recordSize, 0) != nil else {
+            av_free(record)
+            throw DemuxerError.openFailed(code: -1)
+        }
+
+        try #require(avformat_write_header(context, nil) >= 0)
+        while let packet = try video.readPacket() {
+            var owned: UnsafeMutablePointer<AVPacket>? = packet
+            defer { trackedPacketFree(&owned) }
+            guard packet.pointee.stream_index == video.videoStreamIndex else { continue }
+            av_packet_rescale_ts(packet, source.pointee.time_base, target.pointee.time_base)
+            packet.pointee.stream_index = 0
+            packet.pointee.pos = -1
+            try #require(av_interleaved_write_frame(context, packet) >= 0)
+        }
+        try #require(av_write_trailer(context) >= 0)
+        let count = avio_close_dyn_buf(buffer, &bytes)
+        bufferClosed = true
+        context.pointee.pb = nil
+        try #require(count > 0)
+        return Data(bytes: try #require(bytes), count: Int(count))
+    }
+
+    @Test("The fixture is the pairing the RPU audit exists for")
+    func fixtureIsAContradictedRecord() throws {
+        let demuxer = Demuxer()
+        defer { demuxer.close() }
+        try demuxer.open(reader: DataIOReader(data: Self.dolbyVisionProfile5OverHDR10()), formatHint: "mp4")
+        let stream = try #require(demuxer.stream(at: demuxer.videoStreamIndex))
+        let codecpar = try #require(stream.pointee.codecpar)
+        #expect(AetherEngine.dvConfig(stream: stream)?.profile == 5)
+        #expect(DolbyVisionRecordAudit.recordIsContradicted(
+            codecID: codecpar.pointee.codec_id, dvProfile: 5,
+            colorTransfer: codecpar.pointee.color_trc, colorMatrix: codecpar.pointee.color_space))
+    }
+
+    @Test("A load superseded during its RPU audit does not write its width over the successor's")
+    func supersededAuditPublishesNothing() async throws {
+        let origin = try ProbeHTTPTestOrigin(data: try Self.dolbyVisionProfile5OverHDR10())
+        defer { origin.stop() }
+        let engine = try AetherEngine()
+        defer { engine.stop() }
+        // The open's last stage hops to the main actor ahead of the open's own continuation, so
+        // every request from here on is the audit's.
+        let sub = engine.$startupProgress.sink { progress in
+            if progress?.checkpoint == .streamsProbed { origin.holdLaterRequests() }
+        }
+        defer { sub.cancel() }
+
+        let superseded = Task { @MainActor in
+            try await engine.load(url: try #require(URL(string: "http://127.0.0.1:\(origin.port)/p5.mp4")))
+        }
+        try await waitFor { origin.held.entered }
+        _ = try await engine.load(url: try #require(URL(string: "http://127.0.0.1:9/vod.m3u8")),
+                                  options: LoadOptions(nativeRemoteHLS: true))
+        #expect(engine.sourceVideoWidth == 0)
+        origin.held.open()
+
+        await #expect(throws: CancellationError.self) { try await superseded.value }
+        #expect(engine.sourceVideoWidth == 0)
+        #expect(engine.sourceVideoHeight == 0)
+    }
+}
diff --git a/Tests/AetherEngineTests/Support/ProbeHTTPTestOrigin.swift b/Tests/AetherEngineTests/Support/ProbeHTTPTestOrigin.swift
index affc5300a..da436dbe6 100644
--- a/Tests/AetherEngineTests/Support/ProbeHTTPTestOrigin.swift
+++ b/Tests/AetherEngineTests/Support/ProbeHTTPTestOrigin.swift
@@ -21,6 +21,10 @@ final class ProbeHTTPTestOrigin: @unchecked Sendable {
 
     let port: UInt16
     let blocked = ProbeTestGate()
+    /// Every request that arrives after `holdLaterRequests()` waits here, before its response head,
+    /// until the test opens the gate (or `stop()` does).
+    let held = ProbeTestGate()
+    private let holding = ProbeTestBox(false)
     private let listener: Int32
     private let wakeRead: Int32
     private let wakeWrite: Int32
@@ -74,6 +78,8 @@ final class ProbeHTTPTestOrigin: @unchecked Sendable {
     }
 
     var requests: [Request] { state.value.requests }
+
+    func holdLaterRequests() { holding.update { $0 = true } }
     var failure: String? { state.value.failure }
     var isStopped: Bool {
         let snapshot = state.value
@@ -96,6 +102,7 @@ final class ProbeHTTPTestOrigin: @unchecked Sendable {
             for fd in state.connections { shutdown(fd, SHUT_RDWR) }
         }
         blocked.open()
+        held.open()
     }
 
     private func acceptLoop() {
@@ -167,6 +174,7 @@ final class ProbeHTTPTestOrigin: @unchecked Sendable {
             $0.requests.append(request)
         }
         if stage == .headers, index == 0 { park() }
+        if holding.value { held.wait() }
         guard !state.value.stopping else { return }
 
         var start = 0

From 28c51c6f5f1c92a4fce855c5d57e5385ddb88691 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 06:45:21 +0200
Subject: [PATCH 175/359] fix(segments): the end-of-file bridge flush follows
 the video cutter on sequential origins (audit SEG-103)

7.22 made sequential-origin audio follow the video cutter
(audioFollowsVideoCut) at the per-feed bridge site and the stream-copy
sites, but the EOF bridge.flush() loop still routed its tail by plan
time. When the last GOP crossed the last plan boundary the flushed tail
opened the plan index the cutter never reached: the real final segment
was closed as not final, its duration never arrived, and ENDLIST landed
behind the segment before it, so AVPlayer ended the archive early.

Both bridge sites now route through bridgedAudioSegmentIndex, so the
live, sequential and plan rules live in one place.

Test: a 16 s forward-only Matroska archive (embedded, Opus bridged to
FLAC, keyframes at 0, 9 and 11 s under the uniform 4 s plan) lists all
160 video frames and its whole duration. Before, the playlist stopped
after 9 s with 90 of 160 frames.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../Video/HLSSegmentProducer.swift            |  38 +---
 .../SequentialBridgedTailPlaylistTests.swift  | 212 ++++++++++++++++++
 2 files changed, 224 insertions(+), 26 deletions(-)
 create mode 100644 Tests/AetherEngineTests/SequentialBridgedTailPlaylistTests.swift

diff --git a/Sources/AetherEngine/Video/HLSSegmentProducer.swift b/Sources/AetherEngine/Video/HLSSegmentProducer.swift
index 53b88e3ed..9234f93a6 100644
--- a/Sources/AetherEngine/Video/HLSSegmentProducer.swift
+++ b/Sources/AetherEngine/Video/HLSSegmentProducer.swift
@@ -4092,21 +4092,7 @@ final class HLSSegmentProducer: @unchecked Sendable {
                                 trackedPacketFree(&fpVar)
                                 continue
                             }
-                            // Rescale FLAC pts to source video TB for segment lookup; live and
-                            // sequential audio follow the video cutter.
-                            let fpSeg: Int
-                            if isLive {
-                                fpSeg = liveCurrentSegmentIndex
-                            } else if audioFollowsVideoCut {
-                                fpSeg = vodCutter.current
-                            } else {
-                                let fpPtsInVideoTb = av_rescale_q(
-                                    fp.pointee.pts,
-                                    audio.inputTimeBase,
-                                    sourceVideoTimeBase
-                                )
-                                fpSeg = segmentIndex(forSourcePts: fpPtsInVideoTb)
-                            }
+                            let fpSeg = bridgedAudioSegmentIndex(fp, audio: audio)
                             guard let muxer = ensureMuxer(forSegmentIndex: fpSeg) else {
                                 trackedPacketFree(&fpVar)
                                 bridgedMuxerGone = true
@@ -4257,17 +4243,7 @@ final class HLSSegmentProducer: @unchecked Sendable {
         // EOF tail flush for bridge audio: drains ~100-200 ms remainder (per-feed only emits full frames).
         if case .eof = exitReason, let audio = audioConfig, let bridge = audio.bridge {
             for fp in bridge.flush() {
-                let fpSeg: Int
-                if isLive {
-                    fpSeg = liveCurrentSegmentIndex
-                } else {
-                    let fpPtsInVideoTb = av_rescale_q(
-                        fp.pointee.pts,
-                        audio.inputTimeBase,
-                        sourceVideoTimeBase
-                    )
-                    fpSeg = segmentIndex(forSourcePts: fpPtsInVideoTb)
-                }
+                let fpSeg = bridgedAudioSegmentIndex(fp, audio: audio)
                 if let muxer = ensureMuxer(forSegmentIndex: fpSeg) {
                     fp.pointee.stream_index = muxer.audioOutputStreamIndex
                     av_packet_rescale_ts(fp, audio.inputTimeBase, muxer.muxerAudioTimeBase)
@@ -4300,6 +4276,16 @@ final class HLSSegmentProducer: @unchecked Sendable {
         onPumpFinished?(exitReason)
     }
 
+    /// The segment a bridged audio packet belongs to. Live and sequential audio follow the video
+    /// cutter; everything else is routed by the packet's own time against the plan. One helper for the
+    /// per-feed and the end-of-file flush, because the flush missing the sequential rule opened a plan
+    /// index the cutter never reached and cost the archive its final segment (audit SEG-103).
+    private func bridgedAudioSegmentIndex(_ packet: UnsafeMutablePointer<AVPacket>, audio: AudioConfig) -> Int {
+        if isLive { return liveCurrentSegmentIndex }
+        if audioFollowsVideoCut { return vodCutter.current }
+        return segmentIndex(forSourcePts: av_rescale_q(packet.pointee.pts, audio.inputTimeBase, sourceVideoTimeBase))
+    }
+
     // MARK: - Look-behind finalize helpers
 
     /// Sample duration (source video TB) written for a look-behind video packet. Always telescope to
diff --git a/Tests/AetherEngineTests/SequentialBridgedTailPlaylistTests.swift b/Tests/AetherEngineTests/SequentialBridgedTailPlaylistTests.swift
new file mode 100644
index 000000000..bf58d125d
--- /dev/null
+++ b/Tests/AetherEngineTests/SequentialBridgedTailPlaylistTests.swift
@@ -0,0 +1,212 @@
+import Foundation
+import Testing
+@testable import AetherEngine
+
+/// Audit SEG-103: on a sequential origin the bridged audio follows the video cutter (7.22), but the
+/// end-of-file flush of the bridge still routed its tail by plan time. When the last GOP crossed the
+/// last plan boundary, that tail opened the plan index the cutter never reached: the real final
+/// segment was closed as not-final, its duration never reported, and ENDLIST landed one segment early,
+/// cutting the end of the archive off.
+@Suite("A sequential archive whose last GOP crosses the last plan boundary lists its whole tail")
+struct SequentialBridgedTailPlaylistTests {
+
+    /// 16 s, H.264 16x16 at 10 fps with keyframes at 0, 9 and 11 s, and silent mono Opus (bridged to
+    /// FLAC) in 120 ms frames. The first GOP outlasts every packet the open samples, so a forward-only
+    /// session knows one keyframe and plans the uniform 4 s stride (boundaries 0, 4, 8, 12). The cutter
+    /// ends in seg2 ([9, 16)), while the flushed audio tail sits in plan seg3. Regenerate with:
+    ///
+    ///     ffmpeg -f lavfi -i "color=c=black:s=16x16:r=10:d=16" -f lavfi -i "anullsrc=r=48000:cl=mono" \
+    ///       -map 0:v -map 1:a -c:v libx264 -preset ultrafast -profile:v baseline -crf 51 -g 1000 \
+    ///       -sc_threshold 0 -force_key_frames "0,9,11" -x264-params bframes=0 -pix_fmt yuv420p \
+    ///       -c:a libopus -b:a 6k -frame_duration 120 -ac 1 -t 16 -f matroska - > tail.mkv
+    ///
+    /// Written to a pipe so the file carries no Cues: the whole file fits the first read, and with its
+    /// Cues in the buffer the plan would come out keyframe-aligned and hide the defect.
+    private static let fixtureBase64 = [
+        "GkXfo6NChoEBQveBAULygQRC84EIQoKIbWF0cm9za2FCh4EEQoWBAhhTgGcB/////////xFNm3Sxv4S8aizJTbuLU6uEFUmp",
+        "ZlOsgaFNu4tTq4QWVK5rU6yB8U27jFOrhBJUw2dTrIIB3OwBAAAAAAAAYgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
+        "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAFUmp",
+        "Zsu/hLjH+Nwq17GDD0JATYCNTGF2ZjYyLjEyLjEwMVdBjUxhdmY2Mi4xMi4xMDFzpJA0kss7xod4ugMjeGfAY/KcRImIQM9A",
+        "AAAAAAAWVK5rQOW/hJ6CS2SuAQAAAAAAAHHXgQFzxYiAoAqYJZs2m5yBACK1nIN1bmSIgQCGj1ZfTVBFRzQvSVNPL0FWQ4OB",
+        "ASPjg4QF9eEA4JCwgRC6gRCagQJVsIRVuYEBY6KlAULACv/hABVnQsAK2nsBEAAAAwAQAAADAUDxImoBAAVozgGXIK4BAAAA",
+        "AAAAXNeBAnPFiM7OMF8gqYhDnIEAIrWcg3VuZIiBAIaGQV9PUFVTVqqDYy6gVruEBMS0AIOBAuGRn4EBtYhA53AAAAAAAGJk",
+        "gRBjopNPcHVzSGVhZAEBOAGAuwAAAAAAElTDZ0CVv4Qb4HYic3OgY8CAZ8iaRaOHRU5DT0RFUkSHjUxhdmY2Mi4xMi4xMDFz",
+        "c7NjwItjxYiAoAqYJZs2m2fIokWjh0VOQ09ERVJEh5VMYXZjNjIuMjguMTAxIGxpYngyNjRzc7NjwItjxYjOzjBfIKmIQ2fI",
+        "okWjh0VOQ09ERVJEh5VMYXZjNjIuMjguMTAxIGxpYm9wdXMfQ7Z1RDe/hAXdYNDngQCjoYIAAIAaDgL5jsjhz5S+lx76gm6w",
+        "Aissw4zYC9cFtr0Q0qNCaoEAAIAAAAJVBgX//1HcRem95tlIt5Ys2CDZI+7veDI2NCAtIGNvcmUgMTY1IHIzMjIyIGIzNTYw",
+        "NWEgLSBILjI2NC9NUEVHLTQgQVZDIGNvZGVjIC0gQ29weWxlZnQgMjAwMy0yMDI1IC0gaHR0cDovL3d3dy52aWRlb2xhbi5v",
+        "cmcveDI2NC5odG1sIC0gb3B0aW9uczogY2FiYWM9MCByZWY9MSBkZWJsb2NrPTA6MDowIGFuYWx5c2U9MDowIG1lPWRpYSBz",
+        "dWJtZT0wIHBzeT0xIHBzeV9yZD0xLjAwOjAuMDAgbWl4ZWRfcmVmPTAgbWVfcmFuZ2U9MTYgY2hyb21hX21lPTEgdHJlbGxp",
+        "cz0wIDh4OGRjdD0wIGNxbT0wIGRlYWR6b25lPTIxLDExIGZhc3RfcHNraXA9MSBjaHJvbWFfcXBfb2Zmc2V0PTAgdGhyZWFk",
+        "cz0xIGxvb2thaGVhZF90aHJlYWRzPTEgc2xpY2VkX3RocmVhZHM9MCBucj0wIGRlY2ltYXRlPTEgaW50ZXJsYWNlZD0wIGJs",
+        "dXJheV9jb21wYXQ9MCBjb25zdHJhaW5lZF9pbnRyYT0wIGJmcmFtZXM9MCB3ZWlnaHRwPTAga2V5aW50PTEwMDAga2V5aW50",
+        "X21pbj0xMCBzY2VuZWN1dD0wIGludHJhX3JlZnJlc2g9MCByYz1jcmYgbWJ0cmVlPTAgY3JmPTUxLjAgcWNvbXA9MC42MCBx",
+        "cG1pbj0wIHFwbWF4PTY5IHFwc3RlcD00IGlwX3JhdGlvPTEuNDAgYXE9MACAAAAACWWIhDomKAAVwKONgQBkAAAAAAVBmiAy",
+        "lKOfggB5gBkCKyzDjNgL1wW2vRDSAissw4zYC9cFtr0Q0qONgQDIAAAAAAVBmkA2lKOfggDxgBkCKyzDjNgL1wW2vRDSAiss",
+        "w4zYC9cFtr0Q0qONgQEsAAAAAAVBmmA2lKOfggFpgBkCKyzDjNgL1wW2vRDSAissw4zYC9cFtr0Q0qONgQGQAAAAAAVBmoA2",
+        "lKOfggHhgBkCKyzDjNgL1wW2vRDSAissw4zYC9cFtr0Q0qONgQH0AAAAAAVBmqA2lKOfggJZgBkCKyzDjNgL1wW2vRDSAiss",
+        "w4zYC9cFtr0Q0qONgQJYAAAAAAVBmsA6lKONgQK8AAAAAAVBmuA6lKOfggLRgBkCKyzDjNgL1wW2vRDSAissw4zYC9cFtr0Q",
+        "0qONgQMgAAAAAAVBmwA6lKOfggNJgBkCKyzDjNgL1wW2vRDSAissw4zYC9cFtr0Q0qONgQOEAAAAAAVBmyA6lKOfggPBgBkC",
+        "KyzDjNgL1wW2vRDSAissw4zYC9cFtr0Q0qONgQPoAAAAAAVBm0A6lB9DtnVBqL+EaVCv8ueCBDmjn4IAAIAZAissw4zYC9cF",
+        "tr0Q0gIrLMOM2AvXBba9ENKjjYEAEwAAAAAFQZtgOpSjn4IAeIAZAissw4zYC9cFtr0Q0gIrLMOM2AvXBba9ENKjjYEAdwAA",
+        "AAAFQZuAOpSjjYEA2wAAAAAFQZugOpSjn4IA8IAZAissw4zYC9cFtr0Q0gIrLMOM2AvXBba9ENKjjYEBPwAAAAAFQZvAOpSj",
+        "n4IBaIAZAissw4zYC9cFtr0Q0gIrLMOM2AvXBba9ENKjjYEBowAAAAAFQZvgOpSjn4IB4IAZAissw4zYC9cFtr0Q0gIrLMOM",
+        "2AvXBba9ENKjjYECBwAAAAAFQZoAOpSjn4ICWIAZAissw4zYC9cFtr0Q0gIrLMOM2AvXBba9ENKjjYECawAAAAAFQZogOpSj",
+        "n4IC0IAZAissw4zYC9cFtr0Q0gIrLMOM2AvXBba9ENKjjYECzwAAAAAFQZpAOpSjjYEDMwAAAAAFQZpgOpSjn4IDSIAZAiss",
+        "w4zYC9cFtr0Q0gIrLMOM2AvXBba9ENKjjYEDlwAAAAAFQZqAOpQfQ7Z1Qcm/hGOleDnnggf5o5+CAACAGQIrLMOM2AvXBba9",
+        "ENICKyzDjNgL1wW2vRDSo42BADsAAAAABUGaoDqUo5+CAHiAGQIrLMOM2AvXBba9ENICKyzDjNgL1wW2vRDSo42BAJ8AAAAA",
+        "BUGawDqUo5+CAPCAGQIrLMOM2AvXBba9ENICKyzDjNgL1wW2vRDSo42BAQMAAAAABUGa4DqUo5+CAWiAGQIrLMOM2AvXBba9",
+        "ENICKyzDjNgL1wW2vRDSo42BAWcAAAAABUGbADqUo42BAcsAAAAABUGbIDqUo5+CAeCAGQIrLMOM2AvXBba9ENICKyzDjNgL",
+        "1wW2vRDSo42BAi8AAAAABUGbQDqUo5+CAliAGQIrLMOM2AvXBba9ENICKyzDjNgL1wW2vRDSo42BApMAAAAABUGbYDqUo5+C",
+        "AtCAGQIrLMOM2AvXBba9ENICKyzDjNgL1wW2vRDSo42BAvcAAAAABUGbgDqUo5+CA0iAGQIrLMOM2AvXBba9ENICKyzDjNgL",
+        "1wW2vRDSo42BA1sAAAAABUGboDqUo5+CA8CAGQIrLMOM2AvXBba9ENICKyzDjNgL1wW2vRDSo42BA78AAAAABUGbwDqUH0O2",
+        "dUHYv4RN4H6V54IMHKONgQAAAAAAAAVBm+A6lKOfggAVgBkCKyzDjNgL1wW2vRDSAissw4zYC9cFtr0Q0qONgQBkAAAAAAVB",
+        "mgA6lKOfggCNgBkCKyzDjNgL1wW2vRDSAissw4zYC9cFtr0Q0qONgQDIAAAAAAVBmiA6lKOfggEFgBkCKyzDjNgL1wW2vRDS",
+        "Aissw4zYC9cFtr0Q0qONgQEsAAAAAAVBmkA6lKOfggF9gBkCKyzDjNgL1wW2vRDSAissw4zYC9cFtr0Q0qONgQGQAAAAAAVB",
+        "mmA6lKOfggH1gBkCKyzDjNgL1wW2vRDSAissw4zYC9cFtr0Q0qONgQH0AAAAAAVBmoA6lKONgQJYAAAAAAVBmqA6lKOfggJt",
+        "gBkCKyzDjNgL1wW2vRDSAissw4zYC9cFtr0Q0qONgQK8AAAAAAVBmsA6lKOfggLlgBkCKyzDjNgL1wW2vRDSAissw4zYC9cF",
+        "tr0Q0qONgQMgAAAAAAVBmuA6lKOfggNdgBkCKyzDjNgL1wW2vRDSAissw4zYC9cFtr0Q0qONgQOEAAAAAAVBmwA6lKOfggPV",
+        "gBkCKyzDjNgL1wW2vRDSAissw4zYC9cFtr0Q0qONgQPoAAAAAAVBmyA6lB9DtnVB2L+EPAUI9+eCEGmjn4IAAIAZAissw4zY",
+        "C9cFtr0Q0gIrLMOM2AvXBba9ENKjjYH//wAAAAAFQZtAOpSjjYEAYwAAAAAFQZtgOpSjn4IAeIAZAissw4zYC9cFtr0Q0gIr",
+        "LMOM2AvXBba9ENKjjYEAxwAAAAAFQZuAOpSjn4IA8IAZAissw4zYC9cFtr0Q0gIrLMOM2AvXBba9ENKjjYEBKwAAAAAFQZug",
+        "OpSjn4IBaIAZAissw4zYC9cFtr0Q0gIrLMOM2AvXBba9ENKjjYEBjwAAAAAFQZvAOpSjn4IB4IAZAissw4zYC9cFtr0Q0gIr",
+        "LMOM2AvXBba9ENKjjYEB8wAAAAAFQZvgOpSjn4ICWIAZAissw4zYC9cFtr0Q0gIrLMOM2AvXBba9ENKjjYECVwAAAAAFQZoA",
+        "OpSjjYECuwAAAAAFQZogOpSjn4IC0IAZAissw4zYC9cFtr0Q0gIrLMOM2AvXBba9ENKjjYEDHwAAAAAFQZpAOpSjn4IDSIAZ",
+        "Aissw4zYC9cFtr0Q0gIrLMOM2AvXBba9ENKjjYEDgwAAAAAFQZpgOpSjn4IDwIAZAissw4zYC9cFtr0Q0gIrLMOM2AvXBba9",
+        "ENKjjYED5wAAAAAFQZqAOpQfQ7Z1Qai/hGM6jEvnghSho5+CAACAGQIrLMOM2AvXBba9ENICKyzDjNgL1wW2vRDSo42BABMA",
+        "AAAABUGaoDqUo5+CAHiAGQIrLMOM2AvXBba9ENICKyzDjNgL1wW2vRDSo42BAHcAAAAABUGawDqUo42BANsAAAAABUGa4DqU",
+        "o5+CAPCAGQIrLMOM2AvXBba9ENICKyzDjNgL1wW2vRDSo42BAT8AAAAABUGbADqUo5+CAWiAGQIrLMOM2AvXBba9ENICKyzD",
+        "jNgL1wW2vRDSo42BAaMAAAAABUGbIDqUo5+CAeCAGQIrLMOM2AvXBba9ENICKyzDjNgL1wW2vRDSo42BAgcAAAAABUGbQDqU",
+        "o5+CAliAGQIrLMOM2AvXBba9ENICKyzDjNgL1wW2vRDSo42BAmsAAAAABUGbYDqUo5+CAtCAGQIrLMOM2AvXBba9ENICKyzD",
+        "jNgL1wW2vRDSo42BAs8AAAAABUGbgDqUo42BAzMAAAAABUGboDqUo5+CA0iAGQIrLMOM2AvXBba9ENICKyzDjNgL1wW2vRDS",
+        "o42BA5cAAAAABUGbwDqUH0O2dUHJv4S/7m/C54IYYaOfggAAgBkCKyzDjNgL1wW2vRDSAissw4zYC9cFtr0Q0qONgQA7AAAA",
+        "AAVBm+A6lKOfggB4gBkCKyzDjNgL1wW2vRDSAissw4zYC9cFtr0Q0qONgQCfAAAAAAVBmgA6lKOfggDwgBkCKyzDjNgL1wW2",
+        "vRDSAissw4zYC9cFtr0Q0qONgQEDAAAAAAVBmiA6lKOfggFogBkCKyzDjNgL1wW2vRDSAissw4zYC9cFtr0Q0qONgQFnAAAA",
+        "AAVBmkA6lKONgQHLAAAAAAVBmmA6lKOfggHggBkCKyzDjNgL1wW2vRDSAissw4zYC9cFtr0Q0qONgQIvAAAAAAVBmoA6lKOf",
+        "ggJYgBkCKyzDjNgL1wW2vRDSAissw4zYC9cFtr0Q0qONgQKTAAAAAAVBmqA6lKOfggLQgBkCKyzDjNgL1wW2vRDSAissw4zY",
+        "C9cFtr0Q0qONgQL3AAAAAAVBmsA6lKOfggNIgBkCKyzDjNgL1wW2vRDSAissw4zYC9cFtr0Q0qONgQNbAAAAAAVBmuA6lKOf",
+        "ggPAgBkCKyzDjNgL1wW2vRDSAissw4zYC9cFtr0Q0qONgQO/AAAAAAVBmwA6lB9DtnVB2L+EcCOFlOeCHISjjYEAAAAAAAAF",
+        "QZsgOpSjn4IAFYAZAissw4zYC9cFtr0Q0gIrLMOM2AvXBba9ENKjjYEAZAAAAAAFQZtAOpSjn4IAjYAZAissw4zYC9cFtr0Q",
+        "0gIrLMOM2AvXBba9ENKjjYEAyAAAAAAFQZtgOpSjn4IBBYAZAissw4zYC9cFtr0Q0gIrLMOM2AvXBba9ENKjjYEBLAAAAAAF",
+        "QZuAOpSjn4IBfYAZAissw4zYC9cFtr0Q0gIrLMOM2AvXBba9ENKjjYEBkAAAAAAFQZugOpSjn4IB9YAZAissw4zYC9cFtr0Q",
+        "0gIrLMOM2AvXBba9ENKjjYEB9AAAAAAFQZvAOpSjjYECWAAAAAAFQZvgOpSjn4ICbYAZAissw4zYC9cFtr0Q0gIrLMOM2AvX",
+        "Bba9ENKjjYECvAAAAAAFQZoAOpSjn4IC5YAZAissw4zYC9cFtr0Q0gIrLMOM2AvXBba9ENKjjYEDIAAAAAAFQZogOpSjn4ID",
+        "XYAZAissw4zYC9cFtr0Q0gIrLMOM2AvXBba9ENKjjYEDhAAAAAAFQZpAOpSjn4ID1YAZAissw4zYC9cFtr0Q0gIrLMOM2AvX",
+        "Bba9ENKjjYED6AAAAAAFQZpgOpQfQ7Z1Qd6/hO+e4KzngiDRo5+CAACAGQIrLMOM2AvXBba9ENICKyzDjNgL1wW2vRDSo42B",
+        "//8AAAAABUGagDqUo42BAGMAAAAABUGaoDqUo5+CAHiAGQIrLMOM2AvXBba9ENICKyzDjNgL1wW2vRDSo42BAMcAAAAABUGa",
+        "wDqUo5+CAPCAGQIrLMOM2AvXBba9ENICKyzDjNgL1wW2vRDSo42BASsAAAAABUGa4DqUo5+CAWiAGQIrLMOM2AvXBba9ENIC",
+        "KyzDjNgL1wW2vRDSo42BAY8AAAAABUGbADqUo5+CAeCAGQIrLMOM2AvXBba9ENICKyzDjNgL1wW2vRDSo42BAfMAAAAABUGb",
+        "IDqUo5+CAliAGQIrLMOM2AvXBba9ENICKyzDjNgL1wW2vRDSo5OBAleAAAAAC2WIggEKJigACCDgo42BArsAAAAABUGaIDaU",
+        "o5+CAtCAGQIrLMOM2AvXBba9ENICKyzDjNgL1wW2vRDSo42BAx8AAAAABUGaQDaUo5+CA0iAGQIrLMOM2AvXBba9ENICKyzD",
+        "jNgL1wW2vRDSo42BA4MAAAAABUGaYDaUo5+CA8CAGQIrLMOM2AvXBba9ENICKyzDjNgL1wW2vRDSo42BA+cAAAAABUGagDaU",
+        "H0O2dUGov4R5ya9c54IlCaOfggAAgBkCKyzDjNgL1wW2vRDSAissw4zYC9cFtr0Q0qONgQATAAAAAAVBmqA2lKOfggB4gBkC",
+        "KyzDjNgL1wW2vRDSAissw4zYC9cFtr0Q0qONgQB3AAAAAAVBmsA6lKONgQDbAAAAAAVBmuA6lKOfggDwgBkCKyzDjNgL1wW2",
+        "vRDSAissw4zYC9cFtr0Q0qONgQE/AAAAAAVBmwA6lKOfggFogBkCKyzDjNgL1wW2vRDSAissw4zYC9cFtr0Q0qONgQGjAAAA",
+        "AAVBmyA6lKOfggHggBkCKyzDjNgL1wW2vRDSAissw4zYC9cFtr0Q0qONgQIHAAAAAAVBm0A6lKOfggJYgBkCKyzDjNgL1wW2",
+        "vRDSAissw4zYC9cFtr0Q0qONgQJrAAAAAAVBm2A6lKOfggLQgBkCKyzDjNgL1wW2vRDSAissw4zYC9cFtr0Q0qONgQLPAAAA",
+        "AAVBm4A6lKONgQMzAAAAAAVBm6A6lKOfggNIgBkCKyzDjNgL1wW2vRDSAissw4zYC9cFtr0Q0qONgQOXAAAAAAVBm8A6lB9D",
+        "tnVBz7+E81n7sOeCKMmjn4IAAIAZAissw4zYC9cFtr0Q0gIrLMOM2AvXBba9ENKjjYEAOwAAAAAFQZvgOpSjn4IAeIAZAiss",
+        "w4zYC9cFtr0Q0gIrLMOM2AvXBba9ENKjjYEAnwAAAAAFQZoAOpSjn4IA8IAZAissw4zYC9cFtr0Q0gIrLMOM2AvXBba9ENKj",
+        "jYEBAwAAAAAFQZogOpSjn4IBaIAZAissw4zYC9cFtr0Q0gIrLMOM2AvXBba9ENKjjYEBZwAAAAAFQZpAOpSjjYEBywAAAAAF",
+        "QZpgOpSjn4IB4IAZAissw4zYC9cFtr0Q0gIrLMOM2AvXBba9ENKjk4ECL4AAAAALZYiEBCiYoAAgg4Cjn4ICWIAZAissw4zY",
+        "C9cFtr0Q0gIrLMOM2AvXBba9ENKjjYECkwAAAAAFQZogNpSjn4IC0IAZAissw4zYC9cFtr0Q0gIrLMOM2AvXBba9ENKjjYEC",
+        "9wAAAAAFQZpANpSjn4IDSIAZAissw4zYC9cFtr0Q0gIrLMOM2AvXBba9ENKjjYEDWwAAAAAFQZpgNpSjn4IDwIAZAissw4zY",
+        "C9cFtr0Q0gIrLMOM2AvXBba9ENKjjYEDvwAAAAAFQZqANpQfQ7Z1Qdi/hGw/LR/ngizso42BAAAAAAAABUGaoDaUo5+CABWA",
+        "GQIrLMOM2AvXBba9ENICKyzDjNgL1wW2vRDSo42BAGQAAAAABUGawDqUo5+CAI2AGQIrLMOM2AvXBba9ENICKyzDjNgL1wW2",
+        "vRDSo42BAMgAAAAABUGa4DqUo5+CAQWAGQIrLMOM2AvXBba9ENICKyzDjNgL1wW2vRDSo42BASwAAAAABUGbADqUo5+CAX2A",
+        "GQIrLMOM2AvXBba9ENICKyzDjNgL1wW2vRDSo42BAZAAAAAABUGbIDqUo5+CAfWAGQIrLMOM2AvXBba9ENICKyzDjNgL1wW2",
+        "vRDSo42BAfQAAAAABUGbQDqUo42BAlgAAAAABUGbYDqUo5+CAm2AGQIrLMOM2AvXBba9ENICKyzDjNgL1wW2vRDSo42BArwA",
+        "AAAABUGbgDqUo5+CAuWAGQIrLMOM2AvXBba9ENICKyzDjNgL1wW2vRDSo42BAyAAAAAABUGboDqUo5+CA12AGQIrLMOM2AvX",
+        "Bba9ENICKyzDjNgL1wW2vRDSo42BA4QAAAAABUGbwDqUo5+CA9WAGQIrLMOM2AvXBba9ENICKyzDjNgL1wW2vRDSo42BA+gA",
+        "AAAABUGb4DqUH0O2dUHYv4RyMcKR54IxOaOfggAAgBkCKyzDjNgL1wW2vRDSAissw4zYC9cFtr0Q0qONgf//AAAAAAVBmgA6",
+        "lKONgQBjAAAAAAVBmiA6lKOfggB4gBkCKyzDjNgL1wW2vRDSAissw4zYC9cFtr0Q0qONgQDHAAAAAAVBmkA6lKOfggDwgBkC",
+        "KyzDjNgL1wW2vRDSAissw4zYC9cFtr0Q0qONgQErAAAAAAVBmmA6lKOfggFogBkCKyzDjNgL1wW2vRDSAissw4zYC9cFtr0Q",
+        "0qONgQGPAAAAAAVBmoA6lKOfggHggBkCKyzDjNgL1wW2vRDSAissw4zYC9cFtr0Q0qONgQHzAAAAAAVBmqA6lKOfggJYgBkC",
+        "KyzDjNgL1wW2vRDSAissw4zYC9cFtr0Q0qONgQJXAAAAAAVBmsA6lKONgQK7AAAAAAVBmuA6lKOfggLQgBkCKyzDjNgL1wW2",
+        "vRDSAissw4zYC9cFtr0Q0qONgQMfAAAAAAVBmwA6lKOfggNIgBkCKyzDjNgL1wW2vRDSAissw4zYC9cFtr0Q0qONgQODAAAA",
+        "AAVBmyA6lKOfggPAgBkCKyzDjNgL1wW2vRDSAissw4zYC9cFtr0Q0qONgQPnAAAAAAVBm0A6lB9DtnVBqL+EMUMKneeCNXGj",
+        "n4IAAIAZAissw4zYC9cFtr0Q0gIrLMOM2AvXBba9ENKjjYEAEwAAAAAFQZtgOpSjn4IAeIAZAissw4zYC9cFtr0Q0gIrLMOM",
+        "2AvXBba9ENKjjYEAdwAAAAAFQZuAOpSjjYEA2wAAAAAFQZugOpSjn4IA8IAZAissw4zYC9cFtr0Q0gIrLMOM2AvXBba9ENKj",
+        "jYEBPwAAAAAFQZvAOpSjn4IBaIAZAissw4zYC9cFtr0Q0gIrLMOM2AvXBba9ENKjjYEBowAAAAAFQZvgOpSjn4IB4IAZAiss",
+        "w4zYC9cFtr0Q0gIrLMOM2AvXBba9ENKjjYECBwAAAAAFQZoAOpSjn4ICWIAZAissw4zYC9cFtr0Q0gIrLMOM2AvXBba9ENKj",
+        "jYECawAAAAAFQZogOpSjn4IC0IAZAissw4zYC9cFtr0Q0gIrLMOM2AvXBba9ENKjjYECzwAAAAAFQZpAOpSjjYEDMwAAAAAF",
+        "QZpgOpSjn4IDSIAZAissw4zYC9cFtr0Q0gIrLMOM2AvXBba9ENKjjYEDlwAAAAAFQZqAOpQfQ7Z1Qcm/hI1CLejngjkxo5+C",
+        "AACAGQIrLMOM2AvXBba9ENICKyzDjNgL1wW2vRDSo42BADsAAAAABUGaoDqUo5+CAHiAGQIrLMOM2AvXBba9ENICKyzDjNgL",
+        "1wW2vRDSo42BAJ8AAAAABUGawDqUo5+CAPCAGQIrLMOM2AvXBba9ENICKyzDjNgL1wW2vRDSo42BAQMAAAAABUGa4DqUo5+C",
+        "AWiAGQIrLMOM2AvXBba9ENICKyzDjNgL1wW2vRDSo42BAWcAAAAABUGbADqUo42BAcsAAAAABUGbIDqUo5+CAeCAGQIrLMOM",
+        "2AvXBba9ENICKyzDjNgL1wW2vRDSo42BAi8AAAAABUGbQDqUo5+CAliAGQIrLMOM2AvXBba9ENICKyzDjNgL1wW2vRDSo42B",
+        "ApMAAAAABUGbYDqUo5+CAtCAGQIrLMOM2AvXBba9ENICKyzDjNgL1wW2vRDSo42BAvcAAAAABUGbgDqUo5+CA0iAGQIrLMOM",
+        "2AvXBba9ENICKyzDjNgL1wW2vRDSo42BA1sAAAAABUGboDqUo5+CA8CAGQIrLMOM2AvXBba9ENICKyzDjNgL1wW2vRDSo42B",
+        "A78AAAAABUGbwDqUH0O2dUCmv4R3b3PO54I9VKONgQAAAAAAAAVBm+A6lKOfggAVgBkCKyzDjNgL1wW2vRDSAissw4zYC9cF",
+        "tr0Q0qONgQBkAAAAAAVBmgA6lKOfggCNgBkCKyzDjNgL1wW2vRDSAissw4zYC9cFtr0Q0qONgQDIAAAAAAVBmiA6lKCroZ+C",
+        "AQUAGQIrLMOM2AvXBba9ENICKyzDjNgL1wW2vRDSm4EvdaKEBGGFYA==",
+    ]
+    private static let videoFrames = 160
+
+    /// Video samples (track 1) across every fragment of a segment, from the `trun` sample counts.
+    private static func videoSampleCount(_ segment: Data) -> Int {
+        let bytes = [UInt8](segment)
+        func u32(_ off: Int) -> Int {
+            Int(bytes[off]) << 24 | Int(bytes[off + 1]) << 16 | Int(bytes[off + 2]) << 8 | Int(bytes[off + 3])
+        }
+        func boxes(_ range: Range<Int>) -> [(String, Range<Int>)] {
+            var out: [(String, Range<Int>)] = []
+            var off = range.lowerBound
+            while off + 8 <= range.upperBound {
+                let size = u32(off)
+                guard size >= 8, off + size <= range.upperBound else { break }
+                out.append((String(decoding: bytes[off + 4..<off + 8], as: UTF8.self), (off + 8)..<(off + size)))
+                off += size
+            }
+            return out
+        }
+        var count = 0
+        for (type, moof) in boxes(0..<bytes.count) where type == "moof" {
+            for (t2, traf) in boxes(moof) where t2 == "traf" {
+                var track = 0
+                var samples = 0
+                for (t3, body) in boxes(traf) {
+                    if t3 == "tfhd" { track = u32(body.lowerBound + 4) }
+                    if t3 == "trun" { samples += u32(body.lowerBound + 4) }
+                }
+                if track == 1 { count += samples }
+            }
+        }
+        return count
+    }
+
+    @Test("the finished playlist lists every video frame and the whole duration", .timeLimit(.minutes(1)))
+    func bridgedTailKeepsTheFinalSegment() async throws {
+        let body = try #require(Data(base64Encoded: Self.fixtureBase64.joined()))
+        let server = try #require(ScriptedOriginServer { _ in
+            .init(status: 200, declaredLength: nil, close: true, body: body)
+        })
+        defer { server.stop() }
+        let url = URL(string: "http://127.0.0.1:\(server.port)/tail.mkv")!
+        let engine = HLSVideoEngine(url: url, dvModeAvailable: false,
+                                    sequentialOrigin: true, declaredDurationSeconds: 16)
+        _ = try engine.start()
+        defer { engine.stop() }
+        let mediaURL = try #require(engine.mediaPlaylistURL)
+
+        var playlist = ""
+        try await waitFor {
+            playlist = (try? String(contentsOf: mediaURL, encoding: .utf8)) ?? ""
+            return playlist.contains("#EXT-X-ENDLIST")
+        }
+
+        let lines = playlist.split(whereSeparator: \.isNewline).map(String.init)
+        let durations = lines.filter { $0.hasPrefix("#EXTINF:") }
+            .compactMap { Double($0.dropFirst("#EXTINF:".count).split(separator: ",").first ?? "") }
+        #expect(abs(durations.reduce(0, +) - 16) < 0.6,
+                "EXTINF sums to \(durations.reduce(0, +)) s for a 16 s source:\n\(playlist)")
+
+        var frames = 0
+        for uri in lines where uri.hasSuffix(".mp4") && !uri.hasPrefix("#") {
+            let data = try Data(contentsOf: mediaURL.deletingLastPathComponent().appendingPathComponent(uri))
+            frames += Self.videoSampleCount(data)
+        }
+        #expect(frames == Self.videoFrames,
+                "the listed segments carry \(frames) of \(Self.videoFrames) video frames:\n\(playlist)")
+    }
+}

From e191b80384d4ce362a1fff9c4e555f011cd64f47 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 06:48:00 +0200
Subject: [PATCH 176/359] refactor(demuxer): judge index entries by the packet
 funnel's plausibility rule (audit HLS-102)

The two fix branches each introduced the same 2^62 ticks / 4e9 s bound. The index
check now delegates to SourceTimestampBounds.plausible(_:timeBase:) so the rule has
one definition.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 Sources/AetherEngine/Demuxer/Demuxer.swift | 18 +++++++-----------
 1 file changed, 7 insertions(+), 11 deletions(-)

diff --git a/Sources/AetherEngine/Demuxer/Demuxer.swift b/Sources/AetherEngine/Demuxer/Demuxer.swift
index 391fba35a..867bbb73c 100644
--- a/Sources/AetherEngine/Demuxer/Demuxer.swift
+++ b/Sources/AetherEngine/Demuxer/Demuxer.swift
@@ -429,20 +429,16 @@ public final class Demuxer: @unchecked Sendable {
         return overflow ? nil : placed
     }
 
-    /// Whether an index entry can be a real position (audit HLS-102): under 2^62 ticks, so any
-    /// difference of two entries fits `Int64`, and under 4e9 s on its own time base. libavformat
-    /// rejects only NOPTS and the relative-timestamp band near `Int64.max`; entries near `Int64.min`
-    /// and just below the band reach the plan builders otherwise. Epoch-anchored sources stay inside
-    /// both limits (1.79e18 ns in 2026 is under 2^62 until about 2116, 1.79e9 epoch seconds under 4e9
-    /// until about 2096).
+    /// Whether an index entry can be a real position (audit HLS-102), by the same rule the packet
+    /// funnel applies (`SourceTimestampBounds.plausible(_:timeBase:)`). libavformat rejects only NOPTS
+    /// and the relative-timestamp band near `Int64.max`; entries near `Int64.min` and just below the
+    /// band reach the plan builders otherwise.
     static func isPlausibleIndexTimestamp(_ ts: Int64, timeBase: AVRational) -> Bool {
-        guard ts != Int64.min, ts.magnitude < UInt64(1) << 62,
-              timeBase.num > 0, timeBase.den > 0 else { return false }
-        return abs(Double(ts) * Double(timeBase.num) / Double(timeBase.den)) < maxPlausibleIndexSeconds
+        guard timeBase.num > 0, timeBase.den > 0 else { return false }
+        return SourceTimestampBounds.plausible(ts, timeBase: timeBase) != Int64.min
     }
 
-    static let maxPlausibleIndexTicks: Double = 0x1p62
-    static let maxPlausibleIndexSeconds: Double = 4e9
+    static let maxPlausibleIndexTicks = Double(SourceTimestampBounds.demuxedMagnitude)
 
     /// Seconds as ticks on `timeBase`, nil unless the result is finite and under 2^62 ticks (audit
     /// DMX-113, BIT-105). This is where every seconds-based reposition becomes an integer, and

From 8c5a4208ca81e85b7361e6a96983e5ad51670916 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 06:48:54 +0200
Subject: [PATCH 177/359] fix(network): throttle and escape what a tokenless
 LAN peer can put in the log (audit NET-111)

A connection that never presented the session token cost the host's
log two unthrottled lines per request (the rejection and the 404), and
its request line was attacker text split only on CRLF, so a bare LF
forged a line of its own. Every line such a connection can cause
(rejection, malformed or non-UTF8 request, oversize head, EOF or recv
error mid-head) now shares one LogThrottle with a tally, the rejection
and its 404 are one line, and request text is logged with C0 controls
and DEL escaped (a stranger's cut at 256 characters). Local to the
server, because EngineLog passes the multi-line playlist bodies this
server logs on purpose.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../AetherEngine/Network/HLSLocalServer.swift | 91 +++++++++++++++----
 .../HLSLocalServerSlowPeerTests.swift         | 35 +++++++
 2 files changed, 107 insertions(+), 19 deletions(-)

diff --git a/Sources/AetherEngine/Network/HLSLocalServer.swift b/Sources/AetherEngine/Network/HLSLocalServer.swift
index 7908fb63b..510805117 100644
--- a/Sources/AetherEngine/Network/HLSLocalServer.swift
+++ b/Sources/AetherEngine/Network/HLSLocalServer.swift
@@ -248,7 +248,32 @@ final class HLSLocalServer: @unchecked Sendable {
         var line = "\(method) \(routePath)"
         if !query.isEmpty { line += "?\(query)" }
         if let version { line += " \(version)" }
-        return line
+        return escapedForLog(line)
+    }
+
+    /// Longest stretch of a stranger's request text a log line carries. A head may be 8 KB, and one
+    /// line of that per interval would still crowd a small log ring.
+    static let maximumStrangerText = 256
+
+    /// Request text as a log line may carry it: C0 controls and DEL escaped, so a bare LF cannot forge
+    /// a line of its own (audit NET-111), and cut after `limit` characters. Done here rather than in
+    /// `EngineLog`, which passes the multi-line playlist bodies this server logs on purpose.
+    static func escapedForLog(_ text: String, limit: Int = .max) -> String {
+        var out = ""
+        var count = 0
+        for scalar in text.unicodeScalars {
+            if count >= limit {
+                out += "..."
+                break
+            }
+            if scalar.value < 0x20 || scalar.value == 0x7F {
+                out += String(format: "\\x%02X", scalar.value)
+            } else {
+                out.unicodeScalars.append(scalar)
+            }
+            count += 1
+        }
+        return out
     }
 
     /// Kernel-assigned ephemeral port. Zero until start() succeeds.
@@ -445,6 +470,10 @@ final class HLSLocalServer: @unchecked Sendable {
     private static let acceptFailureBackoffMicroseconds: useconds_t = 100_000
     private var acceptFailureLog = LogThrottle(interval: 5)
     private var refusalLog = LogThrottle(interval: 5)
+    /// Audit NET-111: every line a connection that never presented the token can cause shares this, so
+    /// a LAN peer looping short connections costs the host's log one line per interval, not two per
+    /// request.
+    private var strangerLog = LogThrottle(interval: 5)
 
     // MARK: - Init
 
@@ -727,7 +756,7 @@ final class HLSLocalServer: @unchecked Sendable {
                 : acceptedAt + unauthenticatedHeadDeadline
             guard let request = readHTTPRequest(
                 fd, firstByteDeadline: firstByteDeadline, authenticated: authenticated) else { return }
-            guard processRequest(request, on: fd) else { return }
+            guard processRequest(request, on: fd, authenticated: authenticated) else { return }
             authenticated = true
         }
     }
@@ -760,8 +789,8 @@ final class HLSLocalServer: @unchecked Sendable {
             }
             if n == 0 {
                 if buffer.isEmpty { return nil }
-                EngineLog.emit("[HLSLocalServer] peer EOF mid-request fd=\(fd)",
-                               category: .hlsServer)
+                emitRequestProblem("[HLSLocalServer] peer EOF mid-request fd=\(fd)",
+                                   authenticated: authenticated)
                 return nil
             }
             if n < 0 {
@@ -772,8 +801,8 @@ final class HLSLocalServer: @unchecked Sendable {
                                    category: .hlsServer, level: authenticated ? .info : .verbose)
                     return nil
                 }
-                EngineLog.emit("[HLSLocalServer] recv error fd=\(fd) errno=\(err)",
-                               category: .hlsServer)
+                emitRequestProblem("[HLSLocalServer] recv error fd=\(fd) errno=\(err)",
+                                   authenticated: authenticated)
                 return nil
             }
             if buffer.isEmpty {
@@ -784,8 +813,8 @@ final class HLSLocalServer: @unchecked Sendable {
                 return buffer.prefix(end + 4)
             }
             if buffer.count > 8192 {
-                EngineLog.emit("[HLSLocalServer] request too large fd=\(fd) bytes=\(buffer.count)",
-                               category: .hlsServer)
+                emitRequestProblem("[HLSLocalServer] request too large fd=\(fd) bytes=\(buffer.count)",
+                                   authenticated: authenticated)
                 return nil
             }
         }
@@ -818,21 +847,40 @@ final class HLSLocalServer: @unchecked Sendable {
         }
     }
 
-    private func processRequest(_ request: Data, on fd: Int32) -> Bool {
+    /// A line caused by a connection that has not presented the token: throttled, since anyone on the
+    /// LAN can cause it (audit NET-111). An authenticated connection's lines go out as they come.
+    private func emitRequestProblem(_ line: String, authenticated: Bool) {
+        guard !authenticated else {
+            EngineLog.emit(line, category: .hlsServer)
+            return
+        }
+        stateLock.lock()
+        let admitted = strangerLog.admit(now: Self.uptimeSeconds())
+        stateLock.unlock()
+        guard let suppressed = admitted else { return }
+        EngineLog.emit(
+            line + (suppressed > 0
+                ? " (\(suppressed) more from unauthenticated connections since the last line)" : ""),
+            category: .hlsServer)
+    }
+
+    private func processRequest(_ request: Data, on fd: Int32, authenticated: Bool) -> Bool {
         byteCounterLock.lock()
         _requestCount &+= 1
         byteCounterLock.unlock()
         guard let text = String(data: request, encoding: .utf8) else {
-            EngineLog.emit("[HLSLocalServer] non-UTF8 request bytes (\(request.count)B)",
-                           category: .hlsServer)
+            emitRequestProblem("[HLSLocalServer] non-UTF8 request bytes (\(request.count)B)",
+                               authenticated: authenticated)
             return false
         }
         let firstLine = text.components(separatedBy: "\r\n").first ?? ""
         let parts = firstLine.split(separator: " ", maxSplits: 2,
                                     omittingEmptySubsequences: true)
         guard parts.count >= 2 else {
-            EngineLog.emit("[HLSLocalServer] malformed request line: '\(firstLine)'",
-                           category: .hlsServer)
+            emitRequestProblem(
+                "[HLSLocalServer] malformed request line: "
+                    + "'\(Self.escapedForLog(firstLine, limit: Self.maximumStrangerText))'",
+                authenticated: authenticated)
             return false
         }
         let rawTarget = String(parts[1])
@@ -850,9 +898,12 @@ final class HLSLocalServer: @unchecked Sendable {
         // The listener is reachable from the whole LAN, so an unprefixed request is a scan or a
         // stale URL, never AVPlayer following a playlist we handed out.
         guard let routePath = Self.pathAfterToken(pathToken, in: path) else {
-            EngineLog.emit("[HLSLocalServer] rejected request without a valid session token: \(firstLine)",
-                           category: .hlsServer)
-            _ = send404(fd: fd, path: path, reason: "bad session token")
+            // One line for the rejection and the 404 together: the path is the stranger's text.
+            emitRequestProblem(
+                "[HLSLocalServer] rejected request without a valid session token, -> 404: "
+                    + Self.escapedForLog(firstLine, limit: Self.maximumStrangerText),
+                authenticated: authenticated)
+            _ = send404(fd: fd, path: path, reason: "bad session token", logged: false)
             return false
         }
         let normalizedPath = (routePath == "/audio.m3u8") ? "/media.m3u8" : routePath
@@ -1328,10 +1379,12 @@ final class HLSLocalServer: @unchecked Sendable {
         }
     }
 
-    private func send404(fd: Int32, path: String, reason: String) -> Bool {
+    private func send404(fd: Int32, path: String, reason: String, logged: Bool = true) -> Bool {
         let response = Self.responseHeader(status: "404 Not Found", contentLength: 0, contentType: nil)
-        EngineLog.emit("[HLSLocalServer] -> 404 \(path) reason=\(reason)",
-                       category: .hlsServer)
+        if logged {
+            EngineLog.emit("[HLSLocalServer] -> 404 \(path) reason=\(reason)",
+                           category: .hlsServer)
+        }
         return writeAll(fd: fd, data: response, path: path)
     }
 
diff --git a/Tests/AetherEngineTests/HLSLocalServerSlowPeerTests.swift b/Tests/AetherEngineTests/HLSLocalServerSlowPeerTests.swift
index 0136fadd7..59370639f 100644
--- a/Tests/AetherEngineTests/HLSLocalServerSlowPeerTests.swift
+++ b/Tests/AetherEngineTests/HLSLocalServerSlowPeerTests.swift
@@ -94,6 +94,41 @@ struct HLSLocalServerSlowPeerTests {
         #expect(tap.matching("[HLSLocalServer] stop: port 0 released").isEmpty)
     }
 
+    /// Audit NET-111: every tokenless request cost the host's log two unthrottled lines, so a LAN
+    /// peer looping short connections could scroll a 300-line ring in a fraction of a second.
+    @Test("A flood of tokenless requests costs the log a handful of lines")
+    func tokenlessFloodIsThrottled() async throws {
+        let tap = LineTap()
+        defer { tap.restore() }
+        let server = HLSLocalServer(provider: StubProvider())
+        try server.start()
+        defer { server.stop() }
+        let marker = "flood-\(UUID().uuidString)"
+        let port = server.port
+
+        let answered = await Self.onOwnThread { () -> Int in
+            var answered = 0
+            for _ in 0 ..< 1000 {
+                guard let fd = Self.connect(port: port, host: "127.0.0.1") else { continue }
+                if Self.requestStatus(fd: fd, path: "/\(marker)/media.m3u8") == 404 { answered += 1 }
+                close(fd)
+            }
+            return answered
+        }
+        #expect(answered == 1000)
+        #expect(tap.matching(marker).count <= 3, "\(tap.matching(marker).count) lines for 1000 requests")
+    }
+
+    @Test("Attacker text is logged with its control characters escaped")
+    func controlCharactersAreEscaped() {
+        #expect(HLSLocalServer.escapedForLog("GET /x\n[HLSLocalServer] GET /forged HTTP/1.1")
+                == "GET /x\\x0A[HLSLocalServer] GET /forged HTTP/1.1")
+        #expect(HLSLocalServer.escapedForLog("a\u{7F}b\tc\u{0}") == "a\\x7Fb\\x09c\\x00")
+        #expect(HLSLocalServer.escapedForLog("GET /seg_1.m4s HTTP/1.1") == "GET /seg_1.m4s HTTP/1.1")
+        #expect(HLSLocalServer.escapedForLog(String(repeating: "a", count: 300), limit: 256)
+                == String(repeating: "a", count: 256) + "...")
+    }
+
     @Test("A repeating failure line goes out once per interval with a tally of the rest")
     func throttleCountsWhatItHeldBack() {
         var throttle = LogThrottle(interval: 5)

From d8ab091355453cb72470dfd905740a205b57c52e Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 06:51:26 +0200
Subject: [PATCH 178/359] fix(mux): the BIT-1 framing verdict belongs to the
 session, not to one muxer (audit BIT-104)

The latch that lets the AE#561 sanitizer read a `00 00 01` head as a
256-511 byte NAL length lived in each MP4SegmentMuxer and started false,
and every seek, restart and reload builds a fresh muxer. The sample a
restart lands on is that muxer's first, so a damaged IRAP with such a
first NAL and an overlong length behind it reached movenc uncut on
every retry, which is the -19602 session death BIT-1 targeted.

A NALFramingLatch is created once per session in start(), carried on the
producer's StreamConfig into every program muxer (an SSAI ad creative
keeps its own), and seeded confirmed only when #365 measured the packets
length-prefixed; the extradata-derived framing is not a measurement.
The residual window is a session whose very first sample is the damaged
one.

Test: two muxers sharing one latch; the first walks a clean sample, the
rebuilt one cuts the damaged sample, a muxer with its own unconfirmed
latch keeps the Annex B head guard.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../Video/HLSSegmentProducer.swift            | 10 ++-
 .../AetherEngine/Video/HLSVideoEngine.swift   |  7 ++-
 .../AetherEngine/Video/MP4SegmentMuxer.swift  | 21 ++++---
 Sources/AetherEngine/Video/NALUnitChain.swift | 15 +++++
 .../AetherEngineTests/NALUnitChainTests.swift | 62 +++++++++++++++++++
 5 files changed, 105 insertions(+), 10 deletions(-)

diff --git a/Sources/AetherEngine/Video/HLSSegmentProducer.swift b/Sources/AetherEngine/Video/HLSSegmentProducer.swift
index 9234f93a6..4785e0864 100644
--- a/Sources/AetherEngine/Video/HLSSegmentProducer.swift
+++ b/Sources/AetherEngine/Video/HLSSegmentProducer.swift
@@ -50,6 +50,9 @@ final class HLSSegmentProducer: @unchecked Sendable {
         /// which is only correct while the two agree; on a source where they do not, every walker
         /// downstream (A53 captions, the DV P7 RPU rewrite) reads the packet at the wrong offsets.
         let nalFramingOverride: VideoNALFraming?
+        /// The session's BIT-1 framing verdict, handed to every muxer this producer builds for the
+        /// program's own track (audit BIT-104).
+        let nalFramingLatch: NALFramingLatch?
 
         init(
             codecpar: UnsafePointer<AVCodecParameters>,
@@ -59,7 +62,8 @@ final class HLSSegmentProducer: @unchecked Sendable {
             convertP7ToProfile81: Bool = false,
             colorOverride: MP4SegmentMuxer.ColorOverride? = nil,
             extradataOverride: [UInt8]? = nil,
-            nalFramingOverride: VideoNALFraming? = nil
+            nalFramingOverride: VideoNALFraming? = nil,
+            nalFramingLatch: NALFramingLatch? = nil
         ) {
             self.codecpar = codecpar
             self.timeBase = timeBase
@@ -69,6 +73,7 @@ final class HLSSegmentProducer: @unchecked Sendable {
             self.colorOverride = colorOverride
             self.extradataOverride = extradataOverride
             self.nalFramingOverride = nalFramingOverride
+            self.nalFramingLatch = nalFramingLatch
         }
     }
 
@@ -2088,7 +2093,8 @@ final class HLSSegmentProducer: @unchecked Sendable {
             // parameter-set change is still the same program, so it keeps them (isAdCreative false).
             doviConfig: isAdCreative ? .keep : videoConfig.doviConfig,
             colorOverride: isAdCreative ? nil : videoConfig.colorOverride,
-            extradataOverride: isAdCreative ? nil : videoConfig.extradataOverride
+            extradataOverride: isAdCreative ? nil : videoConfig.extradataOverride,
+            nalFramingLatch: isAdCreative ? nil : videoConfig.nalFramingLatch
         )
         let muxerAudio: MP4SegmentMuxer.AudioConfig? = audioConfig.map { a in
             MP4SegmentMuxer.AudioConfig(codecpar: a.codecpar, timeBase: a.inputTimeBase, language: a.language)
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine.swift b/Sources/AetherEngine/Video/HLSVideoEngine.swift
index 3411bf6b7..dc7dd78ba 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine.swift
@@ -1540,6 +1540,10 @@ public final class HLSVideoEngine: @unchecked Sendable {
                 category: .session
             )
         }
+        // Audit BIT-104: one framing verdict for the session, seeded only by a measurement (#365).
+        // The extradata-derived framing is a claim, not a measurement.
+        var framingMeasuredLengthPrefixed = false
+        if case .lengthPrefixed? = measuredVideoNALFraming { framingMeasuredLengthPrefixed = true }
         let videoConfig = HLSSegmentProducer.StreamConfig(
             codecpar: UnsafePointer(ownedVideoParams.ptr),
             timeBase: videoTimeBase,
@@ -1548,7 +1552,8 @@ public final class HLSVideoEngine: @unchecked Sendable {
             convertP7ToProfile81: convertP7ToProfile81,
             colorOverride: p5ColorOverride,
             extradataOverride: hevcExtradataOverride,
-            nalFramingOverride: measuredVideoNALFraming
+            nalFramingOverride: measuredVideoNALFraming,
+            nalFramingLatch: NALFramingLatch(confirmed: framingMeasuredLengthPrefixed)
         )
         self.videoStreamIndex = videoIndex
         self.savedVideoConfig = videoConfig
diff --git a/Sources/AetherEngine/Video/MP4SegmentMuxer.swift b/Sources/AetherEngine/Video/MP4SegmentMuxer.swift
index 04c77d85f..b9c422f29 100644
--- a/Sources/AetherEngine/Video/MP4SegmentMuxer.swift
+++ b/Sources/AetherEngine/Video/MP4SegmentMuxer.swift
@@ -72,6 +72,8 @@ final class MP4SegmentMuxer {
         /// has numOfArrays=0 (in-band parameter sets) and the engine rebuilt a proper hvcC with
         /// VPS/SPS/PPS arrays; the mp4 muxer writes extradata directly into the hvcC/avcC box.
         let extradataOverride: [UInt8]?
+        /// The session's framing verdict for this track (audit BIT-104); nil gives the muxer its own.
+        let nalFramingLatch: NALFramingLatch?
 
         init(
             codecpar: UnsafePointer<AVCodecParameters>,
@@ -79,7 +81,8 @@ final class MP4SegmentMuxer {
             codecTagOverride: String?,
             doviConfig: DoviConfigPolicy = .keep,
             colorOverride: ColorOverride? = nil,
-            extradataOverride: [UInt8]? = nil
+            extradataOverride: [UInt8]? = nil,
+            nalFramingLatch: NALFramingLatch? = nil
         ) {
             self.codecpar = codecpar
             self.timeBase = timeBase
@@ -87,6 +90,7 @@ final class MP4SegmentMuxer {
             self.doviConfig = doviConfig
             self.colorOverride = colorOverride
             self.extradataOverride = extradataOverride
+            self.nalFramingLatch = nalFramingLatch
         }
     }
 
@@ -173,17 +177,19 @@ final class MP4SegmentMuxer {
     static let nalChainSanitizerDisabled =
         ProcessInfo.processInfo.environment["AETHER_DISABLE_NAL_SANITIZER"] != nil
     /// How many video samples the AE#561 sanitizer has had to cut, over this muxer's life.
-    private var truncatedVideoSamples: Int = 0
+    private(set) var truncatedVideoSamples: Int = 0
     /// Audit BIT-1: a video sample of this track walked exactly as a length-prefixed chain, so a
-    /// `00 00 01` head is a 256-511 byte length from here on, not an Annex B start code.
-    private var videoNALFramingConfirmed = false
+    /// `00 00 01` head is a 256-511 byte length from here on, not an Annex B start code. The
+    /// session's latch when it passed one (audit BIT-104), so a rebuilt muxer keeps the verdict.
+    private let videoNALFraming: NALFramingLatch
 
     private func sanitizerCut(_ bytes: UnsafeRawBufferPointer, lengthPrefixSize: Int) -> Int? {
+        let confirmed = videoNALFraming.isConfirmed
         let cut = NALUnitChain.completeRunLength(
-            bytes, lengthPrefixSize: lengthPrefixSize, framingConfirmed: videoNALFramingConfirmed)
-        if cut == nil, !videoNALFramingConfirmed,
+            bytes, lengthPrefixSize: lengthPrefixSize, framingConfirmed: confirmed)
+        if cut == nil, !confirmed,
            NALUnitChain.walksExactly(bytes, lengthPrefixSize: lengthPrefixSize) {
-            videoNALFramingConfirmed = true
+            videoNALFraming.confirm()
         }
         return cut
     }
@@ -263,6 +269,7 @@ final class MP4SegmentMuxer {
         self.audioDelaySeconds = audioDelaySeconds
         self.audioNeedsParsedPacketForMoov =
             audio.map { Self.audioNeedsParsedPacketForMoov($0.codecpar.pointee.codec_id) } ?? false
+        self.videoNALFraming = video.nalFramingLatch ?? NALFramingLatch()
         // AE#561: the override, when there is one, is the record that reaches the sample entry. Both
         // carry the same width (the #19 rebuild keeps the source header's first 22 bytes), so this
         // only matters for a source whose own extradata is missing or Annex B.
diff --git a/Sources/AetherEngine/Video/NALUnitChain.swift b/Sources/AetherEngine/Video/NALUnitChain.swift
index 2a8113e6c..24042142a 100644
--- a/Sources/AetherEngine/Video/NALUnitChain.swift
+++ b/Sources/AetherEngine/Video/NALUnitChain.swift
@@ -2,6 +2,21 @@ import Foundation
 import AetherLibavcodec
 import AetherLibavutil
 
+/// Audit BIT-104: whether a video sample of the session's track has walked exactly as a
+/// length-prefixed chain (BIT-1). Held by the session rather than by one muxer, because every seek,
+/// restart and reload builds a fresh muxer, and a muxer's first sample is exactly the one a restart
+/// lands on.
+final class NALFramingLatch: @unchecked Sendable {
+    private let lock = NSLock()
+    private var confirmed: Bool
+
+    init(confirmed: Bool = false) { self.confirmed = confirmed }
+
+    var isConfirmed: Bool { lock.withLock { confirmed } }
+
+    func confirm() { lock.withLock { confirmed = true } }
+}
+
 /// The length-prefixed NAL chain (avcC / hvcC framing) as Apple's fMP4 parser walks it.
 ///
 /// A sample in an mp4 video track is a run of NAL units, each introduced by a big-endian length of
diff --git a/Tests/AetherEngineTests/NALUnitChainTests.swift b/Tests/AetherEngineTests/NALUnitChainTests.swift
index 134857afa..8c15c7e2d 100644
--- a/Tests/AetherEngineTests/NALUnitChainTests.swift
+++ b/Tests/AetherEngineTests/NALUnitChainTests.swift
@@ -140,4 +140,66 @@ struct NALUnitChainTests {
     }
 
     private enum Codec { case hevc, h264, av1 }
+
+    // MARK: - The verdict outlives the muxer (audit BIT-104)
+
+    /// Audit BIT-104: every seek, restart and reload builds a fresh muxer, and the sample a restart
+    /// lands on is that muxer's first. With the BIT-1 verdict held per muxer, exactly that sample was
+    /// judged by the head test alone, so a damaged IRAP with a 256-511 byte first NAL reached movenc
+    /// uncut on every retry of the restart.
+    @Test("A muxer rebuilt mid-session inherits the track's confirmed framing")
+    func rebuiltMuxerInheritsConfirmedFraming() throws {
+        let data = try #require(Data(base64Encoded: AtmosDetectionProbeIntegrationTests.videoOnlyBase64,
+                                     options: .ignoreUnknownCharacters))
+        let demuxer = Demuxer()
+        try demuxer.open(reader: DataIOReader(data: data), formatHint: "mp4")
+        defer { demuxer.close() }
+        let stream = try #require(demuxer.stream(at: demuxer.videoStreamIndex))
+        let sessionDir = FileManager.default.temporaryDirectory
+            .appendingPathComponent("bit104-\(UUID().uuidString)")
+        try FileManager.default.createDirectory(at: sessionDir, withIntermediateDirectories: true)
+        defer { try? FileManager.default.removeItem(at: sessionDir) }
+
+        func makeMuxer(_ index: Int, latch: NALFramingLatch?) throws -> MP4SegmentMuxer {
+            try MP4SegmentMuxer(
+                initialSegmentIndex: index, sessionDir: sessionDir,
+                video: .init(codecpar: UnsafePointer(stream.pointee.codecpar),
+                             timeBase: stream.pointee.time_base, codecTagOverride: nil,
+                             nalFramingLatch: latch),
+                audio: nil, onInitCaptured: { _ in })
+        }
+        func write(_ bytes: [UInt8], to muxer: MP4SegmentMuxer) throws {
+            var packet: UnsafeMutablePointer<AVPacket>? = try #require(trackedPacketAlloc())
+            defer { trackedPacketFree(&packet) }
+            let pkt = packet!
+            #expect(av_new_packet(pkt, Int32(bytes.count)) >= 0)
+            bytes.withUnsafeBytes { _ = memcpy(pkt.pointee.data, $0.baseAddress, bytes.count) }
+            pkt.pointee.pts = 0
+            pkt.pointee.dts = 0
+            pkt.pointee.duration = 512
+            pkt.pointee.flags |= AV_PKT_FLAG_KEY
+            pkt.pointee.stream_index = muxer.videoOutputStreamIndex
+            _ = muxer.writePacket(pkt)
+        }
+
+        // What the restart lands on: a first NAL whose 4-byte length reads `00 00 01 40`, then a
+        // length far past the end of the sample.
+        let first = Self.nal([0x65, 0x88] + [UInt8](repeating: 0x5A, count: 318))
+        #expect(Array(first.prefix(4)) == [0x00, 0x00, 0x01, 0x40])
+        let damaged = first + [0x16, 0xE5, 0x7A, 0xB3] + [UInt8](repeating: 0x5A, count: 96)
+
+        let session = NALFramingLatch()
+        let earlier = try makeMuxer(0, latch: session)
+        try write(Self.nal([0x65, 0x88, 0x84, 0x00]), to: earlier)   // walks exactly
+        #expect(session.isConfirmed)
+
+        let rebuilt = try makeMuxer(7, latch: session)
+        try write(damaged, to: rebuilt)
+        #expect(rebuilt.truncatedVideoSamples == 1, "the rebuilt muxer passed the overrun through uncut")
+
+        // A track nobody has confirmed keeps the Annex B head guard.
+        let unconfirmed = try makeMuxer(7, latch: nil)
+        try write(damaged, to: unconfirmed)
+        #expect(unconfirmed.truncatedVideoSamples == 0)
+    }
 }

From f4eda5263f77c560d3ddbd4a8ca355aa89f23408 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 06:52:40 +0200
Subject: [PATCH 179/359] fix(network): the first-request header dump prints no
 credential values (audit Vcred-102)

On the #316 / AE#495 stand-in route AVPlayer applies the host's
AVURLAssetHTTPHeaderFieldsKey headers to the loopback master too, so
the once-per-session #50 header dump logged whatever credential the
host passed, and the redactor cannot know every header name. The dump
now names every header and shows a value only for Accept, Host, Range,
User-Agent and X-Playback-Session-Id.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../AetherEngine/Network/HLSLocalServer.swift | 20 +++++-
 .../HLSLocalServerSessionTokenTests.swift     | 71 ++++++++++++++++++-
 2 files changed, 88 insertions(+), 3 deletions(-)

diff --git a/Sources/AetherEngine/Network/HLSLocalServer.swift b/Sources/AetherEngine/Network/HLSLocalServer.swift
index 510805117..ddbcff259 100644
--- a/Sources/AetherEngine/Network/HLSLocalServer.swift
+++ b/Sources/AetherEngine/Network/HLSLocalServer.swift
@@ -251,6 +251,24 @@ final class HLSLocalServer: @unchecked Sendable {
         return escapedForLog(line)
     }
 
+    /// The headers whose values the first-request dump shows: the capability headers it exists for
+    /// (#50), and the address the client used (#86). Nothing that carries a credential.
+    static let loggedRequestHeaderValues: Set<String> = [
+        "accept", "host", "range", "user-agent", "x-playback-session-id",
+    ]
+
+    /// Audit Vcred-102: on the #316 / AE#495 stand-in route AVPlayer sends the host's own headers to
+    /// this server too, credentials included (measured), so the dump names every header and prints a
+    /// value only where `loggedRequestHeaderValues` says it answers a question.
+    static func requestHeadersForLog(_ headerLines: [String]) -> String {
+        headerLines.map { line -> String in
+            guard let colon = line.firstIndex(of: ":") else { return "?" }
+            let name = line[..<colon].trimmingCharacters(in: .whitespaces)
+            let shown = loggedRequestHeaderValues.contains(name.lowercased()) ? line : name
+            return escapedForLog(shown, limit: maximumStrangerText)
+        }.joined(separator: " | ")
+    }
+
     /// Longest stretch of a stranger's request text a log line carries. A head may be 8 KB, and one
     /// line of that per interval would still crowd a small log ring.
     static let maximumStrangerText = 256
@@ -933,7 +951,7 @@ final class HLSLocalServer: @unchecked Sendable {
         stateLock.unlock()
         if dumpHeaders {
             let allLines = text.components(separatedBy: "\r\n")
-            let headers = allLines.dropFirst().prefix(while: { !$0.isEmpty }).joined(separator: " | ")
+            let headers = Self.requestHeadersForLog(Array(allLines.dropFirst().prefix(while: { !$0.isEmpty })))
             // #50 diag: once-per-session, promoted to .info to surface any
             // Range / capability header that explains the 404. Revert with the
             // arrival-line promotion above once #50 is root-caused.
diff --git a/Tests/AetherEngineTests/HLSLocalServerSessionTokenTests.swift b/Tests/AetherEngineTests/HLSLocalServerSessionTokenTests.swift
index 241657bfd..789b434c1 100644
--- a/Tests/AetherEngineTests/HLSLocalServerSessionTokenTests.swift
+++ b/Tests/AetherEngineTests/HLSLocalServerSessionTokenTests.swift
@@ -111,10 +111,52 @@ struct HLSLocalServerSessionTokenTests {
                 == "GET /media.m3u8?_HLS_msn=12 HTTP/1.1")
     }
 
+    // MARK: - Credential headers in the log (audit Vcred-102)
+
+    /// On the #316 / AE#495 stand-in route AVPlayer carries the host's own headers to this server, so
+    /// the once-per-session header dump printed whatever credential the host passed.
+    @Test("The first-request header dump names a credential header but never prints its value")
+    func headerDumpOmitsCredentialValues() throws {
+        let tap = HeaderLineTap()
+        defer { tap.restore() }
+        let server = HLSLocalServer(provider: StubProvider())
+        try server.start()
+        defer { server.stop() }
+        let marker = "X-Probe-\(UUID().uuidString.prefix(8))"
+
+        let status = Self.status(
+            port: server.port, path: "/\(server.pathToken)/media.m3u8",
+            extraHeaders: [#"Authorization: Digest username="bob", response="6629fae49393a05397450978507c4ef1""#,
+                           "X-Portal-Auth: SECRETportal123", "\(marker): 1", "Range: bytes=0-1"])
+        #expect(status == 200)
+
+        // Header names no redactor rule knows, which is the point: the dump must not depend on one.
+        let dumped = tap.lines.filter { $0.contains("first request headers") && $0.contains(marker) }
+        #expect(dumped.count == 1)
+        for line in dumped {
+            #expect(!line.contains("6629fae49393a05397450978507c4ef1"), "\(line)")
+            #expect(!line.contains("SECRETportal123"), "\(line)")
+            #expect(line.contains("Authorization"))
+            #expect(line.contains("X-Portal-Auth"))
+            #expect(line.contains("Range: bytes=0-1"))
+        }
+    }
+
+    @Test("Only the capability headers keep their values in the dump")
+    func headerDumpFormat() {
+        let dumped = HLSLocalServer.requestHeadersForLog([
+            "Host: 127.0.0.1:50123", "Authorization: Bearer abcdefghijklmnopqrstuvwxyz0123",
+            "Cookie: session=SECRETsess123", "Range: bytes=0-1", "X-Playback-Session-Id: 5A0C",
+            "Accept: */*", "User-Agent: AppleCoreMedia/1.0", "garbage",
+        ])
+        #expect(dumped == "Host: 127.0.0.1:50123 | Authorization | Cookie | Range: bytes=0-1 | "
+                + "X-Playback-Session-Id: 5A0C | Accept: */* | User-Agent: AppleCoreMedia/1.0 | ?")
+    }
+
     // MARK: - Helpers
 
     /// Status line of a plain GET, or 0 when the request could not be completed.
-    private static func status(port: UInt16, path: String) -> Int {
+    private static func status(port: UInt16, path: String, extraHeaders: [String] = []) -> Int {
         let fd = socket(AF_INET, SOCK_STREAM, IPPROTO_TCP)
         guard fd >= 0 else { return 0 }
         defer { close(fd) }
@@ -129,7 +171,8 @@ struct HLSLocalServerSessionTokenTests {
             }
         }
         guard connected == 0 else { return 0 }
-        let request = "GET \(path) HTTP/1.1\r\nHost: 127.0.0.1\r\nConnection: close\r\n\r\n"
+        let extra = extraHeaders.map { "\($0)\r\n" }.joined()
+        let request = "GET \(path) HTTP/1.1\r\nHost: 127.0.0.1\r\n\(extra)Connection: close\r\n\r\n"
         let sent = Array(request.utf8).withUnsafeBytes { send(fd, $0.baseAddress, $0.count, 0) }
         guard sent > 0 else { return 0 }
         var buffer = [UInt8](repeating: 0, count: 256)
@@ -150,3 +193,27 @@ private final class StubProvider: HLSSegmentProvider, @unchecked Sendable {
     func segmentDuration(at index: Int) -> Double { 4.0 }
     var playlistType: HLSPlaylistType { .vod }
 }
+
+/// Captures `EngineLog` lines for one test; the handler is global, so it is restored on every path.
+private final class HeaderLineTap: @unchecked Sendable {
+    private let lock = NSLock()
+    private var captured: [String] = []
+    private let previous: ((String) -> Void)?
+
+    init() {
+        previous = EngineLog.handler
+        EngineLog.handler = { [self] line in
+            lock.lock()
+            captured.append(line)
+            lock.unlock()
+        }
+    }
+
+    func restore() { EngineLog.handler = previous }
+
+    var lines: [String] {
+        lock.lock()
+        defer { lock.unlock() }
+        return captured
+    }
+}

From 868903caa38cde06b024113a4d43e4b87266bc3e Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 06:54:28 +0200
Subject: [PATCH 180/359] test(segments): read the finished playlist without a
 captured mutable local (audit SEG-103)

Keeps the SEG-103 witness clear of the older CI toolchain's stricter
region isolation.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../SequentialBridgedTailPlaylistTests.swift              | 8 +++-----
 1 file changed, 3 insertions(+), 5 deletions(-)

diff --git a/Tests/AetherEngineTests/SequentialBridgedTailPlaylistTests.swift b/Tests/AetherEngineTests/SequentialBridgedTailPlaylistTests.swift
index bf58d125d..116a6ce6c 100644
--- a/Tests/AetherEngineTests/SequentialBridgedTailPlaylistTests.swift
+++ b/Tests/AetherEngineTests/SequentialBridgedTailPlaylistTests.swift
@@ -189,11 +189,9 @@ struct SequentialBridgedTailPlaylistTests {
         defer { engine.stop() }
         let mediaURL = try #require(engine.mediaPlaylistURL)
 
-        var playlist = ""
-        try await waitFor {
-            playlist = (try? String(contentsOf: mediaURL, encoding: .utf8)) ?? ""
-            return playlist.contains("#EXT-X-ENDLIST")
-        }
+        func playlistText() -> String { (try? String(contentsOf: mediaURL, encoding: .utf8)) ?? "" }
+        try await waitFor { playlistText().contains("#EXT-X-ENDLIST") }
+        let playlist = playlistText()
 
         let lines = playlist.split(whereSeparator: \.isNewline).map(String.init)
         let durations = lines.filter { $0.hasPrefix("#EXTINF:") }

From 429f3f8bf2f62b714defddc526f6379f407a8388 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 06:55:05 +0200
Subject: [PATCH 181/359] fix(cli): aetherctl banners carry the redacted source
 URL (audit OPS-106)

The fifteen command banners printed url.absoluteString directly, so
the first line of a pasted transcript carried the api_key or Xtream
password the engine's own lines below it hid. They now print through
EngineLog.redacted(_:), a thin public accessor to the funnel's
redactor. Plain EngineLog.emit was not enough: audio, dovitest, bgaudio
and segverify install no handler, so their banner would have vanished.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 Sources/AetherEngine/Diagnostics/EngineLog.swift | 7 +++++++
 Sources/aetherctl/AudioCmd.swift                 | 2 +-
 Sources/aetherctl/AudioTapCmd.swift              | 4 ++--
 Sources/aetherctl/BackgroundAudioCmd.swift       | 2 +-
 Sources/aetherctl/DiscInspect.swift              | 2 +-
 Sources/aetherctl/DoviTest.swift                 | 2 +-
 Sources/aetherctl/Extract.swift                  | 2 +-
 Sources/aetherctl/PktDump.swift                  | 2 +-
 Sources/aetherctl/PlaybackCmd.swift              | 2 +-
 Sources/aetherctl/Probe.swift                    | 2 +-
 Sources/aetherctl/SWDecode.swift                 | 2 +-
 Sources/aetherctl/SeekTest.swift                 | 2 +-
 Sources/aetherctl/SegVerify.swift                | 2 +-
 Sources/aetherctl/Serve.swift                    | 4 ++--
 Tests/AetherEngineTests/LogRedactionTests.swift  | 8 ++++++++
 docs/api.md                                      | 2 +-
 16 files changed, 31 insertions(+), 16 deletions(-)

diff --git a/Sources/AetherEngine/Diagnostics/EngineLog.swift b/Sources/AetherEngine/Diagnostics/EngineLog.swift
index e37d70143..9f24628af 100644
--- a/Sources/AetherEngine/Diagnostics/EngineLog.swift
+++ b/Sources/AetherEngine/Diagnostics/EngineLog.swift
@@ -46,6 +46,13 @@ public enum EngineLog {
         LogRedaction.unregister(value)
     }
 
+    /// The line as `emit` would deliver it, with credentials stripped. For a tool or a host that prints
+    /// a line of its own next to the engine's, such as aetherctl's banners, so the line it composes does
+    /// not carry the token the engine's lines hide (audit OPS-106).
+    public static func redacted(_ line: String) -> String {
+        LogRedaction.redact(line)
+    }
+
     public static let subsystem: String = "de.superuser404.AetherEngine"
 
     private static let loggers: [Category: Logger] = {
diff --git a/Sources/aetherctl/AudioCmd.swift b/Sources/aetherctl/AudioCmd.swift
index 1deefb842..5d3752aef 100644
--- a/Sources/aetherctl/AudioCmd.swift
+++ b/Sources/aetherctl/AudioCmd.swift
@@ -5,7 +5,7 @@ import AetherEngine
 
 /// Load a source through the audio-only path and play it, printing the synchronizer clock once a second. Smoke-tests FFmpeg decode -> AVSampleBufferAudioRenderer on macOS.
 func runAudio(url: URL, seconds playSeconds: Double) -> Int32 {
-    print("aetherctl audio: \(url.absoluteString) (play \(playSeconds)s)")
+    print(EngineLog.redacted("aetherctl audio: \(url.absoluteString) (play \(playSeconds)s)"))
     // Must use CFRunLoopRun, not a blocking semaphore: AetherEngine is @MainActor, so parking the main thread would deadlock the executor.
     let box = UncheckedBox<Int32?>(nil)
     Task { @MainActor in
diff --git a/Sources/aetherctl/AudioTapCmd.swift b/Sources/aetherctl/AudioTapCmd.swift
index d1c50aad1..12c62f19a 100644
--- a/Sources/aetherctl/AudioTapCmd.swift
+++ b/Sources/aetherctl/AudioTapCmd.swift
@@ -8,7 +8,7 @@ func runAudioTap(url: URL, duration: Double, outPath: String,
     if software { return runSoftwareAudioTap(url: url, duration: duration, outPath: outPath) }
     EngineLog.handler = { print($0) }
     let mode = remote ? "remote-HLS" : "loopback"
-    print("aetherctl audiotap (\(mode)): \(url.absoluteString) duration=\(duration)s out=\(outPath)")
+    print(EngineLog.redacted("aetherctl audiotap (\(mode)): \(url.absoluteString) duration=\(duration)s out=\(outPath)"))
     do {
         let report = remote
             ? try AudioTapProbe.runRemote(url: url, durationSeconds: duration, outPath: outPath)
@@ -26,7 +26,7 @@ func runAudioTap(url: URL, duration: Double, outPath: String,
 /// main thread would deadlock its executor (same shape as `bgaudio`).
 private func runSoftwareAudioTap(url: URL, duration: Double, outPath: String) -> Int32 {
     EngineLog.handler = { print($0) }
-    print("aetherctl audiotap (software): \(url.absoluteString) duration=\(duration)s out=\(outPath)")
+    print(EngineLog.redacted("aetherctl audiotap (software): \(url.absoluteString) duration=\(duration)s out=\(outPath)"))
     let box = UncheckedBox<Int32?>(nil)
     Task { @MainActor in
         do {
diff --git a/Sources/aetherctl/BackgroundAudioCmd.swift b/Sources/aetherctl/BackgroundAudioCmd.swift
index b0d37ee80..3504611a7 100644
--- a/Sources/aetherctl/BackgroundAudioCmd.swift
+++ b/Sources/aetherctl/BackgroundAudioCmd.swift
@@ -9,7 +9,7 @@ import AetherEngine
 /// (the macOS stand-in for the iOS background lifecycle) and verify audio keeps advancing while video is
 /// dropped, then resumes on foreground return. Exercises the real runDemuxLoop background branch headless.
 func runBackgroundAudio(url: URL, fgSeconds: Double, bgSeconds: Double) -> Int32 {
-    print("aetherctl bgaudio: \(url.absoluteString) (fg=\(fgSeconds)s bg=\(bgSeconds)s)")
+    print(EngineLog.redacted("aetherctl bgaudio: \(url.absoluteString) (fg=\(fgSeconds)s bg=\(bgSeconds)s)"))
     // Must use CFRunLoopRun, not a blocking semaphore: AetherEngine is @MainActor, so parking the main thread
     // would deadlock the executor. The run loop also lets the host's time timer + Combine sinks fire.
     let box = UncheckedBox<Int32?>(nil)
diff --git a/Sources/aetherctl/DiscInspect.swift b/Sources/aetherctl/DiscInspect.swift
index e33f1ab11..3852fb55f 100644
--- a/Sources/aetherctl/DiscInspect.swift
+++ b/Sources/aetherctl/DiscInspect.swift
@@ -8,7 +8,7 @@ import AetherEngine
 /// does detection bail?". Exit 0 when the image is recognized as playable, else 1.
 func runDiscInspect(url: URL, dump: Bool = false) -> Int32 {
     EngineLog.handler = { print($0) }
-    print("aetherctl disc-inspect: \(url.absoluteString)")
+    print(EngineLog.redacted("aetherctl disc-inspect: \(url.absoluteString)"))
     print("")
 
     let d = AetherEngine.inspectDisc(url: url, verbose: dump)
diff --git a/Sources/aetherctl/DoviTest.swift b/Sources/aetherctl/DoviTest.swift
index 6b9902e44..2327aff5c 100644
--- a/Sources/aetherctl/DoviTest.swift
+++ b/Sources/aetherctl/DoviTest.swift
@@ -7,7 +7,7 @@ import AetherEngine
 func runDoviTest(url: URL) -> Int32 {
     let outputPath = debugOutputPath("aetherctl-dovitest.hevc")
     let rpuPath = debugOutputPath("host.rpu")
-    print("aetherctl dovitest: \(url.absoluteString)")
+    print(EngineLog.redacted("aetherctl dovitest: \(url.absoluteString)"))
     print("output: \(outputPath)")
     print("")
 
diff --git a/Sources/aetherctl/Extract.swift b/Sources/aetherctl/Extract.swift
index 4fb9dc163..a9bff6c1a 100644
--- a/Sources/aetherctl/Extract.swift
+++ b/Sources/aetherctl/Extract.swift
@@ -29,7 +29,7 @@ private func writePNG(_ image: CGImage, to path: String) -> Bool {
 
 func runExtract(url: URL, at seconds: Double, mode: FrameMode, loops: Int, maxWidth: Int) -> Int32 {
     EngineLog.handler = { print($0) }
-    print("aetherctl extract: \(url.absoluteString) at=\(seconds)s mode=\(mode) loops=\(loops)")
+    print(EngineLog.redacted("aetherctl extract: \(url.absoluteString) at=\(seconds)s mode=\(mode) loops=\(loops)"))
     print("")
 
     let extractor = FrameExtractor(url: url, httpHeaders: [:])
diff --git a/Sources/aetherctl/PktDump.swift b/Sources/aetherctl/PktDump.swift
index f90f4c677..b96ce9474 100644
--- a/Sources/aetherctl/PktDump.swift
+++ b/Sources/aetherctl/PktDump.swift
@@ -9,7 +9,7 @@ import AetherEngine
 /// restartReopen confirms the skipped find_stream_info pass as the judder source.
 func runPktDump(url: URL, at seconds: Double, count: Int, profileName: String) -> Int32 {
     EngineLog.handler = { print($0) }
-    print("aetherctl pktdump: \(url.absoluteString)")
+    print(EngineLog.redacted("aetherctl pktdump: \(url.absoluteString)"))
     print("  profile=\(profileName) at=\(seconds)s count=\(count)")
     print("")
     do {
diff --git a/Sources/aetherctl/PlaybackCmd.swift b/Sources/aetherctl/PlaybackCmd.swift
index 06963d07b..938feab9c 100644
--- a/Sources/aetherctl/PlaybackCmd.swift
+++ b/Sources/aetherctl/PlaybackCmd.swift
@@ -127,7 +127,7 @@ func runPlay(url: URL, seconds: Double, live: Bool, nativeHLS: Bool = false, liv
         print("[aetherctl] audio switch: selectAudioTrack(index: \(audioSwitch.index)) "
               + "\(audioSwitch.delayMilliseconds) ms after the load returns")
     }
-    print("aetherctl play: \(url.absoluteString) (seconds=\(seconds) live=\(live) nativeHLS=\(nativeHLS) liveIngest=\(liveIngest) dvrWindow=\(dvrWindow.map { String($0) } ?? "nil") subs=\(subsPick ?? "off") hostCalls=\(hostCalls.isEmpty ? "none" : hostCalls.joined(separator: "+")) audioStats=\(audioStats) seekEvery=\(seekEvery.map { String($0) } ?? "off") seekCount=\(seekCount.map { String($0) } ?? "unbounded") seekPattern=\(seekPattern.isEmpty ? "off" : seekPattern.map { String($0) }.joined(separator: "/")) startPosition=\(startPosition.map { String($0) } ?? "0"))")
+    print(EngineLog.redacted("aetherctl play: \(url.absoluteString) (seconds=\(seconds) live=\(live) nativeHLS=\(nativeHLS) liveIngest=\(liveIngest) dvrWindow=\(dvrWindow.map { String($0) } ?? "nil") subs=\(subsPick ?? "off") hostCalls=\(hostCalls.isEmpty ? "none" : hostCalls.joined(separator: "+")) audioStats=\(audioStats) seekEvery=\(seekEvery.map { String($0) } ?? "off") seekCount=\(seekCount.map { String($0) } ?? "unbounded") seekPattern=\(seekPattern.isEmpty ? "off" : seekPattern.map { String($0) }.joined(separator: "/")) startPosition=\(startPosition.map { String($0) } ?? "0"))"))
     print("")
     // CFRunLoopRun, not a blocking semaphore: AetherEngine is @MainActor, so parking the main thread would deadlock the executor.
     let box = UncheckedBox<Int32?>(nil)
diff --git a/Sources/aetherctl/Probe.swift b/Sources/aetherctl/Probe.swift
index 7219a5686..05727c79f 100644
--- a/Sources/aetherctl/Probe.swift
+++ b/Sources/aetherctl/Probe.swift
@@ -5,7 +5,7 @@ import AetherEngine
 
 func runProbe(url: URL, detecting: ProbeDetail = []) -> Int32 {
     EngineLog.handler = { print($0) }
-    print("aetherctl probe: \(url.absoluteString)")
+    print(EngineLog.redacted("aetherctl probe: \(url.absoluteString)"))
     if !detecting.isEmpty {
         var passes: [String] = []
         if detecting.contains(.hdr10Plus) { passes.append("hdr10plus (packet scan)") }
diff --git a/Sources/aetherctl/SWDecode.swift b/Sources/aetherctl/SWDecode.swift
index 1eb9c66a6..0a0195b43 100644
--- a/Sources/aetherctl/SWDecode.swift
+++ b/Sources/aetherctl/SWDecode.swift
@@ -5,7 +5,7 @@ import AetherEngine
 
 func runSWDecode(url: URL, maxPackets: Int) -> Int32 {
     EngineLog.handler = { print($0) }
-    print("aetherctl swdecode: \(url.absoluteString) (maxPackets=\(maxPackets))")
+    print(EngineLog.redacted("aetherctl swdecode: \(url.absoluteString) (maxPackets=\(maxPackets))"))
     print("")
 
     let result: SoftwareDecodeProbeResult
diff --git a/Sources/aetherctl/SeekTest.swift b/Sources/aetherctl/SeekTest.swift
index b69d01b86..662a82ebe 100644
--- a/Sources/aetherctl/SeekTest.swift
+++ b/Sources/aetherctl/SeekTest.swift
@@ -84,7 +84,7 @@ private func seekTestRun(url: URL, seeks: Int, gapMs: Int, settleSeconds: Double
 
     print("")
     print("=== SEEKTEST (issue #35 rapid-seek burst) ===")
-    print("  url=\(url.absoluteString) seeks=\(seeks) gapMs=\(gapMs) settle=\(settleSeconds)s")
+    print(EngineLog.redacted("  url=\(url.absoluteString) seeks=\(seeks) gapMs=\(gapMs) settle=\(settleSeconds)s"))
 
     let engine: AetherEngine
     do {
diff --git a/Sources/aetherctl/SegVerify.swift b/Sources/aetherctl/SegVerify.swift
index 94e6d9af5..67646af9b 100644
--- a/Sources/aetherctl/SegVerify.swift
+++ b/Sources/aetherctl/SegVerify.swift
@@ -14,7 +14,7 @@ func runSegVerify(url: URL, from: Int, count: Int, dvModeAvailable: Bool,
                   dolbyVisionHandling: DolbyVisionHandling = .automatic,
                   dumpDir: String? = nil) -> Int32 {
     setvbuf(stdout, nil, _IONBF, 0)   // unbuffered: progressive output survives a long-running run
-    print("segverify: starting engine for \(url.absoluteString)")
+    print(EngineLog.redacted("segverify: starting engine for \(url.absoluteString)"))
     let engine = HLSVideoEngine(url: url, dvModeAvailable: dvModeAvailable,
                                 forceDolbyVisionOnNonDVDisplay: forceDVWithoutDisplay,
                                 dolbyVisionHandling: dolbyVisionHandling,
diff --git a/Sources/aetherctl/Serve.swift b/Sources/aetherctl/Serve.swift
index c1b364a2e..b6f86ec64 100644
--- a/Sources/aetherctl/Serve.swift
+++ b/Sources/aetherctl/Serve.swift
@@ -22,7 +22,7 @@ func runServe(url: URL, dvModeAvailable: Bool, forceDVWithoutDisplay: Bool = fal
     if let idx = nativeSubsIndex { flagSuffix += " [--native-subs \(idx)]" }
     if let pos = startPosition { flagSuffix += " [--start-position \(pos)]" }
     if audioDelayMs != 0 { flagSuffix += " [--audio-delay \(audioDelayMs)]" }
-    print("aetherctl serve: \(url.absoluteString)\(flagSuffix)")
+    print(EngineLog.redacted("aetherctl serve: \(url.absoluteString)\(flagSuffix)"))
     print("")
 
     let engine = HLSVideoEngine(
@@ -97,7 +97,7 @@ func runValidate(url: URL, dvModeAvailable: Bool, forceDVWithoutDisplay: Bool =
     var flagSuffix = dvModeAvailable ? "" : " [--no-dv]"
     if forceDVWithoutDisplay { flagSuffix += " [--force-dv]" }
     if dolbyVisionHandling == .baseLayerOnly { flagSuffix += " [--dv-base-layer]" }
-    print("aetherctl validate: \(url.absoluteString)\(flagSuffix)")
+    print(EngineLog.redacted("aetherctl validate: \(url.absoluteString)\(flagSuffix)"))
     print("")
 
     let engine = HLSVideoEngine(
diff --git a/Tests/AetherEngineTests/LogRedactionTests.swift b/Tests/AetherEngineTests/LogRedactionTests.swift
index ce24704c8..ed18579e4 100644
--- a/Tests/AetherEngineTests/LogRedactionTests.swift
+++ b/Tests/AetherEngineTests/LogRedactionTests.swift
@@ -383,6 +383,14 @@ struct LogRedactionTests {
         #expect(LogRedaction.redact(line) == line)
     }
 
+    /// Audit OPS-106: aetherctl printed the source URL in its own banner, outside the funnel, so the
+    /// first line of a pasted transcript undid the redaction of every engine line below it.
+    @Test("a line a tool prints itself gets the funnel's redaction")
+    func redactedForATool() {
+        #expect(EngineLog.redacted("aetherctl probe: http://h:8080/live/john/S3cretPass/1.ts?api_key=\(token)")
+                == "aetherctl probe: http://h:8080/live/john/<redacted>/1.ts?api_key=<redacted>")
+    }
+
     /// The point of putting this in EngineLog rather than in each host: the handler a host installs
     /// must never see the raw token, whether or not that host scrubs its own log.
     @Test("the host handler receives the redacted line")
diff --git a/docs/api.md b/docs/api.md
index 5f38c8fe8..879960952 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -930,7 +930,7 @@ as well.
 | `EngineLog.handler` | Mirror every info-level line into a host capture path. Fires from whatever thread emitted it, so it must be thread-safe and non-blocking. |
 | `EngineLog.subsystem`, `EngineLog.Category` | `de.superuser404.AetherEngine`, one category per subsystem: `engine`, `ffmpeg`, `session`, `muxer`, `demux`, `hls.server`, `audio.bridge`, `sw.playback`, `scrub`. |
 | `EngineLog.Level` | `.info` reaches os_log and the host handler; `.verbose` is per-segment trace and reaches os_log's debug level **only**, never the handler, which is what keeps a mirrored stream readable. Read the verbose ones with `log stream --level debug`. |
-| `EngineLog.registerSecret(_:)`, `EngineLog.unregisterSecret(_:)` | Name a value that must never be logged, such as an IPTV password the host holds. Every line reaching os_log or the handler has it replaced, raw or percent-encoded, wherever it sits. The engine already strips named parameters, `Bearer` / `Basic` credentials, userinfo, encoded payloads and the Xtream Codes path layout on its own, also inside a URL carried percent-encoded in another URL's query; this covers what only the host can know, such as a provider URL carrying the password as a bare path segment. Registrations are counted: a value registered twice stays redacted until it is unregistered twice. Returns false for a value under four bytes. |
+| `EngineLog.registerSecret(_:)`, `EngineLog.unregisterSecret(_:)`, `EngineLog.redacted(_:)` | Name a value that must never be logged, such as an IPTV password the host holds. Every line reaching os_log or the handler has it replaced, raw or percent-encoded, wherever it sits. The engine already strips named parameters, `Bearer` / `Basic` credentials, userinfo, encoded payloads and the Xtream Codes path layout on its own, also inside a URL carried percent-encoded in another URL's query; this covers what only the host can know, such as a provider URL carrying the password as a bare path segment. Registrations are counted: a value registered twice stays redacted until it is unregistered twice. Returns false for a value under four bytes. `redacted(_:)` returns a line as the handler would receive it, for a line a host or tool prints itself next to the engine's. |
 | `EngineLog.emit(_:category:level:)` | Emit a host line into the same stream, for a host that wants its own events interleaved with the engine's. |
 | `segmentCacheDiskBytes`, `softwareHostFramesEnqueued` | Point reads for a stats overlay. |
 | `activeProducerShiftSeconds`, `frameAhead`, `clockLeadSeconds` | Divergence diagnostics for tracing a clock that disagrees with the picture. Not for production playback logic. |

From 7e51c3b8afed7a020819c06819e489b502b3232a Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 08:25:51 +0200
Subject: [PATCH 182/359] fix(ci): the manual DMG workflow builds the tag it
 uploads to (audit OPS-101)

workflow_dispatch checked out the dispatching branch, then signed,
notarized and --clobber-uploaded a DMG named and versioned for the input
tag. Pin the checkout to refs/tags/<tag> and log the built commit.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .github/RELEASE_SETUP.md          | 1 +
 .github/workflows/release-dmg.yml | 6 ++++++
 2 files changed, 7 insertions(+)

diff --git a/.github/RELEASE_SETUP.md b/.github/RELEASE_SETUP.md
index 3201001a2..e3a4d6fc2 100644
--- a/.github/RELEASE_SETUP.md
+++ b/.github/RELEASE_SETUP.md
@@ -67,6 +67,7 @@ Once all six secrets are set:
 
 1. Make sure a release exists (use the existing `2.0.0` or create a draft tag).
 2. Trigger the workflow manually: [Actions](https://github.com/superuser404notfound/AetherEngine/actions) → `Release .dmg` → `Run workflow` → enter the tag → Run.
+   The job checks out that tag, whatever branch the "Use workflow from" dropdown says, so a tag that predates `Examples/DemoPlayerMac/Scripts/build-dmg.sh` fails loudly instead of building `main`. The log's "Building commit" line names the built SHA.
 3. Watch the job. It should reach "Upload .dmg to release" and finish green in 3-6 minutes.
 4. Confirm the `.dmg` appears under the release's Assets (or got `--clobber`'d over the existing one if you pointed at `2.0.0`).
 
diff --git a/.github/workflows/release-dmg.yml b/.github/workflows/release-dmg.yml
index 1809d080b..a0d03371c 100644
--- a/.github/workflows/release-dmg.yml
+++ b/.github/workflows/release-dmg.yml
@@ -49,7 +49,12 @@ jobs:
     runs-on: macos-15
     timeout-minutes: 30
     steps:
+      # workflow_dispatch checks out the ref picked in "Use workflow from"
+      # (normally main), so the tag is pinned explicitly: the DMG is named,
+      # versioned and uploaded for the tag and must be built from it (audit OPS-101).
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: refs/tags/${{ github.event.release.tag_name || inputs.tag }}
 
       - uses: maxim-lobanov/setup-xcode@ed7a3b1fda3918c0306d1b724322adc0b8cc0a90 # v1.7.0
         with:
@@ -65,6 +70,7 @@ jobs:
           fi
           echo "tag=$TAG" >> "$GITHUB_OUTPUT"
           echo "Building for tag: $TAG"
+          echo "Building commit: $(git rev-parse HEAD)"
 
       - name: Import Developer ID certificate into temporary keychain
         env:

From 5431ac2d500c890c80b186eb8ef58d2fe2015fa9 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 08:39:08 +0200
Subject: [PATCH 183/359] docs: Xcode floor, server exposure, header scoping,
 cli flags and curl tokens (audit OPS-102, OPS-103, OPS-111, Vcred-104)

README states the Xcode 26.2 SDK the source compiles against. SECURITY.md,
architecture.md and cli.md describe the local server as it is (all
interfaces for AirPlay behind a per-session path token, the 32 / 24
connection caps and the head deadline) and the serve curl examples carry
the token. api.md says AVFoundation sends LoadOptions.httpHeaders to every
host on the nativeRemoteHLS bypass, so engine-side scoping applies only to
the routes the engine fetches itself. cli.md gains --assert-dv,
--max-concurrent-requests and --no-blocking-reload, guarded by
CLIDocCoverageTests; the duplicated live usage lines are tidied.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 README.md                                     |  6 +-
 SECURITY.md                                   |  2 +-
 Sources/aetherctl/main.swift                  | 15 ++---
 .../CLIDocCoverageTests.swift                 | 56 +++++++++++++++++++
 .../DocumentedConstantsTests.swift            | 12 ++++
 docs/api.md                                   |  2 +-
 docs/architecture.md                          |  4 +-
 docs/cli.md                                   | 17 ++++--
 8 files changed, 96 insertions(+), 18 deletions(-)
 create mode 100644 Tests/AetherEngineTests/CLIDocCoverageTests.swift

diff --git a/README.md b/README.md
index fcc1fe52c..a9b328dcc 100644
--- a/README.md
+++ b/README.md
@@ -644,8 +644,10 @@ Pin to `.upToNextMinor(from: "7.22.2")` for stricter teams that prefer to opt in
 | tvOS | 18.0 |
 | macOS | 15.0 |
 | visionOS | 1.0 |
-| Swift | 6.0 |
-| Xcode | 16.0 |
+| Swift | 6.2 |
+| Xcode | 26.2 |
+
+The Xcode row is the SDK the source compiles against (`VTRegisterSupplementalVideoDecoderIfAvailable` is iOS / tvOS 26.2 API, and an unguarded C symbol has to exist at compile time); the deployment floor above stays iOS / tvOS 18 and macOS 15, with the 26.x calls behind `#available`.
 
 The 7.x line raised the floor from iOS 16, tvOS 17 and macOS 14. A project that still supports those pins the 6.x line with `.upToNextMajor(from: "6.89.1")`.
 
diff --git a/SECURITY.md b/SECURITY.md
index 0b4e7041e..fb6f25c84 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -28,7 +28,7 @@ You can expect an initial acknowledgement within a few days. Once a fix is ready
 AetherEngine plays media from servers and local sources and parses untrusted container and codec data. Areas most relevant to security:
 
 - **Media parsing.** Demuxing and decoding of untrusted containers and bitstreams (the FFmpeg / dav1d surface).
-- **Network handling.** The engine's HTTP range reading and its on-device loopback server used to bridge sources into AVPlayer. Nothing is exposed off the device, and there is no external analytics or session reporting.
+- **Network handling.** The engine's HTTP range reading and its local HTTP server used to bridge sources into AVPlayer. The server listens on all interfaces, not only loopback, so that an AirPlay receiver can fetch the stream over the LAN, on an ephemeral port and for the current stream only. Every path it answers starts with a per-session 128-bit random token, and a request without it is answered 404 before it reaches any route. A peer that is not loopback may hold at most 24 of the server's 32 connection slots (the rest stay free for the local player), and a connection that has not presented the token has 10 seconds from accept to deliver a whole request head. The token is also kept out of the diagnostic log. Beyond that listener nothing is exposed off the device, and there is no external analytics or session reporting.
 - **Memory safety.** Crashes or out-of-bounds behavior triggered by crafted input.
 
 Out of scope: vulnerabilities in a host app's own UI or networking (report those on the host app's tracker), and issues in upstream FFmpeg / dav1d themselves (report those upstream, though we are glad to know if a bundled build is affected).
diff --git a/Sources/aetherctl/main.swift b/Sources/aetherctl/main.swift
index 1f2bad5da..1fb3d2fa0 100644
--- a/Sources/aetherctl/main.swift
+++ b/Sources/aetherctl/main.swift
@@ -118,8 +118,6 @@ func printUsage() {
                           never EOF, unknown size; prints physFP and its slope against that rate)
       aetherctl live [--seconds N] [--seed <path>] [--dvr-window N] [--serve-only] [--measure-rss] [--report-cache-bytes] [--rewind-test] [--reload-test] [--sw] [--drop-after N] [--discontinuity-at N] [--realtime] [--realtime-rate X] [--fast-zap] [--preroll N] [--rewind-hold N] [--gen-highbitrate-seed]
                      [--freeze-after N] [--unfreeze-after N] [--rewind-before-freeze N] [--force-recovery-reload-at N] [--live-only] [--no-blocking-reload] [--force-master]
-                     [--freeze-after N] [--unfreeze-after N] [--rewind-before-freeze N] [--force-recovery-reload-at N]
-                     [--no-blocking-reload]
       aetherctl dvr [--path native|sw|both] [--seconds N] [--dvr-window N]
       aetherctl dualsubs <file> --primary <streamIndex> --secondary <streamIndex> [--seek <seconds>]
       aetherctl hlsfixture <input.ts> [--port N] [--segment-seconds N] [--target-duration N] [--window N]
@@ -216,13 +214,16 @@ func printUsage() {
                 mediastreamvalidator / mp4dump / ffprobe from another
                 terminal:
 
-                  curl -i  http://127.0.0.1:<port>/master.m3u8
-                  curl -o  /tmp/init.mp4  http://127.0.0.1:<port>/init.mp4
-                  curl -o  /tmp/seg0.mp4  http://127.0.0.1:<port>/seg0.mp4
-                  mediastreamvalidator http://127.0.0.1:<port>/master.m3u8
+                  curl -i  http://127.0.0.1:<port>/<token>/master.m3u8
+                  curl -o  /tmp/init.mp4  http://127.0.0.1:<port>/<token>/init.mp4
+                  curl -o  /tmp/seg0.mp4  http://127.0.0.1:<port>/<token>/seg0.mp4
+                  mediastreamvalidator http://127.0.0.1:<port>/<token>/master.m3u8
                   mp4dump --verbosity 1 /tmp/init.mp4
                   ffprobe -v debug /tmp/seg0.mp4
-                  open 'http://127.0.0.1:<port>/master.m3u8'
+                  open 'http://127.0.0.1:<port>/<token>/master.m3u8'
+
+                The server answers only paths that start with its
+                per-session token; copy <port>/<token> from the printed URL.
 
                 Ctrl-C to tear down.
 
diff --git a/Tests/AetherEngineTests/CLIDocCoverageTests.swift b/Tests/AetherEngineTests/CLIDocCoverageTests.swift
new file mode 100644
index 000000000..17a26ad3a
--- /dev/null
+++ b/Tests/AetherEngineTests/CLIDocCoverageTests.swift
@@ -0,0 +1,56 @@
+import Testing
+import Foundation
+
+/// `docs/cli.md` is the only place a flag of `aetherctl` is explained, and three of them (`--assert-dv`,
+/// `--max-concurrent-requests`, `--no-blocking-reload`) lived in the parser for a long time before
+/// anyone noticed the page never mentioned them (audit OPS-111). Every quoted `"--flag"` literal in
+/// `Sources/aetherctl` is a flag the CLI accepts, so each one has to appear in the page.
+///
+/// aetherctl is an executable target that no test target can link, so this reads the sources as text.
+@Suite("aetherctl flags are documented")
+struct CLIDocCoverageTests {
+    private static let root = URL(fileURLWithPath: #filePath)
+        .deletingLastPathComponent().deletingLastPathComponent().deletingLastPathComponent()
+
+    private static var checkoutPresent: Bool {
+        FileManager.default.fileExists(atPath: root.appendingPathComponent("docs/cli.md").path)
+            && FileManager.default.fileExists(atPath: root.appendingPathComponent("Sources/aetherctl").path)
+    }
+
+    /// `--help` is the one literal that is a command, not a flag of a subcommand, and the usage text
+    /// already documents it.
+    private static let notFlags: Set<String> = ["--help"]
+
+    @Test("every --flag literal in aetherctl appears in docs/cli.md",
+          .enabled(if: CLIDocCoverageTests.checkoutPresent, "needs a source checkout"))
+    func everyFlagIsDocumented() throws {
+        let sourcesDir = Self.root.appendingPathComponent("Sources/aetherctl")
+        let files = try FileManager.default.contentsOfDirectory(atPath: sourcesDir.path)
+            .filter { $0.hasSuffix(".swift") }
+        #expect(!files.isEmpty)
+
+        let literal = try NSRegularExpression(pattern: #""(--[a-z0-9][a-z0-9-]*)""#)
+        var flags = Set<String>()
+        for file in files {
+            let text = try String(contentsOf: sourcesDir.appendingPathComponent(file), encoding: .utf8)
+            let whole = NSRange(text.startIndex..., in: text)
+            for match in literal.matches(in: text, range: whole) {
+                if let range = Range(match.range(at: 1), in: text) { flags.insert(String(text[range])) }
+            }
+        }
+        // A parser that stopped matching would pass vacuously.
+        #expect(flags.count > 50, "found only \(flags.count) flag literals, the pattern has drifted")
+
+        let doc = try String(contentsOf: Self.root.appendingPathComponent("docs/cli.md"), encoding: .utf8)
+        let missing = flags.subtracting(Self.notFlags).filter { !Self.mentions(doc, flag: $0) }.sorted()
+        #expect(missing.isEmpty, "docs/cli.md does not mention: \(missing.joined(separator: ", "))")
+    }
+
+    /// A whole-flag match, so `--sw` is not satisfied by `--sweep` or `--sw-escalation`.
+    private static func mentions(_ doc: String, flag: String) -> Bool {
+        let escaped = NSRegularExpression.escapedPattern(for: flag)
+        guard let pattern = try? NSRegularExpression(pattern: "(?<![A-Za-z0-9-])\(escaped)(?![A-Za-z0-9-])")
+        else { return false }
+        return pattern.firstMatch(in: doc, range: NSRange(doc.startIndex..., in: doc)) != nil
+    }
+}
diff --git a/Tests/AetherEngineTests/DocumentedConstantsTests.swift b/Tests/AetherEngineTests/DocumentedConstantsTests.swift
index 04045558c..8f9047053 100644
--- a/Tests/AetherEngineTests/DocumentedConstantsTests.swift
+++ b/Tests/AetherEngineTests/DocumentedConstantsTests.swift
@@ -283,6 +283,18 @@ final class DocumentedConstantsTests: XCTestCase {
             """)
     }
 
+    /// The README's Xcode row is the SDK the source needs, not a taste (audit OPS-103): the engine
+    /// names a 26.2 C symbol unguarded, so an older Xcode cannot compile it. When the symbol goes,
+    /// this fails and the row can come down with it.
+    func testXcodeRequirementIsTheSDKTheSourceCompilesAgainst() throws {
+        let probe = try sourceFile("Sources/AetherEngine/Video/VTCapabilityProbe.swift")
+        XCTAssertTrue(probe.contains("VTRegisterSupplementalVideoDecoderIfAvailable("), """
+            VTCapabilityProbe no longer calls the iOS / tvOS 26.2 symbol that sets the README's Xcode row.
+            Re-derive the SDK requirement and update the Requirements table.
+            """)
+        assertDocumented("| Xcode | 26.2 |", try documentation())
+    }
+
     /// The docs corpus is README + docs/; a claim living in a source docstring is read straight.
     private func sourceFile(_ relativePath: String) throws -> String {
         guard let text = try? String(contentsOf: Self.repoRoot.appendingPathComponent(relativePath),
diff --git a/docs/api.md b/docs/api.md
index 0156678a0..8b256f8d2 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -942,7 +942,7 @@ All flags default to safe values; the table is the full set. Depth for the media
 
 | Option | Default | What it does |
 | --- | --- | --- |
-| `httpHeaders` | empty | Extra headers on every probe, range and segment fetch. On `nativeRemoteHLS` they ride into the `AVURLAsset`, so header-enforcing IPTV origins work. Forwarded to sidecar subtitle fetches unless overridden. |
+| `httpHeaders` | empty | Extra headers on every probe, range and segment fetch. On `nativeRemoteHLS` they ride into the `AVURLAsset`, so header-enforcing IPTV origins work. Forwarded to sidecar subtitle fetches unless overridden. **Scoping differs by route.** On the plain `nativeRemoteHLS` bypass AVFoundation itself sends them to every host the playlists name (cross-host variants, segments and `EXT-X-KEY` URIs) and carries them across 302 redirects, so credential headers there reach every such host and the engine cannot narrow that. The per-origin credential scoping described for `HLSLiveIngestReader` applies only on the routes the engine fetches itself: the ingest, the disc reader, the origin relay, the subtitle proxy, the audio tap and the live subtitle renditions. A credential that must not reach every host a playlist names should not ride in `httpHeaders` on the bypass. |
 | `isLive` | false | Treat the source as live. Set it explicitly; duration-based auto-detection is too noisy. |
 | `dvrWindowSeconds` | nil | Timeshift window. nil means live-only and `seek` is a no-op. |
 | `liveJoinProfile` | `.standard` | A `LiveJoinProfile`. `.fastZap` collapses TARGETDURATION to the source GOP so an IPTV join costs seconds instead of a full holdback. |
diff --git a/docs/architecture.md b/docs/architecture.md
index a97e02700..e41b0660d 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -8,7 +8,7 @@ AetherEngine has three playback pipelines, picked once at `load(url:)`: the audi
 
 ### Native AVPlayer pipeline (default)
 
-Demux the source with libavformat, re-mux the elementary streams on the fly into HLS-fMP4, serve them from a local HTTP server on `127.0.0.1:<port>`, point `AVPlayer` at the playlist. Apple's stack does all decode, all HDR / Dolby Vision signaling over HDMI, all audio routing. This is the path for HEVC and progressive H.264, which is what AVPlayer's HLS-fMP4 pipeline reliably accepts (interlaced H.264 routes to the software path for deinterlacing, #107). Atmos passthrough, DV HDMI handshake, HDR10 / HDR10+ system-side tone-mapping all live on this path.
+Demux the source with libavformat, re-mux the elementary streams on the fly into HLS-fMP4, serve them from a local HTTP server on an ephemeral port (the player is handed `127.0.0.1:<port>/<session-token>/...`; the listener binds all interfaces so an AirPlay receiver can reach it over the LAN, behind the per-session path token, a 32-connection cap with 24 for non-loopback peers, and a 10 s head deadline for unauthenticated connections), point `AVPlayer` at the playlist. Apple's stack does all decode, all HDR / Dolby Vision signaling over HDMI, all audio routing. This is the path for HEVC and progressive H.264, which is what AVPlayer's HLS-fMP4 pipeline reliably accepts (interlaced H.264 routes to the software path for deinterlacing, #107). Atmos passthrough, DV HDMI handshake, HDR10 / HDR10+ system-side tone-mapping all live on this path.
 
 ```
 Source URL ──► Demuxer ──► HLSSegmentProducer ──► SegmentCache ──► HLSLocalServer
@@ -445,7 +445,7 @@ Sources/AetherEngine/
 │   ├── SoftwarePiPSource.swift              Everything a host needs to build an `AVPictureInPictureController` content source around the software path without AVKit entering the engine: the layer plus the four transport answers behind the sample-buffer delegate
 │   └── StartupReadinessGate.swift           Outcome of one startup-readiness attempt: the reloaded item reached a playable state, died, or ran out the settle window without doing either
 ├── Network/
-│   └── HLSLocalServer.swift                 Native path: local HTTP server (127.0.0.1) serving playlist + segments
+│   └── HLSLocalServer.swift                 Native path: local HTTP server (all interfaces for AirPlay, every path behind a per-session token, loopback URLs handed to the local player) serving playlist + segments
 ├── Renderer/
 │   ├── SampleBufferRenderer.swift           SW path: AVSampleBufferDisplayLayer + B-frame reorder, HDR10+ attachments; `flush(removingDisplayedImage:)` holds the last frame through a seek (#90); the decode thread reaches the layer only through its `sampleBufferRenderer`, taken once on the main actor (#351)
 │   └── SubtitleFrameCompositor.swift        Composites active cues into decoded software-path frames while PiP is active, since the system PiP window renders only the sample-buffer layer; playback wins, every failure path returns the original buffer untouched
diff --git a/docs/cli.md b/docs/cli.md
index 9c5121986..fca500181 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -43,15 +43,16 @@ swift run aetherctl probe --detect-hdr10plus /path/to/hdr10plus.mkv
 
 ## serve
 
-The original behavior. The CLI prints the loopback URL and parks until Ctrl-C; from another terminal you can:
+The original behavior. The CLI prints the loopback URL (`=== PLAYBACK URL ===`) and parks until Ctrl-C. The server listens on all interfaces (so an AirPlay receiver can reach it) and answers only paths that start with a per-session token, anything else is a 404, so the printed URL carries it: `http://127.0.0.1:<port>/<token>/...`. Take the `<port>/<token>` prefix from that line; from another terminal you can:
 
 ```bash
-curl -i  http://127.0.0.1:<port>/master.m3u8
-curl -o  /tmp/init.mp4   http://127.0.0.1:<port>/init.mp4
-mediastreamvalidator http://127.0.0.1:<port>/master.m3u8
+curl -i  http://127.0.0.1:<port>/<token>/master.m3u8
+curl -o  /tmp/init.mp4   http://127.0.0.1:<port>/<token>/init.mp4
+mediastreamvalidator http://127.0.0.1:<port>/<token>/master.m3u8
 mp4dump --verbosity 1 /tmp/init.mp4
+curl -o  /tmp/seg0.mp4   http://127.0.0.1:<port>/<token>/seg0.mp4
 ffprobe -v debug /tmp/seg0.mp4
-open 'http://127.0.0.1:<port>/master.m3u8'   # macOS QuickTime
+open 'http://127.0.0.1:<port>/<token>/master.m3u8'   # macOS QuickTime
 ```
 
 `--no-dv` forces the SDR / HDR10 route even for a Dolby Vision source (compare the two playlists).
@@ -267,6 +268,10 @@ point is that there is no second ask to refuse. Two shapes are worth running del
 they are the two the flag has to survive: a long uninterrupted read, and a PAUSE, which must end the
 connection after five seconds and cost exactly one re-request at the frontier when playback resumes.
 
+`--max-concurrent-requests N` sets `LoadOptions.maxConcurrentSourceRequests` (#377): the most requests the reader may have open against the origin at once, across every path it fetches on. `1` also switches off the speculative parallel paths, which is the shape of a connection-metered CDN. Count the requests in the origin's own log, or read the `[AVIOReader]` connection lines, with and without the flag.
+
+`--assert-dv` sets `LoadOptions.panelPresentsDolbyVision` (AE#493), the host's assertion that its display presents Dolby Vision. macOS has no per-mode display capability API, so a Mac run plays a Dolby Vision source as its HDR10 base layer (`effective-format=hdr10`) until the host says otherwise; the flag moves that label and the tvOS criteria request. It does not change the packaging of a Profile 5 / 8.1 / 8.4 source (those carry their `dvcC` and `SUPPLEMENTAL-CODECS` on every display since 6.72.0 / 6.73.0), while Profile 7 and AV1 Dolby Vision are still gated on it. A wrong claim costs one in-place media-playlist fallback, not the item.
+
 `--picture-probe` attaches an `AVPlayerItemVideoOutput` to the running item and decodes the source
 time out of the picture itself, which is the one axis question nothing else here can answer: every
 other observable (`#260` frame times, `prodShift` / `hostShift`) describes what the engine WROTE, not
@@ -629,6 +634,8 @@ Activates two subtitle tracks simultaneously on one source (primary + secondary)
 
 Runs a live MPEG-TS session against a built-in fixture that serves an endless broadcast by looping a seed `.ts` with rewritten timestamps. Flags simulate the failure modes the live path hardens against: `--drop-after N` (mid-stream connection drop + reconnect), `--discontinuity-at N` (program-boundary PTS / PCR jump), `--realtime` (1x wall-clock pacing), `--preroll N` (backlog seconds the paced fixture bursts before 1x pacing; default 30, `0` models a strict-realtime origin with no backlog), `--origin-lead N` (how far ahead of the wall clock the paced origin is allowed to run, which is the standing distance a raw live client ends up reading behind it: the built-in 2 s sits exactly on the old live-edge tolerance and hides both sides of it, `--origin-lead 6` joins a session six seconds behind the reader's frontier and its post-rejoin distance then sawtooths 1.4 to 2.6 s, which is the Sodalite#104 round 2 measurement), `--realtime-rate X` (implies `--realtime`; holds the origin at X times wall clock for the whole run, which is the shape `--realtime` at 1x and an unpaced fixture bracket without covering: a restreamer serving from a standing buffer keeps handing over faster than the content happens, so the live edge outruns the client tracking it for as long as the session lasts rather than for the length of one burst), `--fast-zap` (loads with `LoadOptions.liveJoinProfile = .fastZap`; the first serve prefers the full holdback but is bounded after two finalized segments plus a 0.5...2.0 s observed-segment grace), `--dvr-window N` (timeshift), `--measure-rss` (sliding-window retention), `--reload-test` (live rejoin end to end, including the full-backlog replay shape some origins serve on reconnect). `--seed <ts>` overrides the seed clip, `--sw` forces the software live path, `--report-cache-bytes` tracks on-disk DVR footprint, `--serve-only` parks the fixture without attaching an engine (raw `curl` / `ffprobe` inspection), `--rewind-test` runs the DVR rewind-and-return matrix variant, `--rewind-hold N` parks the playhead N seconds behind the edge and HOLDS it there for the rest of the run (the regime that separates a resident floor doing its job from a window outrunning the reader: it reports the floor-minus-playhead inversion, stalled ticks, and any `live window slid past the consumer` line), `--freeze-after N` freezes the upstream with the connection still open, `--rewind-before-freeze N` parks the playhead inside the DVR window first, `--unfreeze-after N` lets the frozen upstream deliver again after N seconds (the only way to drive the recovery half: a window closed with ENDLIST re-opening, and where the rejoin puts a timeshifted viewer). Since AE#446 round 7 the leg reports two different healthy outcomes for it, and the difference is the whole point of that round: `VERDICT: live-freeze position held` is a window that was closed and rejoined, while `VERDICT: live-freeze gap absorbed` is a gap short enough that the window was never closed at all, so no item was swapped and the viewer saw nothing. The per-tick line carries `item=` (the item's own playhead, which is the session clock less the session's shift, so the two disagree by a constant and only the first is the consumer's place) and `buf=` (how long that consumer can keep playing out of what it already holds). The pair is what makes an outage decision readable: the close spends a DEPTH, and the segments the window lists above the consumer's fetch point are only half of one. Since AE#523 round 2 what decides between them is the CONTENT: a freeze drives the second for as long as the consumer still holds more than one target duration of runway ahead of its own fetch point, whatever the clock says, and the clock keeps only the ceiling at which the producer gives a silent source up (`35 s` less a patience, so 26.0 s at the fixture's TARGETDURATION 6). With the built-in fixture that is, for example, `--freeze-after 60 --unfreeze-after 22 --rewind-before-freeze 30`, where 24.0 s of runway carries a 20.1 s silence and is absorbed, against a close and an item swap before that round. Drop the rewind to 0 and the same 12 s freeze is absorbed too since AE#520 round 2, because the edge viewer's own buffer is counted: 8.0 s listed plus 3.9 s in hand against a 6.0 s reserve, where the listed half alone closed the window 1.84 s before the source delivered again. A 30 s freeze at the same depth still closes, at 16.07 s of silence with 6.0 s of depth left and nothing at all still to fetch, which is the case the old gate could not close at all, `--live-only` loads with no DVR window at all (the shape of a client that keeps its rewind outside the engine, which is where AE#446 round 4 came from: the freeze leg then measures the only timeshift such a session can have, the backlog an outage puts between the closed window's end and the source's return, and the sliding 60 s live-only retention makes the fresh item's own axis observable), `--force-recovery-reload-at N` drives the stage-2 recovery reload without waiting for a real item death, and `--gen-highbitrate-seed` generates a ~22 Mbps 1080p H.264 MPEG-TS seed (for RSS-retention measurement) then exits. `--start-position S` loads the live session with a resume anchor, the same one `load(url:startPosition:)` takes. Live callers normally pass nil, so what the anchor does on a live join had never been drivable from here at all. Measured on a seed offset to 95173 s: the mount seek is spent on the ITEM axis while a host only ever sees the published clock (item + shift), and AVPlayer CLAMPS an anchor past the end of a 15 s item and joins normally (`item=0.74s`, playing), so an anchor on the wrong axis is not by itself a wedge.
 
+`--no-blocking-reload` sets `LoadOptions.liveBlockingReload = false` (AE#446): the live playlist never advertises `CAN-BLOCK-RELOAD`, which separates "AVPlayer stopped fetching because the playlist stopped changing" from "AVPlayer stopped fetching because it is in low-latency mode".
+
 `--sliding` is still accepted and does nothing: the sliding window is unconditional for live sessions now, and the flag stays only so an older script does not fail on it.
 
 The 1 Hz tick prints `item=<s> ranges=<n> status=<n>` beside `t=` and `edge=` (AE#509). `t=` is the PUBLISHED clock, which carries `playlistShiftSeconds`; `item=` is `AVPlayerItem.currentTime()` on the item axis, which is the field a host's own diagnostic dumps. On a live source whose axis is hours into an encoder clock the two differ by the whole shift in a perfectly healthy session (`t=95173.70s item=0.75s ranges=1 status=1`), so a report quoting one of them cannot be read against a harness printing the other. `ranges=0` is the discriminating fact behind a live join that fetches a whole window and presents none of it: it says nothing has been PLACED, which `isPlaybackBufferEmpty` cannot say (AE#418, a fetch is not a placement).

From 9553ee782d636c6ca4916e7cdfbc15c37799b497 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 08:39:41 +0200
Subject: [PATCH 184/359] fix(audio): live bytes telemetry reads a published
 snapshot, not the swapped FFmpeg contexts (audit DEC-104, Vpipeline-101)

AudioBridge.liveBytes and fifoSampleCount loaded swrCtx / encoderCtx without
opLock and called swr_get_delay on them, while feed() rebuilds the resampler
on a decoded format change and startSegment() rebuilds the encoder after an
EOF drain. A read that lost the race used freed memory, and the garbage delay
reached checked multiplication (measured: arithmetic overflow trap in the
getter under a format-flipping stress run).

The bridge now publishes the figures at the end of feed, flush, startSegment
and close, while opLock is held, and the readers take the snapshot under a
separate small lock. They never touch a context.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 Sources/AetherEngine/Audio/AudioBridge.swift  |  61 ++++----
 .../AudioBridgeLiveBytesTests.swift           | 137 ++++++++++++++++++
 2 files changed, 168 insertions(+), 30 deletions(-)
 create mode 100644 Tests/AetherEngineTests/AudioBridgeLiveBytesTests.swift

diff --git a/Sources/AetherEngine/Audio/AudioBridge.swift b/Sources/AetherEngine/Audio/AudioBridge.swift
index c33014ec0..af615e152 100644
--- a/Sources/AetherEngine/Audio/AudioBridge.swift
+++ b/Sources/AetherEngine/Audio/AudioBridge.swift
@@ -181,10 +181,17 @@ final class AudioBridge: @unchecked Sendable {
     /// source), the abandoned pump can still be inside feed() while the restart thread calls
     /// startSegment() on this otherwise lock-free bridge; concurrent libswresample/libavcodec calls on
     /// the same contexts are a data race. Uncontended in the normal single-pump case. Mirrors
-    /// AudioDecoder.stateLock. Diagnostic reads (fifoSampleCount/liveBytes) stay lock-free; the engine
-    /// lifecycle (restartLock ref-handoff + waitForFinish-gated cleanup) forecloses their races.
+    /// AudioDecoder.stateLock. Diagnostic reads (fifoSampleCount/liveBytes) never touch a context: they read
+    /// a snapshot published under `opLock` (audit DEC-104, Vpipeline-101), because feed() and startSegment()
+    /// free and replace `swrCtx` / `encoderCtx` mid-session and the lifecycle only forecloses that for cleanup().
     private let opLock = NSLock()
 
+    /// The figures `liveBytes` and `fifoSampleCount` report, written at the end of every operation that
+    /// can change them while `opLock` is held. Its own lock, so a 1 Hz reader neither waits on a long
+    /// feed() nor sees a torn struct.
+    private let liveBytesLock = NSLock()
+    private var publishedLiveBytes = LiveBytes(fifoSamples: 0, fifoBytes: 0, swrDelaySamples: 0, swrDelayBytes: 0)
+
     /// PCM intermediate format end-to-end (resampler -> FIFO -> encoder). S16 for lossy sources (EAC3/AC3);
     /// S32 @ bits_per_raw_sample=24 for lossless sources (TrueHD, DTS-HD MA, FLAC, ALAC, raw 24/32-bit PCM) so
     /// FLAC output stays bit-perfect (S16 would dither away the bottom 8 bits, audible in quiet passages).
@@ -487,14 +494,12 @@ final class AudioBridge: @unchecked Sendable {
         opLock.lock()
         defer { opLock.unlock() }
         cleanup()
+        publishLiveBytes()
     }
 
     /// FIFO depth in samples/channel, for the engine memory probe. Steady-state below frame_size (~4608 @48kHz);
     /// a growing value means the encoder isn't keeping up with the resampler.
-    var fifoSampleCount: Int {
-        guard let f = fifo else { return 0 }
-        return Int(av_audio_fifo_size(f))
-    }
+    var fifoSampleCount: Int { liveBytes.fifoSamples }
 
     /// Cumulative bytes of encoded audio the bridge has emitted this session (sum of every output packet's size).
     /// Monotonic across producer restarts and encoder rebuilds; the telemetry sampler diffs it into a live output
@@ -623,37 +628,30 @@ final class AudioBridge: @unchecked Sendable {
     }
 
     var liveBytes: LiveBytes {
-        let fifoSamples: Int
-        if let f = fifo {
-            fifoSamples = Int(av_audio_fifo_size(f))
-        } else {
-            fifoSamples = 0
-        }
-
-        let channels: Int
-        let bytesPerSample: Int = Int(pcmBytesPerSample)
-        if let enc = encoderCtx {
-            channels = Int(enc.pointee.ch_layout.nb_channels)
-        } else {
-            channels = 0
-        }
-
-        let fifoBytes = fifoSamples * channels * bytesPerSample
+        liveBytesLock.lock()
+        defer { liveBytesLock.unlock() }
+        return publishedLiveBytes
+    }
 
-        let swrDelaySamples: Int
+    /// Reads the FFmpeg contexts and publishes the result for `liveBytes`. Callers hold `opLock`, which
+    /// is what makes the reads safe against the swaps.
+    private func publishLiveBytes() {
+        let fifoSamples = fifo.map { Int(av_audio_fifo_size($0)) } ?? 0
+        let channels = encoderCtx.map { Int($0.pointee.ch_layout.nb_channels) } ?? 0
+        let bytesPerSample = Int(pcmBytesPerSample)
+        var swrDelaySamples = 0
         if let swr = swrCtx, let enc = encoderCtx {
             swrDelaySamples = Int(swr_get_delay(swr, Int64(enc.pointee.sample_rate)))
-        } else {
-            swrDelaySamples = 0
         }
-        let swrDelayBytes = swrDelaySamples * channels * bytesPerSample
-
-        return LiveBytes(
+        let snapshot = LiveBytes(
             fifoSamples: fifoSamples,
-            fifoBytes: fifoBytes,
+            fifoBytes: fifoSamples * channels * bytesPerSample,
             swrDelaySamples: swrDelaySamples,
-            swrDelayBytes: swrDelayBytes
+            swrDelayBytes: swrDelaySamples * channels * bytesPerSample
         )
+        liveBytesLock.lock()
+        publishedLiveBytes = snapshot
+        liveBytesLock.unlock()
     }
 
     /// Mark a producer restart boundary: drain the FIFO (drops the buffered partial frame, max ~96 ms @48kHz) and
@@ -662,6 +660,7 @@ final class AudioBridge: @unchecked Sendable {
     func startSegment() {
         opLock.lock()
         defer { opLock.unlock() }
+        defer { publishLiveBytes() }
         // A prior pump reached EOF and flush() drained the encoder into its terminal state; rebuild it
         // before this restart feeds new frames (#99 failure mode B).
         if drainedAtEOF {
@@ -697,6 +696,7 @@ final class AudioBridge: @unchecked Sendable {
         guard let dec = decoderCtx, let enc = encoderCtx,
               let swr = swrCtx, let fifoPtr = fifo else { return [] }
         drainedAtEOF = true
+        defer { publishLiveBytes() }
         var results: [UnsafeMutablePointer<AVPacket>] = []
 
         // 1. Drain the decoder's internal delay.
@@ -833,6 +833,7 @@ final class AudioBridge: @unchecked Sendable {
               let fifoPtr = fifo else {
             return []
         }
+        defer { publishLiveBytes() }
 
         stats.packetsFed += 1
         stats.packetsFedSinceLastEnqueue += 1
diff --git a/Tests/AetherEngineTests/AudioBridgeLiveBytesTests.swift b/Tests/AetherEngineTests/AudioBridgeLiveBytesTests.swift
new file mode 100644
index 000000000..0a8bc6e1e
--- /dev/null
+++ b/Tests/AetherEngineTests/AudioBridgeLiveBytesTests.swift
@@ -0,0 +1,137 @@
+import Testing
+import Foundation
+import AetherLibavcodec
+import AetherLibavutil
+@testable import AetherEngine
+
+/// Audit DEC-104 / Vpipeline-101: the 1 Hz telemetry read `swrCtx` and `encoderCtx` without the
+/// bridge's lock and called `swr_get_delay` on them, while the pump thread frees and replaces both
+/// mid-stream (a decoded format change rebuilds the resampler, a restart after EOF rebuilds the
+/// encoder). The read is a use-after-free in a window a few instructions wide, so the defect is pinned
+/// as a stress run that is meant to be read under TSan, plus the figures the snapshot must agree on.
+@Suite("AudioBridge live bytes snapshot (DEC-104, Vpipeline-101)")
+struct AudioBridgeLiveBytesTests {
+
+    private final class Flag: @unchecked Sendable {
+        private let lock = NSLock()
+        private var done = false
+        func set() { lock.withLock { done = true } }
+        var isSet: Bool { lock.withLock { done } }
+    }
+
+    private final class Tally: @unchecked Sendable {
+        private let lock = NSLock()
+        private var polls = 0
+        private var insane = 0
+        func record(sane: Bool) { lock.withLock { polls += 1; if !sane { insane += 1 } } }
+        var snapshot: (polls: Int, insane: Int) { lock.withLock { (polls, insane) } }
+    }
+
+    private func makeCodecpar() -> UnsafeMutablePointer<AVCodecParameters> {
+        let par = avcodec_parameters_alloc()!
+        par.pointee.codec_type = AVMEDIA_TYPE_AUDIO
+        par.pointee.codec_id = AV_CODEC_ID_MP3
+        par.pointee.sample_rate = 48_000
+        par.pointee.format = AV_SAMPLE_FMT_FLTP.rawValue
+        av_channel_layout_default(&par.pointee.ch_layout, 2)
+        return par
+    }
+
+    /// One silent MPEG-1 Layer III frame (128 kbps). 44.1 kHz and 48 kHz frames alternate, so the
+    /// decoder answers with a different rate every packet and the bridge rebuilds its resampler each time.
+    private func makeFrame(rate48k: Bool, pts: Int64) -> UnsafeMutablePointer<AVPacket>? {
+        let size = rate48k ? 384 : 417
+        guard let pkt = trackedPacketAlloc(), av_new_packet(pkt, Int32(size)) >= 0 else { return nil }
+        memset(pkt.pointee.data, 0, size)
+        pkt.pointee.data[0] = 0xFF
+        pkt.pointee.data[1] = 0xFB
+        pkt.pointee.data[2] = rate48k ? 0x94 : 0x90
+        pkt.pointee.pts = pts
+        pkt.pointee.dts = pts
+        return pkt
+    }
+
+    private func free(_ packets: [UnsafeMutablePointer<AVPacket>]) {
+        for p in packets {
+            var pp: UnsafeMutablePointer<AVPacket>? = p
+            trackedPacketFree(&pp)
+        }
+    }
+
+    @Test("a poller reading liveBytes through resampler and encoder swaps sees only sane figures")
+    func pollerSurvivesContextSwaps() throws {
+        let codecpar = makeCodecpar()
+        defer {
+            var p: UnsafeMutablePointer<AVCodecParameters>? = codecpar
+            avcodec_parameters_free(&p)
+        }
+        let bridge = try AudioBridge(srcCodecpar: codecpar, srcTimeBase: AVRational(num: 1, den: 1000),
+                                     mode: .surroundCompat)
+        defer { bridge.close() }
+
+        let finished = Flag()
+        let tally = Tally()
+        let poller = Thread {
+            while !finished.isSet {
+                let live = bridge.liveBytes
+                let sane = live.fifoSamples >= 0
+                    && live.swrDelaySamples >= 0 && live.swrDelaySamples < 1 << 20
+                    && live.fifoBytes >= 0 && live.swrDelayBytes >= 0
+                    && live.totalBytes == live.fifoBytes + live.swrDelayBytes
+                tally.record(sane: sane)
+            }
+        }
+        poller.start()
+
+        var produced = 0
+        for round in 0..<40 {
+            for i in 0..<40 {
+                guard let pkt = makeFrame(rate48k: i % 2 == 0, pts: Int64(round * 40 + i) * 26) else { continue }
+                let out = (try? bridge.feed(packet: pkt)) ?? []
+                produced += out.count
+                free(out)
+                var p: UnsafeMutablePointer<AVPacket>? = pkt
+                trackedPacketFree(&p)
+            }
+            free(bridge.flush())
+            bridge.startSegment()
+        }
+        finished.set()
+        while !poller.isFinished { usleep(1000) }
+
+        #expect(bridge.feedStats.framesDecoded > 0, "the fixture must reach the resampler for the swaps to happen")
+        let result = tally.snapshot
+        #expect(result.polls > 0)
+        #expect(result.insane == 0)
+    }
+
+    @Test("the snapshot follows the bridge through feed, restart and close")
+    func snapshotTracksOperations() throws {
+        let codecpar = makeCodecpar()
+        defer {
+            var p: UnsafeMutablePointer<AVCodecParameters>? = codecpar
+            avcodec_parameters_free(&p)
+        }
+        let bridge = try AudioBridge(srcCodecpar: codecpar, srcTimeBase: AVRational(num: 1, den: 1000),
+                                     mode: .surroundCompat)
+        for i in 0..<3 {
+            guard let pkt = makeFrame(rate48k: true, pts: Int64(i) * 24) else { continue }
+            free((try? bridge.feed(packet: pkt)) ?? [])
+            var p: UnsafeMutablePointer<AVPacket>? = pkt
+            trackedPacketFree(&p)
+        }
+        let afterFeed = bridge.liveBytes
+        #expect(afterFeed.fifoSamples > 0, "three MP3 frames leave a partial encoder frame in the FIFO")
+        #expect(afterFeed.fifoSamples == bridge.fifoSampleCount)
+        #expect(afterFeed.fifoBytes > 0)
+
+        bridge.startSegment()
+        #expect(bridge.liveBytes.fifoSamples == 0)
+        #expect(bridge.fifoSampleCount == 0)
+
+        bridge.close()
+        let closed = bridge.liveBytes
+        #expect(closed.fifoSamples == 0 && closed.fifoBytes == 0)
+        #expect(closed.swrDelaySamples == 0 && closed.swrDelayBytes == 0)
+    }
+}

From 45404c1e889d3dc4cdfc7b9fe5eea113bae1888f Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 08:42:53 +0200
Subject: [PATCH 185/359] fix(audio): a flush retires in-flight audio buffers
 atomically with the enqueue (audit DEC-106)

Both FFmpeg hosts compared the seek generation and then called
AudioOutput.enqueue, so a seek whose renderer flush landed in between parked a
pre-seek buffer in the fresh queue: silence until the clock reached its stamp,
and a false rebuffer on the software host.

AudioOutput now carries an epoch that flush() and stop() retire under the lock,
and enqueue(sampleBuffer:ifEpoch:) compares and enqueues under that same lock.
The audio-only host and the software host's audio branch read the epoch before
the packet and drop the packet when the enqueue is refused. The audio tap
mirror moves behind the accept.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 Sources/AetherEngine/Audio/AudioOutput.swift  | 74 ++++++++-------
 .../Audio/AudioPlaybackHost.swift             | 19 +++-
 .../Native/SoftwarePlaybackHost.swift         | 10 +-
 .../AudioOutputFlushEpochTests.swift          | 91 +++++++++++++++++++
 4 files changed, 158 insertions(+), 36 deletions(-)
 create mode 100644 Tests/AetherEngineTests/AudioOutputFlushEpochTests.swift

diff --git a/Sources/AetherEngine/Audio/AudioOutput.swift b/Sources/AetherEngine/Audio/AudioOutput.swift
index 56ca7d657..84d1bdd5e 100644
--- a/Sources/AetherEngine/Audio/AudioOutput.swift
+++ b/Sources/AetherEngine/Audio/AudioOutput.swift
@@ -19,6 +19,16 @@ final class AudioOutput: @unchecked Sendable {
     /// One line per offset change, not per buffer. Reset by `setPresentationOffset`.
     private var loggedOffsetInEffect = false
 
+    /// Audit DEC-106: retired by every `flush()` and `stop()`, under `lock`. A feed loop reads it before
+    /// it reads a packet and enqueues through `enqueue(sampleBuffer:ifEpoch:)`, which compares under the
+    /// same lock, so a buffer decided on before a seek's flush can no longer land after it.
+    private var _epoch: UInt64 = 0
+    var epoch: UInt64 {
+        lock.lock()
+        defer { lock.unlock() }
+        return _epoch
+    }
+
     init() {
         renderer = AVSampleBufferAudioRenderer()
         synchronizer = AVSampleBufferRenderSynchronizer()
@@ -155,13 +165,38 @@ final class AudioOutput: @unchecked Sendable {
     /// Enqueue a decoded audio CMSampleBuffer. Always enqueues (renderer buffers internally); gating on
     /// isReadyForMoreMediaData dropped early samples before the synchronizer started, giving silence.
     ///
+    /// Audit DEC-106: with `epoch`, the buffer is enqueued only if no flush has retired that epoch, and the
+    /// comparison and the enqueue happen under the lock `flush` takes. Returns false, enqueuing nothing,
+    /// for a buffer that predates a flush.
+    ///
     /// AE#464: this is where a lip-sync offset is applied, and the position is the point. It is past
     /// the audio tap (whose `sourceTime` is documented as the SOURCE axis and feeds transcription),
     /// past the decoder's gapless clock (which would absorb a sub-100 ms offset as rounding), and
     /// past the caller's `lastEnqueuedAudioPtsSec` bookkeeping (whose lead is measured against the
     /// synchronizer clock, i.e. against the source axis too). Only the renderer sees the shift.
-    func enqueue(sampleBuffer: CMSampleBuffer) {
-        renderer.enqueue(retimed(sampleBuffer))
+    @discardableResult
+    func enqueue(sampleBuffer: CMSampleBuffer, ifEpoch epoch: UInt64? = nil) -> Bool {
+        lock.lock()
+        if let epoch, epoch != _epoch {
+            lock.unlock()
+            return false
+        }
+        let offset = presentationOffset
+        let delivered = offset == .zero ? sampleBuffer : Self.retimed(sampleBuffer, by: offset)
+        var offsetLine: String?
+        if offset != .zero, !loggedOffsetInEffect, delivered !== sampleBuffer {
+            loggedOffsetInEffect = true
+            // Release-visible, once per offset change: an offset that was set and an offset that is being
+            // DELIVERED are different claims, and without this line the difference is only measurable with
+            // a capture card. The two timestamps are the whole proof.
+            let source = CMSampleBufferGetPresentationTimeStamp(sampleBuffer).seconds
+            offsetLine = "[AudioOutput] AE#464 audio delay in effect: "
+                + String(format: "%+.0f ms", offset.seconds * 1000)
+                + String(format: " (sample at %.3fs delivered at %.3fs)", source, source + offset.seconds)
+        }
+        renderer.enqueue(delivered)
+        lock.unlock()
+        if let offsetLine { EngineLog.emit(offsetLine, category: .swPlayback) }
 
         #if DEBUG
         // Once per session: first enqueue + any renderer rejection, to distinguish "nothing enqueued" from
@@ -180,6 +215,7 @@ final class AudioOutput: @unchecked Sendable {
             EngineLog.emit("[AudioOutput] renderer error: \(err)", category: .swPlayback)
         }
         #endif
+        return true
     }
 
     #if DEBUG
@@ -187,36 +223,10 @@ final class AudioOutput: @unchecked Sendable {
     private var _loggedRendererError = false
     #endif
 
-    /// A copy of `sampleBuffer` shifted by the current offset, or the buffer itself when there is
-    /// none (the overwhelmingly common case, and one that must not cost an allocation). A copy that
-    /// cannot be made is delivered unshifted: an audible lip-sync error is a far better outcome than
-    /// a dropped buffer, which is silence.
-    private func retimed(_ sampleBuffer: CMSampleBuffer) -> CMSampleBuffer {
-        lock.lock()
-        let offset = presentationOffset
-        lock.unlock()
-        guard offset != .zero else { return sampleBuffer }
-        let shifted = Self.retimed(sampleBuffer, by: offset)
-
-        // Release-visible, once per offset change: an offset that was set and an offset that is being
-        // DELIVERED are different claims, and without this line the difference is only measurable with
-        // a capture card. The two timestamps are the whole proof.
-        if !loggedOffsetInEffect, shifted !== sampleBuffer {
-            loggedOffsetInEffect = true
-            let source = CMSampleBufferGetPresentationTimeStamp(sampleBuffer).seconds
-            EngineLog.emit(
-                "[AudioOutput] AE#464 audio delay in effect: "
-                + String(format: "%+.0f ms", offset.seconds * 1000)
-                + String(format: " (sample at %.3fs delivered at %.3fs)", source, source + offset.seconds),
-                category: .swPlayback
-            )
-        }
-        return shifted
-    }
-
-    /// The timing half, pure so the shift can be checked without a renderer. Every timing entry moves
+    /// The shift itself, pure so it can be checked without a renderer. Every timing entry moves
     /// by `offset`, presentation and decode alike; an entry with no valid presentation stamp is left
-    /// alone rather than given one.
+    /// alone rather than given one. A copy that cannot be made is delivered unshifted: an audible
+    /// lip-sync error is a far better outcome than a dropped buffer, which is silence.
     static func retimed(_ sampleBuffer: CMSampleBuffer, by offset: CMTime) -> CMSampleBuffer {
         guard offset != .zero else { return sampleBuffer }
         var count: CMItemCount = 0
@@ -268,12 +278,14 @@ final class AudioOutput: @unchecked Sendable {
     func flush() {
         lock.lock()
         defer { lock.unlock() }
+        _epoch &+= 1
         renderer.flush()
     }
 
     func stop() {
         lock.lock()
         defer { lock.unlock() }
+        _epoch &+= 1
         synchronizer.setRate(0.0, time: .zero)
         renderer.flush()
     }
diff --git a/Sources/AetherEngine/Audio/AudioPlaybackHost.swift b/Sources/AetherEngine/Audio/AudioPlaybackHost.swift
index 4340190b7..2402f5d1f 100644
--- a/Sources/AetherEngine/Audio/AudioPlaybackHost.swift
+++ b/Sources/AetherEngine/Audio/AudioPlaybackHost.swift
@@ -438,6 +438,9 @@ final class AudioPlaybackHost {
                 if stopRequested() { return false }
             }
 
+            // Audit DEC-106: read before the packet, so a flush landing anywhere after this retires every
+            // buffer decided on below, inside `enqueue`, where the comparison is atomic with the enqueue.
+            let epochBeforeRead = audioOutput?.epoch ?? 0
             let packet: UnsafeMutablePointer<AVPacket>?
             do {
                 packet = try demuxer.readPacket()
@@ -456,8 +459,14 @@ final class AudioPlaybackHost {
                     // Audit DEC-2: a seek's flush can land inside the drain, as in `decode` below.
                     let drained = aDec.drain()
                     let tail = seekGeneration() == seenSeekGeneration ? drained : []
-                    for buf in tail { aOut.enqueue(sampleBuffer: buf) }
-                    if let last = tail.last {
+                    var tailAccepted = true
+                    for buf in tail {
+                        guard aOut.enqueue(sampleBuffer: buf, ifEpoch: epochBeforeRead) else {
+                            tailAccepted = false
+                            break
+                        }
+                    }
+                    if tailAccepted, let last = tail.last {
                         let end = CMTimeGetSeconds(CMSampleBufferGetPresentationTimeStamp(last))
                             + CMTimeGetSeconds(CMSampleBufferGetDuration(last))
                         if end.isFinite, end > lastEnqueuedEnd { lastEnqueuedEnd = end }
@@ -505,7 +514,11 @@ final class AudioPlaybackHost {
                     return true
                 }
                 for buf in buffers {
-                    aOut.enqueue(sampleBuffer: buf)
+                    guard aOut.enqueue(sampleBuffer: buf, ifEpoch: epochBeforeRead) else {
+                        av_packet_unref(packet)
+                        av_packet_free_safe(packet)
+                        return true
+                    }
                 }
                 if let last = buffers.last {
                     let end = CMTimeGetSeconds(CMSampleBufferGetPresentationTimeStamp(last))
diff --git a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
index 7cf6dd858..cb0f06ad4 100644
--- a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
+++ b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
@@ -2653,6 +2653,8 @@ final class SoftwarePlaybackHost {
             // inside the decoder rather than leaving the caller to re-check a value it cannot hold
             // across the call.
             var epochBeforeRead = videoDecoder.feedEpoch
+            // Audit DEC-106: the audio side of the same rule, compared under the output's lock by `enqueue`.
+            let audioEpochBeforeRead = audioOutput?.epoch ?? 0
             let packet: UnsafeMutablePointer<AVPacket>?
             do {
                 if let readAhead {
@@ -2921,8 +2923,12 @@ final class SoftwarePlaybackHost {
                     return true
                 }
                 for buf in buffers {
-                    tapSink?(buf)   // #95: mirror before enqueue
-                    aOut.enqueue(sampleBuffer: buf)
+                    guard aOut.enqueue(sampleBuffer: buf, ifEpoch: audioEpochBeforeRead) else {
+                        av_packet_unref(packet)
+                        av_packet_free_safe(packet)
+                        return true
+                    }
+                    tapSink?(buf)   // #95: mirrored behind the accept, so a refused buffer is not transcribed
                 }
                 if decoupleAudio, let last = buffers.last {
                     let pts = CMSampleBufferGetPresentationTimeStamp(last)
diff --git a/Tests/AetherEngineTests/AudioOutputFlushEpochTests.swift b/Tests/AetherEngineTests/AudioOutputFlushEpochTests.swift
new file mode 100644
index 000000000..cf9d655f3
--- /dev/null
+++ b/Tests/AetherEngineTests/AudioOutputFlushEpochTests.swift
@@ -0,0 +1,91 @@
+import Foundation
+import AVFoundation
+import CoreMedia
+import Testing
+@testable import AetherEngine
+
+/// Audit DEC-106: both FFmpeg hosts decided "this buffer still belongs to the current position" with a
+/// seek-generation read and then called `AudioOutput.enqueue`, so a seek whose renderer flush landed
+/// between the two parked a pre-seek buffer in the fresh queue (silence until the clock reached its
+/// stamp, and on the software host a false rebuffer). The check has to be made under the lock `flush`
+/// takes, against an epoch the flush retires.
+@Suite("AudioOutput flush epoch (DEC-106)")
+struct AudioOutputFlushEpochTests {
+
+    private func makeBuffer(pts: Double, samples: Int = 1024, sampleRate: Int32 = 48000) -> CMSampleBuffer? {
+        var asbd = AudioStreamBasicDescription(
+            mSampleRate: Float64(sampleRate),
+            mFormatID: kAudioFormatLinearPCM,
+            mFormatFlags: kAudioFormatFlagIsFloat | kAudioFormatFlagIsPacked,
+            mBytesPerPacket: 4, mFramesPerPacket: 1, mBytesPerFrame: 4,
+            mChannelsPerFrame: 1, mBitsPerChannel: 32, mReserved: 0)
+        var format: CMAudioFormatDescription?
+        guard CMAudioFormatDescriptionCreate(allocator: kCFAllocatorDefault,
+                                             asbd: &asbd,
+                                             layoutSize: 0, layout: nil,
+                                             magicCookieSize: 0, magicCookie: nil,
+                                             extensions: nil,
+                                             formatDescriptionOut: &format) == noErr,
+              let format else { return nil }
+        var block: CMBlockBuffer?
+        guard CMBlockBufferCreateWithMemoryBlock(allocator: kCFAllocatorDefault,
+                                                 memoryBlock: nil,
+                                                 blockLength: samples * 4,
+                                                 blockAllocator: kCFAllocatorDefault,
+                                                 customBlockSource: nil,
+                                                 offsetToData: 0,
+                                                 dataLength: samples * 4,
+                                                 flags: kCMBlockBufferAssureMemoryNowFlag,
+                                                 blockBufferOut: &block) == noErr,
+              let block else { return nil }
+        var timing = CMSampleTimingInfo(duration: CMTime(value: 1, timescale: sampleRate),
+                                        presentationTimeStamp: CMTime(seconds: pts, preferredTimescale: sampleRate),
+                                        decodeTimeStamp: .invalid)
+        var out: CMSampleBuffer?
+        guard CMSampleBufferCreate(allocator: kCFAllocatorDefault,
+                                   dataBuffer: block, dataReady: true,
+                                   makeDataReadyCallback: nil, refcon: nil,
+                                   formatDescription: format,
+                                   sampleCount: CMItemCount(samples),
+                                   sampleTimingEntryCount: 1, sampleTimingArray: &timing,
+                                   sampleSizeEntryCount: 0, sampleSizeArray: nil,
+                                   sampleBufferOut: &out) == noErr else { return nil }
+        return out
+    }
+
+    @Test("a buffer decided on before a flush is refused after it")
+    func staleBufferIsRefused() throws {
+        let output = AudioOutput()
+        let buffer = try #require(makeBuffer(pts: 100))
+        let captured = output.epoch
+        output.flush()
+        #expect(output.enqueue(sampleBuffer: buffer, ifEpoch: captured) == false)
+    }
+
+    @Test("a buffer decided on after the flush is accepted")
+    func freshBufferIsAccepted() throws {
+        let output = AudioOutput()
+        output.flush()
+        let buffer = try #require(makeBuffer(pts: 100))
+        #expect(output.enqueue(sampleBuffer: buffer, ifEpoch: output.epoch))
+    }
+
+    @Test("every flush retires the epoch, and stop counts as one")
+    func flushAndStopMoveTheEpoch() {
+        let output = AudioOutput()
+        let start = output.epoch
+        output.flush()
+        let afterFlush = output.epoch
+        #expect(afterFlush != start)
+        output.stop()
+        #expect(output.epoch != afterFlush)
+    }
+
+    @Test("an unconditional enqueue is untouched by the epoch")
+    func unconditionalEnqueueStillEnqueues() throws {
+        let output = AudioOutput()
+        output.flush()
+        let buffer = try #require(makeBuffer(pts: 1))
+        #expect(output.enqueue(sampleBuffer: buffer))
+    }
+}

From e5f71f08424f87fa87943d5429b1349f913442de Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 08:44:00 +0200
Subject: [PATCH 186/359] fix(subtitles): override blocks strip in one forward
 pass and a cue is capped at 64 KiB (audit SUB-101, SUB-110)

cleanASSBody stripped {...} with a regex that rescans to the end of the text at every unclosed
brace, 2.6 s for 20k braces and 4x per doubling, on the pump thread under the tap lock that
HLSVideoEngine.stop() takes on the main actor. One forward scan replaces it, shared with
MovTextSampleBuilder.sanitize, and every per-cue entry point cuts the text to 64 KiB first.
edgeTrimmed removes the leading blank runs with one removeFirst(k) instead of one shift each.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .build-warm.log                               |   1 +
 .../Subtitles/MovTextSampleBuilder.swift      |  13 +-
 .../Subtitles/SubtitleRectText.swift          |  81 ++++++--
 .../ASSOverrideBlockScanTests.swift           | 182 ++++++++++++++++++
 4 files changed, 249 insertions(+), 28 deletions(-)
 create mode 100644 .build-warm.log
 create mode 100644 Tests/AetherEngineTests/ASSOverrideBlockScanTests.swift

diff --git a/.build-warm.log b/.build-warm.log
new file mode 100644
index 000000000..49d5cfc14
--- /dev/null
+++ b/.build-warm.log
@@ -0,0 +1 @@
+EXIT=0
diff --git a/Sources/AetherEngine/Subtitles/MovTextSampleBuilder.swift b/Sources/AetherEngine/Subtitles/MovTextSampleBuilder.swift
index c5fb03a8e..fe73bae26 100644
--- a/Sources/AetherEngine/Subtitles/MovTextSampleBuilder.swift
+++ b/Sources/AetherEngine/Subtitles/MovTextSampleBuilder.swift
@@ -10,18 +10,7 @@ enum MovTextSampleBuilder {
     /// per block, quadratic on a remote cue made of many small blocks (karaoke tracks emit one per
     /// syllable). An unclosed `{` keeps itself and everything after it, as before.
     static func sanitize(_ assText: String) -> String {
-        var s = ""
-        s.reserveCapacity(assText.utf8.count)
-        var cursor = assText.startIndex
-        while cursor < assText.endIndex {
-            guard let open = assText[cursor...].firstIndex(of: "{"),
-                  let close = assText[open...].firstIndex(of: "}") else {
-                s += assText[cursor...]
-                break
-            }
-            s += assText[cursor..<open]
-            cursor = assText.index(after: close)
-        }
+        var s = SubtitleRectText.strippingOverrideBlocks(assText)
         s = s.replacingOccurrences(of: "\\N", with: "\n")
         s = s.replacingOccurrences(of: "\\n", with: "\n")
         s = s.replacingOccurrences(of: "\\h", with: " ")
diff --git a/Sources/AetherEngine/Subtitles/SubtitleRectText.swift b/Sources/AetherEngine/Subtitles/SubtitleRectText.swift
index 041852bca..13cb60bed 100644
--- a/Sources/AetherEngine/Subtitles/SubtitleRectText.swift
+++ b/Sources/AetherEngine/Subtitles/SubtitleRectText.swift
@@ -14,25 +14,49 @@ extension SubtitleTextRun {
 /// Plain-text extraction from FFmpeg subtitle rects, shared by `SubtitleDecoder` (sidecar) and `EmbeddedSubtitleDecoder` (in-container) so ASS parsing fixes live in one place.
 enum SubtitleRectText {
 
+    /// Audit SUB-101: the most text of one cue any pass below looks at. A real cue is a few hundred
+    /// bytes; a hostile track can hand over megabytes, and every per-cue pass here runs on the demux
+    /// pump thread under the subtitle tap lock.
+    static let maxCueBytes = 64 * 1024
+
+    /// `text` cut to `maxCueBytes` at a scalar boundary; the same string, untouched, when it fits.
+    static func capped(_ text: String) -> String {
+        guard text.utf8.count > maxCueBytes else { return text }
+        var end = text.unicodeScalars.startIndex
+        var used = 0
+        for scalar in text.unicodeScalars {
+            let next = used + UTF8.width(scalar)
+            if next > maxCueBytes { break }
+            used = next
+            end = text.unicodeScalars.index(after: end)
+        }
+        return String(text[..<end])
+    }
+
     /// Plain text for a rect: prefers `text` field, falls back to parsing the raw ASS `Dialogue:` line (strip 8 header fields, clean tags + escapes).
     static func plainText(for rect: UnsafeMutablePointer<AVSubtitleRect>) -> String? {
         if let textPtr = rect.pointee.text {
-            let s = String(cString: textPtr)
+            let s = boundedString(cString: textPtr)
             let trimmed = s.trimmingCharacters(in: .whitespacesAndNewlines)
             if !trimmed.isEmpty { return trimmed }
         }
         if let assPtr = rect.pointee.ass {
-            return plainText(fromASSEventLine: String(cString: assPtr))
+            return plainText(fromASSEventLine: boundedString(cString: assPtr))
         }
         return nil
     }
 
+    private static func boundedString(cString pointer: UnsafePointer<CChar>) -> String {
+        let length = strnlen(pointer, maxCueBytes)
+        return String(decoding: UnsafeRawBufferPointer(start: pointer, count: length), as: UTF8.self)
+    }
+
     /// Plain text from a raw ASS event line (`ReadOrder,Layer,Style,...,Text`), for surfaces that need
     /// plain text out of markup-preserving cues (the WebVTT rendition over tap-harvested stores,
     /// Sodalite#32). Guarded on the first field being the integer ReadOrder so a plain, comma-heavy
     /// line is never misparsed as an event; non-event lines just get tag/escape cleaning.
     static func plainText(fromASSEventLine line: String) -> String? {
-        var l = line
+        var l = capped(line)
         if l.hasPrefix("Dialogue: ") {
             l.removeFirst("Dialogue: ".count)
         }
@@ -54,19 +78,44 @@ enum SubtitleRectText {
     /// Strip ASS escapes (`\\N` newline, `\\h` hard space) and
     /// `{...}` override tags; nil when nothing displayable remains.
     static func cleanASSBody(_ raw: String) -> String? {
-        var s = raw
+        var s = capped(raw)
         s = s.replacingOccurrences(of: "\\N", with: "\n")
         s = s.replacingOccurrences(of: "\\n", with: "\n")
         s = s.replacingOccurrences(of: "\\h", with: " ")
-        s = s.replacingOccurrences(
-            of: "\\{[^}]*\\}",
-            with: "",
-            options: .regularExpression
-        )
+        s = strippingOverrideBlocks(s)
         let trimmed = s.trimmingCharacters(in: .whitespacesAndNewlines)
         return trimmed.isEmpty ? nil : trimmed
     }
 
+    /// Drop every `{...}` span: from a `{` to the first `}` after it, so `{a{b}c}` leaves `c}`. A `{`
+    /// with no `}` behind it keeps itself and the rest verbatim.
+    ///
+    /// Audit SUB-101: this was `\\{[^}]*\\}` through `NSRegularExpression`, which rescans to the end
+    /// of the text at every unclosed `{` (20k braces took 2.6 s, doubling cost 4x). One forward pass
+    /// instead: once a `{` finds no `}`, no later one can either. Scanned as UTF-8, so the braces
+    /// match exactly where the regex's UTF-16 units did.
+    static func strippingOverrideBlocks(_ text: String) -> String {
+        guard text.utf8.contains(0x7B) else { return text }
+        let bytes = Array(text.utf8)
+        var out: [UInt8] = []
+        out.reserveCapacity(bytes.count)
+        var index = 0
+        while index < bytes.count {
+            let byte = bytes[index]
+            guard byte == 0x7B else {
+                out.append(byte)
+                index += 1
+                continue
+            }
+            guard let close = bytes[(index + 1)...].firstIndex(of: 0x7D) else {
+                out.append(contentsOf: bytes[index...])
+                break
+            }
+            index = close + 1
+        }
+        return String(decoding: out, as: UTF8.self)
+    }
+
     /// Default ASS play resolution (`ASS_DEFAULT_PLAYRESX/Y`, libavcodec/ass.h). Every event line
     /// libavcodec synthesises for SRT, WebVTT and teletext positions against this space, so it is
     /// the right frame of reference unless a real ASS header declares its own.
@@ -130,7 +179,7 @@ enum SubtitleRectText {
     static func styledRuns(fromASSEventLine line: String,
                            playRes: CGSize = SubtitleRectText.defaultASSPlayRes)
         -> (runs: [SubtitleTextRun], placement: SubtitleTextPlacement?, firstTextRow: Int)? {
-        var body = line
+        var body = capped(line)
         if body.hasPrefix("Dialogue: ") { body.removeFirst("Dialogue: ".count) }
         let parts = body.split(separator: ",", maxSplits: 8, omittingEmptySubsequences: false)
         let text: String = (parts.count == 9 && Int(parts[0]) != nil) ? String(parts[8]) : body
@@ -261,7 +310,7 @@ enum SubtitleRectText {
     /// what the plain path produces. libzvbi teletext ass can prefix a row-positioning newline that
     /// would otherwise render as a blank line ONLY on styled cues (#107). Interior blank lines are
     /// NOT folded here: that is teletext-specific and lives in `teletextBody`.
-    private static func edgeTrimmed(_ runs: [SubtitleTextRun]) -> [SubtitleTextRun]? {
+    static func edgeTrimmed(_ runs: [SubtitleTextRun]) -> [SubtitleTextRun]? {
         var cleaned = runs.filter { !$0.text.isEmpty }
         // Edge-trim leading/trailing whitespace and newlines across the run sequence so a coloured
         // cue matches the plain path (teletextBody flattens + trims the .text case). libzvbi
@@ -271,11 +320,11 @@ enum SubtitleRectText {
         // Predicate matches the plain path's `.whitespacesAndNewlines` (Unicode Zs plus tab plus
         // the newline characters). A literal-space/tab/newline test let U+00A0 survive on a styled
         // cue that an unstyled one trimmed, so the two paths disagreed on the same payload.
-        while let first = cleaned.first {
-            let d = String(first.text.drop(while: \.isWhitespace))
-            if d.isEmpty { cleaned.removeFirst(); continue }
-            cleaned[0] = first.withText(d)
-            break
+        // Audit SUB-110: one `removeFirst(k)`, not one shift of the whole array per blank run.
+        let leadingBlank = cleaned.firstIndex { !$0.text.allSatisfy(\.isWhitespace) } ?? cleaned.count
+        cleaned.removeFirst(leadingBlank)
+        if let first = cleaned.first {
+            cleaned[0] = first.withText(String(first.text.drop(while: \.isWhitespace)))
         }
         while let last = cleaned.last {
             var s = last.text
diff --git a/Tests/AetherEngineTests/ASSOverrideBlockScanTests.swift b/Tests/AetherEngineTests/ASSOverrideBlockScanTests.swift
new file mode 100644
index 000000000..9649841f1
--- /dev/null
+++ b/Tests/AetherEngineTests/ASSOverrideBlockScanTests.swift
@@ -0,0 +1,182 @@
+import Testing
+import Foundation
+@testable import AetherEngine
+
+/// Audit SUB-101 / SUB-110: `cleanASSBody` stripped override blocks with `\{[^}]*\}`, which is
+/// quadratic on a cue made of unclosed `{` (20k braces took 2.6 s, doubling costs 4x) and ran on the
+/// pump thread under the subtitle tap lock. `edgeTrimmed` shifted the run array once per leading
+/// blank run. Both are one pass now.
+struct ASSOverrideBlockScanTests {
+
+    /// The implementation `cleanASSBody` had before the forward scan, kept as the oracle.
+    private func legacyCleanASSBody(_ raw: String) -> String? {
+        var s = raw
+        s = s.replacingOccurrences(of: "\\N", with: "\n")
+        s = s.replacingOccurrences(of: "\\n", with: "\n")
+        s = s.replacingOccurrences(of: "\\h", with: " ")
+        s = s.replacingOccurrences(of: "\\{[^}]*\\}", with: "", options: .regularExpression)
+        let trimmed = s.trimmingCharacters(in: .whitespacesAndNewlines)
+        return trimmed.isEmpty ? nil : trimmed
+    }
+
+    private struct SplitMix64: RandomNumberGenerator {
+        var state: UInt64
+        mutating func next() -> UInt64 {
+            state &+= 0x9E37_79B9_7F4A_7C15
+            var z = state
+            z = (z ^ (z >> 30)) &* 0xBF58_476D_1CE4_E5B9
+            z = (z ^ (z >> 27)) &* 0x94D0_49BB_1331_11EB
+            return z ^ (z >> 31)
+        }
+    }
+
+    private static let normalLines: [String] = [
+        "plain text",
+        "",
+        "   ",
+        "{\\an8}Top of the screen",
+        "{\\an8}{\\b1}Top{\\b0}\\Nline two",
+        "{\\pos(192,240)}Positioned{\\i1} italic{\\i0}",
+        "{\\1c&H00FF00&}green{\\r} back",
+        "{a}{b}{c}adjacent blocks",
+        "{a}{b}",
+        "{}empty block",
+        "x{}y{}z",
+        "{a{b}c}nested open brace",
+        "{{a}b",
+        "{a}{b",
+        "a{b",
+        "{",
+        "}",
+        "}{",
+        "a}b{c}d",
+        "{\\k20}ka{\\k25}ra{\\k30}o{\\k15}ke",
+        "line one\\Nline two\\nline three\\hspaced",
+        "{\\fnArial\\fs32\\b1}\\NLeading break",
+        "trailing {\\i1}",
+        "  {\\an2}  padded  ",
+        "multi\nline {\\b1}text\r\nwith {\\i1}CRLF",
+        "{multi\nline\nblock}after",
+        "\u{00E9}\u{00E8} {\\i1}caf\u{00E9}{\\i0} \u{4E2D}\u{6587} \u{1F600} end",
+        "{\u{4E2D}\u{6587}}\u{1F600}",
+        "e\u{0301}{\\b1}x",
+        "{\u{0301}}x",
+        "{\\N}x",
+        "\\N{\\N}\\N",
+        "{\\b1}{\\i1}{\\u1}{\\s1}",
+    ]
+
+    @Test("the forward scan matches the old regex on ordinary lines")
+    func matchesRegexOnOrdinaryLines() {
+        for line in Self.normalLines {
+            #expect(SubtitleRectText.cleanASSBody(line) == legacyCleanASSBody(line), "line: \(line.debugDescription)")
+        }
+    }
+
+    @Test("the forward scan matches the old regex on generated lines full of braces")
+    func matchesRegexOnGeneratedLines() {
+        let alphabet: [String] = ["{", "}", "{", "}", "\\", "N", "n", "h", "a", "b", " ", "\n", "\u{00E9}",
+                                  "\u{1F600}", "\u{0301}", "\\N", "{\\b1}", ","]
+        var rng = SplitMix64(state: 0xA55_0C1E)
+        for _ in 0..<6000 {
+            let length = Int.random(in: 0...40, using: &rng)
+            var line = ""
+            for _ in 0..<length { line += alphabet.randomElement(using: &rng)! }
+            #expect(SubtitleRectText.cleanASSBody(line) == legacyCleanASSBody(line), "line: \(line.debugDescription)")
+        }
+    }
+
+    @Test("an ASS event line keeps its semantics through plainText(fromASSEventLine:)")
+    func eventLineSemanticsHold() {
+        #expect(SubtitleRectText.plainText(fromASSEventLine: "0,0,Default,,0,0,0,,{\\an8}Hello\\Nthere, friend")
+                == "Hello\nthere, friend")
+        #expect(SubtitleRectText.plainText(fromASSEventLine: "{a}b{c}") == "b")
+        #expect(SubtitleRectText.plainText(fromASSEventLine: "{{a}b") == "b")
+        #expect(SubtitleRectText.plainText(fromASSEventLine: "a{b") == "a{b")
+        #expect(SubtitleRectText.plainText(fromASSEventLine: "{a}{b") == "{b")
+    }
+
+    @Test("a cue of unclosed braces cleans in linear time")
+    func unclosedBracesAreLinear() {
+        let hostile = String(repeating: "{", count: 50_000)
+        let started = ContinuousClock.now
+        let cleaned = SubtitleRectText.cleanASSBody(hostile)
+        let elapsed = ContinuousClock.now - started
+        #expect(cleaned == hostile)
+        #expect(elapsed < .seconds(2), "took \(elapsed)")
+    }
+
+    @Test("a cue of unclosed braces with an unclosed tail is linear through the plain path too")
+    func plainPathIsLinear() {
+        let hostile = "0,0,Default,,0,0,0,," + String(repeating: "{a", count: 25_000)
+        let started = ContinuousClock.now
+        _ = SubtitleRectText.plainText(fromASSEventLine: hostile)
+        _ = SubtitleRectText.styledRuns(fromASSEventLine: hostile)
+        #expect(ContinuousClock.now - started < .seconds(2))
+    }
+
+    @Test("leading blank runs of alternating style trim away through the parser")
+    func alternatingBlankRunsTrimAway() {
+        var line = "0,0,Default,,0,0,0,,"
+        for _ in 0..<5_000 { line += "{\\b1} {\\b0} " }
+        line += "visible"
+        #expect(line.utf8.count < SubtitleRectText.maxCueBytes)
+        let parsed = SubtitleRectText.styledRuns(fromASSEventLine: line)
+        #expect(parsed?.runs.map(\.text).joined() == "visible")
+    }
+
+    @Test("edgeTrimmed drops 100k leading blank runs in linear time")
+    func edgeTrimmedIsLinear() {
+        var runs: [SubtitleTextRun] = []
+        for index in 0..<100_000 {
+            runs.append(SubtitleTextRun(text: " ", color: nil, isBold: index % 2 == 0))
+        }
+        runs.append(SubtitleTextRun(text: "  visible  ", color: nil))
+        let started = ContinuousClock.now
+        let trimmed = SubtitleRectText.edgeTrimmed(runs)
+        let elapsed = ContinuousClock.now - started
+        #expect(trimmed?.map(\.text) == ["visible"])
+        #expect(elapsed < .seconds(2), "took \(elapsed)")
+    }
+
+    @Test("edge trimming still drops leading blank runs and keeps the styled text after them")
+    func edgeTrimKeepsStyledText() {
+        let parsed = SubtitleRectText.styledRuns(fromASSEventLine: "0,0,Default,,0,0,0,,{\\b1} {\\b0}\\N{\\i1} {\\i0}  {\\b1}bold {\\i1}it  ")
+        #expect(parsed?.runs.map(\.text) == ["bold ", "it"])
+        #expect(parsed?.runs.first?.isBold == true)
+        #expect(SubtitleRectText.styledRuns(fromASSEventLine: "0,0,Default,,0,0,0,,{\\b1} {\\b0}\\N ") == nil)
+    }
+
+    @Test("a cue past 64 KiB is cut before any per-cue pass")
+    func oversizedCueIsCapped() {
+        let big = String(repeating: "abcdefgh", count: 200_000)
+        let cleaned = SubtitleRectText.cleanASSBody(big)
+        #expect(cleaned?.utf8.count == 64 * 1024)
+        let plain = SubtitleRectText.plainText(fromASSEventLine: "0,0,Default,,0,0,0,," + big)
+        #expect((plain?.utf8.count ?? .max) <= 64 * 1024)
+        let runs = SubtitleRectText.styledRuns(fromASSEventLine: "0,0,Default,,0,0,0,," + big)?.runs
+        #expect((runs?.map(\.text.utf8.count).reduce(0, +) ?? .max) <= 64 * 1024)
+    }
+
+    @Test("the cap never splits a scalar")
+    func capKeepsScalarsWhole() {
+        let emoji = String(repeating: "\u{1F600}", count: 40_000)
+        let cleaned = SubtitleRectText.cleanASSBody(emoji)
+        #expect(cleaned != nil)
+        #expect(cleaned?.unicodeScalars.contains("\u{FFFD}") == false)
+        #expect((cleaned?.utf8.count ?? .max) <= 64 * 1024)
+        #expect(cleaned?.unicodeScalars.allSatisfy { $0 == "\u{1F600}" } == true)
+    }
+
+    @Test("MovTextSampleBuilder shares the same scan")
+    func movTextSanitizeMatches() {
+        #expect(MovTextSampleBuilder.sanitize("{a}b{c}") == "b")
+        #expect(MovTextSampleBuilder.sanitize("{{a}b") == "b")
+        #expect(MovTextSampleBuilder.sanitize("a{b") == "a{b")
+        #expect(MovTextSampleBuilder.sanitize("{a}{b") == "{b")
+        let hostile = String(repeating: "{", count: 50_000)
+        let started = ContinuousClock.now
+        #expect(MovTextSampleBuilder.sanitize(hostile) == hostile)
+        #expect(ContinuousClock.now - started < .seconds(2))
+    }
+}

From 10958b99e43822e089bcd5b4ed6db5e4c7f166dd Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 08:44:29 +0200
Subject: [PATCH 187/359] fix(demuxer): a Range-ignoring origin plays
 forward-only instead of ending at the first 32 MB boundary (audit DMX-101)

The cold open asks for `bytes=0-33554431`. An origin that cannot address
bytes answers it with a 200 and the whole source, which the reader accepted
(the Content-Length became the file size), cut at the range end (DMX-1), and
then rejected at every later refill because a 200 at offset > 0 is not the
range asked for. After 12 unproductive reconnects the read returned -1, so
playback ended at 32 MB.

The response head of that one connection is now classified with a shared
`AVIOReader.rangeAnswer` (200 that is not the asked span, 206 that starts
elsewhere, 206 wider than asked, a small 200 that covers the whole file).
A range-ignoring 200 is hung up on at the head and confirmed once with
`bytes=1-1`, because some CDNs answer a cache miss with a 200 and every
later request with a 206. A 206 keeps the seekable path; anything else runs
the forward-only streaming path `sequentialOnly` already uses: one unranged
GET, non-seekable pb, the streaming buffer's high water and hard cap.
AVSEEK_SIZE keeps answering the stated Content-Length, which FFmpeg needs to
estimate an MPEG-TS duration. A 200 that covers a small file still sizes it
and stays seekable, and a 200 later in a session is still rejected and
retried rather than read as a verdict on the origin.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 Sources/AetherEngine/Demuxer/AVIOReader.swift | 194 ++++++++++++++++-
 .../RangeIgnoringOriginTests.swift            | 203 ++++++++++++++++++
 .../ThrottledOriginServer.swift               |  23 +-
 docs/api.md                                   |   2 +-
 4 files changed, 404 insertions(+), 18 deletions(-)
 create mode 100644 Tests/AetherEngineTests/RangeIgnoringOriginTests.swift

diff --git a/Sources/AetherEngine/Demuxer/AVIOReader.swift b/Sources/AetherEngine/Demuxer/AVIOReader.swift
index c4d453481..0202c8b31 100644
--- a/Sources/AetherEngine/Demuxer/AVIOReader.swift
+++ b/Sources/AetherEngine/Demuxer/AVIOReader.swift
@@ -504,6 +504,8 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
 
     private var streamBuffer = Data()
     private var streamBytesRead: Int64 = 0
+    /// Most bytes `streamBuffer` has held at once, for the bound tests. Guarded by `streamLock`.
+    private var streamPeakBytes = 0
     private var streamEnded = false
     private let streamLock = NSLock()
     private let streamDataReady = DispatchSemaphore(value: 0)
@@ -792,6 +794,13 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
         return activeTransfer != nil
     }
 
+    /// The most the forward-only streaming buffer has held at once.
+    var streamPeakBufferBytesForTesting: Int {
+        streamLock.lock()
+        defer { streamLock.unlock() }
+        return streamPeakBytes
+    }
+
     /// Bytes the persistent window holds, behind and ahead of the cursor.
     var windowBytesForTesting: Int {
         winCond.lock()
@@ -835,6 +844,17 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
     /// (live sources, and any source whose total size is not resolved yet). winCond-guarded.
     private var connRangeEnd: Int64?
 
+    /// Audit DMX-101: true only while `open()` waits on the cold data connection, so that response
+    /// alone is judged for range support. A 200 later in a session (a CDN cache miss on a refill)
+    /// stays what it always was: rejected and retried, never a verdict on the origin. winCond-guarded.
+    private var rangeVerdictPending = false
+    /// Audit DMX-101: Content-Length of the cold connection's range-ignoring 200, -1 when it stated
+    /// none, nil while the origin has not been caught ignoring. winCond-guarded.
+    private var rangeIgnoredAtOpenLength: Int64?
+    /// Audit DMX-101: the origin cannot address bytes, so this source plays forward-only on the
+    /// streaming path. Written once by `open()` on the demux thread, read by `seek` on the same one.
+    private(set) var originIgnoresRange = false
+
     /// Sodalite#117: contiguous range starts are summarised instead of logged one by one.
     /// winCond-guarded.
     private var connStartLogGate = ConnStartLogGate()
@@ -1169,6 +1189,9 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
                 gotData = true
                 openPrefix = Array(warm.head.data.prefix(16))
             } else {
+                winCond.lock()
+                rangeVerdictPending = !isLive
+                winCond.unlock()
                 startPersistentConnection(at: 0, boundedTo: boundedInitialFetch)
                 gotData = awaitFirstPersistentData()
                 openPrefix = firstWindowPrefix()
@@ -1203,10 +1226,20 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
                 // a size; if not, abandon it (generation bump ignores a size landing in the
                 // race window). fileSize is read under the lock because the delegate thread now
                 // writes it (issue #70 review #4/#5).
-                let (haveSize, abandoned, pumpStatus) = resolveOptimisticOpen()
+                let (haveSize, abandoned, pumpStatus, caughtIgnoringRange) = resolveOptimisticOpen()
                 abandoned?.cancelTransfer()
                 abandoned?.releaseOriginTicket()
-                if !haveSize {
+                var ignoredRangeLength = caughtIgnoringRange
+                if let length = caughtIgnoringRange {
+                    tookFallback = true
+                    try probeControl?.check()
+                    if confirmRangeIsIgnored(contentLength: length) == .honoured { ignoredRangeLength = nil }
+                    try probeControl?.check()
+                }
+                if let ignoredRangeLength {
+                    openForwardOnlyBecauseRangeIsIgnored(contentLength: ignoredRangeLength)
+                    try failIfStreamingRefused(fallbackStatus: 0)
+                } else if !haveSize {
                     tookFallback = true
                     // A 401/403/404/410 at byte 0 is the origin's answer to the RESOURCE, not to
                     // the range form: a HEAD or a `bytes=0-1` from the same client is answered
@@ -1401,10 +1434,14 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
     /// the lock. Demux thread, open-time only; leaves the AVIO context intact (unlike close()).
     /// `pumpStatus` is the HTTP status the abandoned connection was answered with (0 when no
     /// response arrived), so the caller can tell a refused resource from a length-less one.
-    private func resolveOptimisticOpen() -> (haveSize: Bool, abandoned: (any PersistentTransfer)?, pumpStatus: Int) {
+    private func resolveOptimisticOpen() -> (haveSize: Bool, abandoned: (any PersistentTransfer)?,
+                                             pumpStatus: Int, caughtIgnoringRange: Int64?) {
         winCond.lock()
         defer { winCond.unlock() }
-        if fileSize > 0 { return (true, nil, connStatus) }
+        rangeVerdictPending = false
+        let ignoredLength = rangeIgnoredAtOpenLength
+        rangeIgnoredAtOpenLength = nil
+        if fileSize > 0 { return (true, nil, connStatus, nil) }
         let status = connStatus
         connGeneration &+= 1
         let transfer = activeTransfer
@@ -1412,7 +1449,67 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
         window.removeAll()
         connEnded = true
         winCond.broadcast()
-        return (false, transfer, status)
+        return (false, transfer, status, ignoredLength)
+    }
+
+    private enum RangeConfirmation { case honoured, ignored }
+
+    /// Audit DMX-101: the cold connection's 200 is one answer. Some CDNs send a 200 on a cache miss
+    /// and a 206 for every request after it, so the verdict waits for a second, one byte request.
+    /// Anything but a 206 that starts where asked (a 200, a refusal, a timeout, a misplaced range)
+    /// leaves the origin judged as it was caught: a source that cannot address bytes. The body a
+    /// 200 answer carries is cut after the one byte the request asked for (`ChunkFetchDelegate`).
+    /// Demux thread, open-time only.
+    private func confirmRangeIsIgnored(contentLength: Int64) -> RangeConfirmation {
+        var request = URLRequest(url: requestURL())
+        request.setValue("bytes=1-1", forHTTPHeaderField: "Range")
+        let budget = min(10, chunkRequestTimeout)
+        request.timeoutInterval = budget
+        applyExtraHeaders(&request)
+        do {
+            let (_, response) = try syncRequest(request, budget: budget)
+            guard let http = response as? HTTPURLResponse else { return .ignored }
+            switch Self.rangeAnswer(http, requestedStart: 1, requestedEnd: 1) {
+            case .honoured:
+                EngineLog.emit(
+                    "[AVIOReader] \(label) the origin answered the ranged open with a 200 "
+                    + "(Content-Length \(contentLength)) but honours a one byte range; "
+                    + "keeping the seekable path (audit DMX-101)", category: .demux)
+                return .honoured
+            case .overWide:
+                // A 206 is the origin addressing bytes, however wide it answered.
+                return .honoured
+            default:
+                return .ignored
+            }
+        } catch {
+            return .ignored
+        }
+    }
+
+    /// Audit DMX-101: an origin that cannot address bytes is played forward-only, exactly what
+    /// `sequentialOnly` does by declaration: one unranged GET, `fileSize` unresolved so the pb is
+    /// non-seekable (#126 below), and the window bounded by the streaming path's high water. The
+    /// Content-Length it stated stays advisory and is what `AVSEEK_SIZE` answers, because FFmpeg
+    /// estimates an MPEG-TS duration from the size and a length-less source reports none.
+    /// Demux thread, open-time only.
+    private func openForwardOnlyBecauseRangeIsIgnored(contentLength: Int64) {
+        EngineLog.emit(
+            "[AVIOReader] \(label) origin does not honour Range (Content-Length \(contentLength)); "
+            + "playing forward-only from one unranged GET (audit DMX-101)", category: .demux)
+        originIgnoresRange = true
+        fileSize = -1
+        streamLock.lock()
+        streamExpectedBytes = contentLength > 0 ? contentLength : -1
+        streamLock.unlock()
+        winCond.lock()
+        let tailTask = tailPrefetchTask
+        tailPrefetchTask = nil
+        tailPrefetchInFlight = false
+        winCond.unlock()
+        tailTask?.cancel()
+        startStreamingDownload()
+        _ = streamDataReady.wait(timeout: .now() + .seconds(15))
     }
 
     // Close flags written on the teardown thread (markClosed / fullyClose) and read on the demux
@@ -3321,6 +3418,16 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
         // from byte 0 (silent corruption). Reject it. Live is exempt: transcode
         // reconnect legitimately answers 200 with "from now".
         let requestedOffset = (generation == connGeneration) ? connRequestedOffset : 0
+        // Audit DMX-101: the cold open asked for a bounded range at byte 0. A 200 whose body is not
+        // that range is an origin that cannot address bytes, and this connection is abandoned at the
+        // head: nothing below may adopt its Content-Length as a size the persistent reader could
+        // seek by.
+        var rangeIgnoredAtOpen = false
+        if generation == connGeneration, !isLive, rangeVerdictPending,
+           Self.rangeAnswer(http, requestedStart: requestedOffset, requestedEnd: connRangeEnd) == .ignored {
+            rangeIgnoredAtOpen = true
+            rangeIgnoredAtOpenLength = http.expectedContentLength
+        }
         // #331: the origin just told us its live stream has no byte address to resume at. Latch
         // it, so every later request in this session is the join shape instead of repeating an
         // offset that can only ever be rejected again. Nonzero offsets only: a 416 at zero is a
@@ -3352,7 +3459,7 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
             fileSize = 0
             adoptedWarmSize = nil
         }
-        if generation == connGeneration, !isLive, fileSize <= 0,
+        if generation == connGeneration, !isLive, fileSize <= 0, !rangeIgnoredAtOpen,
            let total = Self.sizeFromResponse(http, requestedOffset: requestedOffset) {
             fileSize = total
             // #112: share this resolved length so a later side demuxer on the same origin can skip a probe that
@@ -3385,6 +3492,13 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
             )
             isOK = false
         }
+        if rangeIgnoredAtOpen {
+            EngineLog.emit(
+                "[AVIOReader] \(label) origin answered the ranged open with a 200 "
+                + "(Content-Length \(http.expectedContentLength)); hanging up at the head (audit DMX-101)",
+                category: .demux)
+            isOK = false
+        }
         // Live is exempt for the same reason as above: its offset is bookkeeping, and the append
         // anchors the bytes at the frontier whatever the origin calls them.
         if isOK, !isLive, generation == connGeneration,
@@ -3524,6 +3638,7 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
                 return
             }
             self.streamBuffer.append(data)
+            self.streamPeakBytes = max(self.streamPeakBytes, self.streamBuffer.count)
             var toCancel: URLSessionDataTask?
             if self.streamBuffer.count > Self.streamHardCap {
                 self.streamFailed = true
@@ -3647,7 +3762,12 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
     /// the same reason `recordRateLimitAndShouldGiveUp` is not private. Callers outside the file
     /// are tests; production reaches this through `seekCallback`.
     func seek(offset: Int64, whence: Int32) -> Int64 {
-        if whence == AVSEEK_SIZE { return fileSize }
+        if whence == AVSEEK_SIZE {
+            guard fileSize <= 0, originIgnoresRange else { return fileSize }
+            streamLock.lock()
+            defer { streamLock.unlock() }
+            return streamExpectedBytes
+        }
         // For persistent mode, position is shared with the delegate thread;
         // read SEEK_CUR base under the window lock.
         let newPosition: Int64
@@ -3711,14 +3831,18 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
         return URLSession(configuration: config, delegate: EngineTLS.sessionDelegate, delegateQueue: nil)
     }()
 
-    /// Total size from a data-connection response: `Content-Range` total on a 206, or
-    /// `Content-Length` on a from-0 2xx (origins that answer 200 ignoring Range). Nil when
-    /// the origin gave no usable length (chunked, or an unknown `*` total). Issue #70.
     /// Audit DMX-5: where a 206 says its body starts, when that is not where it was asked to.
     /// Every ranged path here places the body at the REQUESTED offset, so a 206 aligned to an
     /// edge's own chunk boundary would shift every later read by the difference. Nil for any other
     /// status and for a Content-Range this cannot read (those keep the lenient historical path).
     static func misplacedRangeStart(_ http: HTTPURLResponse, requestedOffset: Int64) -> Int64? {
+        guard let served = contentRangeSpan(http) else { return nil }
+        return served.start == requestedOffset ? nil : served.start
+    }
+
+    /// First and last byte a 206 says it carries, nil for any other status and for a Content-Range
+    /// this cannot read.
+    static func contentRangeSpan(_ http: HTTPURLResponse) -> (start: Int64, end: Int64?)? {
         guard http.statusCode == 206,
               let value = http.value(forHTTPHeaderField: "Content-Range") else { return nil }
         let trimmed = value.trimmingCharacters(in: .whitespaces)
@@ -3726,9 +3850,57 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
         let span = trimmed.dropFirst("bytes ".count).split(separator: "/", maxSplits: 1).first ?? ""
         guard let dash = span.firstIndex(of: "-"),
               let start = Int64(span[..<dash].trimmingCharacters(in: .whitespaces)) else { return nil }
-        return start == requestedOffset ? nil : start
+        let end = Int64(span[span.index(after: dash)...].trimmingCharacters(in: .whitespaces))
+        return (start, end)
+    }
+
+    /// Audit DMX-101, NET-102: what an origin did with `Range: bytes=a-b`, judged from the response
+    /// head alone, so a reader can hang up before a body it would have to throw away. One
+    /// classification for every reader (`HTTPDiscIOReader` uses it too).
+    enum RangeAnswer: Equatable {
+        /// A 206 that starts where asked and stays inside the ask.
+        case honoured
+        /// A 206 that starts where asked but runs past the requested end. The origin CAN address
+        /// bytes, so the caller keeps what it asked for and hangs up (audit DMX-1).
+        case overWide
+        /// A 206 that starts elsewhere, the way an edge that aligns ranges to its own chunks answers.
+        case misplaced(start: Int64)
+        /// A 200 that is not the asked range: the body is the source from byte 0, whatever was
+        /// asked, and its length is not the ask's or is not stated at all.
+        case ignored
+        /// A 200 at offset 0 whose Content-Length fits inside the ask: the whole file, and a small
+        /// one. Nothing was ignored that matters, so the source stays sized and seekable.
+        case wholeFile
+        /// Any other status. It says nothing about range support.
+        case unjudged
+    }
+
+    static func rangeAnswer(_ http: HTTPURLResponse, requestedStart: Int64,
+                            requestedEnd: Int64?) -> RangeAnswer {
+        switch http.statusCode {
+        case 206:
+            if let served = misplacedRangeStart(http, requestedOffset: requestedStart) {
+                return .misplaced(start: served)
+            }
+            if let end = requestedEnd {
+                if let servedEnd = contentRangeSpan(http)?.end, servedEnd > end { return .overWide }
+                if http.expectedContentLength > end - requestedStart + 1 { return .overWide }
+            }
+            return .honoured
+        case 200:
+            guard requestedStart == 0 else { return .ignored }
+            let length = http.expectedContentLength
+            guard length > 0 else { return .ignored }
+            if let end = requestedEnd, length > end + 1 { return .ignored }
+            return .wholeFile
+        default:
+            return .unjudged
+        }
     }
 
+    /// Total size from a data-connection response: `Content-Range` total on a 206, or
+    /// `Content-Length` on a from-0 2xx (origins that answer 200 ignoring Range). Nil when
+    /// the origin gave no usable length (chunked, or an unknown `*` total). Issue #70.
     static func sizeFromResponse(_ http: HTTPURLResponse, requestedOffset: Int64) -> Int64? {
         // On a 206 the total lives ONLY in Content-Range; Content-Length is the partial span,
         // so a 206 with an unknown (`*`) or unparseable range must report no size, never fall
diff --git a/Tests/AetherEngineTests/RangeIgnoringOriginTests.swift b/Tests/AetherEngineTests/RangeIgnoringOriginTests.swift
new file mode 100644
index 000000000..184207efc
--- /dev/null
+++ b/Tests/AetherEngineTests/RangeIgnoringOriginTests.swift
@@ -0,0 +1,203 @@
+import Testing
+import Foundation
+@testable import AetherEngine
+
+/// Audit DMX-101: an origin that cannot address bytes (a plain file server, a proxy that strips
+/// `Range`) answered every 32 MB refill with a 200, which the reader rejects, so playback ended at
+/// the first range boundary. Such an origin is now caught at the open and played forward-only with
+/// the streaming path's bounded buffer, and an origin that does honour ranges is left alone.
+@Suite("Range-ignoring origins")
+struct RangeIgnoringOriginTests {
+
+    private static let avseekSize: Int32 = 65536
+    private let mb = 1024 * 1024
+
+    private final class FirstClaim: @unchecked Sendable {
+        private let lock = NSLock()
+        private var claimed = false
+        func take() -> Bool {
+            lock.lock()
+            defer { lock.unlock() }
+            if claimed { return false }
+            claimed = true
+            return true
+        }
+    }
+
+    private func expected(at offset: Int64, count: Int) -> [UInt8] {
+        (0..<count).map { ThrottledOriginServer.patternByte(at: offset + Int64($0)) }
+    }
+
+    /// Reads `total` bytes in 256 KB reads, checking the first 1 KB of the read that crosses each
+    /// 4 MB mark against the origin's pattern. Checking every byte of a 72 MB body would measure the
+    /// test, not the reader.
+    private func drain(_ reader: AVIOReader, total: Int64) -> (read: Int64, last: Int32, firstBadOffset: Int64?) {
+        let chunk = 256 * 1024
+        let buf = UnsafeMutablePointer<UInt8>.allocate(capacity: chunk)
+        defer { buf.deallocate() }
+        var read: Int64 = 0
+        var last: Int32 = 0
+        var nextCheck: Int64 = 0
+        var bad: Int64?
+        while read < total {
+            last = reader.read(into: buf, size: Int32(chunk))
+            if last <= 0 { break }
+            if read + Int64(last) > nextCheck {
+                let start = max(0, nextCheck - read)
+                let n = Int(min(1024, Int64(last) - start))
+                let got = Array(UnsafeBufferPointer(start: buf.advanced(by: Int(start)), count: n))
+                if got != expected(at: read + start, count: n), bad == nil { bad = read + start }
+                nextCheck = (read + Int64(last) + 4 * Int64(mb) - 1) / (4 * Int64(mb)) * 4 * Int64(mb)
+            }
+            read += Int64(last)
+        }
+        return (read, last, bad)
+    }
+
+    private func response(_ status: Int, _ headers: [String: String]) -> HTTPURLResponse {
+        HTTPURLResponse(url: URL(string: "http://example.invalid/movie.bin")!, statusCode: status,
+                        httpVersion: "HTTP/1.1", headerFields: headers)!
+    }
+
+    // MARK: - The classification every reader shares
+
+    @Test("a response is classified by what it did with the range that was asked for")
+    func classification() {
+        func answer(_ http: HTTPURLResponse, start: Int64 = 0, end: Int64? = 99) -> AVIOReader.RangeAnswer {
+            AVIOReader.rangeAnswer(http, requestedStart: start, requestedEnd: end)
+        }
+        #expect(answer(response(206, ["Content-Range": "bytes 0-99/1000", "Content-Length": "100"])) == .honoured)
+        #expect(answer(response(206, ["Content-Range": "bytes 64-99/1000"])) == .misplaced(start: 64))
+        #expect(answer(response(206, ["Content-Range": "bytes 0-999/1000", "Content-Length": "1000"])) == .overWide)
+        #expect(answer(response(206, ["Content-Range": "bytes 0-99/*"])) == .honoured)
+        #expect(answer(response(200, ["Content-Length": "1000"])) == .ignored)
+        #expect(answer(response(200, [:])) == .ignored, "a 200 that states no length cannot be the asked range")
+        #expect(answer(response(200, ["Content-Length": "100"])) == .wholeFile)
+        #expect(answer(response(200, ["Content-Length": "50"])) == .wholeFile)
+        #expect(answer(response(200, ["Content-Length": "100"]), start: 5, end: 99) == .ignored,
+                "a 200 cannot be a range that starts past byte 0")
+        #expect(answer(response(200, ["Content-Length": "5000"]), end: nil) == .wholeFile,
+                "an open-ended ask has no span a 200 could exceed")
+        #expect(answer(response(404, [:])) == .unjudged)
+        #expect(answer(response(416, [:])) == .unjudged)
+    }
+
+    // MARK: - On the wire
+
+    @Test("an origin that ignores Range is read forward-only past the 32 MB range boundary",
+          .timeLimit(.minutes(2)))
+    func forwardOnlyPastTheRangeBoundary() throws {
+        let total = Int64(72 * mb)
+        let maybe = ThrottledOriginServer(totalSize: total, throttleUs: 500, patternedBody: true,
+                                          respond: { _, _, _ in .serve200 })
+        let server = try #require(maybe)
+        defer { server.stop() }
+        let reader = AVIOReader(url: URL(string: "http://127.0.0.1:\(server.port)/movie.ts")!)
+        defer { reader.markClosed(); reader.close() }
+        try reader.open()
+
+        #expect(reader.originIgnoresRange)
+        #expect(!reader.isSeekable, "the pb must be non-seekable so FFmpeg never seeks a source that cannot")
+        #expect(reader.seek(offset: 0, whence: Self.avseekSize) == total,
+                "the Content-Length still answers AVSEEK_SIZE, which an MPEG-TS duration estimate needs")
+
+        let result = drain(reader, total: total)
+        #expect(result.read == total, "read \(result.read / Int64(mb)) MB of \(total / Int64(mb)) MB")
+        #expect(result.firstBadOffset == nil, "bytes differ from the origin's at \(result.firstBadOffset ?? -1)")
+        let tailBuf = UnsafeMutablePointer<UInt8>.allocate(capacity: 4096)
+        defer { tailBuf.deallocate() }
+        #expect(reader.read(into: tailBuf, size: 4096) == FFmpegErr.eof, "a body read to its end is EOF")
+
+        #expect(reader.streamPeakBufferBytesForTesting <= 64 * mb + 8 * mb,
+                "the streaming buffer held \(reader.streamPeakBufferBytesForTesting / mb) MB of a \(total / Int64(mb)) MB body")
+
+        // One unranged GET carried the whole body. Everything else is the open's own: the bounded
+        // range that was answered with a 200, the one byte confirmation, the suffix tail prefetch.
+        #expect(server.rangeHeaderPresence.filter { !$0 }.count == 1)
+        let tail = total - Int64(AVIOReader.tailPrefetchBytes)
+        let strays = server.requestLog.enumerated().filter { index, request in
+            server.rangeHeaderPresence[index] && request.start > 1 && request.start != tail
+        }
+        #expect(strays.isEmpty, "ranged requests past the open: \(strays.map(\.element))")
+    }
+
+    @Test("an origin that honours Range keeps the seekable path and its range refills",
+          .timeLimit(.minutes(2)))
+    func honouringOriginIsUnaffected() throws {
+        let total = Int64(40 * mb)
+        let server = try #require(ThrottledOriginServer(totalSize: total, throttleUs: 500))
+        defer { server.stop() }
+        let reader = AVIOReader(url: URL(string: "http://127.0.0.1:\(server.port)/movie.bin")!)
+        defer { reader.markClosed(); reader.close() }
+        try reader.open()
+
+        #expect(!reader.originIgnoresRange)
+        #expect(reader.isSeekable)
+        #expect(reader.seek(offset: 0, whence: Self.avseekSize) == total)
+
+        let chunk = 256 * 1024
+        let buf = UnsafeMutablePointer<UInt8>.allocate(capacity: chunk)
+        defer { buf.deallocate() }
+        var read: Int64 = 0
+        while read < 36 * Int64(mb) {
+            let n = reader.read(into: buf, size: Int32(chunk))
+            #expect(n > 0, "read failed at \(read)")
+            if n <= 0 { break }
+            read += Int64(n)
+        }
+        #expect(read >= 36 * Int64(mb))
+        #expect(server.rangeHeaderPresence.allSatisfy { $0 }, "a ranged source asked for an unranged GET")
+        #expect(server.requestedRanges.contains { $0.start == 32 * Int64(mb) },
+                "the refill at the 32 MB boundary never asked for its range")
+        #expect(!server.requestLog.contains { $0.start == 1 && $0.end == 1 },
+                "an honoured range needs no confirmation")
+    }
+
+    @Test("a 200 on a cache miss at the open does not take the seekable path away",
+          .timeLimit(.minutes(2)))
+    func cacheMissAtTheOpenIsConfirmedAway() throws {
+        let total = Int64(40 * mb)
+        let once = FirstClaim()
+        let respond: @Sendable (Int, Int64, String) -> ThrottledOriginServer.Directive = { _, offset, _ in
+            offset == 0 && once.take() ? .serve200 : .serve206
+        }
+        let maybe = ThrottledOriginServer(totalSize: total, throttleUs: 500, respond: respond)
+        let server = try #require(maybe)
+        defer { server.stop() }
+        let reader = AVIOReader(url: URL(string: "http://127.0.0.1:\(server.port)/movie.bin")!)
+        defer { reader.markClosed(); reader.close() }
+        try reader.open()
+
+        #expect(!reader.originIgnoresRange)
+        #expect(reader.isSeekable)
+        #expect(reader.resolvedByteSize == total)
+        #expect(server.requestLog.contains { $0.start == 1 && $0.end == 1 },
+                "the 200 was never confirmed with a one byte range")
+        let buf = UnsafeMutablePointer<UInt8>.allocate(capacity: 64 * 1024)
+        defer { buf.deallocate() }
+        #expect(reader.read(into: buf, size: 64 * 1024) > 0)
+    }
+
+    @Test("a small file answered with a 200 that covers it stays sized and seekable",
+          .timeLimit(.minutes(1)))
+    func smallWholeFileStaysSeekable() throws {
+        let total = Int64(4 * mb)
+        let maybe = ThrottledOriginServer(totalSize: total, throttleUs: 0, patternedBody: true,
+                                          respond: { _, _, _ in .serve200 })
+        let server = try #require(maybe)
+        defer { server.stop() }
+        let reader = AVIOReader(url: URL(string: "http://127.0.0.1:\(server.port)/small.mp4")!)
+        defer { reader.markClosed(); reader.close() }
+        try reader.open()
+
+        #expect(!reader.originIgnoresRange)
+        #expect(reader.isSeekable)
+        #expect(reader.resolvedByteSize == total)
+        #expect(!server.requestLog.contains { $0.start == 1 && $0.end == 1 },
+                "a whole small file needs no confirmation")
+        let buf = UnsafeMutablePointer<UInt8>.allocate(capacity: 4096)
+        defer { buf.deallocate() }
+        #expect(reader.read(into: buf, size: 4096) == 4096)
+        #expect(Array(UnsafeBufferPointer(start: buf, count: 4096)) == expected(at: 0, count: 4096))
+    }
+}
diff --git a/Tests/AetherEngineTests/ThrottledOriginServer.swift b/Tests/AetherEngineTests/ThrottledOriginServer.swift
index f83288609..8706d1d49 100644
--- a/Tests/AetherEngineTests/ThrottledOriginServer.swift
+++ b/Tests/AetherEngineTests/ThrottledOriginServer.swift
@@ -33,6 +33,9 @@ final class ThrottledOriginServer: @unchecked Sendable {
         /// Audit DMX-5: a 206 that starts `start` rather than where it was asked, the way an edge
         /// that aligns ranges to its own chunk boundary answers. The body is that range's.
         case serve206From(start: Int64)
+        /// Audit DMX-101: a server that cannot address bytes. Whatever range was asked for, the
+        /// answer is a 200 with the whole source from byte 0 and its full Content-Length.
+        case serve200
     }
 
     let port: UInt16
@@ -314,9 +317,13 @@ final class ThrottledOriginServer: @unchecked Sendable {
 
         var silentAfter: Int64? = nil
         var dropAfter: Int64? = nil
+        var answersWholeSource = false
         switch respond(requestIndex, offset, path) {
         case .serve206:
             break
+        case .serve200:
+            answersWholeSource = true
+            offset = 0
         case .serve206From(let start):
             offset = max(0, min(start, totalSize - 1))
         case .serveThenGoSilent(let afterBytes):
@@ -348,15 +355,19 @@ final class ThrottledOriginServer: @unchecked Sendable {
             pendingDelay -= slice
         }
 
-        let last = (ignoreRangeEnd ? nil : rangeEnd) ?? (totalSize - 1)
+        let last = answersWholeSource ? totalSize - 1 : (ignoreRangeEnd ? nil : rangeEnd) ?? (totalSize - 1)
         let remaining = last - offset + 1
         // Keep-alive, not close: a bounded range that tears the socket down would make every
         // refill a fresh connection and would hide exactly the pooling question under test.
-        let header = "HTTP/1.1 206 Partial Content\r\n"
-            + "Content-Range: bytes \(offset)-\(last)/\(totalSize)\r\n"
-            + "Content-Length: \(remaining)\r\n"
-            + "Accept-Ranges: bytes\r\n"
-            + "Connection: keep-alive\r\n\r\n"
+        let header = answersWholeSource
+            ? "HTTP/1.1 200 OK\r\n"
+                + "Content-Length: \(remaining)\r\n"
+                + "Connection: keep-alive\r\n\r\n"
+            : "HTTP/1.1 206 Partial Content\r\n"
+                + "Content-Range: bytes \(offset)-\(last)/\(totalSize)\r\n"
+                + "Content-Length: \(remaining)\r\n"
+                + "Accept-Ranges: bytes\r\n"
+                + "Connection: keep-alive\r\n\r\n"
         guard writeFully(fd, Array(header.utf8)) else { return false }
 
         let chunk = [UInt8](repeating: 0x55, count: chunkBytes)
diff --git a/docs/api.md b/docs/api.md
index 0156678a0..97bec5b7a 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -978,7 +978,7 @@ All flags default to safe values; the table is the full set. Depth for the media
 | `deinterlaceFieldRate` | `.field` | A `DeinterlaceFieldRate`: the hardware deinterlacer emits one frame per field (25i to 50p) or per frame. The software fallback is always frame rate, because doubling a CPU bwdif is the wrong trade and a fallback should not change cost class. |
 | `probesize`, `maxAnalyzeDuration` | nil | Caller-bounded open-time probe budget (defaults 50 MB / 60 s). They fail **open**: an over-tight budget loads with late-resolving tracks silently missing rather than throwing, so validate track presence if you tighten them. Do not pass `0` for `maxAnalyzeDuration`; FFmpeg maps it to a shorter heuristic. |
 | `forwardBufferSegments` | nil (10, about 40 s) | How far the producer may race ahead and how much the cache keeps resident. Clamped to 4...2700; past the historical 150 the real bound is the session's disk budget, so a "buffer without limit" option can pass `Int.max`. Ignored on `nativeRemoteHLS`. Native HLS retention is readable as `$residentRanges` (see Time). Software VOD uses the same forward-window and volume-budget policy for compressed packet read-ahead; its continuous selected A/V frontier is `bufferedPosition`, not native `residentRanges`. |
-| `sequentialOrigin` | false | Declare an origin that fabricates range answers: one long-lived unranged GET, no ranged probes, non-seekable pb. **Seeking is unavailable**; re-request the archive at a shifted start instead. A URL source the reader finds forward-only by itself (`Range` ignored and no length, so it can only stream front to back) is served this way without the declaration when its container states a duration; `loadedOptions` then reads `true` with that duration declared, and without a duration it stays on the software path. An AirPlay hop on such a session swaps the item onto the LAN address instead of reopening the source, since a reopen could only start again from byte 0. |
+| `sequentialOrigin` | false | Declare an origin that fabricates range answers: one long-lived unranged GET, no ranged probes, non-seekable pb. **Seeking is unavailable**; re-request the archive at a shifted start instead. A URL source the reader finds forward-only by itself (`Range` ignored, so it can only stream front to back; the open confirms a 200 answer with a one byte range, because some CDNs answer a cache miss that way) is served this way without the declaration when its container states a duration, which a stated `Content-Length` lets an MPEG-TS source estimate; `loadedOptions` then reads `true` with that duration declared, and without a duration it stays on the software path. An AirPlay hop on such a session swaps the item onto the LAN address instead of reopening the source, since a reopen could only start again from byte 0. |
 | `declaredDurationSeconds` | nil | Trusted duration, overriding the container's. Required alongside `sequentialOrigin` on VOD, where the tail read is gone. |
 | `maxConcurrentSourceRequests` | nil | Most requests the reader may have open against this origin at once, across every path it fetches on (pump ranges, detour blocks, size probes, tail prefetch, subtitle side reader). nil counts without capping and lowers the ceiling on its own after a 429/503/509. Set it when the provider states a limit; `1` also switches off the speculative parallel paths, which exist only to overlap with the pump. Counts **requests**, not TCP connections, because over HTTP/2 a session multiplexes every request onto one connection while the origin still counts each one (AE#377). It is also the only ceiling: several engines playing from one origin are bounded by this value and by what the origin refuses, not by a transport pool underneath it (AE#450). |
 | `heldSourceConnection` | false | Ask the source **once** and pull it, instead of ending the connection at the reader's window high water and asking again every 8 to 16 MB of drain (AE#377). For an origin that punishes repeated requests rather than concurrency: some CDNs refuse new requests for minutes at a stretch while serving an already open connection at full rate, and against one of those the request cadence is the defect, at any range size (measured at the reporting origin: 32 MB ranges raised to 256 MB, eight times fewer requests, the refusals unchanged). Where `maxConcurrentSourceRequests` bounds how many requests are in flight, this removes the second request. The read path is the engine's own HTTP/1.1 over a demand-driven stream task, so: **HTTP/1.1 only** (no ALPN, an HTTP/2-only origin is out of scope), the **system proxy configuration does not apply**, and TLS is the OS's through the same host trust decision as every other engine session but has not been exercised against a self-signed origin. A viewer who pauses ends the connection after five seconds and resuming costs one request at the frontier, because a held flow nobody reads is the process-wide Network.framework starvation of AE#310. Applies to the playback reader; the subtitle and enrichment side readers keep the default transport, since they park for minutes at a time. **Names the session**: the transport is chosen at open, so a reload that changes it is refused. |

From 86f4847a7ed016cc3fc57fcdf37f906a5257a163 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 08:46:24 +0200
Subject: [PATCH 188/359] fix(demuxer): close the disc reader the demuxer built
 for a remote disc image (audit NET-110, DMX-110)

openHTTP built an HTTPDiscIOReader for a remote .iso/.img/.udf and kept no reference to it: the
disc adapter's ConcatIOReader.close() is a no-op and the bridge does not own its reader, so its
URLSession and pooled keep-alive socket outlived every open (1000 opens measured as 1020 open
sockets). The demuxer now owns that reader and closes it in close() and on both throw paths
(wrap, openWithProvider), and a throwing wrap puts the adopted prewarm back.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 Sources/AetherEngine/Demuxer/Demuxer.swift    |  42 ++++-
 .../RemoteDiscSessionReleaseTests.swift       | 164 ++++++++++++++++++
 .../Support/KeepAliveRangeOrigin.swift        | 146 ++++++++++++++++
 3 files changed, 349 insertions(+), 3 deletions(-)
 create mode 100644 Tests/AetherEngineTests/RemoteDiscSessionReleaseTests.swift
 create mode 100644 Tests/AetherEngineTests/Support/KeepAliveRangeOrigin.swift

diff --git a/Sources/AetherEngine/Demuxer/Demuxer.swift b/Sources/AetherEngine/Demuxer/Demuxer.swift
index 867bbb73c..7b592afc2 100644
--- a/Sources/AetherEngine/Demuxer/Demuxer.swift
+++ b/Sources/AetherEngine/Demuxer/Demuxer.swift
@@ -244,6 +244,27 @@ public final class Demuxer: @unchecked Sendable {
         }
     }
 
+    /// Audit NET-110: the disc reader `openHTTP` builds for a remote disc image. The disc adapter's
+    /// `ConcatIOReader.close()` is a no-op and the bridge does not own its reader, so this is the only
+    /// owner left to end the reader's `URLSession`. Guarded by `providerLock`.
+    private var _ownedSourceReader: IOReader?
+
+    private func adoptOwnedSourceReader(_ reader: IOReader) {
+        providerLock.lock()
+        let previous = _ownedSourceReader
+        _ownedSourceReader = reader
+        providerLock.unlock()
+        previous?.close()
+    }
+
+    private func releaseOwnedSourceReader() {
+        providerLock.lock()
+        let reader = _ownedSourceReader
+        _ownedSourceReader = nil
+        providerLock.unlock()
+        reader?.close()
+    }
+
     /// Audit HLS-2: `markClosed()` before the provider exists used to be a no-op, so a teardown
     /// that raced an in-flight open let it finish its connect and probe.
     private let closeRequestLock = NSLock()
@@ -600,15 +621,29 @@ public final class Demuxer: @unchecked Sendable {
         if !isLive, Self.isDiscImageURL(url) {
             let warm = HTTPDiscIOReader.takePrewarm(for: url, extraHeaders: extraHeaders)
             if let discReader = HTTPDiscIOReader(url: url, extraHeaders: extraHeaders, prewarmed: warm) {
-                if let discInfo = try DiscReader.wrap(discReader, selectTitleID: selectTitleID, cacheKey: url.absoluteString) {
+                adoptOwnedSourceReader(discReader)
+                let discInfo: DiscInfo?
+                do {
+                    discInfo = try DiscReader.wrap(discReader, selectTitleID: selectTitleID, cacheKey: url.absoluteString)
+                } catch {
+                    releaseOwnedSourceReader()
+                    if let warm { SourcePrewarmStore.shared.store(warm, for: url) }
+                    throw error
+                }
+                if let discInfo {
                     adoptDiscInfo(discInfo)
                     auditSource = nil
                     let bridge = CustomIOReaderBridge(reader: discInfo.reader)
                     let inputFormat = av_find_input_format(discInfo.formatHint)
-                    try openWithProvider(bridge, inputFormat: inputFormat, isLive: false)
+                    do {
+                        try openWithProvider(bridge, inputFormat: inputFormat, isLive: false)
+                    } catch {
+                        releaseOwnedSourceReader()
+                        throw error
+                    }
                     return
                 }
-                discReader.close()
+                releaseOwnedSourceReader()
             }
             // Not a disc: hand the warm back so the streaming reader below adopts it (#647).
             if let warm { SourcePrewarmStore.shared.store(warm, for: url) }
@@ -2370,6 +2405,7 @@ public final class Demuxer: @unchecked Sendable {
 
         avioProvider?.close()
         avioProvider = nil
+        releaseOwnedSourceReader()
     }
 
     deinit {
diff --git a/Tests/AetherEngineTests/RemoteDiscSessionReleaseTests.swift b/Tests/AetherEngineTests/RemoteDiscSessionReleaseTests.swift
new file mode 100644
index 000000000..3bdfe4f75
--- /dev/null
+++ b/Tests/AetherEngineTests/RemoteDiscSessionReleaseTests.swift
@@ -0,0 +1,164 @@
+import Testing
+import Foundation
+@testable import AetherEngine
+
+/// Audit NET-110 / DMX-110: the Demuxer builds the `HTTPDiscIOReader` for a remote disc image
+/// itself, so it is the only party that can end that reader's `URLSession`. The disc adapter's
+/// `ConcatIOReader.close()` is deliberately a no-op and the bridge does not own its reader, so a
+/// demuxer that forgot the reader left one uninvalidated session (and its pooled keep-alive
+/// socket) behind per open: 1000 opens measured as 1020 open sockets.
+///
+/// The origin counts sockets that are still open, which is the one place the leak shows.
+/// `.serialized`: the warm case goes through the process-wide prewarm store.
+@Suite("Remote disc image sessions are released (audit NET-110)", .serialized)
+struct RemoteDiscSessionReleaseTests {
+
+    /// 0.5 s of 64x64 MPEG-2 video in an MPEG-PS pack stream (ffmpeg `-f vob`), 4096 bytes: the
+    /// smallest title the DVD adapter can hand to `mpegps` and have it open.
+    private static let vob = Data(base64Encoded: """
+        AAABukQABAAEAYZmz/gAAAG7AAnDM2cAIf/g4OYAAAHgB92AwQ4xAAO3dREAA1+REGDm/wAAAbMEAEAS///gEAAAAbUUigAB
+        AAIAAAG4AAgAQAAAAQAAD//4AAABtY//80GAAAABARv4ffSQDMAzAoAPgKJAqBVIxGVtiSWkxCMangd7bXiwAvAC8AeABAAP
+        CaAPwB6TQMEwMCEIQ3JoFSb9xhCIRX+JYaW3bPttulPQhH+vvoBmAZgVAH4FUgVAqkanq2xIKQYhGMRgO9/4SANQQQEyYWMK
+        JYaTWxTkhAzd08ez5Ro+AKAgAfgg/jgGIDAAtAdgB8AaAFw1IDElLIZNALUlDCYTDEDcGFjQ3uSlBHe/LEIAbExGAKeBnjs+
+        RgpfEk68OTAQAKwAwIQYUGIAGAA6+KQhG5YCYhBpfyM2GlhpSSy0j0pT0/r/e9TfPr9HACsAJQBSAYlhhZNAHoBqE8vjAwhh
+        pCDMczFExKEZnHXqggAUgCUAcgBaQwB+QwB2AxLATpQAVAYQWwGCYSwG43EwM2xRW4xDjMts9/pQEH9kAQgi/0ADcEn/MBiC
+        b/5eGJgA3AqVwLsG4c2Rw77Efe+nXz6/m4ALwAsAFgBqGBgYTQB0AZdHwbgLAUDAxOclEgsMQgtHUfvfJggAWACgAdACMmAD
+        8mADsBATADVCMBTFcm5ywwlgNxvJgbviwz8Yh+V9+2vYAOwBsAxAGxNwYBXYJzlFoflFjxn+3dB332+EfX06/NIFQKEwBiTC
+        yYTSsWUXmSjmkXfH75e69fcAQPyAQAMADUEADIAZk0BMTQwvgJiaWGlgFwDv/F4CoDrJCMkvFFIAKwzdCAKlDEDEr2JSUf36
+        QGgDRAA4DU8ML6QwmsM3JKBjvvzcE5uePvcAMgQPwSGCB+QAZAUQAhAdIIQCEAfDUAVDQxRCArgKjCUGlFHhiQChJLKWg7o6
+        20AAAAECG+qCB8cAE5NAMQBWGACorllAUAHBRQaTUd9iaAnAdhiA3Ftg3lFoDAKJKQGJ5SC0JLIeWj66t6IED8ghk0CoIH6w
+        AjSTQ0sNTgBuAZhmSWnp+KJgFSwwMK3T/xhQYhBRSDkIRtla87emAMQRABgSP/QAZXw4IAIgIn94JABIJn/V/P759fQb59fp
+        QAxBEAGBI/9ABlfrwIAIgIn94JABIJn/V/qm+fX0G+fX8igDEEQAYEj/0AGV+ZggAiAif3gkAEgmf9X8/qAQPpwAmJgAYgBE
+        AnIbFIAYgDYoNAMQKBqWwFiYV+A7JnSBgssYGkLf4pHRkkMomdKW1feBIZCJgDEmBpCIYYUTSYTSkhgaGBqMWUGlF5klFoTu
+        hKE7/JR83yvfpQAxBEAGBI/9ABlfrwIAIgIn94JABIJn/UAAAAEDG/qAIH5oIf7AAhBH/qAHoJf+pNvM2UED5IATAVAHwASg
+        AjTxoFABqTAwsM7IxKJoCYmBgFCaTGJaU9kYmBpL6CtwG4zOM/tV6QAz3BCAGVwEpgCq+IBABD+BC/vXgRACTQR/+r+f3z6+
+        g3z6/SgBijghADK4CUzgPL9cBABD3BC/vVwRACTOCN/1f6pvn19Bvn1/I4AxSgEIAYJQAlNwDy/NAQAQ1AAjdQIYBJ6gRf+r
+        +f3z6+g3OBA+xAE4FABMCABYAO0k3DSwDEmFgDwChTpw0mgIQwsr8agovYDBMAyTQkZkgYJQ3dOv0kAZ/cAsBI/9ABlfrwIA
+        IagARuoEMAkEz/qAAAABBBusAJwEoffRgRP9k35aDQBYANiGATgFwBkGgj/+gMCEkjle+lAGYAUADgA1ISSkAJgHQFC+tBDJ
+        hCDEFoTjnGbDUD0frFdvfFgDAAJyYGAUJqMAmDQ1JSM2JYZhv7q3+UcbfWAIA0mAgAYgVALigDEh8sMAdlpQkhkxCfiEgrlb
+        lpKcaXsS3ZC23a/bgGADgOiBW82A6DQB8XlEwChM5u5RSMYd2bkcVfPgwAZACwB2GFE0MAMAB4TQwNQgsotADoB0WUWhOdCU
+        JxXyUfL3yvr7sED8wED8TEIEIAcBiAKAC8BMX+nAFPDMh8OTsMS5gz+/JwBUCB+akhJIYCABCAKADEAwJoDAlb4h8M2DRo1Y
+        YnYYnYYv7/L1/RQAmASB186BEAKRfo4MAHIBeQgCYA1AThgI4AYFQ1BGTr5qTCGALyaEAB6AalIwBKQyGhGDulYdvagBOCAC
+        uA7AMhgDsBiAIQB4AwDAlLk1BDQpDOzpdJJytv7sALwBmAYABaQgDUhhoDECgAyDCFkflgIQ1GycWNJGR90jGO2/dOvzwBiA
+        5D4AUvcADkAMQEIA/JuShKQGBSMyCgwvu5vLLwzp45W2x2P/vouAC8AV44AbgD3Akf6gOwTf/L0gAsAHwAJgKl8ArQBVAZ0B
+        OQlA13XsleONv0EARggAnADMBAGAJgHYCcB2AwAYE0A1wangMAkNSBTlDALFhoZwMJSxeclPt3z8+AAAAQAAV//7gAAAAbWB
+        H/NBgAAAAQESgcgB5+6svDu2fIQjJCe5ZaISYoxz17Y5ZO2dKfyuWX4ghx36svj+2fpSnpCcxZaYGD/80/q2Y18hlwGzFmMe
+        rKyRIwICSRUSErdh7Djl7vuNP6N0czwUo47Cl/i9jdxq3JeT0+Hr7CsPzZWUphuxrfv+8PcdxCiI4dwg8vlb1EieFgdgGZh4
+        5R7OIbDHeDws7iVMa3zdCcwmJxPEiV9ZJzDAn/I2qBoAAAG6RAAEAAwBhmbP+AAAAeAHXYDACzEABWc9EQAFD1n/DgrqZRqj
+        /1jwhIw8suEdeFnMfl4XsbjkBKC0b6IhOJzGDs/6UJbhCfD+FtzGZQ7ncdj9soamPDx++WpYs8WEfgS3gAAAAQISjAjHB+3U
+        avnOrfYZzu6enwk8L/PJzc3GcYMQ6EaA0RarA0RZoyHCTHAmztx34HnZk5CCk+AWMzdBwhtvxpJ/26P9AaIsAAABAxKIZBhJ
+        748KUpfZnW+HYbmgFsBodVYGiLU0GP/+Bi//qPkdXFOQGYax3MXng77iFwDNQ+AAAAEEEymAU1hgDjAI4A1AHAYUWAOwB4GF
+        hhRZRYBiAgQkpKEJKLRwHYZuhKE75O5333cdAMQGBMwCHBoA0UTOAOQQgDCYAxDEEoB2AXAOyG5CAdAIQHReGFpwYWGjQKgM
+        E9BQCdGGAKAKgBsAZkKTiwxKeGJ+IWyMXy07krAOTz2AcEk6DQHYaTADQBMGAD8B2WA2AMgA/LKAQgVb8ANAEADrAMCwDUAv
+        SUxLJoYAmIQDvgO0gUITkMNQQg1BMQWQ0lI9TAHYDsAmARkSJmPD7d8yXOJCQ91qzP2xIdv1amwePw5XfGZxubvz8lH+8AmD
+        QHXT3G5D4YPHc8cyXc77fwFQ0m4N7slCsSRhrjj9nUMcknrXZTAKwGSTw6AMgBqQyyEANgB2Q8TUkzkwAuANS8QxqSuTCUA6
+        DeS8XuEDGGjTGeBCAILALy8APiEGpAoQwDVgEyAE+cEIAksB25MDAHY1HQlIDZPGjCYWS3YkO8GlAOi+MJvbBn4aNJpYFgwr
+        EwBtw1PT22GANynyP+vbIdKN4mFcmAFpDAD8m4AyANADQB0TADUAzAHpN34DoBAAmGkMAPwHaQMYBunAICiEA3JoYTCWTQ0l
+        hhRMK5ZaEepgDoB0ATgIiLE3nB0rO6MFPj2WrZxqca7KwDnsiXx/DkwBqUAxyMxK/X2ZW+UBMx3Y7/N2x0QiYTOUhaRfGOpe
+        Pc85z2HK2QmAAAABAACX//uAAAABtYEf80GAAAABARKsH0AGokYDn//HAw//wMoAMuqxFTiIDR//E8G0AGAAAAECEnTZOgAA
+        AQMSjwP//89gA/qauVVYGiLXQYv/4AAAAQQTKYBSSg7CCJAGoA2DAwsAdgD4ospBZRYBiAmKSUnDUJRwKhmShO6vknffNx0A
+        nAdEwANwMgDbgKAQf7WAQEwBCjAhf8AFwDEmjSEA6AMwKBqCUWCEAOWTXIYCYllBgCcmBDkIBigBAAhATW5SS+UWXiYhCMXy
+        al+VnJZ4xYCQ9mHqiwHYaGAGgCAmAF4DsNxMAQAB+WGAGpDX+AYAJgHQAeFgIQC9KEBJDKATAUAd8B2khEwEL/kNQBQNQTMk
+        mpKKTUwNATgJBBFsBgCH/yTAFenCT1sc65ldSmOZXwfjYAySAmSksaS8yjBQVFkMsDPL5z5icxA4iymAVkJJKRPgDAAak3kI
+        AcADsm4N5M5CALgDUNwbi+UBjlAOg1IGcW+GdDDRrqZ4oAPA0AvLwA8JgaWBQhgGYIQBRQDHI/AD4sBOSyYGAVcaGdPJha2J
+        ieTd+VwLZJLiGGAOi+jBr5AYApyQ1PGBgZiYA24aWktLIZGJpSiStCnSh4MKAwA3IeAYk3AGQBoAgAoGAIQDUAdk1BfAdAJg
+        EA0hgB+BUslbll4A0DCYA3DSiYNJqcWGFEwrhpaMmpgYAmASiSJQDEEMAcmgKvWCCQEDzHBg//nXmSE4dzgqANUAMchAwZ+L
+        fCzIohFANsVvxozucLcDkAAAAQAA1//7gAAAAbWBH/NBgAAAAQESepB///m0AbQAAAECEnTZPgAAAQMSlgD6AXVWeBuaaeOi
+        PAAAAQQTKYQkEnB0GwBmAOCiiwB2APiiyiklJAMQECEoShHQlCQKhmShO+b7nfdXgEIDoMADXFgDbpAwCD/awCAmAGpWYBiA
+        XAMSaNJgDAA1AolAwN+AoWTRpDAYEtAYAnJgQNIQDEoBAAagJrQkosslFlgNshBLSGp36AkaeMf7AWPWziYNAqWGAIAEAYAP
+        wHZeJgBoAH4aUAhAq3/AMgEADoAPCwEIBelG3SQygEwFAHfAd8hEwEL/oNKIRaCFkk3hhSamAB+CH/34CoBcCH/yCQAGkj6d
+        /1rFnkc6GflBKAjrXn3J3cnnk+ANAA8SN6RuJLgfeSQ/iaBlsxLc8XZTCGk7iEwYAbQBgANSakmADYAdk0BvwwDABcAahoDf
+        FjOGEoB0GpJZLV0DGca+ZnkAB4WAXpwA+ISUgUJoBnwA6KAY5HYBgWAnJZMDAKvuUNAwWsYTCwM7krsjJJcTQwCiegDJwZ0h
+        o0NSEBhWJmDOGlpL7ZkYhlPt3WjN+lDxMDOGAFpDAD0m4AyANAEADooA1AMwB2TUJ4DABAAgGk0APwHZZKAunAIAwhANw0MJ
+        mSTUksMKJhXDS0b1MAD4EMAXQFAC8EMAcEj/1BG8yhQrE86fZKvt8O+cDkAa4BOglDCV1IaQTMBgDDtxjOLYcJgAAAG+AIn/
+        ////////////////////////////////////////////////////////////////////////////////////////////////
+        /////////////////////////////////////////////////////////////////////////////////////w==
+        """, options: .ignoreUnknownCharacters)!
+
+    private static func isoImage(vob: Data) -> Data {
+        let sector = ISO9660Fixture.sectorSize
+        var image = ISO9660Fixture.make(files: [
+            .init(name: "VTS_01_1.VOB", length: vob.count, content: [UInt8](vob.prefix(sector))),
+        ])
+        image.append(vob.dropFirst(sector))
+        return image
+    }
+
+    private func url(_ origin: KeepAliveRangeOrigin, _ name: String = "disc.iso") -> URL {
+        URL(string: "http://127.0.0.1:\(origin.port)/\(name)")!
+    }
+
+    private func drained(_ origin: KeepAliveRangeOrigin) async throws -> Bool {
+        try await waitFor(upTo: .seconds(10)) { origin.openConnectionCount == 0 }
+    }
+
+    @Test("a disc image that opens releases its session when the demuxer closes")
+    func openedDiscReleasesOnClose() async throws {
+        let origin = try #require(KeepAliveRangeOrigin(data: Self.isoImage(vob: Self.vob)))
+        defer { origin.stop() }
+
+        let demuxer = Demuxer()
+        try demuxer.open(url: url(origin))
+        #expect(demuxer.isDiscSource, "the fixture was not taken for a disc")
+        #expect(origin.openConnectionCount > 0, "the open never reached the origin")
+        demuxer.close()
+
+        #expect(try await drained(origin), "sockets left open: \(origin.openConnectionCount)")
+    }
+
+    @Test("a disc image whose open throws releases its session")
+    func failedOpenReleasesItsSession() async throws {
+        // A pack-start-code-only title: recognised as a disc, and mpegps then finds no stream.
+        let image = ISO9660Fixture.make(files: [.init(name: "VTS_01_1.VOB", length: 2048)])
+        let origin = try #require(KeepAliveRangeOrigin(data: image))
+        defer { origin.stop() }
+
+        for _ in 0..<3 {
+            let demuxer = Demuxer()
+            #expect(throws: (any Error).self) { try demuxer.open(url: url(origin)) }
+            demuxer.close()
+        }
+        #expect(origin.acceptedConnectionCount > 0, "the open never reached the origin")
+
+        #expect(try await drained(origin), "sockets left open: \(origin.openConnectionCount)")
+    }
+
+    /// The root directory's length, past the reader's extent cap: `wrap` throws `malformed` instead of
+    /// reporting "not a disc".
+    private static func unparseableImage() -> Data {
+        var image = ISO9660Fixture.make(files: [.init(name: "VTS_01_1.VOB", length: 2048)])
+        let lengthOffset = 16 * ISO9660Fixture.sectorSize + 156 + 10
+        image.replaceSubrange(lengthOffset..<(lengthOffset + 4), with: ISO9660Fixture.le32(16 * 1024 * 1024))
+        return image
+    }
+
+    @Test("a disc image whose structure cannot be parsed releases its session")
+    func throwingWrapReleasesItsSession() async throws {
+        let origin = try #require(KeepAliveRangeOrigin(data: Self.unparseableImage()))
+        defer { origin.stop() }
+
+        let demuxer = Demuxer()
+        #expect(throws: (any Error).self) { try demuxer.open(url: url(origin)) }
+        demuxer.close()
+
+        #expect(origin.acceptedConnectionCount > 0, "the open never reached the origin")
+        #expect(try await drained(origin), "sockets left open: \(origin.openConnectionCount)")
+    }
+
+    @Test("a disc image whose structure cannot be parsed hands the warm back")
+    func throwingWrapReturnsTheWarm() async throws {
+        let origin = try #require(KeepAliveRangeOrigin(data: Self.unparseableImage()))
+        defer { origin.stop() }
+        let source = url(origin, "corrupt.iso")
+        _ = await SourcePrewarmFetcher.warm(url: source, extraHeaders: [:], byteBudget: 1 << 20, into: .shared)
+        #expect(SourcePrewarmStore.shared.isWarm(for: source), "the warm was not taken")
+        defer { _ = SourcePrewarmStore.shared.take(for: source) }
+
+        let demuxer = Demuxer()
+        defer { demuxer.close() }
+        #expect(throws: (any Error).self) { try demuxer.open(url: source) }
+
+        #expect(SourcePrewarmStore.shared.isWarm(for: source),
+                "a throwing wrap dropped the warm instead of putting it back")
+    }
+}
diff --git a/Tests/AetherEngineTests/Support/KeepAliveRangeOrigin.swift b/Tests/AetherEngineTests/Support/KeepAliveRangeOrigin.swift
new file mode 100644
index 000000000..b06fbc4e5
--- /dev/null
+++ b/Tests/AetherEngineTests/Support/KeepAliveRangeOrigin.swift
@@ -0,0 +1,146 @@
+import Darwin
+import Foundation
+
+/// A loopback origin that serves one byte blob with Range support over keep-alive connections and
+/// counts the connections that are still open. A client that leaves its `URLSession` uninvalidated
+/// leaves its pooled socket here, which is the only place that leak is visible from outside: the
+/// session has no public liveness and the origin is the one party that sees the socket.
+final class KeepAliveRangeOrigin: @unchecked Sendable {
+    let port: UInt16
+    private let listenFD: Int32
+    private let data: Data
+    private let lock = NSLock()
+    private var connections: Set<Int32> = []
+    private var stopped = false
+    private var accepted = 0
+
+    init?(data: Data) {
+        self.data = data
+        let fd = socket(AF_INET, SOCK_STREAM, 0)
+        guard fd >= 0 else { return nil }
+        var one: Int32 = 1
+        setsockopt(fd, SOL_SOCKET, SO_REUSEADDR, &one, socklen_t(MemoryLayout<Int32>.size))
+        var address = sockaddr_in()
+        address.sin_family = sa_family_t(AF_INET)
+        address.sin_port = 0
+        address.sin_addr.s_addr = inet_addr("127.0.0.1")
+        let bound = withUnsafePointer(to: &address) {
+            $0.withMemoryRebound(to: sockaddr.self, capacity: 1) {
+                bind(fd, $0, socklen_t(MemoryLayout<sockaddr_in>.size))
+            }
+        }
+        guard bound == 0, listen(fd, 16) == 0 else {
+            close(fd)
+            return nil
+        }
+        var length = socklen_t(MemoryLayout<sockaddr_in>.size)
+        let named = withUnsafeMutablePointer(to: &address) {
+            $0.withMemoryRebound(to: sockaddr.self, capacity: 1) { getsockname(fd, $0, &length) }
+        }
+        guard named == 0 else {
+            close(fd)
+            return nil
+        }
+        listenFD = fd
+        port = UInt16(bigEndian: address.sin_port)
+        Thread.detachNewThread { [self] in acceptLoop() }
+    }
+
+    var openConnectionCount: Int { lock.withLock { connections.count } }
+    var acceptedConnectionCount: Int { lock.withLock { accepted } }
+
+    func stop() {
+        lock.lock()
+        let already = stopped
+        stopped = true
+        for fd in connections { shutdown(fd, SHUT_RDWR) }
+        lock.unlock()
+        guard !already else { return }
+        shutdown(listenFD, SHUT_RDWR)
+        close(listenFD)
+    }
+
+    private func acceptLoop() {
+        while true {
+            let fd = accept(listenFD, nil, nil)
+            if fd < 0 { return }
+            var one: Int32 = 1
+            setsockopt(fd, SOL_SOCKET, SO_NOSIGPIPE, &one, socklen_t(MemoryLayout<Int32>.size))
+            lock.lock()
+            if stopped {
+                lock.unlock()
+                shutdown(fd, SHUT_RDWR)
+                close(fd)
+                return
+            }
+            connections.insert(fd)
+            accepted += 1
+            lock.unlock()
+            Thread.detachNewThread { [self] in serve(fd) }
+        }
+    }
+
+    private func serve(_ fd: Int32) {
+        defer {
+            lock.lock()
+            connections.remove(fd)
+            close(fd)
+            lock.unlock()
+        }
+        while let head = readRequestHead(fd) {
+            var start = 0
+            var end = data.count - 1
+            if let range = Self.range(in: head) {
+                start = range.start
+                end = min(end, range.end ?? end)
+            }
+            guard start < data.count, end >= start else {
+                guard writeAll(fd, Data("HTTP/1.1 416 Range Not Satisfiable\r\nContent-Length: 0\r\n\r\n".utf8))
+                else { return }
+                continue
+            }
+            let header = "HTTP/1.1 206 Partial Content\r\n"
+                + "Content-Length: \(end - start + 1)\r\n"
+                + "Content-Range: bytes \(start)-\(end)/\(data.count)\r\n"
+                + "Accept-Ranges: bytes\r\nConnection: keep-alive\r\n\r\n"
+            guard writeAll(fd, Data(header.utf8)),
+                  writeAll(fd, data.subdata(in: start..<(end + 1))) else { return }
+        }
+    }
+
+    private static func range(in head: String) -> (start: Int, end: Int?)? {
+        guard let line = head.components(separatedBy: "\r\n")
+            .first(where: { $0.lowercased().hasPrefix("range:") }),
+              let equals = line.range(of: "bytes=") else { return nil }
+        let parts = line[equals.upperBound...].split(separator: "-", omittingEmptySubsequences: false)
+        guard parts.count == 2, let start = Int(parts[0].trimmingCharacters(in: .whitespaces)) else { return nil }
+        return (start, Int(parts[1].trimmingCharacters(in: .whitespaces)))
+    }
+
+    private func readRequestHead(_ fd: Int32) -> String? {
+        var collected = Data()
+        var buffer = [UInt8](repeating: 0, count: 4096)
+        let terminator = Data("\r\n\r\n".utf8)
+        while collected.range(of: terminator) == nil {
+            let count = recv(fd, &buffer, buffer.count, 0)
+            guard count > 0 else { return nil }
+            collected.append(contentsOf: buffer.prefix(count))
+            guard collected.count <= 64 * 1024 else { return nil }
+        }
+        return String(decoding: collected, as: UTF8.self)
+    }
+
+    private func writeAll(_ fd: Int32, _ bytes: Data) -> Bool {
+        bytes.withUnsafeBytes { raw in
+            guard let base = raw.baseAddress else { return true }
+            var sent = 0
+            while sent < raw.count {
+                let count = write(fd, base.advanced(by: sent), raw.count - sent)
+                if count < 0, errno == EINTR { continue }
+                guard count > 0 else { return false }
+                sent += count
+            }
+            return true
+        }
+    }
+}

From 8090ffc97652e66d9ec59e9e8a1cdfbb007fe45b Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 08:47:26 +0200
Subject: [PATCH 189/359] fix(live): every undecodable audio stream stays
 marked, not just the first (audit FEA-103)

The AE#641 mark held one stream index, so a channel with a second undecodable
audio track re-hung silently once the viewer picked it: the drop was refused
without a line and the cascade only skipped the one marked index.

The engine's mark, the HLSVideoEngine parameter and the cascade check are now a
Set<Int32>, a session-preserving reload keeps all of it and a host load clears
it. A repeat report for an already marked stream logs instead of returning
silently.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../AetherEngine+LiveAudioDrop.swift          | 20 +++++++-----
 .../AetherEngine/AetherEngine+Loading.swift   |  2 +-
 Sources/AetherEngine/AetherEngine.swift       | 12 ++++---
 .../Video/HLSVideoEngine+AudioRoute.swift     |  4 +--
 .../AetherEngine/Video/HLSVideoEngine.swift   | 15 ++++++---
 .../Issue641LiveUndecodableAudioTests.swift   | 31 ++++++++++++++++---
 6 files changed, 60 insertions(+), 24 deletions(-)

diff --git a/Sources/AetherEngine/AetherEngine+LiveAudioDrop.swift b/Sources/AetherEngine/AetherEngine+LiveAudioDrop.swift
index e70c17648..45a78f200 100644
--- a/Sources/AetherEngine/AetherEngine+LiveAudioDrop.swift
+++ b/Sources/AetherEngine/AetherEngine+LiveAudioDrop.swift
@@ -14,18 +14,24 @@ import Foundation
 /// tail, and `audioDelivery` reads `.droppedNoPipeline`, the fact a host ladder demotes on.
 extension AetherEngine {
 
-    /// What a load keeps of the undecodable stream: the session's own rebuilds keep it, which is
+    /// What a load keeps of the undecodable streams: the session's own rebuilds keep them, which is
     /// what keeps them video-only, and a host load is a new source and starts clean.
-    nonisolated static func undecodableAudioStreamIndexAcrossLoad(
-        _ current: Int32?, sessionPreservingReload: Bool
-    ) -> Int32? {
-        sessionPreservingReload ? current : nil
+    nonisolated static func undecodableAudioStreamIndicesAcrossLoad(
+        _ current: Set<Int32>, sessionPreservingReload: Bool
+    ) -> Set<Int32> {
+        sessionPreservingReload ? current : []
     }
 
     @MainActor
     func dropUndecodableLiveAudio(streamIndex: Int32, bridgeSummary: String) async {
-        guard undecodableLiveAudioStreamIndex == nil else { return }
-        undecodableLiveAudioStreamIndex = streamIndex
+        guard undecodableLiveAudioStreamIndices.insert(streamIndex).inserted else {
+            EngineLog.emit(
+                "[AetherEngine] AE#641 stream \(streamIndex) is already marked undecodable "
+                + "(\(bridgeSummary)); the session is already video-only for it",
+                category: .engine
+            )
+            return
+        }
         EngineLog.emit(
             "[AetherEngine] AE#641 the live audio bridge decoded nothing from stream \(streamIndex) "
             + "(\(bridgeSummary)); rebuilding the session video-only instead of serving an audio "
diff --git a/Sources/AetherEngine/AetherEngine+Loading.swift b/Sources/AetherEngine/AetherEngine+Loading.swift
index 8cd100ee4..483f90d11 100644
--- a/Sources/AetherEngine/AetherEngine+Loading.swift
+++ b/Sources/AetherEngine/AetherEngine+Loading.swift
@@ -826,7 +826,7 @@ extension AetherEngine {
             matchContentEnabled: matchContentEnabled,
             panelIsInHDRMode: panelIsInHDRMode,
             audioSourceStreamIndexOverride: audioSourceStreamIndex,
-            undecodableAudioStreamIndex: undecodableLiveAudioStreamIndex,
+            undecodableAudioStreamIndices: undecodableLiveAudioStreamIndices,
             audioBridgeMode: audioBridgeMode,
             isLiveSession: isLive,
             dvrWindowSeconds: dvrWindowSeconds,
diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index 096b78de3..e5af43ded 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -2424,9 +2424,11 @@ public final class AetherEngine: ObservableObject {
     /// until its teardown claims it (see `claimSoftwarePathTakeover`).
     var softwarePathRebuild: Task<Void, Error>?
     var softwarePathTakeoverArm: UInt64?
-    /// AE#641: the live audio stream whose bridge decoded nothing in this session. It outlives the
-    /// session's own rebuilds, which is what keeps them video-only, and a host load clears it.
-    var undecodableLiveAudioStreamIndex: Int32?
+    /// AE#641: the live audio streams whose bridge decoded nothing in this session. They outlive the
+    /// session's own rebuilds, which is what keeps them video-only, and a host load clears them. A set,
+    /// not a slot (audit FEA-103): a channel with two undecodable tracks would otherwise re-hang on the
+    /// second one, after the viewer's pick, with nothing surfaced.
+    var undecodableLiveAudioStreamIndices: Set<Int32> = []
     /// #65 final rung, storm shape: on a frozen live playlist each stage-2 reload replays the tail,
     /// re-stalls within seconds, and the fresh stall SUPERSEDES the ladder task before its
     /// post-reload rung can run, so the reload cycle alone would loop forever. This gate persists
@@ -3955,8 +3957,8 @@ public final class AetherEngine: ObservableObject {
         itemDeathReviveGate = ItemDeathReviveGate(maxAttempts: 3)
         stallReloadReviveGate = ItemDeathReviveGate(maxAttempts: 2)
         softwarePathEscalationBudget = SoftwarePathEscalation.Budget()
-        undecodableLiveAudioStreamIndex = Self.undecodableAudioStreamIndexAcrossLoad(
-            undecodableLiveAudioStreamIndex, sessionPreservingReload: sessionPreservingReloadInFlight)
+        undecodableLiveAudioStreamIndices = Self.undecodableAudioStreamIndicesAcrossLoad(
+            undecodableLiveAudioStreamIndices, sessionPreservingReload: sessionPreservingReloadInFlight)
         masterFallbackUsed = false
         nativeSubtitleReanchorTask?.cancel()
         nativeSubtitleReanchorTask = nil
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine+AudioRoute.swift b/Sources/AetherEngine/Video/HLSVideoEngine+AudioRoute.swift
index cff45e2a6..7b9aa310d 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine+AudioRoute.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine+AudioRoute.swift
@@ -190,8 +190,8 @@ extension HLSVideoEngine {
         }
         // AE#641: this session's bridge already decoded nothing from this stream, and a second
         // bridge would be handed the same bytes.
-        let knownUndecodable = sourceAudioStreamIndex >= 0
-            && undecodableAudioStreamIndex == sourceAudioStreamIndex
+        let knownUndecodable = Self.isKnownUndecodable(
+            undecodableAudioStreamIndices, sourceAudioStreamIndex: sourceAudioStreamIndex)
         if knownUndecodable {
             EngineLog.emit(
                 "[HLSVideoEngine] AE#641 audio stream \(sourceAudioStreamIndex) decoded nothing earlier "
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine.swift b/Sources/AetherEngine/Video/HLSVideoEngine.swift
index dc7dd78ba..2450fb695 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine.swift
@@ -77,9 +77,14 @@ public final class HLSVideoEngine: @unchecked Sendable {
     /// Caller-chosen audio stream index; nil falls back to `av_find_best_stream`. Enables
     /// host-driven track switching via `AetherEngine.selectAudioTrack(index:)` reload.
     private let audioSourceStreamIndexOverride: Int32?
-    /// AE#641: a source audio stream this session already found undecodable (its bridge decoded
-    /// nothing). When the pick lands on it again, the cascade goes straight to its video-only tail.
-    let undecodableAudioStreamIndex: Int32?
+    /// AE#641: the source audio streams this session already found undecodable (their bridge decoded
+    /// nothing). When the pick lands on one again, the cascade goes straight to its video-only tail.
+    let undecodableAudioStreamIndices: Set<Int32>
+
+    /// Whether the cascade has to skip the stream it is about to build a pipeline for.
+    nonisolated static func isKnownUndecodable(_ indices: Set<Int32>, sourceAudioStreamIndex: Int32) -> Bool {
+        sourceAudioStreamIndex >= 0 && indices.contains(sourceAudioStreamIndex)
+    }
 
     /// AE#443: whoever REPLACES one of these two mid-session owes the session the totals the outgoing
     /// instance held (`retireDemuxer` / `retireProducer` below). They carry the session's byte and
@@ -894,7 +899,7 @@ public final class HLSVideoEngine: @unchecked Sendable {
         matchContentEnabled: Bool = true,
         panelIsInHDRMode: Bool = false,
         audioSourceStreamIndexOverride: Int32? = nil,
-        undecodableAudioStreamIndex: Int32? = nil,
+        undecodableAudioStreamIndices: Set<Int32> = [],
         audioBridgeMode: AudioBridgeMode = .surroundCompat,
         isLiveSession: Bool = false,
         dvrWindowSeconds: Double? = nil,
@@ -939,7 +944,7 @@ public final class HLSVideoEngine: @unchecked Sendable {
         self.matchContentEnabled = matchContentEnabled
         self.panelIsInHDRMode = panelIsInHDRMode
         self.audioSourceStreamIndexOverride = audioSourceStreamIndexOverride
-        self.undecodableAudioStreamIndex = undecodableAudioStreamIndex
+        self.undecodableAudioStreamIndices = undecodableAudioStreamIndices
         self.audioBridgeMode = audioBridgeMode
         self.isLiveSession = isLiveSession
         self.dvrWindowSeconds = dvrWindowSeconds
diff --git a/Tests/AetherEngineTests/Issue641LiveUndecodableAudioTests.swift b/Tests/AetherEngineTests/Issue641LiveUndecodableAudioTests.swift
index 8ae75d1b7..2cbecadc7 100644
--- a/Tests/AetherEngineTests/Issue641LiveUndecodableAudioTests.swift
+++ b/Tests/AetherEngineTests/Issue641LiveUndecodableAudioTests.swift
@@ -101,11 +101,34 @@ struct Issue641LiveUndecodableAudioTests {
         #expect(calls.all.isEmpty)
     }
 
-    @Test("the session's own rebuild keeps the stream marked, a host load starts clean")
+    @Test("the session's own rebuild keeps every marked stream, a host load starts clean")
     func markSurvivesOnlyTheSessionsOwnRebuild() {
-        #expect(AetherEngine.undecodableAudioStreamIndexAcrossLoad(1, sessionPreservingReload: true) == 1)
-        #expect(AetherEngine.undecodableAudioStreamIndexAcrossLoad(1, sessionPreservingReload: false) == nil)
-        #expect(AetherEngine.undecodableAudioStreamIndexAcrossLoad(nil, sessionPreservingReload: true) == nil)
+        #expect(AetherEngine.undecodableAudioStreamIndicesAcrossLoad([1, 2], sessionPreservingReload: true) == [1, 2])
+        #expect(AetherEngine.undecodableAudioStreamIndicesAcrossLoad([1, 2], sessionPreservingReload: false).isEmpty)
+        #expect(AetherEngine.undecodableAudioStreamIndicesAcrossLoad([], sessionPreservingReload: true).isEmpty)
+    }
+
+    /// Audit FEA-103: the mark was a single slot, so a second undecodable stream was refused silently
+    /// and its pick left the session serving a bridge that never carries a sample.
+    @Test("a second undecodable stream is marked as well, and a repeat report changes nothing")
+    @MainActor
+    func secondUndecodableStreamIsMarked() async throws {
+        let engine = try AetherEngine()
+        await engine.dropUndecodableLiveAudio(streamIndex: 1, bridgeSummary: "fed=64 decoded=0")
+        #expect(engine.undecodableLiveAudioStreamIndices == [1])
+        await engine.dropUndecodableLiveAudio(streamIndex: 2, bridgeSummary: "fed=64 decoded=0")
+        #expect(engine.undecodableLiveAudioStreamIndices == [1, 2])
+        await engine.dropUndecodableLiveAudio(streamIndex: 2, bridgeSummary: "fed=128 decoded=0")
+        #expect(engine.undecodableLiveAudioStreamIndices == [1, 2])
+    }
+
+    @Test("the cascade skips every marked stream and only those")
+    func cascadeSkipsEveryMarkedStream() {
+        #expect(HLSVideoEngine.isKnownUndecodable([1, 2], sourceAudioStreamIndex: 1))
+        #expect(HLSVideoEngine.isKnownUndecodable([1, 2], sourceAudioStreamIndex: 2))
+        #expect(!HLSVideoEngine.isKnownUndecodable([1, 2], sourceAudioStreamIndex: 3))
+        #expect(!HLSVideoEngine.isKnownUndecodable([], sourceAudioStreamIndex: 1))
+        #expect(!HLSVideoEngine.isKnownUndecodable([0], sourceAudioStreamIndex: -1))
     }
 
     // MARK: - Where the verdict goes

From 1be57754610f030c6e964ce35b9aac68088feeef Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 08:51:30 +0200
Subject: [PATCH 190/359] fix(dovitest): the probe walks the source's own
 framing and fails loudly (audit BIT-106, OPS-107)

doviConvertProbe resolves the NAL framing once from the extradata and uses
it for the enhancement-layer probe, the converter and the writer, so an
Annex-B source (a disc remux) is no longer reported as converted while no
RPU is touched and written as one bogus NAL per packet. Annex-B extradata
is written as it is. Writes go through FileHandle.write(contentsOf:) and a
read error is thrown instead of ending the run as EOF. The output is opened
O_NOFOLLOW.

aetherctl keeps one private per-user debug directory (aetherctl-<uid>,
0700, lstat-checked, mkdtemp fallback) so the next run overwrites a
multi-gigabyte dovitest output instead of leaving another, and dovitest
takes --out.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../Video/DoviRpuConverter+Probe.swift        | 107 ++++++++++--------
 Sources/aetherctl/DebugOutput.swift           |  30 ++++-
 Sources/aetherctl/DoviTest.swift              |  10 +-
 Sources/aetherctl/main.swift                  |  12 +-
 .../DoviConvertProbeTests.swift               |  70 ++++++++++++
 .../DoviRpuConverterTests.swift               |  47 ++++++++
 docs/cli.md                                   |  10 +-
 7 files changed, 217 insertions(+), 69 deletions(-)
 create mode 100644 Tests/AetherEngineTests/DoviConvertProbeTests.swift

diff --git a/Sources/AetherEngine/Video/DoviRpuConverter+Probe.swift b/Sources/AetherEngine/Video/DoviRpuConverter+Probe.swift
index fa4da7a19..c724255af 100644
--- a/Sources/AetherEngine/Video/DoviRpuConverter+Probe.swift
+++ b/Sources/AetherEngine/Video/DoviRpuConverter+Probe.swift
@@ -40,7 +40,38 @@ extension AetherEngine {
 
     // MARK: - Dovi convert probe (aetherctl dovitest)
 
-    /// Walk every HEVC video packet, run `convertPacketToProfile81`, and write Annex-B output (AVCC length prefix replaced by `00 00 00 01`) for validation with `dovi_tool extract-rpu`. False returns are counted as failures but still emitted.
+    private nonisolated static let doviProbeStartCode: [UInt8] = [0x00, 0x00, 0x00, 0x01]
+
+    /// The head of the probe's output: the source's VPS/SPS/PPS, so `dovi_tool`'s parser can walk the stream. hvcC keeps them out of band and they are re-emitted start-coded; Annex-B extradata already is start-coded and is written as it is.
+    nonisolated static func doviProbeParameterSets(
+        extradata: UnsafePointer<UInt8>?, size: Int, framing: VideoNALFraming
+    ) -> Data {
+        guard let extradata, size > 0 else { return Data() }
+        switch framing {
+        case .annexB:
+            return Data(bytes: extradata, count: size)
+        case .lengthPrefixed:
+            var out = Data()
+            for nal in parseHVCCParameterSets(extradata, size) {
+                out.append(contentsOf: doviProbeStartCode)
+                out.append(contentsOf: nal)
+            }
+            return out
+        }
+    }
+
+    /// One packet as Annex B: every NAL behind a four-byte start code, whichever framing the packet arrived in.
+    nonisolated static func doviProbeAnnexB(_ packet: UnsafePointer<AVPacket>, framing: VideoNALFraming) -> Data {
+        guard let data = packet.pointee.data, packet.pointee.size > 0 else { return Data() }
+        var out = Data()
+        A53SEIParser.forEachNAL(data, Int(packet.pointee.size), framing) { nal, len in
+            out.append(contentsOf: doviProbeStartCode)
+            out.append(nal, count: len)
+        }
+        return out
+    }
+
+    /// Walk every HEVC video packet, run `convertPacketToProfile81`, and write the result as Annex B for validation with `dovi_tool extract-rpu`. The source's own NAL framing is resolved once from its extradata and used for the converter, the enhancement-layer probe and the writer alike, so an Annex-B source (a disc remux) is walked as what it is. False returns are counted as failures but still emitted. A read or write error ends the run by throwing rather than reporting the part that was done.
     public nonisolated static func doviConvertProbe(
         url: URL,
         outputPath: String,
@@ -59,65 +90,43 @@ extension AetherEngine {
             )
         }
 
-        FileManager.default.createFile(atPath: outputPath, contents: nil)
-        guard let handle = FileHandle(forWritingAtPath: outputPath) else {
-            throw AetherEngineError.noVideoStream
-        }
+        // O_NOFOLLOW: the output name may sit in a directory other users can write to.
+        let fd = open(outputPath, O_WRONLY | O_CREAT | O_TRUNC | O_NOFOLLOW, 0o600)
+        guard fd >= 0 else { throw POSIXError(POSIXErrorCode(rawValue: errno) ?? .EIO) }
+        let handle = FileHandle(fileDescriptor: fd, closeOnDealloc: true)
         defer { try? handle.close() }
 
-        let startCode: [UInt8] = [0x00, 0x00, 0x00, 0x01]
-
-        // MP4 hvcC keeps VPS/SPS/PPS out-of-band; emit them once as Annex-B so dovi_tool's parser can walk the stream.
-        if let cp = stream.pointee.codecpar,
-           let ed = cp.pointee.extradata, cp.pointee.extradata_size > 0 {
-            let edSize = Int(cp.pointee.extradata_size)
-            for nal in parseHVCCParameterSets(ed, edSize) {
-                handle.write(Data(startCode))
-                handle.write(Data(nal))
-            }
+        var extradata: UnsafePointer<UInt8>?
+        var extradataSize = 0
+        if let cp = stream.pointee.codecpar, let ed = cp.pointee.extradata, cp.pointee.extradata_size > 0 {
+            extradata = UnsafePointer(ed)
+            extradataSize = Int(cp.pointee.extradata_size)
         }
+        let framing = A53SEIParser.nalFraming(codec: .hevc, extradata: extradata, size: extradataSize)
+        try handle.write(contentsOf: doviProbeParameterSets(
+            extradata: extradata, size: extradataSize, framing: framing))
 
         var packetsProcessed = 0
         var conversions = 0
         var failures = 0
         var elType: String? = nil
 
-        while true {
-            let maybePacket: UnsafeMutablePointer<AVPacket>?
-            do {
-                maybePacket = try demuxer.readPacket()
-            } catch {
-                break
+        while let packet = try demuxer.readPacket() {
+            defer {
+                av_packet_unref(packet)
+                av_packet_free_safe(packet)
             }
-            guard let packet = maybePacket else { break }  // EOF
-
-            if packet.pointee.stream_index == videoIdx {
-                packetsProcessed += 1
-                if elType == nil {
-                    elType = DoviRpuConverter.enhancementLayerType(packet)
-                }
-                if DoviRpuConverter.convertPacketToProfile81(packet) {
-                    conversions += 1
-                } else {
-                    failures += 1
-                }
-                if let data = packet.pointee.data, packet.pointee.size > 4 {
-                    let size = Int(packet.pointee.size)
-                    var off = 0
-                    while off + 4 <= size {
-                        var len = 0
-                        for i in 0..<4 { len = (len << 8) | Int(data[off + i]) }
-                        let nalStart = off + 4
-                        if len == 0 || nalStart + len > size { break }
-                        handle.write(Data(startCode))
-                        handle.write(Data(bytes: data + nalStart, count: len))
-                        off = nalStart + len
-                    }
-                }
+            guard packet.pointee.stream_index == videoIdx else { continue }
+            packetsProcessed += 1
+            if elType == nil {
+                elType = DoviRpuConverter.enhancementLayerType(packet, framing: framing)
             }
-
-            av_packet_unref(packet)
-            av_packet_free_safe(packet)
+            if DoviRpuConverter.convertPacketToProfile81(packet, framing: framing) {
+                conversions += 1
+            } else {
+                failures += 1
+            }
+            try handle.write(contentsOf: doviProbeAnnexB(packet, framing: framing))
         }
 
         return DoviConvertProbeResult(
diff --git a/Sources/aetherctl/DebugOutput.swift b/Sources/aetherctl/DebugOutput.swift
index 38fab53f7..286a1dc11 100644
--- a/Sources/aetherctl/DebugOutput.swift
+++ b/Sources/aetherctl/DebugOutput.swift
@@ -1,21 +1,39 @@
 import Foundation
 
-/// Audit OPS-3: debug artefacts go into one private directory per run (`mkdtemp`, mode 0700) under
-/// the user's temporary directory. A fixed name in the shared `/tmp` could be pre-created as a
-/// symlink by another local user, and the write would follow it.
+/// Audit OPS-3: debug artefacts go into a private directory under the user's temporary directory,
+/// never a fixed name in the shared `/tmp` that another local user could pre-create as a symlink.
+/// Audit OPS-107: the directory is the SAME one on every run (`aetherctl-<uid>`, mode 0700, checked
+/// with `lstat` for being a real directory we own), so the next run overwrites the last one's files
+/// instead of leaving another multi-gigabyte `dovitest` output behind. A directory that fails the
+/// check (a symlink, someone else's) is not used: the run falls back to a fresh `mkdtemp` one.
 let debugOutputDirectory: String = {
-    let template = FileManager.default.temporaryDirectory.appendingPathComponent("aetherctl-XXXXXX").path
+    let temporary = FileManager.default.temporaryDirectory
+    let stable = temporary.appendingPathComponent("aetherctl-\(getuid())").path
+    if privateOwnedDirectory(stable) { return stable }
+
+    let template = temporary.appendingPathComponent("aetherctl-XXXXXX").path
     var buffer = Array(template.utf8CString)
     if let made = mkdtemp(&buffer) {
         return String(cString: made)
     }
-    let fallback = FileManager.default.temporaryDirectory
-        .appendingPathComponent("aetherctl-\(UUID().uuidString)").path
+    let fallback = temporary.appendingPathComponent("aetherctl-\(UUID().uuidString)").path
     try? FileManager.default.createDirectory(atPath: fallback, withIntermediateDirectories: false,
                                              attributes: [.posixPermissions: 0o700])
     return fallback
 }()
 
+/// Creates `path` (mode 0700) when it is absent and reports whether what stands there is a real
+/// directory owned by this user that nobody else can enter.
+private func privateOwnedDirectory(_ path: String) -> Bool {
+    if mkdir(path, 0o700) != 0, errno != EEXIST { return false }
+    var info = stat()
+    guard lstat(path, &info) == 0,
+          (info.st_mode & S_IFMT) == S_IFDIR,
+          info.st_uid == getuid() else { return false }
+    if info.st_mode & 0o077 != 0, chmod(path, 0o700) != 0 { return false }
+    return true
+}
+
 func debugOutputPath(_ name: String) -> String {
     (debugOutputDirectory as NSString).appendingPathComponent(name)
 }
diff --git a/Sources/aetherctl/DoviTest.swift b/Sources/aetherctl/DoviTest.swift
index 2327aff5c..e4817929d 100644
--- a/Sources/aetherctl/DoviTest.swift
+++ b/Sources/aetherctl/DoviTest.swift
@@ -3,10 +3,12 @@ import AetherEngine
 
 // MARK: - dovitest
 
-/// Validate DoviRpuConverter.convertPacketToProfile81 against dovi_tool ground truth. Walks the HEVC stream, converts DV P7 -> P8.1, writes Annex-B to aetherctl-dovitest.hevc in the run's private temporary directory.
-func runDoviTest(url: URL) -> Int32 {
-    let outputPath = debugOutputPath("aetherctl-dovitest.hevc")
-    let rpuPath = debugOutputPath("host.rpu")
+/// Validate DoviRpuConverter.convertPacketToProfile81 against dovi_tool ground truth. Walks the HEVC stream, converts DV P7 -> P8.1, writes Annex-B to `outputPath`, by default aetherctl-dovitest.hevc in the per-user private temporary directory (overwritten by the next run).
+func runDoviTest(url: URL, outputPath: String? = nil) -> Int32 {
+    let outputPath = outputPath ?? debugOutputPath("aetherctl-dovitest.hevc")
+    let rpuPath = outputPath.hasSuffix(".hevc")
+        ? String(outputPath.dropLast(".hevc".count)) + ".rpu"
+        : outputPath + ".rpu"
     print(EngineLog.redacted("aetherctl dovitest: \(url.absoluteString)"))
     print("output: \(outputPath)")
     print("")
diff --git a/Sources/aetherctl/main.swift b/Sources/aetherctl/main.swift
index 1fb3d2fa0..c485905f7 100644
--- a/Sources/aetherctl/main.swift
+++ b/Sources/aetherctl/main.swift
@@ -106,7 +106,7 @@ func printUsage() {
       aetherctl segverify [--from N] [--count K] [--no-dv] [--force-dv] [--dv-base-layer] [--dump <dir>] <url>
                           (#92: SW-decode each segment in isolation; framesDecoded==0 => not independent)
       aetherctl disc-inspect <disc.iso>
-      aetherctl dovitest <file>
+      aetherctl dovitest [--out PATH.hevc] <file>
       aetherctl extract [--at <sec>] [--snapshot] [--width <px>] [--loops <n>] <url>
       aetherctl audio [--seconds N] <url>
       aetherctl audiotap [--duration S] [--out PATH.wav] [--remote | --software] <url>
@@ -236,7 +236,8 @@ func printUsage() {
                 8.1 (and drop the enhancement layer) via
                 DoviRpuConverter, and write the result to
                 aetherctl-dovitest.hevc (Annex-B) in a private
-                per-run temporary directory, printed. Feed
+                per-user temporary directory (printed, reused and
+                overwritten by the next run), or to --out PATH. Feed
                 that to `dovi_tool extract-rpu` + `info` to validate
                 the rewritten RPU against ground truth.
 
@@ -260,7 +261,7 @@ func printUsage() {
                 frame-accurately at full resolution. Use --loops N
                 with `leaks --atExit` to detect memory leaks.
                 Writes the first frame to aetherctl-extract-<mode>.png
-                in a private per-run temporary directory, printed.
+                in a private per-user temporary directory, printed.
 
       audio     Load a source through the engine's audio-only path
                 (LoadOptions.audioOnly=true), play for ~10 seconds,
@@ -444,14 +445,15 @@ if first == "disc-inspect" {
 // DV P7 -> 8.1 converter validation harness.
 if first == "dovitest" {
     var rest = Array(args.dropFirst(2))
+    let outPath = takeStringFlag("--out", from: &rest)
     guard let urlArg = rest.first(where: { !$0.hasPrefix("--") }) else {
         print("ERROR: dovitest requires a <file> argument")
-        print("Usage: aetherctl dovitest <file>")
+        print("Usage: aetherctl dovitest [--out PATH.hevc] <file>")
         exit(64)
     }
     rest.removeAll { $0 == urlArg }
     rejectStrayFlags(rest, subcommand: "dovitest")
-    exit(runDoviTest(url: parseSourceURL(urlArg)))
+    exit(runDoviTest(url: parseSourceURL(urlArg), outputPath: outPath))
 }
 
 // #93 post-recovery judder: raw video packet timing per demuxer open profile.
diff --git a/Tests/AetherEngineTests/DoviConvertProbeTests.swift b/Tests/AetherEngineTests/DoviConvertProbeTests.swift
new file mode 100644
index 000000000..063aab2ae
--- /dev/null
+++ b/Tests/AetherEngineTests/DoviConvertProbeTests.swift
@@ -0,0 +1,70 @@
+import Foundation
+import Testing
+@testable import AetherEngine
+
+private func fixtureURL(_ name: String) -> URL {
+    URL(fileURLWithPath: #filePath)
+        .deletingLastPathComponent()
+        .deletingLastPathComponent()
+        .deletingLastPathComponent()
+        .appendingPathComponent("Fixtures")
+        .appendingPathComponent(name)
+}
+
+private func fixtureExists(_ name: String) -> Bool {
+    FileManager.default.fileExists(atPath: fixtureURL(name).path)
+}
+
+/// `aetherctl dovitest` writes a source's video stream as Annex B for `dovi_tool`. It resolved the
+/// framing of neither the converter calls nor its writer, so an Annex-B source (a Blu-ray remux) came
+/// out as one bogus NAL per packet, with every packet counted as converted (audit BIT-106).
+@Suite("dovitest probe")
+struct DoviConvertProbeTests {
+
+    private func nalTypes(of file: URL) throws -> [UInt8] {
+        let bytes = try Data(contentsOf: file)
+        var types: [UInt8] = []
+        bytes.withUnsafeBytes { raw in
+            guard let base = raw.bindMemory(to: UInt8.self).baseAddress else { return }
+            A53SEIParser.forEachNAL(base, bytes.count, .annexB) { nal, _ in types.append((nal[0] >> 1) & 0x3F) }
+        }
+        return types
+    }
+
+    @Test("A raw Annex-B stream probes to the same NALs as the hvcC file it was written from",
+          .enabled(if: fixtureExists("hdr10-hevc.mp4"), "needs Fixtures/hdr10-hevc.mp4 (Scripts/fetch-fixtures.sh)"),
+          .timeLimit(.minutes(2)))
+    func annexBSourceKeepsItsNALs() throws {
+        let dir = FileManager.default.temporaryDirectory
+            .appendingPathComponent("dovi-probe-\(UUID().uuidString)", isDirectory: true)
+        try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
+        defer { try? FileManager.default.removeItem(at: dir) }
+
+        let first = dir.appendingPathComponent("first.hevc")
+        let second = dir.appendingPathComponent("second.hevc")
+        let fromMP4 = try AetherEngine.doviConvertProbe(url: fixtureURL("hdr10-hevc.mp4"), outputPath: first.path)
+        let fromAnnexB = try AetherEngine.doviConvertProbe(url: first, outputPath: second.path)
+
+        #expect(fromMP4.videoStreamFound && fromMP4.packetsProcessed > 0)
+        #expect(fromAnnexB.videoStreamFound && fromAnnexB.packetsProcessed > 0)
+        #expect(fromAnnexB.failures == 0)
+
+        // The raw demuxer also hands the stream's parameter sets over as extradata, so they head the
+        // second output once more on top of the in-band copy. Repeated parameter sets are legal Annex B.
+        let notParameterSet: (UInt8) -> Bool = { !(32...34).contains($0) }
+        let expected = try nalTypes(of: first).filter(notParameterSet)
+        #expect(expected.count >= fromMP4.packetsProcessed, "at least one NAL per packet")
+        let actual = try nalTypes(of: second).filter(notParameterSet)
+        #expect(actual == expected, "\(actual.count) NALs (\(actual.prefix(12))) against \(expected.count) (\(expected.prefix(12)))")
+    }
+
+    @Test("An output path that cannot be opened throws instead of reporting an empty run",
+          .enabled(if: fixtureExists("hdr10-hevc.mp4"), "needs Fixtures/hdr10-hevc.mp4 (Scripts/fetch-fixtures.sh)"))
+    func unwritableOutputThrows() {
+        let path = FileManager.default.temporaryDirectory
+            .appendingPathComponent("dovi-probe-missing-\(UUID().uuidString)/out.hevc").path
+        #expect(throws: (any Error).self) {
+            _ = try AetherEngine.doviConvertProbe(url: fixtureURL("hdr10-hevc.mp4"), outputPath: path)
+        }
+    }
+}
diff --git a/Tests/AetherEngineTests/DoviRpuConverterTests.swift b/Tests/AetherEngineTests/DoviRpuConverterTests.swift
index eee659ea2..9f57b5e79 100644
--- a/Tests/AetherEngineTests/DoviRpuConverterTests.swift
+++ b/Tests/AetherEngineTests/DoviRpuConverterTests.swift
@@ -184,4 +184,51 @@ struct DoviRpuConverterTests {
         #expect(DoviRpuConverter.enhancementLayerType(pkt, framing: .annexB) == nil)
         #expect(annexBNALTypes(pkt) == [1, 62])
     }
+
+    // MARK: - aetherctl dovitest output (audit BIT-106)
+
+    /// The probe's writer used to walk every packet as 4-byte-length NALs whatever the source was,
+    /// so an Annex-B packet holding four NALs came out as one 1-byte NAL.
+    @Test("The probe writes every NAL of a packet behind a start code, in either framing")
+    func probeEmitsEveryNALInEitherFraming() {
+        let nals = [hevcNAL(type: 35, payload: [0x50]),
+                    hevcNAL(type: 19, payload: [UInt8](repeating: 0xAA, count: 40)),
+                    hevcNAL(type: 62, payload: [UInt8](repeating: 0x11, count: 9)),
+                    hevcNAL(type: 63, payload: [UInt8](repeating: 0x22, count: 30))]
+        for (framing, build) in [(VideoNALFraming.annexB, annexBPacket),
+                                 (VideoNALFraming.lengthPrefixed(size: 4), avccPacket)] {
+            let pkt = build(nals)
+            defer { var p: UnsafeMutablePointer<AVPacket>? = pkt; av_packet_free(&p) }
+            let out = AetherEngine.doviProbeAnnexB(UnsafePointer(pkt), framing: framing)
+            var emitted: [[UInt8]] = []
+            out.withUnsafeBytes { raw in
+                let base = raw.bindMemory(to: UInt8.self).baseAddress!
+                A53SEIParser.forEachNAL(base, out.count, .annexB) { nal, len in
+                    emitted.append([UInt8](UnsafeBufferPointer(start: nal, count: len)))
+                }
+            }
+            #expect(emitted == nals, "framing \(framing)")
+            #expect(Array(out.prefix(4)) == [0, 0, 0, 1])
+        }
+    }
+
+    @Test("Annex-B extradata is written as it is, hvcC parameter sets are start-coded")
+    func probeParameterSetsFollowTheExtradataFraming() {
+        let annexB: [UInt8] = [0, 0, 0, 1, 0x40, 0x01, 0xAA, 0, 0, 0, 1, 0x42, 0x01, 0xBB]
+        let annexBOut = annexB.withUnsafeBufferPointer {
+            AetherEngine.doviProbeParameterSets(extradata: $0.baseAddress, size: $0.count, framing: .annexB)
+        }
+        #expect([UInt8](annexBOut) == annexB)
+
+        var hvcC = [UInt8](repeating: 0, count: 22)
+        hvcC[0] = 1
+        hvcC[21] = 0x03
+        hvcC.append(1)                                   // numOfArrays
+        hvcC += [0x20, 0x00, 0x01, 0x00, 0x03, 0x40, 0x01, 0xAA]   // VPS array, one NAL of 3 bytes
+        let hvcCOut = hvcC.withUnsafeBufferPointer {
+            AetherEngine.doviProbeParameterSets(extradata: $0.baseAddress, size: $0.count, framing: .lengthPrefixed(size: 4))
+        }
+        #expect([UInt8](hvcCOut) == [0, 0, 0, 1, 0x40, 0x01, 0xAA])
+        #expect(AetherEngine.doviProbeParameterSets(extradata: nil, size: 0, framing: .annexB).isEmpty)
+    }
 }
diff --git a/docs/cli.md b/docs/cli.md
index fca500181..3ed1621b0 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -141,7 +141,7 @@ the same clock as `FIRSTFRAME`. The 1 Hz tick samples the phase, which is far to
 signal apart from the moment the rate rolls; a healthy native join is exactly two edges, `loading` at the
 load and `playing` at the roll (AE#440).
 
-`--subs <codec-or-lang>` matches against the track's libavcodec name or language and logs every overlay cue and cue trim as it lands. `--host-calls` replays host post-load behavior against the fresh session: `play`, `extractor` (`makeFrameExtractor`), `setrate` (`setRate(1.0)`), `pausestart` (Sodalite#104 round 4: `pause()` the instant load returns, before any frame exists, and `play()` at t=8; the shape of a host that holds a fresh load paused, and a software session used to answer it with eight ticks of `enq=+0 status=unknown r4d=n`, a black picture under a paused clock; now the `[SWHost] #104` lines show the first frame presented at a stopped clock and `startup 8/8 presenting` arrives while paused), `ratehold` (set 1.5, pause at tick 3, resume at tick 5, then read the rate back off the transport itself: the #436 drill, and it fails the run if the resume came back at 1.0), `reloadlive` (reload the URL on the live path when the probe flags it live, the AetherPlayer Open URL flow), `reloadnext` (a host's episode seam: the same URL loaded again at t=4 on the still-playing engine with no `stop()` in between, so the native host is reused, and every published `state` printed as `STATE <state> t=<s>`; the second load must go `loading`, `playing` with no `paused` between them, which it did not while the reused host still carried the outgoing item's `.playing` status and every host raised its transport over the next episode), `seekback` (rewind 20 s into the DVR window at t=15, return to the live edge at t=30), `overlapseek` (the #292 seek-window drills below), `pausehold` (Sodalite#104: pause at t=10 and HOLD until ten seconds before the end, printing the playhead, the edge and the resident depth every second, which is how a session paused for longer than its own DVR window is measured without waiting out a real one: pair it with `--dvr-window 30` and `--seconds 90` and the ninety minute question becomes a ninety second run), `still` (#544: asks for a scrub still at three aims, 20 s behind the playhead at t=15, 5 s behind at t=20 and at the edge at t=25, writing each to `aetherctl-still-<tick>.png` in the run's private temporary directory (the path is printed) and reporting hit or MISS with the decode time; pair it with `--sw --dvr-window N`, where the picture comes out of the DVR packet ring rather than a segment cache, and read the FILE as well as the count, because the bundled seed burns its own second into the frame so a still asked for 14.85 s showing `14` is the verdict that it decoded the right moment and not merely an image; exit 6 when nothing hit, 5 when the session ended before the first aim; on a VOD session (AE#605) the three aims are 10.5 s behind the playhead, 4.5 s ahead of it and 600 s past it, through `scrubThumbnail`, and the third is EXPECTED to miss, because a frame the cache does not hold yet must not be answered with the one before it: `--sw` against an HTTP source is the software packet-cache case, and the testsrc fixture's counter in the PNG is the verdict that the still decoded to the target rather than snapping to its keyframe), `stallclock` (AE#549: stop the master clock at t=4 behind the host's back, the way an interrupted audio session does, then call a plain `play()` at t=7 and read whether the playhead moves again; the interruption itself cannot be staged on macOS, its outcome can, and without the `RendererClockResume` branch the run ends with the clock standing exactly where the stall left it, which is the field log's shape; the drill drives DEBUG-only engine hooks, so a Release `aetherctl` prints a notice and ends inconclusive, build it with `swift build --product aetherctl`), `pausereload`, `playreload` and `extplayreload` (#623: force the #93/#65 stage-2 item reload at t=10, on a session paused at t=6, on one left playing, and on one paused through the engine at t=6 and resumed at t=8 straight on the `AVPlayer` the way AVKit's transport does, which leaves the engine's intent reading paused while the player runs; the run fails with exit 4 if the clock moves after the paused reload or stands still after either playing one, and before #623 `pausereload` ended `+7.20 s, state=playing`), and `pauseseek` (pause at t=12, seek at t=15 while paused, resume at t=20; with `--sw` the five paused ticks between landing and resume show what the `[SWDiag]` line reports while the pump is parked and has not heard of the seek, the AE#479 shape); this is how the pre-arming `setRate` wedge was isolated.
+`--subs <codec-or-lang>` matches against the track's libavcodec name or language and logs every overlay cue and cue trim as it lands. `--host-calls` replays host post-load behavior against the fresh session: `play`, `extractor` (`makeFrameExtractor`), `setrate` (`setRate(1.0)`), `pausestart` (Sodalite#104 round 4: `pause()` the instant load returns, before any frame exists, and `play()` at t=8; the shape of a host that holds a fresh load paused, and a software session used to answer it with eight ticks of `enq=+0 status=unknown r4d=n`, a black picture under a paused clock; now the `[SWHost] #104` lines show the first frame presented at a stopped clock and `startup 8/8 presenting` arrives while paused), `ratehold` (set 1.5, pause at tick 3, resume at tick 5, then read the rate back off the transport itself: the #436 drill, and it fails the run if the resume came back at 1.0), `reloadlive` (reload the URL on the live path when the probe flags it live, the AetherPlayer Open URL flow), `reloadnext` (a host's episode seam: the same URL loaded again at t=4 on the still-playing engine with no `stop()` in between, so the native host is reused, and every published `state` printed as `STATE <state> t=<s>`; the second load must go `loading`, `playing` with no `paused` between them, which it did not while the reused host still carried the outgoing item's `.playing` status and every host raised its transport over the next episode), `seekback` (rewind 20 s into the DVR window at t=15, return to the live edge at t=30), `overlapseek` (the #292 seek-window drills below), `pausehold` (Sodalite#104: pause at t=10 and HOLD until ten seconds before the end, printing the playhead, the edge and the resident depth every second, which is how a session paused for longer than its own DVR window is measured without waiting out a real one: pair it with `--dvr-window 30` and `--seconds 90` and the ninety minute question becomes a ninety second run), `still` (#544: asks for a scrub still at three aims, 20 s behind the playhead at t=15, 5 s behind at t=20 and at the edge at t=25, writing each to `aetherctl-still-<tick>.png` in aetherctl's private per-user temporary directory (the path is printed) and reporting hit or MISS with the decode time; pair it with `--sw --dvr-window N`, where the picture comes out of the DVR packet ring rather than a segment cache, and read the FILE as well as the count, because the bundled seed burns its own second into the frame so a still asked for 14.85 s showing `14` is the verdict that it decoded the right moment and not merely an image; exit 6 when nothing hit, 5 when the session ended before the first aim; on a VOD session (AE#605) the three aims are 10.5 s behind the playhead, 4.5 s ahead of it and 600 s past it, through `scrubThumbnail`, and the third is EXPECTED to miss, because a frame the cache does not hold yet must not be answered with the one before it: `--sw` against an HTTP source is the software packet-cache case, and the testsrc fixture's counter in the PNG is the verdict that the still decoded to the target rather than snapping to its keyframe), `stallclock` (AE#549: stop the master clock at t=4 behind the host's back, the way an interrupted audio session does, then call a plain `play()` at t=7 and read whether the playhead moves again; the interruption itself cannot be staged on macOS, its outcome can, and without the `RendererClockResume` branch the run ends with the clock standing exactly where the stall left it, which is the field log's shape; the drill drives DEBUG-only engine hooks, so a Release `aetherctl` prints a notice and ends inconclusive, build it with `swift build --product aetherctl`), `pausereload`, `playreload` and `extplayreload` (#623: force the #93/#65 stage-2 item reload at t=10, on a session paused at t=6, on one left playing, and on one paused through the engine at t=6 and resumed at t=8 straight on the `AVPlayer` the way AVKit's transport does, which leaves the engine's intent reading paused while the player runs; the run fails with exit 4 if the clock moves after the paused reload or stands still after either playing one, and before #623 `pausereload` ended `+7.20 s, state=playing`), and `pauseseek` (pause at t=12, seek at t=15 while paused, resume at t=20; with `--sw` the five paused ticks between landing and resume show what the `[SWDiag]` line reports while the pump is parked and has not heard of the seek, the AE#479 shape); this is how the pre-arming `setRate` wedge was isolated.
 
 `--seek-every N` seeks once every N ticks past tick 10, walking `--seek-pattern <abs,abs,...>` if one is given (a short backward hop otherwise), and `--seek-count K` stops after K seeks so a run can be a BURST and then play. Both halves are needed for anything about what a seek sequence leaves behind: the burst puts the store in the state under test, and only the playing half shows what the overlay carries through it. That pairing is what made AE#362's second mechanism reproducible (a hole between a restarted pump and the island the previous run left ahead of it, decoded across and then never re-read).
 
@@ -435,10 +435,10 @@ A healthy run prints `contiguous` on every line. AE#561 is the counter-example i
 
 ## dovitest
 
-Runs the Dolby Vision Profile 7 to 8.1 converter over every video packet of the source and writes the converted elementary stream (Annex B) to `aetherctl-dovitest.hevc` in the run's private temporary directory (the path is printed), reporting packets processed, conversions, and failures. Lets you confirm the in-engine `DoviRpuConverter` (libdovi) output matches the `dovi_tool -m 2` ground truth offline, without a DV panel:
+Runs the Dolby Vision Profile 7 to 8.1 converter over every video packet of the source and writes the converted elementary stream (Annex B) to `aetherctl-dovitest.hevc` in aetherctl's private per-user temporary directory (`$TMPDIR/aetherctl-<uid>`, mode 0700, the same directory on every run, so the next run overwrites the file instead of leaving a second copy of the film; the path is printed), or to the path given with `--out`, reporting packets processed, conversions, and failures. Lets you confirm the in-engine `DoviRpuConverter` (libdovi) output matches the `dovi_tool -m 2` ground truth offline, without a DV panel:
 
 ```bash
-swift run aetherctl dovitest <p7-source>
+swift run aetherctl dovitest [--out PATH.hevc] <p7-source>
 dovi_tool extract-rpu -i <printed output path> -o out.rpu
 dovi_tool info -i out.rpu -f 0   # expect dovi_profile 8, disable_residual_flag true
 ```
@@ -459,7 +459,7 @@ The profile differential is the diagnostic: a `video_delay=0` plus NOPTS or non-
 
 ## extract
 
-Opens a `FrameExtractor` against the source and pulls a still frame. Thumbnail mode (default) snaps to the nearest keyframe and downscales to `--width` (default 320); `--snapshot` decodes frame-accurately at full resolution. `--at <sec>` sets the seek position (default 60.0). The first frame is written to `aetherctl-extract-<mode>.png` in the run's private temporary directory (the path is printed). `--loops N` repeats the extraction across eight cycling positions, which pairs with `leaks --atExit` to validate the decode-context teardown is clean:
+Opens a `FrameExtractor` against the source and pulls a still frame. Thumbnail mode (default) snaps to the nearest keyframe and downscales to `--width` (default 320); `--snapshot` decodes frame-accurately at full resolution. `--at <sec>` sets the seek position (default 60.0). The first frame is written to `aetherctl-extract-<mode>.png` in aetherctl's private per-user temporary directory (the path is printed). `--loops N` repeats the extraction across eight cycling positions, which pairs with `leaks --atExit` to validate the decode-context teardown is clean:
 
 ```bash
 swift run aetherctl extract --at 612 --snapshot <url>          # frame-accurate still
@@ -475,7 +475,7 @@ Plays a source through the audio-only pipeline (default ten seconds, `--seconds
 
     aetherctl audiotap [--duration S] [--out PATH.wav] [--remote | --software] <url>
 
-Brings up the loopback session headless, decodes the audio tap (#95) as fast as segments are produced, writes mono Float32 48 kHz WAV (default `audiotap.wav` in the run's private temporary directory; `--out` sets the path), and prints buffer count, PCM seconds, discontinuity count, and the covered `sourceTime` span. A clean run reports exactly one discontinuity (the install itself). `--remote` drives the remote-HLS delivery path instead (direct AVPlayer ingest of an HLS url, no loopback): rendition/variant resolution, segment fetch + decrypt, playhead-follow decode. Verification tool for the PCM audio tap across the stream-copy and bridge audio paths.
+Brings up the loopback session headless, decodes the audio tap (#95) as fast as segments are produced, writes mono Float32 48 kHz WAV (default `audiotap.wav` in aetherctl's private per-user temporary directory; `--out` sets the path), and prints buffer count, PCM seconds, discontinuity count, and the covered `sourceTime` span. A clean run reports exactly one discontinuity (the install itself). `--remote` drives the remote-HLS delivery path instead (direct AVPlayer ingest of an HLS url, no loopback): rendition/variant resolution, segment fetch + decrypt, playhead-follow decode. Verification tool for the PCM audio tap across the stream-copy and bridge audio paths.
 
 `--software` drives the third delivery path, the SW sink (`AudioTapPCMConverter`), which the other two modes cannot reach: they drive their readers directly, while the sink only exists inside a real session. This mode therefore loads the source through the whole engine, fails if it did not route to the software host, installs the tap through the public `installAudioTap()` and plays, so the sink runs exactly as it does in a host. It is bound to wall clock (the SW host decodes in real time), and it reports `peak` next to the buffer count because the two ways this path fails look identical in a report otherwise: **exit 3 covers both no buffers at all and buffers of digital silence**, which at a consumer is indistinguishable from a muted source. That gap is not hypothetical. With no harness here, a force unwrap that trapped on the FIRST buffer of any multichannel track shipped in 6.1.3 and survived to main (#400), and the silent-downmix defect underneath it only became visible once the trap was gone. Software routing needs a source the native path declines, e.g. `ffmpeg -f lavfi -i testsrc2 -f lavfi -i sine -c:v libvpx-vp9 -c:a aac -shortest clip.mkv`; add `-af "pan=5.1|c0=c0|c1=c0|c2=c0|c3=c0|c4=c0|c5=c0"` for the multichannel case and `-af "pan=quad|c0=c0|c1=c0|c2=c0|c3=c0"` for the layout AVAudioConverter refuses to mix.
 

From 3f939efb2be6c7d63851be37b886d111ca72faa5 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 08:51:49 +0200
Subject: [PATCH 191/359] perf(demuxer): the forward-only streaming buffer
 trims without copying the buffer (audit PERF-102, DMX-104)

`readStreaming` dropped its consumed head with `Data.subdata` on every read
past the 1 MB lookback, copying all 32-64 MB still ahead of the cut each
time. The buffer is now a `ChunkedByteWindow` (AE#619), so a read copies out
of the delivered chunks and a trim advances an offset and releases the chunks
it passed. Each delivery is copied once on the way in, as `Data.append` did,
so the transport's buffers are not pinned while a chunk waits to be read.

Measured on a debug build against a 60 MB resident buffer: 200 reads of
262,000 bytes took 329 ms before and 5.7 ms after.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 Sources/AetherEngine/Demuxer/AVIOReader.swift | 30 ++++---
 .../StreamingBufferTrimTests.swift            | 84 +++++++++++++++++++
 2 files changed, 104 insertions(+), 10 deletions(-)
 create mode 100644 Tests/AetherEngineTests/StreamingBufferTrimTests.swift

diff --git a/Sources/AetherEngine/Demuxer/AVIOReader.swift b/Sources/AetherEngine/Demuxer/AVIOReader.swift
index 0202c8b31..e79ef5c2b 100644
--- a/Sources/AetherEngine/Demuxer/AVIOReader.swift
+++ b/Sources/AetherEngine/Demuxer/AVIOReader.swift
@@ -502,7 +502,10 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
 
     // MARK: - Streaming Mode (sequential GET)
 
-    private var streamBuffer = Data()
+    /// Held as the delivered chunks, like the persistent window (AE#619): a read trims its consumed
+    /// head by advancing an offset, where `Data.subdata` copied the whole 32-64 MB still ahead of the
+    /// cut on every read (audit PERF-102). Guarded by `streamLock`.
+    private var streamBuffer = ChunkedByteWindow()
     private var streamBytesRead: Int64 = 0
     /// Most bytes `streamBuffer` has held at once, for the bound tests. Guarded by `streamLock`.
     private var streamPeakBytes = 0
@@ -801,6 +804,16 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
         return streamPeakBytes
     }
 
+    #if DEBUG
+    /// Storage address of every chunk the streaming buffer still holds, first to last. A trim that
+    /// copied the buffer would move all of them.
+    var streamChunkAddressesForTesting: [UnsafeRawPointer?] {
+        streamLock.lock()
+        defer { streamLock.unlock() }
+        return streamBuffer.chunkStorageAddresses()
+    }
+    #endif
+
     /// Bytes the persistent window holds, behind and ahead of the cursor.
     var windowBytesForTesting: Int {
         winCond.lock()
@@ -1646,7 +1659,7 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
 
         streamLock.lock()
         streamEnded = true
-        streamBuffer = Data()
+        streamBuffer.removeAll()
         let sTask = streamingTask
         let sSession = streamingSession
         let wasSuspended = streamingTaskSuspended
@@ -1824,22 +1837,17 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
                 let toCopy = min(available, requestSize - totalRead)
 
                 streamLock.lock()
-                streamBuffer.withUnsafeBytes { raw in
-                    let src = raw.baseAddress!.advanced(by: posInBuffer)
-                        .assumingMemoryBound(to: UInt8.self)
-                    buf.advanced(by: totalRead).update(from: src, count: toCopy)
-                }
+                streamBuffer.copyBytes(to: buf.advanced(by: totalRead), from: posInBuffer, count: toCopy)
                 streamLock.unlock()
 
                 position += Int64(toCopy)
                 totalRead += toCopy
 
-                // subdata (not removeFirst): removeFirst leaks backing storage (see trimWindowLocked).
                 streamLock.lock()
                 let consumed = Int(position - streamBytesRead)
                 if consumed > Self.streamTrimThreshold {
                     let trimAmount = consumed - Self.streamTrimThreshold
-                    streamBuffer = streamBuffer.subdata(in: trimAmount..<streamBuffer.count)
+                    streamBuffer.dropFirst(trimAmount)
                     streamBytesRead += Int64(trimAmount)
                 }
                 var toResume: URLSessionDataTask?
@@ -3637,7 +3645,9 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
                 self.streamLock.unlock()
                 return
             }
-            self.streamBuffer.append(data)
+            // Owned bytes: the chunk is retained until it is consumed, and a delivery that still
+            // references the transport's dispatch_data would pin its buffer for that long.
+            self.streamBuffer.append(data.withUnsafeBytes { Data($0) })
             self.streamPeakBytes = max(self.streamPeakBytes, self.streamBuffer.count)
             var toCancel: URLSessionDataTask?
             if self.streamBuffer.count > Self.streamHardCap {
diff --git a/Tests/AetherEngineTests/StreamingBufferTrimTests.swift b/Tests/AetherEngineTests/StreamingBufferTrimTests.swift
new file mode 100644
index 000000000..3869ae1cd
--- /dev/null
+++ b/Tests/AetherEngineTests/StreamingBufferTrimTests.swift
@@ -0,0 +1,84 @@
+import Testing
+import Foundation
+@testable import AetherEngine
+
+/// Audit PERF-102: the forward-only reader trimmed its consumed head with `Data.subdata`, which
+/// copied the whole 32-64 MB still ahead of the cut on every read. The buffer now holds the chunks
+/// as they were delivered (AE#619), so a trim advances an offset and moves nothing.
+@Suite("Forward-only streaming buffer")
+struct StreamingBufferTrimTests {
+
+    private let total = 6 * 1024 * 1024
+
+    private func makeReader(_ server: ThrottledOriginServer) -> AVIOReader {
+        AVIOReader(url: URL(string: "http://127.0.0.1:\(server.port)/archive.ts")!, sequentialOnly: true)
+    }
+
+    @Test("unaligned reads return exactly the bytes the origin sent", .timeLimit(.minutes(2)))
+    func byteExactAcrossUnalignedReads() async throws {
+        let maybe = ThrottledOriginServer(totalSize: Int64(total), throttleUs: 0, patternedBody: true)
+        let server = try #require(maybe)
+        defer { server.stop() }
+        let reader = makeReader(server)
+        defer { reader.markClosed(); reader.close() }
+        try reader.open()
+        // Everything is resident before the first read, so each trim below runs against the whole body.
+        try await waitFor { reader.streamPeakBufferBytesForTesting >= total }
+
+        let expected = (0..<total).map { ThrottledOriginServer.patternByte(at: Int64($0)) }
+        let sizes = [1, 7, 4093, 65_537, 262_000, 300_001, 12, 1_048_576 + 5]
+        let buf = UnsafeMutablePointer<UInt8>.allocate(capacity: sizes.max()!)
+        defer { buf.deallocate() }
+        var offset = 0
+        var turn = 0
+        while offset < total {
+            let want = sizes[turn % sizes.count]
+            turn += 1
+            let n = Int(reader.read(into: buf, size: Int32(want)))
+            #expect(n > 0, "read failed at \(offset)")
+            if n <= 0 { return }
+            let matches = expected.withUnsafeBufferPointer { memcmp($0.baseAddress! + offset, buf, n) == 0 }
+            #expect(matches, "\(n) bytes at \(offset) differ from the origin's")
+            if !matches { return }
+            offset += n
+        }
+        #expect(offset == total)
+        #expect(reader.read(into: buf, size: 4096) == FFmpegErr.eof)
+    }
+
+    #if DEBUG
+    @Test("a trim releases what it passed and moves nothing it keeps", .timeLimit(.minutes(2)))
+    func trimMovesNothing() async throws {
+        let maybe = ThrottledOriginServer(totalSize: Int64(total), throttleUs: 0)
+        let server = try #require(maybe)
+        defer { server.stop() }
+        let reader = makeReader(server)
+        defer { reader.markClosed(); reader.close() }
+        try reader.open()
+        try await waitFor { reader.streamPeakBufferBytesForTesting >= total }
+
+        let chunk = 262_000
+        let buf = UnsafeMutablePointer<UInt8>.allocate(capacity: chunk)
+        defer { buf.deallocate() }
+        // Past the 1 MB lookback, so every later read trims.
+        var read = 0
+        while read < 2 * 1024 * 1024 {
+            let n = Int(reader.read(into: buf, size: Int32(chunk)))
+            #expect(n > 0)
+            if n <= 0 { return }
+            read += n
+        }
+        let before = reader.streamChunkAddressesForTesting
+        #expect(before.count > 1, "the body arrived as one chunk, so this could not tell a copy from a slice")
+
+        for _ in 0..<8 {
+            #expect(reader.read(into: buf, size: Int32(chunk)) > 0)
+        }
+        let after = reader.streamChunkAddressesForTesting
+        #expect(after.count < before.count, "the trim released nothing")
+        #expect(after.count > 1)
+        #expect(Array(before.suffix(after.count)) == after,
+                "a trim reallocated the chunks it kept: the buffer was copied, not sliced")
+    }
+    #endif
+}

From 44c7c31ae8bf24ed3599d0af1f4639778548fcc5 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 08:51:53 +0200
Subject: [PATCH 192/359] fix(recording): a stop joins a scheduled teardown,
 and a start re-checks after its wait (audit FEA-105, FEA-106)

FEA-105: when the writer tore itself down (queue ceiling, write error) and a
stop arrived while it drained, the stop's finish saw the writer already closed
and returned at once, so .ended was published for a file still being written
and the teardown's own failure was dropped because the recording had been
released. finish(reason:) now joins the scheduled teardown through a dispatch
group and returns the failure it recorded, and endRecordingIfRunning publishes
.failed for it instead of .ended.

FEA-106: startRecording suspends on the previous file's finish, and a stop or
a new load could run inside that wait. It now captures the load generation and
a stop serial before the wait and throws CancellationError when either moved,
instead of installing a writer on the wrong channel or after the host stopped.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../AetherEngine/AetherEngine+Recording.swift |  29 +++-
 Sources/AetherEngine/AetherEngine.swift       |   4 +
 .../Recording/LiveRecordingWriter.swift       |  35 ++++-
 .../LiveRecordingTeardownTests.swift          | 141 ++++++++++++++++++
 4 files changed, 201 insertions(+), 8 deletions(-)
 create mode 100644 Tests/AetherEngineTests/LiveRecordingTeardownTests.swift

diff --git a/Sources/AetherEngine/AetherEngine+Recording.swift b/Sources/AetherEngine/AetherEngine+Recording.swift
index 0d7734eb0..1becc3c68 100644
--- a/Sources/AetherEngine/AetherEngine+Recording.swift
+++ b/Sources/AetherEngine/AetherEngine+Recording.swift
@@ -22,8 +22,16 @@ public extension AetherEngine {
     /// or a path that cannot be created. Anything that can only be discovered while writing arrives
     /// through `$recordingState` as `.failed`, never through both.
     func startRecording(to url: URL) async throws {
-        // The previous file is still being finalized off the main actor; it may be this path.
+        // The previous file is still being finalized off the main actor; it may be this path. The wait
+        // suspends, so a stop or a new load can run inside it (audit FEA-106): either one retires this
+        // start, which would otherwise install a writer the host had already stopped, or one on the
+        // channel that replaced the one it was asked for.
+        let generation = loadGeneration
+        let stopSerial = recordingStopSerial
         await recordingFinish?.value
+        guard loadGeneration == generation, recordingStopSerial == stopSerial else {
+            throw CancellationError()
+        }
         if case .recording(let progress) = recordingState {
             throw RecordingFailure.alreadyRecording(progress.url)
         }
@@ -63,6 +71,7 @@ public extension AetherEngine {
 
     /// Ends the recording and closes the file. Idempotent, and a no-op when nothing is recording.
     func stopRecording() async {
+        recordingStopSerial &+= 1
         endRecordingIfRunning(reason: .stoppedByHost)
         await recordingFinish?.value
     }
@@ -103,6 +112,10 @@ extension AetherEngine {
     /// used to run right here on the main actor. It runs detached now, and `.ended` is published
     /// once it is done, because `.ended` promises a closed, playable file. A recording started in
     /// the meantime owns the state, so the late `.ended` of this one is dropped.
+    ///
+    /// Audit FEA-105: when the writer was already tearing itself down (the queue ceiling, a write
+    /// error), the writer's own failure report is ignored here because this call released the
+    /// recording first, so the failure it returns is what gets published instead of `.ended`.
     func endRecordingIfRunning(reason: RecordingEndReason) {
         guard let writer = activeRecording else { return }
         (activeRecordingHost as? LiveRecordingHost)?.setRecordingSink(nil)
@@ -113,9 +126,14 @@ extension AetherEngine {
         let previous = recordingFinish
         recordingFinish = Task { [weak self] in
             await previous?.value
-            await Task.detached(priority: .utility) { writer.finish(reason: reason) }.value
+            let failure = await Task.detached(priority: .utility) { writer.finish(reason: reason) }.value
             guard let self, self.recordingGeneration == generation else { return }
-            self.recordingState = .ended(reason)
+            if let failure {
+                self.recordingState = .failed(failure)
+                EngineLog.emit("[Recording] failed: \(failure)", category: .session)
+            } else {
+                self.recordingState = .ended(reason)
+            }
         }
     }
 
@@ -217,12 +235,13 @@ extension AetherEngine {
 
     /// Test-only: runs the real `startRecording` path against a stub route, so a lifecycle test
     /// exercises production code rather than a parallel implementation.
-    func _testStartRecordingWithStubHost(to url: URL, host: TestRecordingHost) throws {
+    func _testStartRecordingWithStubHost(to url: URL, host: TestRecordingHost,
+                                         ceilingBytes: Int = AetherEngine.recordingQueueCeilingBytes) throws {
         _testSetLiveRoute(isLive: true, route: .loopback)
         let writer = try LiveRecordingWriter(
             url: url,
             streams: host.recordingStreamDescriptors(),
-            ceilingBytes: Self.recordingQueueCeilingBytes,
+            ceilingBytes: ceilingBytes,
             onFailure: makeRecordingFailureHandler()
         )
         activeRecording = writer
diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index e5af43ded..9cff56189 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -1383,6 +1383,10 @@ public final class AetherEngine: ObservableObject {
     /// The ended recording's drain and trailer, run off the main actor (audit REC-1).
     var recordingFinish: Task<Void, Never>?
 
+    /// Bumped by every `stopRecording()`, so a `startRecording` that was waiting on `recordingFinish`
+    /// can tell that a stop overtook it (audit FEA-106).
+    var recordingStopSerial: UInt64 = 0
+
     /// Republishes `recordingState` progress at 1 Hz while a recording runs.
     var recordingProgressTimer: Timer?
 
diff --git a/Sources/AetherEngine/Recording/LiveRecordingWriter.swift b/Sources/AetherEngine/Recording/LiveRecordingWriter.swift
index 0c443e703..0079b8204 100644
--- a/Sources/AetherEngine/Recording/LiveRecordingWriter.swift
+++ b/Sources/AetherEngine/Recording/LiveRecordingWriter.swift
@@ -32,6 +32,11 @@ final class LiveRecordingWriter: LiveRecordingSink, @unchecked Sendable {
     private var videoSourceStreamIndex: Int32?
     private var reportedFailure = false
     private var teardownScheduled = false
+    /// The failure a scheduled teardown is ending the recording with, kept so whoever else ends the
+    /// recording meanwhile (a stop, a zap) can report it instead of calling the file cleanly ended.
+    private var pendingFailure: RecordingFailure?
+    /// Entered when a teardown is scheduled, left when it has run: `finish(reason:)` joins it.
+    private let teardownGroup = DispatchGroup()
 
     private var queue: LiveRecordingQueue!
 
@@ -39,6 +44,13 @@ final class LiveRecordingWriter: LiveRecordingSink, @unchecked Sendable {
     private let onFailure: @Sendable (RecordingFailure) -> Void
 
     var bytesWritten: Int64 { ctxLock.lock(); defer { ctxLock.unlock() }; return _bytesWritten }
+    var isClosed: Bool { ctxLock.lock(); defer { ctxLock.unlock() }; return closed }
+
+    #if DEBUG
+    /// Test-only: runs on the drain queue before each write, so a test can hold the drain and make a
+    /// teardown take as long as a slow disk would.
+    nonisolated(unsafe) var beforeWriteForTesting: (@Sendable () -> Void)?
+    #endif
     var droppedBytes: Int64 { queue.droppedBytes }
 
     init(url: URL,
@@ -170,6 +182,9 @@ final class LiveRecordingWriter: LiveRecordingSink, @unchecked Sendable {
     // MARK: - Writer queue
 
     private func write(_ item: LiveRecordingQueue.QueuedPacket) {
+        #if DEBUG
+        beforeWriteForTesting?()
+        #endif
         ctxLock.lock()
         // Deliberately NOT gated on `closed`. `finish` stops ACCEPTING first and drains second, so
         // gating the write here would discard everything still queued at the moment of a stop, up
@@ -218,8 +233,18 @@ final class LiveRecordingWriter: LiveRecordingSink, @unchecked Sendable {
 
     // MARK: - Teardown
 
-    func finish(reason: RecordingEndReason) {
+    /// Closes the recording and returns the failure it ended with, if any (audit FEA-105). A stop that
+    /// lands while a scheduled teardown is already draining used to see `closed`, return at once, and let
+    /// the caller publish `.ended` for a file that was still being written; it now joins that teardown
+    /// and hands back the failure the teardown recorded, which its own report can no longer deliver
+    /// because the recording has been released by then.
+    @discardableResult
+    func finish(reason: RecordingEndReason) -> RecordingFailure? {
         finish(reason: reason, failure: nil)
+        teardownGroup.wait()
+        ctxLock.lock()
+        defer { ctxLock.unlock() }
+        return pendingFailure
     }
 
     /// Tears the writer down from somewhere that must not block: the demux thread (a refused
@@ -228,10 +253,14 @@ final class LiveRecordingWriter: LiveRecordingSink, @unchecked Sendable {
         ctxLock.lock()
         guard !closed, !teardownScheduled else { ctxLock.unlock(); return }
         teardownScheduled = true
+        pendingFailure = failure
+        teardownGroup.enter()
         ctxLock.unlock()
 
-        DispatchQueue.global(qos: .utility).async { [weak self] in
-            self?.finish(reason: .stoppedByHost, failure: failure)
+        // Strong self: the group is entered, and a group released while entered is a libdispatch trap.
+        DispatchQueue.global(qos: .utility).async {
+            self.finish(reason: .stoppedByHost, failure: failure)
+            self.teardownGroup.leave()
         }
     }
 
diff --git a/Tests/AetherEngineTests/LiveRecordingTeardownTests.swift b/Tests/AetherEngineTests/LiveRecordingTeardownTests.swift
new file mode 100644
index 000000000..db1b01803
--- /dev/null
+++ b/Tests/AetherEngineTests/LiveRecordingTeardownTests.swift
@@ -0,0 +1,141 @@
+import Testing
+import Foundation
+@testable import AetherEngine
+
+/// Audit FEA-105 / FEA-106: a stop or a zap that lands while a recording is being torn down, or while
+/// a start is waiting for the previous file, must neither publish `.ended` early nor lose a failure, and
+/// a start that was overtaken must not install a writer afterwards.
+@Suite("Live recording teardown and start races (FEA-105, FEA-106)", .serialized)
+@MainActor
+struct LiveRecordingTeardownTests {
+
+    /// A gate that, once opened, stays open for every waiter.
+    private final class Latch: @unchecked Sendable {
+        private let condition = NSCondition()
+        private var isOpen = false
+        func wait() {
+            condition.lock()
+            while !isOpen { condition.wait() }
+            condition.unlock()
+        }
+        func open() {
+            condition.lock()
+            isOpen = true
+            condition.broadcast()
+            condition.unlock()
+        }
+    }
+
+    private func tempURL() -> URL {
+        FileManager.default.temporaryDirectory.appendingPathComponent("rec-\(UUID().uuidString).ts")
+    }
+
+    private func isRecording(_ state: RecordingState) -> Bool {
+        if case .recording = state { return true }
+        return false
+    }
+
+    private func annexB(_ size: Int, nalType: UInt8) -> [UInt8] {
+        var bytes: [UInt8] = [0x00, 0x00, 0x00, 0x01, nalType]
+        bytes.append(contentsOf: [UInt8](repeating: 0x88, count: max(0, size - bytes.count)))
+        return bytes
+    }
+
+    // MARK: - FEA-105
+
+    @Test("a stop inside a scheduled teardown waits for its drain and publishes its failure")
+    func stopJoinsAScheduledTeardown() async throws {
+        let engine = try AetherEngine()
+        let host = AetherEngine.TestRecordingHost()
+        let url = tempURL()
+        defer { try? FileManager.default.removeItem(at: url) }
+
+        try engine._testStartRecordingWithStubHost(to: url, host: host, ceilingBytes: 4096)
+        let writer = try #require(engine.activeRecording)
+        let gate = Latch()
+        writer.beforeWriteForTesting = { gate.wait() }
+
+        // The first packet enters the held drain, the second breaks the ceiling: the demux thread's
+        // offer is refused and the teardown is scheduled off it.
+        annexB(2000, nalType: 0x65).withUnsafeBytes {
+            writer.accept(packetBytes: $0, sourceStreamIndex: 0, pts: 0, dts: 0, duration: 3000, isKeyframe: true)
+        }
+        annexB(3000, nalType: 0x41).withUnsafeBytes {
+            writer.accept(packetBytes: $0, sourceStreamIndex: 0, pts: 3000, dts: 3000, duration: 3000, isKeyframe: false)
+        }
+        try await waitFor { writer.isClosed }
+
+        engine.endRecordingIfRunning(reason: .stoppedByHost)
+        let publishedEarly = try await waitFor(upTo: .milliseconds(300)) { !self.isRecording(engine.recordingState) }
+        #expect(!publishedEarly, "the file is still being drained, so nothing may claim it closed")
+
+        gate.open()
+        await engine.recordingFinish?.value
+        #expect(engine.recordingState == .failed(.writeTooSlow(bytesWritten: 0, queuedBytesDropped: 3000)))
+        #expect(engine.activeRecording == nil)
+    }
+
+    @Test("a clean stop still ends with .ended")
+    func cleanStopStillEnds() async throws {
+        let engine = try AetherEngine()
+        let host = AetherEngine.TestRecordingHost()
+        let url = tempURL()
+        defer { try? FileManager.default.removeItem(at: url) }
+
+        try engine._testStartRecordingWithStubHost(to: url, host: host)
+        await engine.stopRecording()
+        #expect(engine.recordingState == .ended(.stoppedByHost))
+    }
+
+    // MARK: - FEA-106
+
+    /// Holds `recordingFinish` open the way a slow drain does, and returns the handle that releases it.
+    private func holdPreviousFinish(_ engine: AetherEngine) -> AsyncStream<Void>.Continuation {
+        let (stream, release) = AsyncStream<Void>.makeStream()
+        engine.recordingFinish = Task { for await _ in stream { break } }
+        return release
+    }
+
+    @Test("a start that a stop overtook while it waited does not begin recording")
+    func stopDuringTheStartsWaitCancelsIt() async throws {
+        let engine = try AetherEngine()
+        engine._testSetLiveRoute(isLive: true, route: .loopback)
+        let release = holdPreviousFinish(engine)
+
+        let url = tempURL()
+        let starter = Task { @MainActor in try await engine.startRecording(to: url) }
+        await Task.yield()
+        let stopper = Task { @MainActor in await engine.stopRecording() }
+        await Task.yield()
+
+        release.yield(())
+        release.finish()
+        let outcome = await starter.result
+        await stopper.value
+
+        #expect({ if case .failure(let error) = outcome { return error is CancellationError }; return false }(),
+                "the stop came after the start, so the start must not win: \(outcome)")
+        #expect(engine.activeRecording == nil)
+        #expect(!isRecording(engine.recordingState))
+    }
+
+    @Test("a start that a new load overtook while it waited does not record the new channel")
+    func loadDuringTheStartsWaitCancelsIt() async throws {
+        let engine = try AetherEngine()
+        engine._testSetLiveRoute(isLive: true, route: .loopback)
+        let release = holdPreviousFinish(engine)
+
+        let url = tempURL()
+        let starter = Task { @MainActor in try await engine.startRecording(to: url) }
+        await Task.yield()
+        engine.loadGeneration &+= 1
+
+        release.yield(())
+        release.finish()
+        let outcome = await starter.result
+
+        #expect({ if case .failure(let error) = outcome { return error is CancellationError }; return false }(),
+                "a zap ends the session the start was asked for: \(outcome)")
+        #expect(engine.activeRecording == nil)
+    }
+}

From 004dd76d6389b8bb0842fa27256adbc7b4855717 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 08:58:14 +0200
Subject: [PATCH 193/359] fix(cli): seektest reads its counters under the
 handler lock and exits 1 on a FAIL, smbtest compares against the file (audit
 OPS-104, OPS-105)

seektest copied its tallies and shift arrays without handlerLock while the
engine threads still logged, and returned 0 after printing <-- FAIL or
PRODUCER WEDGE (UNRECOVERED). It now takes one snapshot under the lock and
returns 1 when the #37 bounce, the #38 isSeeking window, the #38 event pair,
an unpaired began or an unrecovered wedge is reported; the restart tallies
stay informational.

smbtest's random-seek check passed vacuously when reads failed (0 and -1
both became empty Data, and two empty reads are equal). The offsets are now
drawn first, the sequential pass records the bytes at each, and every seeked
read must be whole and equal to them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 Sources/aetherctl/SMBTestCommand.swift | 61 +++++++++++++++++++------
 Sources/aetherctl/SeekTest.swift       | 62 ++++++++++++++++++--------
 docs/cli.md                            |  4 +-
 3 files changed, 94 insertions(+), 33 deletions(-)

diff --git a/Sources/aetherctl/SMBTestCommand.swift b/Sources/aetherctl/SMBTestCommand.swift
index 6ce49b6fb..a54c0c0e5 100644
--- a/Sources/aetherctl/SMBTestCommand.swift
+++ b/Sources/aetherctl/SMBTestCommand.swift
@@ -23,6 +23,20 @@ private func smbTestRun(_ args: [String]) async -> Int32 {
         let total = reader.seek(offset: 0, whence: 65536) // AVSEEK_SIZE
         print("connected: \(u.path) size=\(total) bytes")
 
+        // The random-seek offsets are drawn first so the sequential pass can record the bytes that
+        // belong at each of them: the seeked reads are then compared against what the file holds, not
+        // against a second read of the same path (audit OPS-105).
+        struct Probe { let offset: Int64; let length: Int; var reference: [UInt8] }
+        var rng = SystemRandomNumberGenerator()
+        var probes: [Probe] = []
+        if total > 0 {
+            for _ in 0..<randomReads {
+                let off = Int64.random(in: 0..<max(1, total - 16), using: &rng)
+                let length = Int(min(16, total - off))
+                probes.append(Probe(offset: off, length: length, reference: [UInt8](repeating: 0, count: length)))
+            }
+        }
+
         let chunk = 1 << 20 // 1 MiB sequential read
         var buf = [UInt8](repeating: 0, count: chunk)
         var readBytes: Int64 = 0
@@ -31,7 +45,16 @@ private func smbTestRun(_ args: [String]) async -> Int32 {
         while true {
             let n = buf.withUnsafeMutableBufferPointer { reader.read($0.baseAddress, size: Int32(chunk)) }
             if n <= 0 { break }
-            readBytes += Int64(n)
+            let chunkEnd = readBytes + Int64(n)
+            for i in probes.indices {
+                let lo = max(probes[i].offset, readBytes)
+                let hi = min(probes[i].offset + Int64(probes[i].length), chunkEnd)
+                guard lo < hi else { continue }
+                for position in lo..<hi {
+                    probes[i].reference[Int(position - probes[i].offset)] = buf[Int(position - readBytes)]
+                }
+            }
+            readBytes = chunkEnd
         }
         let seqElapsed = ProcessInfo.processInfo.systemUptime - seqStart
         let mibps = seqElapsed > 0 ? Double(readBytes) / 1_048_576.0 / seqElapsed : 0
@@ -42,18 +65,23 @@ private func smbTestRun(_ args: [String]) async -> Int32 {
             return 1
         }
 
-        // Random-seek correctness: two reads at each random offset must agree (deterministic content).
-        var rng = SystemRandomNumberGenerator()
-        for _ in 0..<randomReads {
-            let off = Int64.random(in: 0..<max(1, total - 16), using: &rng)
-            let a = smbReadAt(reader, off, 16)
-            let b = smbReadAt(reader, off, 16)
-            if a != b {
-                print("FAIL: random reads at \(off) disagree")
-                return 1
+        // Random-seek correctness: each seeked read must come back whole and equal to the bytes the
+        // sequential pass saw at that offset. A failed read is 0 or -1 bytes, which used to compare
+        // equal to another failed read.
+        for probe in probes {
+            for attempt in 1...2 {
+                let got = smbReadAt(reader, probe.offset, probe.length)
+                guard got.count == probe.length else {
+                    print("FAIL: random read \(attempt) at \(probe.offset) returned \(got.count) of \(probe.length) bytes")
+                    return 1
+                }
+                guard [UInt8](got) == probe.reference else {
+                    print("FAIL: random read \(attempt) at \(probe.offset) differs from the sequential pass")
+                    return 1
+                }
             }
         }
-        print("random-seek: \(randomReads) offsets consistent")
+        print("random-seek: \(probes.count) offsets match the sequential pass")
 
         reader.close()
         let wall = ProcessInfo.processInfo.systemUptime - started
@@ -65,11 +93,18 @@ private func smbTestRun(_ args: [String]) async -> Int32 {
     }
 }
 
+/// Reads until `length` bytes arrived, so a legitimate short read is not taken for a failure; a read that
+/// returns 0 (EOF) or -1 (error) ends it short, and the caller sees the shortfall.
 private func smbReadAt(_ reader: SMBIOReader, _ offset: Int64, _ length: Int) -> Data {
     _ = reader.seek(offset: offset, whence: Int32(SEEK_SET))
+    var out = Data()
     var buf = [UInt8](repeating: 0, count: length)
-    let n = buf.withUnsafeMutableBufferPointer { reader.read($0.baseAddress, size: Int32(length)) }
-    return Data(buf.prefix(Int(max(n, 0))))
+    while out.count < length {
+        let n = buf.withUnsafeMutableBufferPointer { reader.read($0.baseAddress, size: Int32(length - out.count)) }
+        if n <= 0 { break }
+        out.append(contentsOf: buf.prefix(Int(n)))
+    }
+    return out
 }
 
 private func smbParseIntFlag(_ args: [String], _ flag: String) -> Int? {
diff --git a/Sources/aetherctl/SeekTest.swift b/Sources/aetherctl/SeekTest.swift
index 662a82ebe..a61a33cc6 100644
--- a/Sources/aetherctl/SeekTest.swift
+++ b/Sources/aetherctl/SeekTest.swift
@@ -163,13 +163,17 @@ private func seekTestRun(url: URL, seeks: Int, gapMs: Int, settleSeconds: Double
     }
     let sawSeeking = probes.contains { $0.seeking }
     let endedCleared = !(probes.last?.seeking ?? true)
+    // A line printed "<-- FAIL" has to reach the exit code too: nothing else a script can gate on (audit OPS-104).
+    var failures: [String] = []
     print("")
     print("=== #37/#38 PROBE (single backward seek, concurrent sampler) ===")
     print(String(format: "  preSeek=%.1f target=%.1f tol=%.1f samples=%d", preSeekCt, probeLo, tol, probes.count))
     print("  #37 clock bounce back through pre-seek after reaching target: "
           + (bounceAfterTarget ? "YES  <-- FAIL" : "no  <-- PASS"))
+    if bounceAfterTarget { failures.append("#37 clock bounce") }
     print("  #38 isSeeking observed in-flight=\(sawSeeking ? "yes" : "NO") ended-cleared=\(endedCleared ? "yes" : "NO")  "
           + ((sawSeeking && endedCleared) ? "<-- PASS" : "<-- FAIL"))
+    if !(sawSeeking && endedCleared) { failures.append("#38 isSeeking window") }
     // #38 follow-up: the falling edge alone cannot say what happened; the probe seek must produce a
     // .began and a matching .landed, and that landing must name a position at the target.
     let probeSeekEvents = seekEvents.value.filter { $0.origin == .programmatic }
@@ -184,6 +188,7 @@ private func seekTestRun(url: URL, seeks: Int, gapMs: Int, settleSeconds: Double
     print("  #38 event pair: \(probeBegan.map { "began@\(String(format: "%.1f", $0.target))" } ?? "NONE") -> "
           + (probeTerminator.map { "\($0)" } ?? "NO TERMINATOR")
           + "  " + (probeLandedAtTarget ? "<-- PASS" : "<-- FAIL"))
+    if !probeLandedAtTarget { failures.append("#38 seek event pair") }
 
     struct Sample { let wall: Double; let ct: Double; let src: Double; let playing: Bool }
     var samples: [Sample] = []
@@ -260,10 +265,23 @@ private func seekTestRun(url: URL, seeks: Int, gapMs: Int, settleSeconds: Double
     let finalCt = samples.last?.ct ?? engine.currentTime
     let settleError = abs(finalCt - finalTarget)
 
-    let fullRestart   = tally.value["fullRestart"]   ?? 0
-    let coalesced     = tally.value["coalesced"]     ?? 0
-    let settleAdvance = tally.value["settleAdvance"] ?? 0
-    let abandon       = tally.value["abandon"]       ?? 0
+    // The log handler keeps appending from engine threads until `engine.stop()` below, and it mutates
+    // these under `handlerLock`: read them once under the same lock and report from the copy (audit OPS-104).
+    let counters: (tally: [String: Int], publishedShifts: [Double], gateOpenShifts: [Int],
+                   ledgerCount: Int, maxLedgerDriftAbs: Double, parkCount: Int,
+                   liveConsumerParkCount: Int, wedgeBrokenCount: Int, reanchorCount: Int,
+                   seekReconcileCount: Int) = {
+        handlerLock.lock()
+        defer { handlerLock.unlock() }
+        return (tally.value, publishedShifts.value, gateOpenShifts.value, ledgerCount.value,
+                maxLedgerDriftAbs.value, parkCount.value, liveConsumerParkCount.value,
+                wedgeBrokenCount.value, reanchorCount.value, seekReconcileCount.value)
+    }()
+
+    let fullRestart   = counters.tally["fullRestart"]   ?? 0
+    let coalesced     = counters.tally["coalesced"]     ?? 0
+    let settleAdvance = counters.tally["settleAdvance"] ?? 0
+    let abandon       = counters.tally["abandon"]       ?? 0
 
     print("")
     print("=== SEEKTEST RESULTS ===")
@@ -285,8 +303,8 @@ private func seekTestRun(url: URL, seeks: Int, gapMs: Int, settleSeconds: Double
     print("  full restarts for the same burst; 'abandoned' should trend to 0.")
 
     // #65 discriminator: did the producer shift VARY across the burst's restart epochs?
-    let pubShifts = publishedShifts.value
-    let rawShifts = gateOpenShifts.value
+    let pubShifts = counters.publishedShifts
+    let rawShifts = counters.gateOpenShifts
     let distinctPub = Set(pubShifts.map { ($0 * 1000).rounded() / 1000 })
     let distinctRaw = Set(rawShifts)
     print("")
@@ -296,11 +314,11 @@ private func seekTestRun(url: URL, seeks: Int, gapMs: Int, settleSeconds: Double
                  "[" + pubShifts.map { String(format: "%.3f", $0) }.joined(separator: ", ") + "]",
                  distinctPub.count))
     print("  clockLead settle = \(String(format: "%.2f", settleClockLead))s  (headless ~0 by design; #65 is presented-vs-clock, invisible to ct-src)")
-    print("  ledger segments opened = \(ledgerCount.value)  maxContentDrift = \(String(format: "%.3f", maxLedgerDriftAbs.value))s  (the POSITIVE Root-B signal)")
-    print("  abnormal backpressure parks (VOD wedge signature) = \(parkCount.value)"
-          + "  (of those, \(liveConsumerParkCount.value) with the consumer still fetching, AE#528)")
-    print("  #65 FIX signals: wedge breaks=\(wedgeBrokenCount.value)  producer re-anchors=\(reanchorCount.value)  seek-deadline reconciles=\(seekReconcileCount.value)")
-    let fixEngaged = wedgeBrokenCount.value > 0 || reanchorCount.value > 0 || seekReconcileCount.value > 0
+    print("  ledger segments opened = \(counters.ledgerCount)  maxContentDrift = \(String(format: "%.3f", counters.maxLedgerDriftAbs))s  (the POSITIVE Root-B signal)")
+    print("  abnormal backpressure parks (VOD wedge signature) = \(counters.parkCount)"
+          + "  (of those, \(counters.liveConsumerParkCount) with the consumer still fetching, AE#528)")
+    print("  #65 FIX signals: wedge breaks=\(counters.wedgeBrokenCount)  producer re-anchors=\(counters.reanchorCount)  seek-deadline reconciles=\(counters.seekReconcileCount)")
+    let fixEngaged = counters.wedgeBrokenCount > 0 || counters.reanchorCount > 0 || counters.seekReconcileCount > 0
     if fixEngaged {
         print("  >> #65 FIX ENGAGED: the VOD wedge breaker / seek-deadline reconcile fired during the burst. A")
         print("     non-zero break+re-anchor with playback resuming afterward (clock advancing, no sustained PARK")
@@ -310,28 +328,29 @@ private func seekTestRun(url: URL, seeks: Int, gapMs: Int, settleSeconds: Double
         print("  >> INCONCLUSIVE: 0 producer restarts. The file was fully produced before the burst, so")
         print("     every seek hit the cache and the cross-epoch cascade never fired. Re-run with a LONGER")
         print("     file (seek targets must land beyond the producer write head) to exercise #65.")
-    } else if maxLedgerDriftAbs.value >= 0.5 {
+    } else if counters.maxLedgerDriftAbs >= 0.5 {
         print("  >> ROOT B CONFIRMED (content-vs-clock): a segment was muxed with source content offset")
-        print("     \(String(format: "%.2f", maxLedgerDriftAbs.value))s from its planned/EXTINF position, so the presented frame leads the")
+        print("     \(String(format: "%.2f", counters.maxLedgerDriftAbs))s from its planned/EXTINF position, so the presented frame leads the")
         print("     clock by that much. Fix the content-drift source (off-plan seek landing / uniform-plan stride),")
         print("     NOT a seam port. Grep '#65 ledger' for the exact seg/epoch.")
     } else if distinctRaw.count > 1 || distinctPub.count > 1 {
         print("  >> ROOT A (cross-epoch shift divergence): the producer published MORE THAN ONE shift across")
         print("     the burst. Buffered bytes from a superseded epoch fold with the latest scalar -> picture")
         print("     leads the clock. The live seam-history port is the fix.")
-    } else if parkCount.value > 0, parkCount.value == liveConsumerParkCount.value, !fixEngaged {
-        print("  >> PARKED BEHIND A LIVE CONSUMER (not a wedge): \(parkCount.value) park(s), every one of them")
+    } else if counters.parkCount > 0, counters.parkCount == counters.liveConsumerParkCount, !fixEngaged {
+        print("  >> PARKED BEHIND A LIVE CONSUMER (not a wedge): \(counters.parkCount) park(s), every one of them")
         print("     logged idle=0s, so the consumer kept declaring fetch targets or kept rendering the whole")
         print("     time. The breaker staying quiet here is AE#528 working; a wedge is a park whose idle= climbs.")
-    } else if parkCount.value > 0 {
+    } else if counters.parkCount > 0 {
         if fixEngaged {
-            print("  >> PRODUCER WEDGE DETECTED AND BROKEN: \(parkCount.value) abnormal park(s) but the breaker fired")
-            print("     (\(wedgeBrokenCount.value) break(s), \(reanchorCount.value) re-anchor(s), \(seekReconcileCount.value) seek reconcile(s)).")
+            print("  >> PRODUCER WEDGE DETECTED AND BROKEN: \(counters.parkCount) abnormal park(s) but the breaker fired")
+            print("     (\(counters.wedgeBrokenCount) break(s), \(counters.reanchorCount) re-anchor(s), \(counters.seekReconcileCount) seek reconcile(s)).")
             print("     This is the #65 fix recovering the livelock; verify on device that playback actually resumes.")
         } else {
-            print("  >> PRODUCER WEDGE (UNRECOVERED): invariant shift AND ~zero ledger drift, but \(parkCount.value) abnormal")
+            print("  >> PRODUCER WEDGE (UNRECOVERED): invariant shift AND ~zero ledger drift, but \(counters.parkCount) abnormal")
             print("     backpressure park(s) and the breaker did NOT fire. The 6s symptom is the frozen-clock/stall")
             print("     artifact. Either the park stayed under the break threshold or the fix is not in this build.")
+            failures.append("producer wedge unrecovered")
         }
     } else {
         print("  >> NO ENGINE-LEVEL DIVERGENCE REPRODUCED: invariant shift, ledger drift ~0, no wedge. The headless")
@@ -359,6 +378,7 @@ private func seekTestRun(url: URL, seeks: Int, gapMs: Int, settleSeconds: Double
           + "late-landings=\(lateLandings.count)")
     let unpaired = begun.subtracting(terminated).sorted()
     print("  unpaired begans: " + (unpaired.isEmpty ? "none  <-- PASS" : "\(unpaired)  <-- FAIL"))
+    if !unpaired.isEmpty { failures.append("unpaired seek begans \(unpaired)") }
     // AE#534: began -> first terminal, per seek, in issue order. Quote the median and the MAX: the
     // read this measures is an XPC round trip to a media server that is least likely to answer during
     // a seek, so a mean would bury exactly the case the question is about.
@@ -379,6 +399,10 @@ private func seekTestRun(url: URL, seeks: Int, gapMs: Int, settleSeconds: Double
     }
     for event in events.suffix(12) { print("    \(event)") }
     print("")
+    if !failures.isEmpty {
+        print("VERDICT: seektest FAIL: " + failures.joined(separator: "; "))
+        return 1
+    }
     print("VERDICT: seektest DONE (comparison harness; compare tallies old vs new build)")
     return 0
 }
diff --git a/docs/cli.md b/docs/cli.md
index 3ed1621b0..40eadca3b 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -740,6 +740,8 @@ Note that the slicing is byte-based, not keyframe-aligned, so segments start mid
 
 Drives a real AVPlayer (native loopback-HLS path) through a burst of rapid seeks and reports the producer-restart coalescing behavior, the longest "wedge" (state `.playing` but the clock frozen), and final settle accuracy (AetherEngine#35). A concurrent sampler probe also checks the seek clock-bounce / `isSeeking` signal (AetherEngine#37 / #38): a single backward seek must not bounce the clock back through the pre-seek position, and `isSeeking` must span the real landing. The run ends with a `#38 SEEK EVENT LEDGER`: every `.began` must reach a terminal event (an unpaired one is a stranded in-flight window), and `.stalled` seeks are listed with any late `.landed` that followed them. The ledger also prints **seek latency** (`.began` to its first terminal event, per seek, with min / median / max), which is what an A/B about the cost of work ON the seek path is read off: quote the median and the max, never a mean, because the tail belongs to the source rather than to the change under test. Note the burst is serialised, so every seek here terminates before the next is issued; to put a seek on top of an unsettled one use `play --seek-every 1 --seek-count N` against an origin below media rate, where `phase=seeking` holds across the run and the ledger shows supersedes. `--seeks N`, `--gap-ms N`, `--settle N` shape the burst; needs `> 30 s` of seekable VOD. `--throttle-kbps N` caps source-IO delivery to simulate a slow CDN and force rebuffers during the burst (see `serve`).
 
+The exit code is 1 when a printed `<-- FAIL` line is among the `#37` bounce, the `#38` `isSeeking` window, the `#38` event pair and the unpaired-`began` ledger, or when the `#65` block ends in `PRODUCER WEDGE (UNRECOVERED)`, and the final `VERDICT` line then names them. The restart tallies stay informational: they are for comparing two builds, and a run that only prints them exits 0.
+
 The `#65` block of the results separates two parks that look alike in a log and mean opposite things (AE#528). A park whose `PARK` line reads `stuck=0s` is backpressure behind a consumer that is still declaring fetch targets, which is what a viewer scrubbing backwards through resident content looks like, and the wedge breaker staying quiet there is correct. `stuck=` counts the seconds since the consumer last declared a target and `idle=` only those in which it did not render either, and the breaker trips on `idle=` (AE#649): a park that reads `(consumer quiet, still playing)` with `stuck=` climbing and `idle=0s` is AVPlayer playing out a deep forward buffer between fetch bursts, which a cellular iPhone does for up to a minute at a time, and it does not break either. When every park of the run logged `idle=0s`, the run says `PARKED BEHIND A LIVE CONSUMER (not a wedge)`. A wedge is a park whose `idle=` climbs, and that one still breaks and re-anchors.
 
 ## hlslive
@@ -748,7 +750,7 @@ Replays a synthetic SSAI ad-pod feed through the live-direct-play path to repro
 
 ## smbtest
 
-Connects to an SMB2/3 share with `SMBConnection` (SMBClient backend), wraps the file in `SMBIOReader`, and runs a sequential-throughput pass plus a random-seek consistency check. macOS-only; needs the optional `AetherEngineSMB` product (`swift build --product aetherctl` pulls it in). Validates the SMB byte source without a device:
+Connects to an SMB2/3 share with `SMBConnection` (SMBClient backend), wraps the file in `SMBIOReader`, and runs a sequential-throughput pass plus a random-seek check: the offsets are drawn first, the sequential pass records the 16 bytes at each, and every seeked read must come back whole and equal to those bytes (a failed or short read fails the run). macOS-only; needs the optional `AetherEngineSMB` product (`swift build --product aetherctl` pulls it in). Validates the SMB byte source without a device:
 
 ```bash
 swift run aetherctl smbtest "smb://user:pass@host/share/path/to/file.mkv" --reads 128

From d2aff5505d23ec7e72b4eed1c8b1b297055809f3 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 08:58:48 +0200
Subject: [PATCH 194/359] perf(live): spool the software DVR ring into chunk
 files with a byte budget (audit PERF-101, SEG-106, VPERF-101, SEG-105)

The ring wrote one atomically renamed file per packet and kept a URL per
index entry. Measured on the test harness (debug build, 100k packets of
12 KB, infinite window): 266 MB of index heap, 100k files, 314 us per
append and 58 us per mapped read. It also evicted by time only and only
after a successful write, so a full volume froze the live feeder for good.

Now packets append into ~4 MB chunk files through pwrite, the index is a
flat 24-byte record per packet in a head-offset ring, reads are pread on a
small LRU of chunk descriptors (an unlinked chunk stays readable for a
reader already holding it), and eviction walks the keyframe list instead of
the packet list. Same 100k packets: 4 MB index, 288 files, 28-45 us per
append, 3-28 us per read.

- The host arms the ring with the native path's retention funnel
  (min(2 GiB, a quarter of the tmp volume), at least 64 MiB), so a long
  window on a small volume or a high bitrate shrinks instead of filling the
  disk, and an infinite window is bounded too.
- A failed write evicts up to the first keyframe in a later chunk (or
  replaces a single-chunk span when the incoming packet is a keyframe) and
  retries once before dropping the packet.
- The ring's resident floor is published on the software live route, so the
  seekable range follows what the ring still holds.
- The audio pump and the feeder skip the other stream's packets through an
  index-only isVideo(atSeq:), and the host appends straight from the
  AVPacket memory, which removes one map per packet and one copy plus one
  allocation per appended packet.
- The ring directory holds the same flock marker as SegmentCache (shared
  SessionDirectoryLiveness), so the cache's stale sweep no longer deletes a
  live ring an hour into a session.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 Sources/AetherEngine/AetherEngine+Live.swift  |   2 +-
 .../Native/SoftwarePlaybackHost.swift         |  45 +-
 Sources/AetherEngine/PlayerState.swift        |   2 +-
 .../AetherEngine/Video/PacketRingBuffer.swift | 531 +++++++++++++++---
 Sources/AetherEngine/Video/SegmentCache.swift |  46 +-
 .../Video/SessionDirectoryLiveness.swift      |  50 ++
 .../PacketRingBufferBehaviourTests.swift      | 193 +++++++
 .../PacketRingBufferChunkSpoolTests.swift     | 383 +++++++++++++
 docs/api.md                                   |   4 +-
 docs/architecture.md                          |   3 +-
 10 files changed, 1133 insertions(+), 126 deletions(-)
 create mode 100644 Sources/AetherEngine/Video/SessionDirectoryLiveness.swift
 create mode 100644 Tests/AetherEngineTests/PacketRingBufferBehaviourTests.swift
 create mode 100644 Tests/AetherEngineTests/PacketRingBufferChunkSpoolTests.swift

diff --git a/Sources/AetherEngine/AetherEngine+Live.swift b/Sources/AetherEngine/AetherEngine+Live.swift
index ba596fab2..fcd45fcd1 100644
--- a/Sources/AetherEngine/AetherEngine+Live.swift
+++ b/Sources/AetherEngine/AetherEngine+Live.swift
@@ -453,7 +453,7 @@ extension AetherEngine {
         guard var w = liveWindow else { return }
         w.noteEdge(edgeSessionTime)
         w.notePlayhead(currentTime)
-        w.noteResidentFloor(residentLiveFloorSessionSeconds())
+        w.noteResidentFloor(residentLiveFloorSessionSeconds() ?? softwareHost?.dvrResidentFloorSessionSeconds)
         // Sodalite#104 round 4: the cadence the playlist declares, which outranks how the source
         // happened to deliver. nil on the paths that serve no playlist of ours.
         w.noteTargetDuration(liveTargetDurationSeconds)
diff --git a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
index 7cf6dd858..c0bb9e941 100644
--- a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
+++ b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
@@ -319,6 +319,17 @@ final class SoftwarePlaybackHost {
         return max(0, newestSourcePts - sessionStartPts)
     }
 
+    /// The DVR ring's rewind floor on the session axis once byte or time eviction has moved it past
+    /// the start; nil before that and when no ring is armed. Published as the resident floor so the
+    /// seekable range follows what the ring still holds (audit VPERF-101).
+    nonisolated var dvrResidentFloorSessionSeconds: Double? {
+        guard let ring = dvrRing else { return nil }
+        liveEdgeLock.lock()
+        let start = sessionStartPts
+        liveEdgeLock.unlock()
+        return ring.residentFloorSessionSeconds(sessionStartPts: start)
+    }
+
     // MARK: - Live reader/feeder split (DVR sessions)
     //
     // DVR live sessions: reader (demuxQueue) fills ring regardless of play/pause; feeder (feedQueue) decodes from ring cursor with renderer back-pressure.
@@ -762,8 +773,13 @@ final class SoftwarePlaybackHost {
             let scratch = baseDir.appendingPathComponent("dvr-\(UUID().uuidString)", isDirectory: true)
             do {
                 try FileManager.default.createDirectory(at: scratch, withIntermediateDirectories: true)
-                self.dvrRing = try PacketRingBuffer(windowSeconds: window, scratch: scratch)
-                EngineLog.emit("[SWHost] DVR ring armed window=\(String(format: "%.0f", window))s scratch=\(scratch.lastPathComponent)", category: .swPlayback)
+                // Audit VPERF-101: the same allowance the native path gives this session, so a long
+                // window on a small volume shrinks instead of filling the disk.
+                let available = (try? baseDir.resourceValues(forKeys: [.volumeAvailableCapacityKey]))?
+                    .volumeAvailableCapacity.map(Int64.init)
+                let budget = PacketRingBuffer.liveByteBudget(volumeAvailableBytes: available)
+                self.dvrRing = try PacketRingBuffer(windowSeconds: window, scratch: scratch, byteBudget: budget)
+                EngineLog.emit("[SWHost] DVR ring armed window=\(String(format: "%.0f", window))s budget=\(budget >> 20)MiB scratch=\(scratch.lastPathComponent)", category: .swPlayback)
             } catch {
                 EngineLog.emit("[SWHost] DVR ring create failed (\(error)); live-only fallback", category: .swPlayback)
                 self.dvrRing = nil
@@ -2005,11 +2021,11 @@ final class SoftwarePlaybackHost {
                     noteEdge(ptsSec)
                     playedMedia?.record(isVideo ? .video : .audio, pts: ptsSec, bytes: Int(packet.pointee.size))
                     if let data = packet.pointee.data, packet.pointee.size > 0 {
-                        let bytes = Data(bytes: data, count: Int(packet.pointee.size))
                         let isKey = isVideo && (packet.pointee.flags & AV_PKT_FLAG_KEY) != 0
                         // Best-effort: a write failure just shrinks the
                         // rewind window, it must not stall the reader.
-                        try? ring.append(pts: ptsSec, isKeyframe: isKey, isVideo: isVideo, bytes: bytes)
+                        try? ring.append(pts: ptsSec, isKeyframe: isKey, isVideo: isVideo,
+                                         bytes: UnsafeRawBufferPointer(start: data, count: Int(packet.pointee.size)))
                         condition.lock()
                         condition.broadcast()
                         condition.unlock()
@@ -2085,13 +2101,10 @@ final class SoftwarePlaybackHost {
                     clockSeconds: aOut.currentTimeSeconds
                 ) == .feed else { return false }
                 guard seq < ring.seqBounds.end else { return false }  // live edge: nothing to pump yet
-                guard let pkt = ring.packet(atSeq: seq) else {
-                    // Evicted/unreadable under the pump: skip, same as the combined loop.
-                    guard audioLookahead.advance(from: seq, fedPTS: nil) else { return false }
-                    seq += 1
-                    return true
-                }
-                if pkt.isVideo {
+                // Audit PERF-101: the kind is in the index, so the video packets this pump skips are
+                // never read off the disk (the feeder reads each of them once, for decode).
+                guard ring.isVideo(atSeq: seq) == false, let pkt = ring.packet(atSeq: seq) else {
+                    // Video, or evicted/unreadable under the pump: skip, same as the combined loop.
                     guard audioLookahead.advance(from: seq, fedPTS: nil) else { return false }
                     seq += 1
                     return true
@@ -2206,6 +2219,12 @@ final class SoftwarePlaybackHost {
                 clampCursor(cursor, bounds.first)
                 return true
             }
+            // Audio the pump already delivered: consume the slot without reading it back, the
+            // pump read it once already (audit PERF-101).
+            if cursor < audioLookahead.current, ring.isVideo(atSeq: cursor) == false {
+                advanceCursor(cursor)
+                return true
+            }
             guard let pkt = ring.packet(atSeq: cursor) else {
                 // Resident entry whose file read failed (disk hiccup,
                 // pruned mid-read): skip it, or the feeder would spin on
@@ -2783,13 +2802,13 @@ final class SoftwarePlaybackHost {
                         if let ring {
                             let isKey = isVideo && (packet.pointee.flags & AV_PKT_FLAG_KEY) != 0
                             if let data = packet.pointee.data, packet.pointee.size > 0 {
-                                let bytes = Data(bytes: data, count: Int(packet.pointee.size))
                                 // Append is a small file write; off-main and
                                 // internally locked, so it never touches the
                                 // decoders' state. Best-effort: a write failure
                                 // just shrinks the rewind window, it must not
                                 // stall live playback.
-                                try? ring.append(pts: ptsSec, isKeyframe: isKey, isVideo: isVideo, bytes: bytes)
+                                try? ring.append(pts: ptsSec, isKeyframe: isKey, isVideo: isVideo,
+                                                 bytes: UnsafeRawBufferPointer(start: data, count: Int(packet.pointee.size)))
                             }
                         }
                     }
diff --git a/Sources/AetherEngine/PlayerState.swift b/Sources/AetherEngine/PlayerState.swift
index 5954fba61..c21c89c7f 100644
--- a/Sources/AetherEngine/PlayerState.swift
+++ b/Sources/AetherEngine/PlayerState.swift
@@ -528,7 +528,7 @@ public struct LoadOptions: Sendable, Equatable {
     /// Lean audio-only path (FFmpeg + AVSampleBufferAudioRenderer): skips video probe, display-criteria handshake, HLS/muxer/loopback stack. Also set automatically when the probe finds no video stream. Default `false`.
     public var audioOnly: Bool
 
-    /// DVR rewind window in seconds; nil = live-only (seek is a no-op). Engine retains roughly this much past content disk-backed. Suggested default: 1800. Ignored when `isLive == false`. Default nil.
+    /// DVR rewind window in seconds; nil = live-only (seek is a no-op). Engine retains roughly this much past content disk-backed, bounded by the session disk budget (a quarter of the free space, at most 2 GiB), so a long window on a high-bitrate channel or a small volume holds less than it asks for. Suggested default: 1800. Ignored when `isLive == false`. Default nil.
     public var dvrWindowSeconds: Double?
 
     /// LL-HLS blocking-reload (`#EXT-X-SERVER-CONTROL:CAN-BLOCK-RELOAD`) override for live loopback sessions.
diff --git a/Sources/AetherEngine/Video/PacketRingBuffer.swift b/Sources/AetherEngine/Video/PacketRingBuffer.swift
index ea7f4872b..35fc3a342 100644
--- a/Sources/AetherEngine/Video/PacketRingBuffer.swift
+++ b/Sources/AetherEngine/Video/PacketRingBuffer.swift
@@ -1,13 +1,21 @@
+import Darwin
 import Foundation
 
-/// Keyframe-indexed disk-spooled DVR ring buffer. Eviction is keyframe-aligned (retained span always starts at a decodable keyframe). Bytes stored as flat files under a scratch dir; in-RAM index holds only metadata; `Data(contentsOf:,.alwaysMapped)` keeps RSS flat. NSLock guards the index (demux-thread appends, seek-thread reads).
-// Thread-safe: all mutable state is guarded by `lock` (NSLock), so it is safe to share across the
-// demux/seek/feeder threads and capture in @Sendable closures.
+/// Keyframe-indexed disk-spooled DVR ring buffer. Eviction is keyframe-aligned (once the ring has
+/// evicted, the retained span starts at a decodable keyframe). Packet bytes are appended into a few
+/// large chunk files under a scratch dir; the in-RAM index holds one 24-byte record per packet.
+///
+/// Audit PERF-101 / SEG-106: this used to write one atomically renamed file per packet and keep a
+/// heap `URL` per index entry (554-586 B per entry measured, ~230 MB of index at a 90 min window, and
+/// ~305 us of file work per packet). Audit VPERF-101: eviction was by time only and ran only after a
+/// successful write, so a full disk stopped the ring, and with it the software live feeder, for good.
+// Thread-safe: `lock` guards the index, the chunk table and the read-handle cache; `writeLock`
+// serializes appends (tail chunk, tail offset). Lock order: writeLock, then lock.
 final class PacketRingBuffer: @unchecked Sendable {
 
     // MARK: - Public types
 
-    /// A single packet as returned by `packets(fromPts:)`.
+    /// A single packet as returned by `packet(atSeq:)` and `packets(fromPts:)`.
     struct Packet {
         let pts: Double
         let isKeyframe: Bool
@@ -15,34 +23,113 @@ final class PacketRingBuffer: @unchecked Sendable {
         let bytes: Data
     }
 
+    /// Writes all of `bytes` at `offset` or throws. Injectable so tests can fill the disk.
+    typealias WriteAll = @Sendable (_ fd: Int32, _ bytes: UnsafeRawBufferPointer, _ offset: off_t) throws -> Void
+
+    enum Failure: Error, Equatable {
+        case closed
+        case packetTooLarge
+        case capacityExceeded
+    }
+
+    /// The software live route plays FROM this ring, so it is a playback buffer before it is seek
+    /// history: the quarter-of-free-space retention rule may read 0 on a nearly full volume, and a
+    /// ring that small evicts packets before the feeder reaches them. A disk that is really full is
+    /// handled by the evict-and-retry in `append`.
+    static let minimumLiveByteBudget = 64 << 20
+
+    /// The native path's retention funnel (min(2 GiB, a quarter of free space)) with the live floor.
+    static func liveByteBudget(volumeAvailableBytes: Int64?, capRelaxed: Bool = false) -> Int {
+        max(minimumLiveByteBudget,
+            HLSVideoEngine.sessionRetentionBudgetBytes(volumeAvailableBytes: volumeAvailableBytes,
+                                                       capRelaxed: capRelaxed))
+    }
+
     // MARK: - Private types
 
-    private struct Entry {
+    struct Entry {
         let pts: Double
-        let isKeyframe: Bool
-        let isVideo: Bool
-        let fileURL: URL
-        let byteCount: Int
+        let offset: UInt32
+        let length: UInt32
+        let chunk: UInt32
+        let flags: UInt8
+
+        static let keyframeFlag: UInt8 = 1
+        static let videoFlag: UInt8 = 2
+        var isKeyframe: Bool { flags & Self.keyframeFlag != 0 }
+        var isVideo: Bool { flags & Self.videoFlag != 0 }
+    }
+
+    /// Closed when the last holder lets go, so a reader that picked a handle up under the lock can
+    /// finish its `pread` on a chunk that eviction unlinked meanwhile.
+    private final class ChunkHandle: @unchecked Sendable {
+        let id: UInt32
+        let fd: Int32
+        init(id: UInt32, fd: Int32) {
+            self.id = id
+            self.fd = fd
+        }
+        deinit { Darwin.close(fd) }
+    }
+
+    private struct ChunkRecord {
+        let id: UInt32
+        var bytes: Int
     }
 
     // MARK: - State
 
     private let lock = NSLock()
+    private let writeLock = NSLock()
     private let windowSeconds: Double
+    private let byteBudget: Int
+    private let chunkTargetBytes: Int
     private let scratch: URL
+    private let writeAll: WriteAll
 
+    /// The retained span is `entries[head...]`; the dead prefix is compacted away in batches.
     private var entries: [Entry] = []
-    /// Sequence number of `entries[0]`; eviction advances this instead of renumbering. Feeder cursor below `firstSeq` = fell out of window.
+    private var head = 0
+    /// Sequence number of `entries[head]`; eviction advances this instead of renumbering. Feeder cursor below `firstSeq` = fell out of window.
     private var firstSeq: Int = 0
-    private var counter: Int = 0
+    /// Absolute sequence numbers of retained keyframes, `keyframeSeqs[keyframeHead...]`. One per GOP,
+    /// so eviction and keyframe lookups walk GOPs instead of packets.
+    private var keyframeSeqs: [Int] = []
+    private var keyframeHead = 0
     private var edge: Double = -.infinity
     private var closed: Bool = false
+    /// Oldest first; the last record is the chunk the writer appends to.
+    private var chunks: [ChunkRecord] = []
+    private var retainedDiskBytes = 0
+    /// Most recently used first, at most `readHandleCap`. Opening a descriptor per retained chunk
+    /// would hold hundreds at a 2 GiB budget.
+    private var readHandles: [ChunkHandle] = []
+    private static let readHandleCap = 4
+    /// Audit SEG-105: the ring's directory sits beside the segment cache's under `aether-segments/`
+    /// and must read as live to its stale sweep.
+    private var markerFD: Int32 = -1
+
+    // Writer state, guarded by `writeLock`.
+    private var tail: ChunkHandle?
+    private var tailOffset = 0
+    private var nextChunkID: UInt32 = 0
 
     // MARK: - Init / close
 
-    init(windowSeconds: Double, scratch: URL) throws {
+    init(windowSeconds: Double, scratch: URL, byteBudget: Int = .max,
+         chunkTargetBytes: Int = 4 << 20, writeAll: WriteAll? = nil) throws {
         self.windowSeconds = windowSeconds
         self.scratch = scratch
+        self.byteBudget = max(0, byteBudget)
+        // Several chunks per budget, so evicting the oldest one frees a fraction of it, not all.
+        let target = min(chunkTargetBytes, max(64 << 10, self.byteBudget / 16))
+        self.chunkTargetBytes = max(1, min(target, Int(UInt32.max / 2)))
+        self.writeAll = writeAll ?? Self.pwriteAll
+        self.markerFD = SessionDirectoryLiveness.acquire(sessionDir: scratch, logPrefix: "[PacketRingBuffer]")
+    }
+
+    deinit {
+        if markerFD >= 0 { Darwin.close(markerFD) }
     }
 
     /// Idempotent teardown. State is cleared synchronously so the ring is immediately
@@ -52,33 +139,80 @@ final class PacketRingBuffer: @unchecked Sendable {
         lock.lock()
         guard !closed else { lock.unlock(); return }
         closed = true
-        entries.removeAll(keepingCapacity: false)
-        edge = -.infinity
-        counter = 0
+        entries = []
+        head = 0
         firstSeq = 0
+        keyframeSeqs = []
+        keyframeHead = 0
+        edge = -.infinity
+        chunks = []
+        retainedDiskBytes = 0
+        readHandles = []
+        let marker = markerFD
+        markerFD = -1
         lock.unlock()
 
         DispatchQueue.global(qos: .userInitiated).async { [scratch] in
             try? FileManager.default.removeItem(at: scratch)
+            // Released after the removal, so the directory reads live until it is gone.
+            if marker >= 0 { Darwin.close(marker) }
         }
     }
 
     // MARK: - Writer
 
     func append(pts: Double, isKeyframe: Bool, isVideo: Bool, bytes: Data) throws {
-        let fileURL = scratch.appendingPathComponent("pkt-\(nextCounter()).bin")
-        try bytes.write(to: fileURL, options: [.atomic])
-        let entry = Entry(pts: pts, isKeyframe: isKeyframe, isVideo: isVideo, fileURL: fileURL, byteCount: bytes.count)
+        try bytes.withUnsafeBytes { raw in
+            try append(pts: pts, isKeyframe: isKeyframe, isVideo: isVideo, bytes: raw)
+        }
+    }
+
+    /// Takes the packet's memory as is, so the host appends straight from the `AVPacket` without an
+    /// intermediate copy.
+    func append(pts: Double, isKeyframe: Bool, isVideo: Bool, bytes: UnsafeRawBufferPointer) throws {
+        guard bytes.count <= Int(UInt32.max / 2) else { throw Failure.packetTooLarge }
+        writeLock.lock()
+        defer { writeLock.unlock() }
+        guard !isClosed else {
+            tail = nil
+            throw Failure.closed
+        }
+
+        let placement: (chunk: UInt32, offset: Int)
+        do {
+            placement = try writeLocked(bytes)
+        } catch {
+            // Audit VPERF-101: eviction used to run only after a successful write, so once the volume
+            // filled, every append failed, nothing was ever freed, and the feeder waited at the live
+            // edge forever. Shrink the window and try once more before dropping the packet.
+            guard makeRoomAfterFailedWrite(incomingKeyframe: isVideo && isKeyframe) else { throw error }
+            placement = try writeLocked(bytes)
+        }
+        tailOffset = placement.offset + bytes.count
+
+        var flags: UInt8 = 0
+        if isKeyframe { flags |= Entry.keyframeFlag }
+        if isVideo { flags |= Entry.videoFlag }
+        let entry = Entry(pts: pts, offset: UInt32(placement.offset), length: UInt32(bytes.count),
+                          chunk: placement.chunk, flags: flags)
 
         lock.lock()
+        guard !closed else {
+            lock.unlock()
+            tail = nil
+            throw Failure.closed
+        }
+        if isKeyframe { keyframeSeqs.append(firstSeq + (entries.count - head)) }
         entries.append(entry)
         if pts > edge { edge = pts }
-        let evictedURLs = evictLocked()
+        if let last = chunks.indices.last, chunks[last].id == placement.chunk {
+            retainedDiskBytes += tailOffset - chunks[last].bytes
+            chunks[last].bytes = tailOffset
+        }
+        let doomed = evictLocked()
         lock.unlock()
 
-        for url in evictedURLs {  // delete outside the lock; removeItem is filesystem I/O
-            try? FileManager.default.removeItem(at: url)
-        }
+        Self.unlinkAll(doomed)
     }
 
     // MARK: - Reader
@@ -86,25 +220,18 @@ final class PacketRingBuffer: @unchecked Sendable {
     func keyframePts(atOrBefore target: Double) throws -> Double? {
         lock.lock()
         defer { lock.unlock() }
-        return entries
-            .filter { $0.isKeyframe && $0.pts <= target }
-            .last
-            .map(\.pts)
+        return lastKeyframeIndexLocked(atOrBefore: target).map { entries[$0].pts }
     }
 
     /// Returns packets with `pts >= startPts`. Entries evicted between index snapshot and off-lock disk read are skipped (eviction is front-only, so skipping preserves keyframe alignment).
     func packets(fromPts startPts: Double) throws -> [Packet] {
         lock.lock()
-        let slice = entries.filter { $0.pts >= startPts }
+        let start = firstSeq
+        let seqs = entries[head...].indices.filter { entries[$0].pts >= startPts }.map { start + ($0 - head) }
         lock.unlock()
 
-        var packets = slice.compactMap { entry -> Packet? in
-            guard let data = try? Data(contentsOf: entry.fileURL, options: [.alwaysMapped, .uncached]) else {
-                return nil
-            }
-            return Packet(pts: entry.pts, isKeyframe: entry.isKeyframe, isVideo: entry.isVideo, bytes: data)
-        }
-        // Off-lock reads can race deferred eviction deletions: trim to the first video keyframe to guarantee a clean decode start.
+        var packets = seqs.compactMap { packet(atSeq: $0) }
+        // Off-lock reads can race eviction: trim to the first video keyframe to guarantee a clean decode start.
         if packets.contains(where: { $0.isVideo }),
            let kf = packets.firstIndex(where: { $0.isVideo && $0.isKeyframe }) {
             if kf > 0 { packets.removeFirst(kf) }
@@ -119,31 +246,37 @@ final class PacketRingBuffer: @unchecked Sendable {
     var seqBounds: (first: Int, end: Int) {
         lock.lock()
         defer { lock.unlock() }
-        return (firstSeq, firstSeq + entries.count)
+        return (firstSeq, firstSeq + (entries.count - head))
     }
 
-    /// Returns packet for `seq`, or nil if evicted or not yet appended. Index lock NOT held across the disk read.
+    /// Whether `seq` is a video packet, from the index alone, or nil if evicted or not yet appended.
+    /// Audit PERF-101: the audio pump and the feeder skip the other stream's packets through this,
+    /// where they used to map every packet file only to read the flag.
+    func isVideo(atSeq seq: Int) -> Bool? {
+        lock.lock()
+        defer { lock.unlock() }
+        return indexLocked(seq).map { entries[$0].isVideo }
+    }
+
+    /// Returns packet for `seq`, or nil if evicted, not yet appended, or unreadable. Index lock NOT held across the disk read.
     func packet(atSeq seq: Int) -> Packet? {
         lock.lock()
-        let idx = seq - firstSeq
-        guard idx >= 0, idx < entries.count else {
+        guard let idx = indexLocked(seq) else {
             lock.unlock()
             return nil
         }
         let entry = entries[idx]
+        let cached = cachedReadHandleLocked(entry.chunk)
         lock.unlock()
-        guard let data = try? Data(contentsOf: entry.fileURL,
-                                   options: [.alwaysMapped, .uncached]) else { return nil }
-        return Packet(pts: entry.pts, isKeyframe: entry.isKeyframe,
-                      isVideo: entry.isVideo, bytes: data)
+        guard let handle = cached ?? openReadHandle(entry.chunk),
+              let bytes = Self.read(handle.fd, offset: entry.offset, length: entry.length) else { return nil }
+        return Packet(pts: entry.pts, isKeyframe: entry.isKeyframe, isVideo: entry.isVideo, bytes: bytes)
     }
 
     func seq(forKeyframeAtOrBefore target: Double) -> Int? {
         lock.lock()
         defer { lock.unlock() }
-        return entries.indices
-            .last(where: { entries[$0].isKeyframe && entries[$0].pts <= target })
-            .map { firstSeq + $0 }
+        return lastKeyframeIndexLocked(atOrBefore: target).map { firstSeq + ($0 - head) }
     }
 
     /// Sequence of the EARLIEST retained keyframe, or nil if the ring holds no keyframe yet. DVR reseed
@@ -152,9 +285,7 @@ final class PacketRingBuffer: @unchecked Sendable {
     func firstKeyframeSeq() -> Int? {
         lock.lock()
         defer { lock.unlock() }
-        return entries.indices
-            .first(where: { entries[$0].isKeyframe })
-            .map { firstSeq + $0 }
+        return keyframeHead < keyframeSeqs.count ? keyframeSeqs[keyframeHead] : nil
     }
 
     // MARK: - Still runs (#544)
@@ -222,8 +353,7 @@ final class PacketRingBuffer: @unchecked Sendable {
                   maxSpanSeconds: Double,
                   reorderTail: Int) -> [Packet]? {
         lock.lock()
-        guard let startIdx = entries.indices
-            .last(where: { entries[$0].isKeyframe && entries[$0].pts <= target }) else {
+        guard let startIdx = lastKeyframeIndexLocked(atOrBefore: target) else {
             lock.unlock()
             return nil
         }
@@ -232,7 +362,7 @@ final class PacketRingBuffer: @unchecked Sendable {
         let window = entries[startIdx..<upper].map {
             IndexEntry(pts: $0.pts, isKeyframe: $0.isKeyframe, isVideo: $0.isVideo)
         }
-        let base = firstSeq + startIdx
+        let base = firstSeq + (startIdx - head)
         lock.unlock()
 
         guard let span = Self.stillRunSpan(target: target, index: window, firstSeq: base,
@@ -240,7 +370,9 @@ final class PacketRingBuffer: @unchecked Sendable {
                                            reorderTail: reorderTail,
                                            indexReachesEnd: reachesEnd) else { return nil }
 
-        let run = span.compactMap { packet(atSeq: $0) }.filter(\.isVideo)
+        let run = span.compactMap { seq -> Packet? in
+            window[seq - base].isVideo ? packet(atSeq: seq) : nil
+        }
         // Eviction between the snapshot and the off-lock reads would cost the run its keyframe, and
         // a run that does not open on one decodes as garbage.
         guard let first = run.first, first.isKeyframe else { return nil }
@@ -252,32 +384,299 @@ final class PacketRingBuffer: @unchecked Sendable {
     var oldestPts: Double? {
         lock.lock()
         defer { lock.unlock() }
-        return entries.first.map(\.pts)
+        return head < entries.count ? entries[head].pts : nil
+    }
+
+    /// PTS of the earliest retained keyframe: the oldest position a DVR rewind can land on.
+    var oldestKeyframePts: Double? {
+        lock.lock()
+        defer { lock.unlock() }
+        guard keyframeHead < keyframeSeqs.count, let idx = indexLocked(keyframeSeqs[keyframeHead]) else {
+            return nil
+        }
+        return entries[idx].pts
+    }
+
+    /// The oldest position a rewind can land on, on the session axis, once eviction has taken history
+    /// the window alone would have kept. nil until then, so a young session keeps its window arithmetic.
+    /// Audit VPERF-101: the byte budget can shrink the ring below `windowSeconds`, and the transport rail
+    /// must not advertise history that was evicted for space.
+    func residentFloorSessionSeconds(sessionStartPts: Double) -> Double? {
+        lock.lock()
+        defer { lock.unlock() }
+        guard firstSeq > 0, sessionStartPts.isFinite,
+              keyframeHead < keyframeSeqs.count, let idx = indexLocked(keyframeSeqs[keyframeHead]) else {
+            return nil
+        }
+        return max(0, entries[idx].pts - sessionStartPts)
+    }
+
+    /// Bytes the retained chunk files occupy, including the evicted prefix of the oldest chunk.
+    var diskBytes: Int {
+        lock.lock()
+        defer { lock.unlock() }
+        return retainedDiskBytes
+    }
+
+    /// Heap the index occupies, dead prefix and spare capacity included.
+    var indexFootprintBytes: Int {
+        lock.lock()
+        defer { lock.unlock() }
+        return entries.capacity * MemoryLayout<Entry>.stride + keyframeSeqs.capacity * MemoryLayout<Int>.stride
     }
 
     // MARK: - Internal
 
-    private func nextCounter() -> Int {
+    private var isClosed: Bool {
         lock.lock()
         defer { lock.unlock() }
-        let c = counter
-        counter += 1
-        return c
+        return closed
+    }
+
+    private func chunkURL(_ id: UInt32) -> URL {
+        scratch.appendingPathComponent("chunk-\(id).bin", isDirectory: false)
+    }
+
+    private func indexLocked(_ seq: Int) -> Int? {
+        let offset = seq - firstSeq
+        guard !closed, offset >= 0, offset < entries.count - head else { return nil }
+        return head + offset
     }
 
-    /// Drop leading entries outside `edge - windowSeconds`, keyframe-aligned. Forward scan: backward scan walked ~150k entries per append at 80 pkt/s; forward scan touches a few hundred at most. Caller deletes returned URLs after releasing the lock.
+    private func lastKeyframeIndexLocked(atOrBefore target: Double) -> Int? {
+        var k = keyframeSeqs.count
+        while k > keyframeHead {
+            k -= 1
+            if let idx = indexLocked(keyframeSeqs[k]), entries[idx].pts <= target { return idx }
+        }
+        return nil
+    }
+
+    /// Writer side, `writeLock` held. Rolls to a fresh chunk when the packet would overflow a
+    /// non-empty one, then writes it at the tail offset. Nothing moves on failure: a partial write
+    /// is overwritten by the next attempt at the same offset.
+    private func writeLocked(_ bytes: UnsafeRawBufferPointer) throws -> (chunk: UInt32, offset: Int) {
+        if tail == nil || (tailOffset > 0 && tailOffset + bytes.count > chunkTargetBytes) {
+            try rollChunkLocked()
+        }
+        guard let tail else { throw Failure.closed }
+        try writeAll(tail.fd, bytes, off_t(tailOffset))
+        return (tail.id, tailOffset)
+    }
+
+    private func rollChunkLocked() throws {
+        guard nextChunkID < UInt32.max else { throw Failure.capacityExceeded }
+        let id = nextChunkID
+        let fd = open(chunkURL(id).path, O_CREAT | O_EXCL | O_RDWR | O_CLOEXEC, 0o600)
+        guard fd >= 0 else { throw NSError(domain: NSPOSIXErrorDomain, code: Int(errno)) }
+        nextChunkID += 1
+        let handle = ChunkHandle(id: id, fd: fd)
+        tail = handle
+        tailOffset = 0
+
+        lock.lock()
+        guard !closed else {
+            lock.unlock()
+            throw Failure.closed
+        }
+        chunks.append(ChunkRecord(id: id, bytes: 0))
+        // Readers of the newest packets share the writer's descriptor.
+        insertReadHandleLocked(handle)
+        let doomed = releaseUnreferencedChunksLocked(includingTail: false)
+        lock.unlock()
+        Self.unlinkAll(doomed)
+    }
+
+    /// `writeLock` held. Frees at least one chunk file while keeping the retained span on a keyframe:
+    /// up to the first keyframe in a later chunk, or, when the incoming packet is itself a video
+    /// keyframe that can open a fresh span, everything including the tail chunk. False when nothing
+    /// could be freed, and the packet is dropped as before.
+    private func makeRoomAfterFailedWrite(incomingKeyframe: Bool) -> Bool {
+        lock.lock()
+        var doomed: [URL] = []
+        var releasedTail = false
+        if let pivot = keyframeInLaterChunkLocked() {
+            dropEntriesLocked(upTo: pivot)
+            doomed = releaseUnreferencedChunksLocked(includingTail: false)
+        } else if incomingKeyframe {
+            dropEntriesLocked(upTo: entries.count)
+            doomed = releaseUnreferencedChunksLocked(includingTail: true)
+            releasedTail = chunks.isEmpty
+        }
+        compactIfDueLocked()
+        lock.unlock()
+        if releasedTail {
+            tail = nil
+            tailOffset = 0
+        }
+        Self.unlinkAll(doomed)
+        if !doomed.isEmpty {
+            EngineLog.emit("[PacketRingBuffer] write failed; freed \(doomed.count) chunk(s) and retrying "
+                           + "(the rewind window shrinks instead of the live feed stopping)",
+                           category: .swPlayback)
+        }
+        return !doomed.isEmpty
+    }
+
+    /// Drop leading entries outside `edge - windowSeconds` or past the byte budget, keyframe-aligned,
+    /// and return the chunk files no retained entry references any more (the caller unlinks them
+    /// after releasing the lock). Walks the keyframe list, one step per GOP.
     private func evictLocked() -> [URL] {
         let cutoff = edge - windowSeconds
         var pivot: Int? = nil
-        var i = 0
-        while i < entries.count, entries[i].pts <= cutoff {
-            if entries[i].isKeyframe { pivot = i }
+        var k = keyframeHead
+        while k < keyframeSeqs.count, let idx = indexLocked(keyframeSeqs[k]), entries[idx].pts <= cutoff {
+            pivot = idx
+            k += 1
+        }
+        if let p = pivot, p > head { dropEntriesLocked(upTo: p) }
+        var doomed = releaseUnreferencedChunksLocked(includingTail: false)
+
+        // Audit VPERF-101: time alone put 5.4 GB on disk at 8 Mbit/s over the 90 min default, and an
+        // infinite window never evicted at all.
+        while retainedDiskBytes > byteBudget, chunks.count > 1 {
+            if let p = keyframeInLaterChunkLocked() {
+                dropEntriesLocked(upTo: p)
+            } else if retainedDiskBytes - byteBudget > byteBudget, let p = firstIndexInLaterChunkLocked() {
+                // A GOP longer than the whole budget (or a stream that never flags a keyframe) must
+                // not grow the directory without bound; the rewind floor then decodes from the next
+                // keyframe, which `firstKeyframeSeq` points at.
+                dropEntriesLocked(upTo: p)
+            } else {
+                break
+            }
+            let freed = releaseUnreferencedChunksLocked(includingTail: false)
+            if freed.isEmpty { break }
+            doomed += freed
+        }
+        compactIfDueLocked()
+        return doomed
+    }
+
+    private func dropEntriesLocked(upTo idx: Int) {
+        guard idx > head else { return }
+        firstSeq += idx - head
+        head = idx
+        while keyframeHead < keyframeSeqs.count, keyframeSeqs[keyframeHead] < firstSeq { keyframeHead += 1 }
+    }
+
+    /// The first retained keyframe stored in a later chunk than the oldest retained entry.
+    private func keyframeInLaterChunkLocked() -> Int? {
+        guard head < entries.count else { return nil }
+        let headChunk = entries[head].chunk
+        var k = keyframeHead
+        while k < keyframeSeqs.count {
+            if let idx = indexLocked(keyframeSeqs[k]), entries[idx].chunk > headChunk { return idx }
+            k += 1
+        }
+        return nil
+    }
+
+    private func firstIndexInLaterChunkLocked() -> Int? {
+        guard head < entries.count else { return nil }
+        let headChunk = entries[head].chunk
+        var i = head + 1
+        while i < entries.count {
+            if entries[i].chunk > headChunk { return i }
             i += 1
         }
-        guard let p = pivot, p > 0 else { return [] }
-        let urls = entries[..<p].map(\.fileURL)
-        entries.removeSubrange(..<p)
-        firstSeq += p
-        return urls
+        return nil
+    }
+
+    /// Chunks wholly before the oldest retained entry. The tail stays unless asked for, because the
+    /// writer is still appending to it.
+    private func releaseUnreferencedChunksLocked(includingTail: Bool) -> [URL] {
+        let floorChunk: UInt32? = head < entries.count ? entries[head].chunk : nil
+        var doomed: [URL] = []
+        while let first = chunks.first,
+              chunks.count > 1 || includingTail,
+              floorChunk.map({ first.id < $0 }) ?? true {
+            chunks.removeFirst()
+            retainedDiskBytes -= first.bytes
+            readHandles.removeAll { $0.id == first.id }
+            doomed.append(chunkURL(first.id))
+        }
+        return doomed
+    }
+
+    /// Batched, so the dead prefix costs one memmove per few minutes of packets rather than one per GOP.
+    private func compactIfDueLocked() {
+        if head >= 1024, head * 8 >= entries.count - head {
+            entries.removeSubrange(0..<head)
+            head = 0
+        }
+        if keyframeHead >= 256, keyframeHead * 8 >= keyframeSeqs.count - keyframeHead {
+            keyframeSeqs.removeSubrange(0..<keyframeHead)
+            keyframeHead = 0
+        }
+    }
+
+    private func cachedReadHandleLocked(_ chunk: UInt32) -> ChunkHandle? {
+        guard let i = readHandles.firstIndex(where: { $0.id == chunk }) else { return nil }
+        let handle = readHandles[i]
+        if i > 0 {
+            readHandles.remove(at: i)
+            readHandles.insert(handle, at: 0)
+        }
+        return handle
+    }
+
+    private func insertReadHandleLocked(_ handle: ChunkHandle) {
+        readHandles.removeAll { $0.id == handle.id }
+        readHandles.insert(handle, at: 0)
+        if readHandles.count > Self.readHandleCap { readHandles.removeLast() }
+    }
+
+    private func openReadHandle(_ chunk: UInt32) -> ChunkHandle? {
+        let fd = open(chunkURL(chunk).path, O_RDONLY | O_CLOEXEC)
+        guard fd >= 0 else { return nil }
+        let handle = ChunkHandle(id: chunk, fd: fd)
+        lock.lock()
+        if !closed, let first = chunks.first, let last = chunks.last, first.id <= chunk, chunk <= last.id {
+            insertReadHandleLocked(handle)
+        }
+        lock.unlock()
+        return handle
+    }
+
+    private static func read(_ fd: Int32, offset: UInt32, length: UInt32) -> Data? {
+        let count = Int(length)
+        if count == 0 { return Data() }
+        guard let buffer = malloc(count) else { return nil }
+        var done = 0
+        while done < count {
+            let n = pread(fd, buffer + done, count - done, off_t(offset) + off_t(done))
+            if n > 0 {
+                done += n
+            } else if n < 0, errno == EINTR {
+                continue
+            } else {
+                free(buffer)
+                return nil
+            }
+        }
+        return Data(bytesNoCopy: buffer, count: count, deallocator: .free)
+    }
+
+    static let pwriteAll: WriteAll = { fd, bytes, offset in
+        guard var base = bytes.baseAddress else { return }
+        var remaining = bytes.count
+        var at = offset
+        while remaining > 0 {
+            let n = pwrite(fd, base, remaining, at)
+            if n > 0 {
+                base += n
+                remaining -= n
+                at += off_t(n)
+            } else if n < 0, errno == EINTR {
+                continue
+            } else {
+                throw NSError(domain: NSPOSIXErrorDomain, code: Int(n < 0 ? errno : EIO))
+            }
+        }
+    }
+
+    private static func unlinkAll(_ urls: [URL]) {
+        for url in urls { unlink(url.path) }
     }
 }
diff --git a/Sources/AetherEngine/Video/SegmentCache.swift b/Sources/AetherEngine/Video/SegmentCache.swift
index 2452511d5..4fcc1388c 100644
--- a/Sources/AetherEngine/Video/SegmentCache.swift
+++ b/Sources/AetherEngine/Video/SegmentCache.swift
@@ -68,20 +68,9 @@ final class SegmentCache: @unchecked Sendable {
 
     let sessionDir: URL
 
-    /// AE#451: an flock(2) held on `sessionDir/session.lock` for as long as this cache lives.
-    /// This is the liveness half of the stale-session sweep: the age check alone cannot tell a
-    /// session an hour into a film from one that crashed an hour ago, because the directory's
-    /// creation date IS the session's start time.
-    ///
-    /// flock and not fcntl: flock locks belong to the open file description, so a second cache in
-    /// the SAME process fails to take it too, which is the case the report is about. fcntl locks
-    /// are per-process and a process never blocks itself.
-    ///
-    /// The kernel drops it when the process dies, so a crashed session leaves an unheld marker and
-    /// sweeps exactly as before. -1 means unheld (open or flock failed); such a session is swept
-    /// like today's, which is the pre-AE#451 behaviour rather than a new failure.
+    /// AE#451: the `SessionDirectoryLiveness` marker held for as long as this cache lives. -1 means
+    /// unheld (open or flock failed); such a session is swept by age like before AE#451.
     private var lockFD: Int32 = -1
-    private static let liveMarkerName = "session.lock"
 
     private var _totalBytes: Int = 0
 
@@ -149,20 +138,7 @@ final class SegmentCache: @unchecked Sendable {
     }
 
     private static func acquireLiveMarker(sessionDir: URL) -> Int32 {
-        let path = sessionDir.appendingPathComponent(liveMarkerName).path
-        let fd = open(path, O_CREAT | O_RDWR, 0o600)
-        guard fd >= 0 else {
-            EngineLog.emit("[SegmentCache] live marker open failed at \(path): errno=\(errno)",
-                           category: .session)
-            return -1
-        }
-        guard flock(fd, LOCK_EX | LOCK_NB) == 0 else {
-            EngineLog.emit("[SegmentCache] live marker lock failed at \(path): errno=\(errno)",
-                           category: .session)
-            Darwin.close(fd)
-            return -1
-        }
-        return fd
+        SessionDirectoryLiveness.acquire(sessionDir: sessionDir, logPrefix: "[SegmentCache]")
     }
 
     private func releaseLiveMarker() {
@@ -173,20 +149,6 @@ final class SegmentCache: @unchecked Sendable {
         if fd >= 0 { Darwin.close(fd) }
     }
 
-    /// Whether some open file description still holds `entry`'s marker. A missing marker answers
-    /// false: it is a directory from a build without one, and the age check decides it as before.
-    private static func isSessionDirLive(_ entry: URL) -> Bool {
-        let path = entry.appendingPathComponent(liveMarkerName).path
-        let fd = open(path, O_RDONLY)
-        guard fd >= 0 else { return false }
-        defer { Darwin.close(fd) }
-        if flock(fd, LOCK_EX | LOCK_NB) == 0 {
-            flock(fd, LOCK_UN)
-            return false
-        }
-        return true
-    }
-
     private static func sweepStaleSessionDirs(baseDir: URL, currentSession: String) {
         let fm = FileManager.default
         guard let entries = try? fm.contentsOfDirectory(at: baseDir,
@@ -199,7 +161,7 @@ final class SegmentCache: @unchecked Sendable {
             let created = (try? entry.resourceValues(forKeys: [.creationDateKey]))?.creationDate
             guard created == nil || created! < cutoff else { continue }
             // AE#451: age says how long it has been there, not whether anyone is still using it.
-            if isSessionDirLive(entry) {
+            if SessionDirectoryLiveness.isLive(entry) {
                 EngineLog.emit("[SegmentCache] sweep spared live session dir \(entry.lastPathComponent)",
                                category: .session)
                 continue
diff --git a/Sources/AetherEngine/Video/SessionDirectoryLiveness.swift b/Sources/AetherEngine/Video/SessionDirectoryLiveness.swift
new file mode 100644
index 000000000..3cf9e7e96
--- /dev/null
+++ b/Sources/AetherEngine/Video/SessionDirectoryLiveness.swift
@@ -0,0 +1,50 @@
+import Darwin
+import Foundation
+
+/// AE#451: the liveness half of the `aether-segments/` stale-session sweep. A session directory's
+/// creation date is its session's START time, so age alone cannot tell a session an hour in from one
+/// that crashed an hour ago; an flock(2) held on `<dir>/session.lock` for the owner's lifetime can.
+///
+/// flock and not fcntl: flock locks belong to the open file description, so a second owner in the
+/// SAME process fails to take it too. fcntl locks are per-process and a process never blocks itself.
+/// The kernel drops the lock when the process dies, so a crashed session leaves an unheld marker and
+/// sweeps as before.
+///
+/// Audit SEG-105: shared by `SegmentCache` and the software DVR ring, which lives under the same base
+/// directory and was swept an hour into a DVR session because its directory carried no marker.
+enum SessionDirectoryLiveness {
+    static let markerName = "session.lock"
+
+    /// The held marker's descriptor, or -1 when open or flock failed (such a directory is swept by
+    /// age, the pre-AE#451 behaviour rather than a new failure).
+    static func acquire(sessionDir: URL, logPrefix: String) -> Int32 {
+        let path = sessionDir.appendingPathComponent(markerName).path
+        let fd = open(path, O_CREAT | O_RDWR | O_CLOEXEC, 0o600)
+        guard fd >= 0 else {
+            EngineLog.emit("\(logPrefix) live marker open failed at \(path): errno=\(errno)",
+                           category: .session)
+            return -1
+        }
+        guard flock(fd, LOCK_EX | LOCK_NB) == 0 else {
+            EngineLog.emit("\(logPrefix) live marker lock failed at \(path): errno=\(errno)",
+                           category: .session)
+            Darwin.close(fd)
+            return -1
+        }
+        return fd
+    }
+
+    /// Whether some open file description still holds `entry`'s marker. A missing marker answers
+    /// false: it is a directory from a build without one, and the age check decides it as before.
+    static func isLive(_ entry: URL) -> Bool {
+        let path = entry.appendingPathComponent(markerName).path
+        let fd = open(path, O_RDONLY | O_CLOEXEC)
+        guard fd >= 0 else { return false }
+        defer { Darwin.close(fd) }
+        if flock(fd, LOCK_EX | LOCK_NB) == 0 {
+            flock(fd, LOCK_UN)
+            return false
+        }
+        return true
+    }
+}
diff --git a/Tests/AetherEngineTests/PacketRingBufferBehaviourTests.swift b/Tests/AetherEngineTests/PacketRingBufferBehaviourTests.swift
new file mode 100644
index 000000000..774eefad0
--- /dev/null
+++ b/Tests/AetherEngineTests/PacketRingBufferBehaviourTests.swift
@@ -0,0 +1,193 @@
+import Foundation
+import Testing
+@testable import AetherEngine
+
+/// The DVR ring's public behaviour, pinned independently of how it stores bytes: append and read by
+/// sequence, the sequence bounds an evicting ring reports, keyframe-aligned eviction order, the
+/// rewind lookups and the still run the scrub thumbnail decodes from. Written against the
+/// file-per-packet ring first and kept unchanged across the chunk-spool rewrite (audit PERF-101).
+@Suite("DVR ring behaviour")
+struct PacketRingBufferBehaviourTests {
+
+    private func makeScratch() -> URL {
+        let dir = FileManager.default.temporaryDirectory
+            .appendingPathComponent("prbbehave-\(UUID().uuidString)", isDirectory: true)
+        try? FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
+        return dir
+    }
+
+    private func payload(_ i: Int, count: Int = 16) -> Data {
+        Data((0..<count).map { UInt8(truncatingIfNeeded: i &+ $0) })
+    }
+
+    /// One second of 25 fps video per GOP with an audio packet after every video packet.
+    private func fill(_ ring: PacketRingBuffer, seconds: Int, gopSeconds: Int = 2) throws {
+        var index = 0
+        for frame in 0..<(seconds * 25) {
+            let pts = Double(frame) / 25
+            let key = frame % (gopSeconds * 25) == 0
+            try ring.append(pts: pts, isKeyframe: key, isVideo: true, bytes: payload(index))
+            index += 1
+            try ring.append(pts: pts, isKeyframe: false, isVideo: false, bytes: payload(index, count: 4))
+            index += 1
+        }
+    }
+
+    @Test("Packets read back by sequence with their flags and bytes, audio and video interleaved")
+    func readsBackBySequence() throws {
+        let ring = try PacketRingBuffer(windowSeconds: 3600, scratch: makeScratch())
+        defer { ring.close() }
+        try ring.append(pts: 10, isKeyframe: true, isVideo: true, bytes: Data([1, 2, 3]))
+        try ring.append(pts: 10, isKeyframe: false, isVideo: false, bytes: Data([4]))
+        try ring.append(pts: 10.04, isKeyframe: false, isVideo: true, bytes: Data())
+        try ring.append(pts: 10.08, isKeyframe: false, isVideo: true, bytes: Data([9, 9]))
+
+        #expect(ring.seqBounds.first == 0)
+        #expect(ring.seqBounds.end == 4)
+        let v = try #require(ring.packet(atSeq: 0))
+        #expect(v.pts == 10 && v.isKeyframe && v.isVideo && v.bytes == Data([1, 2, 3]))
+        let a = try #require(ring.packet(atSeq: 1))
+        #expect(a.pts == 10 && !a.isKeyframe && !a.isVideo && a.bytes == Data([4]))
+        let empty = try #require(ring.packet(atSeq: 2))
+        #expect(empty.bytes.isEmpty && empty.isVideo)
+        #expect(ring.packet(atSeq: 3)?.bytes == Data([9, 9]))
+        #expect(ring.packet(atSeq: 4) == nil, "not appended yet")
+        #expect(ring.packet(atSeq: -1) == nil)
+    }
+
+    @Test("Eviction keeps the retained span on a video keyframe and advances the first sequence")
+    func evictionIsKeyframeAlignedAndMonotonic() throws {
+        let ring = try PacketRingBuffer(windowSeconds: 10, scratch: makeScratch())
+        defer { ring.close() }
+        var lastFirst = 0
+        for second in 0..<60 {
+            for frame in 0..<25 {
+                let n = second * 25 + frame
+                try ring.append(pts: Double(n) / 25, isKeyframe: n % 50 == 0, isVideo: true, bytes: payload(n))
+                let bounds = ring.seqBounds
+                #expect(bounds.first >= lastFirst, "firstSeq never moves backwards")
+                #expect(bounds.end == n + 1)
+                lastFirst = bounds.first
+            }
+        }
+        let bounds = ring.seqBounds
+        #expect(bounds.first > 0)
+        let first = try #require(ring.packet(atSeq: bounds.first))
+        #expect(first.isKeyframe && first.isVideo, "the retained span opens on a keyframe")
+        #expect(first.bytes == payload(bounds.first))
+        #expect(ring.packet(atSeq: bounds.first - 1) == nil, "the evicted prefix reads as gone")
+        #expect(ring.packet(atSeq: bounds.end - 1)?.bytes == payload(bounds.end - 1))
+
+        let edge = Double(60 * 25 - 1) / 25
+        let oldest = try #require(ring.oldestPts)
+        #expect(oldest <= edge - 10, "never evicts inside the window")
+        #expect(oldest > edge - 10 - 2.0 - 0.001, "evicts up to the last keyframe at or before the cutoff")
+    }
+
+    @Test("Nothing is evicted while the retained history fits the window, and an infinite window keeps everything")
+    func wholeWindowIsKept() throws {
+        let short = try PacketRingBuffer(windowSeconds: 100, scratch: makeScratch())
+        defer { short.close() }
+        try fill(short, seconds: 30)
+        #expect(short.seqBounds.first == 0)
+        #expect(short.seqBounds.end == 30 * 25 * 2)
+
+        let forever = try PacketRingBuffer(windowSeconds: .infinity, scratch: makeScratch())
+        defer { forever.close() }
+        try fill(forever, seconds: 30)
+        #expect(forever.seqBounds.first == 0)
+        #expect(forever.seqBounds.end == 30 * 25 * 2)
+    }
+
+    @Test("Rewind lookups: newest keyframe at or before a target, earliest keyframe as the floor")
+    func rewindLookups() throws {
+        let ring = try PacketRingBuffer(windowSeconds: 3600, scratch: makeScratch())
+        defer { ring.close() }
+        // The session joined mid-GOP: two non-key packets precede the first keyframe.
+        try ring.append(pts: 4.8, isKeyframe: false, isVideo: true, bytes: Data([0]))
+        try ring.append(pts: 4.9, isKeyframe: false, isVideo: false, bytes: Data([1]))
+        try ring.append(pts: 5.0, isKeyframe: true, isVideo: true, bytes: Data([2]))
+        try ring.append(pts: 5.1, isKeyframe: false, isVideo: true, bytes: Data([3]))
+        try ring.append(pts: 7.0, isKeyframe: true, isVideo: true, bytes: Data([4]))
+        try ring.append(pts: 7.1, isKeyframe: false, isVideo: true, bytes: Data([5]))
+
+        #expect(ring.firstKeyframeSeq() == 2, "the floor skips the mid-GOP leading entries")
+        #expect(ring.seq(forKeyframeAtOrBefore: 6.0) == 2)
+        #expect(ring.seq(forKeyframeAtOrBefore: 7.0) == 4)
+        #expect(ring.seq(forKeyframeAtOrBefore: 99) == 4)
+        #expect(ring.seq(forKeyframeAtOrBefore: 4.95) == nil, "before every keyframe")
+        #expect(try ring.keyframePts(atOrBefore: 6.0) == 5.0)
+        #expect(try ring.keyframePts(atOrBefore: 4.0) == nil)
+        #expect(ring.oldestPts == 4.8)
+    }
+
+    @Test("Rewind lookups stay correct after eviction has moved the first sequence")
+    func rewindLookupsAfterEviction() throws {
+        let ring = try PacketRingBuffer(windowSeconds: 10, scratch: makeScratch())
+        defer { ring.close() }
+        try fill(ring, seconds: 60, gopSeconds: 2)
+        let bounds = ring.seqBounds
+        #expect(bounds.first > 0)
+        let floor = try #require(ring.firstKeyframeSeq())
+        #expect(floor >= bounds.first)
+        let floorPacket = try #require(ring.packet(atSeq: floor))
+        #expect(floorPacket.isKeyframe && floorPacket.isVideo)
+        #expect(ring.seq(forKeyframeAtOrBefore: floorPacket.pts - 0.5) == nil)
+        #expect(ring.seq(forKeyframeAtOrBefore: floorPacket.pts) == floor)
+        let newest = try #require(ring.seq(forKeyframeAtOrBefore: .infinity))
+        let newestPacket = try #require(ring.packet(atSeq: newest))
+        #expect(newestPacket.isKeyframe && newestPacket.pts > 55)
+    }
+
+    @Test("packets(fromPts:) replays from the first video keyframe, audio included")
+    func replayStartsOnAVideoKeyframe() throws {
+        let ring = try PacketRingBuffer(windowSeconds: 3600, scratch: makeScratch())
+        defer { ring.close() }
+        try ring.append(pts: 1.0, isKeyframe: false, isVideo: false, bytes: Data([1]))
+        try ring.append(pts: 1.1, isKeyframe: false, isVideo: true, bytes: Data([2]))
+        try ring.append(pts: 1.2, isKeyframe: true, isVideo: true, bytes: Data([3]))
+        try ring.append(pts: 1.2, isKeyframe: false, isVideo: false, bytes: Data([4]))
+        try ring.append(pts: 1.3, isKeyframe: false, isVideo: true, bytes: Data([5]))
+
+        let replay = try ring.packets(fromPts: 1.0)
+        #expect(replay.map { $0.bytes.first } == [3, 4, 5])
+        #expect(try ring.packets(fromPts: 1.25).isEmpty, "a start after the keyframe has no video keyframe to open on")
+        #expect(try ring.packets(fromPts: 99).isEmpty)
+    }
+
+    @Test("A still run opens on the keyframe, carries video only, and respects its bounds")
+    func stillRunShape() throws {
+        let ring = try PacketRingBuffer(windowSeconds: 3600, scratch: makeScratch())
+        defer { ring.close() }
+        try fill(ring, seconds: 10, gopSeconds: 2)
+
+        let run = try #require(ring.stillRun(target: 5.0, maxPackets: 500, maxSpanSeconds: 30, reorderTail: 0))
+        #expect(run.first?.isKeyframe == true)
+        #expect(run.allSatisfy { $0.isVideo })
+        #expect(run.first?.pts == 4.0)
+        #expect(run.last?.pts == 5.0)
+        #expect(run.count == 26)
+
+        let tailed = try #require(ring.stillRun(target: 5.0, maxPackets: 500, maxSpanSeconds: 30, reorderTail: 2))
+        #expect(tailed.count == 28)
+
+        #expect(ring.stillRun(target: 5.0, maxPackets: 10, maxSpanSeconds: 30, reorderTail: 0) == nil)
+        #expect(ring.stillRun(target: 5.0, maxPackets: 500, maxSpanSeconds: 0.5, reorderTail: 0) == nil)
+        #expect(ring.stillRun(target: -1, maxPackets: 500, maxSpanSeconds: 30, reorderTail: 0) == nil)
+
+        let atEdge = try #require(ring.stillRun(target: 99, maxPackets: 500, maxSpanSeconds: 300, reorderTail: 0))
+        #expect(atEdge.last?.pts == 9.96, "a target beyond the newest packet clamps to it")
+    }
+
+    @Test("close() clears the index at once and is idempotent")
+    func closeIsImmediateAndIdempotent() throws {
+        let ring = try PacketRingBuffer(windowSeconds: 60, scratch: makeScratch())
+        try fill(ring, seconds: 4)
+        #expect(ring.seqBounds.end > 0)
+        ring.close()
+        #expect(ring.seqBounds.first == ring.seqBounds.end)
+        #expect(ring.packet(atSeq: 0) == nil)
+        #expect(ring.oldestPts == nil)
+        ring.close()
+    }
+}
diff --git a/Tests/AetherEngineTests/PacketRingBufferChunkSpoolTests.swift b/Tests/AetherEngineTests/PacketRingBufferChunkSpoolTests.swift
new file mode 100644
index 000000000..4417fb710
--- /dev/null
+++ b/Tests/AetherEngineTests/PacketRingBufferChunkSpoolTests.swift
@@ -0,0 +1,383 @@
+import Darwin
+import Foundation
+import Testing
+@testable import AetherEngine
+
+/// Audit PERF-101 / SEG-106 / VPERF-101 / SEG-105: the software live DVR ring spools into a few
+/// append-only chunk files behind a compact index, bounds its disk use by bytes as well as by time,
+/// makes room when a write fails, and marks its directory live for the segment cache's sweep.
+@Suite("DVR ring chunk spool")
+struct PacketRingBufferChunkSpoolTests {
+
+    private func makeScratch(in base: URL? = nil) -> URL {
+        let parent = base ?? URL(fileURLWithPath: NSTemporaryDirectory(), isDirectory: true)
+        let dir = parent.appendingPathComponent("prbspool-\(UUID().uuidString)", isDirectory: true)
+        try? FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
+        return dir
+    }
+
+    private func packetFiles(in dir: URL) -> [URL] {
+        ((try? FileManager.default.contentsOfDirectory(at: dir, includingPropertiesForKeys: nil)) ?? [])
+            .filter { $0.lastPathComponent != "session.lock" }
+    }
+
+    private func bytesOnDisk(in dir: URL) -> Int {
+        packetFiles(in: dir).reduce(0) { sum, url in
+            var info = stat()
+            return lstat(url.path, &info) == 0 ? sum + Int(info.st_size) : sum
+        }
+    }
+
+    @Test("Packets spool into a few chunk files, not one file per packet")
+    func spoolsIntoChunkFiles() throws {
+        let scratch = makeScratch()
+        let ring = try PacketRingBuffer(windowSeconds: 3600, scratch: scratch)
+        defer { ring.close() }
+        let payload = Data(repeating: 0x5A, count: 1024)
+        for i in 0..<2000 {
+            try ring.append(pts: Double(i) * 0.04, isKeyframe: i % 50 == 0, isVideo: true, bytes: payload)
+        }
+        #expect(ring.seqBounds.end == 2000)
+        #expect(packetFiles(in: scratch).count <= 2,
+                "2 MB of packets fit one 4 MB chunk; a file per packet is the PERF-101 defect")
+        let last = try #require(ring.packet(atSeq: 1999))
+        #expect(last.bytes == payload)
+    }
+
+    @Test("A ring directory with a held marker survives the segment cache's stale sweep")
+    func heldRingDirectorySurvivesSweep() throws {
+        let base = URL(fileURLWithPath: NSTemporaryDirectory(), isDirectory: true)
+            .appendingPathComponent("prbsweep-\(UUID().uuidString)", isDirectory: true)
+        try FileManager.default.createDirectory(at: base, withIntermediateDirectories: true)
+        defer { try? FileManager.default.removeItem(at: base) }
+        let scratch = base.appendingPathComponent("dvr-\(UUID().uuidString)", isDirectory: true)
+        try FileManager.default.createDirectory(at: scratch, withIntermediateDirectories: true)
+
+        let ring = try PacketRingBuffer(windowSeconds: 5400, scratch: scratch)
+        defer { ring.close() }
+        try ring.append(pts: 0, isKeyframe: true, isVideo: true, bytes: Data([1, 2, 3]))
+
+        // Ninety minutes into a DVR session: the directory is as old as the session.
+        let past = Date().addingTimeInterval(-7200)
+        try FileManager.default.setAttributes([.creationDate: past], ofItemAtPath: scratch.path)
+        let created = try scratch.resourceValues(forKeys: [.creationDateKey]).creationDate
+        #expect(created.map { $0 < Date().addingTimeInterval(-3600) } == true)
+
+        let cache = SegmentCache(baseDirectory: base)
+        defer { cache.close() }
+
+        #expect(FileManager.default.fileExists(atPath: scratch.path),
+                "a live ring's directory must not be swept by age alone")
+        #expect(ring.packet(atSeq: 0)?.bytes == Data([1, 2, 3]))
+    }
+
+    // MARK: - Index footprint
+
+    @Test("The index is a flat record per packet, not a heap object per packet")
+    func indexIsCompact() throws {
+        #expect(MemoryLayout<PacketRingBuffer.Entry>.stride == 24)
+        let ring = try PacketRingBuffer(windowSeconds: .infinity, scratch: makeScratch())
+        defer { ring.close() }
+        let payload = Data(repeating: 1, count: 64)
+        let count = 100_000
+        for i in 0..<count {
+            try ring.append(pts: Double(i) * 0.0125, isKeyframe: i % 100 == 0, isVideo: i % 2 == 0, bytes: payload)
+        }
+        #expect(ring.seqBounds.end == count)
+        // The file-per-packet ring kept 554-586 B per entry (a URL each): 55 MB for these 100k.
+        #expect(ring.indexFootprintBytes < 5 << 20)
+    }
+
+    // MARK: - Byte budget
+
+    @Test("A byte budget bounds the disk use, even with an infinite window, and the span opens on a keyframe")
+    func byteBudgetBoundsDiskAndKeepsKeyframeAlignment() throws {
+        let scratch = makeScratch()
+        let budget = 8 << 20
+        let ring = try PacketRingBuffer(windowSeconds: .infinity, scratch: scratch, byteBudget: budget)
+        defer { ring.close() }
+        let size = 256 << 10
+        func body(_ i: Int) -> Data { Data(repeating: UInt8(truncatingIfNeeded: i), count: size) }
+        var retainedBound = 0
+        for i in 0..<200 {
+            try ring.append(pts: Double(i) * 0.5, isKeyframe: i % 8 == 0, isVideo: true, bytes: body(i))
+            retainedBound = max(retainedBound, bytesOnDisk(in: scratch))
+        }
+        // 512 KB chunks: the budget plus the one chunk the writer is filling.
+        #expect(retainedBound <= budget + (512 << 10), "on-disk bytes stayed within budget plus one chunk")
+        #expect(ring.diskBytes <= budget + (512 << 10))
+        let bounds = ring.seqBounds
+        #expect(bounds.end == 200)
+        #expect(bounds.first > 0, "50 MB of packets cannot fit an 8 MB budget")
+        let first = try #require(ring.packet(atSeq: bounds.first))
+        #expect(first.isKeyframe && first.isVideo)
+        #expect(first.bytes == body(bounds.first))
+        #expect(ring.packet(atSeq: bounds.end - 1)?.bytes == body(199))
+        #expect(ring.packet(atSeq: bounds.first - 1) == nil)
+    }
+
+    @Test("The budget holds when the window is finite too, and the stricter bound wins")
+    func strictestBoundWins() throws {
+        let ring = try PacketRingBuffer(windowSeconds: 20, scratch: makeScratch(), byteBudget: 64 << 20)
+        defer { ring.close() }
+        let payload = Data(repeating: 3, count: 4 << 10)
+        for i in 0..<400 {
+            try ring.append(pts: Double(i), isKeyframe: i % 5 == 0, isVideo: true, bytes: payload)
+        }
+        let oldest = try #require(ring.oldestPts)
+        #expect(oldest <= 399 - 20 && oldest > 399 - 20 - 5, "time still bounds it when bytes do not")
+    }
+
+    @Test("A budget smaller than one chunk never evicts the only chunk")
+    func tinyBudgetKeepsTheTail() throws {
+        let ring = try PacketRingBuffer(windowSeconds: .infinity, scratch: makeScratch(), byteBudget: 1)
+        defer { ring.close() }
+        for i in 0..<50 {
+            try ring.append(pts: Double(i), isKeyframe: i % 5 == 0, isVideo: true, bytes: Data(repeating: 9, count: 10_000))
+        }
+        let bounds = ring.seqBounds
+        #expect(bounds.end == 50)
+        #expect(bounds.first > 0)
+        #expect(ring.diskBytes <= (64 << 10) + 10_000, "the chunk being written is what stays")
+        let newest = try #require(ring.packet(atSeq: 49))
+        #expect(newest.bytes.count == 10_000)
+        #expect(ring.packet(atSeq: bounds.first) != nil)
+    }
+
+    @Test("A GOP larger than the whole budget still cannot grow the directory without bound")
+    func hugeGopIsBoundedToo() throws {
+        let scratch = makeScratch()
+        let budget = 1 << 20
+        let ring = try PacketRingBuffer(windowSeconds: .infinity, scratch: scratch, byteBudget: budget)
+        defer { ring.close() }
+        // One keyframe, then nothing but delta frames: no pivot exists.
+        try ring.append(pts: 0, isKeyframe: true, isVideo: true, bytes: Data(repeating: 0, count: 1000))
+        for i in 1..<2000 {
+            try ring.append(pts: Double(i), isKeyframe: false, isVideo: true, bytes: Data(repeating: 1, count: 8 << 10))
+        }
+        #expect(bytesOnDisk(in: scratch) <= 3 * budget)
+        #expect(ring.seqBounds.end == 2000)
+    }
+
+    @Test("The resident floor is nil until eviction moves the span, then tracks the oldest keyframe")
+    func residentFloorFollowsEviction() throws {
+        let ring = try PacketRingBuffer(windowSeconds: .infinity, scratch: makeScratch(), byteBudget: 4 << 20)
+        defer { ring.close() }
+        let size = 128 << 10
+        try ring.append(pts: 100, isKeyframe: true, isVideo: true, bytes: Data(repeating: 0, count: size))
+        #expect(ring.residentFloorSessionSeconds(sessionStartPts: 100) == nil)
+        for i in 1..<100 {
+            try ring.append(pts: 100 + Double(i), isKeyframe: i % 4 == 0, isVideo: true,
+                            bytes: Data(repeating: 0, count: size))
+        }
+        let floor = try #require(ring.residentFloorSessionSeconds(sessionStartPts: 100))
+        let oldest = try #require(ring.oldestKeyframePts)
+        #expect(floor == oldest - 100)
+        #expect(floor > 0)
+        #expect(ring.residentFloorSessionSeconds(sessionStartPts: .nan) == nil)
+    }
+
+    // MARK: - Writes that fail
+
+    private final class FlakyDisk: @unchecked Sendable {
+        private let lock = NSLock()
+        private var failures = 0
+        private var capacity: Int?
+        var ring: PacketRingBuffer?
+        private(set) var rejected = 0
+
+        func failNext(_ n: Int) { lock.lock(); failures = n; lock.unlock() }
+        func setCapacity(_ bytes: Int?) { lock.lock(); capacity = bytes; lock.unlock() }
+
+        var writer: PacketRingBuffer.WriteAll {
+            { [self] fd, bytes, offset in
+                lock.lock()
+                var fail = false
+                if failures > 0 { failures -= 1; fail = true }
+                let cap = capacity
+                lock.unlock()
+                if !fail, let cap, let ring, ring.diskBytes + bytes.count > cap { fail = true }
+                if fail {
+                    lock.lock(); rejected += 1; lock.unlock()
+                    throw NSError(domain: NSPOSIXErrorDomain, code: Int(ENOSPC))
+                }
+                try PacketRingBuffer.pwriteAll(fd, bytes, offset)
+            }
+        }
+    }
+
+    private func flakyRing(disk: FlakyDisk, byteBudget: Int = .max) throws -> PacketRingBuffer {
+        let ring = try PacketRingBuffer(windowSeconds: .infinity, scratch: makeScratch(),
+                                        byteBudget: byteBudget, chunkTargetBytes: 64 << 10,
+                                        writeAll: disk.writer)
+        disk.ring = ring
+        return ring
+    }
+
+    @Test("A write that fails once is retried after the oldest chunk is freed, and nothing is dropped")
+    func failedWriteMakesRoomAndRetries() throws {
+        let disk = FlakyDisk()
+        let ring = try flakyRing(disk: disk)
+        defer { ring.close() }
+        let body = Data(repeating: 7, count: 32 << 10)
+        for i in 0..<10 {
+            try ring.append(pts: Double(i), isKeyframe: i % 2 == 0, isVideo: true, bytes: body)
+        }
+        #expect(ring.seqBounds.first == 0)
+        disk.failNext(1)
+        try ring.append(pts: 10, isKeyframe: true, isVideo: true, bytes: body)
+
+        let bounds = ring.seqBounds
+        #expect(bounds.end == 11, "the packet that hit the full disk was stored, not dropped")
+        #expect(bounds.first > 0, "the window shrank to make the room")
+        let first = try #require(ring.packet(atSeq: bounds.first))
+        #expect(first.isKeyframe)
+        #expect(ring.packet(atSeq: 10)?.bytes == body)
+    }
+
+    @Test("A full volume shrinks the rewind window and the live feed keeps flowing")
+    func fullVolumeKeepsFeedingWithAShrinkingWindow() throws {
+        let disk = FlakyDisk()
+        disk.setCapacity(1 << 20)
+        let ring = try flakyRing(disk: disk)
+        defer { ring.close() }
+        let body = { (i: Int) in Data(repeating: UInt8(truncatingIfNeeded: i), count: 16 << 10) }
+        for i in 0..<500 {
+            try ring.append(pts: Double(i) * 0.04, isKeyframe: i % 5 == 0, isVideo: true, bytes: body(i))
+            #expect(ring.seqBounds.end == i + 1, "append \(i) must not freeze at the live edge")
+        }
+        #expect(disk.rejected > 0)
+        #expect(ring.diskBytes <= 1 << 20)
+        let bounds = ring.seqBounds
+        #expect(bounds.first > 0)
+        let first = try #require(ring.packet(atSeq: bounds.first))
+        #expect(first.isKeyframe)
+        #expect(ring.packet(atSeq: 499)?.bytes == body(499))
+    }
+
+    @Test("With nothing reclaimable the append throws cleanly, and the ring recovers when space returns")
+    func nothingToFreeThrowsWithoutCorruption() throws {
+        let disk = FlakyDisk()
+        let ring = try flakyRing(disk: disk)
+        defer { ring.close() }
+        let body = { (i: Int) in Data(repeating: UInt8(truncatingIfNeeded: i), count: 4 << 10) }
+        try ring.append(pts: 0, isKeyframe: true, isVideo: true, bytes: body(0))
+        try ring.append(pts: 1, isKeyframe: false, isVideo: true, bytes: body(1))
+
+        disk.failNext(1)
+        #expect(throws: (any Error).self) {
+            try ring.append(pts: 2, isKeyframe: false, isVideo: true, bytes: body(2))
+        }
+        #expect(ring.seqBounds.end == 2, "a dropped packet leaves no entry behind")
+
+        try ring.append(pts: 3, isKeyframe: false, isVideo: true, bytes: body(3))
+        #expect(ring.seqBounds.end == 3)
+        #expect(ring.packet(atSeq: 0)?.bytes == body(0))
+        #expect(ring.packet(atSeq: 1)?.bytes == body(1))
+        #expect(ring.packet(atSeq: 2)?.bytes == body(3))
+    }
+
+    @Test("An incoming keyframe may replace a retained span that cannot otherwise make room")
+    func incomingKeyframeReplacesATailOnlySpan() throws {
+        let disk = FlakyDisk()
+        let ring = try flakyRing(disk: disk)
+        defer { ring.close() }
+        let body = Data(repeating: 5, count: 4 << 10)
+        for i in 0..<3 {
+            try ring.append(pts: Double(i), isKeyframe: i == 0, isVideo: true, bytes: body)
+        }
+        disk.failNext(1)
+        try ring.append(pts: 3, isKeyframe: true, isVideo: true, bytes: Data(repeating: 6, count: 4 << 10))
+
+        let bounds = ring.seqBounds
+        #expect(bounds.end == 4)
+        #expect(bounds.first == 3)
+        let only = try #require(ring.packet(atSeq: 3))
+        #expect(only.isKeyframe && only.bytes == Data(repeating: 6, count: 4 << 10))
+    }
+
+    // MARK: - Reads beside the writer
+
+    @Test("Readers racing eviction only ever see the bytes of the sequence they asked for")
+    func concurrentReadersSeeConsistentBytes() async throws {
+        let ring = try PacketRingBuffer(windowSeconds: .infinity, scratch: makeScratch(),
+                                        byteBudget: 2 << 20, chunkTargetBytes: 128 << 10)
+        defer { ring.close() }
+        let total = 6000
+        @Sendable func body(_ i: Int) -> Data { Data(repeating: UInt8(truncatingIfNeeded: i), count: 2000 + i % 500) }
+
+        let finished = Counter()
+        let mismatches = Counter()
+        let writerDone = Counter()
+        let writer = Thread {
+            for i in 0..<total {
+                try? ring.append(pts: Double(i) * 0.01, isKeyframe: i % 25 == 0, isVideo: i % 3 != 0, bytes: body(i))
+            }
+            writerDone.add(1)
+            finished.add(1)
+        }
+        var readers: [Thread] = []
+        for r in 0..<3 {
+            readers.append(Thread {
+                var state = UInt64(r + 1) &* 0x9E3779B97F4A7C15
+                while writerDone.value == 0 {
+                    let bounds = ring.seqBounds
+                    guard bounds.end > bounds.first else { continue }
+                    state = state &* 6364136223846793005 &+ 1442695040888963407
+                    let seq = bounds.first + Int(state >> 33) % (bounds.end - bounds.first)
+                    if let p = ring.packet(atSeq: seq) {
+                        if p.bytes != body(seq) || p.isVideo != (seq % 3 != 0) { mismatches.add(1) }
+                    }
+                    if let v = ring.isVideo(atSeq: seq), v != (seq % 3 != 0) { mismatches.add(1) }
+                }
+                finished.add(1)
+            })
+        }
+        writer.start()
+        readers.forEach { $0.start() }
+        try await waitFor { finished.value == 4 }
+        #expect(mismatches.value == 0)
+        #expect(ring.seqBounds.end == total)
+    }
+
+    @Test("isVideo(atSeq:) answers from the index: resident kinds, nil outside the span")
+    func isVideoAnswersFromTheIndex() throws {
+        let ring = try PacketRingBuffer(windowSeconds: .infinity, scratch: makeScratch(), byteBudget: 1 << 20)
+        defer { ring.close() }
+        #expect(ring.isVideo(atSeq: 0) == nil)
+        for i in 0..<300 {
+            try ring.append(pts: Double(i), isKeyframe: i % 6 == 0, isVideo: i % 2 == 0,
+                            bytes: Data(repeating: 1, count: 16 << 10))
+        }
+        let bounds = ring.seqBounds
+        #expect(bounds.first > 0)
+        for seq in bounds.first..<bounds.end {
+            #expect(ring.isVideo(atSeq: seq) == (seq % 2 == 0))
+        }
+        #expect(ring.isVideo(atSeq: bounds.first - 1) == nil)
+        #expect(ring.isVideo(atSeq: bounds.end) == nil)
+    }
+
+    @Test("A chunk file that vanished reads as an unreadable packet, not a crash")
+    func missingChunkFileIsAnUnreadablePacket() throws {
+        let scratch = makeScratch()
+        let ring = try PacketRingBuffer(windowSeconds: .infinity, scratch: scratch, chunkTargetBytes: 64 << 10)
+        defer { ring.close() }
+        for i in 0..<60 {
+            try ring.append(pts: Double(i), isKeyframe: i % 4 == 0, isVideo: true,
+                            bytes: Data(repeating: UInt8(i), count: 30 << 10))
+        }
+        // The oldest chunk is well outside the read-handle cache by now.
+        try FileManager.default.removeItem(at: scratch.appendingPathComponent("chunk-0.bin"))
+        #expect(ring.seqBounds.first == 0)
+        #expect(ring.packet(atSeq: 0) == nil)
+        #expect(ring.packet(atSeq: 59)?.bytes.count == 30 << 10)
+    }
+}
+
+private final class Counter: @unchecked Sendable {
+    private let lock = NSLock()
+    private var n = 0
+    var value: Int { lock.lock(); defer { lock.unlock() }; return n }
+    func add(_ d: Int) { lock.lock(); n += d; lock.unlock() }
+}
diff --git a/docs/api.md b/docs/api.md
index 0156678a0..40b64e814 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -560,7 +560,7 @@ Time lives on `player.clock`, a separate `ObservableObject`, so ~10 Hz ticks nev
 | `clock.$sourceTimeFollowsPicture` | whether `sourceTime` is known to follow the displayed frame. Always true except on `nativeRemoteHLS`, where it is true only while the lead is measured since the last time jump (AE#616); see below the table. |
 | `clock.$progress` | `currentTime / duration` |
 | `clock.$bufferedPosition` | source-axis position buffered ahead |
-| `clock.$liveEdgeTime`, `clock.$seekableLiveRange`, `clock.$behindLiveSeconds`, `clock.$isAtLiveEdge` | live-window surfaces. `seekableLiveRange` is the intersection of the DVR window (policy) and what the segment cache actually holds and can play forward from (fact), so it is honest to scale a rewind strip on and `seek(to:)` clamps to the same floor (AE#441). The two diverge for the whole first `dvrWindowSeconds` of a session and again whenever retention evicts faster than the window slides. Software live sessions have no such cache and keep the arithmetic bound. |
+| `clock.$liveEdgeTime`, `clock.$seekableLiveRange`, `clock.$behindLiveSeconds`, `clock.$isAtLiveEdge` | live-window surfaces. `seekableLiveRange` is the intersection of the DVR window (policy) and what the segment cache actually holds and can play forward from (fact), so it is honest to scale a rewind strip on and `seek(to:)` clamps to the same floor (AE#441). The two diverge for the whole first `dvrWindowSeconds` of a session and again whenever retention evicts faster than the window slides. Software live sessions hold a packet ring instead, which evicts by the same byte budget as the native cache (a quarter of the volume's free space, at most 2 GiB, at least 64 MiB), so the range's floor follows the ring once eviction has moved it past the window. |
 | `$residentRanges` | where the loopback segment cache holds picture right now, as disjoint ascending spans on the `currentTime` axis. This is the cache's own truth, not AVPlayer's `loadedTimeRanges`: a measured session held 64 segments over four minutes across several islands while AVPlayer exposed roughly twelve seconds around the playhead and forgot a seeked-ahead island as soon as the playhead left it. Empty is the nil-equivalent, and a live session publishes empty always (its rewind depth is `seekableLiveRange`, which answers a different question). Residency is not a promise that a seek inside a span is instant: the player may still re-anchor and decode at the target, and a segment can start mid-GOP (AE#412). Coalesced to at most four updates a second, cleared on `load()` and teardown. |
 | `player.currentTime`, `sourceTime`, `sourceTimeFollowsPicture`, `progress`, `bufferedPosition`, `liveEdgeTime`, `seekableLiveRange`, `behindLiveSeconds`, `isAtLiveEdge` | non-published mirrors of the same values for one-shot reads |
 | `$duration` | seconds; a `LoadOptions.declaredDurationSeconds` outranks the container's |
@@ -944,7 +944,7 @@ All flags default to safe values; the table is the full set. Depth for the media
 | --- | --- | --- |
 | `httpHeaders` | empty | Extra headers on every probe, range and segment fetch. On `nativeRemoteHLS` they ride into the `AVURLAsset`, so header-enforcing IPTV origins work. Forwarded to sidecar subtitle fetches unless overridden. |
 | `isLive` | false | Treat the source as live. Set it explicitly; duration-based auto-detection is too noisy. |
-| `dvrWindowSeconds` | nil | Timeshift window. nil means live-only and `seek` is a no-op. |
+| `dvrWindowSeconds` | nil | Timeshift window. nil means live-only and `seek` is a no-op. The window is a ceiling: the disk budget (a quarter of the free space, at most 2 GiB) bounds what is actually kept, so a long window on a high-bitrate channel or a small volume holds less than it asks for. |
 | `liveJoinProfile` | `.standard` | A `LiveJoinProfile`. `.fastZap` collapses TARGETDURATION to the source GOP so an IPTV join costs seconds instead of a full holdback. |
 | `clampsLiveResumeToWindow` | true | Whether `play()` may move a behind-live playhead by itself (edge snap on a live-only source more than 45 s behind, or a landing above the retained floor when a DVR window has slid past it). `false` hands the whole decision to the host, which then also owns the eviction case. |
 | `liveJoinStartsImmediately` | true | Cuts AVPlayer's stall-avoidance wait short once at the live join, over a buffer that is non-empty and at least 1.5 s deep. The join tail no host can otherwise reach; default since 6.55.0 on a device A/B, see the live-join section. |
diff --git a/docs/architecture.md b/docs/architecture.md
index a97e02700..9391a2e95 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -491,7 +491,8 @@ Sources/AetherEngine/
 │   ├── NALUnitChain.swift                   Final-stage payload guard before the fMP4 mux: a video sample whose length-prefixed NAL chain overruns it is cut at its last complete unit, because Apple's parser answers one such sample with -19602 for the whole segment (AE#561)
 │   ├── AudioLanguageMap.swift               Native path: the ISO 639-2/T an audio track is declared with in the master's `EXT-X-MEDIA:TYPE=AUDIO` rendition and written into its `mdhd`; ICU in front of the twenty ISO 639-2/B bibliographic codes Matroska writes, then canonicalization for the ISO 639-3 members CLDR aliases and pass-through for the ones it does not, failing closed on anything ICU can neither resolve nor name (AE#458)
 │   ├── FragmentSplitter.swift               Native path: routes mp4 muxer's avio output stream into init.mp4 (ftyp+moov) vs per-segment moof+mdat files
-│   ├── PacketRingBuffer.swift               Live path: keyframe-indexed, disk-spooled packet ring backing the SW-path DVR rewind
+│   ├── PacketRingBuffer.swift               Live path: keyframe-indexed, disk-spooled packet ring backing the SW-path DVR rewind (append-only chunk files, a 24-byte index record per packet, eviction by time and by the session retention budget, evict-and-retry when a write fails)
+│   ├── SessionDirectoryLiveness.swift       The flock marker a session directory under `aether-segments/` holds for its owner's lifetime, so the stale-session sweep spares a live SegmentCache or DVR ring (AE#451, SEG-105)
 │   ├── SegmentCache.swift                   Native path: producer/consumer segment store with backpressure, scrub-aware eviction + byte-budgeted VOD backward retention (restart-free back-seeks)
 │   ├── VTCapabilityProbe.swift              AV1 system-decode probe + per-format `canHardwareDecode` HW-decodability check for H.264 / HEVC profiles (Intel Macs, older chips, #2); gates codec routing (VP9 / VP8 / MPEG-4 Part 2 / MPEG-2 / VC-1 and interlaced H.264 always route SW, see VideoRoutingPolicy)
 │   ├── LiveCadencePolicy.swift              Turns the observed arrival cadence into the two LL-HLS decisions (served TARGETDURATION, blocking-reload eligibility), re-evaluated on every manifest render, instead of trusting a bursty origin's own number

From f6d84ea8fab9143e43f3e15ea96a6c70670954cf Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 09:02:25 +0200
Subject: [PATCH 195/359] test: skip instead of pass, wait instead of poll,
 keep scratch files out of the checkout (audit OPS-108, OPS-109, Vops-1)

Seven tests that returned early and reported a pass now carry .enabled(if:)
traits (the PGS sidecar pair, the three hardware deinterlace tests) or load
their source file with a throwing call (Issue458, Issue541). The 15 s
private poll deadline in SequentialLongGOPPlaylistTests and the four older
1 to 2 s polls with try? (Issue220, Issue281, Issue378, SourcePrewarmAdoption)
use waitFor, with a .timeLimit as the hang catcher. ProbeTestFixtures.withFile
and the missing-file probe path write under the temporary directory instead
of the working directory.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../DeinterlaceHardwareTests.swift            | 30 +++++++++-------
 .../Issue220BoundedRangeTests.swift           |  6 ++--
 .../Issue281ColdStartRoundTripTests.swift     |  6 ++--
 .../Issue378SourceRefusedTests.swift          |  6 ++--
 .../Issue458AudibleReadbackTests.swift        |  2 +-
 .../Issue541ReloadCarriesHDRRouteTests.swift  |  2 +-
 .../AetherEngineTests/ProbeControlTests.swift |  2 +-
 .../SequentialLongGOPPlaylistTests.swift      | 10 ++----
 .../SidecarPGSDecodeTests.swift               | 34 ++++++++++---------
 .../SourcePrewarmAdoptionTests.swift          |  6 ++--
 .../Support/ProbeControlTestSupport.swift     |  5 +--
 11 files changed, 52 insertions(+), 57 deletions(-)

diff --git a/Tests/AetherEngineTests/DeinterlaceHardwareTests.swift b/Tests/AetherEngineTests/DeinterlaceHardwareTests.swift
index 4daa6708c..51c713a56 100644
--- a/Tests/AetherEngineTests/DeinterlaceHardwareTests.swift
+++ b/Tests/AetherEngineTests/DeinterlaceHardwareTests.swift
@@ -8,11 +8,15 @@ import AetherLibavfilter
 /// AV_PIX_FMT_VIDEOTOOLBOX frames wrapping CVPixelBuffers, and mode=send_field doubles the
 /// output cadence on the sink's time_base.
 ///
-/// Both tests self-skip (early return, engine falls back to .software) when the linked build has
-/// no yadif_videotoolbox or the machine has no Metal device (CI VMs), the fallback itself is
-/// covered by the software tests.
+/// The three tests are reported as skipped (not passed) when the linked build has no
+/// yadif_videotoolbox or the machine has no Metal device (CI VMs): the engine then falls back to
+/// .software, and the fallback itself is covered by the software tests.
 struct DeinterlaceHardwareTests {
 
+    /// Built once: the probe stands up and tears down a whole filter graph.
+    private static let hardwareAvailable = DeinterlaceFilter.prewarmHardwarePipeline()
+    private static let needsHardware: Comment = "needs yadif_videotoolbox and a Metal device"
+
     private func makeFrame(pts: Int64) -> UnsafeMutablePointer<AVFrame> {
         let f = av_frame_alloc()!
         f.pointee.width = 64
@@ -52,7 +56,7 @@ struct DeinterlaceHardwareTests {
             guard hardware else {
                 var ff: UnsafeMutablePointer<AVFrame>? = f
                 av_frame_free(&ff)
-                return ([], false)  // no yadif_videotoolbox / no Metal device: caller skips
+                return ([], false)
             }
 
             #expect(filter.push(f) >= 0)
@@ -72,7 +76,8 @@ struct DeinterlaceHardwareTests {
         return (seconds, hardware)
     }
 
-    @Test("HW engine emits VideoToolbox frames wrapping CVPixelBuffers")
+    @Test("HW engine emits VideoToolbox frames wrapping CVPixelBuffers",
+          .enabled(if: DeinterlaceHardwareTests.hardwareAvailable, DeinterlaceHardwareTests.needsHardware))
     func hardwareEmitsVideoToolboxFrames() {
         var sawVTFrame = false
         let (seconds, hardware) = run(fieldRate: .field, count: 8) { out in
@@ -91,18 +96,18 @@ struct DeinterlaceHardwareTests {
                 Issue.record("AV_PIX_FMT_VIDEOTOOLBOX frame with nil data[3]")
             }
         }
-        guard hardware else { return }  // linked build predates yadif_videotoolbox, or no Metal
+        #expect(hardware)
         #expect(sawVTFrame, "hw graph engaged but produced no frames")
         #expect(!seconds.isEmpty)
     }
 
-    @Test("send_field doubles output cadence; send_frame keeps it")
+    @Test("send_field doubles output cadence; send_frame keeps it",
+          .enabled(if: DeinterlaceHardwareTests.hardwareAvailable, DeinterlaceHardwareTests.needsHardware))
     func fieldRateControlsCadence() {
         let streamTBSeconds = 1.0 / 30.0
         let (fieldSeconds, hwField) = run(fieldRate: .field, count: 8)
-        guard hwField else { return }  // self-skip, see type doc
         let (frameSeconds, hwFrame) = run(fieldRate: .frame, count: 8)
-        guard hwFrame else { return }
+        #expect(hwField && hwFrame)
 
         // Field rate must produce ~2x the frames of frame rate (lookahead trims the tails).
         #expect(fieldSeconds.count > frameSeconds.count + 2,
@@ -129,11 +134,10 @@ struct DeinterlaceHardwareTests {
         }
     }
 
-    @Test("warm-up releases its temporary graph and a fresh hardware graph remains usable")
+    @Test("warm-up releases its temporary graph and a fresh hardware graph remains usable",
+          .enabled(if: DeinterlaceHardwareTests.hardwareAvailable, DeinterlaceHardwareTests.needsHardware))
     func warmupLeavesFreshGraphUsable() {
-        guard DeinterlaceFilter.prewarmHardwarePipeline() else {
-            return
-        }
+        #expect(DeinterlaceFilter.prewarmHardwarePipeline())
 
         let (seconds, hardware) = run(fieldRate: .field, count: 8)
         #expect(hardware)
diff --git a/Tests/AetherEngineTests/Issue220BoundedRangeTests.swift b/Tests/AetherEngineTests/Issue220BoundedRangeTests.swift
index 1f9735397..6614b5c28 100644
--- a/Tests/AetherEngineTests/Issue220BoundedRangeTests.swift
+++ b/Tests/AetherEngineTests/Issue220BoundedRangeTests.swift
@@ -75,7 +75,7 @@ struct Issue220BoundedRangeTests {
     /// the window legitimately opens the next range AT the frontier. A count cannot tell that
     /// apart from a re-fetch: this asserted two requests and saw three on a loaded CI runner,
     /// where the third was `bytes=524288-34078719`, the refill doing its job.
-    @Test("a completed range is read out of the window, not fetched again")
+    @Test("a completed range is read out of the window, not fetched again", .timeLimit(.minutes(1)))
     func completedRangeIsNotRefetched() async throws {
         let server = try #require(ThrottledOriginServer(totalSize: 512 * 1024 * 1024))
         defer { server.stop() }
@@ -91,9 +91,7 @@ struct Issue220BoundedRangeTests {
         defer { buf.deallocate() }
         _ = reader.read(into: buf, size: 64 * 1024)
         // Let the bounded range finish and its completion callback clear activeTask.
-        for _ in 0..<100 where reader.hasLiveConnectionForTesting {
-            try? await Task.sleep(nanoseconds: 10_000_000)
-        }
+        try await waitFor { !reader.hasLiveConnectionForTesting }
 
         // Still inside the delivered range, so the bytes come out of the window.
         #expect(reader.read(into: buf, size: 64 * 1024) == 64 * 1024)
diff --git a/Tests/AetherEngineTests/Issue281ColdStartRoundTripTests.swift b/Tests/AetherEngineTests/Issue281ColdStartRoundTripTests.swift
index ac63d15bf..44d5c677a 100644
--- a/Tests/AetherEngineTests/Issue281ColdStartRoundTripTests.swift
+++ b/Tests/AetherEngineTests/Issue281ColdStartRoundTripTests.swift
@@ -300,7 +300,7 @@ struct Issue281ColdStartRoundTripTests {
     /// itself is still a second connection opened at the same instant as the data connection whose
     /// first byte IS the cold start, and paid again on every open, against a server that has already
     /// shown it cannot serve it.
-    @Test("an origin that declined a suffix range is not asked again")
+    @Test("an origin that declined a suffix range is not asked again", .timeLimit(.minutes(1)))
     func declinedSuffixRangesAreNotRetried() async throws {
         let declared: Int64 = 4 * 1024 * 1024 * 1024
         let server = try #require(ScriptedOriginServer { recorded in
@@ -317,9 +317,7 @@ struct Issue281ColdStartRoundTripTests {
 
         let first = AVIOReader(url: url)
         try first.open()
-        for _ in 0..<100 where SuffixRangeSupport.shared.denialReason(for: url) == nil {
-            try? await Task.sleep(nanoseconds: 20_000_000)
-        }
+        try await waitFor { SuffixRangeSupport.shared.denialReason(for: url) != nil }
         first.markClosed(); first.close()
 
         let reason = try #require(SuffixRangeSupport.shared.denialReason(for: url),
diff --git a/Tests/AetherEngineTests/Issue378SourceRefusedTests.swift b/Tests/AetherEngineTests/Issue378SourceRefusedTests.swift
index da879bc26..8f0557208 100644
--- a/Tests/AetherEngineTests/Issue378SourceRefusedTests.swift
+++ b/Tests/AetherEngineTests/Issue378SourceRefusedTests.swift
@@ -96,7 +96,7 @@ struct Issue378SourceRefusedTests {
 
     /// The regression guard for #281: an origin that answers the suffix form itself — here with a
     /// 416 — is still remembered after one occurrence.
-    @Test("a 416 to the suffix form still latches")
+    @Test("a 416 to the suffix form still latches", .timeLimit(.minutes(1)))
     func rangeNotSatisfiableStillLatches() async throws {
         let declared: Int64 = 4 * 1024 * 1024 * 1024
         let server = try #require(ScriptedOriginServer { recorded in
@@ -114,9 +114,7 @@ struct Issue378SourceRefusedTests {
         let reader = AVIOReader(url: url)
         defer { reader.markClosed(); reader.close() }
         try reader.open()
-        for _ in 0..<100 where SuffixRangeSupport.shared.denialReason(for: url) == nil {
-            try? await Task.sleep(nanoseconds: 20_000_000)
-        }
+        try await waitFor { SuffixRangeSupport.shared.denialReason(for: url) != nil }
         let reason = try #require(SuffixRangeSupport.shared.denialReason(for: url))
         #expect(reason.contains("416"))
     }
diff --git a/Tests/AetherEngineTests/Issue458AudibleReadbackTests.swift b/Tests/AetherEngineTests/Issue458AudibleReadbackTests.swift
index 375c5c0ad..7151397f6 100644
--- a/Tests/AetherEngineTests/Issue458AudibleReadbackTests.swift
+++ b/Tests/AetherEngineTests/Issue458AudibleReadbackTests.swift
@@ -122,7 +122,7 @@ struct Issue458AudibleReadbackTests {
             .deletingLastPathComponent()
             .deletingLastPathComponent()
             .appendingPathComponent("Sources/AetherEngine/AetherEngine+Loading.swift")
-        guard let text = try? String(contentsOf: source, encoding: .utf8) else { return }
+        let text = try String(contentsOf: source, encoding: .utf8)
         #expect(text.contains("logAudibleReadback(host: host)"))
     }
 }
diff --git a/Tests/AetherEngineTests/Issue541ReloadCarriesHDRRouteTests.swift b/Tests/AetherEngineTests/Issue541ReloadCarriesHDRRouteTests.swift
index 8ac481a24..91478d7db 100644
--- a/Tests/AetherEngineTests/Issue541ReloadCarriesHDRRouteTests.swift
+++ b/Tests/AetherEngineTests/Issue541ReloadCarriesHDRRouteTests.swift
@@ -110,7 +110,7 @@ struct Issue541ReloadCarriesHDRRouteTests {
             .deletingLastPathComponent()
             .deletingLastPathComponent()
             .appendingPathComponent("Sources/AetherEngine/AetherEngine+Loading.swift")
-        guard let text = try? String(contentsOf: source, encoding: .utf8) else { return }
+        let text = try String(contentsOf: source, encoding: .utf8)
         #expect(!text.contains("panelIsInHDRMode: loadedOptions.panelIsInHDRMode"))
         #expect(text.contains("panelIsInHDRMode: reloadRoutingPanelHDR"))
     }
diff --git a/Tests/AetherEngineTests/ProbeControlTests.swift b/Tests/AetherEngineTests/ProbeControlTests.swift
index e0b61b3eb..7b1226122 100644
--- a/Tests/AetherEngineTests/ProbeControlTests.swift
+++ b/Tests/AetherEngineTests/ProbeControlTests.swift
@@ -571,7 +571,7 @@ struct ProbeControlTests {
     func filePrecancelled(_ entry: EntryPoint) {
         let token = ProbeCancellation()
         token.cancel()
-        let missing = URL(fileURLWithPath: FileManager.default.currentDirectoryPath)
+        let missing = FileManager.default.temporaryDirectory
             .appendingPathComponent(".missing-probe-\(UUID().uuidString).mp4")
         #expect(throws: CancellationError.self) { try entry.probe(missing, cancellation: token) }
     }
diff --git a/Tests/AetherEngineTests/SequentialLongGOPPlaylistTests.swift b/Tests/AetherEngineTests/SequentialLongGOPPlaylistTests.swift
index 0d32ca006..b75514f40 100644
--- a/Tests/AetherEngineTests/SequentialLongGOPPlaylistTests.swift
+++ b/Tests/AetherEngineTests/SequentialLongGOPPlaylistTests.swift
@@ -82,13 +82,9 @@ struct SequentialLongGOPPlaylistTests {
         defer { engine.stop() }
         let mediaURL = try #require(engine.mediaPlaylistURL)
 
-        var playlist = ""
-        for _ in 0..<300 {
-            playlist = (try? String(contentsOf: mediaURL, encoding: .utf8)) ?? ""
-            if playlist.contains("#EXT-X-ENDLIST") { break }
-            try await Task.sleep(nanoseconds: 50_000_000)
-        }
-        #expect(playlist.contains("#EXT-X-ENDLIST"), "the playlist never completed:\n\(playlist)")
+        func playlistText() -> String { (try? String(contentsOf: mediaURL, encoding: .utf8)) ?? "" }
+        try await waitFor { playlistText().contains("#EXT-X-ENDLIST") }
+        let playlist = playlistText()
 
         let lines = playlist.split(whereSeparator: \.isNewline).map(String.init)
         let durations = lines.filter { $0.hasPrefix("#EXTINF:") }
diff --git a/Tests/AetherEngineTests/SidecarPGSDecodeTests.swift b/Tests/AetherEngineTests/SidecarPGSDecodeTests.swift
index a371a434a..923fd5896 100644
--- a/Tests/AetherEngineTests/SidecarPGSDecodeTests.swift
+++ b/Tests/AetherEngineTests/SidecarPGSDecodeTests.swift
@@ -4,23 +4,25 @@ import Foundation
 
 /// External PGS sidecar decode (Jellyfin serves external PGS tracks as raw .sup streams). The
 /// fixture is local-only like the restart-witness clips (extract one with:
-/// `ffmpeg -i <mkv-with-pgs> -map 0:s:0 -c copy Fixtures/external-pgs.sup`); the test skips when
-/// absent (CI). Requires FFmpegBuild >= 2.1.3 (sup demuxer in the allowlist).
+/// `ffmpeg -i <mkv-with-pgs> -map 0:s:0 -c copy Fixtures/external-pgs.sup`); the tests are reported
+/// as skipped when it is absent (CI). Requires FFmpegBuild >= 2.1.3 (sup demuxer in the allowlist).
 @Suite("Sidecar PGS decode")
 struct SidecarPGSDecodeTests {
-    private var fixtureURL: URL {
-        URL(fileURLWithPath: #filePath)
-            .deletingLastPathComponent()   // AetherEngineTests
-            .deletingLastPathComponent()   // Tests
-            .deletingLastPathComponent()   // repo root
-            .appendingPathComponent("Fixtures")
-            .appendingPathComponent("external-pgs.sup")
-    }
+    private static let fixtureURL = URL(fileURLWithPath: #filePath)
+        .deletingLastPathComponent()   // AetherEngineTests
+        .deletingLastPathComponent()   // Tests
+        .deletingLastPathComponent()   // repo root
+        .appendingPathComponent("Fixtures")
+        .appendingPathComponent("external-pgs.sup")
+
+    private static let fixtureExists = FileManager.default.fileExists(atPath: fixtureURL.path)
+
+    private static let missingFixture: Comment = "needs Fixtures/external-pgs.sup (extract one with the ffmpeg command above)"
 
-    @Test("raw .sup sidecar decodes into image cues with monotonic timing")
+    @Test("raw .sup sidecar decodes into image cues with monotonic timing",
+          .enabled(if: SidecarPGSDecodeTests.fixtureExists, SidecarPGSDecodeTests.missingFixture))
     func supSidecarDecodes() async throws {
-        guard FileManager.default.fileExists(atPath: fixtureURL.path) else { return }
-        let result = try await SubtitleDecoder.decodeFile(url: fixtureURL, httpHeaders: [:], preserveASSMarkup: false)
+        let result = try await SubtitleDecoder.decodeFile(url: Self.fixtureURL, httpHeaders: [:], preserveASSMarkup: false)
         #expect(!result.cues.isEmpty)
         var lastStart = -1.0
         for cue in result.cues {
@@ -35,10 +37,10 @@ struct SidecarPGSDecodeTests {
         }
     }
 
-    @Test("OCR fill turns a .sup sidecar's image cues into non-empty text cues")
+    @Test("OCR fill turns a .sup sidecar's image cues into non-empty text cues",
+          .enabled(if: SidecarPGSDecodeTests.fixtureExists, SidecarPGSDecodeTests.missingFixture))
     func supSidecarOCRFill() async throws {
-        guard FileManager.default.fileExists(atPath: fixtureURL.path) else { return }
-        let result = try await SubtitleDecoder.decodeFile(url: fixtureURL, httpHeaders: [:], preserveASSMarkup: false)
+        let result = try await SubtitleDecoder.decodeFile(url: Self.fixtureURL, httpHeaders: [:], preserveASSMarkup: false)
         let store = NativeSubtitleCueStore()
         await SubtitleImageOCR.appendRecognized(cues: Array(result.cues.prefix(8)), language: "eng", to: store)
         let recognized = store.snapshotCues()
diff --git a/Tests/AetherEngineTests/SourcePrewarmAdoptionTests.swift b/Tests/AetherEngineTests/SourcePrewarmAdoptionTests.swift
index 7317fd4dd..e692fde65 100644
--- a/Tests/AetherEngineTests/SourcePrewarmAdoptionTests.swift
+++ b/Tests/AetherEngineTests/SourcePrewarmAdoptionTests.swift
@@ -207,7 +207,7 @@ struct SourcePrewarmAdoptionTests {
     /// write-once rule treats any positive `fileSize` as settled, so a warm that belongs to a
     /// different response would fix a wrong EOF point for the whole session. The connection that is
     /// actually serving the session gets to overrule it.
-    @Test("a connection that states a different size drops the warm")
+    @Test("a connection that states a different size drops the warm", .timeLimit(.minutes(1)))
     func sizeMismatchDropsTheWarm() async throws {
         SourcePrewarmStore.shared.clear()
         let server = try #require(ThrottledOriginServer(totalSize: fileSize))
@@ -220,9 +220,7 @@ struct SourcePrewarmAdoptionTests {
         let reader = AVIOReader(url: url(server))
         defer { reader.markClosed(); reader.close() }
         try reader.open()
-        for _ in 0..<100 where reader.resolvedByteSize != restated {
-            try? await Task.sleep(nanoseconds: 20_000_000)
-        }
+        try await waitFor { reader.resolvedByteSize == restated }
 
         #expect(reader.resolvedByteSize == restated,
                 "the session kept the warm's size over the one its own connection stated")
diff --git a/Tests/AetherEngineTests/Support/ProbeControlTestSupport.swift b/Tests/AetherEngineTests/Support/ProbeControlTestSupport.swift
index 0a0351aaf..39cbcd120 100644
--- a/Tests/AetherEngineTests/Support/ProbeControlTestSupport.swift
+++ b/Tests/AetherEngineTests/Support/ProbeControlTestSupport.swift
@@ -224,9 +224,10 @@ enum ProbeTestFixtures {
         try decode(AtmosDetectionProbeIntegrationTests.eac3PlainBase64)
     }
 
-    /// Scratch fixtures stay under the checkout, never the system temporary directory.
+    /// Scratch fixtures live in the temporary directory: one written into the working directory is left
+    /// in the checkout when the process dies inside the body (audit OPS-109).
     static func withFile<T>(_ data: Data, _ body: (URL) throws -> T) throws -> T {
-        let url = URL(fileURLWithPath: FileManager.default.currentDirectoryPath, isDirectory: true)
+        let url = FileManager.default.temporaryDirectory
             .appendingPathComponent(".probe-control-\(UUID().uuidString).mp4")
         defer { try? FileManager.default.removeItem(at: url) }
         try data.write(to: url)

From 7224c45623ef6997687df1d4fa0a5182283fcb8d Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 09:02:53 +0200
Subject: [PATCH 196/359] fix(demo): the notarized demo drops its two
 hardened-runtime exceptions (audit OPS-112)

build-dmg.sh granted disable-library-validation and
allow-unsigned-executable-memory with a comment saying to drop them after a
clean notarization run. The frameworks are re-signed in the same run with
the same Developer ID, so library validation has nothing to exempt, and
nothing in the demo needs JIT memory. The entitlements file is now empty.
Takes effect at the next release (re-notarize and launch once on a clean
account).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 Examples/DemoPlayerMac/Scripts/build-dmg.sh | 20 ++++++++------------
 1 file changed, 8 insertions(+), 12 deletions(-)

diff --git a/Examples/DemoPlayerMac/Scripts/build-dmg.sh b/Examples/DemoPlayerMac/Scripts/build-dmg.sh
index 86bf85b47..96dd1fe23 100755
--- a/Examples/DemoPlayerMac/Scripts/build-dmg.sh
+++ b/Examples/DemoPlayerMac/Scripts/build-dmg.sh
@@ -183,22 +183,18 @@ cat > "$APP_DIR/Contents/Info.plist" <<PLIST
 </plist>
 PLIST
 
-# Hardened Runtime entitlements. Both flags are conservative defaults
-# for a SwiftUI app that ships static FFmpeg libraries: the unsigned
-# executable memory entitlement covers Swift / SwiftUI runtime JIT
-# paths; the library-validation disable is a safety net in case
-# FFmpegBuild ever introduces a dynamic load. Drop them once a clean
-# notarization run confirms they're unnecessary.
+# Hardened Runtime with no exceptions. The two this script used to grant
+# (allow-unsigned-executable-memory, disable-library-validation) were
+# conservative defaults waiting on a clean notarization run; the frameworks
+# are embedded and re-signed below with the same Developer ID as the app, so
+# library validation has nothing to exempt, and nothing here needs JIT memory
+# (audit OPS-112). If a launch ever fails with a dyld or code-signing error,
+# the error names the framework that needs its own fix, not a blanket key.
 cat > "$ENTITLEMENTS" <<ENT
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
-<dict>
-    <key>com.apple.security.cs.allow-unsigned-executable-memory</key>
-    <true/>
-    <key>com.apple.security.cs.disable-library-validation</key>
-    <true/>
-</dict>
+<dict/>
 </plist>
 ENT
 

From 4dc30a517e767d8a968af95733d0da606ad5fc2e Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 09:02:57 +0200
Subject: [PATCH 197/359] fix(stills): no-base-layer Dolby Vision cache stills
 stay off VideoToolbox (audit BIT-102)

a8d71840 put every DataIOReader still on VideoToolbox. 10-bit 4:2:0 comes back
as P010 there, DolbyVisionStillConverter accepts only yuv420p10le, and the
IPT-PQ-C2 planes of a Profile 5 / 10.0 title then went through the BT.2020
tone map: the green / magenta cast #103 fixed, back on every DV P5 title
scrubbed without Jellyfin trickplay.

The hardware gate in FrameDecodeContext.openInternal now also requires a
base layer (partial revert for that one profile class). A real Profile 5
fixture opened from a cache reader reports the software decoder after open;
before, it took VideoToolbox.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../FrameExtractor/FrameDecodeContext.swift   | 11 ++++++-
 .../FrameDecodeContextHardwareTests.swift     | 32 +++++++++++++++++++
 2 files changed, 42 insertions(+), 1 deletion(-)

diff --git a/Sources/AetherEngine/FrameExtractor/FrameDecodeContext.swift b/Sources/AetherEngine/FrameExtractor/FrameDecodeContext.swift
index 4a3e99346..ce40de84e 100644
--- a/Sources/AetherEngine/FrameExtractor/FrameDecodeContext.swift
+++ b/Sources/AetherEngine/FrameExtractor/FrameDecodeContext.swift
@@ -82,6 +82,14 @@ final class FrameDecodeContext: @unchecked Sendable {
         return false
     }
 
+    /// Whether this open may ask VideoToolbox. A no-base-layer Dolby Vision title stays on software
+    /// (audit BIT-102): VideoToolbox hands 10-bit 4:2:0 over as P010, `DolbyVisionStillConverter` accepts
+    /// only `yuv420p10le`, and the IPT-PQ-C2 planes then went through the BT.2020 tone map, which is the
+    /// green / magenta cast #103 fixed.
+    static func stillUsesHardware(allows: Bool, disabled: Bool, dvNoBaseLayer: Bool) -> Bool {
+        allows && !disabled && !dvNoBaseLayer
+    }
+
     /// Thread budget for the disposable still/thumbnail decoder. Capped well below the
     /// core count so it cannot grab every core at playback's QoS and starve the
     /// real-time software decode (and, with subs on, the subtitle side-demuxer) on a
@@ -215,7 +223,8 @@ final class FrameDecodeContext: @unchecked Sendable {
             throw FrameDecodeError.unsupportedCodec
         }
         var openedWithHardware = false
-        if allowsHardwareDecode, !hardwareDecodeDisabled {
+        if Self.stillUsesHardware(allows: allowsHardwareDecode, disabled: hardwareDecodeDisabled,
+                                  dvNoBaseLayer: isDolbyVisionNoBaseLayer) {
             let deviceResult = av_hwdevice_ctx_create(
                 &hardwareDeviceContext, AV_HWDEVICE_TYPE_VIDEOTOOLBOX, nil, nil, 0)
             if deviceResult >= 0, hardwareDeviceContext != nil {
diff --git a/Tests/AetherEngineTests/FrameDecodeContextHardwareTests.swift b/Tests/AetherEngineTests/FrameDecodeContextHardwareTests.swift
index 7d5751f0e..85f254e9f 100644
--- a/Tests/AetherEngineTests/FrameDecodeContextHardwareTests.swift
+++ b/Tests/AetherEngineTests/FrameDecodeContextHardwareTests.swift
@@ -30,6 +30,38 @@ struct FrameDecodeContextHardwareTests {
         #expect(context.hardwareDecoderName == "none")
     }
 
+    /// Audit BIT-102: a cache-backed still went through VideoToolbox for every title, including Dolby
+    /// Vision Profile 5 / 10.0 whose planes are IPT-PQ-C2. VideoToolbox's P010 output skips the DV
+    /// converter, which only takes `yuv420p10le`, so those thumbnails carried the #103 cast again.
+    @Test("a no-base-layer Dolby Vision record never takes the hardware path")
+    func noBaseLayerStaysOnSoftware() {
+        #expect(FrameDecodeContext.stillUsesHardware(allows: true, disabled: false, dvNoBaseLayer: false))
+        #expect(!FrameDecodeContext.stillUsesHardware(allows: true, disabled: false, dvNoBaseLayer: true))
+        #expect(!FrameDecodeContext.stillUsesHardware(allows: true, disabled: true, dvNoBaseLayer: false))
+        #expect(!FrameDecodeContext.stillUsesHardware(allows: false, disabled: false, dvNoBaseLayer: false))
+    }
+
+    private static let profile5FixtureURL = URL(fileURLWithPath: #filePath)
+        .deletingLastPathComponent()
+        .deletingLastPathComponent()
+        .deletingLastPathComponent()
+        .appendingPathComponent(
+            "Fixtures/user/Patterns_Of_Nature_DoVi_24_P5_UHD_HEVC-10mbps_DD+JOC-768kbps_iOS.mp4")
+
+    /// Dolby's own Profile 5 signal (see `DolbyVisionRecordAuditTests`), which cannot be committed.
+    @Test("a real Profile 5 title opened from a cache reader decodes in software",
+          .enabled(if: FileManager.default.fileExists(atPath: FrameDecodeContextHardwareTests.profile5FixtureURL.path)))
+    func profile5FromCacheReaderIsSoftware() throws {
+        let data = try Data(contentsOf: Self.profile5FixtureURL, options: .alwaysMapped)
+        let context = FrameDecodeContext(reader: DataIOReader(data: data), formatHint: "mp4")
+        defer { context.close() }
+
+        try context.ensureOpen()
+
+        #expect(context.isDolbyVisionNoBaseLayer)
+        #expect(context.hardwareDecoderName == "none")
+    }
+
     /// One 64x64 MPEG-4 Part 2 frame. VideoToolbox does not offer that legacy codec, while
     /// FFmpeg's software decoder does; this is the deterministic decline/fallback witness.
     /// Regenerate with:

From 532f7040e8bebf22dc91daf0e723b6a111c6a582 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 09:02:57 +0200
Subject: [PATCH 198/359] fix(subtitles): an injected rendition is matched on
 its playlist identity, not on a display name (audit NAT-104)

selectInjectedSubtitleRendition took the first option whose NAME or localized
displayName equalled the sidecar's served NAME. AVFoundation derives the
display name from LANGUAGE, so the origin's own "English CC" rendition reads
back as "English" and, sitting ahead of the injected ones in the served
master, won over the sidecar asked for.

The match is now (playlistName ?? displayName) == name, the injectionKey rule
the dedupe and the auto-select mirror already use, through a pure helper.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../AetherEngine/AetherEngine+Subtitles.swift | 15 ++++---
 .../Native/RemoteHLSMediaSelection.swift      |  8 ++++
 .../InjectedRenditionSelectionTests.swift     | 44 +++++++++++++++++++
 3 files changed, 60 insertions(+), 7 deletions(-)
 create mode 100644 Tests/AetherEngineTests/InjectedRenditionSelectionTests.swift

diff --git a/Sources/AetherEngine/AetherEngine+Subtitles.swift b/Sources/AetherEngine/AetherEngine+Subtitles.swift
index d03640aed..4ba8b3f5d 100644
--- a/Sources/AetherEngine/AetherEngine+Subtitles.swift
+++ b/Sources/AetherEngine/AetherEngine+Subtitles.swift
@@ -2647,21 +2647,22 @@ extension AetherEngine {
         Task { @MainActor in
             self.currentAVPlayer?.appliesMediaSelectionCriteriaAutomatically = false
             guard let group = try? await item.asset.loadMediaSelectionGroup(for: .legible) else { return }
-            var match: AVMediaSelectionOption?
-            var seen: [String] = []
+            var snapshots: [RemoteHLSMediaSelection.LegibleOption] = []
             for option in group.options {
-                let playlistName = await RemoteHLSMediaSelection.playlistName(of: option)
-                seen.append(playlistName ?? option.displayName)
-                if match == nil, playlistName == name || option.displayName == name { match = option }
+                snapshots.append(RemoteHLSMediaSelection.LegibleOption(
+                    displayName: option.displayName, extendedLanguageTag: nil,
+                    isDefault: false, isForced: false, isSDH: false,
+                    playlistName: await RemoteHLSMediaSelection.playlistName(of: option)))
             }
-            guard let option = match else {
+            let seen = snapshots.map(RemoteHLSMediaSelection.injectionKey)
+            guard let index = RemoteHLSMediaSelection.injectedRenditionIndex(named: name, in: snapshots) else {
                 EngineLog.emit(
                     "[AetherEngine] #316: injected rendition \"\(name)\" is not in the item's legible "
                     + "group (\(seen.joined(separator: ", ")))",
                     category: .engine)
                 return
             }
-            item.select(option, in: group)
+            item.select(group.options[index], in: group)
             EngineLog.emit("[AetherEngine] #316: selected injected rendition \"\(name)\" for external id=\(id)",
                            category: .engine)
         }
diff --git a/Sources/AetherEngine/Native/RemoteHLSMediaSelection.swift b/Sources/AetherEngine/Native/RemoteHLSMediaSelection.swift
index 7e58a4d3e..d9e0307cd 100644
--- a/Sources/AetherEngine/Native/RemoteHLSMediaSelection.swift
+++ b/Sources/AetherEngine/Native/RemoteHLSMediaSelection.swift
@@ -62,6 +62,14 @@ enum RemoteHLSMediaSelection {
         option.playlistName ?? option.displayName
     }
 
+    /// The option that carries an injected rendition's served NAME (audit NAT-104). Matched on
+    /// `injectionKey`, the identity the dedupe and the auto-select mirror already use: a first-hit test
+    /// of `playlistName == name || displayName == name` picked the ORIGIN's option whenever its localized
+    /// display name equalled the sidecar's NAME, and the origin's renditions sit ahead of the injected ones.
+    static func injectedRenditionIndex(named name: String, in options: [LegibleOption]) -> Int? {
+        options.firstIndex { injectionKey($0) == name }
+    }
+
     /// Reroute only the typed VOD-path misroute, and only for URL sources: custom readers have no
     /// URL for AVPlayer to open, and the live raw-path misroute has its own destination
     /// (`shouldRouteLiveOntoIngest`, AE#363).
diff --git a/Tests/AetherEngineTests/InjectedRenditionSelectionTests.swift b/Tests/AetherEngineTests/InjectedRenditionSelectionTests.swift
new file mode 100644
index 000000000..a3806fe0b
--- /dev/null
+++ b/Tests/AetherEngineTests/InjectedRenditionSelectionTests.swift
@@ -0,0 +1,44 @@
+import Testing
+@testable import AetherEngine
+
+/// Audit NAT-104: `selectInjectedSubtitleRendition` took the first option whose playlist NAME or
+/// localized display name equalled the sidecar's served NAME. AVFoundation derives the display name from
+/// LANGUAGE, so the origin's own "English CC" rendition reads back as "English" and, sitting ahead of the
+/// injected ones in the served master, won over the sidecar actually asked for.
+@Suite("Injected rendition selection (NAT-104)")
+struct InjectedRenditionSelectionTests {
+
+    private func option(display: String, playlistName: String?) -> RemoteHLSMediaSelection.LegibleOption {
+        RemoteHLSMediaSelection.LegibleOption(
+            displayName: display, extendedLanguageTag: "en",
+            isDefault: false, isForced: false, isSDH: false, playlistName: playlistName)
+    }
+
+    @Test("an origin rendition whose localized display name equals the sidecar's NAME does not win")
+    func originDisplayNameDoesNotShadowTheInjectedRendition() {
+        let group = [
+            option(display: "English", playlistName: "English CC"),   // origin, NAME="English CC"
+            option(display: "English", playlistName: "English"),      // injected sidecar
+        ]
+        #expect(RemoteHLSMediaSelection.injectedRenditionIndex(named: "English", in: group) == 1)
+    }
+
+    @Test("a rendition is found by its playlist NAME when the display name differs")
+    func matchesByPlaylistName() {
+        let group = [option(display: "Chinese", playlistName: "简体中文")]
+        #expect(RemoteHLSMediaSelection.injectedRenditionIndex(named: "简体中文", in: group) == 0)
+    }
+
+    @Test("an OS that exposes no m3u8/NAME falls back to the display name")
+    func fallsBackToDisplayName() {
+        let group = [option(display: "German", playlistName: nil)]
+        #expect(RemoteHLSMediaSelection.injectedRenditionIndex(named: "German", in: group) == 0)
+    }
+
+    @Test("a name that no option carries is a miss")
+    func missIsNil() {
+        let group = [option(display: "English", playlistName: "English CC")]
+        #expect(RemoteHLSMediaSelection.injectedRenditionIndex(named: "English", in: group) == nil)
+        #expect(RemoteHLSMediaSelection.injectedRenditionIndex(named: "English", in: []) == nil)
+    }
+}

From ad8c26d87b68b6c644e34f8c34cef7de7927b5c1 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 09:02:57 +0200
Subject: [PATCH 199/359] fix(atmos): close the reader fork the confirmation
 pass only nil-tests (audit DEC-109)

startAtmosConfirmation forked the host's custom reader to test the fork for
nil and dropped it, but the IOReader contract leaves every independent reader
to the engine to close. A host whose fork opens a connection held one per load
for nothing. The probe now closes the fork it built.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../Audio/AtmosConfirmationWorker.swift       | 11 +++-
 .../AtmosConfirmationForkTests.swift          | 51 +++++++++++++++++++
 2 files changed, 61 insertions(+), 1 deletion(-)
 create mode 100644 Tests/AetherEngineTests/AtmosConfirmationForkTests.swift

diff --git a/Sources/AetherEngine/Audio/AtmosConfirmationWorker.swift b/Sources/AetherEngine/Audio/AtmosConfirmationWorker.swift
index 688ee1912..52f3cb542 100644
--- a/Sources/AetherEngine/Audio/AtmosConfirmationWorker.swift
+++ b/Sources/AetherEngine/Audio/AtmosConfirmationWorker.swift
@@ -60,7 +60,7 @@ extension AetherEngine {
         applyConfirmedAtmos()
         let candidates = Self.atmosConfirmationCandidates(in: audioTracks)
         guard !candidates.isEmpty else { return }
-        if isCustomSource, customReader?.makeIndependentReader() == nil { return }
+        if isCustomSource, !Self.canForkCustomReader(customReader) { return }
 
         let headers = loadedOptions.httpHeaders
         let formatHint = customFormatHint
@@ -74,6 +74,15 @@ extension AetherEngine {
         }
     }
 
+    /// Whether the host's reader can hand out the independent cursor each pass needs. The probe builds a
+    /// real reader, which the `IOReader` contract leaves to the engine to close (audit DEC-109); a host
+    /// whose fork opens a connection would otherwise hold one per load for nothing.
+    nonisolated static func canForkCustomReader(_ reader: IOReader?) -> Bool {
+        guard let probe = reader?.makeIndependentReader() else { return false }
+        probe.close()
+        return true
+    }
+
     /// Teardown. `markClosed()` on the side demuxer so a parked AVIO read cannot outlive the session,
     /// the same rule the native subtitle readers follow.
     func cancelAtmosConfirmation() {
diff --git a/Tests/AetherEngineTests/AtmosConfirmationForkTests.swift b/Tests/AetherEngineTests/AtmosConfirmationForkTests.swift
new file mode 100644
index 000000000..9dcdad116
--- /dev/null
+++ b/Tests/AetherEngineTests/AtmosConfirmationForkTests.swift
@@ -0,0 +1,51 @@
+import Testing
+import Foundation
+@testable import AetherEngine
+
+/// Audit DEC-109: `startAtmosConfirmation` forked the host's custom reader only to test the fork for
+/// nil and dropped it, and the `IOReader` contract says the engine owns and closes every independent
+/// reader it is handed.
+@Suite("Atmos confirmation reader probe (DEC-109)")
+struct AtmosConfirmationForkTests {
+
+    private final class Fork: IOReader, @unchecked Sendable {
+        private let lock = NSLock()
+        private var _closed = false
+        var isClosed: Bool { lock.withLock { _closed } }
+        func read(_ buffer: UnsafeMutablePointer<UInt8>?, size: Int32) -> Int32 { 0 }
+        func seek(offset: Int64, whence: Int32) -> Int64 { -1 }
+        func close() { lock.withLock { _closed = true } }
+    }
+
+    private final class Host: IOReader, @unchecked Sendable {
+        private let lock = NSLock()
+        private let forkable: Bool
+        private var _forks: [Fork] = []
+        var forks: [Fork] { lock.withLock { _forks } }
+        init(forkable: Bool) { self.forkable = forkable }
+        func read(_ buffer: UnsafeMutablePointer<UInt8>?, size: Int32) -> Int32 { 0 }
+        func seek(offset: Int64, whence: Int32) -> Int64 { -1 }
+        func close() {}
+        func makeIndependentReader() -> IOReader? {
+            guard forkable else { return nil }
+            let fork = Fork()
+            lock.withLock { _forks.append(fork) }
+            return fork
+        }
+    }
+
+    @Test("the probe closes the fork it built")
+    func probeClosesItsFork() {
+        let host = Host(forkable: true)
+        #expect(AetherEngine.canForkCustomReader(host))
+        #expect(host.forks.count == 1)
+        let allClosed = host.forks.allSatisfy { $0.isClosed }
+        #expect(allClosed, "a fork built to be nil-tested must not outlive the test")
+    }
+
+    @Test("a one-shot reader, or none at all, cannot be forked")
+    func unforkableReader() {
+        #expect(!AetherEngine.canForkCustomReader(Host(forkable: false)))
+        #expect(!AetherEngine.canForkCustomReader(nil))
+    }
+}

From a7e7588e728295be98cba1b7bf397ca0ecdba76b Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 09:02:57 +0200
Subject: [PATCH 200/359] fix(audio): the audio-only host anchors its clock at
 the first sample (audit DEC-102)

AudioPlaybackHost armed the synchronizer at the load position and ignored the
first sample's PTS. A source whose timestamps start far past it (an Ogg radio
stream's granule position, an audio-only TS that joined mid-broadcast) stamped
every buffer hours ahead of a clock at 0, the 8 s back-pressure gate parked
the loop against the gap, and the session played silence.

The host now resolves the anchor with SWClockAnchorPolicy, as the software
video host does: it anchors at the first sample when that lies past the load
anchor, publishes the position relative to that session zero, and carries seek
targets back over to the source axis before they reach the demuxer and the
clock. A resume whose first sample is where it was asked to be keeps the load
anchor. An end-to-end test runs a generated MPEG-TS that starts at 3600 s.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../Audio/AudioPlaybackHost.swift             |  71 +++++++-
 .../AudioOnlyClockAnchorTests.swift           | 169 ++++++++++++++++++
 2 files changed, 233 insertions(+), 7 deletions(-)
 create mode 100644 Tests/AetherEngineTests/AudioOnlyClockAnchorTests.swift

diff --git a/Sources/AetherEngine/Audio/AudioPlaybackHost.swift b/Sources/AetherEngine/Audio/AudioPlaybackHost.swift
index 2402f5d1f..9f593b773 100644
--- a/Sources/AetherEngine/Audio/AudioPlaybackHost.swift
+++ b/Sources/AetherEngine/Audio/AudioPlaybackHost.swift
@@ -64,10 +64,32 @@ final class AudioPlaybackHost {
 
     private var lastRate: Float = 1.0
 
-    /// Source-position seconds the host opened at; the demux loop aligns the master clock to the first
-    /// decoded sample's PTS. `.zero` on cold start, resume offset on a start-position load.
+    /// Source-position seconds the host opened at; the demux loop resolves the master clock's anchor from it
+    /// and the first decoded sample's PTS (`clockAnchor`). `.zero` on cold start, resume offset on a
+    /// start-position load.
     private var initialClockTime: CMTime = .zero
 
+    /// Where the clock is anchored for a first decoded sample at `firstPTS`, and the session zero the host
+    /// then subtracts from the raw clock. The anchor stays `initialClockTime` for a source that starts where
+    /// it was asked to (a resume lands within `SWClockAnchorPolicy.toleranceSeconds`), and moves to the
+    /// sample for one whose timestamps start far past it: a clock at 0 under buffers stamped 3600 s never
+    /// reaches them, and the back-pressure gate parks the loop against the gap (audit DEC-102).
+    nonisolated static func clockAnchor(initialClockTime: CMTime, firstPTS: CMTime)
+        -> (anchor: CMTime, sessionZeroSeconds: Double) {
+        let resolution = SWClockAnchorPolicy.resolve(
+            initialSeconds: initialClockTime.seconds,
+            firstSampleSeconds: firstPTS.isValid ? firstPTS.seconds : Double.nan)
+        let anchor = resolution.anchorSeconds == initialClockTime.seconds
+            ? initialClockTime
+            : CMTime(seconds: resolution.anchorSeconds, preferredTimescale: 90000)
+        return (anchor, resolution.sessionZeroSeconds)
+    }
+
+    /// The position published for a raw synchronizer time.
+    nonisolated static func publishedTime(raw: Double, sessionZeroSeconds: Double) -> Double {
+        sessionZeroSeconds > 0 ? max(0, raw - sessionZeroSeconds) : raw
+    }
+
     /// Latched once the first `play()` has spun up the demux loop.
     private var demuxLoopStarted: Bool = false
 
@@ -82,6 +104,16 @@ final class AudioPlaybackHost {
         set { flagsLock.lock(); _clockArmed = newValue; flagsLock.unlock() }
     }
 
+    /// Audit DEC-102: the offset between the source's own timestamps and the published position, set once by
+    /// the demux loop when it anchors the clock on a first sample that lies past the load anchor (an Ogg
+    /// radio stream's granule position, an audio-only TS that joined mid-broadcast). 0 for a source that
+    /// starts where it was asked to. Same meaning and same policy as `SoftwarePlaybackHost.clockSessionZero`.
+    nonisolated(unsafe) private var _sessionZeroSeconds: Double = 0
+    nonisolated private var sessionZeroSeconds: Double {
+        get { flagsLock.lock(); defer { flagsLock.unlock() }; return _sessionZeroSeconds }
+        set { flagsLock.lock(); _sessionZeroSeconds = newValue; flagsLock.unlock() }
+    }
+
     /// Bumped by every seek(); demux loop resets its enqueue high-water mark on change so the back-pressure
     /// gate can't park against a pre-seek mark after a backward seek.
     nonisolated(unsafe) private var _seekGeneration: UInt64 = 0
@@ -217,6 +249,9 @@ final class AudioPlaybackHost {
     }
 
     var clockRateForTesting: Float? { audioOutput?.rate }
+    var clockSecondsForTesting: Double? { audioOutput?.currentTimeSeconds }
+    var isClockArmedForTesting: Bool { clockArmed }
+    var sessionZeroForTesting: Double { sessionZeroSeconds }
     var outputVolumeForTesting: Float? { audioOutput?.volume }
     #endif
 
@@ -267,10 +302,14 @@ final class AudioPlaybackHost {
         audioDecoder?.flush()
         audioOutput?.flush()
 
+        // `seconds` is the published axis; the demuxer and the synchronizer clock speak the source's own
+        // timestamps, so the target is carried over before it reaches either (audit DEC-102).
+        let sourceSeconds = SWClockAnchorPolicy.sourceSeconds(
+            forSession: seconds, sessionZeroSeconds: sessionZeroSeconds)
         currentTime = seconds
         seekInFlight = true
         let outcome = await dem.seekBounded(
-            to: seconds, timeout: Self.seekBudgetSeconds, on: seekQueue,
+            to: sourceSeconds, timeout: Self.seekBudgetSeconds, on: seekQueue,
             isSuperseded: { [weak self] in self?.seekGeneration != generation })
         guard seekGeneration == generation, !stopRequested else { return .superseded }
         seekInFlight = false
@@ -283,7 +322,7 @@ final class AudioPlaybackHost {
         }
         currentTime = seconds
 
-        let targetTime = CMTime(seconds: seconds, preferredTimescale: 90000)
+        let targetTime = CMTime(seconds: sourceSeconds, preferredTimescale: 90000)
         guard demuxLoopStarted else {
             // Cold seek (no play() yet): stash target so the loop's first decoded packet anchors there, not at .zero.
             initialClockTime = targetTime
@@ -342,6 +381,7 @@ final class AudioPlaybackHost {
         let getClockArmed: @Sendable () -> Bool = { [weak self] in self?.clockArmed ?? true }
         let setClockArmed: @Sendable () -> Void = { [weak self] in self?.clockArmed = true }
         let getSeekGeneration: @Sendable () -> UInt64 = { [weak self] in self?.seekGeneration ?? 0 }
+        let onClockAnchored: @Sendable (Double) -> Void = { [weak self] zero in self?.sessionZeroSeconds = zero }
         let onError: @Sendable (String) -> Void = { [weak self] msg in
             Task { @MainActor [weak self] in
                 self?.failure = PlaybackErrorInfo(kind: .audioSessionFailed, message: msg)
@@ -367,6 +407,7 @@ final class AudioPlaybackHost {
                 stopRequested: getStopRequested,
                 clockArmed: getClockArmed,
                 armClock: setClockArmed,
+                onClockAnchored: onClockAnchored,
                 seekGeneration: getSeekGeneration,
                 onError: onError,
                 onEnd: onEnd
@@ -388,6 +429,7 @@ final class AudioPlaybackHost {
         stopRequested: @Sendable () -> Bool,
         clockArmed: @Sendable () -> Bool,
         armClock: @Sendable () -> Void,
+        onClockAnchored: @Sendable (Double) -> Void,
         seekGeneration: @Sendable () -> UInt64,
         onError: @Sendable (String) -> Void,
         onEnd: @Sendable () -> Void
@@ -402,7 +444,8 @@ final class AudioPlaybackHost {
         // playback end and bounds decoded-PCM memory in the renderer.
         let maxBufferAhead: Double = 8.0
         // Source-time seconds of the last sample handed to the renderer. lastEnqueuedEnd and currentTimeSeconds
-        // share the source-PTS timeline (clock anchored to initialClockTime), so their difference is seconds queued ahead.
+        // share the source-PTS timeline (the clock is anchored on the source axis, see `clockAnchor`), so their
+        // difference is seconds queued ahead.
         var lastEnqueuedEnd: Double = 0
         var seenSeekGeneration = seekGeneration()
 
@@ -526,7 +569,21 @@ final class AudioPlaybackHost {
                     if end.isFinite, end > lastEnqueuedEnd { lastEnqueuedEnd = end }
                 }
                 if !clockArmed(), !buffers.isEmpty {
-                    aOut.seekClock(to: initialClockTime, rate: initialRate)
+                    let resolved = clockAnchor(
+                        initialClockTime: initialClockTime,
+                        firstPTS: CMSampleBufferGetPresentationTimeStamp(buffers[0]))
+                    if resolved.sessionZeroSeconds > 0 {
+                        EngineLog.emit(
+                            "[AudioHost] clock anchored at the first sample: "
+                            + "anchor=\(String(format: "%.3f", resolved.anchor.seconds))s "
+                            + "(load anchor \(String(format: "%.3f", initialClockTime.seconds))s, "
+                            + "sessionZero=\(String(format: "%.3f", resolved.sessionZeroSeconds))s)",
+                            category: .swPlayback
+                        )
+                        // Before the clock moves, so no tick can publish the raw position in between.
+                        onClockAnchored(resolved.sessionZeroSeconds)
+                    }
+                    aOut.seekClock(to: resolved.anchor, rate: initialRate)
                     armClock()
                 }
             }
@@ -556,7 +613,7 @@ final class AudioPlaybackHost {
                 guard !self.seekInFlight else { return }
                 let t = aOut.currentTimeSeconds
                 if t.isFinite, t >= 0 {
-                    self.currentTime = t
+                    self.currentTime = Self.publishedTime(raw: t, sessionZeroSeconds: self.sessionZeroSeconds)
                 }
             }
     }
diff --git a/Tests/AetherEngineTests/AudioOnlyClockAnchorTests.swift b/Tests/AetherEngineTests/AudioOnlyClockAnchorTests.swift
new file mode 100644
index 000000000..01b3c783b
--- /dev/null
+++ b/Tests/AetherEngineTests/AudioOnlyClockAnchorTests.swift
@@ -0,0 +1,169 @@
+import Testing
+import Foundation
+import CoreMedia
+@testable import AetherEngine
+
+/// Audit DEC-102: the audio-only FFmpeg host anchored its clock at the load position and ignored the
+/// first sample's timestamp. A source whose timestamps start far past that (an Ogg radio stream's granule
+/// position, an audio-only TS that joined mid-broadcast) then stamped every buffer hours ahead of a clock
+/// that started at 0, the back-pressure gate parked the loop against the gap, and the session played
+/// silence. The software video host resolved the same question with `SWClockAnchorPolicy`; this host now
+/// shares it.
+@Suite("Audio-only clock anchor (DEC-102)", .serialized)
+struct AudioOnlyClockAnchorTests {
+
+    // MARK: - The decision
+
+    @Test("a first sample an hour past the load anchor moves the anchor and records the session zero")
+    func farFirstSampleAnchorsAtTheSample() {
+        let first = CMTime(seconds: 3600, preferredTimescale: 90000)
+        let resolved = AudioPlaybackHost.clockAnchor(initialClockTime: .zero, firstPTS: first)
+        #expect(resolved.anchor.seconds == 3600)
+        #expect(resolved.sessionZeroSeconds == 3600)
+        #expect(AudioPlaybackHost.publishedTime(raw: 3600, sessionZeroSeconds: resolved.sessionZeroSeconds) == 0)
+        #expect(AudioPlaybackHost.publishedTime(raw: 3612.5, sessionZeroSeconds: resolved.sessionZeroSeconds) == 12.5)
+    }
+
+    @Test("a resume whose first sample is where it was asked to be keeps the load anchor verbatim")
+    func alignedResumeKeepsTheAnchor() {
+        let initial = CMTime(seconds: 1000, preferredTimescale: 90000)
+        let resolved = AudioPlaybackHost.clockAnchor(
+            initialClockTime: initial, firstPTS: CMTime(seconds: 1000.4, preferredTimescale: 90000))
+        #expect(resolved.anchor == initial)
+        #expect(resolved.sessionZeroSeconds == 0)
+        #expect(AudioPlaybackHost.publishedTime(raw: 1003, sessionZeroSeconds: 0) == 1003)
+    }
+
+    @Test("an invalid first timestamp keeps the load anchor")
+    func invalidFirstSampleKeepsTheAnchor() {
+        let resolved = AudioPlaybackHost.clockAnchor(initialClockTime: .zero, firstPTS: .invalid)
+        #expect(resolved.anchor == .zero)
+        #expect(resolved.sessionZeroSeconds == 0)
+    }
+
+    @Test("a seek target on the published axis round-trips through the source axis")
+    func seekTargetRoundTrips() {
+        let zero = 3600.0
+        let source = SWClockAnchorPolicy.sourceSeconds(forSession: 42, sessionZeroSeconds: zero)
+        #expect(source == 3642)
+        #expect(AudioPlaybackHost.publishedTime(raw: source, sessionZeroSeconds: zero) == 42)
+    }
+
+    // MARK: - End to end, on a real demuxer
+
+    @MainActor
+    @Test("an audio-only TS that starts an hour in is anchored at its first sample, and seeks stay on its axis")
+    func hourOffsetTransportStream() async throws {
+        let stream = Self.makeMP2TransportStream(startPTSSeconds: 3600, frames: 200)
+        let demuxer = Demuxer()
+        try demuxer.open(reader: DataIOReader(data: stream), formatHint: "mpegts")
+        let host = AudioPlaybackHost()
+        try await host.load(demuxer: demuxer, startPosition: nil, audioSourceStreamIndex: nil)
+        defer { host.stop() }
+
+        host.play()
+        try await waitFor { host.isClockArmedForTesting }
+
+        #expect(abs(host.sessionZeroForTesting - 3600) < 1, "zero \(host.sessionZeroForTesting)")
+        let clock = try #require(host.clockSecondsForTesting)
+        #expect(clock >= 3599 && clock < 3700, "the clock has to sit where the samples are, not at 0: \(clock)")
+
+        await host.seek(to: 1.0)
+        let seeked = try #require(host.clockSecondsForTesting)
+        #expect(abs(seeked - 3601) < 2, "a seek to 1.0 s of the published axis is 3601 s of the source: \(seeked)")
+        #expect(host.currentTime == 1.0)
+    }
+
+    // MARK: - Fixture: MPEG-1 Layer II in MPEG-TS
+
+    /// `frames` silent 48 kHz mono Layer II frames (24 ms each, zero allocation bits decode to silence),
+    /// one PES packet each, the first stamped at `startPTSSeconds`. No PCR: the demuxer takes audio
+    /// timestamps from the PES headers.
+    private static func makeMP2TransportStream(startPTSSeconds: Double, frames: Int) -> Data {
+        let pmtPID: UInt16 = 0x1000, audioPID: UInt16 = 0x0100
+        var counters: [UInt16: UInt8] = [:]
+        var out = Data()
+
+        var pat = Data([0x00, 0x01, 0xC1, 0x00, 0x00, 0x00, 0x01])
+        pat.append(contentsOf: [UInt8(0xE0 | (pmtPID >> 8)), UInt8(pmtPID & 0xFF)])
+        out.append(psi(pid: 0, section: section(tableID: 0x00, body: pat), counters: &counters))
+
+        var pmt = Data([0x00, 0x01, 0xC1, 0x00, 0x00])
+        pmt.append(contentsOf: [UInt8(0xE0 | (audioPID >> 8)), UInt8(audioPID & 0xFF), 0xF0, 0x00])
+        pmt.append(contentsOf: [0x03, UInt8(0xE0 | (audioPID >> 8)), UInt8(audioPID & 0xFF), 0xF0, 0x00])
+        out.append(psi(pid: pmtPID, section: section(tableID: 0x02, body: pmt), counters: &counters))
+
+        var frame = Data(count: 192)
+        frame.replaceSubrange(0..<4, with: [0xFF, 0xFD, 0x44, 0xC0])
+        let startTicks = Int64(startPTSSeconds * 90_000)
+        for i in 0..<frames {
+            let pts = startTicks + Int64(i) * 2160   // 24 ms
+            out.append(pes(pid: audioPID, payload: frame, pts: pts, counters: &counters))
+        }
+        return out
+    }
+
+    private static func section(tableID: UInt8, body: Data) -> Data {
+        let length = body.count + 4
+        var s = Data([tableID, UInt8(0xB0 | ((length >> 8) & 0x0F)), UInt8(length & 0xFF)])
+        s.append(body)
+        var crc: UInt32 = 0xFFFF_FFFF
+        for byte in s {
+            crc ^= UInt32(byte) << 24
+            for _ in 0..<8 { crc = (crc & 0x8000_0000) != 0 ? (crc << 1) ^ 0x04C1_1DB7 : crc << 1 }
+        }
+        for shift in stride(from: 24, through: 0, by: -8) { s.append(UInt8((crc >> UInt32(shift)) & 0xFF)) }
+        return s
+    }
+
+    private static func psi(pid: UInt16, section: Data, counters: inout [UInt16: UInt8]) -> Data {
+        var payload = Data([0x00])
+        payload.append(section)
+        payload.append(contentsOf: [UInt8](repeating: 0xFF, count: 184 - payload.count))
+        return packet(pid: pid, pusi: true, payload: payload, counters: &counters)
+    }
+
+    private static func pes(pid: UInt16, payload: Data, pts: Int64, counters: inout [UInt16: UInt8]) -> Data {
+        var packetData = Data([0x00, 0x00, 0x01, 0xC0])
+        let length = 3 + 5 + payload.count
+        packetData.append(contentsOf: [UInt8(length >> 8), UInt8(length & 0xFF), 0x80, 0x80, 0x05])
+        packetData.append(contentsOf: [
+            UInt8(0x21 | ((pts >> 29) & 0x0E)),
+            UInt8((pts >> 22) & 0xFF),
+            UInt8(0x01 | ((pts >> 14) & 0xFE)),
+            UInt8((pts >> 7) & 0xFF),
+            UInt8(0x01 | ((pts << 1) & 0xFE)),
+        ])
+        packetData.append(payload)
+        var out = Data()
+        var offset = 0
+        var first = true
+        while offset < packetData.count {
+            let take = min(184, packetData.count - offset)
+            out.append(packet(pid: pid, pusi: first, payload: packetData.subdata(in: offset..<(offset + take)),
+                              counters: &counters))
+            offset += take
+            first = false
+        }
+        return out
+    }
+
+    private static func packet(pid: UInt16, pusi: Bool, payload: Data, counters: inout [UInt16: UInt8]) -> Data {
+        let counter = counters[pid, default: 0]
+        var p = Data([0x47, UInt8((pusi ? 0x40 : 0x00) | Int(pid >> 8)), UInt8(pid & 0xFF)])
+        let stuffing = 184 - payload.count
+        if stuffing == 0 {
+            p.append(0x10 | counter)
+        } else {
+            p.append(0x30 | counter)
+            p.append(UInt8(stuffing - 1))
+            if stuffing >= 2 {
+                p.append(0x00)
+                p.append(contentsOf: [UInt8](repeating: 0xFF, count: stuffing - 2))
+            }
+        }
+        p.append(payload)
+        counters[pid] = (counter &+ 1) & 0x0F
+        return p
+    }
+}

From ce3f7f35b553a1dfc0234717ddfb77222215a851 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 09:02:57 +0200
Subject: [PATCH 201/359] fix(decode): the software decoder's output format
 follows the decoded frame (audit DEC-107)

The pool format came from the container declaration only. color_range was
never read, so a full-range AV1 / VP9 / HEVC picture was labelled video range
and shown crushed, and bits_per_raw_sample is 0 for libdav1d and the AV1 / VP9
parsers, so a 10-bit SDR stream was dithered down to 8 bit.

convertFrameToPixelBuffer now reads the frame: full range is a label on the
NV12 / P010 pool (the legacy sws_scale copies a plain 4:2:0 frame across
without a range conversion, which keeps 4K on its unscaled path, and a yuvj
source stays video range because swscale converts it itself), and the depth
comes from the pixel format descriptor. The pool is keyed on format as well as
size, the hardware-deinterlace transfer keeps asking for the stream default,
and a format change is logged once.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../Decoder/SoftwareVideoDecoder.swift        |  78 ++++++++--
 .../SoftwareDecoderOutputFormatTests.swift    | 144 ++++++++++++++++++
 2 files changed, 212 insertions(+), 10 deletions(-)
 create mode 100644 Tests/AetherEngineTests/SoftwareDecoderOutputFormatTests.swift

diff --git a/Sources/AetherEngine/Decoder/SoftwareVideoDecoder.swift b/Sources/AetherEngine/Decoder/SoftwareVideoDecoder.swift
index ea63e0054..432660514 100644
--- a/Sources/AetherEngine/Decoder/SoftwareVideoDecoder.swift
+++ b/Sources/AetherEngine/Decoder/SoftwareVideoDecoder.swift
@@ -55,6 +55,10 @@ final class SoftwareVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
     private var pixelBufferPool: CVPixelBufferPool?
     private var poolWidth = 0
     private var poolHeight = 0
+    private var poolFormat = OutputFormat(tenBit: false, fullRange: false)
+    /// The format the last converted frame asked for, so a change is logged once (release-visible) rather
+    /// than per frame. Guarded by `lock`, like the pool.
+    private var loggedOutputFormat: OutputFormat?
 
     /// Skip pre-seek frames; decoded for reference but not converted.
     /// Guarded by `skipLock` not `lock`: emit() runs with `lock` held, so a same-lock accessor would deadlock.
@@ -96,6 +100,48 @@ final class SoftwareVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
     /// still extractor is the only caller, everything on a playback path wants the parallel default.
     var decodesSingleThreaded = false
 
+    /// The pixel buffer format this decoder hands the display layer, read off the decoded frame (audit
+    /// DEC-107). The container's declaration alone missed two cases: `color_range` was never read, so a
+    /// full-range AV1 / VP9 / HEVC picture was labelled video range and shown crushed, and
+    /// `bits_per_raw_sample` is 0 for libdav1d and the AV1 / VP9 parsers, so a 10-bit SDR stream was
+    /// dithered down to 8 bit.
+    struct OutputFormat: Equatable {
+        var tenBit: Bool
+        var fullRange: Bool
+
+        var pixelFormatType: OSType {
+            switch (tenBit, fullRange) {
+            case (false, false): return kCVPixelFormatType_420YpCbCr8BiPlanarVideoRange
+            case (false, true): return kCVPixelFormatType_420YpCbCr8BiPlanarFullRange
+            case (true, false): return kCVPixelFormatType_420YpCbCr10BiPlanarVideoRange
+            case (true, true): return kCVPixelFormatType_420YpCbCr10BiPlanarFullRange
+            }
+        }
+
+        var swscaleFormat: AVPixelFormat { tenBit ? AV_PIX_FMT_P010LE : AV_PIX_FMT_NV12 }
+    }
+
+    /// `streamIs10Bit` is the open-time verdict (declared depth or an HDR transfer) and only ever widens
+    /// the answer. The range is a LABEL: the legacy `sws_scale` reads a source's range from the pixel
+    /// format alone (the yuvj family), so a full-range frame in a plain 4:2:0 format is copied across
+    /// untouched and only has to be tagged as what it is. Asking swscale to convert would take 4K off its
+    /// unscaled NV12 / P010 path, and a yuvj source IS converted to video range by swscale itself, so it
+    /// stays video range here.
+    nonisolated static func outputFormat(pixelFormat: Int32, colorRange: AVColorRange,
+                                         streamIs10Bit: Bool) -> OutputFormat {
+        let format = AVPixelFormat(rawValue: pixelFormat)
+        let depth = av_pix_fmt_desc_get(format)?.pointee.comp.0.depth ?? 8
+        let convertedBySwscale: Bool
+        switch format {
+        case AV_PIX_FMT_YUVJ420P, AV_PIX_FMT_YUVJ422P, AV_PIX_FMT_YUVJ444P, AV_PIX_FMT_YUVJ440P:
+            convertedBySwscale = true
+        default:
+            convertedBySwscale = false
+        }
+        return OutputFormat(tenBit: streamIs10Bit || depth > 8,
+                            fullRange: colorRange == AVCOL_RANGE_JPEG && !convertedBySwscale)
+    }
+
     /// AE#499: what the container declared about colour, captured at `open` before a single frame
     /// exists. A decoded frame carries the VUI alone, and a remux whose VUI is empty would otherwise
     /// reach `attachColorSpace` as an untagged picture, so an HDR10 file decoded in software lost its
@@ -501,6 +547,7 @@ final class SoftwareVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
         pixelBufferPool = nil
         poolWidth = 0
         poolHeight = 0
+        loggedOutputFormat = nil
         if let session = transferSession {
             VTPixelTransferSessionInvalidate(session)
             transferSession = nil
@@ -519,16 +566,12 @@ final class SoftwareVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
     /// Create (or reuse) the decoder-owned CVPixelBufferPool for the given geometry. These
     /// attributes (IOSurface + Metal compatible, NV12/P010) are the ones the display path has
     /// always accepted; both the sws path and the hw-deinterlace transfer draw from here.
-    private func ensurePixelBufferPool(width: Int, height: Int) -> CVPixelBufferPool? {
-        let cvPixelFormat: OSType = use10Bit
-            ? kCVPixelFormatType_420YpCbCr10BiPlanarVideoRange
-            : kCVPixelFormatType_420YpCbCr8BiPlanarVideoRange
-
-        if pixelBufferPool == nil || poolWidth != width || poolHeight != height {
+    private func ensurePixelBufferPool(width: Int, height: Int, format: OutputFormat) -> CVPixelBufferPool? {
+        if pixelBufferPool == nil || poolWidth != width || poolHeight != height || poolFormat != format {
             pixelBufferPool = nil
             let poolAttrs: NSDictionary = [kCVPixelBufferPoolMinimumBufferCountKey: 6]
             let pbAttrs: NSDictionary = [
-                kCVPixelBufferPixelFormatTypeKey: cvPixelFormat,
+                kCVPixelBufferPixelFormatTypeKey: format.pixelFormatType,
                 kCVPixelBufferWidthKey: width,
                 kCVPixelBufferHeightKey: height,
                 kCVPixelBufferMetalCompatibilityKey: true,
@@ -537,6 +580,7 @@ final class SoftwareVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
             CVPixelBufferPoolCreate(kCFAllocatorDefault, poolAttrs, pbAttrs, &pixelBufferPool)
             poolWidth = width
             poolHeight = height
+            poolFormat = format
         }
         return pixelBufferPool
     }
@@ -551,10 +595,12 @@ final class SoftwareVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
             guard status == noErr, let s = session else { return nil }
             transferSession = s
         }
+        // The transfer converts range and depth itself, so it asks for the stream's own default.
         guard let session = transferSession,
               let pool = ensurePixelBufferPool(
                   width: CVPixelBufferGetWidth(src),
-                  height: CVPixelBufferGetHeight(src)
+                  height: CVPixelBufferGetHeight(src),
+                  format: OutputFormat(tenBit: use10Bit, fullRange: false)
               ) else { return nil }
         var dst: CVPixelBuffer?
         guard CVPixelBufferPoolCreatePixelBuffer(kCFAllocatorDefault, pool, &dst) == kCVReturnSuccess,
@@ -587,7 +633,19 @@ final class SoftwareVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
 
         let srcFmt = AVPixelFormat(rawValue: frame.pointee.format)
 
-        let dstFmt = use10Bit ? AV_PIX_FMT_P010LE : AV_PIX_FMT_NV12
+        let outputFormat = Self.outputFormat(
+            pixelFormat: frame.pointee.format, colorRange: frame.pointee.color_range, streamIs10Bit: use10Bit)
+        let dstFmt = outputFormat.swscaleFormat
+        if outputFormat != loggedOutputFormat {
+            loggedOutputFormat = outputFormat
+            EngineLog.emit(
+                "[SWDecoder] output \(outputFormat.tenBit ? "10-bit P010" : "8-bit NV12"), "
+                + "\(outputFormat.fullRange ? "full" : "video") range "
+                + "(frame \(av_get_pix_fmt_name(srcFmt).map { String(cString: $0) } ?? "?"), "
+                + "color_range=\(frame.pointee.color_range.rawValue))",
+                category: .swPlayback
+            )
+        }
 
         swsContext = sws_getCachedContext(
             swsContext,
@@ -600,7 +658,7 @@ final class SoftwareVideoDecoder: VideoDecodingPipeline, @unchecked Sendable {
         guard swsContext != nil else { return nil }
 
         var pixelBuffer: CVPixelBuffer?
-        guard let pool = ensurePixelBufferPool(width: width, height: height) else { return nil }
+        guard let pool = ensurePixelBufferPool(width: width, height: height, format: outputFormat) else { return nil }
         let status = CVPixelBufferPoolCreatePixelBuffer(kCFAllocatorDefault, pool, &pixelBuffer)
         guard status == kCVReturnSuccess, let pb = pixelBuffer else { return nil }
 
diff --git a/Tests/AetherEngineTests/SoftwareDecoderOutputFormatTests.swift b/Tests/AetherEngineTests/SoftwareDecoderOutputFormatTests.swift
new file mode 100644
index 000000000..abcc31843
--- /dev/null
+++ b/Tests/AetherEngineTests/SoftwareDecoderOutputFormatTests.swift
@@ -0,0 +1,144 @@
+import Foundation
+import CoreVideo
+import CoreMedia
+import Testing
+import AetherLibavcodec
+import AetherLibavutil
+@testable import AetherEngine
+
+/// Audit DEC-107: `SoftwareVideoDecoder` hard-wired its output to 8-bit or 10-bit VIDEO range from the
+/// container declaration. `color_range` was never read, so a full-range AV1 / VP9 / HEVC picture was
+/// labelled video range and shown crushed, and `bits_per_raw_sample` is 0 for libdav1d and the AV1 / VP9
+/// parsers, so a 10-bit SDR stream was dithered down to 8 bit. The pool format now follows the frame.
+@Suite("Software decoder output format follows the frame (DEC-107)")
+struct SoftwareDecoderOutputFormatTests {
+
+    // MARK: - The decision
+
+    @Test("full range is carried as a label on 8-bit and on 10-bit output")
+    func fullRangeIsALabel() {
+        let eight = SoftwareVideoDecoder.outputFormat(
+            pixelFormat: AV_PIX_FMT_YUV420P.rawValue, colorRange: AVCOL_RANGE_JPEG, streamIs10Bit: false)
+        #expect(eight == .init(tenBit: false, fullRange: true))
+        #expect(eight.pixelFormatType == kCVPixelFormatType_420YpCbCr8BiPlanarFullRange)
+
+        let ten = SoftwareVideoDecoder.outputFormat(
+            pixelFormat: AV_PIX_FMT_YUV420P10LE.rawValue, colorRange: AVCOL_RANGE_JPEG, streamIs10Bit: false)
+        #expect(ten == .init(tenBit: true, fullRange: true))
+        #expect(ten.pixelFormatType == kCVPixelFormatType_420YpCbCr10BiPlanarFullRange)
+    }
+
+    @Test("limited and unspecified range stay video range")
+    func limitedStaysVideoRange() {
+        for range in [AVCOL_RANGE_MPEG, AVCOL_RANGE_UNSPECIFIED] {
+            let format = SoftwareVideoDecoder.outputFormat(
+                pixelFormat: AV_PIX_FMT_YUV420P.rawValue, colorRange: range, streamIs10Bit: false)
+            #expect(format == .init(tenBit: false, fullRange: false))
+            #expect(format.pixelFormatType == kCVPixelFormatType_420YpCbCr8BiPlanarVideoRange)
+        }
+    }
+
+    @Test("a 10-bit frame is 10-bit output even when the stream declared no depth")
+    func frameDepthWidensTheDeclaration() {
+        let format = SoftwareVideoDecoder.outputFormat(
+            pixelFormat: AV_PIX_FMT_YUV420P10LE.rawValue, colorRange: AVCOL_RANGE_MPEG, streamIs10Bit: false)
+        #expect(format == .init(tenBit: true, fullRange: false))
+        #expect(format.swscaleFormat == AV_PIX_FMT_P010LE)
+    }
+
+    @Test("the stream's own 10-bit verdict is never narrowed by an 8-bit frame")
+    func declarationIsNeverNarrowed() {
+        let format = SoftwareVideoDecoder.outputFormat(
+            pixelFormat: AV_PIX_FMT_YUV420P.rawValue, colorRange: AVCOL_RANGE_MPEG, streamIs10Bit: true)
+        #expect(format.tenBit)
+    }
+
+    @Test("a yuvj source stays video range, because swscale converts it itself")
+    func yuvjIsConvertedBySwscale() {
+        let format = SoftwareVideoDecoder.outputFormat(
+            pixelFormat: AV_PIX_FMT_YUVJ420P.rawValue, colorRange: AVCOL_RANGE_JPEG, streamIs10Bit: false)
+        #expect(format == .init(tenBit: false, fullRange: false))
+    }
+
+    // MARK: - Real decodes
+
+    private func firstPixelBuffer(base64: String, formatHint: String?) throws -> CVPixelBuffer {
+        let data = try #require(Data(base64Encoded: base64, options: .ignoreUnknownCharacters))
+        let demuxer = Demuxer()
+        try demuxer.open(reader: DataIOReader(data: data), formatHint: formatHint)
+        defer { demuxer.close() }
+        let videoIndex = demuxer.videoStreamIndex
+        let stream = try #require(demuxer.stream(at: videoIndex))
+
+        let box = FrameBox()
+        let decoder = SoftwareVideoDecoder()
+        decoder.decodesSingleThreaded = true
+        try decoder.open(stream: stream) { buffer, _, _ in box.keepFirst(buffer) }
+        defer { decoder.close() }
+
+        while let pkt = try? demuxer.readPacket() {
+            if pkt.pointee.stream_index == videoIndex { decoder.decode(packet: pkt) }
+            var p: UnsafeMutablePointer<AVPacket>? = pkt
+            trackedPacketFree(&p)
+        }
+        return try #require(box.first, "the fixture must decode to at least one frame")
+    }
+
+    private final class FrameBox: @unchecked Sendable {
+        private let lock = NSLock()
+        private var buffer: CVPixelBuffer?
+        func keepFirst(_ candidate: CVPixelBuffer) { lock.withLock { if buffer == nil { buffer = candidate } } }
+        var first: CVPixelBuffer? { lock.withLock { buffer } }
+    }
+
+    @Test("a full-range VP9 picture reaches the layer as full range, with its white still at 255")
+    func fullRangeVP9() throws {
+        let buffer = try firstPixelBuffer(base64: Self.vp9FullRangeBase64, formatHint: nil)
+        #expect(CVPixelBufferGetPixelFormatType(buffer) == kCVPixelFormatType_420YpCbCr8BiPlanarFullRange)
+
+        CVPixelBufferLockBaseAddress(buffer, .readOnly)
+        defer { CVPixelBufferUnlockBaseAddress(buffer, .readOnly) }
+        let luma = try #require(CVPixelBufferGetBaseAddressOfPlane(buffer, 0)).assumingMemoryBound(to: UInt8.self)
+        #expect(luma[0] == 255, "no range conversion: the decoder's bytes are copied across and only labelled")
+    }
+
+    @Test("a 10-bit SDR AV1 picture stays 10-bit instead of being dithered to 8")
+    func tenBitSDRAV1() throws {
+        let buffer = try firstPixelBuffer(base64: Self.av1TenBitBase64, formatHint: "mp4")
+        #expect(CVPixelBufferGetPixelFormatType(buffer) == kCVPixelFormatType_420YpCbCr10BiPlanarVideoRange)
+    }
+
+    /// 64x64 white, 3 frames, `-color_range pc`. Regenerate:
+    ///   ffmpeg -f lavfi -i "color=c=white:s=64x64:r=10:d=0.3" -vf "scale=out_range=pc:out_color_matrix=bt709,format=yuv420p" \
+    ///     -c:v libvpx-vp9 -color_range pc -b:v 100k -deadline realtime -cpu-used 8 -g 10 vp9fr.webm
+    static let vp9FullRangeBase64 = """
+        GkXfo59ChoEBQveBAULygQRC84EIQoKEd2VibUKHgQJChYECGFOAZwEAAAAAAAJjEU2bdLpNu4tTq4QVSalmU6yBoU27i1OrhBZU
+        rmtTrIHYTbuMU6uEElTDZ1OsggEpTbuMU6uEHFO7a1OsggJN7AEAAAAAAABZAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
+        AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAVSalmsirXsYMPQkBNgI1M
+        YXZmNjIuMTIuMTAxV0GNTGF2ZjYyLjEyLjEwMUSJiEBywAAAAAAAFlSua8yuAQAAAAAAAEPXgQFzxYjMgzwgXtS2wJyBACK1nIN1
+        bmSIgQCGhVZfVlA5g4EBI+ODhAX14QDglLCBQLqBQJqBAlWwiFWxgQFVuYECElTDZ0CAc3OgY8CAZ8iaRaOHRU5DT0RFUkSHjUxh
+        dmY2Mi4xMi4xMDFzc9pjwItjxYjMgzwgXtS2wGfIpUWjh0VOQ09ERVJEh5hMYXZjNjIuMjguMTAxIGxpYnZweC12cDlnyKFFo4hE
+        VVJBVElPTkSHkzAwOjAwOjAwLjMwMDAwMDAwMAAfQ7Z1QJjngQCj6YEAAICCSYNCUAPwA/YGOCQcGEIAACBAAGxb///ZMyRz+Oqo
+        thxUFRuF7BRUkRNywleB6KhH4xFBDtsK7OkcSQT//+C9lZfb5yBGkxAXMq8VCzCvy+wStgESyCieiKCHbYV2dI4kgNw6QKOTgQBk
+        AIYAQJKcKElAAANwAABUcKOTgQDIAIYAQJKcLErAAANwAABUcBxTu2uRu4+zgQC3iveBAfGCAa/wgQM=
+        """
+
+    /// 64x64 gray, 3 frames, 10-bit 4:2:0, video range, no `bits_per_raw_sample` anywhere. Regenerate:
+    ///   ffmpeg -f lavfi -i "color=c=0x808080:s=64x64:r=10:d=0.3" -vf format=yuv420p10le -c:v libsvtav1 \
+    ///     -preset 12 -g 10 -pix_fmt yuv420p10le av110.mp4
+    static let av1TenBitBase64 = """
+        AAAAIGZ0eXBpc29tAAACAGlzb21hdjAxaXNvMm1wNDEAAAAIZnJlZQAAAEttZGF0CgoAAAACr/+JXygIMgwQAK8CCCBBAQAAAv4y
+        ESgCACSSSRGMAAABAAEAAJwQMhEwAgQJJAAjGAAAAgADAACc6BoBiAAAAyNtb292AAAAbG12aGQAAAAAAAAAAAAAAAAAAAPoAAAB
+        LAABAAABAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
+        AAAAAAACAAACTXRyYWsAAABcdGtoZAAAAAMAAAAAAAAAAAAAAAEAAAAAAAABLAAAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAA
+        AAAAAAEAAAAAAAAAAAAAAAAAAEAAAAAAQAAAAEAAAAAAACRlZHRzAAAAHGVsc3QAAAAAAAAAAQAAASwAAAAAAAEAAAAAAcVtZGlh
+        AAAAIG1kaGQAAAAAAAAAAAAAAAAAACgAAAAMAFXEAAAAAAAtaGRscgAAAAAAAAAAdmlkZQAAAAAAAAAAAAAAAFZpZGVvSGFuZGxl
+        cgAAAAFwbWluZgAAABR2bWhkAAAAAQAAAAAAAAAAAAAAJGRpbmYAAAAcZHJlZgAAAAAAAAABAAAADHVybCAAAAABAAABMHN0YmwA
+        AACsc3RzZAAAAAAAAAABAAAAnGF2MDEAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAQABAAEgAAABIAAAAAAAAAAEXTGF2YzYyLjI4
+        LjEwMSBsaWJzdnRhdjEAAAAAAAAAAAAY//8AAAAYYXYxQ4EATAAKCgAAAAKv/4BfCAgAAAAKZmllbAEAAAAAEHBhc3AAAAABAAAA
+        AQAAABRidHJ0AAAAAAAABvoAAAb6AAAAGHN0dHMAAAAAAAAAAQAAAAMAAAQAAAAAFHN0c3MAAAAAAAAAAQAAAAEAAAAcc3RzYwAA
+        AAAAAAABAAAAAQAAAAMAAAABAAAAIHN0c3oAAAAAAAAAAAAAAAMAAAAaAAAAJgAAAAMAAAAUc3RjbwAAAAAAAAABAAAAMAAAAGJ1
+        ZHRhAAAAWm1ldGEAAAAAAAAAIWhkbHIAAAAAAAAAAG1kaXJhcHBsAAAAAAAAAAAAAAAALWlsc3QAAAAlqXRvbwAAAB1kYXRhAAAA
+        AQAAAABMYXZmNjIuMTIuMTAx
+        """
+}

From 11f6f17b63f2fb4ca348a3842242f5a2ccaa072d Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 09:03:08 +0200
Subject: [PATCH 202/359] fix(hls): attribute scans a tag line once, lines cap
 at 64 KiB, dates parse without a formatter each (audit NET-105, NAT-102,
 NET-106)

HLSPlaylistParser.attribute recounted the quotes from the line start for every KEY= it met, 9.6 s
for a 64 KiB line and 4x per doubling. It is one pass carrying the quote parity now, parse refuses
a line over 64 KiB, and EXTINF finds its duration field without splitting the title. Program dates
go through two static Date.ISO8601FormatStyle values instead of two ISO8601DateFormatters per line.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../IO/HLSIngest/HLSPlaylist.swift            |  88 +++++---
 .../HLSPlaylistHostileInputTests.swift        | 195 ++++++++++++++++++
 2 files changed, 253 insertions(+), 30 deletions(-)
 create mode 100644 Tests/AetherEngineTests/HLSPlaylistHostileInputTests.swift

diff --git a/Sources/AetherEngine/IO/HLSIngest/HLSPlaylist.swift b/Sources/AetherEngine/IO/HLSIngest/HLSPlaylist.swift
index 1a31be72c..f5847bb43 100644
--- a/Sources/AetherEngine/IO/HLSIngest/HLSPlaylist.swift
+++ b/Sources/AetherEngine/IO/HLSIngest/HLSPlaylist.swift
@@ -81,13 +81,23 @@ enum HLSPlaylist: Equatable {
 /// Line-oriented RFC 8216 parser for the subset the live ingest needs. Pure (no I/O).
 enum HLSPlaylistParser {
 
+    /// Audit NET-105: the longest line any tag or URI in a real playlist comes to is a DATERANGE with
+    /// a SCTE-35 payload, a few KB. A line past this is not a playlist line, and refusing it keeps every
+    /// per-line helper, present and future, off a megabyte of one attribute soup.
+    static let maximumLineBytes = 64 * 1024
+
     static func parse(_ text: String) throws -> HLSPlaylist {
         // `split(separator: "\n")` compares whole Characters, and "\r\n" is one grapheme cluster in
         // Swift, so a CRLF playlist came back as a single line (audit NET-2, NAT-3). `isNewline` is
         // true for "\r\n", "\n" and "\r" alike.
-        let lines = text
+        let lines = try text
             .split(whereSeparator: \.isNewline)
-            .map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }
+            .map { line -> String in
+                guard line.utf8.count <= maximumLineBytes else {
+                    throw HLSIngestError.playlistInvalid(reason: "playlist line exceeds \(maximumLineBytes) bytes")
+                }
+                return line.trimmingCharacters(in: .whitespacesAndNewlines)
+            }
             .filter { !$0.isEmpty }
         guard lines.first?.hasPrefix("#EXTM3U") == true else {
             throw HLSIngestError.playlistInvalid(reason: "missing #EXTM3U")
@@ -191,8 +201,11 @@ enum HLSPlaylistParser {
                     mediaSequence = parsed
                 }
             } else if line.hasPrefix("#EXTINF:") {
-                let payload = line.dropFirst("#EXTINF:".count)
-                pendingDuration = try boundedDuration(payload.split(separator: ",").first ?? "", tag: "EXTINF")
+                // The duration is the first non-empty comma field; `split` built a Substring for every
+                // field of the title to find it (audit NET-105).
+                let payload = line.dropFirst("#EXTINF:".count).drop(while: { $0 == "," })
+                let field = payload[..<(payload.firstIndex(of: ",") ?? payload.endIndex)]
+                pendingDuration = try boundedDuration(field, tag: "EXTINF")
             } else if line.hasPrefix("#EXT-X-DISCONTINUITY") && !line.hasPrefix("#EXT-X-DISCONTINUITY-SEQUENCE") {
                 pendingDiscontinuity = true
             } else if line.hasPrefix("#EXT-X-KEY:") {
@@ -280,14 +293,14 @@ enum HLSPlaylistParser {
     /// because the spec allows it.
     private static func parseProgramDateTime(_ raw: String) -> Date? {
         let text = raw.trimmingCharacters(in: .whitespaces)
-        let withFraction = ISO8601DateFormatter()
-        withFraction.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
-        if let date = withFraction.date(from: text) { return date }
-        let plain = ISO8601DateFormatter()
-        plain.formatOptions = [.withInternetDateTime]
-        return plain.date(from: text)
+        return (try? fractionalDateStyle.parse(text)) ?? (try? plainDateStyle.parse(text))
     }
 
+    /// Audit NET-106: two `ISO8601DateFormatter`s were built per PROGRAM-DATE-TIME line, 1.1 to 1.6 s
+    /// for a 3600-segment window that carries one on every segment. Value-type styles are built once.
+    private static let fractionalDateStyle = Date.ISO8601FormatStyle(includingFractionalSeconds: true)
+    private static let plainDateStyle = Date.ISO8601FormatStyle()
+
     private static func parseHexIV(_ raw: String) -> Data? {
         var hex = raw.trimmingCharacters(in: .whitespaces)
         if hex.hasPrefix("0x") || hex.hasPrefix("0X") { hex = String(hex.dropFirst(2)) }
@@ -317,28 +330,43 @@ enum HLSPlaylistParser {
     /// Extract a KEY=VALUE attribute from a tag line, tolerating quoted values. Match is anchored to `:` or `,` before the key: bare substring search matched `BANDWIDTH=` inside `AVERAGE-BANDWIDTH=` and caused wrong variant selection.
     /// Internal rather than private since #316: the master rewriter reads the same attributes off the
     /// same tag lines, and a second parser would be a second place for the anchoring trap to reappear.
+    ///
+    /// One left-to-right pass that carries the quote parity along. It recounted the quotes from the
+    /// line start for every `KEY=` it met, so a line of unclosed quote plus thousands of `,KEY=` took
+    /// time quadratic in its length, 9.6 s at 64 KiB (audit NET-105, NAT-102). Scanned as UTF-8: the
+    /// delimiters are ASCII.
     static func attribute(_ key: String, in line: String) -> String? {
-        let needle = "\(key)="
-        var searchStart = line.startIndex
-        while let range = line.range(of: needle, range: searchStart..<line.endIndex) {
-            searchStart = range.upperBound
-            if range.lowerBound != line.startIndex {
-                let before = line[line.index(before: range.lowerBound)]
-                guard before == ":" || before == "," else { continue }
-            }
-            // Reject matches inside quoted values (odd quote count before match = inside quotes).
-            let quotesBefore = line[line.startIndex..<range.lowerBound]
-                .reduce(0) { $1 == "\"" ? $0 + 1 : $0 }
-            guard quotesBefore % 2 == 0 else { continue }
-            let rest = line[range.upperBound...]
-            if rest.hasPrefix("\"") {
-                let afterQuote = rest.dropFirst()
-                guard let end = afterQuote.firstIndex(of: "\"") else { return nil }
-                return String(afterQuote[..<end])
+        let needle = Array("\(key)=".utf8)
+        var line = line
+        return line.withUTF8 { bytes -> String? in
+            let count = bytes.count
+            var insideQuotes = false
+            var index = 0
+            while index < count {
+                let byte = bytes[index]
+                if byte == UInt8(ascii: "\"") {
+                    insideQuotes.toggle()
+                    index += 1
+                    continue
+                }
+                guard !insideQuotes, byte == needle[0], index + needle.count <= count,
+                      index == 0 || bytes[index - 1] == UInt8(ascii: ":") || bytes[index - 1] == UInt8(ascii: ","),
+                      needle.indices.allSatisfy({ bytes[index + $0] == needle[$0] })
+                else {
+                    index += 1
+                    continue
+                }
+                let valueStart = index + needle.count
+                if valueStart < count, bytes[valueStart] == UInt8(ascii: "\"") {
+                    let quoted = UnsafeBufferPointer(rebasing: bytes[(valueStart + 1)...])
+                    guard let end = quoted.firstIndex(of: UInt8(ascii: "\"")) else { return nil }
+                    return String(decoding: UnsafeBufferPointer(rebasing: quoted[..<end]), as: UTF8.self)
+                }
+                let rest = UnsafeBufferPointer(rebasing: bytes[valueStart...])
+                let end = rest.firstIndex(of: UInt8(ascii: ",")) ?? rest.endIndex
+                return String(decoding: UnsafeBufferPointer(rebasing: rest[..<end]), as: UTF8.self)
             }
-            let end = rest.firstIndex(of: ",") ?? rest.endIndex
-            return String(rest[..<end])
+            return nil
         }
-        return nil
     }
 }
diff --git a/Tests/AetherEngineTests/HLSPlaylistHostileInputTests.swift b/Tests/AetherEngineTests/HLSPlaylistHostileInputTests.swift
new file mode 100644
index 000000000..93a5760db
--- /dev/null
+++ b/Tests/AetherEngineTests/HLSPlaylistHostileInputTests.swift
@@ -0,0 +1,195 @@
+import Testing
+import Foundation
+@testable import AetherEngine
+
+/// Audit NET-105 / NAT-102 / NET-106: `HLSPlaylistParser.attribute` recounted the quotes from the line
+/// start for every `KEY=` it met (a 64 KiB line took 9.6 s, 4x per doubling), and every
+/// EXT-X-PROGRAM-DATE-TIME line built two `ISO8601DateFormatter`s.
+struct HLSPlaylistHostileInputTests {
+
+    /// The implementation `attribute` had before the single pass, kept as the oracle.
+    private func legacyAttribute(_ key: String, in line: String) -> String? {
+        let needle = "\(key)="
+        var searchStart = line.startIndex
+        while let range = line.range(of: needle, range: searchStart..<line.endIndex) {
+            searchStart = range.upperBound
+            if range.lowerBound != line.startIndex {
+                let before = line[line.index(before: range.lowerBound)]
+                guard before == ":" || before == "," else { continue }
+            }
+            let quotesBefore = line[line.startIndex..<range.lowerBound]
+                .reduce(0) { $1 == "\"" ? $0 + 1 : $0 }
+            guard quotesBefore % 2 == 0 else { continue }
+            let rest = line[range.upperBound...]
+            if rest.hasPrefix("\"") {
+                let afterQuote = rest.dropFirst()
+                guard let end = afterQuote.firstIndex(of: "\"") else { return nil }
+                return String(afterQuote[..<end])
+            }
+            let end = rest.firstIndex(of: ",") ?? rest.endIndex
+            return String(rest[..<end])
+        }
+        return nil
+    }
+
+    private struct SplitMix64: RandomNumberGenerator {
+        var state: UInt64
+        mutating func next() -> UInt64 {
+            state &+= 0x9E37_79B9_7F4A_7C15
+            var z = state
+            z = (z ^ (z >> 30)) &* 0xBF58_476D_1CE4_E5B9
+            z = (z ^ (z >> 27)) &* 0x94D0_49BB_1331_11EB
+            return z ^ (z >> 31)
+        }
+    }
+
+    private static let keys = ["BANDWIDTH", "AVERAGE-BANDWIDTH", "URI", "TYPE", "GROUP-ID", "NAME", "DEFAULT",
+                               "SUBTITLES", "AUDIO", "METHOD", "IV", "LANGUAGE", "FORCED"]
+
+    private static let ordinaryLines = [
+        "#EXT-X-STREAM-INF:BANDWIDTH=2000000,AVERAGE-BANDWIDTH=1500000,AUDIO=\"aud\",SUBTITLES=\"subs\"",
+        "#EXT-X-STREAM-INF:AVERAGE-BANDWIDTH=1500000,BANDWIDTH=2000000",
+        "#EXT-X-STREAM-INF:AVERAGE-BANDWIDTH=1500000",
+        "#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID=\"subs\",NAME=\"Deutsch, SDH\",LANGUAGE=\"de\",DEFAULT=YES,URI=\"de.m3u8\"",
+        "#EXT-X-MEDIA:TYPE=AUDIO,GROUP-ID=\"a\",NAME=\"TYPE=VIDEO\",URI=\"a.m3u8\"",
+        "#EXT-X-KEY:METHOD=AES-128,URI=\"https://k.example/key?a=1,b=2\",IV=0x00000000000000000000000000000001",
+        "#EXT-X-KEY:METHOD=NONE",
+        "#EXT-X-MEDIA:NAME=\"unterminated,TYPE=AUDIO",
+        "#EXT-X-MEDIA:URI=\"",
+        "#EXT-X-MEDIA:URI=",
+        "URI=first,TYPE=x",
+        "xURI=nope,URI=yes",
+        "",
+        "=",
+        "#EXT-X-MEDIA:NAME=\"caf\u{00E9} \u{4E2D}\u{6587}\",URI=\"\u{1F600}.m3u8\"",
+    ]
+
+    @Test("the single pass matches the old scan on ordinary tag lines")
+    func matchesOldScanOnOrdinaryLines() {
+        for line in Self.ordinaryLines {
+            for key in Self.keys {
+                #expect(HLSPlaylistParser.attribute(key, in: line) == legacyAttribute(key, in: line),
+                        "key \(key) line \(line.debugDescription)")
+            }
+        }
+    }
+
+    @Test("the single pass matches the old scan on generated quote and comma soup")
+    func matchesOldScanOnGeneratedLines() {
+        let pieces = ["\"", "\"", ",", ",", ":", "=", "#EXT-X-MEDIA:", "URI=", "TYPE=", "BANDWIDTH=", "AVERAGE-",
+                      "NAME=", "a", "b", " ", "x=y", "GROUP-ID=", "\u{00E9}"]
+        var rng = SplitMix64(state: 0x1105_0105)
+        for _ in 0..<4000 {
+            var line = ""
+            for _ in 0..<Int.random(in: 0...24, using: &rng) { line += pieces.randomElement(using: &rng)! }
+            for key in ["URI", "TYPE", "BANDWIDTH", "NAME", "GROUP-ID"] {
+                #expect(HLSPlaylistParser.attribute(key, in: line) == legacyAttribute(key, in: line),
+                        "key \(key) line \(line.debugDescription)")
+            }
+        }
+    }
+
+    @Test("an unclosed quote followed by thousands of attributes scans in linear time")
+    func unclosedQuoteIsLinear() {
+        let line = "#EXT-X-MEDIA:NAME=\"" + String(repeating: ",TYPE=", count: 8_000)
+        #expect(line.utf8.count < 64 * 1024)
+        let started = ContinuousClock.now
+        #expect(HLSPlaylistParser.attribute("TYPE", in: line) == nil)
+        #expect(HLSPlaylistParser.attribute("URI", in: line) == nil)
+        let elapsed = ContinuousClock.now - started
+        #expect(elapsed < .seconds(2), "took \(elapsed)")
+    }
+
+    @Test("a master playlist with a 1 MiB tag line is refused quickly")
+    func oversizedLineIsRefused() {
+        let hostile = "#EXT-X-MEDIA:NAME=\"" + String(repeating: ",TYPE=", count: 200_000)
+        let text = "#EXTM3U\n#EXT-X-STREAM-INF:BANDWIDTH=1\nv.m3u8\n\(hostile)\n"
+        let started = ContinuousClock.now
+        #expect(throws: HLSIngestError.self) { _ = try HLSPlaylistParser.parse(text) }
+        #expect(ContinuousClock.now - started < .seconds(2))
+    }
+
+    @Test("a long but plausible tag line still parses")
+    func longPlausibleLineParses() throws {
+        let scte = String(repeating: "FC302500", count: 1_000)
+        let text = """
+        #EXTM3U
+        #EXT-X-TARGETDURATION:6
+        #EXT-X-DATERANGE:ID="ad",START-DATE="2026-09-30T10:00:00Z",SCTE35-OUT=0x\(scte)
+        #EXTINF:6.0,
+        seg0.ts
+        """
+        guard case .media(let media) = try HLSPlaylistParser.parse(text) else {
+            Issue.record("not a media playlist"); return
+        }
+        #expect(media.segments.count == 1)
+    }
+
+    @Test("EXTINF reads its duration from the first non-empty comma field")
+    func extinfDurationField() throws {
+        func duration(_ tag: String) throws -> Double? {
+            let text = "#EXTM3U\n#EXT-X-TARGETDURATION:9\n\(tag)\nseg.ts\n"
+            guard case .media(let media) = try HLSPlaylistParser.parse(text) else { return nil }
+            return media.segments.first?.duration
+        }
+        #expect(try duration("#EXTINF:6.5,Title, with, commas") == 6.5)
+        #expect(try duration("#EXTINF:6.5") == 6.5)
+        #expect(try duration("#EXTINF:,7,x") == 7)
+        #expect(try duration("#EXTINF:,") == 9)
+        #expect(try duration("#EXTINF:abc,x") == 9)
+    }
+
+    // MARK: - EXT-X-PROGRAM-DATE-TIME
+
+    private func legacyProgramDateTime(_ raw: String) -> Date? {
+        let text = raw.trimmingCharacters(in: .whitespaces)
+        let withFraction = ISO8601DateFormatter()
+        withFraction.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
+        if let date = withFraction.date(from: text) { return date }
+        let plain = ISO8601DateFormatter()
+        plain.formatOptions = [.withInternetDateTime]
+        return plain.date(from: text)
+    }
+
+    private func firstSegmentDate(_ pdt: String) throws -> Date? {
+        let text = "#EXTM3U\n#EXT-X-TARGETDURATION:6\n#EXT-X-PROGRAM-DATE-TIME:\(pdt)\n#EXTINF:6.0,\nseg.ts\n"
+        guard case .media(let media) = try HLSPlaylistParser.parse(text) else { return nil }
+        return media.segments.first?.programDateTime
+    }
+
+    @Test("fractional and plain program dates parse as the ISO8601DateFormatters did")
+    func programDatesMatchTheOldFormatters() throws {
+        let shapes = ["2026-09-30T10:00:00.000Z", "2026-09-30T10:00:00Z", "2026-09-30T10:00:00.123Z",
+                      "2026-09-30T10:00:00.123456Z", "2026-09-30T10:00:00.000+00:00", "2026-09-30T10:00:00.000+0000",
+                      "2026-09-30T12:00:00+02:00", "2026-09-30T12:00:00.250+02:00", "2026-09-30T10:00:00.5Z",
+                      "  2026-09-30T10:00:00.000Z  ", "2026-09-30 10:00:00Z", "garbage", "", "2026-13-45T99:00:00Z"]
+        for shape in shapes {
+            let expected = legacyProgramDateTime(shape)
+            let actual = try firstSegmentDate(shape)
+            switch (expected, actual) {
+            case (nil, nil): break
+            case let (expected?, actual?):
+                #expect(abs(expected.timeIntervalSince(actual)) < 0.001, "shape \(shape.debugDescription)")
+            default:
+                Issue.record("shape \(shape.debugDescription): old \(String(describing: expected)) new \(String(describing: actual))")
+            }
+        }
+    }
+
+    @Test("a playlist with a program date on every segment parses in linear time")
+    func programDatePerSegmentIsLinear() throws {
+        var text = "#EXTM3U\n#EXT-X-TARGETDURATION:2\n#EXT-X-MEDIA-SEQUENCE:1\n"
+        for index in 0..<7_200 {
+            let second = index * 2
+            let stamp = String(format: "2026-09-30T%02d:%02d:%02d.000Z", (second / 3600) % 24, (second / 60) % 60, second % 60)
+            text += "#EXT-X-PROGRAM-DATE-TIME:\(stamp)\n#EXTINF:2.0,\nseg\(index).ts\n"
+        }
+        let started = ContinuousClock.now
+        let parsed = try HLSPlaylistParser.parse(text)
+        let elapsed = ContinuousClock.now - started
+        guard case .media(let media) = parsed else { Issue.record("not a media playlist"); return }
+        #expect(media.segments.count == 7_200)
+        #expect(media.segments.allSatisfy { $0.programDateTime != nil })
+        #expect(elapsed < .seconds(1), "took \(elapsed)")
+    }
+}

From 689f729ef778cc6873cc89e12b01575c82c43168 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 09:03:08 +0200
Subject: [PATCH 203/359] fix(subtitles): the packet store appends in place and
 counts unfinished display sets (audit SUB-103, PERF-107, SUB-111)

appendLocked copied every retained packet per append (40k appends took 10.9 s) because the
dictionary still held the array. The array is taken out first, per-stream and aggregate eviction
drop to a low-water mark with one removeFirst(k), a same-PTS run is screened through a hash set
instead of compared packet by packet, and the window reads search instead of scanning. PGS display
sets in assembly now count toward the aggregate cap and the coldest stream's unfinished set is
dropped first; one set is capped at 4 MiB instead of 16.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../Subtitles/SubtitlePacketStore.swift       | 143 ++++++++++----
 .../SubtitlePacketStoreScalingTests.swift     | 178 ++++++++++++++++++
 2 files changed, 289 insertions(+), 32 deletions(-)
 create mode 100644 Tests/AetherEngineTests/SubtitlePacketStoreScalingTests.swift

diff --git a/Sources/AetherEngine/Subtitles/SubtitlePacketStore.swift b/Sources/AetherEngine/Subtitles/SubtitlePacketStore.swift
index 1374cd9e2..379cb5921 100644
--- a/Sources/AetherEngine/Subtitles/SubtitlePacketStore.swift
+++ b/Sources/AetherEngine/Subtitles/SubtitlePacketStore.swift
@@ -58,7 +58,9 @@ final class SubtitlePacketStore: @unchecked Sendable {
 
     /// Ceiling for one in-assembly PGS display set (a 4K set stays far below this); a pending
     /// buffer past it is malformed or mis-parsed and gets dropped rather than grown unbounded.
-    static let maxPendingDisplaySetBytes: Int = 16 * 1024 * 1024
+    /// Audit SUB-111: pending sets also count toward the aggregate cap, so 16 MiB per set was
+    /// room for 16 MiB x 2 writers x every PID of a crafted transport stream.
+    static let maxPendingDisplaySetBytes: Int = 4 * 1024 * 1024
 
     /// #151: which reader is writing. The pump and the forward prefetcher can both feed the same
     /// stream; a completed entry re-harvested by the other collapses on a byte-identical payload in
@@ -86,14 +88,22 @@ final class SubtitlePacketStore: @unchecked Sendable {
     private var entriesByStream: [Int32: [StoredSubtitlePacket]] = [:]
     private var bytesByStream: [Int32: Int] = [:]
     private var pendingSetByStream: [PendingKey: PendingDisplaySet] = [:]
+    /// Audit SUB-103: same-PTS runs longer than `linearDedupeRun` answer "was this payload already
+    /// stored here" from a hash set instead of comparing against every packet of the run. The set is
+    /// only a filter: it may hold hashes of evicted packets (a stale hit costs one scan) but never
+    /// lacks one of a live packet, since every append to the run inserts its hash.
+    private var payloadHashesByRun: [Int32: [UInt64: Set<Int>]] = [:]
+    private static let linearDedupeRun = 8
+    private static let maxCachedRunsPerStream = 4096
 
     /// Instance caps (default to the static ceilings). Injectable so tests can drive eviction with
     /// tiny payloads instead of allocating gigabytes.
     private let perStreamCap: Int
     private let aggregateCap: Int
 
-    /// #166 aggregate-budget bookkeeping. `totalBytes` mirrors the sum of `bytesByStream` (kept
-    /// incrementally so the per-append check is O(1)). `protectedStreams` are the active drain
+    /// #166 aggregate-budget bookkeeping. `totalBytes` mirrors the sum of `bytesByStream` plus the
+    /// display sets still in assembly (audit SUB-111), kept incrementally so the per-append check is
+    /// O(1). `protectedStreams` are the active drain
     /// targets, never evicted by aggregate pressure. `lastTouchByStream` orders non-protected
     /// streams coldest-first for eviction; a monotonic counter (no wall clock) drives it.
     private var totalBytes: Int = 0
@@ -179,7 +189,10 @@ final class SubtitlePacketStore: @unchecked Sendable {
     private func appendLocked(streamIndex: Int32, ptsSeconds: Double, durationSeconds: Double,
                               flags: Int32, payload: Data, webvttSettings: String? = nil) {
         let before = bytesByStream[streamIndex] ?? 0
-        var entries = entriesByStream[streamIndex] ?? []
+        // Audit SUB-103: taken out of the dictionary before it is mutated. Left in, the dictionary
+        // holds the second reference and the insert below copied every retained packet per append,
+        // 10k appends took 0.65 s and 40k took 10.9 s.
+        var entries = entriesByStream.removeValue(forKey: streamIndex) ?? []
         var bytes = before
         // #362: a re-harvest of a packet already stored takes the FRESH sequence. It is a new
         // observation of that position by the run doing the writing, and that is exactly what the
@@ -198,24 +211,26 @@ final class SubtitlePacketStore: @unchecked Sendable {
         // prefetcher re-harvesting the same packet (#151), and only that collapses. Anything else
         // joins the end of the run, so a shared timestamp reaches the drainer in harvest order:
         // the drainer decodes a window in array order and later events layer over earlier ones.
-        var probe = Self.lowerBound(entries, ptsSeconds)
-        var duplicateIndex: Int?
-        while probe < entries.count, entries[probe].ptsSeconds == ptsSeconds {
-            if entries[probe].payload == payload {
-                duplicateIndex = probe
-                break
-            }
-            probe += 1
-        }
-        if let duplicateIndex {
+        let run = Self.lowerBound(entries, ptsSeconds)..<Self.upperBound(entries, ptsSeconds)
+        if let duplicateIndex = duplicateIndexLocked(in: entries, run: run, payload: payload,
+                                                     streamIndex: streamIndex, ptsSeconds: ptsSeconds) {
             bytes -= entries[duplicateIndex].payload.count
             entries[duplicateIndex] = entry
         } else {
-            entries.insert(entry, at: probe)
+            entries.insert(entry, at: run.upperBound)
         }
         bytes += payload.count
-        while bytes > perStreamCap, entries.count > 1 {
-            bytes -= entries.removeFirst().payload.count
+        if bytes > perStreamCap {
+            // Audit SUB-103: evict to a low-water mark in one move. Dropping just enough made every
+            // append at the cap shift the whole array for one packet.
+            let lowWater = perStreamCap - perStreamCap / 10
+            var dropped = 0
+            while bytes > lowWater, dropped < entries.count - 1 {
+                bytes -= entries[dropped].payload.count
+                dropped += 1
+            }
+            entries.removeFirst(dropped)
+            payloadHashesByRun[streamIndex] = nil
         }
         entriesByStream[streamIndex] = entries
         bytesByStream[streamIndex] = bytes
@@ -225,6 +240,25 @@ final class SubtitlePacketStore: @unchecked Sendable {
         enforceAggregateCapLocked(justTouched: streamIndex)
     }
 
+    /// Index within `run` of the packet `payload` duplicates, nil when it is new. A long run is
+    /// screened through `payloadHashesByRun` first; see there.
+    private func duplicateIndexLocked(in entries: [StoredSubtitlePacket], run: Range<Int>, payload: Data,
+                                      streamIndex: Int32, ptsSeconds: Double) -> Int? {
+        guard !run.isEmpty else { return nil }
+        func scan() -> Int? {
+            run.first { entries[$0].payload.count == payload.count && entries[$0].payload == payload }
+        }
+        guard run.count > Self.linearDedupeRun else { return scan() }
+        let key = (ptsSeconds + 0.0).bitPattern
+        var runs = payloadHashesByRun.removeValue(forKey: streamIndex) ?? [:]
+        var hashes = runs.removeValue(forKey: key) ?? Set(run.map { entries[$0].payload.hashValue })
+        let seenBefore = !hashes.insert(payload.hashValue).inserted
+        if runs.count >= Self.maxCachedRunsPerStream { runs.removeAll() }
+        runs[key] = hashes
+        payloadHashesByRun[streamIndex] = runs
+        return seenBefore ? scan() : nil
+    }
+
     /// First index at or past `ptsSeconds` in a PTS-sorted run. Harvest is near-monotonic, but the
     /// forward prefetcher (#151) backfills far behind the frontier, so the position is searched
     /// rather than assumed. Searched in log time rather than scanned from the front: the scan made
@@ -245,6 +279,21 @@ final class SubtitlePacketStore: @unchecked Sendable {
         return low
     }
 
+    /// First index whose PTS is greater than `ptsSeconds`; `lowerBound` and this bracket a same-PTS run.
+    static func upperBound(_ entries: [StoredSubtitlePacket], _ ptsSeconds: Double) -> Int {
+        var low = 0
+        var high = entries.count
+        while low < high {
+            let mid = low + (high - low) / 2
+            if entries[mid].ptsSeconds <= ptsSeconds {
+                low = mid + 1
+            } else {
+                high = mid
+            }
+        }
+        return low
+    }
+
     /// #166: bound retained bytes across ALL streams. Evict oldest entries from the coldest
     /// (least-recently-touched) NON-protected stream first, then the next coldest, until the total
     /// is back under `aggregateCap` or only protected streams remain. Protected streams (the active
@@ -252,20 +301,35 @@ final class SubtitlePacketStore: @unchecked Sendable {
     /// cold stream is dropped and re-harvested from the pump/prefetcher if it is selected later.
     private func enforceAggregateCapLocked(justTouched: Int32) {
         guard totalBytes > aggregateCap else { return }
-        let candidates = bytesByStream.keys
+        // Audit SUB-103: down to a low-water mark, so the pass does not rerun on the next append, and
+        // each victim loses its leading packets in one `removeFirst(k)`.
+        let lowWater = aggregateCap - aggregateCap / 10
+        var streams = Set(bytesByStream.keys)
+        for key in pendingSetByStream.keys { streams.insert(key.streamIndex) }
+        let candidates = streams
             .filter { !protectedStreams.contains($0) && $0 != justTouched }
             .sorted { (lastTouchByStream[$0] ?? 0) < (lastTouchByStream[$1] ?? 0) }
         for idx in candidates {
-            guard totalBytes > aggregateCap else { break }
-            guard var entries = entriesByStream[idx] else { continue }
+            guard totalBytes > lowWater else { break }
+            // Audit SUB-111: an unfinished display set of a cold stream goes before anything complete.
+            for writer in [Writer.pump, Writer.prefetch] {
+                _ = takePendingLocked(PendingKey(streamIndex: idx, writer: writer))
+            }
+            guard totalBytes > lowWater, var entries = entriesByStream.removeValue(forKey: idx) else {
+                if entriesByStream[idx] == nil { lastTouchByStream[idx] = nil }
+                continue
+            }
             var bytes = bytesByStream[idx] ?? 0
-            while totalBytes > aggregateCap, !entries.isEmpty {
-                let removed = entries.removeFirst().payload.count
+            var dropped = 0
+            while totalBytes > lowWater, dropped < entries.count {
+                let removed = entries[dropped].payload.count
                 bytes -= removed
                 totalBytes -= removed
+                dropped += 1
             }
+            entries.removeFirst(dropped)
+            payloadHashesByRun[idx] = nil
             if entries.isEmpty {
-                entriesByStream[idx] = nil
                 bytesByStream[idx] = nil
                 lastTouchByStream[idx] = nil
             } else {
@@ -275,6 +339,21 @@ final class SubtitlePacketStore: @unchecked Sendable {
         }
     }
 
+    /// A display set in assembly leaves the dictionary while it is worked on, so appending to it is in
+    /// place, and its bytes leave the aggregate count with it. `putPendingLocked` is the way back.
+    private func takePendingLocked(_ key: PendingKey) -> PendingDisplaySet? {
+        guard let pending = pendingSetByStream.removeValue(forKey: key) else { return nil }
+        totalBytes -= pending.payload.count
+        return pending
+    }
+
+    private func putPendingLocked(_ pending: PendingDisplaySet, _ key: PendingKey) {
+        pendingSetByStream[key] = pending
+        totalBytes += pending.payload.count
+        touchCounter &+= 1
+        lastTouchByStream[key.streamIndex] = touchCounter
+    }
+
     /// Shared pump-side harvest for both hosts: convert a raw AVPacket into a stored entry on
     /// the source PTS axis (raw pts x time_base, matching what EmbeddedSubtitleDecoder computes
     /// for tap packets; no start_time subtraction) and append it. Copies synchronously; the
@@ -332,7 +411,7 @@ final class SubtitlePacketStore: @unchecked Sendable {
         }
         let key = PendingKey(streamIndex: streamIndex, writer: writer)
         while !chunk.isEmpty {
-            var pending = pendingSetByStream[key]
+            var pending = takePendingLocked(key)
             // A backward pts jump under an open set means the pump re-anchored mid-set;
             // the stale partial buffer must not swallow the fresh set's segments.
             if let pts = ptsSeconds, let open = pending, pts < open.ptsSeconds - 1.0 {
@@ -344,7 +423,6 @@ final class SubtitlePacketStore: @unchecked Sendable {
                 // restart overlap above) is undecodable on its own and gets dropped.
                 pending = nil
                 guard let pts = ptsSeconds else {
-                    pendingSetByStream[key] = nil
                     return   // No anchor for this set; skip its chunks until the next PCS.
                 }
                 pending = PendingDisplaySet(ptsSeconds: pts, durationSeconds: durationSeconds,
@@ -352,9 +430,9 @@ final class SubtitlePacketStore: @unchecked Sendable {
             }
             guard var open = pending else {
                 // Mid-set start (backfill landed between PCS and END): not decodable, drop.
-                pendingSetByStream[key] = nil
                 return
             }
+            pending = nil
             let endBoundary = Self.pgsEndBoundary(in: chunk)
             let consumed: Data
             if let endBoundary {
@@ -367,16 +445,15 @@ final class SubtitlePacketStore: @unchecked Sendable {
             open.payload.append(consumed)
             open.flags |= flags
             if open.payload.count > Self.maxPendingDisplaySetBytes {
-                pendingSetByStream[key] = nil
                 return
             }
             if endBoundary != nil {
                 appendLocked(streamIndex: streamIndex, ptsSeconds: open.ptsSeconds,
                              durationSeconds: open.durationSeconds, flags: open.flags,
                              payload: open.payload)
-                pendingSetByStream[key] = nil
             } else {
-                pendingSetByStream[key] = open
+                putPendingLocked(open, key)
+                enforceAggregateCapLocked(justTouched: streamIndex)
             }
         }
     }
@@ -409,7 +486,8 @@ final class SubtitlePacketStore: @unchecked Sendable {
     func entries(streamIndex: Int32, from: Double, through: Double) -> [StoredSubtitlePacket] {
         lock.lock(); defer { lock.unlock() }
         guard let entries = entriesByStream[streamIndex] else { return [] }
-        return entries.filter { $0.ptsSeconds >= from && $0.ptsSeconds <= through }
+        // The run is PTS-sorted, so the window is found by search instead of a scan of the session.
+        return Array(entries[Self.lowerBound(entries, from)...].prefix { $0.ptsSeconds <= through })
     }
 
     /// #362: PTS of the first stored packet on `streamIndex` strictly after `ptsSeconds`.
@@ -422,8 +500,7 @@ final class SubtitlePacketStore: @unchecked Sendable {
     func firstPTS(streamIndex: Int32, after ptsSeconds: Double) -> Double? {
         lock.lock(); defer { lock.unlock() }
         guard let entries = entriesByStream[streamIndex] else { return nil }
-        var index = Self.lowerBound(entries, ptsSeconds)
-        while index < entries.count, entries[index].ptsSeconds <= ptsSeconds { index += 1 }
+        let index = Self.upperBound(entries, ptsSeconds)
         guard index < entries.count else { return nil }
         // Deliberately answered even across a harvest hole, where the next stored packet belongs to
         // an older run and the real successor is still on its way. The answer is then too late, but
@@ -457,6 +534,7 @@ final class SubtitlePacketStore: @unchecked Sendable {
                 totalBytes += newBytes - (bytesByStream[idx] ?? 0)
                 entriesByStream[idx] = Array(kept)
                 bytesByStream[idx] = newBytes
+                payloadHashesByRun[idx] = nil
             }
         }
     }
@@ -466,6 +544,7 @@ final class SubtitlePacketStore: @unchecked Sendable {
         entriesByStream.removeAll()
         bytesByStream.removeAll()
         pendingSetByStream.removeAll()
+        payloadHashesByRun.removeAll()
         lastTouchByStream.removeAll()
         protectedStreams.removeAll()
         totalBytes = 0
diff --git a/Tests/AetherEngineTests/SubtitlePacketStoreScalingTests.swift b/Tests/AetherEngineTests/SubtitlePacketStoreScalingTests.swift
new file mode 100644
index 000000000..6110a4a6b
--- /dev/null
+++ b/Tests/AetherEngineTests/SubtitlePacketStoreScalingTests.swift
@@ -0,0 +1,178 @@
+import Foundation
+import Testing
+@testable import AetherEngine
+
+/// Audit SUB-103 / SUB-111: `appendLocked` copied the whole per-stream array on every append (40k
+/// appends took 10.9 s), the same-PTS duplicate check walked the whole run, the aggregate pass shifted
+/// the array once per evicted packet, and display sets still in assembly sat outside every cap.
+struct SubtitlePacketStoreScalingTests {
+
+    private func payload(_ index: Int, size: Int = 24) -> Data {
+        var data = Data(repeating: 0x41, count: size)
+        withUnsafeBytes(of: UInt64(index).littleEndian) { data.replaceSubrange(0..<8, with: $0) }
+        return data
+    }
+
+    @Test("40k ascending appends stay linear")
+    func ascendingAppendsAreLinear() {
+        let store = SubtitlePacketStore()
+        let started = ContinuousClock.now
+        for index in 0..<40_000 {
+            store.append(streamIndex: 3, ptsSeconds: Double(index), durationSeconds: 1, payload: payload(index))
+        }
+        let elapsed = ContinuousClock.now - started
+        #expect(store.frontier(streamIndex: 3) == 39_999)
+        #expect(store.entries(streamIndex: 3, from: 0, through: 1e9).count == 40_000)
+        #expect(elapsed < .seconds(2), "took \(elapsed)")
+    }
+
+    @Test("20k distinct packets on one timestamp stay linear and keep harvest order")
+    func samePTSBurstIsLinear() {
+        let store = SubtitlePacketStore()
+        let started = ContinuousClock.now
+        for index in 0..<20_000 {
+            store.append(streamIndex: 3, ptsSeconds: 10, durationSeconds: 1, payload: payload(index))
+        }
+        let elapsed = ContinuousClock.now - started
+        let stored = store.entries(streamIndex: 3, from: 10, through: 10)
+        #expect(stored.count == 20_000)
+        #expect(stored.map(\.payload) == (0..<20_000).map { payload($0) })
+        #expect(elapsed < .seconds(2), "took \(elapsed)")
+    }
+
+    @Test("a byte-identical packet re-harvested into a long same-PTS run collapses and takes the fresh sequence")
+    func duplicateInALongRunCollapses() {
+        let store = SubtitlePacketStore()
+        for index in 0..<50 {
+            store.append(streamIndex: 3, ptsSeconds: 10, durationSeconds: 1, payload: payload(index))
+        }
+        let before = store.entries(streamIndex: 3, from: 10, through: 10)
+        store.append(streamIndex: 3, ptsSeconds: 10, durationSeconds: 1, payload: payload(17))
+        let after = store.entries(streamIndex: 3, from: 10, through: 10)
+        #expect(after.count == 50)
+        #expect(after[17].payload == payload(17))
+        #expect(after[17].sequence > before.map(\.sequence).max()!)
+        store.append(streamIndex: 3, ptsSeconds: 10, durationSeconds: 1, payload: payload(50))
+        let grown = store.entries(streamIndex: 3, from: 10, through: 10)
+        #expect(grown.count == 51)
+        #expect(grown.last?.payload == payload(50))
+        store.append(streamIndex: 3, ptsSeconds: 10, durationSeconds: 1, payload: payload(50))
+        #expect(store.entries(streamIndex: 3, from: 10, through: 10).count == 51)
+    }
+
+    @Test("the duplicate check still finds a packet after eviction moved the run")
+    func duplicateSurvivesEviction() {
+        let store = SubtitlePacketStore(perStreamByteCap: 40 * 24, aggregateByteCap: 1 << 20)
+        for index in 0..<60 {
+            store.append(streamIndex: 3, ptsSeconds: 10, durationSeconds: 1, payload: payload(index))
+        }
+        let stored = store.entries(streamIndex: 3, from: 10, through: 10)
+        #expect(store.totalRetainedBytes <= 40 * 24)
+        #expect(stored.last?.payload == payload(59))
+        store.append(streamIndex: 3, ptsSeconds: 10, durationSeconds: 1, payload: payload(59))
+        #expect(store.entries(streamIndex: 3, from: 10, through: 10).count == stored.count)
+    }
+
+    @Test("the per-stream cap holds after every append and evicts oldest first")
+    func perStreamCapHolds() {
+        let store = SubtitlePacketStore(perStreamByteCap: 10_000, aggregateByteCap: 1 << 20)
+        for index in 0..<500 {
+            store.append(streamIndex: 4, ptsSeconds: Double(index), durationSeconds: 1, payload: payload(index, size: 100))
+            #expect(store.totalRetainedBytes <= 10_000)
+        }
+        let pts = store.entries(streamIndex: 4, from: 0, through: 1e9).map(\.ptsSeconds)
+        #expect(pts.last == 499)
+        #expect(pts == pts.sorted())
+        #expect(pts.count > 80)
+    }
+
+    @Test("aggregate eviction of a long cold stream is linear")
+    func aggregateEvictionIsLinear() {
+        let store = SubtitlePacketStore(perStreamByteCap: 1 << 30, aggregateByteCap: 40_000 * 24)
+        for index in 0..<40_000 {
+            store.append(streamIndex: 1, ptsSeconds: Double(index), durationSeconds: 1, payload: payload(index))
+        }
+        let started = ContinuousClock.now
+        for index in 0..<40_000 {
+            store.append(streamIndex: 2, ptsSeconds: Double(index), durationSeconds: 1, payload: payload(index))
+        }
+        let elapsed = ContinuousClock.now - started
+        #expect(store.totalRetainedBytes <= 40_000 * 24)
+        #expect(store.frontier(streamIndex: 2) == 39_999)
+        #expect(elapsed < .seconds(2), "took \(elapsed)")
+    }
+
+    @Test("a window read is found by search and matches the filter it replaced")
+    func windowReadMatchesAFilter() {
+        let store = SubtitlePacketStore()
+        for index in 0..<200 {
+            store.append(streamIndex: 3, ptsSeconds: Double(index / 2), durationSeconds: 1, payload: payload(index))
+        }
+        for (from, through) in [(0.0, 0.0), (10.0, 20.0), (-5.0, 3.0), (99.0, 500.0), (50.5, 50.9), (20.0, 10.0)] {
+            let got = store.entries(streamIndex: 3, from: from, through: through).map(\.payload)
+            let expected = (0..<200).filter { Double($0 / 2) >= from && Double($0 / 2) <= through }.map { payload($0) }
+            #expect(got == expected, "window \(from)...\(through)")
+        }
+        #expect(store.firstPTS(streamIndex: 3, after: 10) == 11)
+        #expect(store.firstPTS(streamIndex: 3, after: 99) == nil)
+    }
+
+    // MARK: - SUB-111 part 2: display sets in assembly count toward the aggregate cap
+
+    private func pgsSegment(_ type: UInt8, bodyLen: Int) -> Data {
+        var data = Data([type, UInt8((bodyLen >> 8) & 0xFF), UInt8(bodyLen & 0xFF)])
+        data.append(Data(repeating: type, count: bodyLen))
+        return data
+    }
+
+    @Test("END-less display sets on many streams do not escape the aggregate cap")
+    func pendingSetsCountTowardTheAggregateCap() {
+        let cap = 64 * 1024
+        let store = SubtitlePacketStore(perStreamByteCap: cap, aggregateByteCap: cap)
+        let streams = 100
+        for stream in 0..<streams {
+            for chunk in [pgsSegment(0x16, bodyLen: 11), pgsSegment(0x15, bodyLen: 2_000)] {
+                store.harvestChunk(streamIndex: Int32(stream), ptsSeconds: chunk[0] == 0x16 ? 10 : nil,
+                                   durationSeconds: 0, flags: 0, payload: chunk, assembleSplitDisplaySets: true)
+            }
+            #expect(store.totalRetainedBytes <= cap)
+        }
+        var completed = 0
+        for stream in 0..<streams {
+            store.harvestChunk(streamIndex: Int32(stream), ptsSeconds: nil, durationSeconds: 0, flags: 0,
+                               payload: pgsSegment(0x80, bodyLen: 0), assembleSplitDisplaySets: true)
+            if !store.entries(streamIndex: Int32(stream), from: 0, through: 100).isEmpty { completed += 1 }
+        }
+        #expect(completed > 0)
+        #expect(completed < streams)
+        #expect(store.totalRetainedBytes <= cap)
+    }
+
+    @Test("a display set in assembly on a protected stream survives the pressure and completes")
+    func protectedPendingSetSurvives() {
+        let cap = 64 * 1024
+        let store = SubtitlePacketStore(perStreamByteCap: cap, aggregateByteCap: cap)
+        store.setProtectedStreams([7])
+        store.harvestChunk(streamIndex: 7, ptsSeconds: 10, durationSeconds: 0, flags: 0,
+                           payload: pgsSegment(0x16, bodyLen: 11), assembleSplitDisplaySets: true)
+        for stream in 100..<160 {
+            for chunk in [pgsSegment(0x16, bodyLen: 11), pgsSegment(0x15, bodyLen: 2_000)] {
+                store.harvestChunk(streamIndex: Int32(stream), ptsSeconds: chunk[0] == 0x16 ? 10 : nil,
+                                   durationSeconds: 0, flags: 0, payload: chunk, assembleSplitDisplaySets: true)
+            }
+        }
+        store.harvestChunk(streamIndex: 7, ptsSeconds: nil, durationSeconds: 0, flags: 0,
+                           payload: pgsSegment(0x80, bodyLen: 0), assembleSplitDisplaySets: true)
+        #expect(store.entries(streamIndex: 7, from: 0, through: 100).count == 1)
+    }
+
+    @Test("clear forgets the assembly bytes too")
+    func clearResetsThePendingAccounting() {
+        let store = SubtitlePacketStore()
+        store.harvestChunk(streamIndex: 7, ptsSeconds: 10, durationSeconds: 0, flags: 0,
+                           payload: pgsSegment(0x16, bodyLen: 500), assembleSplitDisplaySets: true)
+        #expect(store.totalRetainedBytes > 0)
+        store.clear()
+        #expect(store.totalRetainedBytes == 0)
+    }
+}

From f0dfd33279b13983dd107f5786a20c3583e684cb Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 09:03:26 +0200
Subject: [PATCH 204/359] docs(recording): a stop inside a failing teardown
 reports the failure, an overtaken start is cancelled (audit FEA-105, FEA-106)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 docs/api.md | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/docs/api.md b/docs/api.md
index 0156678a0..e070648a8 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -843,7 +843,11 @@ way with `.ended(.sessionEnded)`; a recording never outlives its session.
 
 `.ended` is published once the file is closed. The queued tail and the trailer are written off the
 main actor, so it can arrive a moment after the call that ended the recording; `stopRecording()`
-returns only after it, and a `startRecording(to:)` issued in that moment waits for it first.
+returns only after it, and a `startRecording(to:)` issued in that moment waits for it first. If a
+`stopRecording()` or a new `load()` overtakes that wait, the start throws `CancellationError` and
+records nothing. A stop that lands while the writer is already tearing itself down after a failure
+(`.writeTooSlow`, `.diskFull`, `.writeFailed`) waits for that teardown and publishes the failure, not
+`.ended`.
 
 **Not implemented: recording from the start of what is already buffered.** A recording begins at the
 call, not at the back of the DVR window. On `.loopback` what is retained is remuxed fMP4 with

From 6ba2b0c2a0d8ae73356a806d8f46df44b21c9793 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 09:06:16 +0200
Subject: [PATCH 205/359] perf(renderer): hold one frame for presentation-order
 decoders and guard against late frames (audit PERF-104)

The software renderer held four frames for every decoder, but only the
VideoToolbox HEVC decoder (temporal processing) emits B-frames out of
presentation order (19479fc5, -12080 from the layer). libavcodec and dav1d
emit presentation order, so three of the four held frames were dead weight:
75 MB of IOSurface at 4K P010 (24.9 MB per frame by CVPixelBufferGetDataSize).

The depth is now set by the host when it picks the decoder: 4 for
HardwareVideoDecoder, 1 for SoftwareVideoDecoder (1 and not 0, because #407
reads each frame's duration off its held successor). A renderer nobody
configures keeps 4. A frame that arrives after a later one was handed over
is dropped instead of reaching the layer out of order, counted in
lostBeforeLayer, and raises the depth to 4 for the rest of the renderer's
life (logged once), which covers an HEVC SPS that understates its reorder
and demuxer-derived PTS.

Verified on the harness with the SW path: H.264 (libavcodec), AV1 (dav1d)
and VP9 play to EOF with lost=0, and VT HEVC stays on depth 4 with lost=0.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../Native/SoftwarePlaybackHost.swift         |   5 +-
 .../Renderer/SampleBufferRenderer.swift       |  65 ++++++-
 .../SoftwareRendererReorderDepthTests.swift   | 171 ++++++++++++++++++
 3 files changed, 235 insertions(+), 6 deletions(-)
 create mode 100644 Tests/AetherEngineTests/SoftwareRendererReorderDepthTests.swift

diff --git a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
index c0bb9e941..0820ed5df 100644
--- a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
+++ b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
@@ -841,6 +841,9 @@ final class SoftwarePlaybackHost {
             )
         }
 
+        // Audit PERF-104: only the VideoToolbox decoder emits out of presentation order.
+        renderer.setReorderDepth(SampleBufferRenderer.reorderDepth(forHardwareDecoder: videoDecoder is HardwareVideoDecoder))
+
         // Flip display layer into HDR mode before frames arrive; without this preferredDynamicRange stays .standard and PQ/HLG renders desaturated.
         if let codecpar = vStream.pointee.codecpar {
             let trc = codecpar.pointee.color_trc
@@ -867,7 +870,7 @@ final class SoftwarePlaybackHost {
             if self.bumpFramesEnqueued() == 0 {
                 self.noteFirstFrameEnqueuedForDisplayFallback()
                 if self.takePausedBeforeFirstFrame() {
-                    // The reorder buffer holds four frames before it hands one to the layer, and the
+                    // The reorder buffer holds frames before it hands one to the layer, and the
                     // loops park again from here: without the drain the frame never leaves it.
                     self.renderer.drainReorderBuffer()
                     self.presentFirstFrameUnderPause(pts: pts.seconds, generation: self.decodeGeneration)
diff --git a/Sources/AetherEngine/Renderer/SampleBufferRenderer.swift b/Sources/AetherEngine/Renderer/SampleBufferRenderer.swift
index bdcab9e52..16aa16eac 100644
--- a/Sources/AetherEngine/Renderer/SampleBufferRenderer.swift
+++ b/Sources/AetherEngine/Renderer/SampleBufferRenderer.swift
@@ -5,8 +5,8 @@ import CoreVideo
 
 /// Video renderer using AVSampleBufferDisplayLayer for optimal frame pacing.
 ///
-/// Includes a small reorder buffer (4 frames) to handle B-frame decode
-/// order from VTDecompressionSession. Frames are sorted by PTS before
+/// Includes a small reorder buffer to handle B-frame decode order from VTDecompressionSession
+/// (4 frames, see `reorderDepth(forHardwareDecoder:)`). Frames are sorted by PTS before
 /// being enqueued to the display layer in strict presentation order.
 final class SampleBufferRenderer: @unchecked Sendable {
 
@@ -27,10 +27,39 @@ final class SampleBufferRenderer: @unchecked Sendable {
     /// window renders only this layer, the host overlay cannot reach it).
     let subtitleCompositor = SubtitleFrameCompositor()
 
-    /// B-frame reorder buffer (4 frames): collects decoder output, flushes to display layer in ascending PTS order. Third tuple slot carries per-frame HDR10+ T.35 SEI bytes, paired through the reorder to kCMSampleAttachmentKey_HDR10PlusPerFrameData.
+    /// B-frame reorder buffer: collects decoder output, flushes to display layer in ascending PTS order. Third tuple slot carries per-frame HDR10+ T.35 SEI bytes, paired through the reorder to kCMSampleAttachmentKey_HDR10PlusPerFrameData.
     private let reorderLock = NSLock()
     private var reorderBuffer: [(CVPixelBuffer, CMTime, Data?)] = []
-    private let reorderDepth = 4  // handles up to 3 consecutive B-frames
+
+    /// Audit PERF-104: VideoToolbox HEVC with temporal processing emits B-frames out of presentation
+    /// order (19479fc5, -12080 from the layer), so its renderer holds 4 frames, enough for 3
+    /// consecutive B-frames. libavcodec and dav1d emit presentation order, and 3 held frames are 75 MB
+    /// of IOSurface at 4K P010 for nothing. One frame stays held either way: #407 reads each frame's
+    /// duration off its held successor.
+    static let hardwareDecoderReorderDepth = 4
+    static let presentationOrderReorderDepth = 1
+    static func reorderDepth(forHardwareDecoder hardware: Bool) -> Int {
+        hardware ? hardwareDecoderReorderDepth : presentationOrderReorderDepth
+    }
+
+    /// Guarded by `reorderLock`. Starts at the hardware depth, so a renderer nobody configured keeps the
+    /// behaviour it always had.
+    private var reorderDepth = SampleBufferRenderer.hardwareDecoderReorderDepth
+
+    /// Set once by the host when it picks the decoder; a depth below the current one takes effect on
+    /// the next enqueue, which hands the surplus over in order.
+    func setReorderDepth(_ depth: Int) {
+        reorderLock.lock()
+        reorderDepth = max(1, min(depth, Self.hardwareDecoderReorderDepth))
+        reorderLock.unlock()
+    }
+
+    /// Frames waiting for a smaller presentation time. Diagnostics and tests.
+    var heldFrameCount: Int {
+        reorderLock.lock()
+        defer { reorderLock.unlock() }
+        return reorderBuffer.count
+    }
 
     /// Drop frames before this PTS after a seek (prevents keyframe-to-target fast-forward). Cleared after the first passing frame.
     private var skipUntilPTS: CMTime?
@@ -99,6 +128,18 @@ final class SampleBufferRenderer: @unchecked Sendable {
     private var _minHandedDeltaSeconds = Double.infinity
     private var _maxHandedDeltaSeconds = -Double.infinity
 
+    /// Audit PERF-104: frames that arrived after a later one had already been handed over, so they can
+    /// no longer be enqueued in presentation order. Dropped rather than enqueued out of order, and the
+    /// first one raises the depth to the hardware decoder's for the rest of this renderer's life, which
+    /// covers an HEVC stream whose SPS understates its reorder and PTS derived by the demuxer.
+    /// Guarded by `reorderLock`.
+    private var _outOfOrderFramesDropped = 0
+    var outOfOrderFramesDropped: Int {
+        reorderLock.lock()
+        defer { reorderLock.unlock() }
+        return _outOfOrderFramesDropped
+    }
+
     /// #298: frames refused at the enqueue gate for carrying an unschedulable PTS. Guarded by `reorderLock`.
     private var _untimedFramesDropped = 0
     var untimedFramesDropped: Int {
@@ -196,7 +237,7 @@ final class SampleBufferRenderer: @unchecked Sendable {
         _minHandedDeltaSeconds = .infinity
         _maxHandedDeltaSeconds = -.infinity
         return Cadence(handedOver: enqueueCount,
-                       lostBeforeLayer: _untimedFramesDropped + _sampleBuildFailures,
+                       lostBeforeLayer: _untimedFramesDropped + _sampleBuildFailures + _outOfOrderFramesDropped,
                        minDeltaSeconds: minD, maxDeltaSeconds: maxD)
     }
 
@@ -314,6 +355,20 @@ final class SampleBufferRenderer: @unchecked Sendable {
         }
 
         let ptsSeconds = CMTimeGetSeconds(pts)
+        if let handed = _lastHandedPtsSeconds, ptsSeconds < handed {
+            _outOfOrderFramesDropped += 1
+            let dropped = _outOfOrderFramesDropped
+            let raised = reorderDepth < Self.hardwareDecoderReorderDepth
+            reorderDepth = Self.hardwareDecoderReorderDepth
+            reorderLock.unlock()
+            if dropped == 1 {
+                EngineLog.emit(
+                    "[Renderer] frame at \(String(format: "%.3f", ptsSeconds))s arrived after \(String(format: "%.3f", handed))s "
+                    + "was handed over; dropped, reorder depth \(raised ? "raised to \(Self.hardwareDecoderReorderDepth)" : "already \(Self.hardwareDecoderReorderDepth)")",
+                    category: .swPlayback)
+            }
+            return
+        }
         // #303: the frontier is the newest timestamp HELD, not the newest handed over. A B-frame run
         // arrives out of order, so taking the last call's timestamp would report a cushion that
         // shrinks and grows with the coding pattern rather than with the buffer.
diff --git a/Tests/AetherEngineTests/SoftwareRendererReorderDepthTests.swift b/Tests/AetherEngineTests/SoftwareRendererReorderDepthTests.swift
new file mode 100644
index 000000000..fe24745eb
--- /dev/null
+++ b/Tests/AetherEngineTests/SoftwareRendererReorderDepthTests.swift
@@ -0,0 +1,171 @@
+import Foundation
+import Testing
+import AVFoundation
+import CoreMedia
+import CoreVideo
+@testable import AetherEngine
+
+/// Audit PERF-104: the software renderer held four frames for every decoder, which is 75 MB of
+/// IOSurface at 4K P010 that libavcodec and dav1d (presentation order) never needed. Only the
+/// VideoToolbox HEVC decoder emits B-frames out of order. The depth follows the decoder, and a frame
+/// that arrives after a later one was handed over is dropped and raises the depth instead of reaching
+/// the layer out of order.
+@Suite("Software renderer reorder depth")
+struct SoftwareRendererReorderDepthTests {
+
+    private final class Handed: @unchecked Sendable {
+        private let lock = NSLock()
+        private var storage: [Double] = []
+        var seconds: [Double] { lock.lock(); defer { lock.unlock() }; return storage }
+        func append(_ t: SoftwareVideoFrameTime) { lock.lock(); storage.append(t.presentation.seconds); lock.unlock() }
+    }
+
+    private static func makePixelBuffer(width: Int = 16, height: Int = 16,
+                                        format: OSType = kCVPixelFormatType_32BGRA) -> CVPixelBuffer {
+        var pb: CVPixelBuffer?
+        CVPixelBufferCreate(kCFAllocatorDefault, width, height, format,
+                            [kCVPixelBufferIOSurfacePropertiesKey: [:]] as CFDictionary, &pb)
+        return pb!
+    }
+
+    private static func time(_ ticks: Int) -> CMTime { CMTime(value: Int64(ticks), timescale: 1000) }
+
+    @MainActor
+    private func feed(_ renderer: SampleBufferRenderer, _ ticks: [Int], drain: Bool = true) -> Handed {
+        let handed = Handed()
+        renderer.setFrameEnqueuedObserver { handed.append($0) }
+        let pixels = Self.makePixelBuffer()
+        for t in ticks { renderer.enqueue(pixelBuffer: pixels, pts: Self.time(t)) }
+        if drain { renderer.drainReorderBuffer() }
+        return handed
+    }
+
+    @Test("The depth follows the decoder: VideoToolbox keeps four, the presentation-order decoders hold one")
+    func depthPerDecoder() {
+        #expect(SampleBufferRenderer.reorderDepth(forHardwareDecoder: true) == 4)
+        #expect(SampleBufferRenderer.reorderDepth(forHardwareDecoder: false) == 1)
+    }
+
+    @Test("In-order input at depth one is handed over with one frame of latency")
+    @MainActor
+    func inOrderInputHoldsOneFrame() {
+        let renderer = SampleBufferRenderer()
+        renderer.setReorderDepth(SampleBufferRenderer.reorderDepth(forHardwareDecoder: false))
+        let handed = Handed()
+        renderer.setFrameEnqueuedObserver { handed.append($0) }
+        let pixels = Self.makePixelBuffer()
+        for (i, t) in stride(from: 0, to: 400, by: 40).enumerated() {
+            renderer.enqueue(pixelBuffer: pixels, pts: Self.time(t))
+            #expect(handed.seconds.count == i, "frame \(i) waits for its successor and nothing more")
+            #expect(renderer.heldFrameCount == min(i + 1, 1))
+        }
+        renderer.drainReorderBuffer()
+        #expect(handed.seconds == stride(from: 0, to: 400, by: 40).map { Double($0) / 1000 })
+        #expect(renderer.outOfOrderFramesDropped == 0)
+    }
+
+    @Test("A renderer nobody configured keeps holding four frames and sorts a B pyramid")
+    @MainActor
+    func defaultDepthStillSortsABPyramid() {
+        let renderer = SampleBufferRenderer()
+        // Decode order I0 P4 B2 b1 b3, two pyramids.
+        let handed = feed(renderer, [0, 160, 80, 40, 120, 320, 240, 200, 280])
+        #expect(handed.seconds == [0, 40, 80, 120, 160, 200, 240, 280, 320].map { Double($0) / 1000 })
+        #expect(renderer.outOfOrderFramesDropped == 0)
+    }
+
+    @Test("A VideoToolbox-configured renderer sorts a three deep B pyramid")
+    @MainActor
+    func hardwareDepthSortsAThreeDeepPyramid() {
+        let renderer = SampleBufferRenderer()
+        renderer.setReorderDepth(SampleBufferRenderer.reorderDepth(forHardwareDecoder: true))
+        // Decode order: I0 P4 B2 b1 b3, each gap one frame.
+        let handed = feed(renderer, [0, 4, 2, 1, 3, 8, 6, 5, 7].map { $0 * 40 })
+        #expect(handed.seconds == (0...8).map { Double($0 * 40) / 1000 })
+        #expect(renderer.outOfOrderFramesDropped == 0)
+    }
+
+    @Test("At depth one one local inversion is still sorted")
+    @MainActor
+    func depthOneSortsASingleInversion() {
+        let renderer = SampleBufferRenderer()
+        renderer.setReorderDepth(1)
+        let handed = feed(renderer, [30, 10, 20])
+        #expect(handed.seconds == [0.010, 0.020, 0.030])
+        #expect(renderer.outOfOrderFramesDropped == 0)
+    }
+
+    @Test("A frame behind one already handed over is dropped once, counted, and raises the depth")
+    @MainActor
+    func outOfOrderFrameIsDroppedAndDepthRises() {
+        let renderer = SampleBufferRenderer()
+        renderer.setReorderDepth(1)
+        let handed = Handed()
+        renderer.setFrameEnqueuedObserver { handed.append($0) }
+        let pixels = Self.makePixelBuffer()
+        // 0 4 2 1 3 at depth one: 0 and 2 are handed over, 1 then arrives behind 2.
+        for t in [0, 4, 2, 1, 3] { renderer.enqueue(pixelBuffer: pixels, pts: Self.time(t * 40)) }
+        #expect(renderer.outOfOrderFramesDropped == 1)
+        #expect(renderer.takeCadence().lostBeforeLayer == 1)
+        renderer.drainReorderBuffer()
+        #expect(handed.seconds == [0, 0.080, 0.120, 0.160], "the late frame never reached the layer")
+
+        // The depth is now the hardware one: the same shape is sorted rather than dropped.
+        for t in [10, 14, 12, 11, 13].map({ $0 * 40 }) { renderer.enqueue(pixelBuffer: pixels, pts: Self.time(t)) }
+        renderer.drainReorderBuffer()
+        #expect(handed.seconds.suffix(5) == [0.400, 0.440, 0.480, 0.520, 0.560])
+        #expect(renderer.outOfOrderFramesDropped == 1)
+        #expect(zip(handed.seconds, handed.seconds.dropFirst()).allSatisfy { $0 <= $1 },
+                "everything the layer was handed is in ascending order")
+    }
+
+    @Test("The guard also keeps an out of order frame off the layer at the hardware depth")
+    @MainActor
+    func guardAppliesAtTheHardwareDepthToo() {
+        let renderer = SampleBufferRenderer()
+        let handed = Handed()
+        renderer.setFrameEnqueuedObserver { handed.append($0) }
+        let pixels = Self.makePixelBuffer()
+        for t in [100, 200, 300, 400, 500, 600] { renderer.enqueue(pixelBuffer: pixels, pts: Self.time(t)) }
+        // 100 and 200 are out by now; 150 is five frames late.
+        renderer.enqueue(pixelBuffer: pixels, pts: Self.time(150))
+        renderer.drainReorderBuffer()
+        #expect(renderer.outOfOrderFramesDropped == 1)
+        #expect(handed.seconds == [0.100, 0.200, 0.300, 0.400, 0.500, 0.600])
+    }
+
+    @Test("A flush forgets what was handed over, so a seek backwards is not out of order")
+    @MainActor
+    func flushResetsTheGuard() {
+        let renderer = SampleBufferRenderer()
+        renderer.setReorderDepth(1)
+        let pixels = Self.makePixelBuffer()
+        for t in [5000, 5040, 5080] { renderer.enqueue(pixelBuffer: pixels, pts: Self.time(t)) }
+        renderer.flush(removingDisplayedImage: false)
+        for t in [1000, 1040, 1080] { renderer.enqueue(pixelBuffer: pixels, pts: Self.time(t)) }
+        renderer.drainReorderBuffer()
+        #expect(renderer.outOfOrderFramesDropped == 0)
+    }
+
+    @Test("Three fewer held frames at 4K P010 is 75 MB of IOSurface")
+    @MainActor
+    func heldMemoryAtFourK() throws {
+        let frame = Self.makePixelBuffer(width: 3840, height: 2160,
+                                         format: kCVPixelFormatType_420YpCbCr10BiPlanarVideoRange)
+        let bytes = CVPixelBufferGetDataSize(frame)
+        #expect(bytes > 24_000_000, "a 4K P010 frame is ~25 MB")
+
+        func steadyStateHeld(depth: Int) -> Int {
+            let renderer = SampleBufferRenderer()
+            renderer.setReorderDepth(depth)
+            let small = Self.makePixelBuffer()
+            for i in 0..<12 { renderer.enqueue(pixelBuffer: small, pts: Self.time(i * 40)) }
+            return renderer.heldFrameCount
+        }
+        let before = steadyStateHeld(depth: SampleBufferRenderer.reorderDepth(forHardwareDecoder: true))
+        let after = steadyStateHeld(depth: SampleBufferRenderer.reorderDepth(forHardwareDecoder: false))
+        #expect(before == 4)
+        #expect(after == 1)
+        #expect((before - after) * bytes > 70_000_000)
+    }
+}

From 6c4d87321595a7ed3effe60a7c5270d66befe006 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 09:13:15 +0200
Subject: [PATCH 206/359] fix(io): the remote disc reader judges a range answer
 at the response head (audit NET-102)

`HTTPDiscIOReader.rangeGet` used a completion handler, so URLSession buffered
the whole body before the 206 and Content-Range checks ran. A remote image on
an origin that ignored Range (or answered `bytes N-EOF`) was streamed into
memory for up to 35 s per attempt, on every open of the URL.

The fetch now goes through a task delegate that classifies the head with the
shared `AVIOReader.rangeAnswer`: a 200, a misplaced 206 and any refusal are
hung up on before a body byte is taken, a 206 wider than asked is cut where
the range ends (the DMX-1 rule), and what is kept is capped at the range. A
body that ends on the range end is left to finish, so the keep-alive
connection is reused. `HTTPDiscIOReader.open` throws the new
`AVIOReaderError.originIgnoresRange` for an origin that answers the probe
with a 200, where `init?` keeps returning nil, and `Demuxer.openHTTP` uses it
so a remote disc image on such an origin fails with its cause instead of
falling through to a reader that cannot probe it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 Sources/AetherEngine/Demuxer/AVIOReader.swift |   7 +
 Sources/AetherEngine/Demuxer/Demuxer.swift    |   2 +-
 .../AetherEngine/IO/HTTPDiscIOReader.swift    | 218 +++++++++++++-----
 .../DiscReaderRangeAnswerTests.swift          | 111 +++++++++
 docs/formats.md                               |   2 +
 5 files changed, 284 insertions(+), 56 deletions(-)
 create mode 100644 Tests/AetherEngineTests/DiscReaderRangeAnswerTests.swift

diff --git a/Sources/AetherEngine/Demuxer/AVIOReader.swift b/Sources/AetherEngine/Demuxer/AVIOReader.swift
index e79ef5c2b..93bfde316 100644
--- a/Sources/AetherEngine/Demuxer/AVIOReader.swift
+++ b/Sources/AetherEngine/Demuxer/AVIOReader.swift
@@ -5237,6 +5237,11 @@ enum AVIOReaderError: Error, Equatable, CustomStringConvertible, LocalizedError
     /// the same reason `httpStatus` is: without it the open surfaces FFmpeg's invalid data and a
     /// self-signed origin reads as a corrupt file.
     case transportSecurityFailed(code: Int)
+    /// Audit NET-102: a remote disc image on an origin that answers a range request with the whole
+    /// source (a 200). A disc image is a filesystem, which no reader can walk forward-only, so this
+    /// fails at the first response head. A plain media URL on such an origin plays forward-only
+    /// instead (audit DMX-101).
+    case originIgnoresRange
 
     var description: String {
         switch self {
@@ -5248,6 +5253,8 @@ enum AVIOReaderError: Error, Equatable, CustomStringConvertible, LocalizedError
         case .httpStatus(let status): return "Origin answered HTTP \(status) for the source"
         case .transportSecurityFailed(let code):
             return TransportSecurityFailure.sentence(for: code)
+        case .originIgnoresRange:
+            return "The origin ignores HTTP Range requests, which a remote disc image needs"
         }
     }
 
diff --git a/Sources/AetherEngine/Demuxer/Demuxer.swift b/Sources/AetherEngine/Demuxer/Demuxer.swift
index 867bbb73c..6068e085f 100644
--- a/Sources/AetherEngine/Demuxer/Demuxer.swift
+++ b/Sources/AetherEngine/Demuxer/Demuxer.swift
@@ -599,7 +599,7 @@ public final class Demuxer: @unchecked Sendable {
         // the source is not a recognizable disc, fall through to the streaming reader.
         if !isLive, Self.isDiscImageURL(url) {
             let warm = HTTPDiscIOReader.takePrewarm(for: url, extraHeaders: extraHeaders)
-            if let discReader = HTTPDiscIOReader(url: url, extraHeaders: extraHeaders, prewarmed: warm) {
+            if let discReader = try HTTPDiscIOReader.open(url: url, extraHeaders: extraHeaders, prewarmed: warm) {
                 if let discInfo = try DiscReader.wrap(discReader, selectTitleID: selectTitleID, cacheKey: url.absoluteString) {
                     adoptDiscInfo(discInfo)
                     auditSource = nil
diff --git a/Sources/AetherEngine/IO/HTTPDiscIOReader.swift b/Sources/AetherEngine/IO/HTTPDiscIOReader.swift
index 12a2df881..e6dfab66e 100644
--- a/Sources/AetherEngine/IO/HTTPDiscIOReader.swift
+++ b/Sources/AetherEngine/IO/HTTPDiscIOReader.swift
@@ -13,7 +13,8 @@ import Foundation
 /// playback of the title's extents costs few requests); any non-contiguous read resets it. Each
 /// range request retries with backoff so a transient network blip does not end playback. The server
 /// MUST honor range requests (any static file host does); if it does not, `init` returns nil after a
-/// clear log and the caller falls back to the plain streaming path.
+/// clear log and `open` throws `AVIOReaderError.originIgnoresRange`, and the response is hung up on at
+/// its head, so a 40 GB image answered with a 200 is never downloaded to be rejected (audit NET-102).
 ///
 /// A source the host warmed with `AetherEngine.prewarm` (#551) is read out of those bytes first
 /// (#647): the warm has already stated the size and proven range support, so the reader neither
@@ -47,7 +48,7 @@ final class HTTPDiscIOReader: IOReader, @unchecked Sendable {
 
     /// Probes total size and range support with one (retried) `bytes=0-0` request, unless
     /// `prewarmed` has already stated both. Returns nil if the source is unreachable or answers `200`
-    /// (full body, no range support); logs which.
+    /// (full body, no range support); logs which. `open` tells the two apart.
     convenience init?(url: URL,
                       extraHeaders: [String: String] = [:],
                       baseChunkSize: Int = 256 * 1024,
@@ -56,24 +57,59 @@ final class HTTPDiscIOReader: IOReader, @unchecked Sendable {
                       requestTimeout: TimeInterval = 30,
                       sessionConfiguration: URLSessionConfiguration? = nil,
                       prewarmed: PrewarmedSource? = nil) {
+        let session = Self.makeSession(sessionConfiguration)
+        guard case .size(let size) = Self.resolveSize(
+            url: url, extraHeaders: extraHeaders, session: session, requestTimeout: requestTimeout,
+            maxRetries: maxRetries, knownSize: prewarmed?.contentLength) else {
+            session.invalidateAndCancel()
+            return nil
+        }
         self.init(url: url, extraHeaders: extraHeaders, baseChunkSize: baseChunkSize,
                   maxChunkSize: maxChunkSize, maxRetries: maxRetries, requestTimeout: requestTimeout,
-                  sessionConfiguration: sessionConfiguration,
-                  knownSize: prewarmed?.contentLength,
+                  session: session, totalSize: size,
                   residentSpans: prewarmed.map { [$0.head] + ($0.tail.map { [$0] } ?? []) } ?? [])
     }
 
-    /// `knownSize` skips the range probe. Only a source that has already answered a range request
-    /// with its total may pass it: the warm, or the reader a fork is made from.
-    private init?(url: URL,
-                  extraHeaders: [String: String],
-                  baseChunkSize: Int,
-                  maxChunkSize: Int,
-                  maxRetries: Int,
-                  requestTimeout: TimeInterval,
-                  sessionConfiguration: URLSessionConfiguration?,
-                  knownSize: Int64?,
-                  residentSpans: [ResidentSpan]) {
+    /// `init?` for a caller that has to say why a disc image cannot be read: an origin that answers the
+    /// range probe with a 200 cannot address bytes, which is a different failure from an unreachable
+    /// one, and a disc image is a filesystem that no reader can walk without ranges (audit NET-102).
+    /// nil still means unreachable, and the caller falls back to the plain streaming path.
+    static func open(url: URL,
+                     extraHeaders: [String: String] = [:],
+                     baseChunkSize: Int = 256 * 1024,
+                     maxChunkSize: Int = 8 * 1024 * 1024,
+                     maxRetries: Int = 3,
+                     requestTimeout: TimeInterval = 30,
+                     sessionConfiguration: URLSessionConfiguration? = nil,
+                     prewarmed: PrewarmedSource? = nil) throws -> HTTPDiscIOReader? {
+        let session = makeSession(sessionConfiguration)
+        switch resolveSize(url: url, extraHeaders: extraHeaders, session: session,
+                           requestTimeout: requestTimeout, maxRetries: maxRetries,
+                           knownSize: prewarmed?.contentLength) {
+        case .size(let size):
+            return HTTPDiscIOReader(
+                url: url, extraHeaders: extraHeaders, baseChunkSize: baseChunkSize,
+                maxChunkSize: maxChunkSize, maxRetries: maxRetries, requestTimeout: requestTimeout,
+                session: session, totalSize: size,
+                residentSpans: prewarmed.map { [$0.head] + ($0.tail.map { [$0] } ?? []) } ?? [])
+        case .ignoresRange:
+            session.invalidateAndCancel()
+            throw AVIOReaderError.originIgnoresRange
+        case .unreachable:
+            session.invalidateAndCancel()
+            return nil
+        }
+    }
+
+    private init(url: URL,
+                 extraHeaders: [String: String],
+                 baseChunkSize: Int,
+                 maxChunkSize: Int,
+                 maxRetries: Int,
+                 requestTimeout: TimeInterval,
+                 session: URLSession,
+                 totalSize: Int64,
+                 residentSpans: [ResidentSpan]) {
         self.url = url
         self.extraHeaders = extraHeaders
         self.baseChunkSize = max(64 * 1024, baseChunkSize)
@@ -81,27 +117,28 @@ final class HTTPDiscIOReader: IOReader, @unchecked Sendable {
         self.currentChunkSize = max(64 * 1024, baseChunkSize)
         self.maxRetries = max(0, maxRetries)
         self.requestTimeout = requestTimeout
+        self.session = session
+        self.residentSpans = residentSpans.filter { !$0.isEmpty }
+        self.totalSize = totalSize
+    }
+
+    private static func makeSession(_ sessionConfiguration: URLSessionConfiguration?) -> URLSession {
         let config = sessionConfiguration ?? {
             let c = URLSessionConfiguration.ephemeral
             c.requestCachePolicy = .reloadIgnoringLocalCacheData
             return c
         }()
-        self.session = URLSession(
-            configuration: config, delegate: EngineTLS.sessionDelegate, delegateQueue: nil)
-        self.residentSpans = residentSpans.filter { !$0.isEmpty }
+        return URLSession(configuration: config, delegate: EngineTLS.sessionDelegate, delegateQueue: nil)
+    }
 
-        if let knownSize, knownSize > 0 {
-            self.totalSize = knownSize
-            return
-        }
-        guard let size = Self.probeSize(
-            url: url, extraHeaders: extraHeaders, session: session,
-            timeout: requestTimeout, maxRetries: max(0, maxRetries)
-        ), size > 0 else {
-            session.invalidateAndCancel()
-            return nil
-        }
-        self.totalSize = size
+    /// `knownSize` skips the range probe. Only a source that has already answered a range request
+    /// with its total may pass it: the warm, or the reader a fork is made from.
+    private static func resolveSize(url: URL, extraHeaders: [String: String], session: URLSession,
+                                    requestTimeout: TimeInterval, maxRetries: Int,
+                                    knownSize: Int64?) -> SizeProbe {
+        if let knownSize, knownSize > 0 { return .size(knownSize) }
+        return probeSize(url: url, extraHeaders: extraHeaders, session: session,
+                         timeout: requestTimeout, maxRetries: max(0, maxRetries))
     }
 
     /// #647: take what a host warmed for this URL, under the rule `AVIOReader` adopts by (#551).
@@ -230,8 +267,8 @@ final class HTTPDiscIOReader: IOReader, @unchecked Sendable {
         HTTPDiscIOReader(url: url, extraHeaders: extraHeaders,
                          baseChunkSize: baseChunkSize, maxChunkSize: maxChunkSize,
                          maxRetries: maxRetries, requestTimeout: requestTimeout,
-                         sessionConfiguration: nil,
-                         knownSize: totalSize, residentSpans: residentSpans)
+                         session: Self.makeSession(nil),
+                         totalSize: totalSize, residentSpans: residentSpans)
     }
 
     // MARK: - HTTP
@@ -261,23 +298,29 @@ final class HTTPDiscIOReader: IOReader, @unchecked Sendable {
         }
     }
 
+    private enum SizeProbe {
+        case size(Int64)
+        /// The origin answered the range probe with a 200 that is not the byte asked for.
+        case ignoresRange
+        case unreachable
+    }
+
     private static func probeSize(url: URL, extraHeaders: [String: String], session: URLSession,
-                                  timeout: TimeInterval, maxRetries: Int) -> Int64? {
+                                  timeout: TimeInterval, maxRetries: Int) -> SizeProbe {
         var attempt = 0
         while true {
             let r = rangeGet(url: url, extraHeaders: extraHeaders, session: session,
                              timeout: timeout, offset: 0, length: 1)
             if let r = r, r.status == 206, let cr = r.contentRange,
                let total = parseContentRangeTotal(cr) {
-                return total
+                return .size(total)
             }
             if let r = r, r.status == 200 {
                 EngineLog.emit(
-                    "[HTTPDiscIOReader] \(url.lastPathComponent): server answered 200 without a "
-                    + "Content-Range; remote disc images need HTTP byte-range support. "
-                    + "Falling back to the streaming path.",
+                    "[HTTPDiscIOReader] \(url.lastPathComponent): server answered 200 to a range "
+                    + "probe (hung up at the head); remote disc images need HTTP byte-range support.",
                     category: .demux)
-                return nil
+                return r.answer == .ignored ? .ignoresRange : .unreachable
             }
             attempt += 1
             if attempt > maxRetries {
@@ -286,14 +329,25 @@ final class HTTPDiscIOReader: IOReader, @unchecked Sendable {
                     + "\(attempt) attempt(s) (status=\(r.map { String($0.status) } ?? "no response")). "
                     + "Falling back to the streaming path.",
                     category: .demux)
-                return nil
+                return .unreachable
             }
             Thread.sleep(forTimeInterval: min(0.25 * Double(attempt), 1.0))
         }
     }
 
-    private struct RangeResponse { let status: Int; let contentRange: String?; let body: Data }
+    private struct RangeResponse {
+        let status: Int
+        let contentRange: String?
+        let body: Data
+        let answer: AVIOReader.RangeAnswer
+    }
 
+    /// Takes one range of the source. Only a 206 that starts where asked is taken at all, and what is
+    /// taken is capped at `length`: a 200 or a misplaced 206 is hung up on at its head, and a 206 that
+    /// runs past the range is cut where the range ends. The completion-handler form buffered the whole
+    /// body first, so an origin that ignored Range (or answered `bytes N-EOF`) put a disc image into
+    /// memory before the check ran (audit NET-102).
+    ///
     /// #243: the pull path runs this synchronously on FFmpeg's read callback, i.e. on a demux pump
     /// thread that lives for the whole session inside ONE dispatch block, so nothing ever drains
     /// that thread's autorelease pool. Every response bridged out of the completion handler is then
@@ -315,27 +369,22 @@ final class HTTPDiscIOReader: IOReader, @unchecked Sendable {
             req.setValue(rangeHeader(offset: offset, length: length), forHTTPHeaderField: "Range")
             for (k, v) in extraHeaders { req.setValue(v, forHTTPHeaderField: k) }
 
+            let delegate = RangeFetchDelegate(offset: offset, length: length)
             let sem = DispatchSemaphore(value: 0)
-            nonisolated(unsafe) var result: RangeResponse?
-            let task = session.dataTask(with: req) { data, response, _ in
-                if let http = response as? HTTPURLResponse {
-                    result = RangeResponse(
-                        status: http.statusCode,
-                        contentRange: http.value(forHTTPHeaderField: "Content-Range"),
-                        body: data ?? Data()
-                    )
-                }
-                sem.signal()
-            }
+            delegate.onCompletion = { sem.signal() }
+            let task = session.dataTask(with: req)
+            task.delegate = delegate
             task.resume()
             if sem.wait(timeout: .now() + timeout + 5) == .timedOut {
                 task.cancel()
                 return nil
             }
-            // The body escapes the pool inside a retained `Data`; the pool only balances the
-            // bridging autorelease, so the buffer still lives until `read` has copied it out.
-            Self.recordFetched(bytes: result?.body.count ?? 0)
-            return result
+            guard let http = delegate.response else { return nil }
+            let body = delegate.body
+            Self.recordFetched(bytes: body.count)
+            return RangeResponse(status: http.statusCode,
+                                 contentRange: http.value(forHTTPHeaderField: "Content-Range"),
+                                 body: body, answer: delegate.answer)
         }
     }
 
@@ -367,3 +416,62 @@ final class HTTPDiscIOReader: IOReader, @unchecked Sendable {
         fetchedLock.unlock()
     }
 }
+
+/// One range request's delivery. The decision is made at the response head, where nothing of the body
+/// has been taken yet, and the body is capped at the range that was asked for.
+private final class RangeFetchDelegate: NSObject, URLSessionDataDelegate, @unchecked Sendable {
+    private let offset: Int64
+    private let length: Int
+    private(set) var response: HTTPURLResponse?
+    private(set) var answer: AVIOReader.RangeAnswer = .unjudged
+    private(set) var body = Data()
+    var onCompletion: (() -> Void)?
+
+    init(offset: Int64, length: Int) {
+        self.offset = offset
+        self.length = length
+    }
+
+    func urlSession(
+        _ session: URLSession,
+        task: URLSessionTask,
+        didReceive challenge: URLAuthenticationChallenge,
+        completionHandler: @escaping (URLSession.AuthChallengeDisposition, URLCredential?) -> Void
+    ) {
+        EngineTLS.resolve(challenge, completionHandler: completionHandler)
+    }
+
+    func urlSession(
+        _ session: URLSession,
+        dataTask: URLSessionDataTask,
+        didReceive response: URLResponse,
+        completionHandler: @escaping (URLSession.ResponseDisposition) -> Void
+    ) {
+        guard let http = response as? HTTPURLResponse else {
+            completionHandler(.cancel)
+            return
+        }
+        self.response = http
+        answer = AVIOReader.rangeAnswer(
+            http, requestedStart: offset, requestedEnd: offset + Int64(length) - 1)
+        switch answer {
+        case .honoured, .overWide:
+            body.reserveCapacity(Int(max(0, min(http.expectedContentLength, Int64(length)))))
+            completionHandler(.allow)
+        case .ignored, .wholeFile, .misplaced, .unjudged:
+            completionHandler(.cancel)
+        }
+    }
+
+    func urlSession(_ session: URLSession, dataTask: URLSessionDataTask, didReceive data: Data) {
+        let room = length - body.count
+        if room > 0 { body.append(data.prefix(room)) }
+        // A body that ends on the range end is left to finish, which keeps the connection for the
+        // next range. Hanging up is for what runs past it.
+        if data.count > room || (answer == .overWide && body.count >= length) { dataTask.cancel() }
+    }
+
+    func urlSession(_ session: URLSession, task: URLSessionTask, didCompleteWithError error: Error?) {
+        onCompletion?()
+    }
+}
diff --git a/Tests/AetherEngineTests/DiscReaderRangeAnswerTests.swift b/Tests/AetherEngineTests/DiscReaderRangeAnswerTests.swift
new file mode 100644
index 000000000..877d2e800
--- /dev/null
+++ b/Tests/AetherEngineTests/DiscReaderRangeAnswerTests.swift
@@ -0,0 +1,111 @@
+import Testing
+import Foundation
+@testable import AetherEngine
+
+/// Audit NET-102: the remote disc reader checked a range answer only after URLSession had buffered
+/// the whole body, so an origin that ignored Range (or answered `bytes N-EOF`) put a 40 GB image
+/// into memory before the check could refuse it. The check now runs at the response head, and what
+/// is kept is capped at the range that was asked for.
+@Suite("Disc reader range answers")
+struct DiscReaderRangeAnswerTests {
+
+    private let total = Int64(512 * 1024 * 1024)
+
+    private final class FirstClaim: @unchecked Sendable {
+        private let lock = NSLock()
+        private var claimed = false
+        func take() -> Bool {
+            lock.lock()
+            defer { lock.unlock() }
+            if claimed { return false }
+            claimed = true
+            return true
+        }
+    }
+
+    private func url(_ server: ThrottledOriginServer, _ name: String = "movie.iso") -> URL {
+        URL(string: "http://127.0.0.1:\(server.port)/\(name)")!
+    }
+
+    private func read(_ reader: HTTPDiscIOReader, at offset: Int64, count: Int) -> [UInt8]? {
+        guard reader.seek(offset: offset, whence: SEEK_SET) == offset else { return nil }
+        var out = [UInt8](repeating: 0, count: count)
+        let n = out.withUnsafeMutableBufferPointer { reader.read($0.baseAddress, size: Int32(count)) }
+        return n == Int32(count) ? out : nil
+    }
+
+    @Test("an origin that answers the range probe with a 200 is hung up on at the head",
+          .timeLimit(.minutes(1)))
+    func plain200IsHungUpOn() throws {
+        let maybe = ThrottledOriginServer(totalSize: total, respond: { _, _, _ in .serve200 })
+        let server = try #require(maybe)
+        defer { server.stop() }
+
+        #expect(HTTPDiscIOReader(url: url(server)) == nil)
+        #expect(server.bytesWritten < 16 * 1024 * 1024,
+                "the origin wrote \(server.bytesWritten / 1024 / 1024) MB of a \(total / 1024 / 1024) MB body")
+    }
+
+    @Test("open names the origin that cannot address bytes", .timeLimit(.minutes(1)))
+    func openThrowsForAnOriginWithoutRanges() throws {
+        let maybe = ThrottledOriginServer(totalSize: total, respond: { _, _, _ in .serve200 })
+        let server = try #require(maybe)
+        defer { server.stop() }
+
+        #expect(throws: AVIOReaderError.originIgnoresRange) {
+            try HTTPDiscIOReader.open(url: url(server))
+        }
+    }
+
+    @Test("a remote disc image on such an origin fails the demuxer open with that cause",
+          .timeLimit(.minutes(1)))
+    func demuxerOpenFailsTyped() throws {
+        let maybe = ThrottledOriginServer(totalSize: total, respond: { _, _, _ in .serve200 })
+        let server = try #require(maybe)
+        defer { server.stop() }
+
+        let demuxer = Demuxer()
+        defer { demuxer.close() }
+        #expect(throws: AVIOReaderError.originIgnoresRange) {
+            try demuxer.open(url: url(server))
+        }
+        #expect(server.bytesWritten < 16 * 1024 * 1024)
+    }
+
+    @Test("a 206 that runs past the range is cut where the range ends", .timeLimit(.minutes(1)))
+    func overWide206IsCutAtTheRange() throws {
+        let maybe = ThrottledOriginServer(totalSize: total, ignoreRangeEnd: true)
+        let server = try #require(maybe)
+        defer { server.stop() }
+
+        let reader = try #require(HTTPDiscIOReader(url: url(server), baseChunkSize: 64 * 1024,
+                                                   maxChunkSize: 64 * 1024))
+        defer { reader.close() }
+        #expect(read(reader, at: 100_000, count: 4096) == [UInt8](repeating: 0x55, count: 4096))
+        #expect(read(reader, at: 9_000_000, count: 4096) == [UInt8](repeating: 0x55, count: 4096))
+        #expect(server.bytesWritten < 32 * 1024 * 1024,
+                "the origin wrote \(server.bytesWritten / 1024 / 1024) MB for two 64 KB ranges")
+    }
+
+    @Test("a 206 that starts elsewhere is hung up on at the head and the range asked again",
+          .timeLimit(.minutes(1)))
+    func misplaced206IsHungUpOn() throws {
+        let target: Int64 = 64 * 1024 * 1024
+        let once = FirstClaim()
+        let respond: @Sendable (Int, Int64, String) -> ThrottledOriginServer.Directive = { _, offset, _ in
+            offset == target && once.take() ? .serve206From(start: target - 4096) : .serve206
+        }
+        let maybe = ThrottledOriginServer(totalSize: total, ignoreRangeEnd: true, patternedBody: true,
+                                          respond: respond)
+        let server = try #require(maybe)
+        defer { server.stop() }
+
+        let reader = try #require(HTTPDiscIOReader(url: url(server), baseChunkSize: 64 * 1024,
+                                                   maxChunkSize: 64 * 1024))
+        defer { reader.close() }
+        let expected = (0..<4096).map { ThrottledOriginServer.patternByte(at: target + Int64($0)) }
+        #expect(read(reader, at: target, count: 4096) == expected)
+        #expect(server.bytesWritten < 32 * 1024 * 1024,
+                "the origin wrote \(server.bytesWritten / 1024 / 1024) MB, so the misplaced body was taken")
+    }
+}
diff --git a/docs/formats.md b/docs/formats.md
index 031cef8c8..c5f7bf50c 100644
--- a/docs/formats.md
+++ b/docs/formats.md
@@ -465,6 +465,8 @@ Decrypted disc images play through the normal decode path via a synthetic seekab
 
 Both: no decryption (CSS / AACS retail discs must be ripped decrypted first), no GPL nav libraries, no menus, BD-J, or multi-angle.
 
+A remote `.iso` / `.img` / `.udf` needs an origin that honours HTTP `Range`, because a disc image is a filesystem that only random access can walk. The range probe is judged at the response head: an origin that answers it with a 200 fails the load with an error naming the cause (the body is never downloaded), and a range answered wider than asked is cut where the range ends.
+
 **Title selection.** `engine.discTitles` (`@Published [TitleInfo]`) lists the disc's titles (id, name, duration, chapter count) and `engine.selectedDiscTitle` is the active one; `engine.selectTitle(id:)` switches title, rebuilding the pipeline from the new title's head. The selection survives audio-track switches and background-resume reloads, and a fresh `load` defaults to the main title (an out-of-range id clamps to it). Blu-ray enumerates all playlists; a DVD enumerates its title sets (the VMGI TT_SRPT title list, resolved whole-VTS, with the duration read from each VTS's main program chain; per-cell / episodic splitting is deferred).
 
 **Chapters.** `engine.discChapters` (`@Published [ChapterInfo]`) carries the selected title's chapters; `engine.selectChapter(id:)` seeks to one (a thin `seek` wrapper, no pipeline rebuild). For Blu-ray they come from the playlist's PlayListMark entries (entry marks only; link points dropped), each mark's timestamp on its clip's STC offset by the clip's in_time and the cumulative duration of preceding play items. For DVD they come from the main program chain's program map plus the cumulative cell playback times. Chapter starts are title-relative (0-based); `selectChapter` adds the title's content-start base (the native playlist shift, or the software path's container start PTS) so the seek lands on the source-PTS playback axis.

From 1cde22478946e4f355169866cdaf4434834f22b4 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 09:13:18 +0200
Subject: [PATCH 207/359] fix(demuxer): markClosed reaches the connect, local
 reads and parked slot waits (audit DMX-102, DMX-109, DMX-112)

The HLS-2 fix published the provider only after provider.open() returned, so a markClosed()
during the connect (15 s on a live source, longer for a remote disc probe) found nothing and the
open kept its pump ticket: the channel-zap case on a single-slot origin. The provider is now
published under closeRequestLock before it connects, an open that finds itself closed throws
without starting the container open, and the disc reader the demuxer owns is cancelled too.

markClosed() was a no-op for a local-path input although the interrupt callback that could honour
it has been installed on those since 780e9f87: DemuxInterrupt now carries a sticky close flag that
markClosed() and close() set and the callback returns 1 for.

A pump parked in OriginRequestBudget.acquire ignored the close and could take the next session's
slot or pacer token. acquire takes an optional shouldAbort, polled once per slice in the pacer
wait (before a token is consumed) and in the slot wait (leaving the FIFO, and handing back a slot
a release had already counted in). AVIOReader passes its isClosed at the pump and request sites.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 Sources/AetherEngine/Demuxer/AVIOReader.swift |  11 +-
 Sources/AetherEngine/Demuxer/Demuxer.swift    |  57 +++++++-
 .../Demuxer/OriginRequestBudget.swift         |  74 +++++++++--
 .../DemuxerMarkClosedReachTests.swift         | 115 ++++++++++++++++
 .../OriginRequestBudgetAbortTests.swift       | 125 ++++++++++++++++++
 5 files changed, 364 insertions(+), 18 deletions(-)
 create mode 100644 Tests/AetherEngineTests/DemuxerMarkClosedReachTests.swift
 create mode 100644 Tests/AetherEngineTests/OriginRequestBudgetAbortTests.swift

diff --git a/Sources/AetherEngine/Demuxer/AVIOReader.swift b/Sources/AetherEngine/Demuxer/AVIOReader.swift
index c4d453481..4b61b1974 100644
--- a/Sources/AetherEngine/Demuxer/AVIOReader.swift
+++ b/Sources/AetherEngine/Demuxer/AVIOReader.swift
@@ -2966,7 +2966,10 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
         // means "wait for the short thing to finish", not "give up".
         let requestURLForBudget = request.url ?? url
         let ticket = OriginRequestBudget.shared.acquire(
-            for: requestURLForBudget, label: "\(label) pump", timeout: Self.pumpSlotWaitSeconds)
+            for: requestURLForBudget, label: "\(label) pump", timeout: Self.pumpSlotWaitSeconds,
+            shouldAbort: { [weak self] in self?.isClosed ?? true })
+        // Audit DMX-112: a pump torn down while parked for its slot leaves without a transfer.
+        if ticket == nil, isClosed { return }
 
         let transfer: any PersistentTransfer
         if heldConnectionEnabled {
@@ -4121,7 +4124,11 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
     private func requestTicket(for url: URL, label: String,
                                timeout: TimeInterval) throws -> OriginRequestBudget.Ticket? {
         guard let probeControl else {
-            return OriginRequestBudget.shared.acquire(for: url, label: label, timeout: timeout)
+            let ticket = OriginRequestBudget.shared.acquire(
+                for: url, label: label, timeout: timeout,
+                shouldAbort: { [weak self] in self?.isClosed ?? true })
+            if ticket == nil, isClosed { throw CancellationError() }
+            return ticket
         }
         guard !isClosed else { throw CancellationError() }
         try probeControl.check()
diff --git a/Sources/AetherEngine/Demuxer/Demuxer.swift b/Sources/AetherEngine/Demuxer/Demuxer.swift
index 7b592afc2..4fc9e16fa 100644
--- a/Sources/AetherEngine/Demuxer/Demuxer.swift
+++ b/Sources/AetherEngine/Demuxer/Demuxer.swift
@@ -2,6 +2,7 @@ import Foundation
 import AetherLibavformat
 import AetherLibavcodec
 import AetherLibavutil
+import os
 
 
 /// The stages an `open()` passes through, reported as each one finishes (#361). Deliberately the
@@ -265,10 +266,20 @@ public final class Demuxer: @unchecked Sendable {
         reader?.close()
     }
 
+    /// Audit DMX-102: unblocks the disc reader while `DiscReader.wrap` is still reading through it,
+    /// before any provider exists for `markClosed()` to reach.
+    private func cancelOwnedSourceReader() {
+        providerLock.lock()
+        let reader = _ownedSourceReader
+        providerLock.unlock()
+        reader?.cancel()
+    }
+
     /// Audit HLS-2: `markClosed()` before the provider exists used to be a no-op, so a teardown
     /// that raced an in-flight open let it finish its connect and probe.
     private let closeRequestLock = NSLock()
     private var closeRequested = false
+    private var isCloseRequested: Bool { closeRequestLock.withLock { closeRequested } }
     private var openProfile: DemuxerOpenProfile = .playback
 
     /// Audit NAT-7: the stream pointers `stream(at:)` hands out, copied out of `formatContext`
@@ -535,6 +546,7 @@ public final class Demuxer: @unchecked Sendable {
     ///   - extraHeaders: Attached to every HTTP request (ignored for file:// URLs).
     ///   - isLive: Suppresses EOF synthesis and surfaces terminal error on reconnect cap.
     func open(url: URL, extraHeaders: [String: String] = [:], profile: DemuxerOpenProfile = .playback, isLive: Bool = false, selectTitleID: Int? = nil) throws {
+        if isCloseRequested { throw DemuxerError.openFailed(code: -1) }
         self.openProfile = profile
         self.auditSource = isLive ? nil : (url, extraHeaders)
         let isHTTP = url.scheme == "http" || url.scheme == "https"
@@ -592,6 +604,7 @@ public final class Demuxer: @unchecked Sendable {
     /// DVD/BD ISOs to VOB/MPEGTS concat streams unless the reader opts out via
     /// `discImageProbeEnabled`.
     func open(reader: IOReader, formatHint: String? = nil, profile: DemuxerOpenProfile = .playback, isLive: Bool = false, selectTitleID: Int? = nil, discCacheKey: String? = nil) throws {
+        if isCloseRequested { throw DemuxerError.openFailed(code: -1) }
         self.openProfile = profile
         self.auditSource = nil
         if reader.discImageProbeEnabled,
@@ -622,6 +635,10 @@ public final class Demuxer: @unchecked Sendable {
             let warm = HTTPDiscIOReader.takePrewarm(for: url, extraHeaders: extraHeaders)
             if let discReader = HTTPDiscIOReader(url: url, extraHeaders: extraHeaders, prewarmed: warm) {
                 adoptOwnedSourceReader(discReader)
+                if isCloseRequested {
+                    releaseOwnedSourceReader()
+                    throw DemuxerError.openFailed(code: -1)
+                }
                 let discInfo: DiscInfo?
                 do {
                     discInfo = try DiscReader.wrap(discReader, selectTitleID: selectTitleID, cacheKey: url.absoluteString)
@@ -666,6 +683,13 @@ public final class Demuxer: @unchecked Sendable {
         try openWithProvider(reader, isLive: isLive)
     }
 
+    /// A provider that connected (or tried to) for an open that is not going to finish.
+    private func abandonProvider(_ provider: AVIOProvider) {
+        provider.markClosed()
+        provider.close()
+        avioProvider = nil
+    }
+
     /// Common AVIO open path. `inputFormat` forces a demuxer (custom sources with
     /// a format hint). `isLive` suppresses duration-estimate SEEK_END that latches
     /// EOF on unknown-length live sources.
@@ -674,16 +698,25 @@ public final class Demuxer: @unchecked Sendable {
         inputFormat: UnsafePointer<AVInputFormat>? = nil,
         isLive: Bool = false
     ) throws {
+        // Audit DMX-102: the provider is published BEFORE it connects, under the same lock that
+        // decides "already closed", so a `markClosed()` that lands during the connect (up to 15 s on
+        // a live source, longer for a remote disc probe) reaches the provider instead of finding
+        // nothing and leaving the open holding its origin slot.
         closeRequestLock.lock()
         let closedBeforeConnect = closeRequested
+        if !closedBeforeConnect { avioProvider = provider }
         closeRequestLock.unlock()
         if closedBeforeConnect { throw DemuxerError.openFailed(code: -1) }
-        try provider.open()
-        closeRequestLock.lock()
-        avioProvider = provider
-        let closedDuringConnect = closeRequested
-        closeRequestLock.unlock()
-        if closedDuringConnect { provider.markClosed() }
+        do {
+            try provider.open()
+        } catch {
+            abandonProvider(provider)
+            throw error
+        }
+        if isCloseRequested {
+            abandonProvider(provider)
+            throw DemuxerError.openFailed(code: -1)
+        }
         onOpenProgress?(.sourceOpened)   // #361
 
         // AE#460 follow-up: a live source rebuilt on a RETAINED reader resumes where that reader
@@ -2345,11 +2378,13 @@ public final class Demuxer: @unchecked Sendable {
     /// Fast lock-free unblock: AVIO read callback returns -1, av_read_frame returns
     /// at once. No resource freeing. Call before close() when cancelling a pump.
     func markClosed() {
+        interrupt.requestClose()
         closeRequestLock.lock()
         closeRequested = true
         let provider = avioProvider
         closeRequestLock.unlock()
         provider?.markClosed()
+        cancelOwnedSourceReader()
     }
 
     /// Static metadata probes only. Strong ownership outlives the native interrupt callback.
@@ -2391,6 +2426,7 @@ public final class Demuxer: @unchecked Sendable {
     }
 
     func close() {
+        interrupt.requestClose()
         avioProvider?.markClosed()  // unblocks av_read_frame (tvOS suspends threads in background)
         accessLock.lock()
         interrupt.disarmInputCeiling()
@@ -2440,6 +2476,14 @@ private final class DemuxInterrupt: @unchecked Sendable {
     private var ceiling: Int64 = .max
     private(set) var inputCeilingHit = false
 
+    /// Audit DMX-109: set by `Demuxer.markClosed()` from any thread, read by libavformat's callback
+    /// on the demux thread. A provider-backed input stops on its provider's own flag; a local-path
+    /// input has no provider, so this is the only way a close reaches a read parked on a slow volume.
+    private let closeRequested = OSAllocatedUnfairLock<Bool>(initialState: false)
+
+    func requestClose() { closeRequested.withLock { $0 = true } }
+    var isCloseRequested: Bool { closeRequested.withLock { $0 } }
+
     /// Local (URLContext) inputs only: a provider-backed input never consults this callback per read.
     func armInputCeiling(pb: UnsafeMutablePointer<AVIOContext>, bytes: Int64) {
         self.pb = pb
@@ -2454,6 +2498,7 @@ private final class DemuxInterrupt: @unchecked Sendable {
     }
 
     func shouldInterrupt() -> Bool {
+        if isCloseRequested { return true }
         if probeControl?.isStopped == true { return true }
         if let pb, pb.pointee.bytes_read >= ceiling {
             inputCeilingHit = true
diff --git a/Sources/AetherEngine/Demuxer/OriginRequestBudget.swift b/Sources/AetherEngine/Demuxer/OriginRequestBudget.swift
index bc9ec5ebd..443e41af3 100644
--- a/Sources/AetherEngine/Demuxer/OriginRequestBudget.swift
+++ b/Sources/AetherEngine/Demuxer/OriginRequestBudget.swift
@@ -284,8 +284,18 @@ final class OriginRequestBudget: @unchecked Sendable {
         state.lastRefillAt = instant
     }
 
-    /// Wait until this origin's pacer allows one more request. Returns the milliseconds spent
-    /// waiting, or nil when `timeout` measured from `started` ran out first.
+    private enum PacerWait {
+        case passed(milliseconds: Double)
+        /// `timeout` measured from `started` ran out first.
+        case spent
+        /// The caller's `shouldAbort` fired before a token was taken. Nothing was consumed.
+        case aborted
+    }
+
+    /// Wait until this origin's pacer allows one more request, or until `timeout` measured from
+    /// `started` runs out, or until `shouldAbort` says the caller no longer wants it (audit DMX-112:
+    /// a pump parked here for a session that has been torn down must not take the next session's
+    /// token, so the check comes before a token is consumed, every slice).
     ///
     /// **Nothing is held while this waits.** A pacer token is consumed, not held, so a caller
     /// parked here occupies no slot. Waiting for the token INSIDE a slot (the shape this replaces)
@@ -293,10 +303,11 @@ final class OriginRequestBudget: @unchecked Sendable {
     /// every other path behind it for the whole quiet period, and a suite full of readers doing that
     /// blocked enough threads that unrelated tests could not get one.
     private func waitForPacerToken(raw: String, label: String, started: DispatchTime,
-                                   timeout: TimeInterval) -> Double? {
+                                   timeout: TimeInterval, shouldAbort: (() -> Bool)?) -> PacerWait {
         var pacingStarted: DispatchTime?
         let sleeper = DispatchSemaphore(value: 0)
         while true {
+            if shouldAbort?() == true { return .aborted }
             let instant = now()
             lock.lock()
             let key = headLocked(raw)
@@ -306,7 +317,7 @@ final class OriginRequestBudget: @unchecked Sendable {
             guard let quietUntil = state.quietUntil else {
                 origins[key] = state
                 lock.unlock()
-                return pacedMilliseconds(since: pacingStarted, label: label, spent: false)
+                return .passed(milliseconds: pacedMilliseconds(since: pacingStarted, label: label, spent: false))
             }
 
             let waitNeeded: TimeInterval
@@ -318,7 +329,7 @@ final class OriginRequestBudget: @unchecked Sendable {
                     state.tokens -= 1
                     origins[key] = state
                     lock.unlock()
-                    return pacedMilliseconds(since: pacingStarted, label: label, spent: false)
+                    return .passed(milliseconds: pacedMilliseconds(since: pacingStarted, label: label, spent: false))
                 }
                 waitNeeded = (1 - state.tokens) / Self.pacerRefillPerSecond
             }
@@ -328,7 +339,7 @@ final class OriginRequestBudget: @unchecked Sendable {
             let remaining = timeout - Self.elapsedSeconds(from: started, to: DispatchTime.now())
             guard remaining > 0 else {
                 _ = pacedMilliseconds(since: pacingStarted, label: label, spent: true)
-                return nil
+                return .spent
             }
 
             if pacingStarted == nil { pacingStarted = DispatchTime.now() }
@@ -359,14 +370,27 @@ final class OriginRequestBudget: @unchecked Sendable {
     /// not a correctness barrier, and blocking a read forever to honour a guess about someone
     /// else's rate limiter trades a slow session for a dead one. The un-granted case is counted
     /// and logged, because a budget that is being routinely overrun is worth seeing.
-    func acquire(for url: URL, label: String, timeout: TimeInterval) -> Ticket? {
+    ///
+    /// `shouldAbort` (audit DMX-112) is polled once per `pacerWaitSliceSeconds` in both waits, and a
+    /// caller that has been torn down while parked gets nil back with nothing consumed: no pacer
+    /// token, no slot, and its place in the FIFO given up, so it cannot take what the next session
+    /// is waiting for. nil is also what an unkeyable URL returns, so a caller that passes
+    /// `shouldAbort` tells the two apart by asking its own abort state.
+    func acquire(for url: URL, label: String, timeout: TimeInterval,
+                 shouldAbort: (() -> Bool)? = nil) -> Ticket? {
         guard let raw = Self.originKey(for: url) else { return nil }
 
         let started = DispatchTime.now()
         // Rate before concurrency. The two rules bind different things and only this order lets a
         // caller wait for the rate rule without holding the concurrency one.
-        guard let pacedMs = waitForPacerToken(raw: raw, label: label, started: started,
-                                              timeout: timeout) else {
+        let pacedMs: Double
+        switch waitForPacerToken(raw: raw, label: label, started: started,
+                                 timeout: timeout, shouldAbort: shouldAbort) {
+        case .aborted:
+            return nil
+        case .passed(let milliseconds):
+            pacedMs = milliseconds
+        case .spent:
             // The pacer alone spent the caller's budget. Proceed uncounted-for, the same answer the
             // slot timeout below gives, and stay honest about being on the link.
             lock.lock()
@@ -401,9 +425,39 @@ final class OriginRequestBudget: @unchecked Sendable {
         // What the pacer already spent comes off the slot's budget, so the caller's total wait is
         // the one figure it asked for rather than that figure per gate.
         let slotBudget = max(0, timeout - Self.elapsedSeconds(from: started, to: DispatchTime.now()))
-        let signalled = semaphore.wait(timeout: .now() + slotBudget) == .success
+        var signalled = false
+        var aborted = false
+        if let shouldAbort {
+            let deadline = DispatchTime.now() + slotBudget
+            while true {
+                let slice = min(Self.elapsedSeconds(from: DispatchTime.now(), to: deadline),
+                                Self.pacerWaitSliceSeconds)
+                if semaphore.wait(timeout: .now() + slice) == .success { signalled = true; break }
+                if shouldAbort() { aborted = true; break }
+                if DispatchTime.now() >= deadline { break }
+            }
+        } else {
+            signalled = semaphore.wait(timeout: .now() + slotBudget) == .success
+        }
         let waitedMs = Double(DispatchTime.now().uptimeNanoseconds - started.uptimeNanoseconds) / 1_000_000
 
+        if aborted {
+            lock.lock()
+            let keyNow = headLocked(raw)
+            var parked = origins[keyNow] ?? OriginState()
+            if let i = parked.waiters.firstIndex(where: { $0 === semaphore }) {
+                parked.waiters.remove(at: i)
+                origins[keyNow] = parked
+                lock.unlock()
+                return nil
+            }
+            lock.unlock()
+            // A release counted the slot in and signalled between the last slice and this lock, so
+            // the slot is ours already; it goes back rather than to a caller that has left.
+            release(Ticket(key: raw, label: label, waitedMs: waitedMs, granted: true))
+            return nil
+        }
+
         if signalled {
             // `release` counted us in before signalling, so the slot is already ours.
             return Ticket(key: raw, label: label, waitedMs: waitedMs, granted: true)
diff --git a/Tests/AetherEngineTests/DemuxerMarkClosedReachTests.swift b/Tests/AetherEngineTests/DemuxerMarkClosedReachTests.swift
new file mode 100644
index 000000000..7c1b52a64
--- /dev/null
+++ b/Tests/AetherEngineTests/DemuxerMarkClosedReachTests.swift
@@ -0,0 +1,115 @@
+import Testing
+import Foundation
+import AetherLibavcodec
+@testable import AetherEngine
+
+/// Audit DMX-102 / DMX-109 / DMX-112: `Demuxer.markClosed()` is the one lock-free abort a teardown
+/// has, and it only reached the stages that already had a provider to mark. The provider was
+/// published after `provider.open()` returned, so a close during the connect (up to 15 s on a live
+/// source) found nothing; a local-path source had no provider at all, so the interrupt callback
+/// installed on it never saw the close; and a pump parked for an origin slot ignored it.
+///
+/// The bounds below are the assertions: every abort is measured against a wait the defect would
+/// have sat out in full (10 s of withheld first byte, 10 s of slot wait).
+@Suite("markClosed reaches every blocking stage of a demuxer", .serialized)
+struct DemuxerMarkClosedReachTests {
+
+    /// Cross-thread carrier for the result of an open running on a thread of its own.
+    private final class OpenOutcome: @unchecked Sendable {
+        private let lock = NSLock()
+        private var _finished = false
+        private var _threw = false
+        var finished: Bool { lock.withLock { _finished } }
+        var threw: Bool { lock.withLock { _threw } }
+        func finish(threw: Bool) { lock.withLock { _finished = true; _threw = threw } }
+    }
+
+    private func openOnAThread(_ demuxer: Demuxer, url: URL, isLive: Bool) -> OpenOutcome {
+        let outcome = OpenOutcome()
+        Thread.detachNewThread {
+            do {
+                try demuxer.open(url: url, isLive: isLive)
+                outcome.finish(threw: false)
+            } catch {
+                outcome.finish(threw: true)
+            }
+        }
+        return outcome
+    }
+
+    @Test("a close that lands while the source is connecting aborts the open",
+          .timeLimit(.minutes(2)), arguments: [true, false])
+    func closeDuringConnectAbortsTheOpen(isLive: Bool) async throws {
+        let origin = ThrottledOriginServer(
+            totalSize: 64 << 20, patternedBody: true, firstByteDelayUs: { _ in 10_000_000 })
+        let server = try #require(origin)
+        defer { server.stop() }
+        let url = URL(string: "http://127.0.0.1:\(server.port)/movie.ts")!
+
+        let demuxer = Demuxer()
+        let outcome = openOnAThread(demuxer, url: url, isLive: isLive)
+        try await waitFor { server.requestedRanges.count >= 1 }
+        demuxer.markClosed()
+
+        let returned = try await waitFor(upTo: .seconds(4)) { outcome.finished }
+        #expect(returned, "the open sat out the origin's withheld first byte after markClosed()")
+        #expect(outcome.threw, "an aborted open must throw, not hand back a demuxer")
+        demuxer.close()
+    }
+
+    @Test("a pump parked for an origin slot leaves when the demuxer is closed",
+          .timeLimit(.minutes(2)))
+    func closeReachesAParkedPump() async throws {
+        let server = try #require(ThrottledOriginServer(totalSize: 64 << 20, patternedBody: true))
+        defer { server.stop() }
+        let url = URL(string: "http://127.0.0.1:\(server.port)/movie.ts")!
+        OriginRequestBudget.shared.setHostLimit(1, for: url)
+        let holder = OriginRequestBudget.shared.acquire(for: url, label: "holder", timeout: 1)
+        defer { OriginRequestBudget.shared.release(holder) }
+
+        let demuxer = Demuxer()
+        let outcome = openOnAThread(demuxer, url: url, isLive: false)
+        try await waitFor { (OriginRequestBudget.shared.snapshot(for: url)?.waiting ?? 0) >= 1 }
+        demuxer.markClosed()
+
+        let returned = try await waitFor(upTo: .seconds(4)) { outcome.finished }
+        #expect(returned, "the open stayed parked in the origin's slot queue after markClosed()")
+        #expect(outcome.threw)
+        try await waitFor { (OriginRequestBudget.shared.snapshot(for: url)?.waiting ?? 0) == 0 }
+        #expect(OriginRequestBudget.shared.snapshot(for: url)?.inflight == 1,
+                "the closed pump took a slot that belongs to the next session")
+        demuxer.close()
+    }
+
+    @Test("a close on a local-path source stops the reads libavformat makes itself")
+    func closeReachesALocalSource() throws {
+        let tiny = TinyTransportStreamFixture.data
+        var repeated = Data()
+        for _ in 0..<400 { repeated.append(tiny) }
+        let file = FileManager.default.temporaryDirectory
+            .appendingPathComponent("markclosed-\(UUID().uuidString).ts")
+        try repeated.write(to: file)
+        defer { try? FileManager.default.removeItem(at: file) }
+
+        let demuxer = Demuxer()
+        defer { demuxer.close() }
+        try demuxer.open(url: file)
+        demuxer.markClosed()
+
+        // What libavformat already buffered during the probe is still delivered; the next read that
+        // needs the file has to fail instead of finding it.
+        var delivered = 0
+        var failure: Error?
+        while failure == nil, delivered < 100_000 {
+            do {
+                guard let read = try demuxer.readPacket() else { break }
+                var packet: UnsafeMutablePointer<AVPacket>? = read
+                trackedPacketFree(&packet)
+                delivered += 1
+            } catch {
+                failure = error
+            }
+        }
+        #expect(failure != nil, "a closed local source read all \(delivered) packets to its end")
+    }
+}
diff --git a/Tests/AetherEngineTests/OriginRequestBudgetAbortTests.swift b/Tests/AetherEngineTests/OriginRequestBudgetAbortTests.swift
new file mode 100644
index 000000000..440b7b184
--- /dev/null
+++ b/Tests/AetherEngineTests/OriginRequestBudgetAbortTests.swift
@@ -0,0 +1,125 @@
+import Testing
+import Foundation
+@testable import AetherEngine
+
+/// Audit DMX-112: a pump parked in `OriginRequestBudget.acquire` ignored `markClosed()`, so a torn
+/// down session stayed in the origin's FIFO and in the race for the next pacer token, and could take
+/// the very slot the new session was waiting for. `shouldAbort` is polled once per slice in both
+/// waits, and an aborted caller consumes nothing.
+@Suite("Origin request budget abort", .serialized)
+struct OriginRequestBudgetAbortTests {
+
+    private let url = URL(string: "https://abort.example.com:443/movie.mkv")!
+
+    private final class Flag: @unchecked Sendable {
+        private let lock = NSLock()
+        private var _value = false
+        var value: Bool { lock.withLock { _value } }
+        func set() { lock.withLock { _value = true } }
+    }
+
+    private final class Result: @unchecked Sendable {
+        private let lock = NSLock()
+        private var _done = false
+        private var _ticket: OriginRequestBudget.Ticket?
+        var done: Bool { lock.withLock { _done } }
+        var ticket: OriginRequestBudget.Ticket? { lock.withLock { _ticket } }
+        func finish(_ ticket: OriginRequestBudget.Ticket?) { lock.withLock { _ticket = ticket; _done = true } }
+    }
+
+    private final class ManualClock: @unchecked Sendable {
+        private let lock = NSLock()
+        private var nanoseconds: UInt64 = 1_000_000_000
+        func now() -> DispatchTime { lock.withLock { DispatchTime(uptimeNanoseconds: nanoseconds) } }
+        func advance(by seconds: TimeInterval) {
+            lock.withLock { nanoseconds += UInt64((seconds * 1_000_000_000).rounded()) }
+        }
+    }
+
+    @Test("a caller parked for a slot leaves on abort without taking or holding one",
+          .timeLimit(.minutes(2)))
+    func slotWaitAborts() async throws {
+        let budget = OriginRequestBudget()
+        budget.setHostLimit(1, for: url)
+        let held = budget.acquire(for: url, label: "holder", timeout: 1)
+        let abort = Flag()
+        let outcome = Result()
+        let target = url
+        Thread.detachNewThread {
+            // 120 s: the abort, not this budget, is what must end the wait.
+            outcome.finish(budget.acquire(for: target, label: "pump", timeout: 120,
+                                          shouldAbort: { abort.value }))
+        }
+        try await waitFor { budget.snapshot(for: url)?.waiting == 1 }
+
+        abort.set()
+        try await waitFor { outcome.done }
+        #expect(outcome.ticket == nil, "an aborted acquire must not hand out a ticket")
+        #expect(budget.snapshot(for: url)?.waiting == 0, "the aborted caller left the FIFO")
+        #expect(budget.snapshot(for: url)?.inflight == 1, "only the holder is on the books")
+
+        // The slot the holder gives back goes to the next caller, not to a waiter that left.
+        budget.release(held)
+        let next = budget.acquire(for: url, label: "next", timeout: 1)
+        #expect(next?.granted == true)
+        #expect(next?.waitedMs == 0)
+        budget.release(next)
+        #expect(budget.snapshot(for: url)?.inflight == 0)
+    }
+
+    @Test("a caller parked for the pacer leaves on abort and leaves the tokens alone",
+          .timeLimit(.minutes(2)))
+    func pacerWaitAborts() async throws {
+        let clock = ManualClock()
+        let budget = OriginRequestBudget(now: clock.now)
+        budget.noteRefusal(for: url, status: 429)
+        let abort = Flag()
+        let outcome = Result()
+        let target = url
+        Thread.detachNewThread {
+            outcome.finish(budget.acquire(for: target, label: "pump", timeout: 120,
+                                          shouldAbort: { abort.value }))
+        }
+        try await waitFor { budget.snapshot(for: url)?.paced == true && budget.snapshot(for: url)?.inflight == 0 }
+
+        abort.set()
+        try await waitFor { outcome.done }
+        #expect(outcome.ticket == nil)
+        #expect(budget.snapshot(for: url)?.inflight == 0, "an aborted caller is not on the link")
+
+        // The bucket holds its full burst of two once the quiet period has passed: the aborted
+        // caller consumed none of it.
+        clock.advance(by: 4)
+        for _ in 0..<2 {
+            let ticket = budget.tryAcquire(for: url, label: "next")
+            #expect(ticket?.granted == true, "a token went to the caller that had left")
+            budget.release(ticket)
+        }
+    }
+
+    @Test("an abort that is already set returns before anything is taken")
+    func abortBeforeTheWait() {
+        let budget = OriginRequestBudget()
+        #expect(budget.acquire(for: url, label: "pump", timeout: 1, shouldAbort: { true }) == nil)
+        #expect(budget.snapshot(for: url) == nil, "nothing was counted for an aborted caller")
+    }
+
+    @Test("a caller that is never aborted waits and is granted as before")
+    func noAbortKeepsTheOldBehaviour() async throws {
+        let budget = OriginRequestBudget()
+        budget.setHostLimit(1, for: url)
+        let held = budget.acquire(for: url, label: "holder", timeout: 1)
+        let outcome = Result()
+        let target = url
+        Thread.detachNewThread {
+            outcome.finish(budget.acquire(for: target, label: "pump", timeout: 120,
+                                          shouldAbort: { false }))
+        }
+        try await waitFor { budget.snapshot(for: url)?.waiting == 1 }
+        budget.release(held)
+        try await waitFor { outcome.done }
+        #expect(outcome.ticket?.granted == true)
+        budget.release(outcome.ticket)
+        #expect(budget.snapshot(for: url)?.inflight == 0)
+    }
+}

From 8e7273ef88d7762cfb4907b8feb10a20d10ea8d0 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 09:14:31 +0200
Subject: [PATCH 208/359] test(live): ring tests remove their scratch
 directories themselves (audit PERF-101)

PacketRingBuffer.close() unlinks in the background, which a finished test
process does not wait for, so every run left its chunk files in the temp
directory. Each test now owns a ScratchDirs that removes them when it ends,
and the XCTest ring cases register a teardown block.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../PacketRingBufferBehaviourTests.swift      | 48 +++++++++----
 .../PacketRingBufferChunkSpoolTests.swift     | 68 +++++++++++++------
 .../PacketRingBufferTests.swift               |  1 +
 3 files changed, 80 insertions(+), 37 deletions(-)

diff --git a/Tests/AetherEngineTests/PacketRingBufferBehaviourTests.swift b/Tests/AetherEngineTests/PacketRingBufferBehaviourTests.swift
index 774eefad0..34f0e6769 100644
--- a/Tests/AetherEngineTests/PacketRingBufferBehaviourTests.swift
+++ b/Tests/AetherEngineTests/PacketRingBufferBehaviourTests.swift
@@ -9,12 +9,7 @@ import Testing
 @Suite("DVR ring behaviour")
 struct PacketRingBufferBehaviourTests {
 
-    private func makeScratch() -> URL {
-        let dir = FileManager.default.temporaryDirectory
-            .appendingPathComponent("prbbehave-\(UUID().uuidString)", isDirectory: true)
-        try? FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
-        return dir
-    }
+    private func makeScratch(_ dirs: ScratchDirs) -> URL { dirs.make(prefix: "prbbehave") }
 
     private func payload(_ i: Int, count: Int = 16) -> Data {
         Data((0..<count).map { UInt8(truncatingIfNeeded: i &+ $0) })
@@ -35,7 +30,8 @@ struct PacketRingBufferBehaviourTests {
 
     @Test("Packets read back by sequence with their flags and bytes, audio and video interleaved")
     func readsBackBySequence() throws {
-        let ring = try PacketRingBuffer(windowSeconds: 3600, scratch: makeScratch())
+        let dirs = ScratchDirs()
+        let ring = try PacketRingBuffer(windowSeconds: 3600, scratch: makeScratch(dirs))
         defer { ring.close() }
         try ring.append(pts: 10, isKeyframe: true, isVideo: true, bytes: Data([1, 2, 3]))
         try ring.append(pts: 10, isKeyframe: false, isVideo: false, bytes: Data([4]))
@@ -57,7 +53,8 @@ struct PacketRingBufferBehaviourTests {
 
     @Test("Eviction keeps the retained span on a video keyframe and advances the first sequence")
     func evictionIsKeyframeAlignedAndMonotonic() throws {
-        let ring = try PacketRingBuffer(windowSeconds: 10, scratch: makeScratch())
+        let dirs = ScratchDirs()
+        let ring = try PacketRingBuffer(windowSeconds: 10, scratch: makeScratch(dirs))
         defer { ring.close() }
         var lastFirst = 0
         for second in 0..<60 {
@@ -86,13 +83,14 @@ struct PacketRingBufferBehaviourTests {
 
     @Test("Nothing is evicted while the retained history fits the window, and an infinite window keeps everything")
     func wholeWindowIsKept() throws {
-        let short = try PacketRingBuffer(windowSeconds: 100, scratch: makeScratch())
+        let dirs = ScratchDirs()
+        let short = try PacketRingBuffer(windowSeconds: 100, scratch: makeScratch(dirs))
         defer { short.close() }
         try fill(short, seconds: 30)
         #expect(short.seqBounds.first == 0)
         #expect(short.seqBounds.end == 30 * 25 * 2)
 
-        let forever = try PacketRingBuffer(windowSeconds: .infinity, scratch: makeScratch())
+        let forever = try PacketRingBuffer(windowSeconds: .infinity, scratch: makeScratch(dirs))
         defer { forever.close() }
         try fill(forever, seconds: 30)
         #expect(forever.seqBounds.first == 0)
@@ -101,7 +99,8 @@ struct PacketRingBufferBehaviourTests {
 
     @Test("Rewind lookups: newest keyframe at or before a target, earliest keyframe as the floor")
     func rewindLookups() throws {
-        let ring = try PacketRingBuffer(windowSeconds: 3600, scratch: makeScratch())
+        let dirs = ScratchDirs()
+        let ring = try PacketRingBuffer(windowSeconds: 3600, scratch: makeScratch(dirs))
         defer { ring.close() }
         // The session joined mid-GOP: two non-key packets precede the first keyframe.
         try ring.append(pts: 4.8, isKeyframe: false, isVideo: true, bytes: Data([0]))
@@ -123,7 +122,8 @@ struct PacketRingBufferBehaviourTests {
 
     @Test("Rewind lookups stay correct after eviction has moved the first sequence")
     func rewindLookupsAfterEviction() throws {
-        let ring = try PacketRingBuffer(windowSeconds: 10, scratch: makeScratch())
+        let dirs = ScratchDirs()
+        let ring = try PacketRingBuffer(windowSeconds: 10, scratch: makeScratch(dirs))
         defer { ring.close() }
         try fill(ring, seconds: 60, gopSeconds: 2)
         let bounds = ring.seqBounds
@@ -141,7 +141,8 @@ struct PacketRingBufferBehaviourTests {
 
     @Test("packets(fromPts:) replays from the first video keyframe, audio included")
     func replayStartsOnAVideoKeyframe() throws {
-        let ring = try PacketRingBuffer(windowSeconds: 3600, scratch: makeScratch())
+        let dirs = ScratchDirs()
+        let ring = try PacketRingBuffer(windowSeconds: 3600, scratch: makeScratch(dirs))
         defer { ring.close() }
         try ring.append(pts: 1.0, isKeyframe: false, isVideo: false, bytes: Data([1]))
         try ring.append(pts: 1.1, isKeyframe: false, isVideo: true, bytes: Data([2]))
@@ -157,7 +158,8 @@ struct PacketRingBufferBehaviourTests {
 
     @Test("A still run opens on the keyframe, carries video only, and respects its bounds")
     func stillRunShape() throws {
-        let ring = try PacketRingBuffer(windowSeconds: 3600, scratch: makeScratch())
+        let dirs = ScratchDirs()
+        let ring = try PacketRingBuffer(windowSeconds: 3600, scratch: makeScratch(dirs))
         defer { ring.close() }
         try fill(ring, seconds: 10, gopSeconds: 2)
 
@@ -181,7 +183,8 @@ struct PacketRingBufferBehaviourTests {
 
     @Test("close() clears the index at once and is idempotent")
     func closeIsImmediateAndIdempotent() throws {
-        let ring = try PacketRingBuffer(windowSeconds: 60, scratch: makeScratch())
+        let dirs = ScratchDirs()
+        let ring = try PacketRingBuffer(windowSeconds: 60, scratch: makeScratch(dirs))
         try fill(ring, seconds: 4)
         #expect(ring.seqBounds.end > 0)
         ring.close()
@@ -191,3 +194,18 @@ struct PacketRingBufferBehaviourTests {
         ring.close()
     }
 }
+
+/// Removes every directory it handed out when the test that owns it ends. `PacketRingBuffer.close()`
+/// unlinks in the background, which a finished test process does not wait for.
+private final class ScratchDirs: @unchecked Sendable {
+    private let lock = NSLock()
+    private var dirs: [URL] = []
+    func make(prefix: String) -> URL {
+        let dir = FileManager.default.temporaryDirectory
+            .appendingPathComponent("\(prefix)-\(UUID().uuidString)", isDirectory: true)
+        try? FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
+        lock.lock(); dirs.append(dir); lock.unlock()
+        return dir
+    }
+    deinit { for dir in dirs { try? FileManager.default.removeItem(at: dir) } }
+}
diff --git a/Tests/AetherEngineTests/PacketRingBufferChunkSpoolTests.swift b/Tests/AetherEngineTests/PacketRingBufferChunkSpoolTests.swift
index 4417fb710..8c6dc0a02 100644
--- a/Tests/AetherEngineTests/PacketRingBufferChunkSpoolTests.swift
+++ b/Tests/AetherEngineTests/PacketRingBufferChunkSpoolTests.swift
@@ -9,12 +9,7 @@ import Testing
 @Suite("DVR ring chunk spool")
 struct PacketRingBufferChunkSpoolTests {
 
-    private func makeScratch(in base: URL? = nil) -> URL {
-        let parent = base ?? URL(fileURLWithPath: NSTemporaryDirectory(), isDirectory: true)
-        let dir = parent.appendingPathComponent("prbspool-\(UUID().uuidString)", isDirectory: true)
-        try? FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
-        return dir
-    }
+    private func makeScratch(_ dirs: ScratchDirs) -> URL { dirs.make(prefix: "prbspool") }
 
     private func packetFiles(in dir: URL) -> [URL] {
         ((try? FileManager.default.contentsOfDirectory(at: dir, includingPropertiesForKeys: nil)) ?? [])
@@ -30,7 +25,8 @@ struct PacketRingBufferChunkSpoolTests {
 
     @Test("Packets spool into a few chunk files, not one file per packet")
     func spoolsIntoChunkFiles() throws {
-        let scratch = makeScratch()
+        let dirs = ScratchDirs()
+        let scratch = makeScratch(dirs)
         let ring = try PacketRingBuffer(windowSeconds: 3600, scratch: scratch)
         defer { ring.close() }
         let payload = Data(repeating: 0x5A, count: 1024)
@@ -75,8 +71,9 @@ struct PacketRingBufferChunkSpoolTests {
 
     @Test("The index is a flat record per packet, not a heap object per packet")
     func indexIsCompact() throws {
+        let dirs = ScratchDirs()
         #expect(MemoryLayout<PacketRingBuffer.Entry>.stride == 24)
-        let ring = try PacketRingBuffer(windowSeconds: .infinity, scratch: makeScratch())
+        let ring = try PacketRingBuffer(windowSeconds: .infinity, scratch: makeScratch(dirs))
         defer { ring.close() }
         let payload = Data(repeating: 1, count: 64)
         let count = 100_000
@@ -92,7 +89,8 @@ struct PacketRingBufferChunkSpoolTests {
 
     @Test("A byte budget bounds the disk use, even with an infinite window, and the span opens on a keyframe")
     func byteBudgetBoundsDiskAndKeepsKeyframeAlignment() throws {
-        let scratch = makeScratch()
+        let dirs = ScratchDirs()
+        let scratch = makeScratch(dirs)
         let budget = 8 << 20
         let ring = try PacketRingBuffer(windowSeconds: .infinity, scratch: scratch, byteBudget: budget)
         defer { ring.close() }
@@ -118,7 +116,8 @@ struct PacketRingBufferChunkSpoolTests {
 
     @Test("The budget holds when the window is finite too, and the stricter bound wins")
     func strictestBoundWins() throws {
-        let ring = try PacketRingBuffer(windowSeconds: 20, scratch: makeScratch(), byteBudget: 64 << 20)
+        let dirs = ScratchDirs()
+        let ring = try PacketRingBuffer(windowSeconds: 20, scratch: makeScratch(dirs), byteBudget: 64 << 20)
         defer { ring.close() }
         let payload = Data(repeating: 3, count: 4 << 10)
         for i in 0..<400 {
@@ -130,7 +129,8 @@ struct PacketRingBufferChunkSpoolTests {
 
     @Test("A budget smaller than one chunk never evicts the only chunk")
     func tinyBudgetKeepsTheTail() throws {
-        let ring = try PacketRingBuffer(windowSeconds: .infinity, scratch: makeScratch(), byteBudget: 1)
+        let dirs = ScratchDirs()
+        let ring = try PacketRingBuffer(windowSeconds: .infinity, scratch: makeScratch(dirs), byteBudget: 1)
         defer { ring.close() }
         for i in 0..<50 {
             try ring.append(pts: Double(i), isKeyframe: i % 5 == 0, isVideo: true, bytes: Data(repeating: 9, count: 10_000))
@@ -146,7 +146,8 @@ struct PacketRingBufferChunkSpoolTests {
 
     @Test("A GOP larger than the whole budget still cannot grow the directory without bound")
     func hugeGopIsBoundedToo() throws {
-        let scratch = makeScratch()
+        let dirs = ScratchDirs()
+        let scratch = makeScratch(dirs)
         let budget = 1 << 20
         let ring = try PacketRingBuffer(windowSeconds: .infinity, scratch: scratch, byteBudget: budget)
         defer { ring.close() }
@@ -161,7 +162,8 @@ struct PacketRingBufferChunkSpoolTests {
 
     @Test("The resident floor is nil until eviction moves the span, then tracks the oldest keyframe")
     func residentFloorFollowsEviction() throws {
-        let ring = try PacketRingBuffer(windowSeconds: .infinity, scratch: makeScratch(), byteBudget: 4 << 20)
+        let dirs = ScratchDirs()
+        let ring = try PacketRingBuffer(windowSeconds: .infinity, scratch: makeScratch(dirs), byteBudget: 4 << 20)
         defer { ring.close() }
         let size = 128 << 10
         try ring.append(pts: 100, isKeyframe: true, isVideo: true, bytes: Data(repeating: 0, count: size))
@@ -206,8 +208,8 @@ struct PacketRingBufferChunkSpoolTests {
         }
     }
 
-    private func flakyRing(disk: FlakyDisk, byteBudget: Int = .max) throws -> PacketRingBuffer {
-        let ring = try PacketRingBuffer(windowSeconds: .infinity, scratch: makeScratch(),
+    private func flakyRing(disk: FlakyDisk, dirs: ScratchDirs, byteBudget: Int = .max) throws -> PacketRingBuffer {
+        let ring = try PacketRingBuffer(windowSeconds: .infinity, scratch: makeScratch(dirs),
                                         byteBudget: byteBudget, chunkTargetBytes: 64 << 10,
                                         writeAll: disk.writer)
         disk.ring = ring
@@ -216,8 +218,9 @@ struct PacketRingBufferChunkSpoolTests {
 
     @Test("A write that fails once is retried after the oldest chunk is freed, and nothing is dropped")
     func failedWriteMakesRoomAndRetries() throws {
+        let dirs = ScratchDirs()
         let disk = FlakyDisk()
-        let ring = try flakyRing(disk: disk)
+        let ring = try flakyRing(disk: disk, dirs: dirs)
         defer { ring.close() }
         let body = Data(repeating: 7, count: 32 << 10)
         for i in 0..<10 {
@@ -237,9 +240,10 @@ struct PacketRingBufferChunkSpoolTests {
 
     @Test("A full volume shrinks the rewind window and the live feed keeps flowing")
     func fullVolumeKeepsFeedingWithAShrinkingWindow() throws {
+        let dirs = ScratchDirs()
         let disk = FlakyDisk()
         disk.setCapacity(1 << 20)
-        let ring = try flakyRing(disk: disk)
+        let ring = try flakyRing(disk: disk, dirs: dirs)
         defer { ring.close() }
         let body = { (i: Int) in Data(repeating: UInt8(truncatingIfNeeded: i), count: 16 << 10) }
         for i in 0..<500 {
@@ -257,8 +261,9 @@ struct PacketRingBufferChunkSpoolTests {
 
     @Test("With nothing reclaimable the append throws cleanly, and the ring recovers when space returns")
     func nothingToFreeThrowsWithoutCorruption() throws {
+        let dirs = ScratchDirs()
         let disk = FlakyDisk()
-        let ring = try flakyRing(disk: disk)
+        let ring = try flakyRing(disk: disk, dirs: dirs)
         defer { ring.close() }
         let body = { (i: Int) in Data(repeating: UInt8(truncatingIfNeeded: i), count: 4 << 10) }
         try ring.append(pts: 0, isKeyframe: true, isVideo: true, bytes: body(0))
@@ -279,8 +284,9 @@ struct PacketRingBufferChunkSpoolTests {
 
     @Test("An incoming keyframe may replace a retained span that cannot otherwise make room")
     func incomingKeyframeReplacesATailOnlySpan() throws {
+        let dirs = ScratchDirs()
         let disk = FlakyDisk()
-        let ring = try flakyRing(disk: disk)
+        let ring = try flakyRing(disk: disk, dirs: dirs)
         defer { ring.close() }
         let body = Data(repeating: 5, count: 4 << 10)
         for i in 0..<3 {
@@ -300,7 +306,8 @@ struct PacketRingBufferChunkSpoolTests {
 
     @Test("Readers racing eviction only ever see the bytes of the sequence they asked for")
     func concurrentReadersSeeConsistentBytes() async throws {
-        let ring = try PacketRingBuffer(windowSeconds: .infinity, scratch: makeScratch(),
+        let dirs = ScratchDirs()
+        let ring = try PacketRingBuffer(windowSeconds: .infinity, scratch: makeScratch(dirs),
                                         byteBudget: 2 << 20, chunkTargetBytes: 128 << 10)
         defer { ring.close() }
         let total = 6000
@@ -342,7 +349,8 @@ struct PacketRingBufferChunkSpoolTests {
 
     @Test("isVideo(atSeq:) answers from the index: resident kinds, nil outside the span")
     func isVideoAnswersFromTheIndex() throws {
-        let ring = try PacketRingBuffer(windowSeconds: .infinity, scratch: makeScratch(), byteBudget: 1 << 20)
+        let dirs = ScratchDirs()
+        let ring = try PacketRingBuffer(windowSeconds: .infinity, scratch: makeScratch(dirs), byteBudget: 1 << 20)
         defer { ring.close() }
         #expect(ring.isVideo(atSeq: 0) == nil)
         for i in 0..<300 {
@@ -360,7 +368,8 @@ struct PacketRingBufferChunkSpoolTests {
 
     @Test("A chunk file that vanished reads as an unreadable packet, not a crash")
     func missingChunkFileIsAnUnreadablePacket() throws {
-        let scratch = makeScratch()
+        let dirs = ScratchDirs()
+        let scratch = makeScratch(dirs)
         let ring = try PacketRingBuffer(windowSeconds: .infinity, scratch: scratch, chunkTargetBytes: 64 << 10)
         defer { ring.close() }
         for i in 0..<60 {
@@ -381,3 +390,18 @@ private final class Counter: @unchecked Sendable {
     var value: Int { lock.lock(); defer { lock.unlock() }; return n }
     func add(_ d: Int) { lock.lock(); n += d; lock.unlock() }
 }
+
+/// Removes every directory it handed out when the test that owns it ends. `PacketRingBuffer.close()`
+/// unlinks in the background, which a finished test process does not wait for.
+private final class ScratchDirs: @unchecked Sendable {
+    private let lock = NSLock()
+    private var dirs: [URL] = []
+    func make(prefix: String) -> URL {
+        let dir = FileManager.default.temporaryDirectory
+            .appendingPathComponent("\(prefix)-\(UUID().uuidString)", isDirectory: true)
+        try? FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
+        lock.lock(); dirs.append(dir); lock.unlock()
+        return dir
+    }
+    deinit { for dir in dirs { try? FileManager.default.removeItem(at: dir) } }
+}
diff --git a/Tests/AetherEngineTests/PacketRingBufferTests.swift b/Tests/AetherEngineTests/PacketRingBufferTests.swift
index cb2df5a70..a2b42d80d 100644
--- a/Tests/AetherEngineTests/PacketRingBufferTests.swift
+++ b/Tests/AetherEngineTests/PacketRingBufferTests.swift
@@ -7,6 +7,7 @@ final class PacketRingBufferTests: XCTestCase {
         let d = FileManager.default.temporaryDirectory
             .appendingPathComponent("prbtest-\(ProcessInfo.processInfo.globallyUniqueString)")
         try? FileManager.default.createDirectory(at: d, withIntermediateDirectories: true)
+        addTeardownBlock { try? FileManager.default.removeItem(at: d) }
         return d
     }
     func testAppendAndKeyframeSeek() throws {

From 66af52fdc7617d631d7e3f8e5962db9dd37c06de Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 09:14:31 +0200
Subject: [PATCH 209/359] perf(software): park the demux loop on a timed
 condition wait instead of a 5 ms sleep (audit PERF-110)

The parked read gate polled the renderer with Thread.sleep(0.005). The
renderer drains at frame cadence and the audio lead shrinks with the clock,
and nothing signals either, so the wait stays timed, but it is now a wait on
the demux condition, which play, stop, background, seek-settled and
feed-cursor changes already broadcast, and its length follows the time the
read gate needs to open (the lead's excess over its target at the playback
rate), clamped to 5..20 ms. A renderer queue of about ten frames cannot
drain in 20 ms, so the parked video still reaches the decoder in time.

Measured with a temporary iteration counter (removed) on a 60 s H.264/AAC
transport stream through the software path, 20 s of playback: 164 parked
wakeups per second before, 50 after (3.3x fewer; 940 and 935 park episodes,
about 19 s parked in both runs).

requestMediaDataWhenReady does not fit here, because the gate is the audio
lead and not renderer readiness.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../Native/SoftwarePlaybackHost.swift         | 29 +++++++++-
 .../SWDemuxReadGateTests.swift                | 53 +++++++++++++++++++
 2 files changed, 81 insertions(+), 1 deletion(-)

diff --git a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
index 0820ed5df..ca81a504a 100644
--- a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
+++ b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
@@ -741,6 +741,22 @@ final class SoftwarePlaybackHost {
         ) == .stop
     }
 
+    /// How long the parked demux loop waits before it re-checks the renderer, in seconds. The renderer
+    /// drains at frame cadence and the audio lead shrinks with the clock, and nothing signals either,
+    /// so this is a timed wait (audit PERF-110: the fixed 5 ms sleep was 200 wakeups a second in every
+    /// software VOD session). It is bounded by the time the read gate needs to open (the lead's excess
+    /// over its target at the playback rate), never below 5 ms, and never above 20 ms: a renderer queue
+    /// of about ten frames cannot drain in that, so the parked video still reaches the decoder in time.
+    nonisolated static func parkedRendererWaitSeconds(
+        clockArmed: Bool, lastAudioPts: Double, clockSeconds: Double, rate: Float
+    ) -> TimeInterval {
+        let floor = 0.005, ceiling = 0.020
+        guard clockArmed, lastAudioPts.isFinite, clockSeconds.isFinite, rate > 0 else { return floor }
+        let untilGateOpens = (lastAudioPts - clockSeconds - AudioLookaheadPolicy.targetLeadSeconds) / Double(rate)
+        guard untilGateOpens.isFinite else { return floor }
+        return min(max(untilGateOpens, floor), ceiling)
+    }
+
     // MARK: - Load
 
     func load(
@@ -2552,7 +2568,18 @@ final class SoftwarePlaybackHost {
                 diag?.update(lastAudioPts: lastEnqueuedAudioPtsSec,
                              parked: parkedVideo.count, rebuffering: rebuffering,
                              generation: parkedSeekGeneration)
-                if stillWaiting() { Thread.sleep(forTimeInterval: 0.005) }
+                if stillWaiting() {
+                    // The condition is broadcast on play, stop, background, seek-settled and feed-cursor
+                    // changes, so those cut the wait short where the sleep used to ride them out.
+                    let wait = Self.parkedRendererWaitSeconds(
+                        clockArmed: clockArmed(), lastAudioPts: lastEnqueuedAudioPtsSec,
+                        clockSeconds: audioOutput?.currentTimeSeconds ?? .nan, rate: currentRate())
+                    condition.lock()
+                    autoreleasepool {
+                        _ = condition.wait(until: Date(timeIntervalSinceNow: wait))
+                    }
+                    condition.unlock()
+                }
             }
         }
 
diff --git a/Tests/AetherEngineTests/SWDemuxReadGateTests.swift b/Tests/AetherEngineTests/SWDemuxReadGateTests.swift
index f0c5b8c02..b743dfa80 100644
--- a/Tests/AetherEngineTests/SWDemuxReadGateTests.swift
+++ b/Tests/AetherEngineTests/SWDemuxReadGateTests.swift
@@ -57,4 +57,57 @@ struct SWDemuxReadGateTests {
             parkedCount: 4, parkedCap: cap, clockArmed: true,
             lastAudioPts: 104, clockSeconds: .nan) == false)
     }
+
+    // MARK: - Parked wait (audit PERF-110)
+
+    @Test("a lead just over the target wakes when the gate opens, not before the floor")
+    func waitFollowsTheGateOpening() {
+        let clock = 100.0
+        let target = AudioLookaheadPolicy.targetLeadSeconds
+        #expect(abs(SoftwarePlaybackHost.parkedRendererWaitSeconds(
+            clockArmed: true, lastAudioPts: clock + target + 0.012, clockSeconds: clock, rate: 1) - 0.012) < 1e-9)
+        #expect(SoftwarePlaybackHost.parkedRendererWaitSeconds(
+            clockArmed: true, lastAudioPts: clock + target + 0.001, clockSeconds: clock, rate: 1) == 0.005)
+    }
+
+    @Test("a lead far over the target is capped at 20 ms so parked video keeps reaching the decoder")
+    func waitIsCapped() {
+        #expect(SoftwarePlaybackHost.parkedRendererWaitSeconds(
+            clockArmed: true, lastAudioPts: 110, clockSeconds: 100, rate: 1) == 0.020)
+    }
+
+    @Test("a gate that is already open, an unarmed clock and unreadable inputs poll at the 5 ms floor")
+    func waitFloor() {
+        #expect(SoftwarePlaybackHost.parkedRendererWaitSeconds(
+            clockArmed: true, lastAudioPts: 101, clockSeconds: 100, rate: 1) == 0.005)
+        #expect(SoftwarePlaybackHost.parkedRendererWaitSeconds(
+            clockArmed: false, lastAudioPts: 110, clockSeconds: 100, rate: 1) == 0.005)
+        #expect(SoftwarePlaybackHost.parkedRendererWaitSeconds(
+            clockArmed: true, lastAudioPts: .nan, clockSeconds: 100, rate: 1) == 0.005)
+        #expect(SoftwarePlaybackHost.parkedRendererWaitSeconds(
+            clockArmed: true, lastAudioPts: 110, clockSeconds: .nan, rate: 1) == 0.005)
+        #expect(SoftwarePlaybackHost.parkedRendererWaitSeconds(
+            clockArmed: true, lastAudioPts: 110, clockSeconds: 100, rate: 0) == 0.005)
+        #expect(SoftwarePlaybackHost.parkedRendererWaitSeconds(
+            clockArmed: true, lastAudioPts: .infinity, clockSeconds: 100, rate: 1) == 0.005)
+    }
+
+    @Test("the rate shortens the wait the same way it shortens the time to the gate")
+    func waitScalesWithRate() {
+        let target = AudioLookaheadPolicy.targetLeadSeconds
+        let excess = 0.016
+        #expect(abs(SoftwarePlaybackHost.parkedRendererWaitSeconds(
+            clockArmed: true, lastAudioPts: 100 + target + excess, clockSeconds: 100, rate: 2) - 0.008) < 1e-9)
+    }
+
+    @Test("whatever the inputs, the wait stays between 5 and 20 ms")
+    func waitIsAlwaysBounded() {
+        for lead in stride(from: -2.0, through: 12.0, by: 0.37) {
+            for rate: Float in [0.25, 0.5, 1, 1.5, 2, 4, 8] {
+                let w = SoftwarePlaybackHost.parkedRendererWaitSeconds(
+                    clockArmed: true, lastAudioPts: 100 + lead, clockSeconds: 100, rate: rate)
+                #expect(w >= 0.005 && w <= 0.020)
+            }
+        }
+    }
 }

From e0a88e2c4c353a15bdf93d7cf0c47e1dbebe6849 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 09:16:34 +0200
Subject: [PATCH 210/359] fix(demuxer): the streaming hard cap ends the read
 with a typed cause instead of a bare EIO (audit DMX-107)

The forward-only reader pauses its transfer at 64 MB and ends it at 128 MB,
because a pause is advisory (#220 measured 911 MB arriving after one). Where
a transport ignores the pause, the buffer reaches the cap and the read fails
with EIO, which a host cannot tell from a dropped connection. The bound itself
stays: memory is never unbounded, and this path still cannot re-request at an
offset.

The end now records `AVIOReaderError.originIgnoresFlowControl`
(`AVIOReader.lastReadFailure`), the release-visible log lines name it, and a
plain transport loss keeps no cause of ours. The water marks became
per-reader values (`streamHighWater`, default 64 MB) so the cap is testable
without streaming 128 MB. Moving forward-only sources onto the held pull
connection, which would remove the cap as a failure mode, is a later phase.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 Sources/AetherEngine/Demuxer/AVIOReader.swift | 47 +++++++++---
 .../StreamingBufferBoundTests.swift           | 76 +++++++++++++++++++
 2 files changed, 112 insertions(+), 11 deletions(-)
 create mode 100644 Tests/AetherEngineTests/StreamingBufferBoundTests.swift

diff --git a/Sources/AetherEngine/Demuxer/AVIOReader.swift b/Sources/AetherEngine/Demuxer/AVIOReader.swift
index 93bfde316..3f939e4e5 100644
--- a/Sources/AetherEngine/Demuxer/AVIOReader.swift
+++ b/Sources/AetherEngine/Demuxer/AVIOReader.swift
@@ -482,13 +482,15 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
     private static let avioBufferSize: Int32 = 256 * 1024  // 256 KB
     private static let streamTrimThreshold = 1024 * 1024  // 1 MB, keep for small backward seeks
     // Backpressure: suspend the streaming task above highWater, resume below lowWater.
-    private static let streamHighWater = 64 * 1024 * 1024
-    private static let streamLowWater = 32 * 1024 * 1024
+    private static let streamHighWaterDefault = 64 * 1024 * 1024
+    private let streamHighWater: Int
+    private var streamLowWater: Int { streamHighWater / 2 }
     /// Audit DMX-7: the suspend above is advisory (#220 measured 911 MB arriving after one), and
     /// this path cannot re-request at an offset the way the persistent reader does, so a transport
     /// that keeps delivering past twice the high water is ended and the read fails with EIO once
-    /// the buffered bytes are drained.
-    private static let streamHardCap = 2 * streamHighWater
+    /// the buffered bytes are drained. Audit DMX-107: that failure is typed
+    /// (`AVIOReaderError.originIgnoresFlowControl`, `lastReadFailure`), so it reads as what it is.
+    private var streamHardCap: Int { 2 * streamHighWater }
 
     private let bufferLock = NSLock()
     private var currentBuffer = Data()
@@ -522,6 +524,9 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
     /// `streamHardCap`. Either way the bytes that did not arrive are lost, not absent, so the read
     /// that runs out reports EIO instead of end-of-media. Guarded by `streamLock`.
     private var streamFailed = false
+    /// Audit DMX-107: why the streaming GET was ended by this reader when it was not the transport's
+    /// doing. Guarded by `streamLock`.
+    private var streamFailureCause: AVIOReaderError?
     /// The status the streaming GET was answered with when it was anything but 200/206, 0 while
     /// none. A status is not media: the delegate hangs up at the header, and `open()` fails typed
     /// on it rather than handing FFmpeg an empty stream to misreport as invalid data. Written on
@@ -797,6 +802,14 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
         return activeTransfer != nil
     }
 
+    /// Audit DMX-107: the typed cause of the read error the streaming path reports, nil while the
+    /// source is healthy and for a plain transport loss (which has no cause of ours to name).
+    var lastReadFailure: AVIOReaderError? {
+        streamLock.lock()
+        defer { streamLock.unlock() }
+        return streamFailureCause
+    }
+
     /// The most the forward-only streaming buffer has held at once.
     var streamPeakBufferBytesForTesting: Int {
         streamLock.lock()
@@ -1073,7 +1086,7 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
     private let probeDrainLock = NSLock()
     private var drainingProbeRequest = false
 
-    init(url: URL, extraHeaders: [String: String] = [:], label: String = "source", chunkSize: Int = 4 * 1024 * 1024, prefetchEnabled: Bool = true, isLive: Bool = false, chunkRequestTimeout: TimeInterval = 35, chunkMaxRetries: Int = 3, boundedInitialFetch: Int64? = nil, sequentialOnly: Bool = false, connStallTimeout: TimeInterval = AVIOReader.connStallTimeoutDefault, windowHighWater: Int? = nil, heldConnection: Bool = false, probeControl: ProbeControl? = nil, probeRequestSession: URLSession? = nil) {
+    init(url: URL, extraHeaders: [String: String] = [:], label: String = "source", chunkSize: Int = 4 * 1024 * 1024, prefetchEnabled: Bool = true, isLive: Bool = false, chunkRequestTimeout: TimeInterval = 35, chunkMaxRetries: Int = 3, boundedInitialFetch: Int64? = nil, sequentialOnly: Bool = false, connStallTimeout: TimeInterval = AVIOReader.connStallTimeoutDefault, windowHighWater: Int? = nil, streamHighWater: Int? = nil, heldConnection: Bool = false, probeControl: ProbeControl? = nil, probeRequestSession: URLSession? = nil) {
         self.probeControl = probeControl
         self.probeRequestSession = probeControl == nil ? nil : probeRequestSession
         self.url = url
@@ -1092,6 +1105,7 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
         self.connStallTimeout = max(0.05, connStallTimeout)
         self.winHighWater = max(1, windowHighWater
             ?? (isLive ? Self.liveWinHighWaterDefault : Self.winHighWaterDefault))
+        self.streamHighWater = max(1, streamHighWater ?? Self.streamHighWaterDefault)
         self.heldConnectionEnabled = heldConnection
     }
 
@@ -1851,7 +1865,7 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
                     streamBytesRead += Int64(trimAmount)
                 }
                 var toResume: URLSessionDataTask?
-                if streamingTaskSuspended, streamBuffer.count < Self.streamLowWater {
+                if streamingTaskSuspended, streamBuffer.count < streamLowWater {
                     streamingTaskSuspended = false
                     toResume = streamingTask
                 }
@@ -1888,6 +1902,7 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
         streamLock.lock()
         let ended = streamEnded
         let failed = streamFailed
+        let cause = streamFailureCause
         let received = streamBytesRead + Int64(streamBuffer.count)
         let expected = streamExpectedBytes
         streamLock.unlock()
@@ -1899,7 +1914,8 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
         if !ended || failed || (expected > 0 && received < expected) {
             EngineLog.emit(
                 "[AVIOReader] \(label) stream \(!ended ? "stalled out" : failed ? "failed" : "ended short") at "
-                + "\(received)\(expected > 0 ? "/\(expected)" : "") bytes; reporting EIO",
+                + "\(received)\(expected > 0 ? "/\(expected)" : "") bytes"
+                + (cause.map { " (\($0))" } ?? "") + "; reporting EIO",
                 category: .demux
             )
             return FFmpegErr.eio
@@ -3650,8 +3666,9 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
             self.streamBuffer.append(data.withUnsafeBytes { Data($0) })
             self.streamPeakBytes = max(self.streamPeakBytes, self.streamBuffer.count)
             var toCancel: URLSessionDataTask?
-            if self.streamBuffer.count > Self.streamHardCap {
+            if self.streamBuffer.count > self.streamHardCap {
                 self.streamFailed = true
+                self.streamFailureCause = .originIgnoresFlowControl
                 toCancel = self.streamingTask
             }
             // Backpressure: park the transfer once the retained buffer
@@ -3660,15 +3677,17 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
             // any wait, so a far-forward seek can't deadlock against a
             // suspended producer).
             var toSuspend: URLSessionDataTask?
-            if !self.streamingTaskSuspended, self.streamBuffer.count > Self.streamHighWater {
+            if !self.streamingTaskSuspended, self.streamBuffer.count > self.streamHighWater {
                 self.streamingTaskSuspended = true
                 toSuspend = self.streamingTask
             }
             self.streamLock.unlock()
             if let toCancel {
                 EngineLog.emit(
-                    "[AVIOReader] \(self.label) streaming buffer passed \(Self.streamHardCap / 1024 / 1024)MB "
-                    + "with the transfer suspended; ending it (audit DMX-7)", category: .demux)
+                    "[AVIOReader] \(self.label) streaming buffer passed \(self.streamHardCap / 1024)KB "
+                    + "with the transfer suspended: the origin ignores flow control, so the source is "
+                    + "ended here to keep memory bounded and the read will fail (audit DMX-7, DMX-107)",
+                    category: .demux)
                 toCancel.cancel()
             } else {
                 toSuspend?.suspend()
@@ -5242,6 +5261,10 @@ enum AVIOReaderError: Error, Equatable, CustomStringConvertible, LocalizedError
     /// fails at the first response head. A plain media URL on such an origin plays forward-only
     /// instead (audit DMX-101).
     case originIgnoresRange
+    /// Audit DMX-107: a forward-only source kept delivering after the reader paused it, past the
+    /// streaming buffer's hard cap, so the source was ended to keep memory bounded. The read that
+    /// follows fails with EIO, and `AVIOReader.lastReadFailure` says why.
+    case originIgnoresFlowControl
 
     var description: String {
         switch self {
@@ -5255,6 +5278,8 @@ enum AVIOReaderError: Error, Equatable, CustomStringConvertible, LocalizedError
             return TransportSecurityFailure.sentence(for: code)
         case .originIgnoresRange:
             return "The origin ignores HTTP Range requests, which a remote disc image needs"
+        case .originIgnoresFlowControl:
+            return "The origin kept sending after the reader paused it, past the streaming buffer's bound"
         }
     }
 
diff --git a/Tests/AetherEngineTests/StreamingBufferBoundTests.swift b/Tests/AetherEngineTests/StreamingBufferBoundTests.swift
new file mode 100644
index 000000000..60ba40fb7
--- /dev/null
+++ b/Tests/AetherEngineTests/StreamingBufferBoundTests.swift
@@ -0,0 +1,76 @@
+import Testing
+import Foundation
+@testable import AetherEngine
+
+/// Audit DMX-107: the forward-only reader pauses its transfer at a high water and ends it at twice
+/// that, because the pause is advisory. The end was a bare EIO, indistinguishable from a dropped
+/// connection. It now carries a typed cause, and memory stays bounded either way.
+@Suite("Forward-only streaming buffer bound")
+struct StreamingBufferBoundTests {
+
+    private func drain(_ reader: AVIOReader) -> (read: Int, last: Int32) {
+        let chunk = 64 * 1024
+        let buf = UnsafeMutablePointer<UInt8>.allocate(capacity: chunk)
+        defer { buf.deallocate() }
+        var read = 0
+        while true {
+            let n = reader.read(into: buf, size: Int32(chunk))
+            if n <= 0 { return (read, n) }
+            read += Int(n)
+        }
+    }
+
+    @Test("a transport that delivers past the hard cap ends the read with a typed cause",
+          .timeLimit(.minutes(1)))
+    func hardCapIsTyped() throws {
+        let maybe = ThrottledOriginServer(totalSize: 8 * 1024 * 1024, throttleUs: 0)
+        let server = try #require(maybe)
+        defer { server.stop() }
+        // One delivery is larger than twice this, so the cap is passed without depending on
+        // whether the transport honours the pause that comes first.
+        let reader = AVIOReader(url: URL(string: "http://127.0.0.1:\(server.port)/archive.ts")!,
+                                sequentialOnly: true, streamHighWater: 1024)
+        defer { reader.markClosed(); reader.close() }
+        try reader.open()
+
+        let result = drain(reader)
+        #expect(result.last == FFmpegErr.eio, "a source ended at the cap is lost, not finished")
+        #expect(reader.lastReadFailure == .originIgnoresFlowControl)
+        #expect(result.read < 8 * 1024 * 1024, "the cap let the whole body through")
+        #expect(reader.streamPeakBufferBytesForTesting < 2 * 1024 * 1024,
+                "the buffer held \(reader.streamPeakBufferBytesForTesting / 1024) KB")
+    }
+
+    @Test("a body that finishes inside the bound is EOF with no failure", .timeLimit(.minutes(1)))
+    func completeBodyHasNoFailure() throws {
+        let maybe = ThrottledOriginServer(totalSize: 2 * 1024 * 1024, throttleUs: 0)
+        let server = try #require(maybe)
+        defer { server.stop() }
+        let reader = AVIOReader(url: URL(string: "http://127.0.0.1:\(server.port)/archive.ts")!,
+                                sequentialOnly: true)
+        defer { reader.markClosed(); reader.close() }
+        try reader.open()
+
+        let result = drain(reader)
+        #expect(result.read == 2 * 1024 * 1024)
+        #expect(result.last == FFmpegErr.eof)
+        #expect(reader.lastReadFailure == nil)
+    }
+
+    @Test("a dropped connection is EIO without a cause of ours", .timeLimit(.minutes(1)))
+    func droppedConnectionHasNoCause() throws {
+        let total: Int64 = 8 * 1024 * 1024
+        let maybe = ThrottledOriginServer(totalSize: total, throttleUs: 0,
+                                          respond: { _, _, _ in .serveThenDrop(afterBytes: 1024 * 1024) })
+        let server = try #require(maybe)
+        defer { server.stop() }
+        let reader = AVIOReader(url: URL(string: "http://127.0.0.1:\(server.port)/archive.ts")!,
+                                sequentialOnly: true)
+        defer { reader.markClosed(); reader.close() }
+        try reader.open()
+
+        let result = drain(reader)
+        #expect(result.last == FFmpegErr.eio)
+        #expect(reader.lastReadFailure == nil, "a lost connection is the network's, not the origin's flow control")
+    }
+}

From dc1782868379898ffe2e2d200d706bbc346e75f2 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 09:17:39 +0200
Subject: [PATCH 211/359] fix(demuxer): a closed demuxer never reports the
 source's end of file (audit SEG-104)

The abort of a parked read (markClosed) reaches some demuxers as AVERROR_EOF, and the read funnel
returned that as nil, which every consumer acts on as "the source ended" (tail adopt, bridge
flush, onSequentialSourceEnded). readDemuxedPacketLocked now throws readFailed(AVERROR_EXIT)
for an EOF on a demuxer that has been marked closed; a real end of file on an open demuxer is
unchanged. The pump's existing catch-path remap (HLS-1) and its EOF remap (SEG-104 part A, pump
half) compose with it: a stop still exits as .stopRequested.

The two hosts that turned a demux read failure into a playback error now check their stop flag
first, since the abort a stop causes reads as a failure now instead of a silent end: the audio
host's read loop and the software host's live reader.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../Audio/AudioPlaybackHost.swift             |   3 +
 Sources/AetherEngine/Demuxer/Demuxer.swift    |  19 ++-
 .../AetherEngine/FFmpegErrorConstants.swift   |   3 +
 .../Native/SoftwarePlaybackHost.swift         |   3 +
 .../AbortedReadIsNotEndOfFileTests.swift      | 143 ++++++++++++++++++
 5 files changed, 166 insertions(+), 5 deletions(-)
 create mode 100644 Tests/AetherEngineTests/AbortedReadIsNotEndOfFileTests.swift

diff --git a/Sources/AetherEngine/Audio/AudioPlaybackHost.swift b/Sources/AetherEngine/Audio/AudioPlaybackHost.swift
index 4340190b7..ef266e088 100644
--- a/Sources/AetherEngine/Audio/AudioPlaybackHost.swift
+++ b/Sources/AetherEngine/Audio/AudioPlaybackHost.swift
@@ -442,6 +442,9 @@ final class AudioPlaybackHost {
             do {
                 packet = try demuxer.readPacket()
             } catch {
+                // Audit SEG-104: a stop closes the demuxer, which aborts a parked read. That is the
+                // stop arriving, not a playback failure.
+                if stopRequested() { return false }
                 EngineLog.emit("[AudioHost] demux read failed: \(error)", category: .swPlayback)
                 onError("Playback error: \(error.localizedDescription)")
                 return false
diff --git a/Sources/AetherEngine/Demuxer/Demuxer.swift b/Sources/AetherEngine/Demuxer/Demuxer.swift
index 4fc9e16fa..a675aa551 100644
--- a/Sources/AetherEngine/Demuxer/Demuxer.swift
+++ b/Sources/AetherEngine/Demuxer/Demuxer.swift
@@ -1816,6 +1816,18 @@ public final class Demuxer: @unchecked Sendable {
         return packet
     }
 
+    /// What a failed `av_read_frame` means for a demuxer in this state: the code to throw, or nil for
+    /// the source's own end of file.
+    ///
+    /// Audit SEG-104: the abort of a parked read (`markClosed()`) reaches some demuxers as end of
+    /// file, and "the source ended" is a verdict every consumer acts on (tail adopt, bridge flush,
+    /// `onSequentialSourceEnded`). A closed demuxer has no verdict to give, so an EOF it reports is
+    /// the abort, and it says so.
+    static func readFailureCode(_ ret: Int32, closeRequested: Bool) -> Int32? {
+        guard ret == FFmpegErr.eof else { return ret }
+        return closeRequested ? FFmpegErr.exit : nil
+    }
+
     /// One `av_read_frame`, as libavformat delivers it. Caller holds `accessLock`.
     private func readDemuxedPacketLocked() throws -> UnsafeMutablePointer<AVPacket>? {
         guard let ctx = formatContext else { return nil }
@@ -1833,11 +1845,8 @@ public final class Demuxer: @unchecked Sendable {
         }
         if ret < 0 {
             trackedPacketFree(&packet)
-            let isEOF = (ret == FFmpegErr.eof)
-            if isEOF {
-                return nil
-            }
-            throw DemuxerError.readFailed(code: ret)
+            guard let code = Self.readFailureCode(ret, closeRequested: isCloseRequested) else { return nil }
+            throw DemuxerError.readFailed(code: code)
         }
         if let pkt = packet { boundTimestampsLocked(pkt) }
         // #407: before anything reads a timestamp off this packet. The PTS on these streams was
diff --git a/Sources/AetherEngine/FFmpegErrorConstants.swift b/Sources/AetherEngine/FFmpegErrorConstants.swift
index ba5e01a1b..6f4c22da7 100644
--- a/Sources/AetherEngine/FFmpegErrorConstants.swift
+++ b/Sources/AetherEngine/FFmpegErrorConstants.swift
@@ -9,6 +9,9 @@ enum FFmpegErr {
     static let eagain: Int32 = -35
     /// `AVERROR_INVALIDDATA` = FFERRTAG('I','N','D','A') = -0x41444E49.
     static let invalidData: Int32 = -0x41444E49
+    /// `AVERROR_EXIT` = FFERRTAG('E','X','I','T') = -0x54495845: "immediate exit was requested", what
+    /// libavformat answers when its interrupt callback fires.
+    static let exit: Int32 = -0x54495845
     /// `AVERROR(EINVAL)`; EINVAL is POSIX 22 on Apple platforms. Some decoders (notably `dca` on a
     /// DTS-HD MA XLL frame that residual-codes channels without a usable core) reject a single packet
     /// with this while staying usable for the next one (#64).
diff --git a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
index 7cf6dd858..316095f25 100644
--- a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
+++ b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
@@ -1907,6 +1907,9 @@ final class SoftwarePlaybackHost {
             do {
                 packet = try demuxer.readPacket()
             } catch {
+                // Audit SEG-104: a stop closes the demuxer, which aborts a parked read. That is the
+                // stop arriving, not a lost source.
+                if stopRequested() { return false }
                 EngineLog.emit("[SWHost] live reader read failed: \(error)", category: .swPlayback)
                 onError("Playback error: \(error.localizedDescription)")
                 onSourceEnded()
diff --git a/Tests/AetherEngineTests/AbortedReadIsNotEndOfFileTests.swift b/Tests/AetherEngineTests/AbortedReadIsNotEndOfFileTests.swift
new file mode 100644
index 000000000..af59ad4a3
--- /dev/null
+++ b/Tests/AetherEngineTests/AbortedReadIsNotEndOfFileTests.swift
@@ -0,0 +1,143 @@
+import Testing
+import Foundation
+import AetherLibavcodec
+@testable import AetherEngine
+
+/// Audit SEG-104 (A), demuxer half: the abort of a parked read (`markClosed()`) is reported by
+/// Matroska, TS and fMP4 as end of file, and `readDemuxedPacketLocked` returned it as nil, which every
+/// consumer reads as "the source ended". A demuxer that has been closed never reports that: the read
+/// throws, so an aborted read cannot be mistaken for a real end of file.
+@Suite("An aborted read is not the end of the source", .serialized)
+struct AbortedReadIsNotEndOfFileTests {
+
+    /// Serves the fixture a few bytes at a time and, once armed, parks the read that reaches
+    /// `blockAt` until released, then answers it with end of file.
+    private final class ParkingReader: IOReader, @unchecked Sendable {
+        private let bytes: Data
+        private let condition = NSCondition()
+        private var position = 0
+        private var blockAt: Int?
+        private var parked = false
+        private var released = false
+
+        init(_ bytes: Data) { self.bytes = bytes }
+
+        func arm(blockAt offset: Int) { condition.withLock { blockAt = offset } }
+        var isParked: Bool { condition.withLock { parked } }
+        func release() {
+            condition.lock()
+            released = true
+            condition.broadcast()
+            condition.unlock()
+        }
+
+        func read(_ buffer: UnsafeMutablePointer<UInt8>?, size: Int32) -> Int32 {
+            guard let buffer, size > 0 else { return -1 }
+            condition.lock()
+            defer { condition.unlock() }
+            if let blockAt, position >= blockAt {
+                parked = true
+                while !released { condition.wait() }
+                return 0
+            }
+            var n = min(Int(size), 64, bytes.count - position)
+            if let blockAt { n = min(n, blockAt - position) }
+            guard n > 0 else { return 0 }
+            bytes.withUnsafeBytes { raw in _ = memcpy(buffer, raw.baseAddress! + position, n) }
+            position += n
+            return Int32(n)
+        }
+
+        func seek(offset: Int64, whence: Int32) -> Int64 {
+            condition.withLock {
+                switch whence {
+                case 65536: return Int64(bytes.count)
+                case SEEK_SET: position = Int(max(0, min(offset, Int64(bytes.count))))
+                case SEEK_CUR: position = max(0, min(position + Int(offset), bytes.count))
+                case SEEK_END: position = max(0, min(bytes.count + Int(offset), bytes.count))
+                default: return -1
+                }
+                return Int64(position)
+            }
+        }
+
+        func close() {}
+        var discImageProbeEnabled: Bool { false }
+    }
+
+    private final class ReadOutcome: @unchecked Sendable {
+        enum Kind: Sendable { case endOfFile, threw }
+        private let lock = NSLock()
+        private var _kind: Kind?
+        var kind: Kind? { lock.withLock { _kind } }
+        func finish(_ kind: Kind) { lock.withLock { _kind = kind } }
+    }
+
+    /// The SimpleBlock boundary the Issue234 fixture's open never reads past, so the parked read
+    /// comes back as a clean end of file rather than a torn element.
+    private static let parkOffset = 2237
+
+    private func fixture() throws -> Data {
+        try #require(Data(base64Encoded: Issue234SideReaderSeekAnchorTests.fixtureBase64,
+                          options: .ignoreUnknownCharacters))
+    }
+
+    private func drain(_ demuxer: Demuxer, into outcome: ReadOutcome) {
+        Thread.detachNewThread {
+            do {
+                while let read = try demuxer.readPacket() {
+                    var packet: UnsafeMutablePointer<AVPacket>? = read
+                    trackedPacketFree(&packet)
+                }
+                outcome.finish(.endOfFile)
+            } catch {
+                outcome.finish(.threw)
+            }
+        }
+    }
+
+    @Test("a failed read is the source's end only while nobody has closed the demuxer")
+    func readFailureClassification() {
+        #expect(Demuxer.readFailureCode(FFmpegErr.eof, closeRequested: false) == nil,
+                "a real end of file must stay the end of the source")
+        #expect(Demuxer.readFailureCode(FFmpegErr.eof, closeRequested: true) == FFmpegErr.exit,
+                "an end of file on a closed demuxer is the abort, not the source's")
+        for code in [FFmpegErr.eio, FFmpegErr.invalidData, FFmpegErr.exit, -1] {
+            #expect(Demuxer.readFailureCode(code, closeRequested: false) == code)
+            #expect(Demuxer.readFailureCode(code, closeRequested: true) == code)
+        }
+    }
+
+    @Test("a read that the close aborts throws instead of reporting the end of the source",
+          .timeLimit(.minutes(1)))
+    func abortedReadThrows() async throws {
+        let reader = ParkingReader(try fixture())
+        let demuxer = Demuxer()
+        try demuxer.open(reader: reader, formatHint: "matroska")
+        defer { demuxer.close() }
+        reader.arm(blockAt: Self.parkOffset)
+
+        let outcome = ReadOutcome()
+        drain(demuxer, into: outcome)
+        try await waitFor { reader.isParked }
+        demuxer.markClosed()
+        reader.release()
+        try await waitFor { outcome.kind != nil }
+
+        #expect(outcome.kind == .threw, "the aborted read was reported as the end of the source")
+    }
+
+    @Test("the end of a source nobody closed is still the end of the source",
+          .timeLimit(.minutes(1)))
+    func realEndOfFileIsStillNil() async throws {
+        let demuxer = Demuxer()
+        try demuxer.open(reader: ParkingReader(try fixture()), formatHint: "matroska")
+        defer { demuxer.close() }
+
+        let outcome = ReadOutcome()
+        drain(demuxer, into: outcome)
+        try await waitFor { outcome.kind != nil }
+
+        #expect(outcome.kind == .endOfFile)
+    }
+}

From 950ecaacced76c5570fa5ac2906aa58760e26e9e Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 09:17:56 +0200
Subject: [PATCH 212/359] fix(ingest): segment, key and audio tap bodies are
 bounded while they arrive, in chunks (audit NET-112, NET-113, DEC-103)

The ingest readers fetched segments and AES keys with session.data(for:), which holds the whole body
before anyone can look at its size, and the audio tap fetcher did the same for playlists, segments
and keys. BoundedFetch is one delegate-based fetch: it judges the response head (non-2xx or a
declared length over the cap ends the transfer there), accumulates the body in the chunks the session
delivers and cancels at the cap. A segment may weigh 20 MB/s of its EXTINF between 32 MiB and 256
MiB (UHD remux segments run 75 to 125 MB), a key 64 bytes. BoundedPlaylistFetch keeps its contract on
top of it, and no longer appends one byte at a time (32 MiB took 5 s in a debug build, 0.14 s now).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../Audio/Tap/AudioTapHLSFetcher.swift        |  20 +-
 .../IO/HLSIngest/BoundedPlaylistFetch.swift   | 181 +++++++++++-
 .../IO/HLSIngest/HLSLiveIngestReader.swift    |  22 +-
 .../IO/HLSIngest/HLSVODIngestReader.swift     |  16 +-
 .../AetherEngineTests/BoundedFetchTests.swift | 268 ++++++++++++++++++
 5 files changed, 482 insertions(+), 25 deletions(-)
 create mode 100644 Tests/AetherEngineTests/BoundedFetchTests.swift

diff --git a/Sources/AetherEngine/Audio/Tap/AudioTapHLSFetcher.swift b/Sources/AetherEngine/Audio/Tap/AudioTapHLSFetcher.swift
index fc407aff5..4b8a3bfcb 100644
--- a/Sources/AetherEngine/Audio/Tap/AudioTapHLSFetcher.swift
+++ b/Sources/AetherEngine/Audio/Tap/AudioTapHLSFetcher.swift
@@ -41,16 +41,26 @@ final class AudioTapHLSFetcher: @unchecked Sendable {
         credentials = CredentialScope(headers: httpHeaders, anchor: credentialOrigin)
     }
 
-    private func get(_ url: URL) async throws -> (Data, URLResponse) {
+    /// Audit DEC-103: every body is cut off at its cap while it arrives. Playlists take the ingest
+    /// readers' 8 MiB, keys 64 bytes, and a segment, which here is audio only, the floor of the
+    /// duration-derived video cap.
+    private static let maximumPlaylistBytes = 8 * 1024 * 1024
+    private static let maximumSegmentBytes = BoundedFetch.segmentLimit(forDuration: 0)
+
+    private func get(_ url: URL, limit: Int) async throws -> (Data, URLResponse) {
         var request = URLRequest(url: url)
         for (field, value) in credentials.headers(for: url) {
             request.setValue(value, forHTTPHeaderField: field)
         }
-        return try await session.data(for: request)
+        do {
+            return try await BoundedFetch.data(for: request, session: session, limit: limit)
+        } catch let error as BoundedFetch.Exceeded {
+            throw FetchError.invalidPlaylist("body exceeds \(error.limit) bytes")
+        }
     }
 
     func fetchPlaylist(_ url: URL) async throws -> (HLSPlaylist, URL) {
-        let (data, response) = try await get(url)
+        let (data, response) = try await get(url, limit: Self.maximumPlaylistBytes)
         let status = (response as? HTTPURLResponse)?.statusCode ?? -1
         guard (200..<300).contains(status) else { throw FetchError.http(status) }
         guard let text = String(data: data, encoding: .utf8) else {
@@ -60,7 +70,7 @@ final class AudioTapHLSFetcher: @unchecked Sendable {
     }
 
     func fetchSegment(_ url: URL, crypt: HLSSegmentCrypt?, base: URL) async throws -> Data {
-        let (data, response) = try await get(url)
+        let (data, response) = try await get(url, limit: Self.maximumSegmentBytes)
         let status = (response as? HTTPURLResponse)?.statusCode ?? -1
         if status == 404 { return Data() }               // slid out of window; caller advances
         guard (200..<300).contains(status) else { throw FetchError.http(status) }
@@ -78,7 +88,7 @@ final class AudioTapHLSFetcher: @unchecked Sendable {
     private func fetchKey(_ url: URL) async throws -> Data {
         let cacheKey = url.absoluteString
         if let cached = keyCacheLock.withLock({ keyCache[cacheKey] }) { return cached }
-        let (data, response) = try await get(url)
+        let (data, response) = try await get(url, limit: BoundedFetch.keyLimit)
         let status = (response as? HTTPURLResponse)?.statusCode ?? -1
         guard (200..<300).contains(status), data.count == 16 else { throw FetchError.http(status) }
         keyCacheLock.withLock { keyCache[cacheKey] = data }
diff --git a/Sources/AetherEngine/IO/HLSIngest/BoundedPlaylistFetch.swift b/Sources/AetherEngine/IO/HLSIngest/BoundedPlaylistFetch.swift
index 7692eb9fd..cf9368ca2 100644
--- a/Sources/AetherEngine/IO/HLSIngest/BoundedPlaylistFetch.swift
+++ b/Sources/AetherEngine/IO/HLSIngest/BoundedPlaylistFetch.swift
@@ -13,22 +13,179 @@ enum BoundedPlaylistFetch {
     static func data(for request: URLRequest, session: URLSession, limit: Int) async throws
         -> (Data, URLResponse)
     {
-        let (bytes, response) = try await session.bytes(for: request)
-        defer { bytes.task.cancel() }
+        do {
+            return try await BoundedFetch.data(for: request, session: session, limit: limit)
+        } catch let error as BoundedFetch.Exceeded {
+            throw HLSIngestError.playlistInvalid(reason: "playlist exceeds \(error.limit) bytes")
+        }
+    }
+}
+
+/// One bounded HTTP body fetch for everything that holds a whole body in memory: playlists, key
+/// files, transport-stream segments, WebVTT segments (audit NET-112, FEA-107, DEC-103, SUB-106).
+///
+/// A delegate rather than `session.data(for:)`, which buffers the whole body before a caller sees its
+/// size, and rather than iterating `AsyncBytes`, which delivered one byte per step into a per-byte
+/// `Data.append`, about 16 ms per MB (audit NET-113). The response head is judged before any body is
+/// read: a non-2xx answer or a declared length over `limit` ends the transfer there. The body then
+/// arrives in the chunks the session delivers and the transfer is cancelled the moment it passes
+/// `limit`, so the peak is the limit plus one delivery.
+enum BoundedFetch {
+
+    struct Exceeded: Error, Equatable {
+        let limit: Int
+    }
+
+    /// An AES-128 key is 16 bytes; the callers keep their own `== 16` check.
+    static let keyLimit = 64
+
+    /// One WebVTT segment of a live subtitle rendition carries a few cues.
+    static let webVTTSegmentLimit = 1024 * 1024
+
+    /// What a transport-stream segment of `seconds` may weigh: 20 MB/s of its own duration, between
+    /// 32 MiB and 256 MiB. UHD remux HLS runs 6 to 10 s segments at about 100 Mbps (75 to 125 MB), so
+    /// a small fixed cap would refuse the content the path exists for.
+    static func segmentLimit(forDuration seconds: Double) -> Int {
+        let floor = 32.0 * 1024 * 1024
+        let ceiling = 256.0 * 1024 * 1024
+        guard seconds.isFinite, seconds > 0 else { return Int(floor) }
+        return Int(min(ceiling, max(floor, seconds * 20_000_000)))
+    }
+
+    /// The body and response of `request`. A non-2xx answer comes back with an empty body, since every
+    /// caller decides on the status alone. Throws `Exceeded` for a body over `limit`.
+    static func data(for request: URLRequest, session: URLSession, limit: Int) async throws
+        -> (Data, URLResponse)
+    {
+        let delegate = BoundedBodyDelegate(limit: limit)
+        defer { withExtendedLifetime(delegate) {} }
+        let task = session.dataTask(with: request)
+        task.delegate = delegate
+        let outcome: BoundedBodyDelegate.Outcome = try await withTaskCancellationHandler {
+            try await withCheckedThrowingContinuation { continuation in
+                // Installed through the delegate's own lock, and it replays an outcome that has already
+                // landed: `onCancel` runs on the spot for a task that is already cancelled, so the
+                // transfer can end before this line.
+                delegate.installOutcomeHandler { continuation.resume(returning: $0) }
+                task.resume()
+            }
+        } onCancel: {
+            task.cancel()
+        }
+        switch outcome {
+        case .body(let data, let response): return (data, response)
+        case .refused(let response): return (Data(), response)
+        case .exceeded: throw Exceeded(limit: limit)
+        case .failed(let error): throw error
+        }
+    }
+}
+
+private final class BoundedBodyDelegate: EngineTLS.RedirectScrubbingDelegate, URLSessionDataDelegate,
+    @unchecked Sendable
+{
+    enum Outcome {
+        case body(Data, URLResponse)
+        case refused(URLResponse)
+        case exceeded
+        case failed(Error)
+    }
+
+    private enum Verdict {
+        case refused
+        case exceeded
+    }
+
+    private let limit: Int
+    private var buffer = Data()
+    private var response: URLResponse?
+    private var verdict: Verdict?
+
+    /// Guards the handoff between the caller, which installs the handler, and the session's delegate
+    /// queue, which produces the outcome. Either can be first.
+    private let handoff = NSLock()
+    private var onOutcome: ((Outcome) -> Void)?
+    private var landed: Outcome?
+
+    init(limit: Int) {
+        self.limit = limit
+        super.init()
+    }
+
+    func installOutcomeHandler(_ handler: @escaping (Outcome) -> Void) {
+        handoff.lock()
+        if let landed {
+            self.landed = nil
+            handoff.unlock()
+            handler(landed)
+            return
+        }
+        onOutcome = handler
+        handoff.unlock()
+    }
+
+    private func deliver(_ outcome: Outcome) {
+        handoff.lock()
+        guard let handler = onOutcome else {
+            landed = outcome
+            handoff.unlock()
+            return
+        }
+        onOutcome = nil
+        handoff.unlock()
+        handler(outcome)
+    }
+
+    func urlSession(_ session: URLSession, task: URLSessionTask,
+                    didReceive challenge: URLAuthenticationChallenge,
+                    completionHandler: @escaping (URLSession.AuthChallengeDisposition, URLCredential?) -> Void) {
+        EngineTLS.resolve(challenge, completionHandler: completionHandler)
+    }
+
+    func urlSession(_ session: URLSession, dataTask: URLSessionDataTask, didReceive response: URLResponse,
+                    completionHandler: @escaping (URLSession.ResponseDisposition) -> Void) {
+        self.response = response
         let status = (response as? HTTPURLResponse)?.statusCode ?? -1
-        guard (200..<300).contains(status) else { return (Data(), response) }
+        guard (200..<300).contains(status) else {
+            verdict = .refused
+            completionHandler(.cancel)
+            return
+        }
         let declared = response.expectedContentLength
-        guard declared <= Int64(limit) else { throw exceeded(limit) }
-        var data = Data()
-        if declared > 0 { data.reserveCapacity(Int(declared)) }
-        for try await byte in bytes {
-            guard data.count < limit else { throw exceeded(limit) }
-            data.append(byte)
+        guard declared <= Int64(limit) else {
+            verdict = .exceeded
+            completionHandler(.cancel)
+            return
         }
-        return (data, response)
+        if declared > 0 { buffer.reserveCapacity(Int(min(declared, 8 * 1024 * 1024))) }
+        completionHandler(.allow)
     }
 
-    private static func exceeded(_ limit: Int) -> HLSIngestError {
-        .playlistInvalid(reason: "playlist exceeds \(limit) bytes")
+    func urlSession(_ session: URLSession, dataTask: URLSessionDataTask, didReceive data: Data) {
+        guard verdict == nil else { return }
+        guard buffer.count + data.count <= limit else {
+            verdict = .exceeded
+            buffer = Data()
+            dataTask.cancel()
+            return
+        }
+        buffer.append(data)
+    }
+
+    func urlSession(_ session: URLSession, task: URLSessionTask, didCompleteWithError error: Error?) {
+        switch verdict {
+        case .refused?:
+            if let response { deliver(.refused(response)) } else { deliver(.failed(URLError(.badServerResponse))) }
+        case .exceeded?:
+            deliver(.exceeded)
+        case nil:
+            if let error {
+                deliver(.failed(error))
+            } else if let response {
+                deliver(.body(buffer, response))
+            } else {
+                deliver(.failed(URLError(.badServerResponse)))
+            }
+        }
     }
 }
diff --git a/Sources/AetherEngine/IO/HLSIngest/HLSLiveIngestReader.swift b/Sources/AetherEngine/IO/HLSIngest/HLSLiveIngestReader.swift
index 36d591014..e272bbf06 100644
--- a/Sources/AetherEngine/IO/HLSIngest/HLSLiveIngestReader.swift
+++ b/Sources/AetherEngine/IO/HLSIngest/HLSLiveIngestReader.swift
@@ -394,7 +394,7 @@ public final class HLSLiveIngestReader: IOReader, LiveIngestSourceInfo, @uncheck
         mediaURL: URL
     ) {
         group.addTask {
-            let fetched = try await self.fetchSegment(item.url)
+            let fetched = try await self.fetchSegment(item.url, duration: item.segment.duration)
             guard !fetched.isEmpty, let crypt = item.segment.crypt else { return (index, fetched) }
             return (index, try await self.decryptSegment(fetched, crypt: crypt, against: mediaURL))
         }
@@ -581,12 +581,19 @@ public final class HLSLiveIngestReader: IOReader, LiveIngestSourceInfo, @uncheck
         return (try HLSPlaylistParser.parse(text), response.url ?? url)
     }
 
-    private func fetchSegment(_ url: URL) async throws -> Data {
+    private func fetchSegment(_ url: URL, duration: Double) async throws -> Data {
         var lastStatus = -1
+        let limit = BoundedFetch.segmentLimit(forDuration: duration)
         for attempt in 0..<3 {
             if Task.isCancelled { throw CancellationError() }
             do {
-                let (data, response) = try await session.data(for: makeRequest(url))
+                let (data, response): (Data, URLResponse)
+                do {
+                    (data, response) = try await BoundedFetch.data(for: makeRequest(url), session: session, limit: limit)
+                } catch is BoundedFetch.Exceeded {
+                    // Audit NET-112: an endless body is the origin's answer, not a blip to retry.
+                    throw HLSIngestError.playlistInvalid(reason: "segment exceeds \(limit) bytes")
+                }
                 lastStatus = (response as? HTTPURLResponse)?.statusCode ?? -1
                 if (200..<300).contains(lastStatus) { return data }
                 if lastStatus == 404 { return Data() } // slid out of provider window; tracker advances regardless
@@ -619,7 +626,14 @@ public final class HLSLiveIngestReader: IOReader, LiveIngestSourceInfo, @uncheck
         let cacheKey = url.absoluteString
         if let cached = keyCacheLock.withLock({ keyCache[cacheKey] }) { return cached }
 
-        let (data, response) = try await session.data(for: makeRequest(url))
+        let data: Data
+        let response: URLResponse
+        do {
+            (data, response) = try await BoundedFetch.data(
+                for: makeRequest(url), session: session, limit: BoundedFetch.keyLimit)
+        } catch is BoundedFetch.Exceeded {
+            throw HLSIngestError.segmentDecryptFailed(reason: "key exceeds \(BoundedFetch.keyLimit) bytes")
+        }
         let status = (response as? HTTPURLResponse)?.statusCode ?? -1
         guard (200..<300).contains(status) else {
             throw HLSIngestError.segmentDecryptFailed(reason: "key fetch HTTP \(status)")
diff --git a/Sources/AetherEngine/IO/HLSIngest/HLSVODIngestReader.swift b/Sources/AetherEngine/IO/HLSIngest/HLSVODIngestReader.swift
index b0e51a7d6..f2d0b5853 100644
--- a/Sources/AetherEngine/IO/HLSIngest/HLSVODIngestReader.swift
+++ b/Sources/AetherEngine/IO/HLSIngest/HLSVODIngestReader.swift
@@ -384,7 +384,8 @@ final class HLSVODIngestReader: TimeSeekableIOReader, @unchecked Sendable {
             func spawn(_ index: Int) {
                 let item = resolvedSegments[index]
                 group.addTask {
-                    let bytes = try await self.fetch(item.1)
+                    let bytes = try await self.fetch(
+                        item.1, limit: BoundedFetch.segmentLimit(forDuration: item.0.duration))
                     guard let crypt = item.0.crypt else { return (index, bytes) }
                     return (
                         index,
@@ -533,8 +534,15 @@ final class HLSVODIngestReader: TimeSeekableIOReader, @unchecked Sendable {
         return (try HLSPlaylistParser.parse(text), response.url ?? url)
     }
 
-    private func fetch(_ url: URL) async throws -> Data {
-        let (data, response) = try await session.data(for: makeRequest(url))
+    /// A segment or a key body, cut off at `limit` while it arrives (audit NET-112).
+    private func fetch(_ url: URL, limit: Int) async throws -> Data {
+        let data: Data
+        let response: URLResponse
+        do {
+            (data, response) = try await BoundedFetch.data(for: makeRequest(url), session: session, limit: limit)
+        } catch is BoundedFetch.Exceeded {
+            throw HLSIngestError.playlistInvalid(reason: "body exceeds \(limit) bytes")
+        }
         let status = (response as? HTTPURLResponse)?.statusCode ?? -1
         guard (200..<300).contains(status), !data.isEmpty else {
             throw HLSIngestError.playlistUnreachable(status: status)
@@ -564,7 +572,7 @@ final class HLSVODIngestReader: TimeSeekableIOReader, @unchecked Sendable {
         if let cached = keyCacheLock.withLock({ keyCache[keyURL.absoluteString] }) {
             key = cached
         } else {
-            let fetched = try await fetch(keyURL)
+            let fetched = try await fetch(keyURL, limit: BoundedFetch.keyLimit)
             guard fetched.count == kCCKeySizeAES128 else {
                 throw HLSIngestError.segmentDecryptFailed(reason: "key length is not 16 bytes")
             }
diff --git a/Tests/AetherEngineTests/BoundedFetchTests.swift b/Tests/AetherEngineTests/BoundedFetchTests.swift
new file mode 100644
index 000000000..b2cc3d781
--- /dev/null
+++ b/Tests/AetherEngineTests/BoundedFetchTests.swift
@@ -0,0 +1,268 @@
+import Darwin
+import Foundation
+import Testing
+@testable import AetherEngine
+
+/// Audit NET-112 / FEA-107 / DEC-103 / NET-113: segment, key and rendition bodies were read with
+/// `session.data(for:)`, which holds the whole body before anyone can look at its size, and the
+/// playlist fetch appended one byte at a time. One bounded fetch now serves all of them.
+@Suite(.timeLimit(.minutes(2)))
+struct BoundedFetchTests {
+
+    private func makeSession() -> URLSession {
+        let configuration = URLSessionConfiguration.ephemeral
+        configuration.timeoutIntervalForRequest = 20
+        configuration.timeoutIntervalForResource = 60
+        return URLSession(configuration: configuration, delegate: EngineTLS.sessionDelegate, delegateQueue: nil)
+    }
+
+    private func request(_ origin: LoopbackBodyOrigin, _ path: String = "/body") -> URLRequest {
+        URLRequest(url: URL(string: "http://127.0.0.1:\(origin.port)\(path)")!)
+    }
+
+    @Test("an endless body with no declared length is cut off at the cap and the connection is dropped")
+    func endlessBodyIsCutOff() async throws {
+        let origin = try #require(LoopbackBodyOrigin(body: .endless(chunkBytes: 16 * 1024)))
+        defer { origin.stop() }
+        let session = makeSession()
+        defer { session.invalidateAndCancel() }
+        let limit = 512 * 1024
+        await #expect(throws: BoundedFetch.Exceeded(limit: limit)) {
+            _ = try await BoundedFetch.data(for: request(origin), session: session, limit: limit)
+        }
+        try await waitFor { origin.clientHungUp }
+        #expect(origin.bytesWritten < 200 * 1024 * 1024)
+    }
+
+    @Test("a key body is cut off at 64 bytes and a 16 byte key arrives whole")
+    func keyBodiesAreBounded() async throws {
+        let endless = try #require(LoopbackBodyOrigin(body: .endless(chunkBytes: 1024)))
+        let key = try #require(LoopbackBodyOrigin(body: .fixed(16)))
+        defer { endless.stop(); key.stop() }
+        let session = makeSession()
+        defer { session.invalidateAndCancel() }
+        await #expect(throws: BoundedFetch.Exceeded(limit: BoundedFetch.keyLimit)) {
+            _ = try await BoundedFetch.data(for: request(endless), session: session, limit: BoundedFetch.keyLimit)
+        }
+        let (data, response) = try await BoundedFetch.data(
+            for: request(key), session: session, limit: BoundedFetch.keyLimit)
+        #expect(data.count == 16)
+        #expect((response as? HTTPURLResponse)?.statusCode == 200)
+    }
+
+    @Test("a declared length over the cap is refused at the response head")
+    func declaredLengthIsRefusedAtTheHead() async throws {
+        let origin = try #require(LoopbackBodyOrigin(
+            body: .endless(chunkBytes: 16 * 1024), declaredLength: 8 * 1024 * 1024 * 1024))
+        defer { origin.stop() }
+        let session = makeSession()
+        defer { session.invalidateAndCancel() }
+        await #expect(throws: BoundedFetch.Exceeded(limit: 1024 * 1024)) {
+            _ = try await BoundedFetch.data(for: request(origin), session: session, limit: 1024 * 1024)
+        }
+        try await waitFor { origin.clientHungUp }
+        #expect(origin.bytesWritten < 16 * 1024 * 1024)
+    }
+
+    @Test("a refusal comes back with its status and no body")
+    func refusalKeepsItsStatus() async throws {
+        let origin = try #require(LoopbackBodyOrigin(body: .endless(chunkBytes: 4096), status: 404))
+        defer { origin.stop() }
+        let session = makeSession()
+        defer { session.invalidateAndCancel() }
+        let (data, response) = try await BoundedFetch.data(for: request(origin), session: session, limit: 1024)
+        #expect((response as? HTTPURLResponse)?.statusCode == 404)
+        #expect(data.isEmpty)
+    }
+
+    @Test("a body within the cap arrives whole and in order")
+    func bodyWithinTheCapArrivesWhole() async throws {
+        let size = 3 * 1024 * 1024 + 17
+        let origin = try #require(LoopbackBodyOrigin(body: .fixed(size), declaredLength: Int64(size)))
+        defer { origin.stop() }
+        let session = makeSession()
+        defer { session.invalidateAndCancel() }
+        let (data, _) = try await BoundedFetch.data(for: request(origin), session: session, limit: 4 * 1024 * 1024)
+        #expect(data.count == size)
+        #expect(data.prefix(4) == Data([0, 1, 2, 3]))
+    }
+
+    @Test("a cancelled fetch ends instead of waiting for its body")
+    func cancellationEndsTheFetch() async throws {
+        let origin = try #require(LoopbackBodyOrigin(body: .endless(chunkBytes: 4096)))
+        defer { origin.stop() }
+        let session = makeSession()
+        defer { session.invalidateAndCancel() }
+        let task = Task { [request = request(origin)] in
+            try await BoundedFetch.data(for: request, session: session, limit: 1 << 30)
+        }
+        try await waitFor { origin.bytesWritten > 0 }
+        task.cancel()
+        await #expect(throws: (any Error).self) { _ = try await task.value }
+        try await waitFor { origin.clientHungUp }
+    }
+
+    @Test("the playlist wrapper keeps its error text")
+    func playlistWrapperKeepsItsError() async throws {
+        let origin = try #require(LoopbackBodyOrigin(body: .endless(chunkBytes: 1024)))
+        defer { origin.stop() }
+        let session = makeSession()
+        defer { session.invalidateAndCancel() }
+        await #expect(throws: HLSIngestError.playlistInvalid(reason: "playlist exceeds 4096 bytes")) {
+            _ = try await BoundedPlaylistFetch.data(for: request(origin), session: session, limit: 4096)
+        }
+    }
+
+    @Test("32 MiB of body accumulates in chunks, not byte by byte")
+    func largeBodyAccumulatesQuickly() async throws {
+        let size = 32 * 1024 * 1024
+        let origin = try #require(LoopbackBodyOrigin(body: .fixed(size), declaredLength: Int64(size)))
+        defer { origin.stop() }
+        let session = makeSession()
+        defer { session.invalidateAndCancel() }
+        let started = ContinuousClock.now
+        let (data, _) = try await BoundedPlaylistFetch.data(for: request(origin), session: session, limit: 64 * 1024 * 1024)
+        let elapsed = ContinuousClock.now - started
+        #expect(data.count == size)
+        // The per-byte accumulation this replaced took 5 s for this body in a debug build.
+        #expect(elapsed < .seconds(1.5), "took \(elapsed)")
+    }
+
+    @Test("a segment may weigh 20 MB/s of its own duration between 32 MiB and 256 MiB")
+    func segmentLimitFollowsTheDuration() {
+        let floor = 32 * 1024 * 1024
+        let ceiling = 256 * 1024 * 1024
+        #expect(BoundedFetch.segmentLimit(forDuration: 0) == floor)
+        #expect(BoundedFetch.segmentLimit(forDuration: -4) == floor)
+        #expect(BoundedFetch.segmentLimit(forDuration: .nan) == floor)
+        #expect(BoundedFetch.segmentLimit(forDuration: .infinity) == floor)
+        #expect(BoundedFetch.segmentLimit(forDuration: 1) == floor)
+        #expect(BoundedFetch.segmentLimit(forDuration: 2) == 40_000_000)
+        #expect(BoundedFetch.segmentLimit(forDuration: 6) == 120_000_000)
+        // A 10 s UHD remux segment at 125 MB is inside its cap.
+        #expect(BoundedFetch.segmentLimit(forDuration: 10) >= 125_000_000)
+        #expect(BoundedFetch.segmentLimit(forDuration: 600) == ceiling)
+    }
+}
+
+/// A one-request-per-connection loopback origin whose body can be endless, to see a fetch end where
+/// its cap says and to count what the origin managed to write before the client hung up.
+private final class LoopbackBodyOrigin: @unchecked Sendable {
+    enum Body {
+        case endless(chunkBytes: Int)
+        case fixed(Int)
+    }
+
+    let port: UInt16
+    private let listenFD: Int32
+    private let body: Body
+    private let status: Int
+    private let declaredLength: Int64?
+    private let lock = NSLock()
+    private var _bytesWritten = 0
+    private var _clientHungUp = false
+    private var _connections: Set<Int32> = []
+
+    var bytesWritten: Int { lock.withLock { _bytesWritten } }
+    var clientHungUp: Bool { lock.withLock { _clientHungUp } }
+
+    init?(body: Body, status: Int = 200, declaredLength: Int64? = nil) {
+        self.body = body
+        self.status = status
+        self.declaredLength = declaredLength
+        let fd = socket(AF_INET, SOCK_STREAM, 0)
+        guard fd >= 0 else { return nil }
+        var one: Int32 = 1
+        setsockopt(fd, SOL_SOCKET, SO_REUSEADDR, &one, socklen_t(MemoryLayout<Int32>.size))
+        var address = sockaddr_in()
+        address.sin_family = sa_family_t(AF_INET)
+        address.sin_port = 0
+        address.sin_addr.s_addr = inet_addr("127.0.0.1")
+        let bound = withUnsafePointer(to: &address) {
+            $0.withMemoryRebound(to: sockaddr.self, capacity: 1) {
+                bind(fd, $0, socklen_t(MemoryLayout<sockaddr_in>.size))
+            }
+        }
+        guard bound == 0, listen(fd, 8) == 0 else {
+            close(fd)
+            return nil
+        }
+        var length = socklen_t(MemoryLayout<sockaddr_in>.size)
+        let named = withUnsafeMutablePointer(to: &address) {
+            $0.withMemoryRebound(to: sockaddr.self, capacity: 1) { getsockname(fd, $0, &length) }
+        }
+        guard named == 0 else {
+            close(fd)
+            return nil
+        }
+        listenFD = fd
+        port = UInt16(bigEndian: address.sin_port)
+        Thread.detachNewThread { [self] in acceptLoop() }
+    }
+
+    func stop() {
+        lock.lock()
+        for fd in _connections { shutdown(fd, SHUT_RDWR) }
+        lock.unlock()
+        shutdown(listenFD, SHUT_RDWR)
+        close(listenFD)
+    }
+
+    private func acceptLoop() {
+        while true {
+            let fd = accept(listenFD, nil, nil)
+            if fd < 0 { return }
+            var one: Int32 = 1
+            setsockopt(fd, SOL_SOCKET, SO_NOSIGPIPE, &one, socklen_t(MemoryLayout<Int32>.size))
+            lock.withLock { _ = _connections.insert(fd) }
+            Thread.detachNewThread { [self] in serve(fd) }
+        }
+    }
+
+    private func serve(_ fd: Int32) {
+        defer {
+            lock.withLock { _ = _connections.remove(fd) }
+            close(fd)
+        }
+        var received = Data()
+        var byte: UInt8 = 0
+        while !received.suffix(4).elementsEqual([13, 10, 13, 10]) {
+            guard recv(fd, &byte, 1, 0) == 1 else { return }
+            received.append(byte)
+        }
+        var head = "HTTP/1.1 \(status) X\r\nConnection: close\r\nContent-Type: video/mp2t\r\n"
+        if let declaredLength { head += "Content-Length: \(declaredLength)\r\n" }
+        head += "\r\n"
+        guard write(fd, Array(head.utf8)) else { return hangUp() }
+        switch body {
+        case .endless(let chunkBytes):
+            let chunk = [UInt8](repeating: 0x55, count: chunkBytes)
+            while write(fd, chunk) { lock.withLock { _bytesWritten += chunkBytes } }
+            hangUp()
+        case .fixed(let count):
+            // 64 KiB is a multiple of 256, so a repeated ramp stays one continuous ramp.
+            let ramp = (0..<64 * 1024).map { UInt8(truncatingIfNeeded: $0) }
+            var remaining = count
+            while remaining > 0 {
+                let size = min(remaining, ramp.count)
+                guard write(fd, size == ramp.count ? ramp : Array(ramp.prefix(size))) else { return hangUp() }
+                lock.withLock { _bytesWritten += size }
+                remaining -= size
+            }
+        }
+    }
+
+    private func hangUp() {
+        lock.withLock { _clientHungUp = true }
+    }
+
+    private func write(_ fd: Int32, _ bytes: [UInt8]) -> Bool {
+        var sent = 0
+        while sent < bytes.count {
+            let n = bytes.withUnsafeBytes { send(fd, $0.baseAddress! + sent, bytes.count - sent, 0) }
+            if n <= 0 { return false }
+            sent += n
+        }
+        return true
+    }
+}

From fb9cd2a7089418b5a24f08cde76b047025dd0b1e Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 09:20:07 +0200
Subject: [PATCH 213/359] perf(relay): never park the session's delegate queue
 for a consumer that stopped reading (audit NET-107)

UpstreamPump waited inside didReceive once a fetch held 4 MB its consumer
had not taken. The delegate queue is serial across every task on the relay's
session, so one receiver that stopped reading (iOS AirPlay against a
self-signed origin) held up the head and body of every other relayed fetch
for as long as the stall lasted.

The producer now appends without waiting and a fetch that falls more than
32 MiB behind is cancelled: the body the player was promised ends short, the
server closes the connection (the same shape as a transport error after the
head), and the player asks again. URLSessionTask.suspend() is not used,
because transports that ignore it were measured (#220) and suspended flows
correlated with every connection in the process going deaf (#310).

Against the old pump the new test reproduces the defect: with a stalled raw
socket on a 16 MB body, the origin's last write never completes and a second
relayed fetch through the same relay times out after 20 s (-1001). With the
change both finish at once.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../AetherEngine/Network/HLSOriginRelay.swift |  75 +++++--
 .../HLSOriginRelayStalledConsumerTests.swift  | 187 ++++++++++++++++++
 2 files changed, 244 insertions(+), 18 deletions(-)
 create mode 100644 Tests/AetherEngineTests/HLSOriginRelayStalledConsumerTests.swift

diff --git a/Sources/AetherEngine/Network/HLSOriginRelay.swift b/Sources/AetherEngine/Network/HLSOriginRelay.swift
index 88affd755..a559c6185 100644
--- a/Sources/AetherEngine/Network/HLSOriginRelay.swift
+++ b/Sources/AetherEngine/Network/HLSOriginRelay.swift
@@ -75,9 +75,19 @@ final class HLSOriginRelay: @unchecked Sendable {
     private let session: URLSession
 
     private let heldBodyLimit: Int
+    private let pendingLimit: Int
 
-    init(maximumHeldBodyBytes: Int = HLSOriginRelay.maximumHeldBodyBytes) {
+    /// Audit NET-107: fetches cut off because the consumer fell `pendingLimit` bytes behind. Diagnostics and tests.
+    var cappedFetchCount: Int {
+        stateLock.lock(); defer { stateLock.unlock() }
+        return _cappedFetchCount
+    }
+    private var _cappedFetchCount = 0
+
+    init(maximumHeldBodyBytes: Int = HLSOriginRelay.maximumHeldBodyBytes,
+         maximumPendingBytes: Int = HLSOriginRelay.maximumPendingBytes) {
         heldBodyLimit = maximumHeldBodyBytes
+        pendingLimit = maximumPendingBytes
         let config = URLSessionConfiguration.ephemeral
         config.requestCachePolicy = .reloadIgnoringLocalAndRemoteCacheData
         config.urlCache = nil
@@ -390,6 +400,11 @@ final class HLSOriginRelay: @unchecked Sendable {
     static let maximumHeldPlaylistBytes = 16 * 1024 * 1024
     static let maximumHeldBodyBytes = 64 * 1024 * 1024
 
+    /// Audit NET-107: what one streamed fetch may hold for a consumer that is not draining. Above any
+    /// segment a player asks for in one request, so a consumer that is merely slow is never cut off,
+    /// and far enough under a session's memory that a stalled one cannot turn it into a heap.
+    static let maximumPendingBytes = 32 * 1024 * 1024
+
     /// The answers that mean "you are asking too often", which arm the pacer for this origin.
     private static let refusalStatuses: Set<Int> = [429, 503, 509]
 
@@ -422,12 +437,15 @@ final class HLSOriginRelay: @unchecked Sendable {
             for: origin, label: "relay", timeout: Self.slotWaitSeconds)
         defer { OriginRequestBudget.shared.release(ticket) }
 
-        let pump = UpstreamPump()
+        let pump = UpstreamPump(hardCapBytes: pendingLimit) { [weak self] in
+            guard let self else { return }
+            self.stateLock.lock()
+            self._cappedFetchCount += 1
+            self.stateLock.unlock()
+        }
         let task = session.dataTask(with: request)
         task.delegate = pump
         task.resume()
-        // abandon before cancel: a body parked at the high-water mark is waiting on a consumer, and
-        // cancelling the task does not wake it.
         defer { pump.abandon(); task.cancel() }
 
         guard let http = pump.awaitHead() else {
@@ -577,14 +595,23 @@ final class HLSOriginRelay: @unchecked Sendable {
 /// land. Holding them here instead, and writing from the delegate callback, would put a socket the
 /// player has stopped reading in front of every other task on this session's serial delegate queue.
 ///
-/// The bound is what makes the handoff backpressure rather than an unbounded copy of the body: the
-/// producer waits once the consumer is that far behind, which is the same shape the direct route has
-/// when a socket stops draining.
+/// Audit NET-107: the producer never waits. The delegate queue is serial across every task on the
+/// session, so parking it inside `didReceive` for one consumer that stopped reading (an AirPlay
+/// receiver on a slow link) held up the head and body of every other relayed fetch for a whole
+/// park. Backpressure by `URLSessionTask.suspend()` is no way out: transports that ignore it were
+/// measured (#220), and suspended flows correlated with every connection in the process going deaf
+/// (#310). So the bound is a cap on what one fetch may hold: past it the fetch is cancelled, the
+/// body the player was promised ends short and the server closes the connection, which is how a
+/// truncated transfer already reads, and the player asks again.
 private final class UpstreamPump: NSObject, URLSessionDataDelegate, @unchecked Sendable {
 
-    /// One segment's worth of slack. Enough that a fast origin never waits on a loopback write, small
-    /// enough that a stalled player cannot turn a session into a heap of parked segments.
-    private static let highWaterBytes = 4 * 1024 * 1024
+    private let hardCapBytes: Int
+    private let onCapped: @Sendable () -> Void
+
+    init(hardCapBytes: Int, onCapped: @escaping @Sendable () -> Void) {
+        self.hardCapBytes = hardCapBytes
+        self.onCapped = onCapped
+    }
 
     private let condition = NSCondition()
     private var head: HTTPURLResponse?
@@ -592,6 +619,7 @@ private final class UpstreamPump: NSObject, URLSessionDataDelegate, @unchecked S
     private var finished = false
     private var failure: Error?
     private var consumerGaveUp = false
+    private var capped = false
 
     // MARK: - Consumer, on the server's worker thread
 
@@ -643,8 +671,7 @@ private final class UpstreamPump: NSObject, URLSessionDataDelegate, @unchecked S
         }
     }
 
-    /// Stops the producer waiting on a consumer that is no longer there. Without it a body parked at
-    /// the high-water mark holds the delegate queue for the life of the session.
+    /// Tells the producer to stop buffering for a consumer that is no longer there.
     func abandon() {
         condition.lock()
         consumerGaveUp = true
@@ -679,14 +706,26 @@ private final class UpstreamPump: NSObject, URLSessionDataDelegate, @unchecked S
 
     func urlSession(_ session: URLSession, dataTask: URLSessionDataTask, didReceive data: Data) {
         condition.lock()
-        while pending.count >= Self.highWaterBytes && !consumerGaveUp { condition.wait() }
-        let abandoned = consumerGaveUp
-        if !abandoned {
-            pending.append(data)
-            condition.broadcast()
+        var stop = consumerGaveUp || capped
+        var newlyCapped = false
+        if !stop {
+            if pending.count + data.count > hardCapBytes {
+                capped = true
+                newlyCapped = true
+                stop = true
+            } else {
+                pending.append(data)
+                condition.broadcast()
+            }
         }
         condition.unlock()
-        if abandoned { dataTask.cancel() }
+        if newlyCapped {
+            EngineLog.emit(
+                "[HLSOriginRelay] the consumer fell more than \(hardCapBytes >> 20) MiB behind one fetch; "
+                + "cancelling it so the player asks again", category: .hlsServer)
+            onCapped()
+        }
+        if stop { dataTask.cancel() }
     }
 
     func urlSession(_ session: URLSession, task: URLSessionTask, didCompleteWithError error: Error?) {
diff --git a/Tests/AetherEngineTests/HLSOriginRelayStalledConsumerTests.swift b/Tests/AetherEngineTests/HLSOriginRelayStalledConsumerTests.swift
new file mode 100644
index 000000000..6c0c1919d
--- /dev/null
+++ b/Tests/AetherEngineTests/HLSOriginRelayStalledConsumerTests.swift
@@ -0,0 +1,187 @@
+// A relayed fetch whose consumer stopped reading must cost the session nothing but its own
+// memory, bounded. Everything here drives a real origin subprocess, which exists on macOS only.
+#if os(macOS)
+
+import Foundation
+import Testing
+
+@testable import AetherEngine
+
+/// Audit NET-107: the pump used to park the session's serial delegate queue inside `didReceive`
+/// once a fetch held 4 MB its consumer had not taken, so one receiver that stopped reading held up
+/// the head and the body of every other relayed fetch for as long as the stall lasted.
+@Suite("HLS origin relay with a consumer that stops reading", .timeLimit(.minutes(3)))
+struct HLSOriginRelayStalledConsumerTests {
+
+    /// A fixed-length body written as fast as the socket takes it, with a marker file once the last
+    /// byte has gone out. The marker is what says the relay kept reading the origin while its own
+    /// consumer did not.
+    private final class FastBodyOrigin {
+        let port: UInt16
+        private let process: Process
+        private let workDir: URL
+
+        var finishedSending: Bool {
+            FileManager.default.fileExists(atPath: workDir.appendingPathComponent("done").path)
+        }
+
+        init?(megabytes: Int) async {
+            guard let launched = await PythonOrigin.launch(
+                prefix: "aether-fast-body-origin", script: Self.serverPy(bytes: megabytes << 20))
+            else { return nil }
+            process = launched.process
+            port = launched.port
+            workDir = launched.workDir
+        }
+
+        func stop() {
+            process.terminate()
+            try? FileManager.default.removeItem(at: workDir)
+        }
+
+        private static func serverPy(bytes: Int) -> String {
+            """
+            import http.server
+
+            TOTAL = \(bytes)
+            CHUNK = 65536
+
+            class Handler(http.server.BaseHTTPRequestHandler):
+                protocol_version = "HTTP/1.1"
+
+                def log_message(self, *args):
+                    pass
+
+                def do_GET(self):
+                    self.send_response(200)
+                    self.send_header("Content-Length", str(TOTAL))
+                    self.send_header("Content-Type", "video/mp2t")
+                    self.end_headers()
+                    sent = 0
+                    try:
+                        while sent < TOTAL:
+                            n = min(CHUNK, TOTAL - sent)
+                            self.wfile.write(b"\\x47" * n)
+                            sent += n
+                        self.wfile.flush()
+                        open("done", "w").close()
+                    except OSError:
+                        return
+
+            server = http.server.ThreadingHTTPServer(("127.0.0.1", 0), Handler)
+            print("READY", server.server_address[1], flush=True)
+            server.serve_forever()
+            """
+        }
+    }
+
+    /// A client that sends its request on a raw socket with a tiny receive buffer and then never
+    /// reads, which is what a receiver on a link slower than the stream looks like to the server.
+    private final class StalledReader {
+        private var fd: Int32
+
+        init?(url: URL) {
+            guard let host = url.host, let port = url.port else { return nil }
+            fd = socket(AF_INET, SOCK_STREAM, 0)
+            guard fd >= 0 else { return nil }
+            var small: Int32 = 4096
+            setsockopt(fd, SOL_SOCKET, SO_RCVBUF, &small, socklen_t(MemoryLayout<Int32>.size))
+
+            var address = sockaddr_in()
+            address.sin_family = sa_family_t(AF_INET)
+            address.sin_port = UInt16(port).bigEndian
+            guard inet_pton(AF_INET, host, &address.sin_addr) == 1 else { Darwin.close(fd); return nil }
+            let connected = withUnsafePointer(to: &address) {
+                $0.withMemoryRebound(to: sockaddr.self, capacity: 1) {
+                    connect(fd, $0, socklen_t(MemoryLayout<sockaddr_in>.size))
+                }
+            }
+            guard connected == 0 else { Darwin.close(fd); return nil }
+
+            let target = url.path + (url.query.map { "?\($0)" } ?? "")
+            let wire = Array("GET \(target) HTTP/1.1\r\nHost: \(host):\(port)\r\n\r\n".utf8)
+            let sent = wire.withUnsafeBufferPointer { send(fd, $0.baseAddress, $0.count, 0) }
+            guard sent == wire.count else { Darwin.close(fd); return nil }
+        }
+
+        func close() {
+            guard fd >= 0 else { return }
+            Darwin.close(fd)
+            fd = -1
+        }
+    }
+
+    private func entry(_ server: HLSLocalServer, port: UInt16, path: String) throws -> URL {
+        try #require(server.relayURL(for: URL(string: "http://127.0.0.1:\(port)\(path)")!))
+    }
+
+    @Test("A player that stops reading one segment does not hold up another relayed fetch")
+    func stalledConsumerDoesNotBlockOtherFetches() async throws {
+        let big = try #require(await FastBodyOrigin(megabytes: 16))
+        let quick = try #require(await TricklingOrigin(slices: 2, pauseSeconds: 0))
+        defer { big.stop(); quick.stop() }
+        let relay = HLSOriginRelay()
+        let server = HLSLocalServer(relay: relay)
+        try server.start()
+        defer { server.stop(); relay.stop() }
+
+        let stalled = try #require(StalledReader(url: try entry(server, port: big.port, path: "/big.ts")))
+        defer { stalled.close() }
+
+        // The relay keeps taking the body off the origin while nobody reads it downstream. Parked at
+        // 4 MB it never does, and the origin's last write never completes.
+        let absorbed = try await waitFor(upTo: .seconds(30)) { big.finishedSending }
+        #expect(absorbed, "the relay stopped reading the origin because its consumer stalled")
+
+        var request = URLRequest(url: try entry(server, port: quick.port, path: "/quick.ts"))
+        request.timeoutInterval = 20
+        let (body, response) = try await URLSession.shared.data(for: request)
+        #expect((response as? HTTPURLResponse)?.statusCode == 200)
+        #expect(body.count == TricklingOrigin.totalBytes(slices: 2))
+        #expect(relay.cappedFetchCount == 0, "16 MB is under the 32 MiB cap")
+    }
+
+    @Test("A consumer that falls past the cap is cut off and the fetch is cancelled, not parked")
+    func consumerPastTheCapIsCutOff() async throws {
+        let big = try #require(await FastBodyOrigin(megabytes: 16))
+        let quick = try #require(await TricklingOrigin(slices: 2, pauseSeconds: 0))
+        defer { big.stop(); quick.stop() }
+        let relay = HLSOriginRelay(maximumPendingBytes: 1 << 20)
+        let server = HLSLocalServer(relay: relay)
+        try server.start()
+        defer { server.stop(); relay.stop() }
+
+        let stalled = try #require(StalledReader(url: try entry(server, port: big.port, path: "/big.ts")))
+        defer { stalled.close() }
+
+        try await waitFor { relay.cappedFetchCount == 1 }
+
+        var request = URLRequest(url: try entry(server, port: quick.port, path: "/quick.ts"))
+        request.timeoutInterval = 20
+        let (body, response) = try await URLSession.shared.data(for: request)
+        #expect((response as? HTTPURLResponse)?.statusCode == 200)
+        #expect(body.count == TricklingOrigin.totalBytes(slices: 2))
+        #expect(relay.cappedFetchCount == 1)
+    }
+
+    @Test("A body that fits under the cap arrives whole however late its consumer starts")
+    func bodyUnderTheCapArrivesWhole() async throws {
+        // Four megabytes against an eight megabyte cap: even if the consumer took nothing until the
+        // origin had finished, the fetch holds at most what the origin sent, so no timing decides this.
+        let origin = try #require(await TricklingOrigin(slices: 64, pauseSeconds: 0))
+        defer { origin.stop() }
+        let relay = HLSOriginRelay(maximumPendingBytes: 8 << 20)
+        let server = HLSLocalServer(relay: relay)
+        try server.start()
+        defer { server.stop(); relay.stop() }
+
+        var request = URLRequest(url: try entry(server, port: origin.port, path: "/seg.ts"))
+        request.timeoutInterval = 30
+        let (body, response) = try await URLSession.shared.data(for: request)
+        #expect((response as? HTTPURLResponse)?.statusCode == 200)
+        #expect(body.count == TricklingOrigin.totalBytes(slices: 64))
+        #expect(relay.cappedFetchCount == 0)
+    }
+}
+
+#endif

From 0fd16c5749a79b0b77beae8dc77500622adb8301 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 09:22:31 +0200
Subject: [PATCH 214/359] fix(demuxer): a detour block takes one origin ticket,
 not two (audit DMX-105)

`detourFetchBlock` acquired an origin ticket (be8628f6) and then called
`syncRequest`, which acquires its own (6ffff91e, earlier). be8628f6's premise,
that detour fills bypassed the budget, was wrong. On an origin capped at two
requests with the pump holding one, the outer ticket took the last slot and
the inner acquire waited for it: +4 s per block, or the pump's whole range
when that finishes sooner, and a third request on the books. The budget
documents that a reader holding a ticket must never block on a second one.

The outer acquire is gone. What it carried is kept where the ticket is
actually taken: `syncRequest` now takes a slot label and a slot wait, and the
detour passes "detour" and the tight interactive budget, so the log still
names it and the wait is still the detour's.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 Sources/AetherEngine/Demuxer/AVIOReader.swift | 17 ++++--
 .../DetourOriginTicketTests.swift             | 61 +++++++++++++++++++
 2 files changed, 72 insertions(+), 6 deletions(-)
 create mode 100644 Tests/AetherEngineTests/DetourOriginTicketTests.swift

diff --git a/Sources/AetherEngine/Demuxer/AVIOReader.swift b/Sources/AetherEngine/Demuxer/AVIOReader.swift
index 3f939e4e5..2871b93dc 100644
--- a/Sources/AetherEngine/Demuxer/AVIOReader.swift
+++ b/Sources/AetherEngine/Demuxer/AVIOReader.swift
@@ -2622,11 +2622,12 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
 
     /// Single Range fetch for a detour block over the pooled chunkSession. Surfaces rate limiting with
     /// its Retry-After so the caller can back off in place rather than churn the connection (#71).
+    ///
+    /// The origin ticket is `syncRequest`'s, and only that one (audit DMX-105): a second acquire here
+    /// took the last slot of a two-request origin and left the inner one waiting its whole budget for
+    /// a slot this same fetch was holding, +4 s per block, with a third request on the books.
     private func detourFetchBlock(from offset: Int64, size: Int) -> DetourFetch {
         let budget = Self.effectiveDetourBudget(chunkRequestTimeout: chunkRequestTimeout)
-        let ticket = OriginRequestBudget.shared.acquire(
-            for: requestURL(), label: "\(label) detour", timeout: budget)
-        defer { OriginRequestBudget.shared.release(ticket) }
         let rangeEnd = offset + Int64(size) - 1
         var request = URLRequest(url: requestURL())
         request.setValue("bytes=\(offset)-\(rangeEnd)", forHTTPHeaderField: "Range")
@@ -2635,7 +2636,9 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
         request.timeoutInterval = budget
         applyExtraHeaders(&request)
         do {
-            let (data, response) = try syncRequest(request, budget: budget)
+            let (data, response) = try syncRequest(
+                request, budget: budget, slotLabel: "detour",
+                slotWait: min(budget, Self.shortFetchSlotWaitSeconds))
             if let http = response as? HTTPURLResponse {
                 let status = http.statusCode
                 if Self.isRateLimitStatus(status) {
@@ -4362,13 +4365,15 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
         completion.wait()
     }
 
-    private func syncRequest(_ request: URLRequest, budget: TimeInterval = 35) throws -> (Data, URLResponse) {
+    private func syncRequest(_ request: URLRequest, budget: TimeInterval = 35,
+                             slotLabel: String = "fetch",
+                             slotWait: TimeInterval = AVIOReader.shortFetchSlotWaitSeconds) throws -> (Data, URLResponse) {
         // #377: every short fetch the reader makes (detour blocks, size probes, HEAD) funnels
         // through here, so this is the one place that has to take an origin slot for all of them.
         // Scoped to the call: unlike the pump's, this request's life IS this function's.
         let slotURL = request.url ?? url
         let ticket = try requestTicket(
-            for: slotURL, label: "\(label) fetch", timeout: Self.shortFetchSlotWaitSeconds)
+            for: slotURL, label: "\(label) \(slotLabel)", timeout: slotWait)
         defer { OriginRequestBudget.shared.release(ticket) }
 
         let delegate = ChunkFetchDelegate(extraHeaders: headers(for: request.url),
diff --git a/Tests/AetherEngineTests/DetourOriginTicketTests.swift b/Tests/AetherEngineTests/DetourOriginTicketTests.swift
new file mode 100644
index 000000000..957e8ce23
--- /dev/null
+++ b/Tests/AetherEngineTests/DetourOriginTicketTests.swift
@@ -0,0 +1,61 @@
+import Testing
+import Foundation
+@testable import AetherEngine
+
+/// Audit DMX-105: a detour block took an origin ticket in `detourFetchBlock` and a second one inside
+/// `syncRequest`. On an origin capped at two requests, with the pump holding one, the outer ticket
+/// took the last slot and the inner acquire waited its whole four second budget for it: +4 s per
+/// block, and a third request on the books against a limit of two. A reader that already holds a
+/// ticket must never block on another, so the detour holds one.
+@Suite("Detour origin ticket", .serialized)
+struct DetourOriginTicketTests {
+
+    @Test("a detour block behind a pump holding one of two slots takes one slot and no wait",
+          .timeLimit(.minutes(2)))
+    func detourTakesOneTicket() async throws {
+        let total: Int64 = 64 * 1024 * 1024
+        // About 6 MB/s: the pump still has seconds of its 32 MB range to go when the detour is asked for.
+        let maybe = ThrottledOriginServer(totalSize: total, throttleUs: 40_000)
+        let server = try #require(maybe)
+        defer { server.stop() }
+        let url = URL(string: "http://127.0.0.1:\(server.port)/movie.bin")!
+        OriginRequestBudget.shared.setHostLimit(2, for: url)
+        defer { OriginRequestBudget.shared.setHostLimit(nil, for: url) }
+
+        let reader = AVIOReader(url: url)
+        defer { reader.markClosed(); reader.close() }
+        try reader.open()
+
+        let chunk = 256 * 1024
+        let buf = UnsafeMutablePointer<UInt8>.allocate(capacity: chunk)
+        defer { buf.deallocate() }
+        var read = 0
+        while read < 13 * 1024 * 1024 {
+            let n = Int(reader.read(into: buf, size: Int32(chunk)))
+            #expect(n > 0, "forward read failed at \(read)")
+            if n <= 0 { return }
+            read += n
+        }
+        #expect(reader.hasLiveConnectionForTesting, "the pump was not on the link, so the detour had no rival")
+
+        // Backward past the retained head and the window (which trimmed to about 8 MB): the read
+        // that opens the detour block holding 4 to 8 MB.
+        let target = Int64(5 * 1024 * 1024)
+        #expect(reader.seek(offset: target, whence: Int32(SEEK_SET)) == target)
+        let start = ContinuousClock.now
+        let served = reader.read(into: buf, size: Int32(chunk))
+        let elapsed = ContinuousClock.now - start
+
+        #expect(served > 0)
+        #expect(elapsed < .seconds(2), "the detour took \(elapsed): it waited on a slot it already held")
+        #expect(reader.hasLiveConnectionForTesting,
+                "the detour only got its slot once the pump's range had finished")
+        let books = try #require(OriginRequestBudget.shared.snapshot(for: url))
+        #expect(books.limit == 2)
+        #expect(books.peakInflight == 2, "peak \(books.peakInflight) on the books against a limit of 2")
+        // The detour block is the 4 MB aligned block holding the target, and nothing else asks for
+        // exactly that range: the pump's refills are 32 MB and the tail prefetch is a suffix.
+        #expect(server.requestedRanges.contains { $0.start == 4 * 1024 * 1024 && $0.end == 8 * 1024 * 1024 - 1 },
+                "no detour block went out, so this measured nothing: \(server.requestedRanges)")
+    }
+}

From ff7c341987fbce4d4257e8530d6d8b7dce541536 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 09:23:12 +0200
Subject: [PATCH 215/359] fix(demuxer): track accessors never walk the live
 streams array, and close() waits for stream users (audit DMX-108)

The NAT-7 fix covered stream(at:) only. videoStreamIndex, audioStreamIndex,
firstAudioStreamIndexByType, audioTrackInfos, subtitleTrackInfos, subtitleStreamIndices and
splitDisplaySetSubtitleStreamIndices still indexed ctx.streams with no lock while MPEG-TS
reallocates it inside av_read_frame, and close() freed the AVStreams before it emptied the table,
so a caller holding a raw AVStream* across a live reopen's close() read freed memory.

The accessors now compute under accessLock.try() and answer from the last snapshot (rebuilt on a
stream-count change, after find_stream_info and on close) when a read holds the lock, so none of
them can wait out a network read. mediaMetadata and fontAttachmentInfos, load-time only, take the
lock outright. close() empties the stream table before avformat_close_input and waits for every
caller inside the new withStream(at:) to leave, and the two escaping stream(at:) uses on
live-swappable demuxers (makeOverlayDecoder, rebuildSubtitleTapRoutes) go through it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 Sources/AetherEngine/Demuxer/Demuxer.swift    | 188 ++++++++++++++----
 .../AetherEngine/Video/HLSVideoEngine.swift   |  35 ++--
 .../DemuxerStreamLifetimeTests.swift          | 136 +++++++++++++
 3 files changed, 307 insertions(+), 52 deletions(-)
 create mode 100644 Tests/AetherEngineTests/DemuxerStreamLifetimeTests.swift

diff --git a/Sources/AetherEngine/Demuxer/Demuxer.swift b/Sources/AetherEngine/Demuxer/Demuxer.swift
index a675aa551..8178a19cc 100644
--- a/Sources/AetherEngine/Demuxer/Demuxer.swift
+++ b/Sources/AetherEngine/Demuxer/Demuxer.swift
@@ -287,9 +287,32 @@ public final class Demuxer: @unchecked Sendable {
     /// `streams` array, so a caller on another thread must not index the live array while a read
     /// holds the lock. The `AVStream`s themselves live until `avformat_close_input`. Guarded by
     /// `streamTableLock`, a leaf lock; `streamTableSize` is its length, guarded by `accessLock`.
-    private let streamTableLock = NSLock()
+    ///
+    /// Audit DMX-108: also the gate `withStream` and `close()` meet at. A caller inside
+    /// `withStream` counts itself in `streamUsers`, and `close()` empties the table (so no new one
+    /// can start) and waits for the count to reach zero before `avformat_close_input` frees the
+    /// `AVStream`s. The condition is on the leaf lock, so the wait never holds `accessLock`'s
+    /// network reads against anyone.
+    private let streamTableLock = NSCondition()
     private var streamTable: [UnsafeMutablePointer<AVStream>] = []
     private var streamTableSize = 0
+    private var streamUsers = 0
+
+    /// Audit DMX-108: what the track accessors answer with when a read holds `accessLock`.
+    /// MPEG-TS adds streams inside `av_read_frame`, which reallocates `streams`, so the accessors
+    /// walk the live array only under the lock, and the lock can be held for a whole network read.
+    /// An accessor that finds it busy answers from the last snapshot instead of waiting, the same
+    /// contract NAT-7 gave `stream(at:)`. Guarded by `streamTableLock`.
+    private struct TrackSnapshot {
+        var videoStreamIndex: Int32 = -1
+        var audioStreamIndex: Int32 = -1
+        var firstAudioStreamIndexByType: Int32 = -1
+        var audioTracks: [TrackInfo] = []
+        var subtitleTracks: [TrackInfo] = []
+        var subtitleStreamIndices: Set<Int32> = []
+        var splitDisplaySetSubtitleStreamIndices: Set<Int32> = []
+    }
+    private var trackSnapshot = TrackSnapshot()
 
     /// The URL and headers this demuxer was opened from, kept for the recordless Dolby Vision audit's
     /// second open. nil for a custom reader (no second open to give) and for a live source.
@@ -1084,7 +1107,7 @@ public final class Demuxer: @unchecked Sendable {
         guard let ctx = formatContext else { return }
         reclassifyAttachedPictures(ctx)
         _ = avformat_find_stream_info(ctx, nil)
-        refreshStreamTableLocked()
+        refreshStreamTableLocked(rebuildTracks: true)
     }
 
     /// True if the stream at `index` is missing or carries no resolved codec yet (`AV_CODEC_ID_NONE`).
@@ -1151,8 +1174,7 @@ public final class Demuxer: @unchecked Sendable {
     /// Clamped: av_find_best_stream returns AVERROR_STREAM_NOT_FOUND (-1381258232)
     /// on failure, not -1; normalize to -1 to avoid garbage in logs.
     var videoStreamIndex: Int32 {
-        guard let ctx = formatContext else { return -1 }
-        return max(-1, av_find_best_stream(ctx, AVMEDIA_TYPE_VIDEO, -1, -1, nil, 0))
+        answeredFromStreams(\.videoStreamIndex) { Self.bestStreamIndex($0, AVMEDIA_TYPE_VIDEO) }
     }
 
     /// True if `index` names a video stream. Live producer uses this to detect
@@ -1169,15 +1191,51 @@ public final class Demuxer: @unchecked Sendable {
     /// GOTCHA: av_find_best_stream skips streams with no channels/sample_rate (live MPEG-TS
     /// probe may leave them that way). Use `firstAudioStreamIndexByType` as fallback.
     var audioStreamIndex: Int32 {
-        guard let ctx = formatContext else { return -1 }
-        return max(-1, av_find_best_stream(ctx, AVMEDIA_TYPE_AUDIO, -1, -1, nil, 0))
+        answeredFromStreams(\.audioStreamIndex) { Self.bestStreamIndex($0, AVMEDIA_TYPE_AUDIO) }
     }
 
     /// First audio stream by codec_type regardless of codecpar completeness.
     /// Fallback for live MPEG-TS where av_find_best_stream skips empty-codecpar
     /// streams; the engine's live AAC codecpar repair fills them downstream.
     var firstAudioStreamIndexByType: Int32 {
-        guard let ctx = formatContext else { return -1 }
+        answeredFromStreams(\.firstAudioStreamIndexByType) { Self.firstAudioStreamIndexByType($0) }
+    }
+
+    func audioTrackInfos() -> [TrackInfo] {
+        answeredFromStreams(\.audioTracks) { trackInfos(in: $0, ofType: AVMEDIA_TYPE_AUDIO) }
+    }
+
+    func subtitleTrackInfos() -> [TrackInfo] {
+        answeredFromStreams(\.subtitleTracks) { trackInfos(in: $0, ofType: AVMEDIA_TYPE_SUBTITLE) }
+    }
+
+    /// Runs `compute` over the live format context under `accessLock` when the lock is free, and
+    /// remembers the answer; answers from the last snapshot when a read holds it (audit DMX-108).
+    /// `try`, not `lock`, for the reason `stream(at:)` gives: a caller on the main actor must not
+    /// wait out a network read.
+    private func answeredFromStreams<T>(
+        _ field: WritableKeyPath<TrackSnapshot, T>,
+        _ compute: (UnsafeMutablePointer<AVFormatContext>) -> T
+    ) -> T {
+        if accessLock.try() {
+            defer { accessLock.unlock() }
+            let answer = formatContext.map(compute) ?? TrackSnapshot()[keyPath: field]
+            streamTableLock.lock()
+            trackSnapshot[keyPath: field] = answer
+            streamTableLock.unlock()
+            return answer
+        }
+        streamTableLock.lock()
+        defer { streamTableLock.unlock() }
+        return trackSnapshot[keyPath: field]
+    }
+
+    private static func bestStreamIndex(_ ctx: UnsafeMutablePointer<AVFormatContext>,
+                                        _ type: AVMediaType) -> Int32 {
+        max(-1, av_find_best_stream(ctx, type, -1, -1, nil, 0))
+    }
+
+    private static func firstAudioStreamIndexByType(_ ctx: UnsafeMutablePointer<AVFormatContext>) -> Int32 {
         for i in 0..<Int(ctx.pointee.nb_streams) {
             guard let stream = ctx.pointee.streams[i],
                   let codecpar = stream.pointee.codecpar,
@@ -1187,48 +1245,69 @@ public final class Demuxer: @unchecked Sendable {
         return -1
     }
 
-    func audioTrackInfos() -> [TrackInfo] {
-        guard let ctx = formatContext else { return [] }
+    private func trackInfos(in ctx: UnsafeMutablePointer<AVFormatContext>,
+                            ofType type: AVMediaType) -> [TrackInfo] {
         var tracks: [TrackInfo] = []
         for i in 0..<Int(ctx.pointee.nb_streams) {
             guard let stream = ctx.pointee.streams[i],
                   let codecpar = stream.pointee.codecpar,
-                  codecpar.pointee.codec_type == AVMEDIA_TYPE_AUDIO else { continue }
+                  codecpar.pointee.codec_type == type else { continue }
             tracks.append(trackInfo(from: stream, index: i))
         }
         return tracks
     }
 
-    func subtitleTrackInfos() -> [TrackInfo] {
-        guard let ctx = formatContext else { return [] }
-        var tracks: [TrackInfo] = []
+    private static func subtitleStreamIndices(in ctx: UnsafeMutablePointer<AVFormatContext>) -> Set<Int32> {
+        var indices: Set<Int32> = []
         for i in 0..<Int(ctx.pointee.nb_streams) {
             guard let stream = ctx.pointee.streams[i],
                   let codecpar = stream.pointee.codecpar,
                   codecpar.pointee.codec_type == AVMEDIA_TYPE_SUBTITLE else { continue }
-            tracks.append(trackInfo(from: stream, index: i))
+            indices.insert(Int32(i))
         }
-        return tracks
+        return indices
     }
 
-    /// #112: PGS subtitle streams whose display sets arrive split across PES packets and need
-    /// reassembly in the SubtitlePacketStore. Only the MPEG-TS demuxer splits them (Blu-ray
-    /// authoring: PCS|WDS|PDS|ODS|END as separate PES packets, some without a PTS); Matroska
-    /// carries one complete set per packet and must NOT be assembled (converters there strip
-    /// the trailing END, which the decoder's synthetic-END flush rescues per packet).
-    /// #151: every AVMEDIA_TYPE_SUBTITLE stream index; the forward prefetcher's route + keep set.
-    func subtitleStreamIndices() -> Set<Int32> {
-        guard let ctx = formatContext else { return [] }
+    private static func splitDisplaySetSubtitleStreamIndices(
+        in ctx: UnsafeMutablePointer<AVFormatContext>
+    ) -> Set<Int32> {
+        guard let formatName = ctx.pointee.iformat?.pointee.name,
+              String(cString: formatName).split(separator: ",").contains("mpegts")
+        else { return [] }
         var indices: Set<Int32> = []
         for i in 0..<Int(ctx.pointee.nb_streams) {
             guard let stream = ctx.pointee.streams[i],
                   let codecpar = stream.pointee.codecpar,
-                  codecpar.pointee.codec_type == AVMEDIA_TYPE_SUBTITLE else { continue }
+                  codecpar.pointee.codec_type == AVMEDIA_TYPE_SUBTITLE,
+                  codecpar.pointee.codec_id == AV_CODEC_ID_HDMV_PGS_SUBTITLE else { continue }
             indices.insert(Int32(i))
         }
         return indices
     }
 
+    /// Caller holds `accessLock`.
+    private func buildTrackSnapshotLocked() -> TrackSnapshot {
+        guard let ctx = formatContext else { return TrackSnapshot() }
+        return TrackSnapshot(
+            videoStreamIndex: Self.bestStreamIndex(ctx, AVMEDIA_TYPE_VIDEO),
+            audioStreamIndex: Self.bestStreamIndex(ctx, AVMEDIA_TYPE_AUDIO),
+            firstAudioStreamIndexByType: Self.firstAudioStreamIndexByType(ctx),
+            audioTracks: trackInfos(in: ctx, ofType: AVMEDIA_TYPE_AUDIO),
+            subtitleTracks: trackInfos(in: ctx, ofType: AVMEDIA_TYPE_SUBTITLE),
+            subtitleStreamIndices: Self.subtitleStreamIndices(in: ctx),
+            splitDisplaySetSubtitleStreamIndices: Self.splitDisplaySetSubtitleStreamIndices(in: ctx))
+    }
+
+    /// #112: PGS subtitle streams whose display sets arrive split across PES packets and need
+    /// reassembly in the SubtitlePacketStore. Only the MPEG-TS demuxer splits them (Blu-ray
+    /// authoring: PCS|WDS|PDS|ODS|END as separate PES packets, some without a PTS); Matroska
+    /// carries one complete set per packet and must NOT be assembled (converters there strip
+    /// the trailing END, which the decoder's synthetic-END flush rescues per packet).
+    /// #151: every AVMEDIA_TYPE_SUBTITLE stream index; the forward prefetcher's route + keep set.
+    func subtitleStreamIndices() -> Set<Int32> {
+        answeredFromStreams(\.subtitleStreamIndices) { Self.subtitleStreamIndices(in: $0) }
+    }
+
     /// #230: the stream whose packets pace the subtitle side reader's forward park, or -1.
     ///
     /// The park can only be evaluated on a packet the loop actually receives, and with every
@@ -1276,22 +1355,16 @@ public final class Demuxer: @unchecked Sendable {
     }
 
     func splitDisplaySetSubtitleStreamIndices() -> Set<Int32> {
-        guard let ctx = formatContext,
-              let formatName = ctx.pointee.iformat?.pointee.name,
-              String(cString: formatName).split(separator: ",").contains("mpegts")
-        else { return [] }
-        var indices: Set<Int32> = []
-        for i in 0..<Int(ctx.pointee.nb_streams) {
-            guard let stream = ctx.pointee.streams[i],
-                  let codecpar = stream.pointee.codecpar,
-                  codecpar.pointee.codec_type == AVMEDIA_TYPE_SUBTITLE,
-                  codecpar.pointee.codec_id == AV_CODEC_ID_HDMV_PGS_SUBTITLE else { continue }
-            indices.insert(Int32(i))
+        answeredFromStreams(\.splitDisplaySetSubtitleStreamIndices) {
+            Self.splitDisplaySetSubtitleStreamIndices(in: $0)
         }
-        return indices
     }
 
+    /// Load-time only (the probe demuxer has no reader yet), so it takes `accessLock` outright
+    /// rather than answering from a snapshot: it reads the attached picture's bytes.
     func mediaMetadata() -> MediaMetadata {
+        accessLock.lock()
+        defer { accessLock.unlock() }
         guard let ctx = formatContext else {
             return MediaMetadata(title: nil, artist: nil, album: nil, artworkData: nil)
         }
@@ -1500,6 +1573,8 @@ public final class Demuxer: @unchecked Sendable {
     /// MKV font attachments. Payload in codec extradata; filename/MIME in stream metadata.
     /// Non-font attachments filtered by isFontPayload.
     func fontAttachmentInfos() -> [FontAttachment] {
+        accessLock.lock()
+        defer { accessLock.unlock() }
         guard let ctx = formatContext else { return [] }
         var fonts: [FontAttachment] = []
         for i in 0..<Int(ctx.pointee.nb_streams) {
@@ -1568,8 +1643,10 @@ public final class Demuxer: @unchecked Sendable {
         return Int(index) < streamTable.count ? streamTable[Int(index)] : nil
     }
 
-    /// Caller holds `accessLock`.
-    private func refreshStreamTableLocked() {
+    /// Caller holds `accessLock`. The track snapshot is rebuilt when the stream count changed, when
+    /// the context is gone, and when the caller says codec parameters moved under an unchanged count
+    /// (`rebuildTracks`, after a `find_stream_info`).
+    private func refreshStreamTableLocked(rebuildTracks: Bool = false) {
         var table: [UnsafeMutablePointer<AVStream>] = []
         if let ctx = formatContext, let streams = ctx.pointee.streams {
             let count = Int(ctx.pointee.nb_streams)
@@ -1579,10 +1656,38 @@ public final class Demuxer: @unchecked Sendable {
                 table.append(stream)
             }
         }
+        let snapshot = (rebuildTracks || table.count != streamTableSize || formatContext == nil)
+            ? buildTrackSnapshotLocked() : nil
         streamTableSize = table.count
         streamTableLock.lock()
         streamTable = table
+        if let snapshot { trackSnapshot = snapshot }
+        streamTableLock.unlock()
+    }
+
+    /// The stream at `index`, for the length of `body` only (audit DMX-108). `stream(at:)` hands out
+    /// a raw `AVStream*`, and a live reopen's `close()` frees every stream the moment it runs, so a
+    /// caller on another thread that holds one across that point reads freed memory. A caller in
+    /// here is counted, `close()` waits for the count to drain before it frees anything, and once
+    /// `close()` has started no new caller gets a stream. Never waits on `accessLock`, so it cannot
+    /// wait out a network read either. `body` must be short and must not call back into the demuxer.
+    func withStream<T>(at index: Int32, _ body: (UnsafeMutablePointer<AVStream>) -> T) -> T? {
+        guard index >= 0 else { return nil }
+        streamTableLock.lock()
+        guard Int(index) < streamTable.count else {
+            streamTableLock.unlock()
+            return nil
+        }
+        let stream = streamTable[Int(index)]
+        streamUsers += 1
         streamTableLock.unlock()
+        defer {
+            streamTableLock.lock()
+            streamUsers -= 1
+            if streamUsers == 0 { streamTableLock.broadcast() }
+            streamTableLock.unlock()
+        }
+        return body(stream)
     }
 
     /// Sets AVDISCARD_ALL on streams outside `keep`. Without this, matroska reads
@@ -2439,6 +2544,13 @@ public final class Demuxer: @unchecked Sendable {
         avioProvider?.markClosed()  // unblocks av_read_frame (tvOS suspends threads in background)
         accessLock.lock()
         interrupt.disarmInputCeiling()
+        // Audit DMX-108: the table is emptied BEFORE the streams are freed, and close waits for
+        // every `withStream` caller already inside, so no thread is left holding a freed `AVStream*`.
+        streamTableLock.lock()
+        streamTable = []
+        trackSnapshot = TrackSnapshot()
+        while streamUsers > 0 { streamTableLock.wait() }
+        streamTableLock.unlock()
         if formatContext != nil {
             avformat_close_input(&formatContext)
         }
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine.swift b/Sources/AetherEngine/Video/HLSVideoEngine.swift
index dc7dd78ba..2f21d74f8 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine.swift
@@ -293,14 +293,19 @@ public final class HLSVideoEngine: @unchecked Sendable {
     /// #112 rework: build an overlay decoder for any embedded subtitle stream (text or
     /// bitmap), seeded exactly like the tap routes. The drainer owns the returned decoder.
     func makeOverlayDecoder(streamIndex: Int32) -> EmbeddedSubtitleDecoder? {
-        guard let dem = demuxer, let stream = dem.stream(at: streamIndex) else { return nil }
+        guard let dem = demuxer else { return nil }
         let w = savedVideoConfig.map { Int32($0.codecpar.pointee.width) } ?? 1920
         let h = savedVideoConfig.map { Int32($0.codecpar.pointee.height) } ?? 1080
-        return EmbeddedSubtitleDecoder(stream: stream,
-                                       sourceVideoWidth: w > 0 ? w : 1920,
-                                       sourceVideoHeight: h > 0 ? h : 1080,
-                                       preserveASSMarkup: preserveASSMarkupForSubtitleTap,
-                                       teletextPage: teletextPageForSubtitleTap)
+        // Audit DMX-108: the decoder copies what it needs out of the stream inside the call, so a
+        // live reopen's close() cannot free the stream underneath it.
+        let made = dem.withStream(at: streamIndex) { stream in
+            EmbeddedSubtitleDecoder(stream: stream,
+                                    sourceVideoWidth: w > 0 ? w : 1920,
+                                    sourceVideoHeight: h > 0 ? h : 1080,
+                                    preserveASSMarkup: preserveASSMarkupForSubtitleTap,
+                                    teletextPage: teletextPageForSubtitleTap)
+        }
+        return made ?? nil
     }
 
     /// Sodalite#32 Phase 2: tap decoders honor the host's markup preference so the overlay can render
@@ -372,14 +377,16 @@ public final class HLSVideoEngine: @unchecked Sendable {
         let w = savedVideoConfig.map { Int32($0.codecpar.pointee.width) } ?? 1920
         let h = savedVideoConfig.map { Int32($0.codecpar.pointee.height) } ?? 1080
         for (ordinal, sidx) in nativeSubtitleSourceStreamIndicesForSession.enumerated() {
-            guard let sidx, ordinal < nativeSubtitleCueStoresForSession.count,
-                  let stream = dem.stream(at: sidx),
-                  let decoder = EmbeddedSubtitleDecoder(stream: stream,
-                                                        sourceVideoWidth: w > 0 ? w : 1920,
-                                                        sourceVideoHeight: h > 0 ? h : 1080,
-                                                        preserveASSMarkup: preserveASSMarkupForSubtitleTap,
-                                                        teletextPage: teletextPageForSubtitleTap)
-            else { continue }
+            guard let sidx, ordinal < nativeSubtitleCueStoresForSession.count else { continue }
+            // Audit DMX-108: see `makeOverlayDecoder`.
+            let made = dem.withStream(at: sidx) { stream in
+                EmbeddedSubtitleDecoder(stream: stream,
+                                        sourceVideoWidth: w > 0 ? w : 1920,
+                                        sourceVideoHeight: h > 0 ? h : 1080,
+                                        preserveASSMarkup: preserveASSMarkupForSubtitleTap,
+                                        teletextPage: teletextPageForSubtitleTap)
+            }
+            guard let decoder = made ?? nil else { continue }
             subtitleTapRoutes[sidx] = (decoder, nativeSubtitleCueStoresForSession[ordinal])
         }
         if !subtitleTapRoutes.isEmpty {
diff --git a/Tests/AetherEngineTests/DemuxerStreamLifetimeTests.swift b/Tests/AetherEngineTests/DemuxerStreamLifetimeTests.swift
new file mode 100644
index 000000000..f1bb1ffb4
--- /dev/null
+++ b/Tests/AetherEngineTests/DemuxerStreamLifetimeTests.swift
@@ -0,0 +1,136 @@
+import Testing
+import Foundation
+import AetherLibavcodec
+@testable import AetherEngine
+
+/// Audit DMX-108: the NAT-7 fix made `stream(at:)` safe against MPEG-TS reallocating `streams`
+/// inside `av_read_frame`, and left two holes. The sibling track accessors still walked the live
+/// array without the lock, and `close()` freed the streams before it emptied the table, so a caller
+/// on another thread could hold a raw `AVStream*` across a live reopen's `close()`.
+@Suite("Demuxer stream lifetime and track accessors", .serialized)
+struct DemuxerStreamLifetimeTests {
+
+    private final class Flag: @unchecked Sendable {
+        private let lock = NSLock()
+        private var _value = false
+        var value: Bool { lock.withLock { _value } }
+        func set() { lock.withLock { _value = true } }
+    }
+
+    private final class Seen: @unchecked Sendable {
+        private let lock = NSLock()
+        private var _index: Int32?
+        var index: Int32? { lock.withLock { _index } }
+        func set(_ index: Int32) { lock.withLock { _index = index } }
+    }
+
+    private final class Tracks: @unchecked Sendable {
+        private let lock = NSLock()
+        private var _video: Int32?
+        private var _subtitles: [Int32]?
+        private var _indices: Set<Int32>?
+        var video: Int32? { lock.withLock { _video } }
+        var subtitles: [Int32]? { lock.withLock { _subtitles } }
+        var indices: Set<Int32>? { lock.withLock { _indices } }
+        func set(video: Int32, subtitles: [Int32], indices: Set<Int32>) {
+            lock.withLock { _video = video; _subtitles = subtitles; _indices = indices }
+        }
+    }
+
+    @Test("close waits for a caller inside withStream and hands out no stream once it has started",
+          .timeLimit(.minutes(1)))
+    func closeWaitsForStreamUsers() async throws {
+        let url = try MultiSubtitleContainerFixture.write()
+        defer { try? FileManager.default.removeItem(at: url) }
+        let demuxer = Demuxer()
+        try demuxer.open(url: url)
+
+        let entered = Flag()
+        let closed = Flag()
+        let seenInsideTheBody = Seen()
+        let release = DispatchSemaphore(value: 0)
+        Thread.detachNewThread {
+            _ = demuxer.withStream(at: MultiSubtitleContainerFixture.videoStreamIndex) { stream in
+                entered.set()
+                release.wait()
+                seenInsideTheBody.set(stream.pointee.index)
+            }
+        }
+        try await waitFor { entered.value }
+
+        Thread.detachNewThread {
+            demuxer.close()
+            closed.set()
+        }
+        // The table is emptied before the streams are freed: nothing new gets a stream from here.
+        try await waitFor { demuxer.stream(at: MultiSubtitleContainerFixture.videoStreamIndex) == nil }
+        #expect(demuxer.withStream(at: MultiSubtitleContainerFixture.videoStreamIndex) { _ in true } == nil,
+                "a stream was handed out after close() had started")
+
+        let closedUnderTheCaller = try await waitFor(upTo: .milliseconds(300)) { closed.value }
+        #expect(!closedUnderTheCaller, "close() freed the streams while a caller was still inside withStream")
+
+        release.signal()
+        try await waitFor { closed.value }
+        #expect(seenInsideTheBody.index == MultiSubtitleContainerFixture.videoStreamIndex)
+    }
+
+    @Test("withStream hands out nothing for an index the demuxer does not have")
+    func withStreamRejectsUnknownIndices() throws {
+        let url = try MultiSubtitleContainerFixture.write()
+        defer { try? FileManager.default.removeItem(at: url) }
+        let demuxer = Demuxer()
+        defer { demuxer.close() }
+        try demuxer.open(url: url)
+
+        #expect(demuxer.withStream(at: -1) { _ in true } == nil)
+        #expect(demuxer.withStream(at: 99) { _ in true } == nil)
+        #expect(demuxer.withStream(at: MultiSubtitleContainerFixture.spanishStreamIndex) {
+            $0.pointee.codecpar.pointee.codec_type == AVMEDIA_TYPE_SUBTITLE
+        } == true)
+    }
+
+    @Test("the track accessors answer from their snapshot while a read holds the demuxer",
+          .timeLimit(.minutes(1)))
+    func accessorsDoNotWaitOutARead() async throws {
+        let url = try MultiSubtitleContainerFixture.write()
+        defer { try? FileManager.default.removeItem(at: url) }
+        let demuxer = Demuxer()
+        defer { demuxer.close() }
+        try demuxer.open(url: url)
+
+        // `isCurrent` runs inside `readPacket` with the access lock held, which is the state a read
+        // parked on a slow origin leaves the lock in.
+        let holding = Flag()
+        let readReleased = DispatchSemaphore(value: 0)
+        let readFinished = Flag()
+        Thread.detachNewThread {
+            _ = try? demuxer.readPacket(isCurrent: {
+                holding.set()
+                readReleased.wait()
+                return true
+            })
+            readFinished.set()
+        }
+        try await waitFor { holding.value }
+
+        let answered = Tracks()
+        let done = Flag()
+        Thread.detachNewThread {
+            answered.set(video: demuxer.videoStreamIndex,
+                         subtitles: demuxer.subtitleTrackInfos().map { Int32($0.id) },
+                         indices: demuxer.subtitleStreamIndices())
+            done.set()
+        }
+        let returned = try await waitFor(upTo: .seconds(5)) { done.value }
+        readReleased.signal()
+        try await waitFor { readFinished.value }
+
+        #expect(returned, "a track accessor waited out a read that holds the access lock")
+        #expect(answered.video == MultiSubtitleContainerFixture.videoStreamIndex)
+        #expect(answered.subtitles == [MultiSubtitleContainerFixture.englishStreamIndex,
+                                       MultiSubtitleContainerFixture.spanishStreamIndex])
+        #expect(answered.indices == [MultiSubtitleContainerFixture.englishStreamIndex,
+                                     MultiSubtitleContainerFixture.spanishStreamIndex])
+    }
+}

From 4678411a2dbcc5d34fc16928fb777e20978db516 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 09:24:55 +0200
Subject: [PATCH 216/359] fix(live): the subtitle rendition loop fetches and
 parses off the main actor, bounded (audit FEA-104, FEA-107, SUB-106)

The rendition poll fetched its playlist and every WebVTT segment, parsed both and merged the cues on
the main actor, through a .default session (7-day resource timeout, cache) with no status check and
no size cap. The fetch and both parses are nonisolated statics now, over an ephemeral session with a
30 s resource timeout, playlists capped at the ingest's 8 MiB and segments at 1 MiB with the status
checked. WebVTTSegmentParser.merged looks candidates up per text instead of scanning everything
published (40k cues took 3.9 s), a segment holds at most 4096 cues, timestamps must be finite and
non-negative (inf and nan parsed, and a +inf end was never pruned), and the published list is capped
at 2000 cues.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../AetherEngine+LiveSubtitleRenditions.swift |  65 ++++-
 .../Subtitles/WebVTTSegmentParser.swift       |  23 +-
 .../LiveSubtitleRenditionHardeningTests.swift | 254 ++++++++++++++++++
 3 files changed, 327 insertions(+), 15 deletions(-)
 create mode 100644 Tests/AetherEngineTests/LiveSubtitleRenditionHardeningTests.swift

diff --git a/Sources/AetherEngine/AetherEngine+LiveSubtitleRenditions.swift b/Sources/AetherEngine/AetherEngine+LiveSubtitleRenditions.swift
index c6453cc06..71916cdd2 100644
--- a/Sources/AetherEngine/AetherEngine+LiveSubtitleRenditions.swift
+++ b/Sources/AetherEngine/AetherEngine+LiveSubtitleRenditions.swift
@@ -121,9 +121,11 @@ extension AetherEngine {
             }
             var pollInterval = 2.0
             do {
-                let text = try await Self.fetchText(
+                // Audit FEA-104: the fetch and both parses run off the main actor; only the merge and
+                // the publish below are back on it.
+                guard let media = try await Self.fetchLiveSubtitleRenditionPlaylist(
                     rendition.playlistURL, headers: credentials.headers(for: rendition.playlistURL))
-                guard case .media(let media) = try HLSPlaylistParser.parse(text) else { return }
+                else { return }
                 pollInterval = Self.liveSubtitlePollInterval(targetDuration: media.targetDuration)
                 // Anchor the work at the playhead, not at the start of the playlist. A rendition
                 // playlist is not a handful of segments: MDR publishes its whole two hour DVR window,
@@ -145,8 +147,8 @@ extension AetherEngine {
                           let url = HLSPlaylistParser.resolve(uri: segment.uri, against: rendition.playlistURL)
                     else { continue }
                     seen.insert(segment.uri)
-                    guard let body = try? await Self.fetchText(url, headers: credentials.headers(for: url)),
-                          let parsed = WebVTTSegmentParser.parse(body) else { continue }
+                    guard let parsed = await Self.fetchLiveSubtitleRenditionSegment(
+                        url, headers: credentials.headers(for: url)) else { continue }
                     guard activeSubtitleTrackIndex == trackID else { return }
                     let fresh = WebVTTSegmentParser.cues(from: parsed, segmentWallStart: wallStart,
                                                          segmentDuration: segment.duration,
@@ -194,24 +196,65 @@ extension AetherEngine {
     /// line it ever showed, and #271 is the standing reminder that this array is paid for per publish.
     private func pruned(_ cues: [SubtitleCue]) -> [SubtitleCue] {
         let horizon = clock.currentTime - (loadedOptions.dvrWindowSeconds ?? 600) - 60
-        guard horizon > 0 else { return cues }
-        return cues.filter { $0.endTime >= horizon }
+        guard horizon > 0 else { return Self.capLiveSubtitleCues(cues) }
+        return Self.capLiveSubtitleCues(cues.filter { $0.endTime >= horizon })
+    }
+
+    /// Audit SUB-106: the time horizon above is the normal bound; this one is for an origin whose cues
+    /// never age out of it. The newest cues are the ones that were appended last.
+    nonisolated static let maxLiveSubtitleCues = 2000
+
+    nonisolated static func capLiveSubtitleCues(_ cues: [SubtitleCue]) -> [SubtitleCue] {
+        cues.count > maxLiveSubtitleCues ? Array(cues.suffix(maxLiveSubtitleCues)) : cues
+    }
+
+    /// Audit FEA-107: this session was `.default`, a 7-day resource timeout and a disk cache, so one
+    /// endless body grew until jetsam. Ephemeral and finite, like the ingest readers' own.
+    nonisolated static func liveSubtitleRenditionSessionConfiguration() -> URLSessionConfiguration {
+        let configuration = URLSessionConfiguration.ephemeral
+        configuration.timeoutIntervalForRequest = 10
+        configuration.timeoutIntervalForResource = 30
+        return configuration
     }
 
     /// `URLSession.shared` cannot carry a delegate, so this was the one engine fetch a host's trust
     /// decision could never reach. Owned and process-wide for the same reason the carriage probe's
     /// is: an uninvalidated session outlives its caller.
-    private static let renditionSession = URLSession(
-        configuration: .default, delegate: EngineTLS.sessionDelegate, delegateQueue: nil)
+    nonisolated static let renditionSession = URLSession(
+        configuration: liveSubtitleRenditionSessionConfiguration(),
+        delegate: EngineTLS.sessionDelegate, delegateQueue: nil)
 
-    private static func fetchText(_ url: URL, headers: [String: String]) async throws -> String {
+    /// One poll of a rendition playlist, fetched under a size cap with its status checked and parsed
+    /// off the main actor (audit FEA-104, FEA-107). nil when the URL answers with a master playlist.
+    nonisolated static func fetchLiveSubtitleRenditionPlaylist(
+        _ url: URL, headers: [String: String], session: URLSession = renditionSession
+    ) async throws -> HLSMediaPlaylist? {
         var request = URLRequest(url: url)
         for (key, value) in headers { request.setValue(value, forHTTPHeaderField: key) }
-        let (data, _) = try await renditionSession.data(for: request)
+        let (data, response) = try await BoundedPlaylistFetch.data(
+            for: request, session: session, limit: HLSLiveIngestReader.maximumPlaylistBytes)
+        let status = (response as? HTTPURLResponse)?.statusCode ?? -1
+        guard (200..<300).contains(status) else { throw HLSIngestError.playlistUnreachable(status: status) }
         guard let text = String(data: data, encoding: .utf8) else {
             throw HLSIngestError.playlistInvalid(reason: "rendition payload is not UTF-8")
         }
-        return text
+        guard case .media(let media) = try HLSPlaylistParser.parse(text) else { return nil }
+        return media
+    }
+
+    /// One WebVTT segment: nil for anything that is not a parsable body within the cap (audit SUB-106,
+    /// FEA-107). A segment that fails is not retried, as before.
+    nonisolated static func fetchLiveSubtitleRenditionSegment(
+        _ url: URL, headers: [String: String], session: URLSession = renditionSession
+    ) async -> WebVTTSegment? {
+        var request = URLRequest(url: url)
+        for (key, value) in headers { request.setValue(value, forHTTPHeaderField: key) }
+        guard let (data, response) = try? await BoundedFetch.data(
+                for: request, session: session, limit: BoundedFetch.webVTTSegmentLimit),
+              let status = (response as? HTTPURLResponse)?.statusCode, (200..<300).contains(status),
+              let text = String(data: data, encoding: .utf8)
+        else { return nil }
+        return WebVTTSegmentParser.parse(text)
     }
 
     /// Drop the renditions and stop any fetch. Called from the session teardown paths that already
diff --git a/Sources/AetherEngine/Subtitles/WebVTTSegmentParser.swift b/Sources/AetherEngine/Subtitles/WebVTTSegmentParser.swift
index 0ee8e61a2..d98c44b2d 100644
--- a/Sources/AetherEngine/Subtitles/WebVTTSegmentParser.swift
+++ b/Sources/AetherEngine/Subtitles/WebVTTSegmentParser.swift
@@ -29,6 +29,9 @@ enum WebVTTSegmentParser {
     /// are cut on frame times, so the clipped halves rarely meet exactly.
     private static let joinTolerance = 0.25
 
+    /// Audit SUB-106: a real broadcaster segment carries 0 to 5 cues. Cues past this count are not read.
+    static let maxCuesPerSegment = 4096
+
     static func parse(_ text: String) -> WebVTTSegment? {
         let lines = text.replacingOccurrences(of: "\r\n", with: "\n").components(separatedBy: "\n")
         guard lines.first(where: { !$0.trimmingCharacters(in: .whitespaces).isEmpty })?
@@ -61,6 +64,7 @@ enum WebVTTSegmentParser {
             let joined = body.joined(separator: "\n").trimmingCharacters(in: .whitespacesAndNewlines)
             if !joined.isEmpty {
                 cues.append(WebVTTSegment.Cue(start: start, end: end, text: joined))
+                if cues.count >= maxCuesPerSegment { break }
             }
         }
         return WebVTTSegment(anchorLocalSeconds: anchor.local, anchorMPEGTS90k: anchor.mpegts, cues: cues)
@@ -101,10 +105,17 @@ enum WebVTTSegmentParser {
     static func merged(into existing: [SubtitleCue], adding: [SubtitleCue],
                        nextID: inout Int) -> [SubtitleCue] {
         var result = existing
+        // Audit SUB-106: only a cue with identical text can join, so the candidates come from a
+        // per-text index instead of a scan of everything published (40k cues took 3.9 s). The
+        // indices stay ascending, so the first match is the one the scan found.
+        var indicesByText: [String: [Int]] = [:]
+        for (index, candidate) in result.enumerated() {
+            if case .text(let text) = candidate.body { indicesByText[text, default: []].append(index) }
+        }
         for cue in adding {
             guard case .text(let text) = cue.body else { continue }
-            let match = result.firstIndex { candidate in
-                guard case .text(let candidateText) = candidate.body, candidateText == text else { return false }
+            let match = indicesByText[text]?.first { index in
+                let candidate = result[index]
                 return cue.startTime <= candidate.endTime + joinTolerance
                     && cue.endTime >= candidate.startTime - joinTolerance
             }
@@ -116,6 +127,7 @@ enum WebVTTSegmentParser {
                                             body: old.body,
                                             placement: old.placement)
             } else {
+                indicesByText[text, default: []].append(result.count)
                 result.append(cue)
             }
         }
@@ -142,14 +154,17 @@ enum WebVTTSegmentParser {
     }
 
     /// `HH:MM:SS.mmm` or `MM:SS.mmm`; hours are unbounded (providers run the LOCAL clock for days).
+    /// Audit SUB-106: `Double(_:)` accepts `inf`, `nan` and `1e999`, and a cue ending at `+inf` was
+    /// never pruned, so a value that is not a finite non-negative number is refused.
     private static func parseTimestamp(_ text: String) -> Double? {
         let parts = text.components(separatedBy: ":")
         guard parts.count == 2 || parts.count == 3 else { return nil }
         let values = parts.compactMap { Double($0.replacingOccurrences(of: ",", with: ".")) }
-        guard values.count == parts.count else { return nil }
-        return parts.count == 3
+        guard values.count == parts.count, values.allSatisfy({ $0.isFinite && $0.sign == .plus }) else { return nil }
+        let seconds = parts.count == 3
             ? values[0] * 3600 + values[1] * 60 + values[2]
             : values[0] * 60 + values[1]
+        return seconds.isFinite ? seconds : nil
     }
 
 
diff --git a/Tests/AetherEngineTests/LiveSubtitleRenditionHardeningTests.swift b/Tests/AetherEngineTests/LiveSubtitleRenditionHardeningTests.swift
new file mode 100644
index 000000000..0be91a740
--- /dev/null
+++ b/Tests/AetherEngineTests/LiveSubtitleRenditionHardeningTests.swift
@@ -0,0 +1,254 @@
+import Foundation
+import Testing
+@testable import AetherEngine
+
+/// Audit FEA-104 / FEA-107 / SUB-106: the live subtitle rendition loop fetched, parsed and merged on
+/// the main actor, through a session with a 7-day resource timeout, no status check and no cap, and
+/// `WebVTTSegmentParser.merged` compared every cue against everything published (40k cues took 3.9 s)
+/// while `inf` and `nan` timestamps were accepted and a `+inf` end was never pruned.
+struct LiveSubtitleRenditionHardeningTests {
+
+    private func cue(_ id: Int, _ text: String, _ start: Double, _ end: Double) -> SubtitleCue {
+        SubtitleCue(id: id, startTime: start, endTime: end, body: .text(text))
+    }
+
+    /// The fold `merged` was before the per-text index, kept as the oracle.
+    private func legacyMerged(into existing: [SubtitleCue], adding: [SubtitleCue]) -> [SubtitleCue] {
+        var result = existing
+        for cue in adding {
+            guard case .text(let text) = cue.body else { continue }
+            let match = result.firstIndex { candidate in
+                guard case .text(let candidateText) = candidate.body, candidateText == text else { return false }
+                return cue.startTime <= candidate.endTime + 0.25
+                    && cue.endTime >= candidate.startTime - 0.25
+            }
+            if let match {
+                let old = result[match]
+                result[match] = SubtitleCue(id: old.id,
+                                            startTime: min(old.startTime, cue.startTime),
+                                            endTime: max(old.endTime, cue.endTime),
+                                            body: old.body,
+                                            placement: old.placement)
+            } else {
+                result.append(cue)
+            }
+        }
+        return result
+    }
+
+    private struct Snapshot: Equatable {
+        let id: Int
+        let start: Double
+        let end: Double
+        let text: String?
+
+        init(_ cue: SubtitleCue) {
+            id = cue.id
+            start = cue.startTime
+            end = cue.endTime
+            text = cue.text
+        }
+    }
+
+    private struct SplitMix64: RandomNumberGenerator {
+        var state: UInt64
+        mutating func next() -> UInt64 {
+            state &+= 0x9E37_79B9_7F4A_7C15
+            var z = state
+            z = (z ^ (z >> 30)) &* 0xBF58_476D_1CE4_E5B9
+            z = (z ^ (z >> 27)) &* 0x94D0_49BB_1331_11EB
+            return z ^ (z >> 31)
+        }
+    }
+
+    // MARK: - merged
+
+    @Test("the indexed merge gives what the scan gave, on colliding texts and touching ranges")
+    func mergeMatchesTheOldScan() {
+        var rng = SplitMix64(state: 0x5EED_0106)
+        let texts = ["a", "b", "c", "a b", "", "\u{00E9}"]
+        for round in 0..<300 {
+            func make(_ count: Int, firstID: Int) -> [SubtitleCue] {
+                (0..<count).map { offset in
+                    let start = Double(Int.random(in: 0...60, using: &rng)) / 2
+                    let length = [0.0, 0.25, 0.5, 1, 2.5].randomElement(using: &rng)!
+                    return cue(firstID + offset, texts.randomElement(using: &rng)!, start, start + length)
+                }
+            }
+            let existing = make(Int.random(in: 0...12, using: &rng), firstID: 0)
+            let adding = make(Int.random(in: 0...12, using: &rng), firstID: 100)
+            var nextID = 1000
+            let got = WebVTTSegmentParser.merged(into: existing, adding: adding, nextID: &nextID)
+            #expect(got.map(Snapshot.init) == legacyMerged(into: existing, adding: adding).map(Snapshot.init), "round \(round)")
+        }
+    }
+
+    @Test("merging 40k distinct cues is linear")
+    func mergeIsLinear() {
+        let adding = (0..<40_000).map { cue($0, "line \($0)", Double($0), Double($0) + 0.5) }
+        var nextID = 0
+        let started = ContinuousClock.now
+        let merged = WebVTTSegmentParser.merged(into: [], adding: adding, nextID: &nextID)
+        let elapsed = ContinuousClock.now - started
+        #expect(merged.count == 40_000)
+        #expect(elapsed < .seconds(1), "took \(elapsed)")
+    }
+
+    @Test("re-feeding a merged segment changes nothing")
+    func refeedingIsIdempotent() {
+        let adding = (0..<500).map { cue($0, "line \($0 % 50)", Double($0), Double($0) + 0.5) }
+        var nextID = 0
+        let once = WebVTTSegmentParser.merged(into: [], adding: adding, nextID: &nextID)
+        let twice = WebVTTSegmentParser.merged(into: once, adding: adding, nextID: &nextID)
+        #expect(twice.map(Snapshot.init) == once.map(Snapshot.init))
+    }
+
+    // MARK: - parse
+
+    private func segment(_ cues: String) -> String {
+        "WEBVTT\nX-TIMESTAMP-MAP=LOCAL:00:00:00.000,MPEGTS:0\n\n\(cues)"
+    }
+
+    @Test("a cue with a non-finite or negative timestamp is dropped and the others stay")
+    func nonFiniteTimestampsAreDropped() throws {
+        let text = segment("""
+        00:00:01.000 --> 00:00:02.000
+        good
+
+        00:00:inf --> 00:00:03.000
+        start infinity
+
+        00:00:01.000 --> 00:00:inf
+        end infinity
+
+        00:00:nan --> 00:00:03.000
+        start nan
+
+        00:00:01.000 --> 00:00:nan
+        end nan
+
+        00:00:01.000 --> 00:00:1e999
+        end overflow
+
+        -00:00:05.000 --> 00:00:03.000
+        negative
+
+        00:00:04.000 --> 00:00:05.000
+        also good
+        """)
+        let parsed = try #require(WebVTTSegmentParser.parse(text))
+        #expect(parsed.cues.map(\.text) == ["good", "also good"])
+        #expect(parsed.cues.allSatisfy { $0.start.isFinite && $0.end.isFinite })
+    }
+
+    @Test("ordinary timestamps still parse, with a comma as the decimal mark too")
+    func ordinaryTimestampsStillParse() throws {
+        let parsed = try #require(WebVTTSegmentParser.parse(segment("""
+        164:04:24.000 --> 164:04:25.440
+        long clock
+
+        01:02,500 --> 01:03.000
+        short form
+        """)))
+        #expect(parsed.cues.count == 2)
+        #expect(abs(parsed.cues[0].start - (164 * 3600 + 4 * 60 + 24)) < 0.001)
+        #expect(abs(parsed.cues[1].start - 62.5) < 0.001)
+    }
+
+    @Test("a segment holds at most 4096 cues")
+    func cuesPerSegmentAreCapped() throws {
+        var body = ""
+        for index in 0..<10_000 { body += "00:00:\(String(format: "%02d", index % 60)).000 --> 00:59:00.000\ncue \(index)\n\n" }
+        let parsed = try #require(WebVTTSegmentParser.parse(segment(body)))
+        #expect(parsed.cues.count == WebVTTSegmentParser.maxCuesPerSegment)
+        #expect(parsed.cues.first?.text == "cue 0")
+    }
+
+    // MARK: - the fetch, off the main actor
+
+    private func media(_ origin: CannedHTTPOrigin, _ path: String) -> URL {
+        URL(string: origin.baseURL + path)!
+    }
+
+    @Test("a rendition playlist is fetched and parsed from a detached task")
+    func playlistFetchRunsOffTheMainActor() async throws {
+        let origin = try #require(CannedHTTPOrigin())
+        defer { origin.stop() }
+        origin.route("/subs.m3u8", .body("""
+        #EXTM3U
+        #EXT-X-TARGETDURATION:6
+        #EXT-X-PROGRAM-DATE-TIME:2026-09-30T10:00:00.000Z
+        #EXTINF:6.0,
+        seg0.vtt
+        """, contentType: "application/vnd.apple.mpegurl"))
+        let url = media(origin, "/subs.m3u8")
+        let playlist = try await Task.detached {
+            try await AetherEngine.fetchLiveSubtitleRenditionPlaylist(url, headers: [:])
+        }.value
+        #expect(playlist?.segments.map(\.uri) == ["seg0.vtt"])
+        #expect(playlist?.segments.first?.programDateTime != nil)
+    }
+
+    @Test("a master where a media playlist belongs is reported as none, an error status throws")
+    func playlistFetchRefusals() async throws {
+        let origin = try #require(CannedHTTPOrigin())
+        defer { origin.stop() }
+        origin.route("/master.m3u8", .body("""
+        #EXTM3U
+        #EXT-X-STREAM-INF:BANDWIDTH=1000
+        v.m3u8
+        """, contentType: "application/vnd.apple.mpegurl"))
+        origin.route("/gone.m3u8", .status(404))
+        let master = media(origin, "/master.m3u8")
+        let gone = media(origin, "/gone.m3u8")
+        let asMaster = try await Task.detached {
+            try await AetherEngine.fetchLiveSubtitleRenditionPlaylist(master, headers: [:])
+        }.value
+        #expect(asMaster == nil)
+        await #expect(throws: HLSIngestError.playlistUnreachable(status: 404)) {
+            _ = try await Task.detached {
+                try await AetherEngine.fetchLiveSubtitleRenditionPlaylist(gone, headers: [:])
+            }.value
+        }
+    }
+
+    @Test("a WebVTT segment is parsed off the main actor, an oversized or failing one is dropped")
+    func segmentFetch() async throws {
+        let origin = try #require(CannedHTTPOrigin())
+        defer { origin.stop() }
+        origin.route("/ok.vtt", .body(segment("00:00:01.000 --> 00:00:02.000\nhello"), contentType: "text/vtt"))
+        let filler = String(repeating: "x", count: 1_200_000)
+        origin.route("/huge.vtt", .body(segment("00:00:01.000 --> 00:00:02.000\n\(filler)"), contentType: "text/vtt"))
+        origin.route("/gone.vtt", .status(500))
+        let ok = media(origin, "/ok.vtt")
+        let huge = media(origin, "/huge.vtt")
+        let gone = media(origin, "/gone.vtt")
+        let parsed = await Task.detached {
+            await AetherEngine.fetchLiveSubtitleRenditionSegment(ok, headers: [:])
+        }.value
+        #expect(parsed?.cues.map(\.text) == ["hello"])
+        let oversized = await Task.detached {
+            await AetherEngine.fetchLiveSubtitleRenditionSegment(huge, headers: [:])
+        }.value
+        #expect(oversized == nil)
+        let failing = await Task.detached {
+            await AetherEngine.fetchLiveSubtitleRenditionSegment(gone, headers: [:])
+        }.value
+        #expect(failing == nil)
+    }
+
+    @Test("the rendition session has a finite resource timeout")
+    func sessionTimeoutsAreFinite() {
+        let configuration = AetherEngine.liveSubtitleRenditionSessionConfiguration()
+        #expect(configuration.timeoutIntervalForResource <= 60)
+        #expect(configuration.timeoutIntervalForRequest <= 30)
+    }
+
+    @Test("the published cue list is capped")
+    func publishedCuesAreCapped() {
+        let cues = (0..<5_000).map { cue($0, "c\($0)", Double($0), Double($0) + 1) }
+        let kept = AetherEngine.capLiveSubtitleCues(cues)
+        #expect(kept.count == AetherEngine.maxLiveSubtitleCues)
+        #expect(kept.last?.id == 4_999)
+    }
+}

From fff5b96ed4ff7400c8daf63ee3afd9c47774c819 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 09:25:15 +0200
Subject: [PATCH 217/359] perf(dovi): rebuild a P7 packet with one copy instead
 of two (audit PERF-111)

The P7 to 8.1 rewrite copied every surviving NAL into its own [UInt8] and
then copied each array again into the output buffer, so a 4K packet paid two
payload copies and one heap array per NAL. The walk now records where each
surviving NAL lives (the source packet, or the libdovi buffer of a rewritten
RPU) and the single av_buffer_alloc is filled straight from those, before the
source buffer is released. The RPU is still rewritten by libdovi and the
packet is rebuilt, never patched in place, because mode 2 can shrink the RPU.

The tests keep the two-copy rebuild as a reference and compare the output
byte for byte (real RPU, several RPUs, degraded RPU, Annex B and 4-byte
length prefixes, zeroed padding). Measured in the debug harness on a 250 KB
packet with SEI, slice, RPU and EL: 19.5 and 23.2 us before, 15.9 and 18.3 us
after (two rounds each).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../AetherEngine/Video/DoviRpuConverter.swift |  49 +++---
 .../DoviRpuConverterTests.swift               | 150 ++++++++++++++++++
 2 files changed, 175 insertions(+), 24 deletions(-)

diff --git a/Sources/AetherEngine/Video/DoviRpuConverter.swift b/Sources/AetherEngine/Video/DoviRpuConverter.swift
index 951b0484a..2dd68515e 100644
--- a/Sources/AetherEngine/Video/DoviRpuConverter.swift
+++ b/Sources/AetherEngine/Video/DoviRpuConverter.swift
@@ -39,7 +39,18 @@ public enum DoviRpuConverter {
         guard Self.canRebuild(framing) else { return true }
         let size = Int(packet.pointee.size)
 
-        var outputNALs: [[UInt8]] = []
+        // Audit PERF-111: what survives is described, not copied. Each piece points into the source
+        // packet (passed through) or into a libdovi buffer (a rewritten RPU), and the one rebuild below
+        // is the only copy. The source stays alive until that copy is made, and the libdovi buffers
+        // until this function returns.
+        struct Piece {
+            let base: UnsafePointer<UInt8>
+            let count: Int
+        }
+        var pieces: [Piece] = []
+        pieces.reserveCapacity(16)
+        var rewritten: [UnsafePointer<DoviData>] = []
+        defer { for buffer in rewritten { dovi_data_free(buffer) } }
         var converted = false
         var droppedEL = false
         var degraded = false
@@ -56,34 +67,26 @@ public enum DoviRpuConverter {
                     degraded = true
                     return
                 }
-                let rc = dovi_convert_rpu_with_mode(rpu, 2)
-                if rc != 0 {
-                    dovi_rpu_free(rpu)
+                defer { dovi_rpu_free(rpu) }
+                guard dovi_convert_rpu_with_mode(rpu, 2) == 0,
+                      let out = dovi_write_unspec62_nalu(rpu) else {
                     degraded = true
                     return
                 }
-                guard let out = dovi_write_unspec62_nalu(rpu) else {
-                    dovi_rpu_free(rpu)
-                    degraded = true
-                    return
-                }
-                let outLen = out.pointee.len
-                guard let outData = out.pointee.data, outLen > 0 else {
+                guard let outData = out.pointee.data, out.pointee.len > 0 else {
                     dovi_data_free(out)
-                    dovi_rpu_free(rpu)
                     degraded = true
                     return
                 }
-                outputNALs.append([UInt8](UnsafeBufferPointer(start: outData, count: outLen)))
-                dovi_data_free(out)
-                dovi_rpu_free(rpu)
+                rewritten.append(out)
+                pieces.append(Piece(base: outData, count: out.pointee.len))
                 converted = true
 
             case nalTypeEL:
                 droppedEL = true
 
             default:
-                outputNALs.append([UInt8](UnsafeBufferPointer(start: nal, count: len)))
+                pieces.append(Piece(base: nal, count: len))
             }
         }
 
@@ -92,8 +95,8 @@ public enum DoviRpuConverter {
         }
 
         var total = 0
-        for nal in outputNALs {
-            total += lengthPrefixSize + nal.count
+        for piece in pieces {
+            total += lengthPrefixSize + piece.count
         }
         // Degenerate: all NALs were RPU/EL. Leave the packet untouched rather than emit a zero-length video packet.
         guard total > 0 else { return true }
@@ -110,8 +113,8 @@ public enum DoviRpuConverter {
 
         let emitsStartCodes = framing == .annexB
         var w = 0
-        for nal in outputNALs {
-            let n = nal.count
+        for piece in pieces {
+            let n = piece.count
             if emitsStartCodes {
                 dst[w + 0] = 0; dst[w + 1] = 0; dst[w + 2] = 0; dst[w + 3] = 1
             } else {
@@ -121,10 +124,8 @@ public enum DoviRpuConverter {
                 dst[w + 3] = UInt8(n & 0xFF)
             }
             w += lengthPrefixSize
-            nal.withUnsafeBufferPointer { src in
-                if let base = src.baseAddress, n > 0 {
-                    memcpy(dst + w, base, n)
-                }
+            if n > 0 {
+                memcpy(dst + w, piece.base, n)
             }
             w += n
         }
diff --git a/Tests/AetherEngineTests/DoviRpuConverterTests.swift b/Tests/AetherEngineTests/DoviRpuConverterTests.swift
index eee659ea2..e7a4741d2 100644
--- a/Tests/AetherEngineTests/DoviRpuConverterTests.swift
+++ b/Tests/AetherEngineTests/DoviRpuConverterTests.swift
@@ -1,5 +1,6 @@
 import Testing
 import AetherLibavcodec
+import Dovi
 @testable import AetherEngine
 
 /// Deterministic NAL-walk checks for the DV P7 -> P8.1 converter (#132/#135).
@@ -184,4 +185,153 @@ struct DoviRpuConverterTests {
         #expect(DoviRpuConverter.enhancementLayerType(pkt, framing: .annexB) == nil)
         #expect(annexBNALTypes(pkt) == [1, 62])
     }
+
+    // MARK: - Audit PERF-111: one rebuild, byte-identical to the two-copy rebuild it replaced
+
+    /// A real unspec62 RPU NAL (139 bytes, from Dolby's Profile 8.1 test signal), so the rewrite-and-
+    /// keep branch is exercised and not only the degrade branch.
+    private static let realRPU: [UInt8] = {
+        let hex = "7c0119080908406136506f003ff801ffc00fffd0000008000006800000400000340000030200000301a2566000035ea2566f9fceb1c256644ca00000100000030080000003008000000301c36224301860a5e308e0514000001a63e5affff000000300000300000300060200f80e1530100a0000030000030000030024180fa000040fa00640a3c503f380"
+        var out: [UInt8] = []
+        var i = hex.startIndex
+        while i < hex.endIndex {
+            let j = hex.index(i, offsetBy: 2)
+            out.append(UInt8(hex[i..<j], radix: 16)!)
+            i = j
+        }
+        return out
+    }()
+
+    /// The rebuild as it was before: every surviving NAL copied into its own array, then copied again
+    /// into the output. Kept here as the reference the single-copy rebuild has to match byte for byte.
+    private func legacyRebuild(_ input: [UInt8], framing: VideoNALFraming) -> (bytes: [UInt8], ok: Bool)? {
+        var outputNALs: [[UInt8]] = []
+        var converted = false, droppedEL = false, degraded = false
+        input.withUnsafeBufferPointer { buf in
+            A53SEIParser.forEachNAL(buf.baseAddress!, buf.count, framing) { nal, len in
+                switch (nal[0] >> 1) & 0x3F {
+                case 62:
+                    guard let rpu = dovi_parse_unspec62_nalu(nal, len) else { degraded = true; return }
+                    if dovi_convert_rpu_with_mode(rpu, 2) != 0 { dovi_rpu_free(rpu); degraded = true; return }
+                    guard let out = dovi_write_unspec62_nalu(rpu) else { dovi_rpu_free(rpu); degraded = true; return }
+                    guard let data = out.pointee.data, out.pointee.len > 0 else {
+                        dovi_data_free(out); dovi_rpu_free(rpu); degraded = true; return
+                    }
+                    outputNALs.append([UInt8](UnsafeBufferPointer(start: data, count: out.pointee.len)))
+                    dovi_data_free(out)
+                    dovi_rpu_free(rpu)
+                    converted = true
+                case 63:
+                    droppedEL = true
+                default:
+                    outputNALs.append([UInt8](UnsafeBufferPointer(start: nal, count: len)))
+                }
+            }
+        }
+        if !converted && !droppedEL && !degraded { return nil }
+        var bytes: [UInt8] = []
+        for nal in outputNALs {
+            if framing == .annexB {
+                bytes += [0, 0, 0, 1]
+            } else {
+                let n = nal.count
+                bytes += [UInt8((n >> 24) & 0xFF), UInt8((n >> 16) & 0xFF), UInt8((n >> 8) & 0xFF), UInt8(n & 0xFF)]
+            }
+            bytes += nal
+        }
+        return bytes.isEmpty ? nil : (bytes, !degraded)
+    }
+
+    private func packetBytes(_ pkt: UnsafeMutablePointer<AVPacket>) -> [UInt8] {
+        [UInt8](UnsafeBufferPointer(start: pkt.pointee.data, count: Int(pkt.pointee.size)))
+    }
+
+    private func framed(_ nals: [[UInt8]], _ framing: VideoNALFraming) -> [UInt8] {
+        var bytes: [UInt8] = []
+        for nal in nals {
+            if framing == .annexB {
+                bytes += [0, 0, 0, 1]
+            } else {
+                let n = nal.count
+                bytes += [UInt8((n >> 24) & 0xFF), UInt8((n >> 16) & 0xFF), UInt8((n >> 8) & 0xFF), UInt8(n & 0xFF)]
+            }
+            bytes += nal
+        }
+        return bytes
+    }
+
+    private func packet(from bytes: [UInt8]) -> UnsafeMutablePointer<AVPacket> {
+        let pkt = av_packet_alloc()!
+        _ = av_new_packet(pkt, Int32(bytes.count))
+        bytes.withUnsafeBytes { _ = memcpy(pkt.pointee.data, $0.baseAddress, bytes.count) }
+        return pkt
+    }
+
+    private func slice(_ count: Int, seed: UInt8) -> [UInt8] {
+        let header = hevcNAL(type: 1, payload: [])
+        var state = UInt32(seed) &+ 1
+        return header + (0..<count).map { _ in
+            state = state &* 1664525 &+ 1013904223
+            return UInt8(truncatingIfNeeded: state >> 24)
+        }
+    }
+
+    private func expectMatchesLegacy(_ nals: [[UInt8]], framing: VideoNALFraming,
+                                     expectSuccess: Bool, sourceLocation: SourceLocation = #_sourceLocation) {
+        let input = framed(nals, framing)
+        let reference = legacyRebuild(input, framing: framing)
+        let pkt = packet(from: input)
+        defer { free(pkt) }
+
+        let ok = DoviRpuConverter.convertPacketToProfile81(pkt, framing: framing)
+        #expect(ok == expectSuccess, sourceLocation: sourceLocation)
+        if let reference {
+            #expect(reference.ok == ok, sourceLocation: sourceLocation)
+            #expect(packetBytes(pkt) == reference.bytes, "the rebuilt packet differs from the two-copy rebuild",
+                    sourceLocation: sourceLocation)
+            let pad = Int(AV_INPUT_BUFFER_PADDING_SIZE)
+            let tail = [UInt8](UnsafeBufferPointer(start: pkt.pointee.data + Int(pkt.pointee.size), count: pad))
+            #expect(tail == [UInt8](repeating: 0, count: pad), "decoders read past size", sourceLocation: sourceLocation)
+        } else {
+            #expect(packetBytes(pkt) == input, "a packet with nothing to rewrite is left alone",
+                    sourceLocation: sourceLocation)
+        }
+    }
+
+    @Test("A real RPU is rewritten and every other NAL survives byte for byte, in order (length-prefixed)")
+    func realRPUMatchesTheTwoCopyRebuild() {
+        let sei = hevcNAL(type: 39, payload: [0x01, 0x02, 0x03, 0x00, 0x00, 0x03, 0x01])
+        expectMatchesLegacy([hevcNAL(type: 32, payload: [0x0C]), sei, slice(40_000, seed: 1),
+                             Self.realRPU, hevcNAL(type: 63, payload: [0xCC, 0xDD])],
+                            framing: .lengthPrefixed(size: 4), expectSuccess: true)
+    }
+
+    @Test("A real RPU is rewritten and every other NAL survives byte for byte, in order (Annex B)")
+    func realRPUMatchesTheTwoCopyRebuildAnnexB() {
+        expectMatchesLegacy([slice(3_000, seed: 2), Self.realRPU, slice(9_000, seed: 3)],
+                            framing: .annexB, expectSuccess: true)
+    }
+
+    @Test("A malformed RPU degrades exactly as before: dropped, the rest untouched, failure reported")
+    func degradedPacketMatchesTheTwoCopyRebuild() {
+        expectMatchesLegacy([slice(5_000, seed: 4), hevcNAL(type: 62, payload: [0x00]), slice(700, seed: 5),
+                             hevcNAL(type: 63, payload: [0x01])],
+                            framing: .lengthPrefixed(size: 4), expectSuccess: false)
+    }
+
+    @Test("Several RPUs in one packet are each rewritten in place of their own position")
+    func severalRPUsKeepTheirPositions() {
+        expectMatchesLegacy([slice(100, seed: 6), Self.realRPU, slice(200, seed: 7), Self.realRPU, slice(300, seed: 8)],
+                            framing: .lengthPrefixed(size: 4), expectSuccess: true)
+    }
+
+    @Test("A packet that is nothing but RPU and EL is left untouched")
+    func onlyRPUAndELIsLeftAlone() {
+        let input = framed([hevcNAL(type: 63, payload: [0x01]), hevcNAL(type: 63, payload: [0x02])], .lengthPrefixed(size: 4))
+        let pkt = packet(from: input)
+        defer { free(pkt) }
+        // The EL is dropped, which would leave nothing: the degenerate guard keeps the packet.
+        #expect(DoviRpuConverter.convertPacketToProfile81(pkt) == true)
+        #expect(packetBytes(pkt) == input)
+    }
 }

From 2d2b89aedcb5b8607738fad52825523a779d97c3 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 09:26:37 +0200
Subject: [PATCH 218/359] perf(demuxer): idle detour blocks are released
 instead of living until close (audit PERF-108)

The detour block cache (8 blocks of 4 MB) was only emptied by `close()`, so
the blocks a backward scrub filled stayed resident for the rest of the
session, up to 32 MB per reader and double that with the subtitle side
reader.

`DetourBlockCache` now stamps each block when it is inserted or served and
`evictIdle(olderThan:)` drops those nothing has touched for 30 s. The read
path sweeps at most once a second, and playback's re-anchor sweeps at once.
Age rather than a clear at the re-anchor, because a parser ping-ponging
through a region keeps hitting its blocks and must keep them. The clock is
injectable, so the unit test moves it by hand; the threshold is a reader init
parameter for the reader-level test.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 Sources/AetherEngine/Demuxer/AVIOReader.swift | 66 ++++++++++++++++++-
 .../DetourBlockCacheTests.swift               | 54 +++++++++++++++
 .../DetourBlockIdleReleaseTests.swift         | 46 +++++++++++++
 3 files changed, 163 insertions(+), 3 deletions(-)
 create mode 100644 Tests/AetherEngineTests/DetourBlockIdleReleaseTests.swift

diff --git a/Sources/AetherEngine/Demuxer/AVIOReader.swift b/Sources/AetherEngine/Demuxer/AVIOReader.swift
index 2871b93dc..2e55567f0 100644
--- a/Sources/AetherEngine/Demuxer/AVIOReader.swift
+++ b/Sources/AetherEngine/Demuxer/AVIOReader.swift
@@ -697,6 +697,9 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
     // playback fast path never enters this code, so it carries zero overhead.
     private static let detourBlockSize = 4 * 1024 * 1024
     private static let detourMaxBlocks = 8                       // ~32 MB LRU ceiling
+    /// Audit PERF-108: a detour block nobody has read or filled for this long is a scrub's leftover,
+    /// not a parse's working set (a parser revisits its region within seconds).
+    private static let detourBlockIdleSecondsDefault: TimeInterval = 30
     // Once detour reads turn sequential past this much, re-anchor the streaming connection
     // there so sustained playback returns to the cheap window path (e.g. after a backward scrub).
     private static let detourReanchorBytes: Int64 = 8 * 1024 * 1024
@@ -810,6 +813,9 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
         return streamFailureCause
     }
 
+    /// Detour blocks currently resident.
+    var detourResidentBlocksForTesting: Int { detourCache.residentCount }
+
     /// The most the forward-only streaming buffer has held at once.
     var streamPeakBufferBytesForTesting: Int {
         streamLock.lock()
@@ -935,6 +941,12 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
     /// math lives on the cache and is unit-tested without any network.
     private let detourCache = DetourBlockCache(blockSize: AVIOReader.detourBlockSize,
                                                maxBlocks: AVIOReader.detourMaxBlocks)
+    /// When the detour cache was last swept for idle blocks (audit PERF-108). Demux-thread-only.
+    private var lastDetourIdleSweepNs: UInt64 = 0
+    /// How long a detour block may sit unread before the sweep releases it. An init parameter for
+    /// the same reason `connStallTimeout` is one: a process-wide hook would leak into whatever suite
+    /// runs concurrently.
+    private let detourBlockIdleSeconds: TimeInterval
     // Re-anchor run tracking (demux-thread-only): the file offset the next sequential detour read
     // would continue from, and how many contiguous bytes the current detour run has served.
     private var detourRunNextExpected: Int64 = -1
@@ -1086,7 +1098,7 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
     private let probeDrainLock = NSLock()
     private var drainingProbeRequest = false
 
-    init(url: URL, extraHeaders: [String: String] = [:], label: String = "source", chunkSize: Int = 4 * 1024 * 1024, prefetchEnabled: Bool = true, isLive: Bool = false, chunkRequestTimeout: TimeInterval = 35, chunkMaxRetries: Int = 3, boundedInitialFetch: Int64? = nil, sequentialOnly: Bool = false, connStallTimeout: TimeInterval = AVIOReader.connStallTimeoutDefault, windowHighWater: Int? = nil, streamHighWater: Int? = nil, heldConnection: Bool = false, probeControl: ProbeControl? = nil, probeRequestSession: URLSession? = nil) {
+    init(url: URL, extraHeaders: [String: String] = [:], label: String = "source", chunkSize: Int = 4 * 1024 * 1024, prefetchEnabled: Bool = true, isLive: Bool = false, chunkRequestTimeout: TimeInterval = 35, chunkMaxRetries: Int = 3, boundedInitialFetch: Int64? = nil, sequentialOnly: Bool = false, connStallTimeout: TimeInterval = AVIOReader.connStallTimeoutDefault, windowHighWater: Int? = nil, streamHighWater: Int? = nil, detourIdleSeconds: TimeInterval? = nil, heldConnection: Bool = false, probeControl: ProbeControl? = nil, probeRequestSession: URLSession? = nil) {
         self.probeControl = probeControl
         self.probeRequestSession = probeControl == nil ? nil : probeRequestSession
         self.url = url
@@ -1106,6 +1118,7 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
         self.winHighWater = max(1, windowHighWater
             ?? (isLive ? Self.liveWinHighWaterDefault : Self.winHighWaterDefault))
         self.streamHighWater = max(1, streamHighWater ?? Self.streamHighWaterDefault)
+        self.detourBlockIdleSeconds = detourIdleSeconds ?? Self.detourBlockIdleSecondsDefault
         self.heldConnectionEnabled = heldConnection
     }
 
@@ -1933,6 +1946,7 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
     private func readPersistent(into buf: UnsafeMutablePointer<UInt8>, size: Int32) -> Int32 {
         let requestSize = Int(size)
         var totalRead = 0
+        sweepIdleDetourBlocks()
 
         // #93 restart latency: accumulate where THIS read spends its time; one summary line fires
         // on completion when the whole call exceeded the threshold (see SlowReadDiagnostics).
@@ -2131,6 +2145,7 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
                     // the cheap window path instead of fetching 4 MB blocks forever.
                     if curPosition == detourRunNextExpected && detourRunBytes >= Self.detourReanchorBytes {
                         detourResetRun()
+                        sweepIdleDetourBlocks(force: true)
                         timedReconnect(seek: true, at: curPosition)
                         continue
                     }
@@ -2668,6 +2683,21 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
         }
     }
 
+    /// Audit PERF-108: release detour blocks nothing has touched for `detourBlockIdleSeconds`, at most
+    /// once a second from the read path and unconditionally when playback re-anchors, which is the
+    /// moment a scrub's blocks stop being anyone's working set. Demux-thread-only.
+    private func sweepIdleDetourBlocks(force: Bool = false) {
+        let now = DispatchTime.now().uptimeNanoseconds
+        guard force || now &- lastDetourIdleSweepNs >= 1_000_000_000 else { return }
+        lastDetourIdleSweepNs = now
+        let evicted = detourCache.evictIdle(olderThan: detourBlockIdleSeconds)
+        if evicted > 0 {
+            EngineLog.emit(
+                "[AVIOReader] \(label) released \(evicted) idle detour block(s) "
+                + "(\(detourCache.residentCount) resident)", category: .demux, level: .verbose)
+        }
+    }
+
     /// Tracks contiguity of detour reads for the re-anchor heuristic. Shared by BOTH the backward
     /// and far-forward branches; the re-anchor check itself lives only in the backward branch on
     /// purpose, so a forward-accumulated run later met by a contiguous backward read is an intended
@@ -4429,12 +4459,18 @@ final class DetourBlockCache: @unchecked Sendable {
     private let lock = NSLock()
     private var blocks: [Int64: Data] = [:]
     private var lru: [Int64] = []
+    /// When each resident block was last inserted or served, on `now`'s clock (audit PERF-108).
+    private var lastHit: [Int64: TimeInterval] = [:]
     private let maxBlocks: Int
+    private let now: @Sendable () -> TimeInterval
     let blockSize: Int
 
-    init(blockSize: Int, maxBlocks: Int) {
+    /// `now` is injectable so the idle test moves a clock instead of waiting one out.
+    init(blockSize: Int, maxBlocks: Int,
+         now: @escaping @Sendable () -> TimeInterval = { ProcessInfo.processInfo.systemUptime }) {
         self.blockSize = blockSize
         self.maxBlocks = maxBlocks
+        self.now = now
     }
 
     /// Returns the resident block for `idx` and bumps its recency, or nil on a miss.
@@ -4445,6 +4481,7 @@ final class DetourBlockCache: @unchecked Sendable {
             lru.remove(at: i)
             lru.append(idx)
         }
+        lastHit[idx] = now()
         return data
     }
 
@@ -4453,15 +4490,38 @@ final class DetourBlockCache: @unchecked Sendable {
         lock.lock(); defer { lock.unlock() }
         if blocks[idx] == nil { lru.append(idx) }
         blocks[idx] = data
+        lastHit[idx] = now()
         while lru.count > maxBlocks {
-            blocks.removeValue(forKey: lru.removeFirst())
+            let evicted = lru.removeFirst()
+            blocks.removeValue(forKey: evicted)
+            lastHit[evicted] = nil
+        }
+    }
+
+    /// Drops every block nothing has read or filled for `seconds`, and returns how many went. The
+    /// cache is otherwise only emptied at close, so the blocks of a backward scrub (up to 32 MB)
+    /// outlived the scrub for the whole session (audit PERF-108). Age rather than a clear at the
+    /// re-anchor, because a parser ping-ponging through a region keeps hitting its blocks.
+    @discardableResult
+    func evictIdle(olderThan seconds: TimeInterval) -> Int {
+        lock.lock(); defer { lock.unlock() }
+        let cutoff = now() - seconds
+        let idle = lru.filter { (lastHit[$0] ?? 0) < cutoff }
+        guard !idle.isEmpty else { return 0 }
+        let gone = Set(idle)
+        lru.removeAll { gone.contains($0) }
+        for idx in idle {
+            blocks.removeValue(forKey: idx)
+            lastHit[idx] = nil
         }
+        return idle.count
     }
 
     func clear() {
         lock.lock()
         blocks.removeAll()
         lru.removeAll()
+        lastHit.removeAll()
         lock.unlock()
     }
 
diff --git a/Tests/AetherEngineTests/DetourBlockCacheTests.swift b/Tests/AetherEngineTests/DetourBlockCacheTests.swift
index 9985e6287..b76f84db3 100644
--- a/Tests/AetherEngineTests/DetourBlockCacheTests.swift
+++ b/Tests/AetherEngineTests/DetourBlockCacheTests.swift
@@ -116,6 +116,60 @@ struct DetourBlockCacheTests {
         #expect(Array(dst[0..<4]) == [100, 101, 102, 103])   // newest value served
     }
 
+    /// A clock a test moves by hand.
+    private final class ManualClock: @unchecked Sendable {
+        private let lock = NSLock()
+        private var seconds: TimeInterval = 1000
+        var now: TimeInterval { lock.lock(); defer { lock.unlock() }; return seconds }
+        func advance(_ by: TimeInterval) { lock.lock(); seconds += by; lock.unlock() }
+    }
+
+    // audit PERF-108: only close() emptied the cache, so the blocks of a backward scrub stayed
+    // resident (up to 32 MB per reader) for the rest of the session.
+    @Test("a block idle past the threshold is evicted and a recently hit one survives")
+    func idleEviction() {
+        let clock = ManualClock()
+        let cache = DetourBlockCache(blockSize: 16, maxBlocks: 8, now: { clock.now })
+        cache.insert(0, patternBlock(base: 0))
+        cache.insert(1, patternBlock(base: 16))
+        cache.insert(2, patternBlock(base: 32))
+
+        clock.advance(20)
+        _ = cache.block(1)
+        var dst = [UInt8](repeating: 0, count: 16)
+        #expect(dst.withUnsafeMutableBufferPointer { cache.serveCached(into: $0.baseAddress!, maxLen: 4, at: 32) } == 4)
+        clock.advance(20)
+
+        // Block 0 has been idle 40 s; blocks 1 and 2 were hit 20 s ago.
+        #expect(cache.evictIdle(olderThan: 30) == 1)
+        #expect(cache.residentCount == 2)
+        #expect(cache.block(0) == nil)
+        #expect(cache.block(1) != nil)
+        #expect(cache.block(2) != nil)
+
+        clock.advance(31)
+        #expect(cache.evictIdle(olderThan: 30) == 2)
+        #expect(cache.residentCount == 0)
+        #expect(cache.evictIdle(olderThan: 30) == 0)
+    }
+
+    @Test("a block that was evicted for age leaves the LRU order, so a later insert does not trip on it")
+    func evictedBlockLeavesTheOrder() {
+        let clock = ManualClock()
+        let cache = DetourBlockCache(blockSize: 16, maxBlocks: 2, now: { clock.now })
+        cache.insert(0, patternBlock(base: 0))
+        clock.advance(60)
+        cache.insert(1, patternBlock(base: 16))
+        #expect(cache.evictIdle(olderThan: 30) == 1)
+
+        cache.insert(2, patternBlock(base: 32))
+        cache.insert(3, patternBlock(base: 48))
+        #expect(cache.residentCount == 2)
+        #expect(cache.block(1) == nil, "the oldest surviving block is the one the size cap evicts")
+        #expect(cache.block(2) != nil)
+        #expect(cache.block(3) != nil)
+    }
+
     @Test("clear empties the cache")
     func clearEmpties() {
         let cache = DetourBlockCache(blockSize: 16, maxBlocks: 3)
diff --git a/Tests/AetherEngineTests/DetourBlockIdleReleaseTests.swift b/Tests/AetherEngineTests/DetourBlockIdleReleaseTests.swift
new file mode 100644
index 000000000..283abed55
--- /dev/null
+++ b/Tests/AetherEngineTests/DetourBlockIdleReleaseTests.swift
@@ -0,0 +1,46 @@
+import Testing
+import Foundation
+@testable import AetherEngine
+
+/// Audit PERF-108: the detour cache was only emptied at close, so the blocks a backward scrub filled
+/// (up to 32 MB per reader) stayed resident for the rest of the session. The read path now sweeps
+/// blocks nothing has read for a while.
+@Suite("Detour block idle release")
+struct DetourBlockIdleReleaseTests {
+
+    @Test("a detour block nothing reads any more is released by the read path", .timeLimit(.minutes(2)))
+    func idleBlockIsReleased() async throws {
+        let maybe = ThrottledOriginServer(totalSize: 64 * 1024 * 1024, throttleUs: 1000)
+        let server = try #require(maybe)
+        defer { server.stop() }
+        let url = URL(string: "http://127.0.0.1:\(server.port)/movie.bin")!
+        let reader = AVIOReader(url: url, detourIdleSeconds: 0.2)
+        defer { reader.markClosed(); reader.close() }
+        try reader.open()
+
+        let chunk = 256 * 1024
+        let buf = UnsafeMutablePointer<UInt8>.allocate(capacity: chunk)
+        defer { buf.deallocate() }
+        var read = 0
+        while read < 13 * 1024 * 1024 {
+            let n = Int(reader.read(into: buf, size: Int32(chunk)))
+            #expect(n > 0, "forward read failed at \(read)")
+            if n <= 0 { return }
+            read += n
+        }
+        let frontier = Int64(read)
+
+        // Backward past the retained head and the window: this fills the 4 to 8 MB block.
+        #expect(reader.seek(offset: 5 * 1024 * 1024, whence: Int32(SEEK_SET)) == 5 * 1024 * 1024)
+        #expect(reader.read(into: buf, size: Int32(chunk)) > 0)
+        #expect(reader.detourResidentBlocksForTesting == 1, "no detour block was filled, so this measured nothing")
+
+        // Back to the window. Nothing reads the block from here on, and each read is a chance for
+        // the sweep, which runs at most once a second.
+        #expect(reader.seek(offset: frontier, whence: Int32(SEEK_SET)) == frontier)
+        try await waitFor {
+            _ = reader.read(into: buf, size: Int32(chunk))
+            return reader.detourResidentBlocksForTesting == 0
+        }
+    }
+}

From fd5e9c0e893bc768c3cdbe91b6a782a8a155e251 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 10:32:52 +0200
Subject: [PATCH 219/359] fix(demuxer): the held connection's chunked decoder
 bounds a size or trailer line and the framing around a body (audit DMX-111)

A size, terminator or trailer line with no CRLF made takeLine return nil for
ever, so the pull loop kept feeding it: the buffer grew at wire rate and every
call rescanned all of it. Blank lines and trailer fields were consumed without
a byte of body, so they never ended either. A line is now refused past 4 KiB
(only that window is scanned) and 64 KiB of framing without a body byte ends
the connection with a typed error. A chunk's own body is unbounded.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../Demuxer/HeldSourceConnection.swift        |  36 ++++-
 .../ChunkedBodyDecoderBoundsTests.swift       | 133 ++++++++++++++++++
 2 files changed, 163 insertions(+), 6 deletions(-)
 create mode 100644 Tests/AetherEngineTests/ChunkedBodyDecoderBoundsTests.swift

diff --git a/Sources/AetherEngine/Demuxer/HeldSourceConnection.swift b/Sources/AetherEngine/Demuxer/HeldSourceConnection.swift
index e59a0e5c7..87e9623c7 100644
--- a/Sources/AetherEngine/Demuxer/HeldSourceConnection.swift
+++ b/Sources/AetherEngine/Demuxer/HeldSourceConnection.swift
@@ -506,6 +506,16 @@ final class ChunkedBodyDecoder {
     private var buffer = Data()
     private var state: State = .size
 
+    /// Audit DMX-111: a size, terminator or trailer line longer than this is a malformed origin. A
+    /// line with no CRLF would otherwise be buffered and rescanned for one that is not coming.
+    static let maxLineBytes = 4096
+    /// Framing bytes (size lines, terminators, blank lines, trailer fields) the decoder consumes
+    /// without one byte of body in between. Bounds the states that consume without producing:
+    /// endless blank lines, endless trailer fields.
+    static let maxFramingBytes = 64 * 1024
+    private static let crlf = Data("\r\n".utf8)
+    private var framingBytes = 0
+
     var isComplete: Bool {
         if case .done = state { return true }
         return false
@@ -524,7 +534,7 @@ final class ChunkedBodyDecoder {
             case .done:
                 break loop
             case .size:
-                guard let line = takeLine() else { break loop }
+                guard let line = try takeLine() else { break loop }
                 if line.isEmpty { continue }   // tolerate the CRLF of a preceding chunk
                 let sizeField = line.split(separator: ";", maxSplits: 1).first.map(String.init) ?? line
                 guard let size = Int(sizeField.trimmingCharacters(in: .whitespaces), radix: 16), size >= 0 else {
@@ -537,34 +547,48 @@ final class ChunkedBodyDecoder {
                 if want == 0 { break loop }
                 out.append(buffer.prefix(want))
                 buffer.removeFirst(want)
+                framingBytes = 0
                 state = remaining - want == 0 ? .dataTerminator : .data(remaining: remaining - want)
             case .dataTerminator:
-                guard let line = takeLine() else { break loop }
+                guard let line = try takeLine() else { break loop }
                 guard line.isEmpty else { throw ChunkedError.expectedChunkTerminator(line) }
                 state = .size
             case .trailer:
-                guard let line = takeLine() else { break loop }
+                guard let line = try takeLine() else { break loop }
                 if line.isEmpty { state = .done }
             }
         }
         return out.isEmpty ? nil : out
     }
 
-    private func takeLine() -> String? {
-        guard let range = buffer.range(of: Data("\r\n".utf8)) else { return nil }
+    /// The next CRLF-terminated line, nil while there is not one yet. Only the first
+    /// `maxLineBytes + 2` bytes are searched, so a line with no end costs a bounded scan and is
+    /// refused instead of waited for.
+    private func takeLine() throws -> String? {
+        let window = buffer.startIndex..<min(buffer.endIndex, buffer.startIndex + Self.maxLineBytes + 2)
+        guard let range = buffer.range(of: Self.crlf, in: window) else {
+            if buffer.count >= Self.maxLineBytes + 2 { throw ChunkedError.lineTooLong }
+            return nil
+        }
+        framingBytes += buffer.distance(from: buffer.startIndex, to: range.upperBound)
+        if framingBytes > Self.maxFramingBytes { throw ChunkedError.framingTooLong }
         let line = String(decoding: buffer[..<range.lowerBound], as: UTF8.self)
         buffer.removeSubrange(..<range.upperBound)
         return line
     }
 
-    enum ChunkedError: LocalizedError {
+    enum ChunkedError: LocalizedError, Equatable {
         case badChunkSize(String)
         case expectedChunkTerminator(String)
+        case lineTooLong
+        case framingTooLong
 
         var errorDescription: String? {
             switch self {
             case .badChunkSize(let line): return "bad chunk size line: \(line)"
             case .expectedChunkTerminator(let line): return "expected a chunk terminator, got: \(line)"
+            case .lineTooLong: return "a chunked size or trailer line passed \(ChunkedBodyDecoder.maxLineBytes) bytes"
+            case .framingTooLong: return "chunked framing passed \(ChunkedBodyDecoder.maxFramingBytes) bytes without a body byte"
             }
         }
     }
diff --git a/Tests/AetherEngineTests/ChunkedBodyDecoderBoundsTests.swift b/Tests/AetherEngineTests/ChunkedBodyDecoderBoundsTests.swift
new file mode 100644
index 000000000..527b5acc5
--- /dev/null
+++ b/Tests/AetherEngineTests/ChunkedBodyDecoderBoundsTests.swift
@@ -0,0 +1,133 @@
+import Testing
+import Foundation
+@testable import AetherEngine
+
+/// Audit DMX-111: the held connection's chunked decoder waited for a CRLF it would never be sent.
+/// A size or trailer line with no end made `takeLine` return nil forever, so the caller kept feeding
+/// it, the buffer grew at wire rate and every call rescanned all of it. The blank-line and trailer
+/// states consumed forever without producing a byte. A line and the framing around a body are
+/// bounded now, and a chunk's own body is not.
+@Suite("Chunked decoder bounds")
+struct ChunkedBodyDecoderBoundsTests {
+
+    private let maxLine = ChunkedBodyDecoder.maxLineBytes
+    private let maxFraming = ChunkedBodyDecoder.maxFramingBytes
+
+    /// Feeds `wire` in `piece`-sized steps, taking after every step, until `take` throws or the wire
+    /// is spent. Returns the error, if any, how many bytes had been fed when it came, and the body.
+    private func run(_ decoder: ChunkedBodyDecoder, _ wire: Data, piece: Int = 1024)
+        -> (error: ChunkedBodyDecoder.ChunkedError?, fed: Int, body: Data) {
+        var fed = 0
+        var body = Data()
+        while fed < wire.count {
+            let end = min(fed + piece, wire.count)
+            decoder.feed(wire.subdata(in: fed..<end))
+            fed = end
+            do {
+                while let out = try decoder.take(upTo: 1 << 20) { body.append(out) }
+            } catch let error as ChunkedBodyDecoder.ChunkedError {
+                return (error, fed, body)
+            } catch {
+                Issue.record("unexpected error \(error)")
+                return (nil, fed, body)
+            }
+        }
+        return (nil, fed, body)
+    }
+
+    @Test("a size line that never ends is refused once it is longer than a line can be")
+    func unterminatedSizeLine() {
+        let wire = Data(repeating: UInt8(ascii: "a"), count: 1024 * 1024)
+        let result = run(ChunkedBodyDecoder(), wire)
+        #expect(result.error == .lineTooLong)
+        #expect(result.fed <= maxLine + 2 + 1024, "took \(result.fed) bytes before refusing the line")
+    }
+
+    @Test("a trailer line that never ends is refused the same way")
+    func unterminatedTrailerLine() {
+        let wire = Data("0\r\n".utf8) + Data(repeating: UInt8(ascii: "x"), count: 1024 * 1024)
+        let result = run(ChunkedBodyDecoder(), wire)
+        #expect(result.error == .lineTooLong)
+        #expect(result.fed <= 3 + maxLine + 2 + 1024, "took \(result.fed) bytes before refusing the line")
+    }
+
+    @Test("a chunk terminator that is not a line end is refused at the same bound")
+    func unterminatedChunkTerminator() {
+        let wire = Data("3\r\nabc".utf8) + Data(repeating: UInt8(ascii: "z"), count: 1024 * 1024)
+        let result = run(ChunkedBodyDecoder(), wire)
+        #expect(result.error == .lineTooLong)
+        #expect(String(decoding: result.body, as: UTF8.self) == "abc")
+    }
+
+    @Test("endless trailer fields are refused by their total size")
+    func endlessTrailerFields() {
+        var wire = Data("0\r\n".utf8)
+        let field = Data("X-Padding: 0123456789abcdef0123456789abcdef\r\n".utf8)
+        for _ in 0..<(4 * maxFraming / field.count) { wire.append(field) }
+        let result = run(ChunkedBodyDecoder(), wire)
+        #expect(result.error == .framingTooLong)
+        #expect(result.fed < 2 * maxFraming, "took \(result.fed) bytes before refusing the trailer")
+    }
+
+    @Test("a run of blank lines where a chunk size belongs is refused")
+    func endlessBlankLines() {
+        let wire = Data(String(repeating: "\r\n", count: 2 * maxFraming).utf8)
+        let result = run(ChunkedBodyDecoder(), wire)
+        #expect(result.error == .framingTooLong)
+        #expect(result.fed < 2 * maxFraming, "took \(result.fed) bytes before refusing the run")
+    }
+
+    @Test("a size line at the limit is fine, one byte past it is not, however the wire is cut")
+    func lineLimitIsExact() {
+        // A size line is `<hex>;<extension>`, so the extension pads it to the length under test.
+        func wire(lineBytes: Int) -> Data {
+            let head = "5;"
+            let padding = String(repeating: "e", count: lineBytes - head.count)
+            return Data((head + padding + "\r\nhello\r\n0\r\n\r\n").utf8)
+        }
+        for piece in [1, 7, 1024, 1 << 20] {
+            let ok = run(ChunkedBodyDecoder(), wire(lineBytes: maxLine), piece: piece)
+            #expect(ok.error == nil, "a line of \(maxLine) bytes in pieces of \(piece)")
+            #expect(String(decoding: ok.body, as: UTF8.self) == "hello")
+
+            let tooLong = run(ChunkedBodyDecoder(), wire(lineBytes: maxLine + 1), piece: piece)
+            #expect(tooLong.error == .lineTooLong, "a line of \(maxLine + 1) bytes in pieces of \(piece)")
+        }
+    }
+
+    @Test("the bounds are on framing, not on the body a chunk carries")
+    func bodyIsNotBounded() {
+        let payload = Data(repeating: 0x42, count: 3 * 1024 * 1024)
+        let wire = Data("300000\r\n".utf8) + payload + Data("\r\n0\r\n\r\n".utf8)
+        let decoder = ChunkedBodyDecoder()
+        let result = run(decoder, wire, piece: 64 * 1024)
+        #expect(result.error == nil)
+        #expect(result.body == payload)
+        #expect(decoder.isComplete)
+    }
+
+    @Test("framing that adds up past the bound across many small chunks is fine, because body resets it")
+    func manySmallChunks() {
+        let chunkCount = 4 * maxFraming / 6
+        var wire = Data()
+        for _ in 0..<chunkCount { wire.append(Data("1\r\nx\r\n".utf8)) }
+        wire.append(Data("0\r\n\r\n".utf8))
+        #expect(wire.count > 2 * maxFraming)
+        let decoder = ChunkedBodyDecoder()
+        let result = run(decoder, wire)
+        #expect(result.error == nil)
+        #expect(result.body.count == chunkCount)
+        #expect(decoder.isComplete)
+    }
+
+    @Test("a realistic trailer still ends the body")
+    func realisticTrailer() {
+        let trailer = (0..<8).map { "X-Field-\($0): value-\($0)\r\n" }.joined()
+        let wire = Data(("5\r\nhello\r\n0\r\n" + trailer + "\r\n").utf8)
+        let decoder = ChunkedBodyDecoder()
+        let result = run(decoder, wire)
+        #expect(result.error == nil)
+        #expect(String(decoding: result.body, as: UTF8.self) == "hello")
+        #expect(decoder.isComplete)
+    }
+}

From 96c63b67c5d6324795f00bb694382ded52235b59 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 10:36:39 +0200
Subject: [PATCH 220/359] fix(disc): recognition bounds what a disc image can
 make it read and keep (audit NET-103)

A crafted image named its own counts: 65535 PlayItems per playlist, about 160k .mpls entries that can
all point at one ICB (each read and parsed and kept), thousands of extents per clip re-summed per item,
a per-item linear name scan with string interpolation, and any VTS number as a DVD title set. The
title assembly was quadratic (1000 x 2000 took 0.6 s, 4000 x 2000 took 9.2 s) and memory passed 2 GB
after about 1000 retained playlists.

- MPLSParser refuses more than 999 PlayItems (the BD-ROM limit).
- DiscReader.scanPlaylists caps .mpls entries at 4000, playlist bytes at 32 MiB and retained PlayItems
  at 500k, and stops after 16 unreadable playlists in a row (a cancelled or closed reader).
- DiscReader.assembleBluRayTitle looks each distinct clip up once through a name index, keeps a running
  byte offset instead of reducing the extent list per item, ends a title at 65536 extents, and logs the
  per-clip line at .verbose.
- DVDTitleSelector groups only VTS 1 to 99 and wrap looks the IFOs up through one name index.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../AetherEngine/Disc/DVDTitleSelector.swift  |   6 +-
 Sources/AetherEngine/Disc/DiscReader.swift    | 145 ++++++++---
 Sources/AetherEngine/Disc/MPLSParser.swift    |   4 +
 .../DiscRecognitionBoundsTests.swift          | 225 ++++++++++++++++++
 4 files changed, 351 insertions(+), 29 deletions(-)
 create mode 100644 Tests/AetherEngineTests/DiscRecognitionBoundsTests.swift

diff --git a/Sources/AetherEngine/Disc/DVDTitleSelector.swift b/Sources/AetherEngine/Disc/DVDTitleSelector.swift
index 3516be7f8..9fe0a7f9b 100644
--- a/Sources/AetherEngine/Disc/DVDTitleSelector.swift
+++ b/Sources/AetherEngine/Disc/DVDTitleSelector.swift
@@ -4,13 +4,17 @@ import Foundation
 /// VTS_nn_0.VOB = menus; VTS_nn_1..9.VOB = content. Titles are ordered largest-first (total content
 /// VOB size, a proxy for duration) so id 0 is the main feature, matching the Blu-ray convention.
 enum DVDTitleSelector {
+    /// DVD-Video numbers its title sets 01 to 99. The number is an on-disc name, so anything else is
+    /// not a title set and must not become a group (audit NET-103).
+    static let vtsRange = 1...99
+
     /// One selectable title = one VTS's content VOBs (whole-VTS resolution; per-cell/episodic splitting
     /// is deferred). VOBs within a title are ordered by part; titles are ordered by total size, largest first.
     static func enumerateTitleVOBGroups(_ files: [DiscFile]) -> [(vtsn: Int, vobs: [DiscFile])] {
         struct Part { let title: Int; let part: Int; let file: DiscFile }
         var parts: [Part] = []
         for f in files {
-            guard let (title, part) = parseVOBName(f.name), part >= 1 else { continue }
+            guard let (title, part) = parseVOBName(f.name), part >= 1, vtsRange.contains(title) else { continue }
             parts.append(Part(title: title, part: part, file: f))
         }
         let byTitle = Dictionary(grouping: parts, by: \.title)
diff --git a/Sources/AetherEngine/Disc/DiscReader.swift b/Sources/AetherEngine/Disc/DiscReader.swift
index 52ec41dbd..1b77a1f44 100644
--- a/Sources/AetherEngine/Disc/DiscReader.swift
+++ b/Sources/AetherEngine/Disc/DiscReader.swift
@@ -49,13 +49,9 @@ enum DiscReader {
             return nil
         }
         let playlistDir = (try? udf.list(path: ["BDMV", "PLAYLIST"])) ?? []
-        var parsed: [MPLSPlaylist] = []
-        for e in playlistDir where e.name.hasSuffix(".mpls") {
-            let exts = (try? udf.extents(of: e)) ?? []
-            guard !exts.isEmpty else { continue }
-            let bytes = readAll(reader, exts)
-            if let pl = MPLSParser.parse(bytes) { parsed.append(pl) }
-        }
+        let parsed = scanPlaylists(playlistDir,
+                                   extents: { (try? udf.extents(of: $0)) ?? [] },
+                                   read: { readAll(reader, $0) })
         let titles = BDTitleSelector.enumerateTitles(parsed)
         guard !titles.isEmpty else {
             EngineLog.emit("[disc] BDMV present but no parseable .mpls (\(playlistDir.count) PLAYLIST entries, \(parsed.count) parsed); cannot select a title", category: .demux)
@@ -64,24 +60,14 @@ enum DiscReader {
         let selectedIndex = selectTitleID.flatMap { titles.indices.contains($0) ? $0 : nil } ?? 0
         let selected = titles[selectedIndex]
         let streamDir = (try? udf.list(path: ["BDMV", "STREAM"])) ?? []
-        var allExtents: [(offset: Int64, length: Int64)] = []
-        // One ClipSpan per resolved clip: byte start in the concat stream + how far to pull its
-        // timestamps back so it continues contiguously from clip 0 (AE#105 multi-clip position drift).
-        var clipTimeline: [ClipSpan] = []
-        let subTicks = selected.bdClipSubtractTicks ?? []
-        let cumBeforeTicks = selected.bdClipCumulativeBeforeTicks ?? []
-        for (k, clip) in (selected.bdClipIDs ?? []).enumerated() {
-            guard let e = streamDir.first(where: { $0.name == "\(clip).m2ts" }),
-                  let exts = try? udf.extents(of: e) else { continue }
-            let byteStart = allExtents.reduce(Int64(0)) { $0 + max(0, $1.length) }
-            let predictedShift = k < subTicks.count ? Double(subTicks[k]) / discTickRate : 0
-            let cumBeforeSec = k < cumBeforeTicks.count ? Double(cumBeforeTicks[k]) / discTickRate : 0
-            clipTimeline.append(ClipSpan(concatByteStart: byteStart,
-                                         cumulativeBeforeSec: cumBeforeSec,
-                                         predictedShiftSec: predictedShift))
-            EngineLog.emit("[disc] AE#105 clip[\(k)] id=\(clip) subTicks=\(k < subTicks.count ? subTicks[k] : 0) predictedSec=\(String(format: "%.3f", predictedShift)) cumBeforeSec=\(String(format: "%.3f", cumBeforeSec)) byteStart=\(byteStart)", category: .demux)
-            allExtents += exts
-        }
+        let streamIndex = Dictionary(streamDir.map { ($0.name, $0) }, uniquingKeysWith: { first, _ in first })
+        let assembled = assembleBluRayTitle(
+            clipIDs: selected.bdClipIDs ?? [],
+            subtractTicks: selected.bdClipSubtractTicks ?? [],
+            cumulativeBeforeTicks: selected.bdClipCumulativeBeforeTicks ?? [],
+            extentsOfClip: { clip in streamIndex["\(clip).m2ts"].flatMap { try? udf.extents(of: $0) } })
+        let allExtents = assembled.extents
+        var clipTimeline = assembled.clipTimeline
         guard !allExtents.isEmpty else {
             EngineLog.emit("[disc] selected title \(selectedIndex) clips=\(selected.bdClipIDs ?? []) but resolved no m2ts extents in BDMV/STREAM (\(streamDir.count) entries); cannot build stream", category: .demux)
             return nil
@@ -102,6 +88,108 @@ enum DiscReader {
                         clipTimeline: clipTimeline)
     }
 
+    // MARK: - Bounds on what a disc image can make recognition do (audit NET-103)
+
+    /// `.mpls` entries examined per PLAYLIST directory. Real discs carry dozens, anti-rip discs a few hundred.
+    static let maxPlaylistFiles = 4_000
+    /// Bytes of playlist data read in total. A real `.mpls` is KB-scale, so this is orders above any disc.
+    static let maxPlaylistBytes: Int64 = 32 * 1024 * 1024
+    /// PlayItems kept across every parsed playlist (about 32 bytes each), so a directory of maximal
+    /// playlists cannot be retained whole.
+    static let maxPlaylistItems = 500_000
+    /// Extents in one assembled title. A real m2ts is a few dozen extents (1 GB each), a decoy loop
+    /// repeats a short clip a few hundred times.
+    static let maxTitleExtents = 65_536
+    /// A run of this many unreadable playlists means the source is gone (cancelled or closed reader).
+    private static let maxConsecutiveShortReads = 16
+    /// `readAll`'s ceiling.
+    private static let maxSmallFileBytes: Int64 = 8 * 1024 * 1024
+
+    /// Reads and parses the `.mpls` entries of a PLAYLIST directory under the bounds above. Stops at the
+    /// first bound that trips and keeps what was parsed before it.
+    static func scanPlaylists(
+        _ entries: [UDFEntry],
+        extents: (UDFEntry) -> [(offset: Int64, length: Int64)],
+        read: ([(offset: Int64, length: Int64)]) -> [UInt8]
+    ) -> [MPLSPlaylist] {
+        var parsed: [MPLSPlaylist] = []
+        var examined = 0
+        var bytesRead: Int64 = 0
+        var items = 0
+        var shortReads = 0
+        for e in entries where e.name.hasSuffix(".mpls") {
+            examined += 1
+            guard examined <= maxPlaylistFiles else {
+                EngineLog.emit("[disc] PLAYLIST scan stopped at \(maxPlaylistFiles) .mpls entries", category: .demux)
+                break
+            }
+            let exts = extents(e)
+            guard !exts.isEmpty else { continue }
+            let declared = exts.reduce(Int64(0)) { $0 + max(0, $1.length) }
+            guard declared > 0, declared <= maxSmallFileBytes else { continue }
+            bytesRead += declared
+            guard bytesRead <= maxPlaylistBytes else {
+                EngineLog.emit("[disc] PLAYLIST scan stopped after \(maxPlaylistBytes) bytes of playlists", category: .demux)
+                break
+            }
+            let bytes = read(exts)
+            if Int64(bytes.count) < declared {
+                shortReads += 1
+                if shortReads >= maxConsecutiveShortReads {
+                    EngineLog.emit("[disc] PLAYLIST scan stopped, \(shortReads) unreadable playlists in a row", category: .demux)
+                    break
+                }
+            } else {
+                shortReads = 0
+            }
+            guard let pl = MPLSParser.parse(bytes) else { continue }
+            items += pl.clipIDs.count
+            guard items <= maxPlaylistItems else {
+                EngineLog.emit("[disc] PLAYLIST scan stopped after \(maxPlaylistItems) PlayItems", category: .demux)
+                break
+            }
+            parsed.append(pl)
+        }
+        return parsed
+    }
+
+    /// Resolves a title's clips into the concatenated extent list plus one `ClipSpan` per resolved clip
+    /// (byte start in the concat stream, and how far to pull its timestamps back so it continues
+    /// contiguously from clip 0, AE#105). Each distinct clip is looked up once, a repeated clip reuses its
+    /// extents, and the title ends at the clip that would pass `maxTitleExtents`.
+    static func assembleBluRayTitle(
+        clipIDs: [String], subtractTicks: [Int64], cumulativeBeforeTicks: [UInt64],
+        extentsOfClip: (String) -> [(offset: Int64, length: Int64)]?
+    ) -> (extents: [(offset: Int64, length: Int64)], clipTimeline: [ClipSpan]) {
+        var allExtents: [(offset: Int64, length: Int64)] = []
+        var clipTimeline: [ClipSpan] = []
+        var resolved: [String: [(offset: Int64, length: Int64)]?] = [:]
+        var byteStart: Int64 = 0
+        for (k, clip) in clipIDs.enumerated() {
+            let lookup: [(offset: Int64, length: Int64)]?
+            if let known = resolved[clip] {
+                lookup = known
+            } else {
+                lookup = extentsOfClip(clip)
+                resolved[clip] = .some(lookup)
+            }
+            guard let exts = lookup else { continue }
+            guard allExtents.count + exts.count <= maxTitleExtents else {
+                EngineLog.emit("[disc] title truncated at clip[\(k)]: more than \(maxTitleExtents) extents", category: .demux)
+                break
+            }
+            let predictedShift = k < subtractTicks.count ? Double(subtractTicks[k]) / discTickRate : 0
+            let cumBeforeSec = k < cumulativeBeforeTicks.count ? Double(cumulativeBeforeTicks[k]) / discTickRate : 0
+            clipTimeline.append(ClipSpan(concatByteStart: byteStart,
+                                         cumulativeBeforeSec: cumBeforeSec,
+                                         predictedShiftSec: predictedShift))
+            EngineLog.emit("[disc] AE#105 clip[\(k)] id=\(clip) subTicks=\(k < subtractTicks.count ? subtractTicks[k] : 0) predictedSec=\(String(format: "%.3f", predictedShift)) cumBeforeSec=\(String(format: "%.3f", cumBeforeSec)) byteStart=\(byteStart)", category: .demux, level: .verbose)
+            allExtents += exts
+            byteStart += exts.reduce(Int64(0)) { $0 + max(0, $1.length) }
+        }
+        return (allExtents, clipTimeline)
+    }
+
     /// Memoize a successful recognition so a re-open of the same source (track switch on a remote ISO)
     /// reuses it. No-op when the caller passed no cache key (custom sources opt in explicitly).
     private static func storeRecognition(
@@ -129,7 +217,7 @@ enum DiscReader {
         // Extent lengths are untrusted on-disc bytes (up to ~1 GB each). Cap the total before
         // allocating so a crafted .mpls cannot drive an arbitrary allocation (jetsam/DoS); 8 MB
         // matches UDFReader.readDirectory's guard and dwarfs any real playlist (KB-scale).
-        let maxBytes: Int64 = 8 * 1024 * 1024
+        let maxBytes = maxSmallFileBytes
         let declared = exts.reduce(Int64(0)) { $0 + max(0, $1.length) }
         guard declared > 0, declared <= maxBytes else { return [] }
         let total = Int(declared)
@@ -174,7 +262,8 @@ enum DiscReader {
         // incidental content VTS are excluded. Any parse failure (or a filter that would empty the list)
         // falls back to the full VOB-grouped set, so a disc with an unreadable VMGI still plays multi-title.
         var orderedGroups = groups
-        if let ifoFile = files.first(where: { $0.name.uppercased() == "VIDEO_TS.IFO" }) {
+        let filesByName = Dictionary(files.map { ($0.name.uppercased(), $0) }, uniquingKeysWith: { first, _ in first })
+        if let ifoFile = filesByName["VIDEO_TS.IFO"] {
             let ifoBytes = readAll(reader, [(offset: Int64(ifoFile.startSector * iso.sectorSize),
                                              length: Int64(ifoFile.length))])
             if let ifoTitles = DVDIFOParser.parseTitles(ifoBytes) {
@@ -198,7 +287,7 @@ enum DiscReader {
             var subpictureStreamIDs: [Int]?
             let nn = g.vtsn < 10 ? "0\(g.vtsn)" : "\(g.vtsn)"
             let ifoName = "VTS_\(nn)_0.IFO"
-            if let vtsIFO = files.first(where: { $0.name.uppercased() == ifoName }) {
+            if let vtsIFO = filesByName[ifoName] {
                 let bytes = readAll(reader, [(offset: Int64(vtsIFO.startSector * iso.sectorSize),
                                              length: Int64(vtsIFO.length))])
                 if let detail = DVDIFOParser.parseTitleDetail(bytes) {
diff --git a/Sources/AetherEngine/Disc/MPLSParser.swift b/Sources/AetherEngine/Disc/MPLSParser.swift
index a08b39de7..cb4edb0c5 100644
--- a/Sources/AetherEngine/Disc/MPLSParser.swift
+++ b/Sources/AetherEngine/Disc/MPLSParser.swift
@@ -20,12 +20,16 @@ struct MPLSPlaylist: Equatable {
 }
 
 enum MPLSParser {
+    /// BD-ROM caps a playlist at 999 PlayItems, and the count field is 16 bits wide (audit NET-103).
+    static let maxPlayItems = 999
+
     static func parse(_ data: [UInt8]) -> MPLSPlaylist? {
         guard data.count >= 16,
               Array(data[0..<4]) == Array("MPLS".utf8) else { return nil }
         let plStart = be32(data, 8)
         guard plStart + 10 <= data.count else { return nil }
         let count = be16(data, plStart + 6)
+        guard count <= maxPlayItems else { return nil }
         var pos = plStart + 10
         var clips: [String] = []
         var ticks: UInt64 = 0
diff --git a/Tests/AetherEngineTests/DiscRecognitionBoundsTests.swift b/Tests/AetherEngineTests/DiscRecognitionBoundsTests.swift
new file mode 100644
index 000000000..f488ee3b5
--- /dev/null
+++ b/Tests/AetherEngineTests/DiscRecognitionBoundsTests.swift
@@ -0,0 +1,225 @@
+import Foundation
+import Testing
+@testable import AetherEngine
+
+/// Audit NET-103: disc recognition trusted the image's own counts. A crafted Blu-ray made the
+/// title-assembly loop quadratic (1000 PlayItems x 2000 extents took 0.6 s, 4000 took 9.2 s), kept every
+/// parsed `.mpls` alive (a UDF directory under its 8 MB cap names about 160k files that can all point at
+/// one ICB, so memory passed 2 GB after about 1000 entries), and grouped a DVD by any VTS number.
+struct DiscRecognitionBoundsTests {
+
+    private typealias Extents = [(offset: Int64, length: Int64)]
+
+    private func be16(_ v: Int) -> [UInt8] { [UInt8((v >> 8) & 0xff), UInt8(v & 0xff)] }
+    private func be32(_ v: Int) -> [UInt8] {
+        [UInt8((v >> 24) & 0xff), UInt8((v >> 16) & 0xff), UInt8((v >> 8) & 0xff), UInt8(v & 0xff)]
+    }
+
+    private func mpls(playItems declared: Int, present: Int? = nil) -> [UInt8] {
+        func item(_ index: Int) -> [UInt8] {
+            var body: [UInt8] = []
+            body += Array(String(format: "%05d", index % 100_000).utf8)
+            body += Array("M2TS".utf8)
+            body += be16(0)
+            body.append(0)
+            body += be32(0)
+            body += be32(45_000)
+            body += [UInt8](repeating: 0, count: 8)
+            return be16(body.count) + body
+        }
+        var playlist: [UInt8] = []
+        playlist += be32(0)
+        playlist += be16(0)
+        playlist += be16(declared)
+        playlist += be16(0)
+        for index in 0..<(present ?? declared) { playlist += item(index) }
+        var out: [UInt8] = []
+        out += Array("MPLS".utf8)
+        out += Array("0200".utf8)
+        out += be32(40)
+        out += be32(0)
+        out += [UInt8](repeating: 0, count: 40 - out.count)
+        out += playlist
+        return out
+    }
+
+    private func entries(_ count: Int) -> [UDFEntry] {
+        (0..<count).map { UDFEntry(name: "\(String(format: "%05d", $0)).mpls", isDir: false, icbBlock: 7, icbPartRef: 1) }
+    }
+
+    /// A stub source where every entry is a playlist of `bytes`, declared at `declaredLength`.
+    private final class PlaylistSource: @unchecked Sendable {
+        let bytes: [UInt8]
+        let declaredLength: Int64
+        private(set) var extentCalls = 0
+        private(set) var readCalls = 0
+        init(bytes: [UInt8], declaredLength: Int64? = nil) {
+            self.bytes = bytes
+            self.declaredLength = declaredLength ?? Int64(bytes.count)
+        }
+        func scan(_ list: [UDFEntry]) -> [MPLSPlaylist] {
+            DiscReader.scanPlaylists(list,
+                                     extents: { _ in self.extentCalls += 1; return [(offset: 0, length: self.declaredLength)] },
+                                     read: { _ in self.readCalls += 1; return self.bytes })
+        }
+    }
+
+    // MARK: - MPLSParser
+
+    @Test("a playlist may hold at most 999 PlayItems, the BD-ROM limit")
+    func playItemCountIsBounded() {
+        #expect(MPLSParser.parse(mpls(playItems: 999))?.clipIDs.count == 999)
+        #expect(MPLSParser.parse(mpls(playItems: 1000)) == nil)
+        #expect(MPLSParser.parse(mpls(playItems: 65_535, present: 10)) == nil)
+    }
+
+    // MARK: - PLAYLIST scan
+
+    @Test("a PLAYLIST directory of 160k aliases is read at most 4000 times")
+    func playlistEntriesAreCapped() {
+        let source = PlaylistSource(bytes: mpls(playItems: 1))
+        let parsed = source.scan(entries(160_000))
+        #expect(parsed.count == DiscReader.maxPlaylistFiles)
+        #expect(source.extentCalls == DiscReader.maxPlaylistFiles)
+        #expect(source.readCalls == DiscReader.maxPlaylistFiles)
+    }
+
+    @Test("entries that are not .mpls files cost nothing against the cap")
+    func otherEntriesAreNotCounted() {
+        let source = PlaylistSource(bytes: mpls(playItems: 1))
+        var list = (0..<10_000).map { UDFEntry(name: "\($0).clpi", isDir: false, icbBlock: 7, icbPartRef: 1) }
+        list += entries(3)
+        #expect(source.scan(list).count == 3)
+        #expect(source.extentCalls == 3)
+    }
+
+    @Test("playlist bytes are read up to a total budget")
+    func playlistBytesAreBudgeted() {
+        let oneMiB = 1 << 20
+        var padded = mpls(playItems: 1)
+        padded += [UInt8](repeating: 0, count: oneMiB - padded.count)
+        let source = PlaylistSource(bytes: padded)
+        let parsed = source.scan(entries(200))
+        let expected = Int(DiscReader.maxPlaylistBytes) / oneMiB
+        #expect(parsed.count == expected)
+        #expect(source.readCalls == expected)
+    }
+
+    @Test("an oversized playlist extent is skipped without being read or charged")
+    func oversizedPlaylistIsNotRead() {
+        var reads = 0
+        let huge: Extents = [(offset: 0, length: 64 * 1024 * 1024)]
+        let parsed = DiscReader.scanPlaylists(entries(10), extents: { _ in huge }, read: { _ in reads += 1; return [] })
+        #expect(parsed.isEmpty)
+        #expect(reads == 0)
+    }
+
+    @Test("parsed PlayItems are kept up to a total budget")
+    func playItemsAreBudgeted() {
+        let source = PlaylistSource(bytes: mpls(playItems: 999))
+        let parsed = source.scan(entries(600))
+        #expect(parsed.count == DiscReader.maxPlaylistItems / 999)
+        #expect(parsed.reduce(0) { $0 + $1.clipIDs.count } <= DiscReader.maxPlaylistItems)
+    }
+
+    @Test("a source that stops delivering ends the scan after a short run of failures")
+    func unreadableSourceEndsTheScan() {
+        let source = PlaylistSource(bytes: [], declaredLength: 100)
+        #expect(source.scan(entries(1000)).isEmpty)
+        #expect(source.readCalls < 100)
+    }
+
+    @Test("an unparseable playlist does not end the scan")
+    func garbagePlaylistsDoNotEndTheScan() {
+        let garbage = [UInt8](repeating: 0xAB, count: 64)
+        let source = PlaylistSource(bytes: garbage)
+        #expect(source.scan(entries(100)).isEmpty)
+        #expect(source.readCalls == 100)
+    }
+
+    // MARK: - Title assembly
+
+    private func extents(_ count: Int, length: Int64 = 1 << 20, base: Int64 = 0) -> Extents {
+        (0..<count).map { (offset: base + Int64($0) * length, length: length) }
+    }
+
+    @Test("a repeated clip is resolved once and the byte starts run")
+    func repeatedClipIsLookedUpOnce() {
+        var lookups: [String] = []
+        let ids = ["00001", "00002", "00001", "00002", "00001"]
+        let result = DiscReader.assembleBluRayTitle(
+            clipIDs: ids, subtractTicks: [0, 45_000, 0, 45_000, 0],
+            cumulativeBeforeTicks: [0, 90_000, 180_000, 270_000, 360_000],
+            extentsOfClip: { clip in
+                lookups.append(clip)
+                return clip == "00001" ? self.extents(2, length: 100) : self.extents(1, length: 1000)
+            })
+        #expect(lookups == ["00001", "00002"])
+        #expect(result.extents.count == 8)
+        #expect(result.clipTimeline.map(\.concatByteStart) == [0, 200, 1200, 1400, 2400])
+        #expect(result.clipTimeline.map(\.cumulativeBeforeSec) == [0, 2, 4, 6, 8])
+        #expect(result.clipTimeline.map(\.predictedShiftSec) == [0, 1, 0, 1, 0])
+    }
+
+    @Test("a clip without a stream file is skipped and keeps its index for the tick tables")
+    func missingClipIsSkipped() {
+        let result = DiscReader.assembleBluRayTitle(
+            clipIDs: ["00001", "00002", "00003"], subtractTicks: [0, 45_000, 90_000],
+            cumulativeBeforeTicks: [0, 45_000, 90_000],
+            extentsOfClip: { clip in clip == "00002" ? nil : self.extents(1, length: 500) })
+        #expect(result.extents.count == 2)
+        #expect(result.clipTimeline.map(\.concatByteStart) == [0, 500])
+        #expect(result.clipTimeline.map(\.predictedShiftSec) == [0, 2])
+    }
+
+    @Test("a title whose clips hold 2M extents stops at the cap, fast, with consistent spans")
+    func titleExtentsAreCapped() {
+        let ids = (0..<999).map { String(format: "%05d", $0 % 3) }
+        let started = ContinuousClock.now
+        let result = DiscReader.assembleBluRayTitle(
+            clipIDs: ids, subtractTicks: [], cumulativeBeforeTicks: [],
+            extentsOfClip: { _ in self.extents(2_100) })
+        #expect(ContinuousClock.now - started < .seconds(2))
+        let fit = DiscReader.maxTitleExtents / 2_100
+        #expect(result.clipTimeline.count == fit)
+        #expect(result.extents.count == fit * 2_100)
+        #expect(result.clipTimeline.last?.concatByteStart == Int64(fit - 1) * 2_100 * Int64(1 << 20))
+    }
+
+    @Test("a single clip that alone passes the extent cap yields no title")
+    func oversizedClipYieldsNothing() {
+        let result = DiscReader.assembleBluRayTitle(
+            clipIDs: ["00001"], subtractTicks: [], cumulativeBeforeTicks: [],
+            extentsOfClip: { _ in self.extents(DiscReader.maxTitleExtents + 1, length: 1) })
+        #expect(result.extents.isEmpty)
+        #expect(result.clipTimeline.isEmpty)
+    }
+
+    // MARK: - DVD
+
+    @Test("a DVD has title sets 1 to 99, and 8000 names beyond that are not grouped")
+    func vtsNumbersAreBounded() {
+        var files: [DiscFile] = [
+            .init(name: "VTS_01_1.VOB", startSector: 2, length: 100),
+            .init(name: "VTS_99_1.VOB", startSector: 3, length: 200),
+            .init(name: "VTS_00_1.VOB", startSector: 4, length: 300),
+            .init(name: "VTS_100_1.VOB", startSector: 5, length: 400),
+        ]
+        for index in 101..<8_100 { files.append(.init(name: "VTS_\(index)_1.VOB", startSector: index, length: 10)) }
+        let started = ContinuousClock.now
+        let groups = DVDTitleSelector.enumerateTitleVOBGroups(files)
+        #expect(groups.map(\.vtsn) == [99, 1])
+        #expect(ContinuousClock.now - started < .seconds(1))
+    }
+
+    @Test("an ISO naming a VTS beyond 99 never makes that set a title")
+    func dvdWrapIgnoresOutOfRangeTitleSets() throws {
+        let data = ISO9660Fixture.make(files: [
+            .init(name: "VTS_01_1.VOB", length: 2048),
+            .init(name: "VTS_150_1.VOB", length: 900_000_000),
+        ])
+        let info = try #require(try DiscReader.wrap(DataIOReader(data: data)))
+        #expect(info.titles.count == 1)
+        #expect(info.titles.first?.dvdVTSN == 1)
+    }
+}

From e79c088ef8c46ea6ee15d1b22d91ca24b494e6f4 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 10:37:37 +0200
Subject: [PATCH 221/359] perf(software): spool a packet with one writev and
 read it back without intermediate copies (audit PERF-109)

The software VOD read-ahead wrote each record as two write calls (with a header Data allocated
between them), read it back through FileHandle.read(upToCount:) into a temporary and copied that
into a second Data, and decode copied the payload slice once more before makeAVPacket copied it
into the AVPacket. The record now leaves in one writev (a short count finishes with plain writes
and any error latches the FIFO as before), the length is read into a stack value, the payload is
read straight into its one buffer, and decode hands out a view of the record. The on-disk layout
is unchanged. Spool round trip of a 208 KB packet (append, pop, decode, AVPacket) on the dev Mac:
677-927 us before, 350-441 us after.

Not done: building the record straight from AVPacket memory (two of the original five copies
remain on the producer side), which would reshape the read-ahead's readSource contract.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../Native/SoftwarePacketDiskFIFO.swift       |  83 +++++++++---
 .../Native/SoftwareStoredPacket.swift         |   3 +-
 .../SoftwarePacketRecordIOTests.swift         | 125 ++++++++++++++++++
 3 files changed, 193 insertions(+), 18 deletions(-)
 create mode 100644 Tests/AetherEngineTests/SoftwarePacketRecordIOTests.swift

diff --git a/Sources/AetherEngine/Native/SoftwarePacketDiskFIFO.swift b/Sources/AetherEngine/Native/SoftwarePacketDiskFIFO.swift
index ae4dd092e..2126cbf78 100644
--- a/Sources/AetherEngine/Native/SoftwarePacketDiskFIFO.swift
+++ b/Sources/AetherEngine/Native/SoftwarePacketDiskFIFO.swift
@@ -142,10 +142,7 @@ final class SoftwarePacketDiskFIFO: @unchecked Sendable {
             guard let writer else { throw Failure.corruptRecord }
             let cursor = Cursor(chunkID: tailID, generation: generation, offset: tailBytes,
                                 recordIndex: writtenRecordCount, payloadPrefix: writtenPayloadBytes)
-            var length = UInt64(data.count).bigEndian
-            let header = withUnsafeBytes(of: &length) { Data($0) }
-            try writer.write(contentsOf: header)
-            try writer.write(contentsOf: data)
+            try Self.writeRecord(data, to: writer.fileDescriptor)
             tailBytes += UInt64(recordBytes)
             recordCount = nextCount
             payloadBytes = nextPayloadBytes
@@ -174,8 +171,7 @@ final class SoftwarePacketDiskFIFO: @unchecked Sendable {
             }
             guard let reader else { throw Failure.corruptRecord }
             guard headOffset <= limit, limit - headOffset >= 8 else { throw Failure.corruptRecord }
-            let header = try readExactly(8, from: reader)
-            let length = header.reduce(UInt64(0)) { ($0 << 8) | UInt64($1) }
+            let length = try Self.readRecordLength(from: reader)
             guard length <= UInt64(payloadBytes), length <= limit - headOffset - 8 else {
                 throw Failure.corruptRecord
             }
@@ -221,8 +217,7 @@ final class SoftwarePacketDiskFIFO: @unchecked Sendable {
             let size = try replacement.seekToEnd()
             guard cursor.offset <= size, size - cursor.offset >= 8 else { throw Failure.corruptRecord }
             try replacement.seek(toOffset: cursor.offset)
-            let header = try readExactly(8, from: replacement)
-            let length = header.reduce(UInt64(0)) { ($0 << 8) | UInt64($1) }
+            let length = try Self.readRecordLength(from: replacement)
             guard length <= size - cursor.offset - 8,
                   length <= UInt64(writtenPayloadBytes - cursor.payloadPrefix) else {
                 throw Failure.corruptRecord
@@ -279,8 +274,7 @@ final class SoftwarePacketDiskFIFO: @unchecked Sendable {
             try handle.seek(toOffset: offset)
             while offset < limit {
                 guard limit - offset >= 8 else { throw Failure.corruptRecord }
-                let header = try readExactly(8, from: handle)
-                let length = header.reduce(UInt64(0)) { ($0 << 8) | UInt64($1) }
+                let length = try Self.readRecordLength(from: handle)
                 guard length <= limit - offset - 8 else { throw Failure.corruptRecord }
                 let record = try readExactly(Int(length), from: handle)
                 offset += 8 + length
@@ -413,18 +407,73 @@ final class SoftwarePacketDiskFIFO: @unchecked Sendable {
         chunks += 1
     }
 
+    /// Audit PERF-109: one allocation and no copy. `read(upToCount:)` allocated a `Data` per call and
+    /// `append` copied it again into a second one, per payload.
     private func readExactly(_ length: Int, from handle: FileHandle) throws -> Data {
-        var result = Data()
-        result.reserveCapacity(length)
-        while result.count < length {
-            guard let part = try handle.read(upToCount: length - result.count), !part.isEmpty else {
-                throw Failure.corruptRecord
-            }
-            result.append(part)
+        guard length > 0 else { return Data() }
+        var result = Data(count: length)
+        try result.withUnsafeMutableBytes { raw in
+            try Self.readFully(into: raw, from: handle.fileDescriptor)
         }
         return result
     }
 
+    private static func readRecordLength(from handle: FileHandle) throws -> UInt64 {
+        var big: UInt64 = 0
+        try withUnsafeMutableBytes(of: &big) { try readFully(into: $0, from: handle.fileDescriptor) }
+        return UInt64(bigEndian: big)
+    }
+
+    /// EOF before the buffer fills is a record the file does not hold.
+    private static func readFully(into buffer: UnsafeMutableRawBufferPointer, from fd: Int32) throws {
+        guard let base = buffer.baseAddress else { return }
+        var done = 0
+        while done < buffer.count {
+            let n = Darwin.read(fd, base + done, buffer.count - done)
+            if n > 0 { done += n; continue }
+            if n < 0, errno == EINTR { continue }
+            if n < 0 { throw posixError() }
+            throw Failure.corruptRecord
+        }
+    }
+
+    /// Audit PERF-109: the length and the payload leave in one `writev`, not two writes with a
+    /// header `Data` allocated between them. A short count (full volume, quota) finishes with plain
+    /// writes, and any failure throws into the caller's latch, so a half-written record is never
+    /// appended to.
+    private static func writeRecord(_ payload: Data, to fd: Int32) throws {
+        var header = UInt64(payload.count).bigEndian
+        try withUnsafeBytes(of: &header) { head in
+            try payload.withUnsafeBytes { body in
+                let total = head.count + body.count
+                var sent = 0
+                if body.count > 0 {
+                    sent = try withUnsafeTemporaryAllocation(of: iovec.self, capacity: 2) { vec in
+                        vec[0] = iovec(iov_base: UnsafeMutableRawPointer(mutating: head.baseAddress),
+                                       iov_len: head.count)
+                        vec[1] = iovec(iov_base: UnsafeMutableRawPointer(mutating: body.baseAddress),
+                                       iov_len: body.count)
+                        while true {
+                            let n = Darwin.writev(fd, vec.baseAddress, 2)
+                            if n >= 0 { return n }
+                            if errno != EINTR { throw posixError() }
+                        }
+                    }
+                }
+                while sent < total {
+                    let (base, offset) = sent < head.count
+                        ? (head.baseAddress!, sent) : (body.baseAddress!, sent - head.count)
+                    let limit = sent < head.count ? head.count : body.count
+                    let n = Darwin.write(fd, base + offset, limit - offset)
+                    if n > 0 { sent += n; continue }
+                    if n < 0, errno == EINTR { continue }
+                    if n < 0 { throw posixError() }
+                    throw Failure.capacityExceeded
+                }
+            }
+        }
+    }
+
     private func currentReadLimit() throws -> UInt64 {
         if reader == nil { reader = try FileHandle(forReadingFrom: chunkURL(headID)) }
         guard let reader else { throw Failure.corruptRecord }
diff --git a/Sources/AetherEngine/Native/SoftwareStoredPacket.swift b/Sources/AetherEngine/Native/SoftwareStoredPacket.swift
index 4b5bc4a8a..3847285f8 100644
--- a/Sources/AetherEngine/Native/SoftwareStoredPacket.swift
+++ b/Sources/AetherEngine/Native/SoftwareStoredPacket.swift
@@ -111,7 +111,8 @@ struct SoftwareStoredPacket: Sendable, Equatable {
         mutating func bytes(count: UInt64) throws -> Data {
             guard count <= UInt64(remaining) else { throw EnvelopeError.truncated }
             let end = offset + Int(count)
-            let slice = Data(data[offset..<end])
+            // Audit PERF-109: a view of the record, not a copy; the caller copies once into its AVPacket.
+            let slice = data[offset..<end]
             offset = end
             return slice
         }
diff --git a/Tests/AetherEngineTests/SoftwarePacketRecordIOTests.swift b/Tests/AetherEngineTests/SoftwarePacketRecordIOTests.swift
new file mode 100644
index 000000000..f85f0e33f
--- /dev/null
+++ b/Tests/AetherEngineTests/SoftwarePacketRecordIOTests.swift
@@ -0,0 +1,125 @@
+import Foundation
+import Testing
+import AetherLibavcodec
+@testable import AetherEngine
+
+/// Audit PERF-109: a software VOD packet crossed the spool through two write calls, two reads that
+/// each allocated, and two payload copies on the way back out. The record layout is pinned by
+/// `Issue592PacketEnvelopeTests` and by the cursor tests; these pin what the cheaper I/O must keep.
+@Suite("Software packet spool record I/O (audit PERF-109)")
+struct SoftwarePacketRecordIOTests {
+
+    private static func makeRoot() throws -> URL {
+        let root = FileManager.default.temporaryDirectory
+            .appendingPathComponent("perf109-\(UUID().uuidString)", isDirectory: true)
+        try FileManager.default.createDirectory(at: root, withIntermediateDirectories: true)
+        return root
+    }
+
+    private static func payload(_ size: Int, seed: UInt8) -> Data {
+        var data = Data(count: size)
+        data.withUnsafeMutableBytes { raw in
+            for i in 0..<raw.count { raw[i] = UInt8(truncatingIfNeeded: Int(seed) &+ i &* 31) }
+        }
+        return data
+    }
+
+    @Test("records of every size survive the spool across chunk boundaries", arguments: [false, true])
+    func recordsRoundTrip(retainConsumed: Bool) throws {
+        let root = try Self.makeRoot()
+        defer { try? FileManager.default.removeItem(at: root) }
+        let fifo = try SoftwarePacketDiskFIFO(chunkTargetBytes: 64 * 1024, retainConsumed: retainConsumed,
+                                              parentDirectory: root)
+        defer { try? fifo.close() }
+        let sizes = [0, 1, 7, 8, 9, 100, 4_096, 65_528, 65_529, 70_000, 200_000, 0, 3]
+        let records = sizes.enumerated().map { Self.payload($0.element, seed: UInt8($0.offset)) }
+        for record in records { try fifo.append(record) }
+        for record in records { #expect(try fifo.pop() == record) }
+        #expect(try fifo.pop() == nil)
+    }
+
+    @Test("the chunk file is a big-endian length followed by the payload, record after record")
+    func onDiskLayoutIsUnchanged() throws {
+        let root = try Self.makeRoot()
+        defer { try? FileManager.default.removeItem(at: root) }
+        let fifo = try SoftwarePacketDiskFIFO(chunkTargetBytes: 1 << 20, retainConsumed: true,
+                                              parentDirectory: root)
+        defer { try? fifo.close() }
+        let first = Self.payload(300, seed: 1)
+        let second = Data()
+        let third = Self.payload(17, seed: 9)
+        for record in [first, second, third] { try fifo.append(record) }
+
+        let raw = try Data(contentsOf: fifo.storageDirectory.appendingPathComponent("0.packets"))
+        var expected = Data()
+        for record in [first, second, third] {
+            withUnsafeBytes(of: UInt64(record.count).bigEndian) { expected.append(contentsOf: $0) }
+            expected.append(record)
+        }
+        #expect(raw == expected)
+    }
+
+    @Test("a chunk cut short behind the store's back is corruption, and the failure sticks")
+    func truncatedChunkFailsClosed() throws {
+        let root = try Self.makeRoot()
+        defer { try? FileManager.default.removeItem(at: root) }
+        let fifo = try SoftwarePacketDiskFIFO(chunkTargetBytes: 1 << 20, parentDirectory: root)
+        defer { try? fifo.close() }
+        try fifo.append(Self.payload(1_000, seed: 4))
+        let chunk = fifo.storageDirectory.appendingPathComponent("0.packets")
+        let handle = try FileHandle(forWritingTo: chunk)
+        try handle.truncate(atOffset: 500)
+        try handle.close()
+
+        #expect(throws: SoftwarePacketDiskFIFO.Failure.corruptRecord) { try fifo.pop() }
+        #expect(fifo.snapshot.hasFailure)
+        #expect(throws: (any Error).self) { try fifo.append(Data([1])) }
+    }
+
+    @Test("a decoded payload is the record's own memory, not a second copy of it")
+    func decodeDoesNotCopyThePayload() throws {
+        let packet = SoftwareStoredPacket(
+            pts: 1, dts: 1, duration: 1, position: 0, streamIndex: 0, flags: 0,
+            timeBaseNumerator: 1, timeBaseDenominator: 90_000,
+            bytes: Self.payload(4_096, seed: 2),
+            sideData: [.init(type: 7, bytes: Self.payload(40, seed: 3))])
+        let record = try packet.encoded()
+        let decoded = try SoftwareStoredPacket.decode(record)
+        #expect(decoded == packet)
+
+        let recordBase = record.withUnsafeBytes { $0.baseAddress }
+        let payloadBase = decoded.bytes.withUnsafeBytes { $0.baseAddress }
+        #expect(recordBase != nil && payloadBase == recordBase.map { $0 + SoftwareStoredPacket.headerBytes })
+    }
+
+    /// Reported, not asserted: a timing floor would be a CI coin toss. One packet at a time, so the
+    /// spool never holds more than a chunk and the run leaves nothing behind.
+    @Test("spool round trip throughput, reported")
+    func throughputReport() throws {
+        let root = try Self.makeRoot()
+        defer { try? FileManager.default.removeItem(at: root) }
+        let fifo = try SoftwarePacketDiskFIFO(chunkTargetBytes: 4 << 20, parentDirectory: root)
+        defer { try? fifo.close() }
+        let rounds = 1_500
+        let size = 208_000
+        let source = Self.payload(size, seed: 5)
+        let packet = SoftwareStoredPacket(
+            pts: 0, dts: 0, duration: 1_001, position: 0, streamIndex: 0, flags: 1,
+            timeBaseNumerator: 1, timeBaseDenominator: 90_000, bytes: source, sideData: [])
+        let record = try packet.encoded()
+
+        var checksum = 0
+        let start = DispatchTime.now()
+        for _ in 0..<rounds {
+            try fifo.append(record)
+            let back = try #require(try fifo.pop())
+            let decoded = try SoftwareStoredPacket.decode(back)
+            checksum &+= decoded.bytes.count
+            av_packet_free_safe(try decoded.makeAVPacket())
+        }
+        let seconds = Double(DispatchTime.now().uptimeNanoseconds - start.uptimeNanoseconds) / 1e9
+        print(String(format: "[PERF109] %d packets of %d bytes: %.0f us/pkt (append + pop + decode + AVPacket)",
+                     rounds, size, seconds / Double(rounds) * 1e6))
+        #expect(checksum == rounds * size)
+    }
+}

From 996cd31598df2847a51f511b8875c8d53d62dd4c Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 10:41:16 +0200
Subject: [PATCH 222/359] fix(dv): the RPU walk arms an input byte budget like
 the HDR10+ and Atmos probes (audit BIT-103)

Matroska resyncs byte by byte through data no element starts in, inside one av_read_frame, so a video
stream followed by junk made the RPU walk read the whole source before it counted a single packet. The
walk now arms Demuxer.beginInputByteBudget (64 MiB, the walk's own byte ceiling) and disarms it on exit.
The walk body is split out as rpuProfile(walking:) so a test can hand it a counting reader.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../Video/DolbyVisionRecordAudit.swift        | 12 +++
 ...lbyVisionRecordAuditInputBudgetTests.swift | 84 +++++++++++++++++++
 .../HDR10PlusScanInputBudgetTests.swift       |  9 +-
 3 files changed, 102 insertions(+), 3 deletions(-)
 create mode 100644 Tests/AetherEngineTests/DolbyVisionRecordAuditInputBudgetTests.swift

diff --git a/Sources/AetherEngine/Video/DolbyVisionRecordAudit.swift b/Sources/AetherEngine/Video/DolbyVisionRecordAudit.swift
index a64e1b0de..bbfbabc50 100644
--- a/Sources/AetherEngine/Video/DolbyVisionRecordAudit.swift
+++ b/Sources/AetherEngine/Video/DolbyVisionRecordAudit.swift
@@ -191,7 +191,14 @@ public enum DolbyVisionRecordAudit {
         } catch {
             return nil
         }
+        return rpuProfile(walking: demuxer, packetBudget: packetBudget)
+    }
 
+    /// The walk over an opened demuxer, split out so a test can hand it a counting reader.
+    static func rpuProfile(
+        walking demuxer: Demuxer, packetBudget: Int = auditPacketBudget,
+        byteBudget: Int64 = Int64(walkByteBudget)
+    ) -> Int? {
         let videoIdx = demuxer.videoStreamIndex
         guard videoIdx >= 0, let stream = demuxer.stream(at: videoIdx) else { return nil }
         let codecpar = stream.pointee.codecpar
@@ -199,6 +206,11 @@ public enum DolbyVisionRecordAudit {
             codec: .hevc, extradata: codecpar?.pointee.extradata,
             size: Int(codecpar?.pointee.extradata_size ?? 0))
 
+        // Audit BIT-103: Matroska resyncs byte by byte through junk inside one av_read_frame, where
+        // neither the packet fuse nor the packet byte count below can see the bytes go by.
+        demuxer.beginInputByteBudget(byteBudget)
+        defer { demuxer.endInputByteBudget() }
+
         var walked = 0
         var packetsRead = 0
         var bytesRead = 0
diff --git a/Tests/AetherEngineTests/DolbyVisionRecordAuditInputBudgetTests.swift b/Tests/AetherEngineTests/DolbyVisionRecordAuditInputBudgetTests.swift
new file mode 100644
index 000000000..cc73d3c97
--- /dev/null
+++ b/Tests/AetherEngineTests/DolbyVisionRecordAuditInputBudgetTests.swift
@@ -0,0 +1,84 @@
+import Foundation
+import Testing
+@testable import AetherEngine
+
+/// Audit BIT-103: the RPU walk bounded packets and the bytes of the packets it was handed, but not the
+/// bytes libavformat consumes inside one `av_read_frame`. Matroska resyncs byte by byte through data no
+/// element starts in, so a video stream followed by junk read the whole source before the walk got to
+/// count anything. The fixture is that shape: two HEVC frames, then zeros.
+@Suite("DV record audit: the RPU walk holds an input byte budget below the demuxer")
+struct DolbyVisionRecordAuditInputBudgetTests {
+
+    private static let junkBytes = 24 * 1024 * 1024
+    private static let budget: Int64 = 1 << 20
+
+    private final class CountingReader: IOReader, @unchecked Sendable {
+        private let base: FileIOReader
+        private let lock = NSLock()
+        private var total: Int64 = 0
+
+        init(_ base: FileIOReader) { self.base = base }
+
+        var bytesRead: Int64 { lock.lock(); defer { lock.unlock() }; return total }
+
+        func read(_ buffer: UnsafeMutablePointer<UInt8>?, size: Int32) -> Int32 {
+            let n = base.read(buffer, size: size)
+            if n > 0 { lock.lock(); total += Int64(n); lock.unlock() }
+            return n
+        }
+        func seek(offset: Int64, whence: Int32) -> Int64 { base.seek(offset: offset, whence: whence) }
+        func close() { base.close() }
+        var discImageProbeEnabled: Bool { false }
+    }
+
+    private func open(_ demuxer: Demuxer, _ url: URL, reader: CountingReader?) throws {
+        let profile = DemuxerOpenProfile.dolbyVisionRecordAuditDemuxer(callerProbesize: nil, callerMaxAnalyzeDuration: nil)
+        if let reader {
+            try demuxer.open(reader: reader, profile: profile)
+        } else {
+            try demuxer.open(url: url, profile: profile)
+        }
+    }
+
+    @Test("a junk tail stops the walk at its byte budget on a custom reader")
+    func junkTailStopsOnTheBudgetOnACustomReader() throws {
+        let data = try TailHeavyMatroska.make(foreignBytes: Self.junkBytes, junkTail: true)
+        try ProbeTestFixtures.withFile(data) { url in
+            let reader = CountingReader(try #require(FileIOReader(url: url)))
+            let demuxer = Demuxer()
+            defer { demuxer.close() }
+            try open(demuxer, url, reader: reader)
+            let atOpen = reader.bytesRead
+            #expect(DolbyVisionRecordAudit.rpuProfile(walking: demuxer, byteBudget: Self.budget) == nil)
+            #expect(demuxer.inputByteBudgetExhausted)
+            #expect(reader.bytesRead - atOpen <= Self.budget)
+        }
+    }
+
+    @Test("a junk tail stops the walk at its byte budget on a local file")
+    func junkTailStopsOnTheBudgetOnALocalFile() throws {
+        let data = try TailHeavyMatroska.make(foreignBytes: Self.junkBytes, junkTail: true)
+        try ProbeTestFixtures.withFile(data) { url in
+            let demuxer = Demuxer()
+            defer { demuxer.close() }
+            try open(demuxer, url, reader: nil)
+            #expect(DolbyVisionRecordAudit.rpuProfile(walking: demuxer, byteBudget: Self.budget) == nil)
+            #expect(demuxer.inputByteBudgetExhausted)
+        }
+    }
+
+    @Test("a budget that covers the file reaches its end, so the cap is the budget and not the fixture")
+    func coveringBudgetReadsToTheEnd() throws {
+        let data = try TailHeavyMatroska.make(foreignBytes: Self.junkBytes, junkTail: true)
+        try ProbeTestFixtures.withFile(data) { url in
+            let reader = CountingReader(try #require(FileIOReader(url: url)))
+            let demuxer = Demuxer()
+            defer { demuxer.close() }
+            try open(demuxer, url, reader: reader)
+            let atOpen = reader.bytesRead
+            #expect(DolbyVisionRecordAudit.rpuProfile(walking: demuxer, byteBudget: Int64(data.count) * 2) == nil)
+            #expect(!demuxer.inputByteBudgetExhausted)
+            #expect(reader.bytesRead - atOpen > Self.budget)
+        }
+    }
+}
diff --git a/Tests/AetherEngineTests/HDR10PlusScanInputBudgetTests.swift b/Tests/AetherEngineTests/HDR10PlusScanInputBudgetTests.swift
index a94c9f043..903e7e2d2 100644
--- a/Tests/AetherEngineTests/HDR10PlusScanInputBudgetTests.swift
+++ b/Tests/AetherEngineTests/HDR10PlusScanInputBudgetTests.swift
@@ -52,9 +52,11 @@ struct HDR10PlusScanInputBudgetTests {
 }
 
 /// Matroska with the plain HDR10 fixture's two HEVC frames at the head and a long PCM tail after them.
-private enum TailHeavyMatroska {
+/// `junkTail` swaps the PCM clusters for zeros that no EBML element starts in, which libavformat
+/// resyncs through byte by byte inside a single `av_read_frame`.
+enum TailHeavyMatroska {
 
-    static func make(foreignBytes: Int) throws -> Data {
+    static func make(foreignBytes: Int, junkTail: Bool = false) throws -> Data {
         let mp4 = try ProbeTestFixtures.decode(HDR10PlusProbeIntegrationTests.hdr10Base64)
         let (hvcC, frames) = try hevcTrack(mp4)
 
@@ -89,7 +91,8 @@ private enum TailHeavyMatroska {
                             simpleBlock(track: 1, relative: 0, payload: frames[0]) +
                             simpleBlock(track: 1, relative: 40, payload: frames[1]))
         let silence = [UInt8](repeating: 0, count: blockBytes)
-        for i in 0..<max(1, foreignBytes / blockBytes) {
+        if junkTail { clusters += [UInt8](repeating: 0, count: foreignBytes) }
+        for i in 0..<(junkTail ? 0 : max(1, foreignBytes / blockBytes)) {
             clusters += element([0x1F, 0x43, 0xB6, 0x75],
                                 element([0xE7], uint(100 + i * 170)) +
                                 simpleBlock(track: 2, relative: 0, payload: silence))

From 673044f484345144aeb09d6987ef77850055905b Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 10:43:18 +0200
Subject: [PATCH 223/359] test(demuxer): write the hostile sidecar fixture to
 the temporary directory, not the checkout (audit OPS-109)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 Tests/AetherEngineTests/DemuxedTimestampBoundsTests.swift | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Tests/AetherEngineTests/DemuxedTimestampBoundsTests.swift b/Tests/AetherEngineTests/DemuxedTimestampBoundsTests.swift
index 887b9d05c..45dfac6ff 100644
--- a/Tests/AetherEngineTests/DemuxedTimestampBoundsTests.swift
+++ b/Tests/AetherEngineTests/DemuxedTimestampBoundsTests.swift
@@ -137,8 +137,8 @@ struct DemuxedTimestampBoundsTests {
             .init(cluster: 2000, duration: UInt64.max),
             .init(cluster: 5_000_000_000_000, duration: 500),
         ])
-        let url = URL(fileURLWithPath: FileManager.default.currentDirectoryPath, isDirectory: true)
-            .appendingPathComponent(".hostile-timestamps-\(UUID().uuidString).mkv")
+        let url = FileManager.default.temporaryDirectory
+            .appendingPathComponent("hostile-timestamps-\(UUID().uuidString).mkv")
         defer { try? FileManager.default.removeItem(at: url) }
         try data.write(to: url)
         let cues = try await SubtitleDecoder.decodeFile(url: url).cues

From 19ee344e5ca5bfb8c4052ae404087677c4a7db92 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 10:44:26 +0200
Subject: [PATCH 224/359] fix(demuxer): a forward-only source keeps the packets
 its start-up probes look at (audit HLS-103)

70dc485d stopped step 6 from rewinding a pb that cannot rewind, but the NAL framing
probe (Annex-B extradata, every H.264/HEVC MPEG-TS) and the in-band hvcC scan still
seeked to 0 and consumed packets. libavformat flushes its packet queue before it even
tries a seek, so on a forward-only source the opening GOP never reached the producer
(a 4 frame loss on the 16 frame witness clip, a whole GOP on a real archive).

The demuxer gets a held-packet queue: peekPackets reads through the normal pipeline
and holds what the probe looked at, readPacket hands the held packets out first.
scanSourceHead peeks on a source that cannot rewind and keeps the seek-and-consume
walk on one that can, so seekable sources behave exactly as before. seek(to:),
seek(to:streamIndex:), seekBounded and byteSeek now refuse a forward-only source
before touching libavformat (a live AVIOReader reports itself seekable by design and
keeps its own rules), which also ends the AE#366 prime hunt's linear read there.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 Sources/AetherEngine/Demuxer/Demuxer.swift    |  59 +++++
 .../HLSVideoEngine+SegmentPlanning.swift      |  89 ++++---
 .../ForwardOnlyHeadIsKeptTests.swift          | 245 ++++++++++++++++++
 3 files changed, 354 insertions(+), 39 deletions(-)
 create mode 100644 Tests/AetherEngineTests/ForwardOnlyHeadIsKeptTests.swift

diff --git a/Sources/AetherEngine/Demuxer/Demuxer.swift b/Sources/AetherEngine/Demuxer/Demuxer.swift
index 8178a19cc..7358cde47 100644
--- a/Sources/AetherEngine/Demuxer/Demuxer.swift
+++ b/Sources/AetherEngine/Demuxer/Demuxer.swift
@@ -326,6 +326,12 @@ public final class Demuxer: @unchecked Sendable {
     private var compositionRepair: (any H264TimestampRepairSession)?
     private var compositionRepairEvaluated = false
 
+    /// Audit HLS-103: packets `peekPackets` read ahead of the cursor on a source that cannot rewind.
+    /// They are already through everything `readPacket` does to a packet (the #409 repair, the
+    /// timestamp bound), so `readPacket` hands them out first and as they are. Freed by a
+    /// reposition and by `close()`. Guarded by `accessLock`.
+    private var peekedPackets: [UnsafeMutablePointer<AVPacket>] = []
+
     /// #407: video streams whose PTS `+genpts` invented out of decode order, because the container
     /// carries none of its own. Cleared on the way out of `readPacketLocked` so the decoder's reorder
     /// owns the presentation axis. Decided once at open, see `armGeneratedPTSSuppression`.
@@ -1751,6 +1757,44 @@ public final class Demuxer: @unchecked Sendable {
     func readPacket(isCurrent: @Sendable () -> Bool = { true }) throws -> UnsafeMutablePointer<AVPacket>? {
         accessLock.lock()
         defer { accessLock.unlock() }
+        if !peekedPackets.isEmpty {
+            guard isCurrent() else { throw CancellationError() }
+            return peekedPackets.removeFirst()
+        }
+        return try readPipelinePacketLocked(isCurrent: isCurrent)
+    }
+
+    /// Shows the packets at the read position to `inspect`, in order, WITHOUT consuming them: what it
+    /// looked at is held and the next `readPacket()` calls return it first (audit HLS-103). For a source
+    /// that cannot rewind, where a probe that reads packets and seeks back has nothing to seek back
+    /// with. `inspect` returns true once it has seen enough. Stops at `maxPackets` held, at the end of
+    /// the source, or on a read error, which is thrown with the packets read so far still held.
+    func peekPackets(maxPackets: Int,
+                     _ inspect: (UnsafeMutablePointer<AVPacket>) -> Bool) throws {
+        accessLock.lock()
+        defer { accessLock.unlock() }
+        var index = 0
+        while index < maxPackets {
+            if index == peekedPackets.count {
+                guard let packet = try readPipelinePacketLocked() else { return }
+                peekedPackets.append(packet)
+            }
+            if inspect(peekedPackets[index]) { return }
+            index += 1
+        }
+    }
+
+    /// Caller holds `accessLock`.
+    private func dropPeekedPacketsLocked() {
+        for held in peekedPackets {
+            var packet: UnsafeMutablePointer<AVPacket>? = held
+            trackedPacketFree(&packet)
+        }
+        peekedPackets.removeAll()
+    }
+
+    /// One packet through the demuxer's own pipeline, bypassing the peek queue. Caller holds `accessLock`.
+    private func readPipelinePacketLocked(isCurrent: @Sendable () -> Bool = { true }) throws -> UnsafeMutablePointer<AVPacket>? {
         while true {
             // A read-ahead decision made before a seek cannot start a NEW-position read after
             // the seek releases this lock, then throw that first new packet away as stale.
@@ -2038,10 +2082,16 @@ public final class Demuxer: @unchecked Sendable {
         // re-anchors on the next keyframe (a seek always lands on one).
         compositionRepair?.noteSeek()
         if let reader = timeSeekableReader {
+            dropPeekedPacketsLocked()
             guard repositionTimeSeekable(reader, toSourceSeconds: seconds, streamIndex: -1) else { return false }
             resetAfterTimeSeek(ctx)
             return true
         }
+        // Audit HLS-103: libavformat flushes its packet queue before it even tries a seek, so on a
+        // source that cannot rewind a refused seek is pure loss. A live AVIOReader reports itself
+        // seekable by design, so live callers keep their own rules.
+        guard isSourceSeekable else { return false }
+        dropPeekedPacketsLocked()
         let ret = avformat_seek_file(ctx, -1, Int64.min, timestamp, Int64.max, 0)
         if ret < 0 {
             #if DEBUG
@@ -2071,12 +2121,15 @@ public final class Demuxer: @unchecked Sendable {
             guard timeBase.num > 0, timeBase.den > 0 else { return false }
             let seconds = Double(timestamp) * Double(timeBase.num)
                 / Double(timeBase.den)
+            dropPeekedPacketsLocked()
             guard repositionTimeSeekable(reader, toSourceSeconds: seconds, streamIndex: streamIndex) else {
                 return false
             }
             resetAfterTimeSeek(ctx)
             return true
         }
+        guard isSourceSeekable else { return false }  // audit HLS-103, see `seek(to:)`
+        dropPeekedPacketsLocked()
         let ret = avformat_seek_file(
             ctx,
             streamIndex,
@@ -2207,12 +2260,15 @@ public final class Demuxer: @unchecked Sendable {
         // over HTTP would additionally be a request storm. No read deadline is armed: the reader's
         // reposition is a bookkeeping operation, the refetch happens behind the FIFO.
         if let reader = timeSeekableReader {
+            dropPeekedPacketsLocked()
             guard repositionTimeSeekable(reader, toSourceSeconds: seconds, streamIndex: anchorStreamIndex) else {
                 return false
             }
             resetAfterTimeSeek(ctx)
             return true
         }
+        guard isSourceSeekable else { return false }  // audit HLS-103, see `seek(to:)`
+        dropPeekedPacketsLocked()
         // #112 round 9: the deadline lives on the provider protocol. Casting to AVIOReader here left a
         // disc-adapter source (CustomIOReaderBridge over HTTPDiscIOReader) unbounded: one positioning
         // seek on a remote ISO sat wedged ~230 s and every later re-arm queued behind it.
@@ -2415,6 +2471,8 @@ public final class Demuxer: @unchecked Sendable {
         defer { accessLock.unlock() }
         guard let ctx = formatContext else { return false }
         compositionRepair?.noteSeek()  // #409: re-anchor on the next keyframe
+        guard isSourceSeekable else { return false }  // audit HLS-103, see `seek(to:)`
+        dropPeekedPacketsLocked()
         let ret = avformat_seek_file(ctx, -1, Int64.min, byteTarget, Int64.max, AVSEEK_FLAG_BYTE)
         avformat_flush(ctx)
         resetSubpictureAssembly()  // #651: libavformat just dropped the parsers this stands in for
@@ -2551,6 +2609,7 @@ public final class Demuxer: @unchecked Sendable {
         trackSnapshot = TrackSnapshot()
         while streamUsers > 0 { streamTableLock.wait() }
         streamTableLock.unlock()
+        dropPeekedPacketsLocked()
         if formatContext != nil {
             avformat_close_input(&formatContext)
         }
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine+SegmentPlanning.swift b/Sources/AetherEngine/Video/HLSVideoEngine+SegmentPlanning.swift
index 315142afd..54883b154 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine+SegmentPlanning.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine+SegmentPlanning.swift
@@ -442,7 +442,7 @@ extension HLSVideoEngine {
         return out
     }
 
-    /// Scan packets for in-band VPS/SPS/PPS when hvcC `numOfArrays=0` (DV P5 MP4 encoders, e.g. Wandering Earth 2 WEB-DL, issue #19). AVPlayer symptom: `item.tracks count=2`, `fourCC=<no fdesc>`, `CoreMediaErrorDomain -4`. Caller must seek back after this consumes packets.
+    /// Scan packets for in-band VPS/SPS/PPS when hvcC `numOfArrays=0` (DV P5 MP4 encoders, e.g. Wandering Earth 2 WEB-DL, issue #19). AVPlayer symptom: `item.tracks count=2`, `fourCC=<no fdesc>`, `CoreMediaErrorDomain -4`. On a source that can rewind the scan consumes packets and the caller must seek back; on a forward-only one it only peeks (`scanSourceHead`).
     ///
     /// `rewindBeforeScan` rewinds to the head first, because in-band parameter sets are guaranteed at
     /// the first IRAP but only recur every GOP after it. Without the rewind the scan inherited whatever
@@ -479,8 +479,6 @@ extension HLSVideoEngine {
         guard Self.configRecordNeedsInBandRebuild(extradata, size: extradataSize) else { return nil }
         let naluLengthSize = 4   // the predicate above already required it
 
-        if rewindBeforeScan { demuxer.seek(to: 0) }
-
         var vps: [UInt8]?
         var sps: [UInt8]?
         var pps: [UInt8]?
@@ -490,25 +488,11 @@ extension HLSVideoEngine {
         var packetsScanned = 0
         // Second cap so a stream that never yields a video packet cannot walk the whole source.
         let readBudget = 512
-        var packetsRead = 0
 
-        while packetsScanned < packetBudget && packetsRead < readBudget {
-            let readResult: UnsafeMutablePointer<AVPacket>?
-            do {
-                readResult = try demuxer.readPacket()
-            } catch {
-                break
-            }
-            guard let pkt = readResult else { break }
-            defer {
-                // trackedPacketFree not raw av_packet_free: readPacket allocs via trackedPacketAlloc; raw free leaves PacketBalanceTracker.pktAlive permanently high.
-                var maybePkt: UnsafeMutablePointer<AVPacket>? = pkt
-                trackedPacketFree(&maybePkt)
-            }
-            packetsRead += 1
-            if pkt.pointee.stream_index != videoStreamIndex { continue }
+        scanSourceHead(demuxer: demuxer, rewind: rewindBeforeScan, readBudget: readBudget) { pkt in
+            if pkt.pointee.stream_index != videoStreamIndex { return false }
             packetsScanned += 1
-            guard let pktData = pkt.pointee.data else { continue }
+            guard let pktData = pkt.pointee.data else { return packetsScanned >= packetBudget }
             let pktSize = Int(pkt.pointee.size)
 
             var offset = 0
@@ -530,7 +514,7 @@ extension HLSVideoEngine {
                 offset += nalLen
             }
 
-            if vps != nil && sps != nil && pps != nil { break }
+            return (vps != nil && sps != nil && pps != nil) || packetsScanned >= packetBudget
         }
 
         guard let vps, let sps, let pps else {
@@ -560,6 +544,44 @@ extension HLSVideoEngine {
         return hvcC
     }
 
+    /// Shows the packets at the head of the source to `inspect`, which returns true once it has seen
+    /// enough, looking at no more than `readBudget` of them.
+    ///
+    /// A source that can rewind is rewound (when `rewind`) and the packets are CONSUMED, which is
+    /// what these scans always did: `start()` seeks back to 0 afterwards. A source that cannot rewind
+    /// has nothing to seek back with, so whatever the scan consumed is gone from the archive
+    /// (audit HLS-103: a sequential origin lost its opening GOP to the framing probe). Those are
+    /// PEEKED instead: the packets the scan looked at stay queued for the producer.
+    func scanSourceHead(
+        demuxer: Demuxer,
+        rewind: Bool,
+        readBudget: Int,
+        _ inspect: (UnsafeMutablePointer<AVPacket>) -> Bool
+    ) {
+        guard demuxer.isSourceSeekable else {
+            try? demuxer.peekPackets(maxPackets: readBudget, inspect)
+            return
+        }
+        if rewind { demuxer.seek(to: 0) }
+        var packetsRead = 0
+        while packetsRead < readBudget {
+            let readResult: UnsafeMutablePointer<AVPacket>?
+            do {
+                readResult = try demuxer.readPacket()
+            } catch {
+                break
+            }
+            guard let pkt = readResult else { break }
+            defer {
+                // trackedPacketFree not raw av_packet_free: readPacket allocs via trackedPacketAlloc; raw free leaves PacketBalanceTracker.pktAlive permanently high.
+                var maybePkt: UnsafeMutablePointer<AVPacket>? = pkt
+                trackedPacketFree(&maybePkt)
+            }
+            packetsRead += 1
+            if inspect(pkt) { break }
+        }
+    }
+
     /// What the muxer should ship for a source whose config record is Annex B (#365), and the
     /// framing every NAL walker in the session should use.
     struct VideoFramingNormalization {
@@ -580,8 +602,10 @@ extension HLSVideoEngine {
     /// length happens to read as `00 00 01` and drops everything else. Measured 1080p: a 2,158,448 B
     /// segment came out at 61,912 B, AVPlayer reached `readyToPlay` and never produced a frame.
     ///
-    /// Consumes packets and leaves the demuxer cursor where it stopped; `start()` seeks back to 0
-    /// afterwards, same contract as the in-band scan and the cue prewarm.
+    /// On a source that can rewind it consumes packets and leaves the demuxer cursor where it
+    /// stopped; `start()` seeks back to 0 afterwards, same contract as the in-band scan and the cue
+    /// prewarm. A forward-only source is peeked instead (`scanSourceHead`), so the producer still
+    /// receives the packets the probe looked at.
     func normalizeVideoFraming(
         demuxer: Demuxer,
         videoStreamIndex: Int32,
@@ -659,27 +683,13 @@ extension HLSVideoEngine {
         packetBudget: Int = 4,
         readBudget: Int = 512
     ) -> VideoNALFraming? {
-        demuxer.seek(to: 0)
         var lengthPrefixed = 0
         var annexB = 0
         var inspected = 0
-        var packetsRead = 0
 
-        while inspected < packetBudget && packetsRead < readBudget {
-            let readResult: UnsafeMutablePointer<AVPacket>?
-            do {
-                readResult = try demuxer.readPacket()
-            } catch {
-                break
-            }
-            guard let pkt = readResult else { break }
-            defer {
-                var maybePkt: UnsafeMutablePointer<AVPacket>? = pkt
-                trackedPacketFree(&maybePkt)
-            }
-            packetsRead += 1
+        scanSourceHead(demuxer: demuxer, rewind: true, readBudget: readBudget) { pkt in
             guard pkt.pointee.stream_index == videoStreamIndex,
-                  let data = pkt.pointee.data, pkt.pointee.size > 4 else { continue }
+                  let data = pkt.pointee.data, pkt.pointee.size > 4 else { return false }
             inspected += 1
             let size = Int(pkt.pointee.size)
             if VideoConfigRecord.walksAsLengthPrefixed(data, size: size) {
@@ -687,6 +697,7 @@ extension HLSVideoEngine {
             } else if VideoConfigRecord.startsWithStartCode(data, size: size) {
                 annexB += 1
             }
+            return inspected >= packetBudget
         }
 
         let framing: VideoNALFraming?
diff --git a/Tests/AetherEngineTests/ForwardOnlyHeadIsKeptTests.swift b/Tests/AetherEngineTests/ForwardOnlyHeadIsKeptTests.swift
new file mode 100644
index 000000000..78d896149
--- /dev/null
+++ b/Tests/AetherEngineTests/ForwardOnlyHeadIsKeptTests.swift
@@ -0,0 +1,245 @@
+import Testing
+import Foundation
+import AetherLibavcodec
+@testable import AetherEngine
+
+/// Audit HLS-103 (70dc485d was incomplete): a forward-only source cannot rewind, so whatever the
+/// start-up probes read off its head is gone from the archive. `probeVideoNALFraming` (Annex-B
+/// extradata) and the in-band hvcC rebuild both did `seek(to: 0)` and then consumed packets; FFmpeg
+/// flushes the packet queue before it even tries the seek, and 70dc485d's step-6 rewind is skipped
+/// on these sources, so the opening GOP never reached the producer.
+@Suite("A forward-only source keeps its opening packets", .serialized)
+struct ForwardOnlyHeadIsKeptTests {
+
+    /// The tiny H.264 TS as a source that cannot be repositioned: every seek is refused, which is how
+    /// the demuxer learns the source is forward-only.
+    private final class ForwardOnlyReader: IOReader, @unchecked Sendable {
+        private let bytes = TinyTransportStreamFixture.data
+        private let lock = NSLock()
+        private var position = 0
+
+        func read(_ buffer: UnsafeMutablePointer<UInt8>?, size: Int32) -> Int32 {
+            guard let buffer, size > 0 else { return -1 }
+            return lock.withLock {
+                let n = min(Int(size), bytes.count - position)
+                guard n > 0 else { return 0 }
+                bytes.withUnsafeBytes { raw in _ = memcpy(buffer, raw.baseAddress! + position, n) }
+                position += n
+                return Int32(n)
+            }
+        }
+
+        func seek(offset: Int64, whence: Int32) -> Int64 { -1 }
+        func close() {}
+        var discImageProbeEnabled: Bool { false }
+    }
+
+    struct Signature: Equatable {
+        let streamIndex: Int32
+        let pts: Int64
+        let dts: Int64
+        let size: Int32
+    }
+
+    private static func signature(_ packet: UnsafeMutablePointer<AVPacket>) -> Signature {
+        Signature(streamIndex: packet.pointee.stream_index, pts: packet.pointee.pts,
+                  dts: packet.pointee.dts, size: packet.pointee.size)
+    }
+
+    private func openForwardOnly() throws -> Demuxer {
+        let demuxer = Demuxer()
+        try demuxer.open(reader: ForwardOnlyReader(), formatHint: "mpegts")
+        return demuxer
+    }
+
+    /// The packets a plain read delivers, in order: what the producer would see with no probe at all.
+    private func firstPackets(_ count: Int) throws -> [Signature] {
+        let demuxer = try openForwardOnly()
+        defer { demuxer.close() }
+        var out: [Signature] = []
+        while out.count < count, let read = try demuxer.readPacket() {
+            out.append(Self.signature(read))
+            var packet: UnsafeMutablePointer<AVPacket>? = read
+            trackedPacketFree(&packet)
+        }
+        return out
+    }
+
+    private func readSome(_ demuxer: Demuxer, _ count: Int) throws -> [Signature] {
+        var out: [Signature] = []
+        while out.count < count, let read = try demuxer.readPacket() {
+            out.append(Self.signature(read))
+            var packet: UnsafeMutablePointer<AVPacket>? = read
+            trackedPacketFree(&packet)
+        }
+        return out
+    }
+
+    @Test("packets peeked on a forward-only source are read again, in order, from the first")
+    func peekedPacketsAreReadAgain() throws {
+        let expected = try firstPackets(12)
+
+        let demuxer = try openForwardOnly()
+        defer { demuxer.close() }
+        #expect(!demuxer.isSourceSeekable)
+        var peeked: [Signature] = []
+        try demuxer.peekPackets(maxPackets: 6) { packet in
+            peeked.append(Self.signature(packet))
+            return false
+        }
+        #expect(peeked == Array(expected.prefix(6)))
+
+        // A second look starts from the head again and extends the held run.
+        var second: [Signature] = []
+        try demuxer.peekPackets(maxPackets: 9) { packet in
+            second.append(Self.signature(packet))
+            return false
+        }
+        #expect(second == Array(expected.prefix(9)))
+
+        #expect(try readSome(demuxer, 12) == expected,
+                "a peek changed what the producer reads")
+    }
+
+    @Test("a peek that has seen enough stops and holds only what it read")
+    func peekStopsWhenSatisfied() throws {
+        let expected = try firstPackets(4)
+        let demuxer = try openForwardOnly()
+        defer { demuxer.close() }
+        var inspected = 0
+        try demuxer.peekPackets(maxPackets: 100) { _ in
+            inspected += 1
+            return inspected == 3
+        }
+        #expect(inspected == 3)
+        #expect(try readSome(demuxer, 4) == expected)
+    }
+
+    @Test("a refused seek on a forward-only source leaves its packets alone")
+    func refusedSeeksKeepTheHead() throws {
+        let expected = try firstPackets(12)
+        let demuxer = try openForwardOnly()
+        defer { demuxer.close() }
+        try demuxer.peekPackets(maxPackets: 4) { _ in false }
+
+        #expect(!demuxer.seek(to: 0), "a forward-only source was asked to rewind")
+        #expect(!demuxer.seek(to: 0, streamIndex: demuxer.videoStreamIndex))
+        #expect(!demuxer.seekBounded(to: 0, timeout: 1))
+        #expect(!demuxer.seekByteEstimate(to: 1, knownDuration: 8, timeout: 1))
+
+        #expect(try readSome(demuxer, 12) == expected, "a refused seek flushed the packets behind it")
+    }
+
+    @Test("a refused seek on a forward-only source keeps the packets the open read ahead")
+    func refusedSeekKeepsTheOpenQueue() throws {
+        let expected = try firstPackets(12)
+        let demuxer = try openForwardOnly()
+        defer { demuxer.close() }
+
+        #expect(!demuxer.seek(to: 0), "a forward-only source was asked to rewind")
+        #expect(try readSome(demuxer, 12) == expected,
+                "the refused seek flushed what find_stream_info had buffered")
+    }
+
+    @Test("a seek on a source that can rewind drops what was peeked")
+    func seekableSourcesDropThePeek() throws {
+        let demuxer = Demuxer()
+        try demuxer.open(reader: TinyTransportStreamFixture.LiveReader(), formatHint: "mpegts")
+        defer { demuxer.close() }
+        #expect(demuxer.isSourceSeekable)
+        var seen: [Signature] = []
+        try demuxer.peekPackets(maxPackets: 8) { seen.append(Self.signature($0)); return false }
+        #expect(seen.count == 8)
+
+        // Three of the held packets go out, five stay held; a rewind must not hand those five out.
+        _ = try readSome(demuxer, 3)
+        #expect(demuxer.seek(to: 0))
+        let after = try #require(try readSome(demuxer, 1).first)
+        #expect(after == seen[0], "a held packet came back after the rewind instead of the head")
+    }
+
+    @Test("the NAL framing probe leaves the packets it looked at for the producer")
+    func framingProbeDoesNotConsume() throws {
+        let expected = try firstPackets(12)
+        #expect(expected.count == 12)
+
+        let demuxer = try openForwardOnly()
+        defer { demuxer.close() }
+        #expect(!demuxer.isSourceSeekable, "the fixture reader must read as forward-only")
+        let engine = HLSVideoEngine(url: URL(fileURLWithPath: "/nonexistent/forward-only.ts"),
+                                    dvModeAvailable: false)
+        let framing = engine.probeVideoNALFraming(demuxer: demuxer, videoStreamIndex: demuxer.videoStreamIndex)
+        #expect(framing == .annexB)
+
+        #expect(try readSome(demuxer, 12) == expected,
+                "the probe consumed packets the producer will never see")
+    }
+
+    /// Video samples (track 1) across every fragment of a segment, from the `trun` sample counts.
+    private static func videoSampleCount(_ segment: Data) -> Int {
+        func u32(_ off: Int) -> UInt32 {
+            segment.withUnsafeBytes { UInt32(bigEndian: $0.loadUnaligned(fromByteOffset: off, as: UInt32.self)) }
+        }
+        func boxes(_ range: Range<Int>) -> [(String, Range<Int>)] {
+            var out: [(String, Range<Int>)] = []
+            var off = range.lowerBound
+            while off + 8 <= range.upperBound {
+                let size = Int(u32(off))
+                guard size >= 8, off + size <= range.upperBound else { break }
+                out.append((String(decoding: segment[off + 4..<off + 8], as: UTF8.self), (off + 8)..<(off + size)))
+                off += size
+            }
+            return out
+        }
+        var count = 0
+        for (type, moof) in boxes(0..<segment.count) where type == "moof" {
+            for (t2, traf) in boxes(moof) where t2 == "traf" {
+                var track: UInt32 = 0
+                var samples = 0
+                for (t3, body) in boxes(traf) {
+                    if t3 == "tfhd" { track = u32(body.lowerBound + 4) }
+                    if t3 == "trun" { samples += Int(u32(body.lowerBound + 4)) }
+                }
+                if track == 1 { count += samples }
+            }
+        }
+        return count
+    }
+
+    /// The whole path: a range-less origin serves the TS as one plain 200, the session plans on a
+    /// uniform stride, and the finished playlist has to list every frame the source carries. The
+    /// 8 s clip is well inside the reader's 1 MB back window, which is exactly the shape where the
+    /// probe's rewind appeared to work and ate the opening.
+    @Test("the finished playlist of a forward-only Annex-B TS lists every video frame",
+          .timeLimit(.minutes(2)))
+    func playlistKeepsTheOpeningFrames() async throws {
+        let body = TinyTransportStreamFixture.data
+        let origin = ScriptedOriginServer { _ in
+            .init(status: 200, declaredLength: nil, close: true, body: body)
+        }
+        let server = try #require(origin)
+        defer { server.stop() }
+        let url = URL(string: "http://127.0.0.1:\(server.port)/forward-only.ts")!
+        let engine = HLSVideoEngine(url: url, dvModeAvailable: false,
+                                    sequentialOrigin: true, declaredDurationSeconds: 8)
+        _ = try engine.start()
+        defer { engine.stop() }
+        let mediaURL = try #require(engine.mediaPlaylistURL)
+
+        var playlist = ""
+        try await waitFor {
+            playlist = (try? String(contentsOf: mediaURL, encoding: .utf8)) ?? ""
+            return playlist.contains("#EXT-X-ENDLIST")
+        }
+
+        let uris = playlist.split(whereSeparator: \.isNewline).map(String.init)
+            .filter { $0.hasSuffix(".mp4") && !$0.hasPrefix("#") }
+        #expect(!uris.isEmpty, "no segment was listed:\n\(playlist)")
+        var frames = 0
+        for uri in uris {
+            let data = try Data(contentsOf: mediaURL.deletingLastPathComponent().appendingPathComponent(uri))
+            frames += Self.videoSampleCount(data)
+        }
+        #expect(frames == 16, "the listed segments carry \(frames) of 16 video frames:\n\(playlist)")
+    }
+}

From cefa020b7ed12d90a23b7d21233eb2d73d1c7207 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 10:44:37 +0200
Subject: [PATCH 225/359] test(ingest): the chunked accumulation timing bar
 takes the best of three samples

A full-suite run on a loaded machine stretched the single wall-clock sample to 12 s against a 1.5 s bar
while the test passes in 0.3 s alone. The per-byte accumulation it guards against took 5 s unloaded, so it
stays above the bar in every sample and the best of three still catches it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../AetherEngineTests/BoundedFetchTests.swift  | 18 ++++++++++++------
 1 file changed, 12 insertions(+), 6 deletions(-)

diff --git a/Tests/AetherEngineTests/BoundedFetchTests.swift b/Tests/AetherEngineTests/BoundedFetchTests.swift
index b2cc3d781..c110e7723 100644
--- a/Tests/AetherEngineTests/BoundedFetchTests.swift
+++ b/Tests/AetherEngineTests/BoundedFetchTests.swift
@@ -120,12 +120,18 @@ struct BoundedFetchTests {
         defer { origin.stop() }
         let session = makeSession()
         defer { session.invalidateAndCancel() }
-        let started = ContinuousClock.now
-        let (data, _) = try await BoundedPlaylistFetch.data(for: request(origin), session: session, limit: 64 * 1024 * 1024)
-        let elapsed = ContinuousClock.now - started
-        #expect(data.count == size)
-        // The per-byte accumulation this replaced took 5 s for this body in a debug build.
-        #expect(elapsed < .seconds(1.5), "took \(elapsed)")
+        // The per-byte accumulation this replaced took 5 s for this body in a debug build. Best of three,
+        // because a suite run on a loaded machine stretches one wall-clock sample (12 s seen) while the
+        // per-byte cost would stay above the bar in every sample.
+        var best = Duration.seconds(3600)
+        for _ in 0..<3 {
+            let started = ContinuousClock.now
+            let (data, _) = try await BoundedPlaylistFetch.data(for: request(origin), session: session, limit: 64 * 1024 * 1024)
+            best = min(best, ContinuousClock.now - started)
+            #expect(data.count == size)
+            if best < .seconds(1.5) { break }
+        }
+        #expect(best < .seconds(1.5), "took \(best)")
     }
 
     @Test("a segment may weigh 20 MB/s of its own duration between 32 MiB and 256 MiB")

From 4276d4a92aff1c78ac46d0bee9e500d2c57adbd7 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 10:53:52 +0200
Subject: [PATCH 226/359] chore: drop a build log that slipped into the SUB-101
 commit

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .build-warm.log | 1 -
 1 file changed, 1 deletion(-)
 delete mode 100644 .build-warm.log

diff --git a/.build-warm.log b/.build-warm.log
deleted file mode 100644
index 49d5cfc14..000000000
--- a/.build-warm.log
+++ /dev/null
@@ -1 +0,0 @@
-EXIT=0

From b57252e86f6323b1df6393635e196c94e231c05e Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 10:56:10 +0200
Subject: [PATCH 227/359] test(live): bound the ring index footprint by its
 flat minimum, not a fixed 5 MiB (audit PERF-101)

The index footprint is array capacity. It measured 4.2 MB for 100k entries run alone and
failed the 5 MiB bound once in a full parallel run, so the test was flaky without the ring
having regressed. The bound is now six times the flat minimum (14.4 MB), still far under the
55 MB the file-per-packet index cost.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../PacketRingBufferChunkSpoolTests.swift                | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/Tests/AetherEngineTests/PacketRingBufferChunkSpoolTests.swift b/Tests/AetherEngineTests/PacketRingBufferChunkSpoolTests.swift
index 8c6dc0a02..912eec7c4 100644
--- a/Tests/AetherEngineTests/PacketRingBufferChunkSpoolTests.swift
+++ b/Tests/AetherEngineTests/PacketRingBufferChunkSpoolTests.swift
@@ -81,8 +81,13 @@ struct PacketRingBufferChunkSpoolTests {
             try ring.append(pts: Double(i) * 0.0125, isKeyframe: i % 100 == 0, isVideo: i % 2 == 0, bytes: payload)
         }
         #expect(ring.seqBounds.end == count)
-        // The file-per-packet ring kept 554-586 B per entry (a URL each): 55 MB for these 100k.
-        #expect(ring.indexFootprintBytes < 5 << 20)
+        // The file-per-packet ring kept 554-586 B per entry (a URL each): 55 MB for these 100k. The
+        // footprint is array CAPACITY, which moves with growth and allocator rounding (4.2 MB measured
+        // alone, over 5 MB once in a full parallel run), so the bound is a multiple of the flat minimum
+        // that still sits far under the defect.
+        let flatMinimum = count * MemoryLayout<PacketRingBuffer.Entry>.stride
+        #expect(ring.indexFootprintBytes < flatMinimum * 6,
+                "footprint \(ring.indexFootprintBytes) against a flat minimum of \(flatMinimum)")
     }
 
     // MARK: - Byte budget

From c1613c39f51bb49cf8eebd23395ccfbaffdeabda Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 11:01:12 +0200
Subject: [PATCH 228/359] test(live): LiveDvrRetentionTests close their segment
 caches (audit PERF-101 hygiene)

Two tests store 200 segments of 1 to 1.5 MB into a SegmentCache and dropped it. The cache's deinit only
releases its live marker, so every run left about 323 MB in aether-segments under the temp directory
(seven such directories, 2 GB, were found after a few agents' full runs). Both tests now close the cache.
With a private TMPDIR the whole suite (swift-testing and XCTest) now leaves nothing behind.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 Tests/AetherEngineTests/LiveDvrRetentionTests.swift | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/Tests/AetherEngineTests/LiveDvrRetentionTests.swift b/Tests/AetherEngineTests/LiveDvrRetentionTests.swift
index 9e1f5f38e..ebde459c0 100644
--- a/Tests/AetherEngineTests/LiveDvrRetentionTests.swift
+++ b/Tests/AetherEngineTests/LiveDvrRetentionTests.swift
@@ -30,6 +30,7 @@ final class LiveDvrRetentionTests: XCTestCase {
         let segmentBytes = 1_500_000                    // ~2 s at 6 Mbps, the fastZap live shape
         let budget = 512 << 20                          // 512 MiB: far more than this run needs
         let cache = SegmentCache(forwardWindow: 10, retentionBudgetBytes: budget)
+        defer { cache.close() }   // a cache that is only dropped leaves its ~300 MB of segments in the temp dir
         let payload = Data(repeating: 0xAB, count: segmentBytes)
         let total = 200
 
@@ -53,6 +54,7 @@ final class LiveDvrRetentionTests: XCTestCase {
         let segmentBytes = 1_000_000
         let budget = 30 * segmentBytes                  // room for ~30 segments outside the window
         let cache = SegmentCache(forwardWindow: 10, retentionBudgetBytes: budget)
+        defer { cache.close() }   // a cache that is only dropped leaves its ~300 MB of segments in the temp dir
         let payload = Data(repeating: 0xAB, count: segmentBytes)
         let total = 200
 

From 506157b2267bc6a69113bc179495877062838265 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 11:10:08 +0200
Subject: [PATCH 229/359] fix(demuxer): a refused or slow cold open no longer
 hides an origin that ignores Range (audit DMX-101 residual)

The range verdict was armed for the cold connection only. When that
connection was answered with a 429/503 or took longer than the 15 s open
wait, the size probe took a range-ignoring 200's Content-Length for a size
and the post-probe connection accepted the 200, so playback ended at the
first 32 MB refill as before.

The post-probe connection is now armed too. A range-ignoring 200 is hung up
on at the head, confirmed once with `bytes=1-1`, and then plays forward-only
exactly as the cold open does; a 206 keeps the seekable path and retries the
ranged connection. The flag is cleared after the open either way, so a later
refill is never read as a verdict. `fileSize` is now reset under `winCond`
when the forward-only fallback starts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 Sources/AetherEngine/Demuxer/AVIOReader.swift | 48 +++++++++-
 .../RangeIgnoringOriginTests.swift            | 90 ++++++++++++++++---
 docs/api.md                                   |  2 +-
 3 files changed, 125 insertions(+), 15 deletions(-)

diff --git a/Sources/AetherEngine/Demuxer/AVIOReader.swift b/Sources/AetherEngine/Demuxer/AVIOReader.swift
index 2e55567f0..42583513f 100644
--- a/Sources/AetherEngine/Demuxer/AVIOReader.swift
+++ b/Sources/AetherEngine/Demuxer/AVIOReader.swift
@@ -1312,8 +1312,31 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
                         _ = streamDataReady.wait(timeout: .now() + .seconds(15))
                         try failIfStreamingRefused(fallbackStatus: pumpRefusal)
                     } else {
+                        // Audit DMX-101: a cold open that was refused or slow never judged the
+                        // origin's range support, and the probe above takes a 200's Content-Length
+                        // for a size. This connection is then the first to see the origin's answer,
+                        // so it gets the same head classification and confirmation.
+                        winCond.lock()
+                        rangeVerdictPending = true
+                        winCond.unlock()
                         startPersistentConnection(at: 0)
-                        if !awaitFirstPersistentData() {
+                        let gotData = awaitFirstPersistentData()
+                        if let caught = takeRangeVerdictAfterProbe() {
+                            caught.abandoned?.cancelTransfer()
+                            caught.abandoned?.releaseOriginTicket()
+                            try probeControl?.check()
+                            let confirmation = confirmRangeIsIgnored(contentLength: caught.contentLength)
+                            try probeControl?.check()
+                            if confirmation == .ignored {
+                                openForwardOnlyBecauseRangeIsIgnored(contentLength: caught.contentLength)
+                                try failIfStreamingRefused(fallbackStatus: 0)
+                            } else {
+                                startPersistentConnection(at: 0)
+                                if !awaitFirstPersistentData() {
+                                    EngineLog.emit("[AVIOReader] Persistent open (post-probe): no data within 15s, proceeding to read-loop reconnect", category: .demux)
+                                }
+                            }
+                        } else if !gotData {
                             EngineLog.emit("[AVIOReader] Persistent open (post-probe): no data within 15s, proceeding to read-loop reconnect", category: .demux)
                         }
                     }
@@ -1492,6 +1515,27 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
         return (false, transfer, status, ignoredLength)
     }
 
+    /// Audit DMX-101: the verdict of the post-probe connection, which `resolveOptimisticOpen` does
+    /// for the cold one. The size is already resolved by the probe, so nothing here keys off it:
+    /// a caught origin gets its connection abandoned under the lock, with the window emptied, and
+    /// a connection that was not caught is left running. The flag is cleared either way, so a
+    /// refill or reconnect later in the session is never read as a verdict. Demux thread,
+    /// open-time only.
+    private func takeRangeVerdictAfterProbe() -> (contentLength: Int64, abandoned: (any PersistentTransfer)?)? {
+        winCond.lock()
+        defer { winCond.unlock() }
+        rangeVerdictPending = false
+        guard let contentLength = rangeIgnoredAtOpenLength else { return nil }
+        rangeIgnoredAtOpenLength = nil
+        connGeneration &+= 1
+        let transfer = activeTransfer
+        activeTransfer = nil
+        window.removeAll()
+        connEnded = true
+        winCond.broadcast()
+        return (contentLength, transfer)
+    }
+
     private enum RangeConfirmation { case honoured, ignored }
 
     /// Audit DMX-101: the cold connection's 200 is one answer. Some CDNs send a 200 on a cache miss
@@ -1538,7 +1582,9 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
             "[AVIOReader] \(label) origin does not honour Range (Content-Length \(contentLength)); "
             + "playing forward-only from one unranged GET (audit DMX-101)", category: .demux)
         originIgnoresRange = true
+        winCond.lock()
         fileSize = -1
+        winCond.unlock()
         streamLock.lock()
         streamExpectedBytes = contentLength > 0 ? contentLength : -1
         streamLock.unlock()
diff --git a/Tests/AetherEngineTests/RangeIgnoringOriginTests.swift b/Tests/AetherEngineTests/RangeIgnoringOriginTests.swift
index 184207efc..1593389ee 100644
--- a/Tests/AetherEngineTests/RangeIgnoringOriginTests.swift
+++ b/Tests/AetherEngineTests/RangeIgnoringOriginTests.swift
@@ -84,18 +84,10 @@ struct RangeIgnoringOriginTests {
 
     // MARK: - On the wire
 
-    @Test("an origin that ignores Range is read forward-only past the 32 MB range boundary",
-          .timeLimit(.minutes(2)))
-    func forwardOnlyPastTheRangeBoundary() throws {
-        let total = Int64(72 * mb)
-        let maybe = ThrottledOriginServer(totalSize: total, throttleUs: 500, patternedBody: true,
-                                          respond: { _, _, _ in .serve200 })
-        let server = try #require(maybe)
-        defer { server.stop() }
-        let reader = AVIOReader(url: URL(string: "http://127.0.0.1:\(server.port)/movie.ts")!)
-        defer { reader.markClosed(); reader.close() }
-        try reader.open()
-
+    /// What a forward-only source owes: a non-seekable pb that still states its length, every byte of
+    /// the body once and in order, a clean EOF, a bounded buffer, and no ranged request past the open.
+    private func expectForwardOnlyPlayback(_ reader: AVIOReader, _ server: ThrottledOriginServer,
+                                           total: Int64, unrangedRequests: ClosedRange<Int> = 1...1) {
         #expect(reader.originIgnoresRange)
         #expect(!reader.isSeekable, "the pb must be non-seekable so FFmpeg never seeks a source that cannot")
         #expect(reader.seek(offset: 0, whence: Self.avseekSize) == total,
@@ -113,7 +105,8 @@ struct RangeIgnoringOriginTests {
 
         // One unranged GET carried the whole body. Everything else is the open's own: the bounded
         // range that was answered with a 200, the one byte confirmation, the suffix tail prefetch.
-        #expect(server.rangeHeaderPresence.filter { !$0 }.count == 1)
+        #expect(unrangedRequests.contains(server.rangeHeaderPresence.filter { !$0 }.count),
+                "\(server.rangeHeaderPresence.filter { !$0 }.count) requests without a Range header")
         let tail = total - Int64(AVIOReader.tailPrefetchBytes)
         let strays = server.requestLog.enumerated().filter { index, request in
             server.rangeHeaderPresence[index] && request.start > 1 && request.start != tail
@@ -121,6 +114,42 @@ struct RangeIgnoringOriginTests {
         #expect(strays.isEmpty, "ranged requests past the open: \(strays.map(\.element))")
     }
 
+    @Test("an origin that ignores Range is read forward-only past the 32 MB range boundary",
+          .timeLimit(.minutes(2)))
+    func forwardOnlyPastTheRangeBoundary() throws {
+        let total = Int64(72 * mb)
+        let maybe = ThrottledOriginServer(totalSize: total, throttleUs: 500, patternedBody: true,
+                                          respond: { _, _, _ in .serve200 })
+        let server = try #require(maybe)
+        defer { server.stop() }
+        let reader = AVIOReader(url: URL(string: "http://127.0.0.1:\(server.port)/movie.ts")!)
+        defer { reader.markClosed(); reader.close() }
+        try reader.open()
+
+        expectForwardOnlyPlayback(reader, server, total: total)
+    }
+
+    @Test("a cold open that was refused once does not hide an origin that ignores Range",
+          .timeLimit(.minutes(2)))
+    func refusedColdOpenStillFindsTheIgnoredRange() throws {
+        let total = Int64(72 * mb)
+        let once = FirstClaim()
+        let respond: @Sendable (Int, Int64, String) -> ThrottledOriginServer.Directive = { _, offset, _ in
+            offset == 0 && once.take() ? .status(503) : .serve200
+        }
+        let maybe = ThrottledOriginServer(totalSize: total, throttleUs: 500, patternedBody: true,
+                                          respond: respond)
+        let server = try #require(maybe)
+        defer { server.stop() }
+        let reader = AVIOReader(url: URL(string: "http://127.0.0.1:\(server.port)/movie.ts")!)
+        defer { reader.markClosed(); reader.close() }
+        try reader.open()
+
+        // The size probe's HEAD fallback has no Range header either, and it fires when the probe
+        // behind a refusal is slow, which is the case here.
+        expectForwardOnlyPlayback(reader, server, total: total, unrangedRequests: 1...2)
+    }
+
     @Test("an origin that honours Range keeps the seekable path and its range refills",
           .timeLimit(.minutes(2)))
     func honouringOriginIsUnaffected() throws {
@@ -153,6 +182,41 @@ struct RangeIgnoringOriginTests {
                 "an honoured range needs no confirmation")
     }
 
+    @Test("an origin that honours Range and refused the cold open once keeps the seekable path",
+          .timeLimit(.minutes(2)))
+    func refusedColdOpenOnHonouringOriginStaysSeekable() throws {
+        let total = Int64(40 * mb)
+        let once = FirstClaim()
+        let respond: @Sendable (Int, Int64, String) -> ThrottledOriginServer.Directive = { _, offset, _ in
+            offset == 0 && once.take() ? .status(503) : .serve206
+        }
+        let server = try #require(ThrottledOriginServer(totalSize: total, throttleUs: 500, respond: respond))
+        defer { server.stop() }
+        let reader = AVIOReader(url: URL(string: "http://127.0.0.1:\(server.port)/movie.bin")!)
+        defer { reader.markClosed(); reader.close() }
+        try reader.open()
+
+        #expect(!reader.originIgnoresRange)
+        #expect(reader.isSeekable)
+        #expect(reader.resolvedByteSize == total)
+
+        let chunk = 256 * 1024
+        let buf = UnsafeMutablePointer<UInt8>.allocate(capacity: chunk)
+        defer { buf.deallocate() }
+        var read: Int64 = 0
+        while read < 36 * Int64(mb) {
+            let n = reader.read(into: buf, size: Int32(chunk))
+            #expect(n > 0, "read failed at \(read)")
+            if n <= 0 { break }
+            read += Int64(n)
+        }
+        #expect(read >= 36 * Int64(mb))
+        #expect(server.requestedRanges.contains { $0.start == 32 * Int64(mb) },
+                "the refill at the 32 MB boundary never asked for its range")
+        #expect(!server.requestLog.contains { $0.start == 1 && $0.end == 1 },
+                "an honoured range needs no confirmation")
+    }
+
     @Test("a 200 on a cache miss at the open does not take the seekable path away",
           .timeLimit(.minutes(2)))
     func cacheMissAtTheOpenIsConfirmedAway() throws {
diff --git a/docs/api.md b/docs/api.md
index 97bec5b7a..940cefd25 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -981,7 +981,7 @@ All flags default to safe values; the table is the full set. Depth for the media
 | `sequentialOrigin` | false | Declare an origin that fabricates range answers: one long-lived unranged GET, no ranged probes, non-seekable pb. **Seeking is unavailable**; re-request the archive at a shifted start instead. A URL source the reader finds forward-only by itself (`Range` ignored, so it can only stream front to back; the open confirms a 200 answer with a one byte range, because some CDNs answer a cache miss that way) is served this way without the declaration when its container states a duration, which a stated `Content-Length` lets an MPEG-TS source estimate; `loadedOptions` then reads `true` with that duration declared, and without a duration it stays on the software path. An AirPlay hop on such a session swaps the item onto the LAN address instead of reopening the source, since a reopen could only start again from byte 0. |
 | `declaredDurationSeconds` | nil | Trusted duration, overriding the container's. Required alongside `sequentialOrigin` on VOD, where the tail read is gone. |
 | `maxConcurrentSourceRequests` | nil | Most requests the reader may have open against this origin at once, across every path it fetches on (pump ranges, detour blocks, size probes, tail prefetch, subtitle side reader). nil counts without capping and lowers the ceiling on its own after a 429/503/509. Set it when the provider states a limit; `1` also switches off the speculative parallel paths, which exist only to overlap with the pump. Counts **requests**, not TCP connections, because over HTTP/2 a session multiplexes every request onto one connection while the origin still counts each one (AE#377). It is also the only ceiling: several engines playing from one origin are bounded by this value and by what the origin refuses, not by a transport pool underneath it (AE#450). |
-| `heldSourceConnection` | false | Ask the source **once** and pull it, instead of ending the connection at the reader's window high water and asking again every 8 to 16 MB of drain (AE#377). For an origin that punishes repeated requests rather than concurrency: some CDNs refuse new requests for minutes at a stretch while serving an already open connection at full rate, and against one of those the request cadence is the defect, at any range size (measured at the reporting origin: 32 MB ranges raised to 256 MB, eight times fewer requests, the refusals unchanged). Where `maxConcurrentSourceRequests` bounds how many requests are in flight, this removes the second request. The read path is the engine's own HTTP/1.1 over a demand-driven stream task, so: **HTTP/1.1 only** (no ALPN, an HTTP/2-only origin is out of scope), the **system proxy configuration does not apply**, and TLS is the OS's through the same host trust decision as every other engine session but has not been exercised against a self-signed origin. A viewer who pauses ends the connection after five seconds and resuming costs one request at the frontier, because a held flow nobody reads is the process-wide Network.framework starvation of AE#310. Applies to the playback reader; the subtitle and enrichment side readers keep the default transport, since they park for minutes at a time. **Names the session**: the transport is chosen at open, so a reload that changes it is refused. |
+| `heldSourceConnection` | false | Ask the source **once** and pull it, instead of ending the connection at the reader's window high water and asking again every 8 to 16 MB of drain (AE#377). For an origin that punishes repeated requests rather than concurrency: some CDNs refuse new requests for minutes at a stretch while serving an already open connection at full rate, and against one of those the request cadence is the defect, at any range size (measured at the reporting origin: 32 MB ranges raised to 256 MB, eight times fewer requests, the refusals unchanged). Where `maxConcurrentSourceRequests` bounds how many requests are in flight, this removes the second request. The read path is the engine's own HTTP/1.1 over a demand-driven stream task, so: **HTTP/1.1 only** (no ALPN, an HTTP/2-only origin is out of scope), the **system proxy configuration does not apply**, and TLS is the OS's through the same host trust decision as every other engine session but has not been exercised against a self-signed origin. A viewer who pauses ends the connection after five seconds and resuming costs one request at the frontier, because a held flow nobody reads is the process-wide Network.framework starvation of AE#310. Applies to the playback reader; the subtitle and enrichment side readers keep the default transport, since they park for minutes at a time. The open-time detection of an origin that ignores `Range` (see `sequentialOrigin`) does not cover it, because its open is open-ended. **Names the session**: the transport is chosen at open, so a reload that changes it is refused. |
 | `autoplay` | true | False mounts paused: the load skips the terminal `play()` and settles at `.paused` for a host that resumes later. It describes THIS MOUNT and nothing after it: the rebuilds a session makes on its own (`reloadAtCurrentPosition`, an option correction, the AirPlay LAN swap, an audio-delay nudge) come back in the transport state the session is in, not in this one. Correcting it through `reloadAtCurrentPosition(applying:)` therefore does nothing (the log names it as not applied rather than as applied, AE#464 round 3, and the call returns it as `sessionOwned` with `rebuilt` false rather than spending a teardown on it, AE#464 round 4); call `play()` or `pause()` instead. |
 
 ## Value types

From e16abf6b62d831eaa9741b14496b795a741a1606 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 11:11:01 +0200
Subject: [PATCH 230/359] fix(audio): the AE#549 auto-flush runs off the
 posting thread so it cannot wait on the enqueue lock (audit DEC-106 review
 M1)

enqueue(sampleBuffer:ifEpoch:) now holds the output's lock across
renderer.enqueue, and the AE#549 observer takes that lock synchronously on
whatever thread AVFoundation posts from. A renderer that posts from inside
enqueue would make the feed thread wait on a lock it holds itself, and every
later flush(), stop() and seekClock() on the main actor with it (a hung Back).

The observer now reads the flush time from the notification and hops onto a
private serial queue that takes the lock, flushes and logs, so the posting
thread never waits and the flush stays serialized with enqueueing. A DEBUG hook
inside enqueue's locked section posts the notification synchronously; the test
hung the feed thread before the change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 Sources/AetherEngine/Audio/AudioOutput.swift  | 38 ++++++++++++------
 .../AudioOutputFlushEpochTests.swift          | 40 +++++++++++++++++++
 2 files changed, 66 insertions(+), 12 deletions(-)

diff --git a/Sources/AetherEngine/Audio/AudioOutput.swift b/Sources/AetherEngine/Audio/AudioOutput.swift
index 84d1bdd5e..9ec1debab 100644
--- a/Sources/AetherEngine/Audio/AudioOutput.swift
+++ b/Sources/AetherEngine/Audio/AudioOutput.swift
@@ -66,6 +66,11 @@ final class AudioOutput: @unchecked Sendable {
     private var automaticFlushObserver: NSObjectProtocol?
     private var _automaticFlushCount = 0
 
+    /// Where the AE#549 flush runs. The posting thread must never wait on `lock`: `enqueue` holds it
+    /// across `renderer.enqueue` (DEC-106), and a renderer that posts from inside that call would make the
+    /// feed thread wait on a lock it already holds, with every `flush()` / `stop()` / `seekClock()` behind it.
+    private let automaticFlushQueue = DispatchQueue(label: "engine.audio.autoflush")
+
     /// AE#549: the renderer throws its queue away when the route changes under it, and posts the
     /// timestamp of the first sample it dropped. Nothing in the engine observed that, so the lead
     /// that was discarded was neither re-fed nor mentioned anywhere.
@@ -90,18 +95,21 @@ final class AudioOutput: @unchecked Sendable {
             guard let self else { return }
             let flushedFrom = (note.userInfo?[AVSampleBufferAudioRendererFlushTimeKey] as? NSValue)?
                 .timeValue.seconds
-            lock.lock()
-            _automaticFlushCount += 1
-            let count = _automaticFlushCount
-            renderer.flush()
-            lock.unlock()
-            EngineLog.emit(
-                "[AudioOutput] AE#549 renderer flushed itself (#\(count)): "
-                + "dropped from \(flushedFrom.map { String(format: "%.3f", $0) } ?? "unknown")s, "
-                + "clock at \(String(format: "%.3f", currentTimeSeconds))s rate=\(rate); "
-                + "audio returns once the feed reaches the clock",
-                category: .swPlayback
-            )
+            automaticFlushQueue.async { [weak self] in
+                guard let self else { return }
+                lock.lock()
+                _automaticFlushCount += 1
+                let count = _automaticFlushCount
+                renderer.flush()
+                lock.unlock()
+                EngineLog.emit(
+                    "[AudioOutput] AE#549 renderer flushed itself (#\(count)): "
+                    + "dropped from \(flushedFrom.map { String(format: "%.3f", $0) } ?? "unknown")s, "
+                    + "clock at \(String(format: "%.3f", currentTimeSeconds))s rate=\(rate); "
+                    + "audio returns once the feed reaches the clock",
+                    category: .swPlayback
+                )
+            }
         }
     }
 
@@ -195,6 +203,9 @@ final class AudioOutput: @unchecked Sendable {
                 + String(format: " (sample at %.3fs delivered at %.3fs)", source, source + offset.seconds)
         }
         renderer.enqueue(delivered)
+        #if DEBUG
+        afterRendererEnqueueForTesting?()
+        #endif
         lock.unlock()
         if let offsetLine { EngineLog.emit(offsetLine, category: .swPlayback) }
 
@@ -219,6 +230,9 @@ final class AudioOutput: @unchecked Sendable {
     }
 
     #if DEBUG
+    /// Test-only: runs inside `enqueue`'s locked section, right after the renderer took the buffer, which
+    /// is where a renderer that posts its notifications from inside `enqueue` would post them.
+    var afterRendererEnqueueForTesting: (@Sendable () -> Void)?
     private var _loggedFirstEnqueue = false
     private var _loggedRendererError = false
     #endif
diff --git a/Tests/AetherEngineTests/AudioOutputFlushEpochTests.swift b/Tests/AetherEngineTests/AudioOutputFlushEpochTests.swift
index cf9d655f3..9efda83d7 100644
--- a/Tests/AetherEngineTests/AudioOutputFlushEpochTests.swift
+++ b/Tests/AetherEngineTests/AudioOutputFlushEpochTests.swift
@@ -81,6 +81,46 @@ struct AudioOutputFlushEpochTests {
         #expect(output.epoch != afterFlush)
     }
 
+    private final class Returned: @unchecked Sendable {
+        private let lock = NSLock()
+        private var done = false
+        func set() { lock.withLock { done = true } }
+        var isSet: Bool { lock.withLock { done } }
+    }
+
+    private final class BufferBox: @unchecked Sendable {
+        let buffer: CMSampleBuffer
+        init(_ buffer: CMSampleBuffer) { self.buffer = buffer }
+    }
+
+    /// AE#549's observer takes the output's lock on whatever thread AVFoundation posts from, and `enqueue`
+    /// now holds that lock across `renderer.enqueue`. A renderer that posts from inside `enqueue` (the
+    /// 27 SDKs move the same condition into the enqueue call itself) would make the feed thread wait on a
+    /// lock it already holds, and every later `flush()` / `stop()` / `seekClock()` with it.
+    @Test("an automatic-flush notification posted from inside enqueue does not hang the feed",
+          .timeLimit(.minutes(1)))
+    func automaticFlushPostedInsideEnqueueDoesNotDeadlock() async throws {
+        let output = AudioOutput()
+        let box = BufferBox(try #require(makeBuffer(pts: 1)))
+        output.afterRendererEnqueueForTesting = { [unowned output] in
+            NotificationCenter.default.post(name: .AVSampleBufferAudioRendererWasFlushedAutomatically,
+                                            object: output.renderer)
+        }
+        let returned = Returned()
+        let feed = Thread {
+            output.enqueue(sampleBuffer: box.buffer)
+            returned.set()
+        }
+        feed.start()
+
+        let finished = try await waitFor(upTo: .seconds(10)) { returned.isSet }
+        #expect(finished, "the feed thread is parked on a lock it holds itself")
+        guard finished else { return }
+
+        try await waitFor { output.automaticFlushCount == 1 }
+        #expect(output.automaticFlushCount == 1, "the flush still happens, serialized with enqueueing")
+    }
+
     @Test("an unconditional enqueue is untouched by the epoch")
     func unconditionalEnqueueStillEnqueues() throws {
         let output = AudioOutput()

From c0ef3966d607d08e1c98c725cee7890a58c5fce5 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 11:11:01 +0200
Subject: [PATCH 231/359] fix(audio): the DVR ring audio path honours the flush
 epoch too (audit DEC-106 review N1)

seekLiveDVR flushes the audio output and only then moves the ring cursor, so
the feeder or the look-ahead pump could hold a packet read at the old cursor.
feedRingPacket enqueued its buffers unconditionally, and after a rewind a
buffer from before the seek carries a higher stamp than the new clock: it
parks at the head of the fresh queue and mutes audio for the rewind distance.

feederIteration reads the output's epoch before anything else (ahead of the
playing check, which a seek clears before it flushes), hands it to the pump
and to feedRingPacket, which enqueues with ifEpoch and mirrors to the tap only
behind the accept. feedRingPacket is internal for the test.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../Native/SoftwarePlaybackHost.swift         | 22 +++--
 .../RingAudioFlushEpochTests.swift            | 87 +++++++++++++++++++
 2 files changed, 103 insertions(+), 6 deletions(-)
 create mode 100644 Tests/AetherEngineTests/RingAudioFlushEpochTests.swift

diff --git a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
index cb0f06ad4..6bdf9b6f2 100644
--- a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
+++ b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
@@ -1534,7 +1534,7 @@ final class SoftwarePlaybackHost {
 
     /// Reconstruct AVPacket from ring entry, convert PTS from seconds back to stream time_base, and route to decoders. Returns true when audio buffers were enqueued (used for feeder clock arming).
     @discardableResult
-    nonisolated private static func feedRingPacket(
+    nonisolated static func feedRingPacket(
         _ pkt: PacketRingBuffer.Packet,
         videoDecoder: any VideoDecodingPipeline,
         audioDecoder: AudioDecoder?,
@@ -1544,6 +1544,7 @@ final class SoftwarePlaybackHost {
         videoTimeBaseSeconds: Double,
         audioTimeBaseSeconds: Double,
         audioTapSink: (@Sendable (CMSampleBuffer) -> Void)?,
+        audioEpoch: UInt64,
         noteDecodeGeneration: @Sendable () -> Void
     ) -> Bool {
         let tbSec = pkt.isVideo ? videoTimeBaseSeconds : audioTimeBaseSeconds
@@ -1573,8 +1574,11 @@ final class SoftwarePlaybackHost {
         } else if let aDec = audioDecoder, let aOut = audioOutput {
             var enqueued = false
             for buf in aDec.decode(packet: p) {
-                audioTapSink?(buf)   // #95: mirror before enqueue
-                aOut.enqueue(sampleBuffer: buf)
+                // DEC-106 on the DVR path: `audioEpoch` was read before the ring read, so a rewind's flush
+                // retires what this packet decodes to. A pre-seek buffer kept at the head of the fresh queue
+                // carries a higher stamp than the new clock and mutes audio for the rewind distance.
+                guard aOut.enqueue(sampleBuffer: buf, ifEpoch: audioEpoch) else { return enqueued }
+                audioTapSink?(buf)   // #95: mirrored behind the accept
                 enqueued = true
             }
             return enqueued
@@ -2073,7 +2077,7 @@ final class SoftwarePlaybackHost {
         var hadLead = false
         var rebuffering = false
         var lastLowLeadLog = DispatchTime(uptimeNanoseconds: 0)
-        func pumpAudio() {
+        func pumpAudio(epoch audioEpoch: UInt64) {
             guard let aDec = audioDecoder, let aOut = audioOutput, audioStreamIndex >= 0 else { return }
             var seq = audioLookahead.align(to: readCursor())
             func pumpIteration() -> Bool {
@@ -2106,6 +2110,7 @@ final class SoftwarePlaybackHost {
                     videoTimeBaseSeconds: videoTimeBaseSeconds,
                     audioTimeBaseSeconds: audioTimeBaseSeconds,
                     audioTapSink: audioTapSink(),
+                    audioEpoch: audioEpoch,
                     noteDecodeGeneration: noteDecodeGeneration
                 )
                 if !armed {
@@ -2179,6 +2184,10 @@ final class SoftwarePlaybackHost {
         }
 
         func feederIteration() -> Bool {
+            // Read before anything else: a DVR seek clears `isPlaying`, then flushes the audio output, then
+            // moves the cursor, so an epoch read ahead of the playing check is retired by any flush that
+            // lands after the cursor this iteration reads (audit DEC-106).
+            let audioEpoch = audioOutput?.epoch ?? 0
             if !isPlaying() {
                 condition.lock()
                 while !isPlaying() && !stopRequested() {
@@ -2191,7 +2200,7 @@ final class SoftwarePlaybackHost {
             }
 
             // Keep the audio renderer topped up before (possibly expensive) video work.
-            pumpAudio()
+            pumpAudio(epoch: audioEpoch)
 
             let cursor = readCursor()
             let bounds = ring.seqBounds
@@ -2244,7 +2253,7 @@ final class SoftwarePlaybackHost {
                     autoreleasepool {
                         Thread.sleep(forTimeInterval: 0.005)
                         waitTicks += 1
-                        if waitTicks % 20 == 0 { pumpAudio() }
+                        if waitTicks % 20 == 0 { pumpAudio(epoch: audioEpoch) }
                         // #337: the pump is what can still arm the clock from here, so its spent
                         // pre-arm budget is what turns this park terminal (an audio track that
                         // never decodes a buffer). The renderer cannot drain at a stopped clock,
@@ -2285,6 +2294,7 @@ final class SoftwarePlaybackHost {
                 videoTimeBaseSeconds: videoTimeBaseSeconds,
                 audioTimeBaseSeconds: audioTimeBaseSeconds,
                 audioTapSink: audioTapSink(),
+                audioEpoch: audioEpoch,
                 noteDecodeGeneration: noteDecodeGeneration
             )
 
diff --git a/Tests/AetherEngineTests/RingAudioFlushEpochTests.swift b/Tests/AetherEngineTests/RingAudioFlushEpochTests.swift
new file mode 100644
index 000000000..8120093e6
--- /dev/null
+++ b/Tests/AetherEngineTests/RingAudioFlushEpochTests.swift
@@ -0,0 +1,87 @@
+import Foundation
+import Testing
+import AetherLibavcodec
+import AetherLibavutil
+@testable import AetherEngine
+
+/// Audit DEC-106, the DVR ring's audio path. `seekLiveDVR` flushes the audio output and only then moves
+/// the ring cursor, so the feeder or the look-ahead pump can be holding a packet read at the old cursor.
+/// Its decoded buffers used to be enqueued unconditionally, and after a rewind a buffer from before the
+/// seek carries a HIGHER stamp than the new clock: it parks at the head of the fresh queue and mutes the
+/// audio for the length of the rewind.
+@Suite("DVR ring audio follows the flush epoch (DEC-106)")
+struct RingAudioFlushEpochTests {
+
+    private final class Counter: @unchecked Sendable {
+        private let lock = NSLock()
+        private var count = 0
+        func increment() { lock.withLock { count += 1 } }
+        var value: Int { lock.withLock { count } }
+    }
+
+    private func makeWAV(seconds: Double) -> Data {
+        let sampleRate = 48_000, channels = 2
+        let pcm = Data(count: Int(Double(sampleRate) * seconds) * channels * 2)
+        var d = Data()
+        func str(_ s: String) { d.append(s.data(using: .ascii)!) }
+        func u32(_ v: UInt32) { withUnsafeBytes(of: v.littleEndian) { d.append(contentsOf: $0) } }
+        func u16(_ v: UInt16) { withUnsafeBytes(of: v.littleEndian) { d.append(contentsOf: $0) } }
+        str("RIFF"); u32(UInt32(36 + pcm.count)); str("WAVE")
+        str("fmt "); u32(16); u16(1); u16(UInt16(channels)); u32(UInt32(sampleRate))
+        u32(UInt32(sampleRate * channels * 2)); u16(UInt16(channels * 2)); u16(16)
+        str("data"); u32(UInt32(pcm.count)); d.append(pcm)
+        return d
+    }
+
+    @Test("a ring audio packet decided on before a flush yields no buffer after it, one decided after does")
+    func ringPacketsFollowTheEpoch() throws {
+        let demuxer = Demuxer()
+        try demuxer.open(reader: DataIOReader(data: makeWAV(seconds: 4)))
+        defer { demuxer.close() }
+        let audioIndex = demuxer.audioStreamIndex
+        let stream = try #require(demuxer.stream(at: audioIndex))
+        let decoder = AudioDecoder()
+        try decoder.open(stream: stream)
+        defer { decoder.close() }
+
+        var packets: [PacketRingBuffer.Packet] = []
+        while let pkt = try demuxer.readPacket() {
+            if pkt.pointee.stream_index == audioIndex, let data = pkt.pointee.data {
+                packets.append(PacketRingBuffer.Packet(
+                    pts: Double(packets.count) * 1024.0 / 48_000.0, isKeyframe: true, isVideo: false,
+                    bytes: Data(bytes: data, count: Int(pkt.pointee.size))))
+            }
+            var p: UnsafeMutablePointer<AVPacket>? = pkt
+            trackedPacketFree(&p)
+        }
+        try #require(packets.count >= 40)
+
+        let output = AudioOutput()
+        let tapped = Counter()
+        func feed(_ packet: PacketRingBuffer.Packet, epoch: UInt64) -> Bool {
+            SoftwarePlaybackHost.feedRingPacket(
+                packet,
+                videoDecoder: SoftwareVideoDecoder(),
+                audioDecoder: decoder,
+                audioOutput: output,
+                videoStreamIndex: 0,
+                audioStreamIndex: audioIndex,
+                videoTimeBaseSeconds: 1.0 / 90_000.0,
+                audioTimeBaseSeconds: 1.0 / 48_000.0,
+                audioTapSink: { _ in tapped.increment() },
+                audioEpoch: epoch,
+                noteDecodeGeneration: {})
+        }
+
+        let stale = output.epoch
+        output.flush()
+        let half = packets.count / 2
+        let staleProduced = packets[..<half].map { feed($0, epoch: stale) }
+        #expect(!staleProduced.contains(true), "the rewind's flush retired these")
+        #expect(tapped.value == 0, "a refused buffer is not mirrored to the tap either")
+
+        let freshProduced = packets[half...].map { feed($0, epoch: output.epoch) }
+        #expect(freshProduced.contains(true), "an epoch read after the flush is honoured")
+        #expect(tapped.value > 0)
+    }
+}

From 7255137cddd7da35de5d0b8bede914b0b0ada965 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 11:16:45 +0200
Subject: [PATCH 232/359] fix(live): the ring evicts and retries only for a
 full volume or quota (audit PERF-101, review)

The evict-and-retry ran for any write error. With no descriptors left, or a purged tmp directory,
every append then evicted a chunk of real history and still failed, so the DVR window collapsed
within a few packets for nothing. Only ENOSPC and EDQUOT make room now. Any other error drops that
packet, keeps the history, and is logged once per ring.

The new test injects EMFILE, EIO and ENOENT (with a keyframe and a non-keyframe packet) and asserts
the retained window, the disk accounting and every stored packet are untouched; it failed before the
change because the retry evicted and succeeded. The existing retry test now also covers EDQUOT.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../AetherEngine/Video/PacketRingBuffer.swift | 25 +++++++++-
 .../PacketRingBufferChunkSpoolTests.swift     | 49 ++++++++++++++++---
 docs/architecture.md                          |  2 +-
 3 files changed, 68 insertions(+), 8 deletions(-)

diff --git a/Sources/AetherEngine/Video/PacketRingBuffer.swift b/Sources/AetherEngine/Video/PacketRingBuffer.swift
index 35fc3a342..1d752d3e3 100644
--- a/Sources/AetherEngine/Video/PacketRingBuffer.swift
+++ b/Sources/AetherEngine/Video/PacketRingBuffer.swift
@@ -113,6 +113,7 @@ final class PacketRingBuffer: @unchecked Sendable {
     private var tail: ChunkHandle?
     private var tailOffset = 0
     private var nextChunkID: UInt32 = 0
+    private var loggedOtherWriteFailure = false
 
     // MARK: - Init / close
 
@@ -184,7 +185,13 @@ final class PacketRingBuffer: @unchecked Sendable {
         } catch {
             // Audit VPERF-101: eviction used to run only after a successful write, so once the volume
             // filled, every append failed, nothing was ever freed, and the feeder waited at the live
-            // edge forever. Shrink the window and try once more before dropping the packet.
+            // edge forever. Shrink the window and try once more before dropping the packet. Only for a
+            // full volume or quota: any other failure (no descriptors left, a purged tmp directory)
+            // would evict real history on every packet and still fail.
+            guard Self.isOutOfSpace(error) else {
+                noteWriteFailureOnce(error)
+                throw error
+            }
             guard makeRoomAfterFailedWrite(incomingKeyframe: isVideo && isKeyframe) else { throw error }
             placement = try writeLocked(bytes)
         }
@@ -487,6 +494,22 @@ final class PacketRingBuffer: @unchecked Sendable {
         Self.unlinkAll(doomed)
     }
 
+    /// A write that failed because the volume or the quota has no room, which freeing a chunk can cure.
+    static func isOutOfSpace(_ error: Error) -> Bool {
+        let nsError = error as NSError
+        return nsError.domain == NSPOSIXErrorDomain
+            && (nsError.code == Int(ENOSPC) || nsError.code == Int(EDQUOT))
+    }
+
+    /// `writeLock` held. A failure that eviction cannot cure drops only its packet, so a steady one
+    /// must not write a line per packet.
+    private func noteWriteFailureOnce(_ error: Error) {
+        guard !loggedOtherWriteFailure, error as? Failure != .closed else { return }
+        loggedOtherWriteFailure = true
+        EngineLog.emit("[PacketRingBuffer] write failed (\(error)); packet dropped, history kept "
+                       + "(logged once)", category: .swPlayback)
+    }
+
     /// `writeLock` held. Frees at least one chunk file while keeping the retained span on a keyframe:
     /// up to the first keyframe in a later chunk, or, when the incoming packet is itself a video
     /// keyframe that can open a fresh span, everything including the tail chunk. False when nothing
diff --git a/Tests/AetherEngineTests/PacketRingBufferChunkSpoolTests.swift b/Tests/AetherEngineTests/PacketRingBufferChunkSpoolTests.swift
index 912eec7c4..96ef5fae0 100644
--- a/Tests/AetherEngineTests/PacketRingBufferChunkSpoolTests.swift
+++ b/Tests/AetherEngineTests/PacketRingBufferChunkSpoolTests.swift
@@ -189,24 +189,28 @@ struct PacketRingBufferChunkSpoolTests {
     private final class FlakyDisk: @unchecked Sendable {
         private let lock = NSLock()
         private var failures = 0
+        private var failureCode = ENOSPC
         private var capacity: Int?
         var ring: PacketRingBuffer?
         private(set) var rejected = 0
 
-        func failNext(_ n: Int) { lock.lock(); failures = n; lock.unlock() }
+        func failNext(_ n: Int, code: Int32 = ENOSPC) {
+            lock.lock(); failures = n; failureCode = code; lock.unlock()
+        }
         func setCapacity(_ bytes: Int?) { lock.lock(); capacity = bytes; lock.unlock() }
 
         var writer: PacketRingBuffer.WriteAll {
             { [self] fd, bytes, offset in
                 lock.lock()
                 var fail = false
-                if failures > 0 { failures -= 1; fail = true }
+                var code = ENOSPC
+                if failures > 0 { failures -= 1; fail = true; code = failureCode }
                 let cap = capacity
                 lock.unlock()
                 if !fail, let cap, let ring, ring.diskBytes + bytes.count > cap { fail = true }
                 if fail {
                     lock.lock(); rejected += 1; lock.unlock()
-                    throw NSError(domain: NSPOSIXErrorDomain, code: Int(ENOSPC))
+                    throw NSError(domain: NSPOSIXErrorDomain, code: Int(code))
                 }
                 try PacketRingBuffer.pwriteAll(fd, bytes, offset)
             }
@@ -221,8 +225,9 @@ struct PacketRingBufferChunkSpoolTests {
         return ring
     }
 
-    @Test("A write that fails once is retried after the oldest chunk is freed, and nothing is dropped")
-    func failedWriteMakesRoomAndRetries() throws {
+    @Test("A write that fails once for want of space is retried after the oldest chunk is freed, and nothing is dropped",
+          arguments: [ENOSPC, EDQUOT])
+    func failedWriteMakesRoomAndRetries(code: Int32) throws {
         let dirs = ScratchDirs()
         let disk = FlakyDisk()
         let ring = try flakyRing(disk: disk, dirs: dirs)
@@ -232,7 +237,7 @@ struct PacketRingBufferChunkSpoolTests {
             try ring.append(pts: Double(i), isKeyframe: i % 2 == 0, isVideo: true, bytes: body)
         }
         #expect(ring.seqBounds.first == 0)
-        disk.failNext(1)
+        disk.failNext(1, code: code)
         try ring.append(pts: 10, isKeyframe: true, isVideo: true, bytes: body)
 
         let bounds = ring.seqBounds
@@ -243,6 +248,38 @@ struct PacketRingBufferChunkSpoolTests {
         #expect(ring.packet(atSeq: 10)?.bytes == body)
     }
 
+    @Test("A write that fails for any other reason drops that packet and keeps the whole history",
+          arguments: [EMFILE, EIO, ENOENT])
+    func otherWriteFailuresKeepTheWindow(code: Int32) throws {
+        let dirs = ScratchDirs()
+        let disk = FlakyDisk()
+        let ring = try flakyRing(disk: disk, dirs: dirs)
+        defer { ring.close() }
+        let body = { (i: Int) in Data(repeating: UInt8(truncatingIfNeeded: i), count: 32 << 10) }
+        for i in 0..<10 {
+            try ring.append(pts: Double(i), isKeyframe: i % 2 == 0, isVideo: true, bytes: body(i))
+        }
+        let before = ring.seqBounds
+        let diskBefore = ring.diskBytes
+        #expect(before.first == 0)
+
+        for keyframe in [false, true] {
+            disk.failNext(1, code: code)
+            #expect(throws: (any Error).self) {
+                try ring.append(pts: 10, isKeyframe: keyframe, isVideo: true, bytes: body(10))
+            }
+            let after = ring.seqBounds
+            #expect(after.first == before.first && after.end == before.end,
+                    "errno \(code): nothing evicted, nothing indexed (keyframe \(keyframe))")
+            #expect(ring.diskBytes == diskBefore)
+        }
+        for i in 0..<10 { #expect(ring.packet(atSeq: i)?.bytes == body(i)) }
+
+        try ring.append(pts: 10, isKeyframe: false, isVideo: true, bytes: body(10))
+        #expect(ring.seqBounds.end == before.end + 1, "the next write goes through")
+        #expect(ring.seqBounds.first == 0)
+    }
+
     @Test("A full volume shrinks the rewind window and the live feed keeps flowing")
     func fullVolumeKeepsFeedingWithAShrinkingWindow() throws {
         let dirs = ScratchDirs()
diff --git a/docs/architecture.md b/docs/architecture.md
index 9391a2e95..d76d45f1d 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -491,7 +491,7 @@ Sources/AetherEngine/
 │   ├── NALUnitChain.swift                   Final-stage payload guard before the fMP4 mux: a video sample whose length-prefixed NAL chain overruns it is cut at its last complete unit, because Apple's parser answers one such sample with -19602 for the whole segment (AE#561)
 │   ├── AudioLanguageMap.swift               Native path: the ISO 639-2/T an audio track is declared with in the master's `EXT-X-MEDIA:TYPE=AUDIO` rendition and written into its `mdhd`; ICU in front of the twenty ISO 639-2/B bibliographic codes Matroska writes, then canonicalization for the ISO 639-3 members CLDR aliases and pass-through for the ones it does not, failing closed on anything ICU can neither resolve nor name (AE#458)
 │   ├── FragmentSplitter.swift               Native path: routes mp4 muxer's avio output stream into init.mp4 (ftyp+moov) vs per-segment moof+mdat files
-│   ├── PacketRingBuffer.swift               Live path: keyframe-indexed, disk-spooled packet ring backing the SW-path DVR rewind (append-only chunk files, a 24-byte index record per packet, eviction by time and by the session retention budget, evict-and-retry when a write fails)
+│   ├── PacketRingBuffer.swift               Live path: keyframe-indexed, disk-spooled packet ring backing the SW-path DVR rewind (append-only chunk files, a 24-byte index record per packet, eviction by time and by the session retention budget, evict-and-retry when the volume or quota is full)
 │   ├── SessionDirectoryLiveness.swift       The flock marker a session directory under `aether-segments/` holds for its owner's lifetime, so the stale-session sweep spares a live SegmentCache or DVR ring (AE#451, SEG-105)
 │   ├── SegmentCache.swift                   Native path: producer/consumer segment store with backpressure, scrub-aware eviction + byte-budgeted VOD backward retention (restart-free back-seeks)
 │   ├── VTCapabilityProbe.swift              AV1 system-decode probe + per-format `canHardwareDecode` HW-decodability check for H.264 / HEVC profiles (Intel Macs, older chips, #2); gates codec routing (VP9 / VP8 / MPEG-4 Part 2 / MPEG-2 / VC-1 and interlaced H.264 always route SW, see VideoRoutingPolicy)

From d3129e0a1f4a036919b92e330531b856b1513872 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 11:18:48 +0200
Subject: [PATCH 233/359] fix(renderer): the late-frame guard records a frame
 when it leaves the reorder buffer (audit PERF-104, review)

The guard compared a new frame against the timestamp recorded after the previous frame reached the
display layer. A second enqueuer (a drain beside the decode thread) landing between the pop and that
record was judged against the frame before and could slip one frame through out of order. A flush
landing in the same gap was worse: the in-flight frame then wrote its pre-seek timestamp after the
flush had cleared it, so a seek backwards dropped every frame until the playhead passed it.

The timestamp is now recorded under the lock that pops the frame (and for the whole buffer in
drainReorderBuffer), in its own field that flush clears. The #407 cadence statistics keep their own
post-enqueue field.

Two deterministic tests re-enter the renderer from the frame-enqueued observer, which runs in that
window: a late frame offered while another is on its way to the layer, and a flush during a hand
over. Both failed before the change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../Renderer/SampleBufferRenderer.swift       | 11 ++-
 .../SoftwareRendererReorderDepthTests.swift   | 68 +++++++++++++++++++
 2 files changed, 78 insertions(+), 1 deletion(-)

diff --git a/Sources/AetherEngine/Renderer/SampleBufferRenderer.swift b/Sources/AetherEngine/Renderer/SampleBufferRenderer.swift
index 16aa16eac..79d7e0267 100644
--- a/Sources/AetherEngine/Renderer/SampleBufferRenderer.swift
+++ b/Sources/AetherEngine/Renderer/SampleBufferRenderer.swift
@@ -125,6 +125,12 @@ final class SampleBufferRenderer: @unchecked Sendable {
     /// an even 24 fps timeline and for one carrying a doubled or a duplicate interval alike; only the
     /// spacing separates them. Guarded by `reorderLock`, reset by `takeCadence()`.
     private var _lastHandedPtsSeconds: Double?
+    /// Audit PERF-104: the newest timestamp that LEFT the reorder buffer, recorded under the same lock
+    /// that pops it. The late-frame guard reads this, not `_lastHandedPtsSeconds`, which is written
+    /// after the layer enqueue: a second enqueuer (a drain beside the decode thread) landing in that
+    /// gap would be judged against the frame before and slip through out of order. Reset by `flush`.
+    /// Guarded by `reorderLock`.
+    private var _lastReleasedPtsSeconds: Double?
     private var _minHandedDeltaSeconds = Double.infinity
     private var _maxHandedDeltaSeconds = -Double.infinity
 
@@ -355,7 +361,7 @@ final class SampleBufferRenderer: @unchecked Sendable {
         }
 
         let ptsSeconds = CMTimeGetSeconds(pts)
-        if let handed = _lastHandedPtsSeconds, ptsSeconds < handed {
+        if let handed = _lastReleasedPtsSeconds, ptsSeconds < handed {
             _outOfOrderFramesDropped += 1
             let dropped = _outOfOrderFramesDropped
             let raised = reorderDepth < Self.hardwareDecoderReorderDepth
@@ -382,6 +388,7 @@ final class SampleBufferRenderer: @unchecked Sendable {
 
         while reorderBuffer.count > reorderDepth {
             let (pb, t, hdr) = reorderBuffer.removeFirst()
+            _lastReleasedPtsSeconds = CMTimeGetSeconds(t)
             // #407: the successor is already held, so its timestamp is the frame's exact duration at
             // no extra latency. Read before the unlock, since enqueue() runs on the decode thread.
             let next = reorderBuffer.first?.1
@@ -402,6 +409,7 @@ final class SampleBufferRenderer: @unchecked Sendable {
         // #407: the next frame handed over will not follow the last one, so the gap between them is
         // not a cadence measurement. Left standing, every seek would report one enormous interval.
         _lastHandedPtsSeconds = nil
+        _lastReleasedPtsSeconds = nil
         // #303: nothing is held any more, so the frontier is not a frontier. Left standing, a
         // backward seek would keep reporting the pre-seek timestamp and read as a cushion of
         // however far the seek travelled.
@@ -421,6 +429,7 @@ final class SampleBufferRenderer: @unchecked Sendable {
         reorderLock.lock()
         let remaining = reorderBuffer
         reorderBuffer.removeAll()
+        if let newest = remaining.last { _lastReleasedPtsSeconds = CMTimeGetSeconds(newest.1) }
         reorderLock.unlock()
 
         for (i, (pb, t, hdr)) in remaining.enumerated() {
diff --git a/Tests/AetherEngineTests/SoftwareRendererReorderDepthTests.swift b/Tests/AetherEngineTests/SoftwareRendererReorderDepthTests.swift
index fe24745eb..eb1c185b3 100644
--- a/Tests/AetherEngineTests/SoftwareRendererReorderDepthTests.swift
+++ b/Tests/AetherEngineTests/SoftwareRendererReorderDepthTests.swift
@@ -134,6 +134,74 @@ struct SoftwareRendererReorderDepthTests {
         #expect(handed.seconds == [0.100, 0.200, 0.300, 0.400, 0.500, 0.600])
     }
 
+    /// Stands in for a second enqueuer (a drain, another decoder thread). The frame-enqueued observer
+    /// runs with no lock held, after a frame reached the layer and before the renderer would have
+    /// recorded it, which is exactly the window a real second thread lands in.
+    private final class SecondEnqueuer: @unchecked Sendable {
+        private let lock = NSLock()
+        private var armed = true
+        var renderer: SampleBufferRenderer?
+        let pixels: CVPixelBuffer
+        let trigger: Double
+        let lateTicks: Int
+        init(pixels: CVPixelBuffer, trigger: Double, lateTicks: Int) {
+            self.pixels = pixels
+            self.trigger = trigger
+            self.lateTicks = lateTicks
+        }
+        func frameReachedTheLayer(_ t: SoftwareVideoFrameTime) {
+            lock.lock()
+            let fire = armed && abs(t.presentation.seconds - trigger) < 1e-9
+            if fire { armed = false }
+            lock.unlock()
+            if fire { renderer?.enqueue(pixelBuffer: pixels, pts: SoftwareRendererReorderDepthTests.time(lateTicks)) }
+        }
+    }
+
+    @Test("A frame that arrives while another is on its way to the layer is judged against that frame")
+    @MainActor
+    func guardCoversAFrameInFlight() {
+        let renderer = SampleBufferRenderer()
+        renderer.setReorderDepth(1)
+        let handed = Handed()
+        let second = SecondEnqueuer(pixels: Self.makePixelBuffer(), trigger: 0.040, lateTicks: 20)
+        second.renderer = renderer
+        renderer.setFrameEnqueuedObserver { t in
+            handed.append(t)
+            second.frameReachedTheLayer(t)
+        }
+        let pixels = Self.makePixelBuffer()
+        // The frame at 40 ms leaves the buffer when 80 ms arrives. While it is on its way the second
+        // enqueuer offers 20 ms, which is already behind it.
+        for t in [0, 40, 80, 120] { renderer.enqueue(pixelBuffer: pixels, pts: Self.time(t)) }
+        renderer.drainReorderBuffer()
+        second.renderer = nil
+        renderer.setFrameEnqueuedObserver(nil)
+
+        #expect(renderer.outOfOrderFramesDropped == 1)
+        #expect(handed.seconds == [0, 0.040, 0.080, 0.120], "the late frame never reached the layer")
+    }
+
+    @Test("A flush while a frame is on its way does not leave the guard standing for the new timeline")
+    @MainActor
+    func flushDuringHandoverDoesNotPoisonTheGuard() {
+        let renderer = SampleBufferRenderer()
+        renderer.setReorderDepth(1)
+        let handed = Handed()
+        let pixels = Self.makePixelBuffer()
+        // A seek lands (flush) while the frame at 5040 is being handed over.
+        renderer.setFrameEnqueuedObserver { t in
+            handed.append(t)
+            if abs(t.presentation.seconds - 5.040) < 1e-9 { renderer.flush(removingDisplayedImage: false) }
+        }
+        for t in [5000, 5040, 5080] { renderer.enqueue(pixelBuffer: pixels, pts: Self.time(t)) }
+        for t in [1000, 1040, 1080] { renderer.enqueue(pixelBuffer: pixels, pts: Self.time(t)) }
+        renderer.drainReorderBuffer()
+        renderer.setFrameEnqueuedObserver(nil)
+        #expect(renderer.outOfOrderFramesDropped == 0, "the seek backwards is not out of order")
+        #expect(handed.seconds == [5.000, 5.040, 1.000, 1.040, 1.080], "and the frames after it reach the layer")
+    }
+
     @Test("A flush forgets what was handed over, so a seek backwards is not out of order")
     @MainActor
     func flushResetsTheGuard() {

From 9dcfc5e711c7c63daf2545c7de54bfecc11eb58c Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 11:59:49 +0200
Subject: [PATCH 234/359] test(ingest): measure the bounded fetch against a
 plain fetch in the same run, not a wall clock (audit NET-113)

A loaded suite stretched the absolute 1.5 s bar to 8 s per sample; the per-byte path it guards
against ran about 27x slower than session.data(for:) under any load.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../AetherEngineTests/BoundedFetchTests.swift | 20 +++++++++++--------
 1 file changed, 12 insertions(+), 8 deletions(-)

diff --git a/Tests/AetherEngineTests/BoundedFetchTests.swift b/Tests/AetherEngineTests/BoundedFetchTests.swift
index c110e7723..1fe31020d 100644
--- a/Tests/AetherEngineTests/BoundedFetchTests.swift
+++ b/Tests/AetherEngineTests/BoundedFetchTests.swift
@@ -120,18 +120,22 @@ struct BoundedFetchTests {
         defer { origin.stop() }
         let session = makeSession()
         defer { session.invalidateAndCancel() }
-        // The per-byte accumulation this replaced took 5 s for this body in a debug build. Best of three,
-        // because a suite run on a loaded machine stretches one wall-clock sample (12 s seen) while the
-        // per-byte cost would stay above the bar in every sample.
-        var best = Duration.seconds(3600)
+        // Measured against `session.data(for:)` on the same origin in the same run, not against a wall
+        // clock: a loaded suite stretched an absolute sample to 8 s, while the per-byte accumulation this
+        // replaced ran about 27x slower than the plain fetch under any load (audit NET-113).
+        var bestPlain = Duration.seconds(3600)
+        var bestBounded = Duration.seconds(3600)
         for _ in 0..<3 {
-            let started = ContinuousClock.now
+            let plainStart = ContinuousClock.now
+            let (plain, _) = try await session.data(for: request(origin))
+            bestPlain = min(bestPlain, ContinuousClock.now - plainStart)
+            #expect(plain.count == size)
+            let boundedStart = ContinuousClock.now
             let (data, _) = try await BoundedPlaylistFetch.data(for: request(origin), session: session, limit: 64 * 1024 * 1024)
-            best = min(best, ContinuousClock.now - started)
+            bestBounded = min(bestBounded, ContinuousClock.now - boundedStart)
             #expect(data.count == size)
-            if best < .seconds(1.5) { break }
         }
-        #expect(best < .seconds(1.5), "took \(best)")
+        #expect(bestBounded < bestPlain * 4 + .milliseconds(250), "bounded \(bestBounded) vs plain \(bestPlain)")
     }
 
     @Test("a segment may weigh 20 MB/s of its own duration between 32 MiB and 256 MiB")

From aca2420a7608d3d6bdb6e6419d8df8fc7348d442 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 11:59:49 +0200
Subject: [PATCH 235/359] docs(changelog): list the 2026-09-29 audit fixes
 under Unreleased

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md | 100 ++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 99 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 981b09cd4..dfe3e3c23 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,7 +10,105 @@ the public-API contract.
 
 ## [Unreleased]
 
-_Nothing yet._
+Second full audit of the engine (2026-09-29, against 7.22.2): about 107 verified defects (3 High, 35 Medium), including regressions and incomplete fixes the first audit's patches left behind. All but three performance items are fixed here, each with a regression test that failed before it; the embedded-subtitle double download (PERF-103), the byte-bounded fragment flush (PERF-105) and the audio tap readers' cost (DEC-108) need a device round or a larger redesign and are deferred.
+
+### Added
+
+- **`EngineLog.redacted(_:)`** returns a line exactly as the log handler would receive it, so a host or tool can print a URL through the same redaction funnel (audit OPS-106).
+
+### Changed
+
+- **Durations past a week are refused or clamped.** An HLS `#EXTINF` / `#EXT-X-TARGETDURATION` that is non-finite or over 7 days, or a VOD playlist summing past 7 days, fails the load with `playlistInvalid`; a container duration over 7 days is reported as 7 days (audit NET-101, HLS-102).
+- **A server that ignores HTTP Range plays forward-only.** It is detected at the response head (confirmed once with a one byte range) and played like `sequentialOrigin`: no seeking, `AVSEEK_SIZE` still answers the Content-Length. A remote disc image on such a server fails at load with `originIgnoresRange` (audit DMX-101, NET-102).
+- **Remote HLS bodies are size-capped at the response head.** Segments may weigh 20 MB per second of their `#EXTINF` (between 32 and 256 MiB), keys 64 bytes, live subtitle playlists 8 MiB and their segments 1 MiB; a non-2xx status ends the transfer (audit NET-112, FEA-107).
+- **Credential headers stay on the host's origin.** Cross-origin redirects and playlist-named hosts on the ingest, disc, relay, subtitle proxy, audio tap and live-subtitle routes no longer receive `LoadOptions.httpHeaders`. On the native bypass AVFoundation still sends them everywhere, which `docs/api.md` now states (audit NET-108, NET-109, Vcred-104).
+- **Log lines changed shape.** The local server's session token reads `/<redacted>/`, request lines omit it, tokenless requests collapse into one throttled line, and ingest / carriage-probe URL errors log `NSURLError <code> from <host>` instead of the failing URL (audit SUB-107, NET-111, NET-114).
+- **`load()` returns normally when the app backgrounds mid-load, and an audio-track switch keeps a paused session paused.** Hosts that treated a `CancellationError` from `load()` as a supersede now get a normal return followed by the background teardown (audit LIF-101, LIF-102).
+
+### Security
+
+- **A hostile HLS playlist no longer crashes the app with an infinite or huge duration.** `inf`, `nan` or values past a week in `#EXTINF` / `#EXT-X-TARGETDURATION` are refused at the parser, and a VOD playlist summing past a week is refused. Before, a live join, a live subtitle rendition or a HEVC-in-TS VOD ingest trapped on it (audit NET-101, FEA-102, HLS-102).
+- **A corrupt container duration or keyframe index can no longer crash segment planning or ask for terabytes.** Durations are clamped to a week, implausible index entries are dropped, and the plan builders fail empty instead of trapping or reserving trillions of segments (audit HLS-102).
+- **A crafted DVD subpicture no longer reserves up to 4 GiB.** Units above 1 MiB are dropped, the up-front reservation is at most 64 KiB, and fragments join in place instead of copying the partial unit each time (audit NET-104, DMX-106).
+- **Tiny laced audio packets can no longer pin gigabytes while the video gate waits.** The pre-gate audio buffer is also capped at 65,536 entries (audit SEG-102).
+- **Credential headers no longer follow a redirect to another origin on any engine session** (audit NET-108). URLSession's own redirect copies every custom header except `Authorization`, so `X-Emby-Token` and `Cookie` followed a cross-host or https-to-http 302 on the HLS ingest readers, the carriage probe, the remote disc reader, the origin relay, the subtitle proxy, the audio tap and the live rendition fetch. Every engine session now applies the #126 rule AVIOReader already applied.
+- **Allowing a relay or proxy fetch no longer grants it the host's credentials** (audit NET-109, NAT-105, DEC-103, Vcred-101). After a cross-host redirect on the #316 master, the relay anchored its grant on the edge, so the token went there and the host's own origin lost it. The #316 variant fetch, the remote-HLS audio tap and the live subtitle rendition fetch sent every host header to every host a playlist named. All of them now send credentials only to the URL the host handed over.
+- **The log redactor reads through percent escapes** (audit SUB-104, NET-114). An upstream URL carried percent-encoded inside a proxy or debrid wrapper kept its Xtream password, userinfo password or base64 token in `load url=`, `asset.url=` and URL error dumps. The ingest and carriage-probe errors now log the error code and host instead of the failing URL.
+- **A query password holding `:` `;` `,` `)` or `>` is redacted whole** (audit SUB-108). Previously the text after the first such character stayed in the log.
+- **More credential shapes are redacted** (audit SUB-109). This covers `Bearer` and `Basic` credentials, any cookie, `api-key` / `X-Api-Key`, `pwd`, `passwd`, session ids, auth, refresh and session tokens, and quoted JSON or dictionary keys. `EngineLog.registerSecret` now counts registrations.
+- **The local server's session token no longer appears in the log** (audit SUB-107). Request lines, `load url=` and `asset.url=` used to hand a live LAN capability to anyone reading a shared log.
+- **A LAN peer without the session token can no longer flood or forge the log** (audit NET-111). Its lines are throttled with a tally, and its request text is logged with control characters escaped.
+- **The first-request header dump prints header names, not values** (audit Vcred-102). On the stand-in route AVPlayer sends the host's credentials to the loopback server too.
+- **aetherctl banners print the redacted source URL** (audit OPS-106). New public `EngineLog.redacted(_:)` returns a line exactly as the log handler would receive it.
+- **The local server's exposure is documented accurately.** `SECURITY.md`, `architecture.md` and `cli.md` no longer say it is loopback-only: it binds all interfaces for AirPlay behind a per-session 128-bit path token, a 32-connection cap (24 for non-loopback peers) and a 10 s head deadline. `docs/api.md` also states that on the native bypass AVFoundation sends `LoadOptions.httpHeaders` to every host and redirect target (audit OPS-102, Vcred-104).
+- **The bridge memory telemetry no longer reads freed FFmpeg contexts** (audit DEC-104). `liveBytes` and `fifoSampleCount` read a snapshot published under the bridge lock, instead of calling `swr_get_delay` on a resampler or encoder that feed or restart may have just freed.
+- **A crafted Blu-ray or DVD image can no longer stall or exhaust memory during disc recognition** (audit NET-103). Playlists are capped at 999 PlayItems, at most 4000 `.mpls` entries and 32 MiB of playlist data are read, retained PlayItems are budgeted, and a title is cut at 65 536 extents. Clips and IFOs are found through one name index instead of a scan per item, and a DVD only groups title sets 1 to 99.
+- **The Dolby Vision record audit can no longer read a whole source looking for a frame** (audit BIT-103). The RPU walk now arms the same input byte budget the HDR10+ and Atmos probes use.
+- **HLS segments, AES keys and audio tap downloads are bounded as they arrive, not after they are fully held** (audit NET-112, NET-113, DEC-103). A non-2xx status or a declared length over the cap ends the transfer at the response head; the body accumulates in chunks and is cancelled at the cap (a segment may weigh 20 MB per second of its duration, between 32 and 256 MiB; a key 64 bytes).
+- **The live subtitle rendition loop no longer fetches, parses and merges on the main actor, and is bounded** (audit FEA-104, FEA-107, SUB-106). Ephemeral session with a 30 s resource timeout, status checked, playlists capped at 8 MiB, segments at 1 MiB and 4096 cues, non-finite or negative timestamps dropped, published list capped at 2000 cues.
+- **Hostile subtitle and playlist text no longer costs quadratic time** (audit SUB-101, SUB-110, NET-105, NAT-102). An unclosed-brace ASS cue took 2.6 s for 20k braces on the pump thread, and a 64 KiB HLS tag line with unclosed quotes took 9.6 s. Override blocks strip in one forward pass and a cue is cut at 64 KiB; attributes scan a tag line once and a line over 64 KiB is refused.
+
+### Fixed
+
+- **Seeking, thumbnails and resume positions reject NaN, infinity and huge values instead of crashing.** The Demuxer converts seconds through a checked helper and the seek fails cleanly. `FrameExtractor` returns nil, the SW and audio hosts ignore a non-finite start position, `seek(to:)` ignores a non-finite target, and the byte-estimate seek saturates at an inflated `Content-Range` total (audit DMX-113, BIT-105, DMX-103).
+- **`dvrWindowSeconds: .infinity` no longer crashes the first live manifest request.** The window is clamped to a day inside the live window sizing (audit SEG-107).
+- **A non-finite or absurd audio sample rate on the remote-HLS bypass reads as 0 instead of crashing at readyToPlay** (audit NAT-106).
+- **ASS `\pos(nan,nan)` or `PlayResX: inf` no longer publish a NaN placement.** The cue falls back to its alignment (audit SUB-112).
+- **aetherctl rejects huge or negative numeric flags with exit 64, and `pktdump` survives overflowing dts deltas** (audit OPS-110, SUB-112).
+- **Going to the background during a load no longer makes `load()` throw `CancellationError`** (audit LIF-101, LIF-105). The teardown owed since `didEnterBackground` ran when the native load passed item readiness, seconds before it returned, so the host read a supersede and left its spinner up without a start report. It now runs after `load()` returns. A PiP window closed in the background during a load or seek is torn down once it settles, instead of never.
+- **An audio-track switch on a paused session stays paused** (audit LIF-102). The same goes for every custom-source `reloadAtCurrentPosition` (audio-delay nudge, option correction), including a mount with `autoplay = false`.
+- **An audio or disc-title switch after a media services reset builds a fresh AVPlayer** (audit LIF-104).
+- **A callback from an ended session no longer reaches the next one** (audit LIF-103, Vcore-101, Vcore-102). No `.error` on a stopped engine from a late escalation, no reader stall or scrub state carried into a successor, and no stale master rejection replayed by a reused host.
+- **Cancelled or superseded loads stop waiting on a display mode switch at the next tick, and the #667 wait and the play gate share one 6 s cap** (audit LIF-106, DEC-105).
+- **An in-place item swap releases its clock hold only on the fresh item's own playback** (audit NAT-103).
+- **A load superseded during its Dolby Vision RPU audit no longer writes its geometry over its successor's** (audit LIF-107).
+- **A live channel the engine reconnects keeps playing instead of freezing on its last segment** (audit HLS-101). Only the session's first producer reported its segments to the playlist. A live reopen, a muxer-failure rebuild or the AE#222 rebuild cut new segments that the playlist never listed, so AVPlayer froze after "live reopen succeeded" until the host retuned (Sodalite) or the viewer acted (AetherPlayer). Every producer the session builds now reports into the playlist.
+- **A rate-limited source's delayed revive no longer drags a recovered session back to where it failed** (audit HLS-104). The #377 revive waited 3 to 45 s and then re-anchored whichever producer was running, usually the working one a seek or segment request had already put in. It now runs only while its dead producer is still installed and the session is unchanged.
+- **A seek that re-cuts a keyframe drought keeps the clock and captions on the picture when the re-cut opens late** (audit HLS-105). If the AE#412 re-cut took longer than the seek's 2 s wait, its mark was dropped and its backoff went into the published axis, up to one GOP off until the AE#418 reconcile. The mark now belongs to the restart that performs it.
+- **A seek burst no longer leaves a stale timeline entry or a truncated segment behind** (audit SEG-104). A producer replaced while a read was in flight could still record its gate-open epoch, or adopt its half-written segment when the aborted read came back as end of file, so a later backward seek hit a short segment. Replaced producers are now ignored, and a stopped pump drops the read it had in flight.
+- **A sequential archive with bridged audio plays to its real end** (audit SEG-103). When the last GOP crossed the last plan boundary, the audio tail flushed at end of file opened a segment the video never reached, and ENDLIST landed one segment early. The flush now follows the video cutter like the rest of the audio.
+- **A damaged keyframe at a seek or restart point is repaired like the same frame played through** (audit BIT-104). The framing verdict that lets the AE#561 sanitizer cut an overlong NAL length reset with every muxer, so the sample a restart landed on reached movenc uncut and failed with `-19602` on every retry. The verdict is now kept for the whole session.
+- **Manual DMG runs build the tag they upload to.** `release-dmg.yml` dispatched by hand checked out the dispatching branch and then signed, notarized and `--clobber`-uploaded it under the tag's name; the checkout is now pinned to the tag and the log names the built commit (audit OPS-101).
+- **`aetherctl dovitest` reads Annex-B sources and fails loudly.** The probe resolves the NAL framing once and uses it for the converter and the writer, so a disc remux is no longer reported as converted while writing one bogus NAL per packet. A full disk or a read error now ends the run with an error instead of an abort or a silent EOF, and the output is opened without following symlinks (audit BIT-106).
+- **`aetherctl` no longer leaves a new debug directory per run.** Debug artefacts go to one private per-user directory that the next run overwrites, and `dovitest` takes `--out` (audit OPS-107).
+- **`aetherctl seektest` and `smbtest` can fail.** `seektest` reads its counters under the log lock and exits 1 when a probe prints FAIL or a wedge is left unrecovered. `smbtest`'s random-seek check compares against the bytes the sequential pass saw and no longer passes when reads fail (audit OPS-104, OPS-105).
+- **The demo DMG drops two hardened-runtime exceptions.** `disable-library-validation` and `allow-unsigned-executable-memory` are gone from the notarized demo, effective at the next release build (audit OPS-112).
+- **Audio-only files and radio streams whose timestamps start late play instead of staying silent** (audit DEC-102). The audio-only host anchored its clock at the load position and ignored the first sample, so a source starting an hour in (an Ogg Icecast stream, a mid-broadcast audio TS) stamped every buffer far ahead of a clock at 0. It now anchors at the first sample, publishes position relative to it, and seeks on the source axis.
+- **Dolby Vision Profile 5 scrub thumbnails lose the green and magenta cast again** (audit BIT-102). The cache-backed still path took VideoToolbox for every title, and its P010 output skips the Dolby Vision converter. No-base-layer Dolby Vision (P5, AV1 P10.0) stays on software for stills.
+- **A second undecodable audio track on a live channel no longer re-hangs the session silently** (audit FEA-103). The AE#641 mark held one stream; it is a set now, and a repeat report is logged.
+- **A stop during a failing recording teardown reports the failure, and a start that a stop or zap overtook is cancelled** (audit FEA-105, FEA-106). `stopRecording()` used to publish `.ended` while the file was still draining and lose the `.writeTooSlow` failure. `startRecording(to:)` now throws `CancellationError` when a stop or a new load lands during its wait for the previous file.
+- **Full-range and 10-bit SDR software-decoded video show correctly** (audit DEC-107). The software decoder now reads `color_range` and the frame's bit depth, so full-range AV1 / VP9 / HEVC is no longer crushed and 10-bit SDR AV1 / VP9 is no longer dithered to 8 bit.
+- **A seek, a DVR rewind or a renderer self-flush no longer leaves audio stuck** (audit DEC-106). `AudioOutput.flush()` retires an epoch, and the FFmpeg hosts, including the DVR ring path, enqueue only if it is unchanged. The AE#549 auto-flush runs off the posting thread, so a renderer that posts from inside `enqueue` cannot hang the feed.
+- **An injected subtitle rendition is matched by its playlist identity** (audit NAT-104). An origin rendition whose localized display name equalled the sidecar's NAME could be selected instead.
+- **The Atmos confirmation pass closes the reader fork it only tests for nil** (audit DEC-109).
+- **A server that ignores HTTP Range now plays to the end instead of stopping at 32 MB, including when the first request was refused or slow** (audit DMX-101). The response head is judged on the cold open and again on the connection that follows the size probe, so a 429/503 or slow first answer no longer hides the origin. A range-ignoring 200 is confirmed once with a one byte range, then plays forward-only (no seeking), still reporting its Content-Length so MPEG-TS duration estimation works. Origins that honour Range, and small files answered with a 200, are unchanged. A CDN that only fills its cache while a client downloads it can read as range-ignoring and then plays forward-only.
+- **A remote disc image on a server that ignores Range now fails at once with a named cause** (audit NET-102). The disc reader judged range answers only after downloading the whole body. It now decides at the response head and hangs up, and the load throws `originIgnoresRange`. A 206 wider than asked is cut where the range ends.
+- **A forward-only source whose transport ignores the pause now ends with a named cause** (audit DMX-107). Reaching the 128 MB hard cap reports `AVIOReaderError.originIgnoresFlowControl` through `lastReadFailure` and the log, instead of a bare EIO that looked like a dropped connection.
+- **A detour block fetch no longer takes two origin slots** (audit DMX-105). On an origin limited to two requests with the pump holding one, each detour block waited 4 s for its own second slot.
+- **A malformed chunked response on the held connection ends the connection instead of growing without bound** (audit DMX-111). A size or trailer line over 4 KiB, or 64 KiB of framing with no body byte, now throws. Opt-in `heldSourceConnection` path.
+- **A forward-only source keeps its opening GOP** (audit HLS-103). The NAL framing probe and the in-band hvcC scan used to seek to 0 and consume packets; libavformat flushes its queue before it tries a seek, so a range-less archive lost its first GOP. The demuxer now holds the packets those probes look at and hands them to the producer, and refuses repositions on a source that cannot rewind.
+- **A remote disc image session is released when the demuxer closes** (audit NET-110, DMX-110). The disc reader the demuxer built for a remote ISO stayed open on close, on a failed open and on an unparseable structure.
+- **Closing a demuxer cancels an open that is still connecting, a read on a local path, and a pump waiting for its origin slot** (audit DMX-102, DMX-109, DMX-112). `markClosed()` now reaches those stages instead of waiting out the origin's slot or pacer timeout.
+- **A stop no longer looks like the end of the source** (audit SEG-104). A read aborted by the demuxer close now reports `AVERROR_EXIT` and the hosts treat it as the stop arriving; tail adoption, bridge flush and `onSequentialSourceEnded` no longer fire from a teardown.
+- **Track and stream accessors no longer read libavformat's live streams array** (audit DMX-108). They answer from a snapshot, and `close()` waits for callers inside `withStream(at:)`, closing a use-after-free window during a live reopen.
+- **Unfinished PGS display sets count toward the subtitle store's memory cap** (audit SUB-111). A stream that never sends an END segment can no longer escape the aggregate cap; one set is capped at 4 MiB instead of 16.
+- **A full volume no longer freezes a software live channel** (audit VPERF-101). The ring used to evict only after a successful write; it now frees its oldest chunk on a failed write (full disk or quota) and retries.
+- **The segment cache's stale sweep no longer deletes a live DVR ring an hour into a session** (audit SEG-105). The ring holds the same flock marker as the cache.
+- **One stalled relay consumer no longer blocks every other relayed fetch** (audit NET-107). A fetch that falls more than 32 MiB behind is cancelled and re-requested.
+
+### Performance
+
+- **`playlistShiftSeconds` is published only when it changes**, so the engine's `objectWillChange` no longer fires at 10 Hz (audit PERF-106).
+- **Forward-only playback no longer copies the whole read-ahead buffer on every read** (audit PERF-102, DMX-104). The streaming buffer is chunked, so a read copies only what it returns. 200 reads against a 60 MB buffer went from 329 ms to 5.7 ms on a debug build.
+- **Idle scrub detour blocks are released after 30 s** (audit PERF-108). Previously they stayed resident until close, up to 32 MB per reader.
+- **The subtitle packet store appends in place** (audit SUB-103, PERF-107). 40k appends took 10.9 s because every append copied each retained packet.
+- **HLS program dates parse without building two formatters per line** (audit NET-106).
+- **Playlist bodies accumulate in chunks** (audit NET-113). 32 MiB took 5 s in a debug build and takes 0.14 s now.
+- **The software live DVR ring no longer costs a file and a heap object per packet** (audit PERF-101, SEG-106). It spools into ~4 MB chunk files behind a flat 24-byte index (266 MB of index heap at 100k packets is now 4 MB, appends 314 us to 28-45 us) and is bounded by bytes as well as time (min(2 GiB, a quarter of free space), at least 64 MiB). The software live seekable range follows what the ring still holds.
+- **Software video holds one frame for reordering instead of four** (audit PERF-104). Only the VideoToolbox HEVC decoder emits out of presentation order, so libavcodec and dav1d output skips three dead frames (75 MB of IOSurface at 4K P010). A late frame is dropped, not shown out of order, and raises the depth to 4 for that renderer.
+- **The software demux loop no longer wakes 200 times a second while parked** (audit PERF-110). It waits on its condition for 5 to 20 ms.
+- **The software VOD packet spool writes a record with one `writev` and reads it without intermediate copies** (audit PERF-109). A 208 KB packet round trip went from about 800 us to about 380 us on the dev Mac.
+- **Dolby Vision profile 7 to 8.1 rebuilds a packet with one copy instead of two** (audit PERF-111).
 
 ## [7.22.2] - 2026-09-29
 

From 8ac93f9cf1afdaeaefd94f67efb66ab602d4dbb3 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 13:30:42 +0200
Subject: [PATCH 236/359] test(live): type the WebVTT timestamp expectations
 apart so Swift 6.2 can check them in time

CI's Xcode 26.3 lane failed with "unable to type-check this expression in reasonable time" on the
literal sum inside #expect; Xcode 27 accepted it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../LiveSubtitleRenditionHardeningTests.swift             | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/Tests/AetherEngineTests/LiveSubtitleRenditionHardeningTests.swift b/Tests/AetherEngineTests/LiveSubtitleRenditionHardeningTests.swift
index 0be91a740..d8e0e3ae9 100644
--- a/Tests/AetherEngineTests/LiveSubtitleRenditionHardeningTests.swift
+++ b/Tests/AetherEngineTests/LiveSubtitleRenditionHardeningTests.swift
@@ -151,8 +151,12 @@ struct LiveSubtitleRenditionHardeningTests {
         short form
         """)))
         #expect(parsed.cues.count == 2)
-        #expect(abs(parsed.cues[0].start - (164 * 3600 + 4 * 60 + 24)) < 0.001)
-        #expect(abs(parsed.cues[1].start - 62.5) < 0.001)
+        // Typed apart: Swift 6.2 cannot type-check the literal sum inside the macro in time.
+        let longClock: Double = 164 * 3600 + 4 * 60 + 24
+        let longClockError: Double = abs(parsed.cues[0].start - longClock)
+        let shortFormError: Double = abs(parsed.cues[1].start - 62.5)
+        #expect(longClockError < 0.001)
+        #expect(shortFormError < 0.001)
     }
 
     @Test("a segment holds at most 4096 cues")

From 25c7a5ce7c2ca1f5b5bdea43c1359510417d720f Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 14:57:44 +0200
Subject: [PATCH 237/359] test(core): serialize the suites that park a load's
 reader on the cooperative pool

BackgroundDecisionWaitsForLoadTests and the new SoftwarePathEscalationTests cases (audit LIF-101,
LIF-103) hold a load by parking its custom reader, and AetherEngine.loadSession runs Demuxer.open on
a cooperative-pool thread. In parallel they filled CI's four-thread pool; the test's own release
needs a pool thread, so the swift-testing process stalled for about 100 s and unrelated network
tests ran out their time limits (main runs 36708996743 attempts 1 and 2). Sampled during the stall
on a diagnostic PR (#672): all pool threads sat in ParkedReader / HeldDataReader.read. With both
suites serialized the same job passed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../BackgroundDecisionWaitsForLoadTests.swift                | 5 ++++-
 Tests/AetherEngineTests/SoftwarePathEscalationTests.swift    | 4 +++-
 2 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/Tests/AetherEngineTests/BackgroundDecisionWaitsForLoadTests.swift b/Tests/AetherEngineTests/BackgroundDecisionWaitsForLoadTests.swift
index 7b16d1c1e..ddf7ac0b8 100644
--- a/Tests/AetherEngineTests/BackgroundDecisionWaitsForLoadTests.swift
+++ b/Tests/AetherEngineTests/BackgroundDecisionWaitsForLoadTests.swift
@@ -10,7 +10,10 @@ import Testing
 ///
 /// The lifecycle itself is iOS / tvOS only; the owed funnel is not, so these drive it through
 /// `noteDidEnterBackground()` and a policy seam that performs the same synchronous teardown.
-@Suite("A background decision owed during a load waits for the load to return", .timeLimit(.minutes(2)))
+// Serialized: each test parks a load's reader on a cooperative-pool thread until the test releases
+// it, and the release itself needs a pool thread. Run in parallel, these filled CI's four-thread
+// pool and stalled the whole swift-testing process for about 100 s.
+@Suite("A background decision owed during a load waits for the load to return", .serialized, .timeLimit(.minutes(2)))
 @MainActor
 struct BackgroundDecisionWaitsForLoadTests {
 
diff --git a/Tests/AetherEngineTests/SoftwarePathEscalationTests.swift b/Tests/AetherEngineTests/SoftwarePathEscalationTests.swift
index 4453115d6..4056969c1 100644
--- a/Tests/AetherEngineTests/SoftwarePathEscalationTests.swift
+++ b/Tests/AetherEngineTests/SoftwarePathEscalationTests.swift
@@ -7,7 +7,9 @@ import Foundation
 import Testing
 @testable import AetherEngine
 
-@Suite("Software-path escalation (AE#561)")
+// Serialized: several tests park a load's reader on a cooperative-pool thread until the test
+// releases it, and the release itself needs a pool thread (see BackgroundDecisionWaitsForLoadTests).
+@Suite("Software-path escalation (AE#561)", .serialized)
 struct SoftwarePathEscalationTests {
 
     private static func availability(

From ab2002365597a042545a43e725e888c3a7ea5a2d Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 15:23:05 +0200
Subject: [PATCH 238/359] test(support): capture engine log lines through one
 fan-out instead of swapping the global handler

EngineLog.handler is one process-global closure and swift-testing runs
suites in parallel. Eight tests captured lines by replacing it and putting
back the value they had found, so when two overlapped, the one that
restored last reinstated a stale handler and silently disconnected the
other's sink. On the few-core CI runner this left the #450 witness test
("a connection with no first byte is reported before the threshold ends
it") with no lines in three runs.

EngineLogCapture installs one forwarder the first time a capture exists
and fans every line out to the captures alive at that moment, so no test
assigns the handler any more. All eight sites in seven files use it; each
keeps filtering by its own marker. The #450 test now filters by its
reader's own label and waits for its line without a deadline of its own
(the .timeLimit trait is the hang catcher). EngineLogCaptureTests pins
that ending one capture leaves an overlapping one connected.

Nothing in the engine branches on the handler being set (deliver only
calls it optionally), and no test relied on it being nil.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../EngineLogCaptureTests.swift               | 24 ++++++
 .../HLSLocalServerSessionTokenTests.swift     | 28 +------
 .../HLSLocalServerSlowPeerTests.swift         | 32 +-------
 .../Issue374FirstServeAccountTests.swift      | 38 ++--------
 .../Issue377FoldWitnessTests.swift            | 30 +-------
 .../Issue377ReaderTransportLogTests.swift     | 31 +-------
 ...Issue450ConcurrentReaderCeilingTests.swift | 35 ++-------
 .../AetherEngineTests/LogRedactionTests.swift | 31 ++------
 .../Support/EngineLogCapture.swift            | 76 +++++++++++++++++++
 9 files changed, 131 insertions(+), 194 deletions(-)
 create mode 100644 Tests/AetherEngineTests/EngineLogCaptureTests.swift
 create mode 100644 Tests/AetherEngineTests/Support/EngineLogCapture.swift

diff --git a/Tests/AetherEngineTests/EngineLogCaptureTests.swift b/Tests/AetherEngineTests/EngineLogCaptureTests.swift
new file mode 100644
index 000000000..ded7ac650
--- /dev/null
+++ b/Tests/AetherEngineTests/EngineLogCaptureTests.swift
@@ -0,0 +1,24 @@
+import Foundation
+import Testing
+@testable import AetherEngine
+
+/// The property the capture exists for: two tests listening at once do not disconnect each other.
+/// Swapping the global handler failed it, since whichever test restored last put back a stale one.
+@Suite("Engine log capture")
+struct EngineLogCaptureTests {
+
+    @Test("ending one capture leaves an overlapping one connected")
+    func endingOneLeavesTheOtherConnected() {
+        let marker = "capture-\(UUID().uuidString)"
+        let first = EngineLogCapture()
+        let second = EngineLogCapture()
+        defer { second.end() }
+
+        EngineLog.emit("\(marker) before")
+        first.end()
+        EngineLog.emit("\(marker) after")
+
+        #expect(first.matching(marker).count == 1)
+        #expect(second.matching(marker).count == 2)
+    }
+}
diff --git a/Tests/AetherEngineTests/HLSLocalServerSessionTokenTests.swift b/Tests/AetherEngineTests/HLSLocalServerSessionTokenTests.swift
index 789b434c1..5c7072d7e 100644
--- a/Tests/AetherEngineTests/HLSLocalServerSessionTokenTests.swift
+++ b/Tests/AetherEngineTests/HLSLocalServerSessionTokenTests.swift
@@ -117,8 +117,8 @@ struct HLSLocalServerSessionTokenTests {
     /// the once-per-session header dump printed whatever credential the host passed.
     @Test("The first-request header dump names a credential header but never prints its value")
     func headerDumpOmitsCredentialValues() throws {
-        let tap = HeaderLineTap()
-        defer { tap.restore() }
+        let tap = EngineLogCapture()
+        defer { tap.end() }
         let server = HLSLocalServer(provider: StubProvider())
         try server.start()
         defer { server.stop() }
@@ -193,27 +193,3 @@ private final class StubProvider: HLSSegmentProvider, @unchecked Sendable {
     func segmentDuration(at index: Int) -> Double { 4.0 }
     var playlistType: HLSPlaylistType { .vod }
 }
-
-/// Captures `EngineLog` lines for one test; the handler is global, so it is restored on every path.
-private final class HeaderLineTap: @unchecked Sendable {
-    private let lock = NSLock()
-    private var captured: [String] = []
-    private let previous: ((String) -> Void)?
-
-    init() {
-        previous = EngineLog.handler
-        EngineLog.handler = { [self] line in
-            lock.lock()
-            captured.append(line)
-            lock.unlock()
-        }
-    }
-
-    func restore() { EngineLog.handler = previous }
-
-    var lines: [String] {
-        lock.lock()
-        defer { lock.unlock() }
-        return captured
-    }
-}
diff --git a/Tests/AetherEngineTests/HLSLocalServerSlowPeerTests.swift b/Tests/AetherEngineTests/HLSLocalServerSlowPeerTests.swift
index 59370639f..d3602371b 100644
--- a/Tests/AetherEngineTests/HLSLocalServerSlowPeerTests.swift
+++ b/Tests/AetherEngineTests/HLSLocalServerSlowPeerTests.swift
@@ -84,8 +84,8 @@ struct HLSLocalServerSlowPeerTests {
 
     @Test("The stop line names the port that was released")
     func stopLineNamesThePort() throws {
-        let tap = LineTap()
-        defer { tap.restore() }
+        let tap = EngineLogCapture()
+        defer { tap.end() }
         let server = HLSLocalServer(provider: StubProvider())
         try server.start()
         let port = server.port
@@ -98,8 +98,8 @@ struct HLSLocalServerSlowPeerTests {
     /// peer looping short connections could scroll a 300-line ring in a fraction of a second.
     @Test("A flood of tokenless requests costs the log a handful of lines")
     func tokenlessFloodIsThrottled() async throws {
-        let tap = LineTap()
-        defer { tap.restore() }
+        let tap = EngineLogCapture()
+        defer { tap.end() }
         let server = HLSLocalServer(provider: StubProvider())
         try server.start()
         defer { server.stop() }
@@ -237,30 +237,6 @@ private final class Trickle: @unchecked Sendable {
     }
 }
 
-/// Captures `EngineLog` lines for one test; the handler is global, so it is restored on every path.
-private final class LineTap: @unchecked Sendable {
-    private let lock = NSLock()
-    private var lines: [String] = []
-    private let previous: ((String) -> Void)?
-
-    init() {
-        previous = EngineLog.handler
-        EngineLog.handler = { [self] line in
-            lock.lock()
-            lines.append(line)
-            lock.unlock()
-        }
-    }
-
-    func restore() { EngineLog.handler = previous }
-
-    func matching(_ needle: String) -> [String] {
-        lock.lock()
-        defer { lock.unlock() }
-        return lines.filter { $0.contains(needle) }
-    }
-}
-
 private final class StubProvider: HLSSegmentProvider, @unchecked Sendable {
     func initSegment() -> Data? { Data([0x00]) }
     func mediaSegment(at index: Int) -> Data? { Data([0x00]) }
diff --git a/Tests/AetherEngineTests/Issue374FirstServeAccountTests.swift b/Tests/AetherEngineTests/Issue374FirstServeAccountTests.swift
index ce1e9b4e8..456bbcf31 100644
--- a/Tests/AetherEngineTests/Issue374FirstServeAccountTests.swift
+++ b/Tests/AetherEngineTests/Issue374FirstServeAccountTests.swift
@@ -25,32 +25,6 @@ private final class Issue374WaitResult: @unchecked Sendable {
     }
 }
 
-/// Captures `EngineLog` lines for the duration of one test. The handler is global, so it is restored in
-/// every path rather than at the end of the happy one.
-private final class Issue374LogTap: @unchecked Sendable {
-    private let lock = NSLock()
-    private var lines: [String] = []
-    private let previous: ((String) -> Void)?
-
-    init() {
-        previous = EngineLog.handler
-        let sink = { [self] (line: String) in
-            lock.lock()
-            lines.append(line)
-            lock.unlock()
-        }
-        EngineLog.handler = sink
-    }
-
-    func restore() { EngineLog.handler = previous }
-
-    func matching(_ needle: String) -> [String] {
-        lock.lock()
-        defer { lock.unlock() }
-        return lines.filter { $0.contains(needle) }
-    }
-}
-
 final class Issue374FirstServeAccountTests: XCTestCase {
 
     // MARK: The account line
@@ -148,8 +122,8 @@ final class Issue374FirstServeAccountTests: XCTestCase {
     func testSatisfiedGateAccountsForItsWaitExactlyOnceAcrossRepeatedRequests() {
         let (provider, cache) = makeProvider(allowsBoundedDegradedStart: false)
         defer { cache.close() }
-        let tap = Issue374LogTap()
-        defer { tap.restore() }
+        let tap = EngineLogCapture()
+        defer { tap.end() }
 
         for index in 0..<15 {
             append(provider, index: index)
@@ -168,8 +142,8 @@ final class Issue374FirstServeAccountTests: XCTestCase {
     func testBoundedFastZapStartNamesTheWholeWaitAndNotOnlyItsGrace() {
         let (provider, cache) = makeProvider(allowsBoundedDegradedStart: true)
         defer { cache.close() }
-        let tap = Issue374LogTap()
-        defer { tap.restore() }
+        let tap = EngineLogCapture()
+        defer { tap.end() }
 
         let result = Issue374WaitResult()
         let finished = expectation(description: "startup waiter finished")
@@ -200,8 +174,8 @@ final class Issue374FirstServeAccountTests: XCTestCase {
     func testAGateThatNeverCutASegmentSaysSoRatherThanReturningInSilence() {
         let (provider, cache) = makeProvider(allowsBoundedDegradedStart: false)
         defer { cache.close() }
-        let tap = Issue374LogTap()
-        defer { tap.restore() }
+        let tap = EngineLogCapture()
+        defer { tap.end() }
 
         XCTAssertFalse(provider.waitForFirstLiveSegment(timeout: 0.2))
 
diff --git a/Tests/AetherEngineTests/Issue377FoldWitnessTests.swift b/Tests/AetherEngineTests/Issue377FoldWitnessTests.swift
index c1d70a162..629fb0571 100644
--- a/Tests/AetherEngineTests/Issue377FoldWitnessTests.swift
+++ b/Tests/AetherEngineTests/Issue377FoldWitnessTests.swift
@@ -10,45 +10,21 @@
 import XCTest
 @testable import AetherEngine
 
-private final class Issue377FoldLogTap: @unchecked Sendable {
-    private let lock = NSLock()
-    private var lines: [String] = []
-    private let previous: ((String) -> Void)?
-
-    init() {
-        previous = EngineLog.handler
-        let sink = { [self] (line: String) in
-            lock.lock()
-            lines.append(line)
-            lock.unlock()
-        }
-        EngineLog.handler = sink
-    }
-
-    func restore() { EngineLog.handler = previous }
-
-    func matching(_ needle: String) -> [String] {
-        lock.lock()
-        defer { lock.unlock() }
-        return lines.filter { $0.contains(needle) }
-    }
-}
-
 final class Issue377FoldWitnessTests: XCTestCase {
 
     private let source = URL(string: "https://proxy.example.dev/stream/abc?token=one")!
     private let target = URL(string: "https://nexus-097.cdn.example.st/file.mkv?sig=aaa")!
 
-    private var tap: Issue377FoldLogTap!
+    private var tap: EngineLogCapture!
 
     override func setUp() {
         super.setUp()
         OriginRequestBudget.shared.resetForTesting()
-        tap = Issue377FoldLogTap()
+        tap = EngineLogCapture()
     }
 
     override func tearDown() {
-        tap.restore()
+        tap.end()
         tap = nil
         OriginRequestBudget.shared.resetForTesting()
         super.tearDown()
diff --git a/Tests/AetherEngineTests/Issue377ReaderTransportLogTests.swift b/Tests/AetherEngineTests/Issue377ReaderTransportLogTests.swift
index b37d7a76f..01e612797 100644
--- a/Tests/AetherEngineTests/Issue377ReaderTransportLogTests.swift
+++ b/Tests/AetherEngineTests/Issue377ReaderTransportLogTests.swift
@@ -8,43 +8,18 @@
 import XCTest
 @testable import AetherEngine
 
-/// Captures `EngineLog` lines for one test. The handler is global, so it is restored on every path.
-private final class Issue377LogTap: @unchecked Sendable {
-    private let lock = NSLock()
-    private var lines: [String] = []
-    private let previous: ((String) -> Void)?
-
-    init() {
-        previous = EngineLog.handler
-        let sink = { [self] (line: String) in
-            lock.lock()
-            lines.append(line)
-            lock.unlock()
-        }
-        EngineLog.handler = sink
-    }
-
-    func restore() { EngineLog.handler = previous }
-
-    func matching(_ needle: String) -> [String] {
-        lock.lock()
-        defer { lock.unlock() }
-        return lines.filter { $0.contains(needle) }
-    }
-}
-
 final class Issue377ReaderTransportLogTests: XCTestCase {
 
-    private var tap: Issue377LogTap!
+    private var tap: EngineLogCapture!
 
     override func setUp() {
         super.setUp()
         ReaderTransportLog.resetForTesting()
-        tap = Issue377LogTap()
+        tap = EngineLogCapture()
     }
 
     override func tearDown() {
-        tap.restore()
+        tap.end()
         tap = nil
         ReaderTransportLog.resetForTesting()
         super.tearDown()
diff --git a/Tests/AetherEngineTests/Issue450ConcurrentReaderCeilingTests.swift b/Tests/AetherEngineTests/Issue450ConcurrentReaderCeilingTests.swift
index ceca5f736..69b9967f3 100644
--- a/Tests/AetherEngineTests/Issue450ConcurrentReaderCeilingTests.swift
+++ b/Tests/AetherEngineTests/Issue450ConcurrentReaderCeilingTests.swift
@@ -69,29 +69,6 @@ struct Issue450ConcurrentReaderCeilingTests {
         }
     }
 
-    /// `EngineLog.handler` is process-global and swift-testing runs suites in parallel, so this
-    /// collects whatever else is logging at the same time. It only ever filters, never counts a
-    /// total, so a foreign line cannot change a verdict here.
-    private final class LogSink: @unchecked Sendable {
-        private let lock = NSLock()
-        private var lines: [String] = []
-        private let previous: ((String) -> Void)?
-        init() {
-            previous = EngineLog.handler
-            let sink = { [self] (line: String) in
-                lock.lock()
-                lines.append(line)
-                lock.unlock()
-            }
-            EngineLog.handler = sink
-        }
-        func restore() { EngineLog.handler = previous }
-        func matching(_ needle: String) -> [String] {
-            lock.lock(); defer { lock.unlock() }
-            return lines.filter { $0.contains(needle) }
-        }
-    }
-
     // MARK: - The transport contract the reader pools are built on
 
     /// The negative control. Without it the test below could pass for a reason that has nothing to
@@ -190,10 +167,12 @@ struct Issue450ConcurrentReaderCeilingTests {
         let server = try #require(serverMaybe)
         defer { server.stop() }
 
-        let sink = LogSink()
-        defer { sink.restore() }
+        let sink = EngineLogCapture()
+        defer { sink.end() }
 
+        let label = "silent-\(UUID().uuidString)"
         let reader = AVIOReader(url: URL(string: "http://127.0.0.1:\(server.port)/movie.bin")!,
+                                label: label,
                                 boundedInitialFetch: firstRange,
                                 connStallTimeout: stallTimeout)
         defer { reader.markClosed(); reader.close() }
@@ -203,9 +182,11 @@ struct Issue450ConcurrentReaderCeilingTests {
         // refill is the generation that receives headers and no body.
         try await waitFor(upTo: .seconds(10)) { !reader.hasLiveConnectionForTesting }
         #expect(Self.read(reader, bytes: 512 * 1024, deadline: 10) == 512 * 1024)
-        try await waitFor(upTo: .seconds(10)) { !sink.matching("no first byte after").isEmpty }
+        // The capture sees every reader in the process, so the reader's own label picks its line.
+        func reported() -> [String] { sink.matching(label).filter { $0.contains("no first byte after") } }
+        try await waitFor { !reported().isEmpty }
 
-        let lines = sink.matching("no first byte after")
+        let lines = reported()
         #expect(!lines.isEmpty, "a generation that received headers and no body was never reported")
         // The two facts that separate a parked request from an origin sitting on one. Without them
         // the line names the silence but not the side it is on.
diff --git a/Tests/AetherEngineTests/LogRedactionTests.swift b/Tests/AetherEngineTests/LogRedactionTests.swift
index ed18579e4..5f370172d 100644
--- a/Tests/AetherEngineTests/LogRedactionTests.swift
+++ b/Tests/AetherEngineTests/LogRedactionTests.swift
@@ -6,8 +6,7 @@ import Testing
 /// the access token in that same query, and `EngineLog` emits with `.public` privacy into OSLog plus
 /// whatever handler the host installed, so an unredacted line is a live credential in a Console.app
 /// capture, a sysdiagnose, and every in-app log a host builds on the handler.
-/// Serialized: `EngineLog.handler` is process-global, so two of these running at once would
-/// each install over the other and read an empty capture.
+/// Serialized: the secret-registry tests mutate process-global redaction state.
 @Suite("EngineLog credential stripping", .serialized)
 struct LogRedactionTests {
 
@@ -395,10 +394,8 @@ struct LogRedactionTests {
     /// must never see the raw token, whether or not that host scrubs its own log.
     @Test("the host handler receives the redacted line")
     func handlerSeesRedactedLine() {
-        let box = LineBox()
-        let previous = EngineLog.handler
-        EngineLog.handler = { box.append($0) }
-        defer { EngineLog.handler = previous }
+        let box = EngineLogCapture()
+        defer { box.end() }
 
         EngineLog.emit("[test-496a] load url=https://s/v?api_key=\(token)&Static=true", category: .engine)
 
@@ -415,10 +412,8 @@ struct LogRedactionTests {
     /// shared funnel and not on the `.info` branch alone.
     @Test("a verbose line is withheld from the handler")
     func verboseSkipsTheHandler() {
-        let box = LineBox()
-        let previous = EngineLog.handler
-        EngineLog.handler = { box.append($0) }
-        defer { EngineLog.handler = previous }
+        let box = EngineLogCapture()
+        defer { box.end() }
 
         EngineLog.emit("[test-496b] per-segment trace api_key=\(token)", category: .session, level: .verbose)
 
@@ -426,20 +421,4 @@ struct LogRedactionTests {
         // an unrelated AVIOReader line from a parallel suite, which says nothing about `.verbose`.
         #expect(box.lines.filter { $0.contains("[test-496b]") }.isEmpty)
     }
-
-    /// The handler is called on whatever thread emitted, so the capture needs its own lock.
-    private final class LineBox: @unchecked Sendable {
-        private let lock = NSLock()
-        private var storage: [String] = []
-
-        func append(_ line: String) {
-            lock.lock(); defer { lock.unlock() }
-            storage.append(line)
-        }
-
-        var lines: [String] {
-            lock.lock(); defer { lock.unlock() }
-            return storage
-        }
-    }
 }
diff --git a/Tests/AetherEngineTests/Support/EngineLogCapture.swift b/Tests/AetherEngineTests/Support/EngineLogCapture.swift
new file mode 100644
index 000000000..716d9e796
--- /dev/null
+++ b/Tests/AetherEngineTests/Support/EngineLogCapture.swift
@@ -0,0 +1,76 @@
+import Foundation
+@testable import AetherEngine
+
+/// Collects `EngineLog` lines for one test.
+///
+/// `EngineLog.handler` is one process-global closure and swift-testing runs suites in parallel. A
+/// test that replaced it and later put back the value it had found could restore a stale closure
+/// while another test was still listening, and that test then read an empty capture (three red CI
+/// runs of the #450 witness, none of them reproducible on a Mac with cores to spare). So no test
+/// assigns the handler any more: one forwarder is installed the first time a capture is made and
+/// fans every line out to the captures alive at that moment.
+///
+/// Every capture therefore sees the lines of every test that logs at the same time. Filter by a
+/// marker that belongs to the test, never count totals.
+///
+/// Create one, read `lines` / `matching(_:)`, and `end()` it in a `defer` (an XCTest case does so
+/// in `tearDown`). Lines emitted after `end()` are not collected; the ones already collected stay
+/// readable.
+final class EngineLogCapture: @unchecked Sendable {
+    private let lock = NSLock()
+    private var storage: [String] = []
+
+    init() {
+        Registry.shared.add(self)
+    }
+
+    func end() {
+        Registry.shared.remove(self)
+    }
+
+    var lines: [String] {
+        lock.lock(); defer { lock.unlock() }
+        return storage
+    }
+
+    func matching(_ needle: String) -> [String] {
+        lock.lock(); defer { lock.unlock() }
+        return storage.filter { $0.contains(needle) }
+    }
+
+    fileprivate func append(_ line: String) {
+        lock.lock(); defer { lock.unlock() }
+        storage.append(line)
+    }
+
+    /// The handler stays installed for the rest of the process once the first capture exists, which
+    /// is harmless: nothing in the engine branches on it being set, and with no capture registered
+    /// the forwarder does nothing.
+    private final class Registry: @unchecked Sendable {
+        static let shared: Registry = {
+            let registry = Registry()
+            EngineLog.handler = { registry.forward($0) }
+            return registry
+        }()
+
+        private let lock = NSLock()
+        private var captures: [ObjectIdentifier: EngineLogCapture] = [:]
+
+        func add(_ capture: EngineLogCapture) {
+            lock.lock(); defer { lock.unlock() }
+            captures[ObjectIdentifier(capture)] = capture
+        }
+
+        func remove(_ capture: EngineLogCapture) {
+            lock.lock(); defer { lock.unlock() }
+            captures[ObjectIdentifier(capture)] = nil
+        }
+
+        func forward(_ line: String) {
+            lock.lock()
+            let live = Array(captures.values)
+            lock.unlock()
+            for capture in live { capture.append(line) }
+        }
+    }
+}

From c7d257a227fafda3ffe7ab9f312df998712a2095 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 15:23:05 +0200
Subject: [PATCH 239/359] test(demuxer): the trim test reads until a chunk is
 released instead of a fixed count

The test read a fixed 8 x 262000 bytes and then expected the chunk count
to have dropped. A chunk is only released once the read position is a
lookback past its end, and URLSession delivers larger chunks on the CI
runner, so 2 MB of reads could pass without releasing one although the
trim was correct.

It now takes the chunk addresses while everything is resident and nothing
is consumed, then reads until the count drops, bounded by the 6 MiB body.
If the body ends first nothing was released and the test still fails. The
kept-chunks-are-the-same-addresses check is unchanged and now covers every
read up to the first release.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../StreamingBufferTrimTests.swift            | 21 ++++++++++---------
 1 file changed, 11 insertions(+), 10 deletions(-)

diff --git a/Tests/AetherEngineTests/StreamingBufferTrimTests.swift b/Tests/AetherEngineTests/StreamingBufferTrimTests.swift
index 3869ae1cd..22c970bf3 100644
--- a/Tests/AetherEngineTests/StreamingBufferTrimTests.swift
+++ b/Tests/AetherEngineTests/StreamingBufferTrimTests.swift
@@ -57,25 +57,26 @@ struct StreamingBufferTrimTests {
         try reader.open()
         try await waitFor { reader.streamPeakBufferBytesForTesting >= total }
 
+        // Everything is resident and nothing consumed yet, so this is every chunk the body arrived in.
+        let before = reader.streamChunkAddressesForTesting
+        #expect(before.count > 1, "the body arrived as one chunk, so this could not tell a copy from a slice")
+
         let chunk = 262_000
         let buf = UnsafeMutablePointer<UInt8>.allocate(capacity: chunk)
         defer { buf.deallocate() }
-        // Past the 1 MB lookback, so every later read trims.
+        // A chunk is released once the read position is a lookback past its end, and how large
+        // URLSession makes the chunks is not this test's to know (larger on a CI runner), so read
+        // until one goes. The body is the bound: if it ends first, nothing was released and that fails.
         var read = 0
-        while read < 2 * 1024 * 1024 {
+        var after = before
+        while after.count >= before.count, read < total {
             let n = Int(reader.read(into: buf, size: Int32(chunk)))
             #expect(n > 0)
             if n <= 0 { return }
             read += n
+            after = reader.streamChunkAddressesForTesting
         }
-        let before = reader.streamChunkAddressesForTesting
-        #expect(before.count > 1, "the body arrived as one chunk, so this could not tell a copy from a slice")
-
-        for _ in 0..<8 {
-            #expect(reader.read(into: buf, size: Int32(chunk)) > 0)
-        }
-        let after = reader.streamChunkAddressesForTesting
-        #expect(after.count < before.count, "the trim released nothing")
+        #expect(after.count < before.count, "the trim released nothing before the body ended")
         #expect(after.count > 1)
         #expect(Array(before.suffix(after.count)) == after,
                 "a trim reallocated the chunks it kept: the buffer was copied, not sliced")

From 4f2406bc82f523745862407ff05ce0c6ab10f19b Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 15:52:06 +0200
Subject: [PATCH 240/359] test(demuxer): the detour ticket test witnesses the
 pump on the link, not a wall clock

The 2 s bound on the detour read measured 2.0 to 2.3 s on a loaded CI runner for a correct detour.
Reverting 0fd16c57 still fails the test through hasLiveConnectionForTesting: the second ticket waits
out its 4 s budget and the pump's range ends meanwhile.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 Tests/AetherEngineTests/DetourOriginTicketTests.swift | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/Tests/AetherEngineTests/DetourOriginTicketTests.swift b/Tests/AetherEngineTests/DetourOriginTicketTests.swift
index 957e8ce23..e219b99c2 100644
--- a/Tests/AetherEngineTests/DetourOriginTicketTests.swift
+++ b/Tests/AetherEngineTests/DetourOriginTicketTests.swift
@@ -42,12 +42,13 @@ struct DetourOriginTicketTests {
         // that opens the detour block holding 4 to 8 MB.
         let target = Int64(5 * 1024 * 1024)
         #expect(reader.seek(offset: target, whence: Int32(SEEK_SET)) == target)
-        let start = ContinuousClock.now
         let served = reader.read(into: buf, size: Int32(chunk))
-        let elapsed = ContinuousClock.now - start
 
         #expect(served > 0)
-        #expect(elapsed < .seconds(2), "the detour took \(elapsed): it waited on a slot it already held")
+        // The witness is the pump still on the link, not a clock: with the old double acquire the
+        // second ticket waited out its 4 s budget, by which time the pump's range had ended (checked
+        // by reverting 0fd16c57). A wall-clock bound on this read measured 2.0 to 2.3 s on a loaded
+        // CI runner for a correct detour.
         #expect(reader.hasLiveConnectionForTesting,
                 "the detour only got its slot once the pump's range had finished")
         let books = try #require(OriginRequestBudget.shared.snapshot(for: url))

From 3fb969bc60d293f2ed3c27cd0e7f8048faac8ab5 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 16:16:46 +0200
Subject: [PATCH 241/359] test(demuxer): bound the hard-cap test's peak by the
 body, not by a guess at the delivery size

The peak is about one URLSession delivery, which measured 2.4 MB on a CI runner against the 2 MiB
bound (run 36726291772). A 64 MiB body with a quarter-body bound still fails if the cap ever lets
the body pile up.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../AetherEngineTests/StreamingBufferBoundTests.swift | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)

diff --git a/Tests/AetherEngineTests/StreamingBufferBoundTests.swift b/Tests/AetherEngineTests/StreamingBufferBoundTests.swift
index 60ba40fb7..93b56c387 100644
--- a/Tests/AetherEngineTests/StreamingBufferBoundTests.swift
+++ b/Tests/AetherEngineTests/StreamingBufferBoundTests.swift
@@ -23,11 +23,14 @@ struct StreamingBufferBoundTests {
     @Test("a transport that delivers past the hard cap ends the read with a typed cause",
           .timeLimit(.minutes(1)))
     func hardCapIsTyped() throws {
-        let maybe = ThrottledOriginServer(totalSize: 8 * 1024 * 1024, throttleUs: 0)
+        let body = 64 * 1024 * 1024
+        let maybe = ThrottledOriginServer(totalSize: Int64(body), throttleUs: 0)
         let server = try #require(maybe)
         defer { server.stop() }
         // One delivery is larger than twice this, so the cap is passed without depending on
-        // whether the transport honours the pause that comes first.
+        // whether the transport honours the pause that comes first. The peak is then about one
+        // URLSession delivery, which measured 2.4 MB on a CI runner, so the bound is a quarter of
+        // the body rather than a guess at the delivery size.
         let reader = AVIOReader(url: URL(string: "http://127.0.0.1:\(server.port)/archive.ts")!,
                                 sequentialOnly: true, streamHighWater: 1024)
         defer { reader.markClosed(); reader.close() }
@@ -36,8 +39,8 @@ struct StreamingBufferBoundTests {
         let result = drain(reader)
         #expect(result.last == FFmpegErr.eio, "a source ended at the cap is lost, not finished")
         #expect(reader.lastReadFailure == .originIgnoresFlowControl)
-        #expect(result.read < 8 * 1024 * 1024, "the cap let the whole body through")
-        #expect(reader.streamPeakBufferBytesForTesting < 2 * 1024 * 1024,
+        #expect(result.read < body, "the cap let the whole body through")
+        #expect(reader.streamPeakBufferBytesForTesting < body / 4,
                 "the buffer held \(reader.streamPeakBufferBytesForTesting / 1024) KB")
     }
 

From 04ed821991d091a841c2dcba908fe31cc555f015 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 16:55:05 +0200
Subject: [PATCH 242/359] ci: five macOS jobs without a queue, and one compile
 per simulator job

CI ran six macOS jobs against the account's five concurrent macOS runners, so one job queued for
four to six and a half minutes before it started (runs 36626279096, 36702348649). The simulator
jobs each compiled the engine twice, once for `xcodebuild build` and again for `build-for-testing`
in a second derived data folder, which cost 150 to 170 s per job. The release aetherctl build
(126 s) sat on the `swift test` job's critical path.

Now: the tests build is the only compile per simulator job, visionOS rides in the tvOS job, and the
release aetherctl build moves to the iOS job. Every platform, both toolchains, Debug and Release and
the whole test suite still run.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .github/workflows/ci.yml | 86 +++++++++++++---------------------------
 1 file changed, 28 insertions(+), 58 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index d6b527ece..0421994e1 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -31,12 +31,6 @@ jobs:
       - name: swift build
         run: swift build
 
-      # Every other Swift step here is Debug, and aetherctl is not a product, so no consumer compiles
-      # it either: a DEBUG-only engine hook called without a guard kept Release broken from 7.6.0 to
-      # 7.14.0 without anything noticing (AE#610).
-      - name: swift build -c release (aetherctl)
-        run: swift build -c release --product aetherctl
-
       # A test process that dies mid-run reads as exit 1 with no ✘, no backtrace and no swift-testing
       # summary: `swift test` collapses every abnormal child exit to a plain 1, and a signal takes the
       # buffered tail of the event stream with it. What was in flight is whatever the log still lists
@@ -66,7 +60,7 @@ jobs:
         run: swift build --build-tests --package-path Probes/TransportProbe
 
   build-tvos:
-    name: xcodebuild (tvOS Simulator)
+    name: xcodebuild (tvOS + visionOS Simulator)
     runs-on: macos-15
     timeout-minutes: 30
     steps:
@@ -76,14 +70,6 @@ jobs:
         with:
           xcode-version: latest-stable
 
-      - name: Build for tvOS Simulator
-        run: |
-          xcodebuild build \
-            -scheme AetherEngine \
-            -destination 'generic/platform=tvOS Simulator' \
-            -derivedDataPath .build/xcode-tvos \
-            CODE_SIGNING_ALLOWED=NO
-
       # The test target is the only place a platform gate in TEST code is ever checked. `swift test`
       # on macOS compiles the macOS side of every `#if`, so a gate put around a helper instead of
       # around the tests that call it looks complete there and costs nothing until someone builds
@@ -92,12 +78,16 @@ jobs:
       #
       # EXCLUDED_ARCHS because a generic simulator destination builds both slices and `libdovi.a`
       # ships arm64 only, so the x86_64 link fails and says nothing about this repo.
+      #
+      # This step also compiles the library, so no separate `xcodebuild build` of the AetherEngine
+      # scheme runs first: that doubled every simulator job's compile, and the x86_64 slice it added
+      # is one no app can link anyway.
       - name: Build the tests for tvOS Simulator
         run: |
           xcodebuild build-for-testing \
             -scheme AetherEngineTests \
             -destination 'generic/platform=tvOS Simulator' \
-            -derivedDataPath .build/xcode-tvos-tests \
+            -derivedDataPath .build/xcode-tvos \
             EXCLUDED_ARCHS=x86_64 \
             CODE_SIGNING_ALLOWED=NO
 
@@ -114,8 +104,22 @@ jobs:
             -derivedDataPath .build/xcode-probe \
             CODE_SIGNING_ALLOWED=NO
 
+      # #344: the package has declared visionOS since 6.0.0 and nothing here compiled for it, so an
+      # availability list that named tvOS/iOS/macOS and then fell through to `*` broke the visionOS
+      # build silently. `*` resolves to the declared visionOS floor (1.0), so any API newer than that
+      # is a compile error on visionOS and on no other platform. Nobody here owns a Vision Pro, which
+      # makes this step the only place the platform is exercised at all. It rides in this job so CI
+      # stays within the account's concurrent macOS runners instead of queueing a sixth job.
+      - name: Build for visionOS Simulator
+        run: |
+          xcodebuild build \
+            -scheme AetherEngine \
+            -destination 'generic/platform=visionOS Simulator' \
+            -derivedDataPath .build/xcode-visionos \
+            CODE_SIGNING_ALLOWED=NO
+
   build-ios:
-    name: xcodebuild (iOS Simulator)
+    name: xcodebuild (iOS Simulator) + release aetherctl
     runs-on: macos-15
     timeout-minutes: 30
     steps:
@@ -125,14 +129,6 @@ jobs:
         with:
           xcode-version: latest-stable
 
-      - name: Build for iOS Simulator
-        run: |
-          xcodebuild build \
-            -scheme AetherEngine \
-            -destination 'generic/platform=iOS Simulator' \
-            -derivedDataPath .build/xcode-ios \
-            CODE_SIGNING_ALLOWED=NO
-
       # The other half of the gate check above; see the tvOS job for why the test target needs its
       # own build and why x86_64 is excluded.
       - name: Build the tests for iOS Simulator
@@ -140,33 +136,15 @@ jobs:
           xcodebuild build-for-testing \
             -scheme AetherEngineTests \
             -destination 'generic/platform=iOS Simulator' \
-            -derivedDataPath .build/xcode-ios-tests \
+            -derivedDataPath .build/xcode-ios \
             EXCLUDED_ARCHS=x86_64 \
             CODE_SIGNING_ALLOWED=NO
 
-  # #344: the package has declared visionOS since 6.0.0 and nothing here compiled for it, so an
-  # availability list that named tvOS/iOS/macOS and then fell through to `*` broke the visionOS
-  # build silently. `*` resolves to the declared visionOS floor (1.0), so any API newer than that
-  # is a compile error on visionOS and on no other platform. Nobody here owns a Vision Pro, which
-  # makes this job the only place the platform is exercised at all.
-  build-visionos:
-    name: xcodebuild (visionOS Simulator)
-    runs-on: macos-15
-    timeout-minutes: 30
-    steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-
-      - uses: maxim-lobanov/setup-xcode@ed7a3b1fda3918c0306d1b724322adc0b8cc0a90 # v1.7.0
-        with:
-          xcode-version: latest-stable
-
-      - name: Build for visionOS Simulator
-        run: |
-          xcodebuild build \
-            -scheme AetherEngine \
-            -destination 'generic/platform=visionOS Simulator' \
-            -derivedDataPath .build/xcode-visionos \
-            CODE_SIGNING_ALLOWED=NO
+      # Every other Swift step in CI is Debug, and aetherctl is not a product, so no consumer compiles
+      # it either: a DEBUG-only engine hook called without a guard kept Release broken from 7.6.0 to
+      # 7.14.0 without anything noticing (AE#610). Off the `swift test` job's critical path.
+      - name: swift build -c release (aetherctl)
+        run: swift build -c release --product aetherctl
 
   # The Xcode 27 lane. Every job above resolves `latest-stable` on macos-15, which is Xcode 26.3,
   # while the engine is consumed and released from Xcode 27, and Swift 6.4 rejects isolation shapes
@@ -205,21 +183,13 @@ jobs:
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
-      - name: Build for tvOS Simulator
-        run: |
-          xcodebuild build \
-            -scheme AetherEngine \
-            -destination 'generic/platform=tvOS Simulator' \
-            -derivedDataPath .build/xcode-tvos \
-            CODE_SIGNING_ALLOWED=NO
-
       # See the tvOS job above for why the test target needs its own build and why x86_64 is excluded.
       - name: Build the tests for tvOS Simulator
         run: |
           xcodebuild build-for-testing \
             -scheme AetherEngineTests \
             -destination 'generic/platform=tvOS Simulator' \
-            -derivedDataPath .build/xcode-tvos-tests \
+            -derivedDataPath .build/xcode-tvos \
             EXCLUDED_ARCHS=x86_64 \
             CODE_SIGNING_ALLOWED=NO
 

From 8ed60890b78030ab489da5ba07e0cac711430802 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 17:06:51 +0200
Subject: [PATCH 243/359] ci: test on the Xcode 27 toolchain only

Every macOS job now runs on GitHub's `xcode-27` image (macOS 27.0, Xcode 27.0 27A266a), the Xcode
the engine is consumed and released from; the macos-15 lanes resolved `latest-stable` to Xcode
26.3, and its Swift 6.2 disagreed with 6.4 in both directions (a type-check timeout on 2026-09-30,
isolation shapes on 2026-09-16). The two build-only Xcode 27 jobs are gone because the main jobs
now use that toolchain, so CI runs three macOS jobs.

The README's Swift and Xcode rows move to 6.4 / 27.0 and say they are the toolchain CI tests;
CONTRIBUTING follows. DocumentedConstantsTests now ties the rows to ci.yml (every macOS job on
xcode-27, none selecting another Xcode) instead of to the 26.2 SDK symbol.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .github/workflows/ci.yml                      | 75 ++++---------------
 CONTRIBUTING.md                               |  2 +-
 README.md                                     |  6 +-
 .../DocumentedConstantsTests.swift            | 24 +++---
 4 files changed, 31 insertions(+), 76 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 0421994e1..5072788c6 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -12,17 +12,23 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  # One toolchain: GitHub's `xcode-27` image (macOS 27.0, default Xcode 27.0 27A266a), the same
+  # Xcode the engine is consumed and released from. The earlier macos-15 lanes resolved
+  # `latest-stable` to Xcode 26.3, whose Swift 6.2 disagreed with 6.4 in both directions (6.4
+  # rejects isolation shapes 6.3 accepted, 2026-09-16; 6.2 timed out type-checking a literal sum
+  # inside #expect, 2026-09-30), and nothing downstream builds with 26.x any more, so the README's
+  # requirement is Xcode 27 and CI tests exactly that. `xcode-27` is still a GitHub preview image.
+  # Its flaky `swift test` runs of mid-September were on a beta macOS 27 base with Xcode 27
+  # beta 6; the image moved to macOS 27 on 2026-09-16. If it turns unstable again, that shows as
+  # a lane red for its image, which is the signal to wait for the GA label, not to lower the bar.
+  # All three macOS jobs use it, which stays within the account's concurrent macOS runners.
   test-macos:
     name: swift test (macOS)
-    runs-on: macos-15
+    runs-on: xcode-27
     timeout-minutes: 30
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
-      - uses: maxim-lobanov/setup-xcode@ed7a3b1fda3918c0306d1b724322adc0b8cc0a90 # v1.7.0
-        with:
-          xcode-version: latest-stable
-
       - name: Show toolchain
         run: |
           swift --version
@@ -61,15 +67,11 @@ jobs:
 
   build-tvos:
     name: xcodebuild (tvOS + visionOS Simulator)
-    runs-on: macos-15
+    runs-on: xcode-27
     timeout-minutes: 30
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
-      - uses: maxim-lobanov/setup-xcode@ed7a3b1fda3918c0306d1b724322adc0b8cc0a90 # v1.7.0
-        with:
-          xcode-version: latest-stable
-
       # The test target is the only place a platform gate in TEST code is ever checked. `swift test`
       # on macOS compiles the macOS side of every `#if`, so a gate put around a helper instead of
       # around the tests that call it looks complete there and costs nothing until someone builds
@@ -120,15 +122,11 @@ jobs:
 
   build-ios:
     name: xcodebuild (iOS Simulator) + release aetherctl
-    runs-on: macos-15
+    runs-on: xcode-27
     timeout-minutes: 30
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
-      - uses: maxim-lobanov/setup-xcode@ed7a3b1fda3918c0306d1b724322adc0b8cc0a90 # v1.7.0
-        with:
-          xcode-version: latest-stable
-
       # The other half of the gate check above; see the tvOS job for why the test target needs its
       # own build and why x86_64 is excluded.
       - name: Build the tests for iOS Simulator
@@ -146,53 +144,6 @@ jobs:
       - name: swift build -c release (aetherctl)
         run: swift build -c release --product aetherctl
 
-  # The Xcode 27 lane. Every job above resolves `latest-stable` on macos-15, which is Xcode 26.3,
-  # while the engine is consumed and released from Xcode 27, and Swift 6.4 rejects isolation shapes
-  # 6.3 accepted (the Sodalite test target stopped compiling on exactly that, 2026-09-16). These two
-  # jobs compile the package and both test targets against the 27 toolchain, for macOS and for the
-  # tvOS 27 SDK.
-  #
-  # They build and do not run the tests, on purpose. `xcode-27` is GitHub's preview image and runs a
-  # BETA macOS 27 (26A5406e) under Xcode 27 beta 6: measured on two attempts of the first run, Vision
-  # text recognition returns nil there and the loopback-origin tests starve (a global-queue block not
-  # scheduled within 30 s, a TLS relay request timing out), a different set of network tests each
-  # time, while all 2983 pass on macOS 27 GA on a Mac. A lane that is red for its image teaches
-  # everyone to ignore red. Run `swift test` here once a GA macOS 27 image ships, and that is also
-  # the point to move to its label; the preview label disappearing fails these jobs loudly first.
-  # This lane replaces the weekly beta SDK watcher, whose one subject (#351) the 7.0 platform floor
-  # closed.
-  build-macos-xcode27:
-    name: swift build --build-tests (macOS, Xcode 27)
-    runs-on: xcode-27
-    timeout-minutes: 30
-    steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-
-      - name: Show toolchain
-        run: |
-          swift --version
-          xcodebuild -version
-
-      - name: swift build --build-tests
-        run: swift build --build-tests
-
-  build-tvos-xcode27:
-    name: xcodebuild (tvOS Simulator, Xcode 27)
-    runs-on: xcode-27
-    timeout-minutes: 30
-    steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-
-      # See the tvOS job above for why the test target needs its own build and why x86_64 is excluded.
-      - name: Build the tests for tvOS Simulator
-        run: |
-          xcodebuild build-for-testing \
-            -scheme AetherEngineTests \
-            -destination 'generic/platform=tvOS Simulator' \
-            -derivedDataPath .build/xcode-tvos \
-            EXCLUDED_ARCHS=x86_64 \
-            CODE_SIGNING_ALLOWED=NO
-
   # The docs site (aetherengine-website) validates every heading anchor at build time, but it
   # lives in another repo and only builds AFTER a push to main, so a broken anchor ships first
   # and is found second: `docs/api.md` linked `formats.md#dolby-vision` against a heading that
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 83cc453a2..ce83cbe3f 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -17,7 +17,7 @@ swift build
 swift test
 ```
 
-For iterative work, open `Package.swift` in Xcode 26+ and pick the `AetherEngine` scheme. `FFmpegBuild` is a transitive dependency that supplies the bundled FFmpeg / dav1d binaries; you do not build it yourself.
+For iterative work, open `Package.swift` in Xcode 27+ and pick the `AetherEngine` scheme. `FFmpegBuild` is a transitive dependency that supplies the bundled FFmpeg / dav1d binaries; you do not build it yourself.
 
 The `aetherctl` command-line target is macOS-only (it uses `Foundation.Process`) and is excluded from the iOS / tvOS library build.
 
diff --git a/README.md b/README.md
index a9b328dcc..68452db51 100644
--- a/README.md
+++ b/README.md
@@ -644,10 +644,10 @@ Pin to `.upToNextMinor(from: "7.22.2")` for stricter teams that prefer to opt in
 | tvOS | 18.0 |
 | macOS | 15.0 |
 | visionOS | 1.0 |
-| Swift | 6.2 |
-| Xcode | 26.2 |
+| Swift | 6.4 |
+| Xcode | 27.0 |
 
-The Xcode row is the SDK the source compiles against (`VTRegisterSupplementalVideoDecoderIfAvailable` is iOS / tvOS 26.2 API, and an unguarded C symbol has to exist at compile time); the deployment floor above stays iOS / tvOS 18 and macOS 15, with the 26.x calls behind `#available`.
+The Swift and Xcode rows are the toolchain CI builds and tests with (GitHub's `xcode-27` image); older toolchains are not tested. The source needs at least the 26.2 SDK in any case (`VTRegisterSupplementalVideoDecoderIfAvailable` is iOS / tvOS 26.2 API, and an unguarded C symbol has to exist at compile time). The deployment floor above stays iOS / tvOS 18 and macOS 15, with the newer calls behind `#available`.
 
 The 7.x line raised the floor from iOS 16, tvOS 17 and macOS 14. A project that still supports those pins the 6.x line with `.upToNextMajor(from: "6.89.1")`.
 
diff --git a/Tests/AetherEngineTests/DocumentedConstantsTests.swift b/Tests/AetherEngineTests/DocumentedConstantsTests.swift
index 8f9047053..1aeb841d0 100644
--- a/Tests/AetherEngineTests/DocumentedConstantsTests.swift
+++ b/Tests/AetherEngineTests/DocumentedConstantsTests.swift
@@ -283,16 +283,20 @@ final class DocumentedConstantsTests: XCTestCase {
             """)
     }
 
-    /// The README's Xcode row is the SDK the source needs, not a taste (audit OPS-103): the engine
-    /// names a 26.2 C symbol unguarded, so an older Xcode cannot compile it. When the symbol goes,
-    /// this fails and the row can come down with it.
-    func testXcodeRequirementIsTheSDKTheSourceCompilesAgainst() throws {
-        let probe = try sourceFile("Sources/AetherEngine/Video/VTCapabilityProbe.swift")
-        XCTAssertTrue(probe.contains("VTRegisterSupplementalVideoDecoderIfAvailable("), """
-            VTCapabilityProbe no longer calls the iOS / tvOS 26.2 symbol that sets the README's Xcode row.
-            Re-derive the SDK requirement and update the Requirements table.
-            """)
-        assertDocumented("| Xcode | 26.2 |", try documentation())
+    /// The README's Swift and Xcode rows are the toolchain CI builds and tests with, not a taste
+    /// (audit OPS-103): every macOS job runs on the `xcode-27` image and none selects another Xcode.
+    /// Moving CI to another image without the rows, or the rows without CI, fails here.
+    func testToolchainRowsAreTheOnesCITestsWith() throws {
+        let ci = try sourceFile(".github/workflows/ci.yml")
+        let macOSJobs = ci.components(separatedBy: "runs-on: ").dropFirst()
+            .map { entry in entry.prefix { !$0.isNewline } }
+            .filter { !$0.hasPrefix("ubuntu") }
+        XCTAssertFalse(macOSJobs.isEmpty, "ci.yml has no macOS job")
+        XCTAssertTrue(macOSJobs.allSatisfy { $0 == "xcode-27" }, "macOS jobs run on \(macOSJobs)")
+        XCTAssertFalse(ci.contains("xcode-version:"), "a job selects its own Xcode instead of the image's")
+        let docs = try documentation()
+        assertDocumented("| Xcode | 27.0 |", docs)
+        assertDocumented("| Swift | 6.4 |", docs)
     }
 
     /// The docs corpus is README + docs/; a claim living in a source docstring is read straight.

From cb439e8593cb9bfc052b0c80e16c0637d143eb3d Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 17:37:33 +0200
Subject: [PATCH 244/359] chore(release): prep 7.23.0 - the second full audit's
 fixes

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                    | 4 ++++
 Examples/README.md                              | 2 +-
 README.md                                       | 6 +++---
 Sources/AetherEngine/AetherEngine+Version.swift | 2 +-
 4 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index dfe3e3c23..3665a6177 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,10 @@ the public-API contract.
 
 ## [Unreleased]
 
+_Nothing yet._
+
+## [7.23.0] - 2026-09-30
+
 Second full audit of the engine (2026-09-29, against 7.22.2): about 107 verified defects (3 High, 35 Medium), including regressions and incomplete fixes the first audit's patches left behind. All but three performance items are fixed here, each with a regression test that failed before it; the embedded-subtitle double download (PERF-103), the byte-bounded fragment flush (PERF-105) and the audio tap readers' cost (DEC-108) need a device round or a larger redesign and are deferred.
 
 ### Added
diff --git a/Examples/README.md b/Examples/README.md
index ec4c13a80..5cc7083ae 100644
--- a/Examples/README.md
+++ b/Examples/README.md
@@ -18,7 +18,7 @@ Three samples covering different audiences:
    ```
    https://github.com/superuser404notfound/AetherEngine
    ```
-   Dependency Rule: Up to Next Major Version, starting from `7.22.2`. Add the `AetherEngine` library product to your app target.
+   Dependency Rule: Up to Next Major Version, starting from `7.23.0`. Add the `AetherEngine` library product to your app target.
 
 3. **Drop the file in.** Replace the Xcode template's default `App.swift` (or whatever the generated `@main` file is called) with the contents of [`MinimalPlayerApp.swift`](MinimalPlayer/MinimalPlayerApp.swift). The file is self-contained: it defines both the `@main App` struct and the `ContentView`.
 
diff --git a/README.md b/README.md
index 68452db51..b4183e84a 100644
--- a/README.md
+++ b/README.md
@@ -384,7 +384,7 @@ Subtitle cues land in raw source PTS; render the overlay against `player.sourceT
 Install via Swift Package Manager:
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.22.2")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.23.0")
 ```
 
 Three samples ship in `Examples/`:
@@ -631,10 +631,10 @@ Browse all of this as a searchable site at **[aetherengine.superuser404.de](http
 AetherEngine uses [Semantic Versioning](https://semver.org). The public API surface, every `public` declaration in `Sources/AetherEngine/`, is the stability contract. **Major** removes / renames public symbols or breaks adopters; **Minor** adds public API or codec / format support; **Patch** fixes bugs with no public API change. `internal` types are not part of the contract.
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.22.2")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.23.0")
 ```
 
-Pin to `.upToNextMinor(from: "7.22.2")` for stricter teams that prefer to opt into minor bumps explicitly.
+Pin to `.upToNextMinor(from: "7.23.0")` for stricter teams that prefer to opt into minor bumps explicitly.
 
 ## Requirements
 
diff --git a/Sources/AetherEngine/AetherEngine+Version.swift b/Sources/AetherEngine/AetherEngine+Version.swift
index 6e4fe77b3..e6c4e8e8f 100644
--- a/Sources/AetherEngine/AetherEngine+Version.swift
+++ b/Sources/AetherEngine/AetherEngine+Version.swift
@@ -11,5 +11,5 @@ extension AetherEngine {
     ///
     /// Between releases, and in a consumer that pins an unreleased commit for a device test, this
     /// names the last PUBLISHED version the checkout descends from, not every patch in it.
-    public nonisolated static let version = "7.22.2"
+    public nonisolated static let version = "7.23.0"
 }

From 0d3dc68fb01e24af5370e0d5354dc44124c5c63d Mon Sep 17 00:00:00 2001
From: Vincent <superuser404@mailbox.org>
Date: Wed, 30 Sep 2026 19:42:33 +0200
Subject: [PATCH 245/359] fix(live): fastZap seals headroom over the GOPs it
 cuts (#676)

Reported in AE#670. Under .fastZap the cut target (0.5 s) sits below any real GOP, so every
segment the engine cuts is one whole source GOP, and TARGETDURATION was
sealed from the first few with no headroom over them. A broadcast whose
GOPs run 1.0 to 2.4 s sealed TD 1 on three 1.000 s ones, then broke
EXTINF <= TD on every longer GOP and held the playlist unchanged past
AVPlayer's 1.5 x TD patience: -12888, #446 reading the source as dead,
#524 on 1.5 s of runway, and on macOS the playlist refused as a parse
error (-12642) with a fall to the software path.

Self-cut fastZap segments now seal ceil(1.5 x max EXTINF), the headroom
.standard always had from its 1.5 x cut-target floor. Ingested segments
(bounded by the upstream's own TD, AE#447) and .standard are unchanged.

Measured with aetherctl live --fast-zap --realtime --preroll 0 on a seed
with that GOP pattern, two passes per arm: main sealed 1 s, one stall,
-12642 and a software fallback on both; this branch sealed 2 s, none of
the three on either. Regular 1 s GOPs: join 1.38 s against 1.14 / 1.23 s.


Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS

Co-authored-by: Vincent Herbst <superuser404@tuta.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md                                  |  4 +-
 README.md                                     |  2 +-
 Sources/AetherEngine/PlayerState.swift        |  6 +-
 .../Video/VideoSegmentProvider.swift          | 38 ++++++++-
 .../Issue195FastLiveJoinTests.swift           | 10 +--
 .../Issue670FastZapGOPHeadroomTests.swift     | 85 +++++++++++++++++++
 .../LiveWindowObservedCadenceTests.swift      |  4 +-
 docs/api.md                                   |  8 +-
 docs/cli.md                                   |  2 +-
 9 files changed, 142 insertions(+), 17 deletions(-)
 create mode 100644 Tests/AetherEngineTests/Issue670FastZapGOPHeadroomTests.swift

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3665a6177..95ebf31b6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,7 +10,9 @@ the public-API contract.
 
 ## [Unreleased]
 
-_Nothing yet._
+### Fixed
+
+- **`.fastZap` live froze on sources with irregular GOPs (#670).** The engine's sub-second cut makes every segment one whole GOP, and TARGETDURATION was sealed from the first few with no headroom over them: a broadcast whose GOPs run 1.0 to 2.4 s sealed 1 on three 1.000 s ones, then broke `EXTINF <= TD` on every longer GOP and held the playlist unchanged past AVPlayer's patience (-12888, #524 on 1.5 s of runway, and on macOS the playlist refused outright). Self-cut fastZap segments now seal `ceil(1.5 x max EXTINF)`, the headroom `.standard` always had from its cut-target floor, so 1 s GOPs serve TARGETDURATION 2 and a 6 s holdback. Ingested segments and `.standard` are unchanged.
 
 ## [7.23.0] - 2026-09-30
 
diff --git a/README.md b/README.md
index b4183e84a..58e2fb716 100644
--- a/README.md
+++ b/README.md
@@ -477,7 +477,7 @@ player.$recordingState            // .idle / .recording / .ended / .failed
 
 `startRecording(to:)` (AetherEngine#560) writes the live source to an MPEG-TS file fed from the connection the session already holds. That is the point of it rather than a detail: an IPTV plan commonly caps an account at 1 to 3 simultaneous connections, so a host that opens its own connection to record either fails outright or knocks the viewer off the channel. It is a stream copy of the source packets taken before any audio bridging, so a TrueHD or DTS channel records its original audio while playback listens to the bridged rendition, and a file cut short by a crash is still playable up to the cut. Recording follows the source rather than the playhead, so pausing or scrubbing back inside the DVR window does not interrupt it, and a `liveSourceReset` ends it cleanly rather than writing past a seam the codecs may not survive. The one route that cannot record is `nativeRemoteHLS` (`.remoteBypass`), where AVFoundation holds the source connection and the engine never sees a byte; `startRecording` throws `.unsupportedRoute` there instead of producing an empty file. Full contract in [docs/api.md](docs/api.md#recording-a-live-stream).
 
-`liveJoinProfile: .fastZap` (AetherEngine#195/#208) cuts live segments at every keyframe past 0.5 s instead of the standard ~4 s, so the served `TARGETDURATION` collapses to the source GOP length and its live-edge holdback (`HOLD-BACK` = 3 x `TARGETDURATION`, the RFC 8216bis floor; AetherEngine#189) shrinks with it. The first manifest still prefers the full holdback. After two finalized segments, a strict-realtime source gets one observed-segment grace clamped to 0.5...2.0 s, then a shallow first window may be served so startup stays bounded. This can produce one early `-16832` or a short rebuffer. `.standard` retains the full-holdback guarantee. The smaller `TARGETDURATION` also tightens AVPlayer's unchanged-playlist patience and live-edge buffer, so origins that stall or burst mid-stream rebuffer more readily; opt in for zapping UX, keep `.standard` for lean-back viewing.
+`liveJoinProfile: .fastZap` (AetherEngine#195/#208) cuts live segments at every keyframe past 0.5 s instead of the standard ~4 s, so the served `TARGETDURATION` collapses to 1.5 x the source GOP length (1 s GOPs serve 2; the headroom covers a broadcast's irregular GOPs, AetherEngine#670) and its live-edge holdback (`HOLD-BACK` = 3 x `TARGETDURATION`, the RFC 8216bis floor; AetherEngine#189) shrinks with it. The first manifest still prefers the full holdback. After two finalized segments, a strict-realtime source gets one observed-segment grace clamped to 0.5...2.0 s, then a shallow first window may be served so startup stays bounded. This can produce one early `-16832` or a short rebuffer. `.standard` retains the full-holdback guarantee. The smaller `TARGETDURATION` also tightens AVPlayer's unchanged-playlist patience and live-edge buffer, so origins that stall or burst mid-stream rebuffer more readily; opt in for zapping UX, keep `.standard` for lean-back viewing.
 
 `liveSourceReset` is live's counterpart to a terminal `state = .error`, and a host that plays live has to subscribe to it. It fires where the session cannot be revived from inside the engine and only a new URL can: a source that restarted from byte 0 (a Jellyfin transcode respawn), a playlist still frozen after the stall ladder's last reload rung (#65), or an in-engine reopen transport whose budget is spent (#199). Each of those halts production first, so a dead provider stops advertising blocking reloads behind the host's back. Answer it by negotiating a fresh URL and calling `load` again, and guard that answer (one retune in flight, a minimum spacing, a bounded count per session) or a permanently dead upstream turns into a retune loop. Spend that bound out loud: a retune ladder that ends on a silent `return` leaves the same dead channel behind a counter, so surface the exhaustion the way a terminal `.error` would be surfaced.
 
diff --git a/Sources/AetherEngine/PlayerState.swift b/Sources/AetherEngine/PlayerState.swift
index c21c89c7f..b1fc8d63f 100644
--- a/Sources/AetherEngine/PlayerState.swift
+++ b/Sources/AetherEngine/PlayerState.swift
@@ -546,8 +546,10 @@ public struct LoadOptions: Sendable, Equatable {
     /// live-edge holdback (`HOLD-BACK` >= 3 x TARGETDURATION, RFC 8216bis) the first manifest is gated on
     /// (AE#189) becomes >= 18s, which a strict-realtime origin can only fill in wall-clock time (10-18s of
     /// black on an IPTV zap). `.fastZap` cuts at every keyframe past 0.5s instead: segments quantize to the
-    /// source keyframe cadence, TARGETDURATION follows the real GOP length, and the holdback shrinks with
-    /// it. The first serve still prefers the full holdback, but after two finalized segments a
+    /// source keyframe cadence, TARGETDURATION follows the real GOP length with 1.5x headroom over the
+    /// longest GOP seen before the seal (a broadcast's GOPs are irregular and each segment is one whole
+    /// GOP, AE#670), and the holdback shrinks with it: 1 s GOPs serve TARGETDURATION 2, a 6 s holdback.
+    /// The first serve still prefers the full holdback, but after two finalized segments a
     /// strict-realtime source gets one observed-segment grace clamped to 0.5...2.0s, then may serve a
     /// shallow first window. This bounds black-screen startup but may produce one early `-16832` or a
     /// short rebuffer. `.standard` retains the full-holdback guarantee. A smaller TARGETDURATION also
diff --git a/Sources/AetherEngine/Video/VideoSegmentProvider.swift b/Sources/AetherEngine/Video/VideoSegmentProvider.swift
index 46cc5f726..e8be6f34e 100644
--- a/Sources/AetherEngine/Video/VideoSegmentProvider.swift
+++ b/Sources/AetherEngine/Video/VideoSegmentProvider.swift
@@ -343,15 +343,36 @@ enum LiveEdgePolicy {
     /// `cadenceFloorSeconds` are nil for VOD/EVENT. Every term is taken at the resolution the playlist
     /// serves (`servedSeconds`), so the value covers the EXTINFs the client is actually handed and no
     /// sub-millisecond noise can buy a whole second of holdback.
+    ///
+    /// AE#670: `segmentsAreCutHere` adds `ceil(1.5 x max EXTINF)` where that headroom has no other source
+    /// (`gopHeadroomApplies`).
     static func targetDurationSeconds(maxSegmentDuration: Double,
                                       cutTargetSeconds: Double?,
-                                      cadenceFloorSeconds: Double?) -> Int {
+                                      cadenceFloorSeconds: Double?,
+                                      segmentsAreCutHere: Bool = false) -> Int {
         var td = wholeSecondsCovering(max(1.0, maxSegmentDuration))
         if let cut = cutTargetSeconds { td = max(td, wholeSecondsCovering(cut * 1.5)) }
+        if gopHeadroomApplies(cutTargetSeconds: cutTargetSeconds, segmentsAreCutHere: segmentsAreCutHere) {
+            td = max(td, wholeSecondsCovering(maxSegmentDuration * 1.5))
+        }
         if let floor = cadenceFloorSeconds { td = max(td, targetDurationForCadence(floor)) }
         return td
     }
 
+    /// AE#670: does the sealed value need headroom over the GOPs seen so far?
+    ///
+    /// A cut target under a second never bounds a segment: the cutter waits for the next keyframe, so
+    /// every segment it cuts is one whole source GOP, and the value is sealed from the first few of them.
+    /// A broadcast's GOPs are not regular (reported: 1.0 to 2.4 s, sealed on three 1.000 s ones), and a
+    /// later longer one then breaks `EXTINF <= TD` and holds the playlist unchanged past AVPlayer's
+    /// patience. `.standard` has that headroom already in its `1.5 x cut target` floor, and ingested
+    /// segments are bounded by the upstream's own target duration (AE#447 keeps TD 2 on those), so only
+    /// the engine's own sub-second cut needs it from the segments.
+    static func gopHeadroomApplies(cutTargetSeconds: Double?, segmentsAreCutHere: Bool) -> Bool {
+        guard segmentsAreCutHere, let cut = cutTargetSeconds else { return false }
+        return cut < 1.0
+    }
+
     /// AVPlayer's default (and our explicitly advertised) live-edge holdback: `3 x TARGETDURATION`, the
     /// RFC 8216bis floor for `EXT-X-SERVER-CONTROL:HOLD-BACK`.
     static func holdBackSeconds(targetDuration: Int) -> Double { Double(3 * targetDuration) }
@@ -377,10 +398,12 @@ enum LiveEdgePolicy {
                                         maxSegmentDuration: Double,
                                         cutTargetSeconds: Double?,
                                         cadenceFloorSeconds: Double?,
+                                        segmentsAreCutHere: Bool = false,
                                         windowSegmentCount: Int) -> Bool {
         let td = targetDurationSeconds(maxSegmentDuration: maxSegmentDuration,
                                        cutTargetSeconds: cutTargetSeconds,
-                                       cadenceFloorSeconds: cadenceFloorSeconds)
+                                       cadenceFloorSeconds: cadenceFloorSeconds,
+                                       segmentsAreCutHere: segmentsAreCutHere)
         return startupCushionSatisfied(
             segmentCount: segmentCount,
             summedDurationSeconds: summedDurationSeconds,
@@ -521,6 +544,7 @@ struct LiveTargetDurationDerivation {
     let value: Int
     let maxSegmentDuration: Double
     let cutTargetFloor: Double?
+    var gopHeadroomApplies = false
     let cadenceFloor: CadenceFloorTerm
     let selfReported: Double?
 
@@ -530,6 +554,10 @@ struct LiveTargetDurationDerivation {
         if let cutTargetFloor {
             terms.append("1.5 x cut target \(LiveEdgePolicy.seconds(cutTargetFloor * 1.5))s")
         }
+        if gopHeadroomApplies {
+            terms.append("1.5 x max EXTINF \(LiveEdgePolicy.seconds(maxSegmentDuration * 1.5))s "
+                + "(each segment is one whole GOP)")
+        }
         terms.append(cadenceFloor.account)
         let claim = selfReported.map {
             "; upstream advertises \(LiveEdgePolicy.seconds($0))s (reported, not used)"
@@ -2282,14 +2310,18 @@ final class VideoSegmentProvider: HLSSegmentProvider, @unchecked Sendable {
         let floor: CadenceFloorTerm = liveCadencePolicy.map { policy in
             policy.targetDurationFloorSeconds.map { CadenceFloorTerm.measured($0) } ?? .pending
         } ?? .unmeasurable
+        let cutHere = liveCadencePolicy == nil
         return LiveTargetDurationDerivation(
             value: LiveEdgePolicy.targetDurationSeconds(
                 maxSegmentDuration: maxSegmentDuration,
                 cutTargetSeconds: cutTarget,
-                cadenceFloorSeconds: floor.seconds
+                cadenceFloorSeconds: floor.seconds,
+                segmentsAreCutHere: cutHere
             ),
             maxSegmentDuration: maxSegmentDuration,
             cutTargetFloor: cutTarget,
+            gopHeadroomApplies: LiveEdgePolicy.gopHeadroomApplies(cutTargetSeconds: cutTarget,
+                                                                  segmentsAreCutHere: cutHere),
             cadenceFloor: floor,
             selfReported: liveCadencePolicy?.selfReportedTargetDurationSeconds
         )
diff --git a/Tests/AetherEngineTests/Issue195FastLiveJoinTests.swift b/Tests/AetherEngineTests/Issue195FastLiveJoinTests.swift
index 0caaa8278..f2631d69f 100644
--- a/Tests/AetherEngineTests/Issue195FastLiveJoinTests.swift
+++ b/Tests/AetherEngineTests/Issue195FastLiveJoinTests.swift
@@ -50,12 +50,12 @@ final class Issue195FastLiveJoinTests: XCTestCase {
     // MARK: - TARGETDURATION / holdback under fastZap
 
     func testFastZapShortGOPTargetDurationTracksGOP() {
-        // 0.96s keyframe cadence: ceil(0.96)=1, cut floor ceil(1.5*0.5)=1 -> TD=1 -> 3s holdback.
+        // 0.96s keyframe cadence, cut here: ceil(1.5*0.96)=2 (AE#670 GOP headroom) -> TD=2 -> 6s holdback.
         let cut = HLSVideoEngine.liveCutTargetSeconds(for: .fastZap)
-        XCTAssertEqual(LiveEdgePolicy.targetDurationSeconds(maxSegmentDuration: 0.96, cutTargetSeconds: cut, cadenceFloorSeconds: nil), 1)
-        XCTAssertEqual(LiveEdgePolicy.holdBackSeconds(targetDuration: 1), 3.0, accuracy: 0.0001)
-        // 2s GOP: ceil(1.92)=2 -> TD=2 -> 6s holdback. Still 3x faster than the standard 18s.
-        XCTAssertEqual(LiveEdgePolicy.targetDurationSeconds(maxSegmentDuration: 1.92, cutTargetSeconds: cut, cadenceFloorSeconds: nil), 2)
+        XCTAssertEqual(LiveEdgePolicy.targetDurationSeconds(maxSegmentDuration: 0.96, cutTargetSeconds: cut, cadenceFloorSeconds: nil, segmentsAreCutHere: true), 2)
+        XCTAssertEqual(LiveEdgePolicy.holdBackSeconds(targetDuration: 2), 6.0, accuracy: 0.0001)
+        // 2s GOP: ceil(1.5*1.92)=3 -> TD=3 -> 9s holdback. Still 2x faster than the standard 18s.
+        XCTAssertEqual(LiveEdgePolicy.targetDurationSeconds(maxSegmentDuration: 1.92, cutTargetSeconds: cut, cadenceFloorSeconds: nil, segmentsAreCutHere: true), 3)
     }
 
     func testFastZapLongGOPDegradesToStandardBehavior() {
diff --git a/Tests/AetherEngineTests/Issue670FastZapGOPHeadroomTests.swift b/Tests/AetherEngineTests/Issue670FastZapGOPHeadroomTests.swift
new file mode 100644
index 000000000..ccff08886
--- /dev/null
+++ b/Tests/AetherEngineTests/Issue670FastZapGOPHeadroomTests.swift
@@ -0,0 +1,85 @@
+// Tests/AetherEngineTests/Issue670FastZapGOPHeadroomTests.swift
+// AE#670: live 1080p50 H.264 TS under `.fastZap` froze at irregular intervals, with AVPlayer reporting
+// -12888 (playlist unchanged for longer than 1.5 x target duration) and #524 firing on 1.5 to 2 s of
+// runway. The fastZap cut target (0.5 s) sits below any real GOP, so every segment the engine cuts is one
+// whole source GOP. The TARGETDURATION is sealed from the first window, which on the reported source held
+// three 1.000 s GOPs: TD 1, holdback 3 s, and no headroom at all over the GOP it had seen. The source's
+// GOPs are not regular (1.0 to 2.4 s), so every longer one broke `EXTINF <= TD` and left the playlist
+// unchanged past 1.5 x TD. `.standard` never had the problem because its `1.5 x cut target` floor is that
+// headroom; under fastZap it collapses to 1 s.
+//
+// Measured with `aetherctl live --fast-zap --realtime --preroll 0` on a seed with that GOP pattern, two
+// passes per arm: sealed at 1 s, one stall, the playlist refused as a parse error (-12642, macOS AVPlayer
+// is stricter than the reporter's tvOS one) and a fall to the software path on both passes; sealed at 2 s,
+// none of the three on either.
+import XCTest
+@testable import AetherEngine
+
+final class Issue670FastZapGOPHeadroomTests: XCTestCase {
+
+    private let fastZapCut = HLSVideoEngine.liveCutTargetSeconds(for: .fastZap)
+    private let standardCut = HLSVideoEngine.liveCutTargetSeconds(for: .standard)
+
+    /// The reported seal: three 1.000 s GOPs in the first window.
+    func testSelfCutFastZapSealsHeadroomOverTheFirstGOPs() {
+        let td = LiveEdgePolicy.targetDurationSeconds(maxSegmentDuration: 1.0,
+                                                      cutTargetSeconds: fastZapCut,
+                                                      cadenceFloorSeconds: nil,
+                                                      segmentsAreCutHere: true)
+        XCTAssertEqual(td, 2)
+        XCTAssertEqual(LiveEdgePolicy.holdBackSeconds(targetDuration: td), 6.0, accuracy: 1e-9)
+    }
+
+    /// What the seal has to survive afterwards: the 2.4 s GOP the reporter's log shows. It must round
+    /// under TD (RFC 8216 4.3.3.1), and the playlist must not stay unchanged past AVPlayer's patience
+    /// while the cutter waits for the keyframe that ends it.
+    func testLaterLongGOPStaysInsideTheSealedValue() {
+        let td = LiveEdgePolicy.targetDurationSeconds(maxSegmentDuration: 1.0,
+                                                      cutTargetSeconds: fastZapCut,
+                                                      cadenceFloorSeconds: nil,
+                                                      segmentsAreCutHere: true)
+        let laterGOP = 2.4
+        XCTAssertLessThanOrEqual(Int(laterGOP.rounded()), td)
+        XCTAssertGreaterThan(Double(td) * LiveEdgePolicy.unchangedPlaylistPatienceMultiplier, laterGOP)
+    }
+
+    func testHeadroomScalesWithTheObservedGOP() {
+        XCTAssertEqual(LiveEdgePolicy.targetDurationSeconds(maxSegmentDuration: 0.96,
+                                                            cutTargetSeconds: fastZapCut,
+                                                            cadenceFloorSeconds: nil,
+                                                            segmentsAreCutHere: true), 2)
+        XCTAssertEqual(LiveEdgePolicy.targetDurationSeconds(maxSegmentDuration: 1.92,
+                                                            cutTargetSeconds: fastZapCut,
+                                                            cadenceFloorSeconds: nil,
+                                                            segmentsAreCutHere: true), 3)
+    }
+
+    /// AE#447: ingested segments are the upstream's own, bounded by its advertised target duration, so
+    /// the field-measured TD 2 on 2.000 s segments stays.
+    func testIngestedSegmentsKeepTheirTargetDuration() {
+        XCTAssertEqual(LiveEdgePolicy.targetDurationSeconds(maxSegmentDuration: 2.0,
+                                                            cutTargetSeconds: fastZapCut,
+                                                            cadenceFloorSeconds: 2.0,
+                                                            segmentsAreCutHere: false), 2)
+    }
+
+    /// `.standard`'s cut target bounds its segments, and its `1.5 x cut target` floor is already the
+    /// headroom: the common 1.92 s GOP shape cuts 5.76 s segments and must keep TD 6, not rise to 9.
+    func testStandardProfileIsUnchanged() {
+        XCTAssertEqual(LiveEdgePolicy.targetDurationSeconds(maxSegmentDuration: 5.76,
+                                                            cutTargetSeconds: standardCut,
+                                                            cadenceFloorSeconds: nil,
+                                                            segmentsAreCutHere: true), 6)
+        XCTAssertEqual(LiveEdgePolicy.targetDurationSeconds(maxSegmentDuration: 4.0,
+                                                            cutTargetSeconds: standardCut,
+                                                            cadenceFloorSeconds: nil,
+                                                            segmentsAreCutHere: true), 6)
+    }
+
+    func testSealAccountNamesTheHeadroomTerm() {
+        let derivation = LiveTargetDurationDerivation(
+            value: 2, maxSegmentDuration: 1.0, cutTargetFloor: fastZapCut,
+            gopHeadroomApplies: true, cadenceFloor: .unmeasurable, selfReported: nil)
+        XCTAssertTrue(derivation.account.contains("1.5 x max EXTINF 1.500s"), derivation.account)
+    }
+}
diff --git a/Tests/AetherEngineTests/LiveWindowObservedCadenceTests.swift b/Tests/AetherEngineTests/LiveWindowObservedCadenceTests.swift
index 106acfc1e..2d43bdd50 100644
--- a/Tests/AetherEngineTests/LiveWindowObservedCadenceTests.swift
+++ b/Tests/AetherEngineTests/LiveWindowObservedCadenceTests.swift
@@ -61,8 +61,8 @@ final class LiveWindowObservedCadenceTests: XCTestCase {
         let provider = makeFastZapProvider()
         // Unsealed: legacy 18s (3 x fallback TD 6) so non-live/test conformers keep today's bound.
         XCTAssertEqual(provider.liveBlockingReloadHoldSeconds, 18.0, accuracy: 0.001)
-        // Seal at fastZap cadence: max segment 1.92s -> TD=2 -> hold 6s.
-        XCTAssertEqual(provider.liveTargetDurationSeconds(maxSegmentDuration: 1.92), 2)
+        // Seal at fastZap cadence: max segment 0.96s, cut here -> TD=ceil(1.5 x 0.96)=2 (AE#670) -> hold 6s.
+        XCTAssertEqual(provider.liveTargetDurationSeconds(maxSegmentDuration: 0.96), 2)
         XCTAssertEqual(provider.liveBlockingReloadHoldSeconds, 6.0, accuracy: 0.001)
         // Seal is session-stable: a later, longer segment cannot stretch the hold.
         _ = provider.liveTargetDurationSeconds(maxSegmentDuration: 5.76)
diff --git a/docs/api.md b/docs/api.md
index 99a91b7bc..4e29c6923 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -689,7 +689,11 @@ measured against, whether it waited or was satisfied immediately.
 `LoadOptions.liveJoinProfile` is the lever. `.fastZap` collapses `TARGETDURATION` to the source keyframe
 cadence and the holdback follows it down, so the win belongs to the source GOP rather than to the flag:
 `TARGETDURATION` can never fall below `ceil(max EXTINF)`, and a long-GOP source therefore keeps most of
-its runway under either profile.
+its runway under either profile. Where the engine cuts the segments itself, each one is a whole GOP and
+the value is sealed from the first few, so it carries `ceil(1.5 x max EXTINF)` of headroom: a broadcast
+whose GOPs run 1.0 to 2.4 s sealed TARGETDURATION 1 on its first three and then broke `EXTINF <= TD`
+on every longer one (AE#670). 1 s GOPs therefore serve TARGETDURATION 2 and a 6 s holdback. Ingested
+segments are bounded by the upstream's own target duration and keep `ceil(max EXTINF)`.
 
 **An HLS source with a window of its own now fills that cushion at the join rather than in wall clock**
 (6.77.0). The ingest used to enter a live playlist three segments behind the edge, and three joined
@@ -949,7 +953,7 @@ All flags default to safe values; the table is the full set. Depth for the media
 | `httpHeaders` | empty | Extra headers on every probe, range and segment fetch. On `nativeRemoteHLS` they ride into the `AVURLAsset`, so header-enforcing IPTV origins work. Forwarded to sidecar subtitle fetches unless overridden. **Scoping differs by route.** On the plain `nativeRemoteHLS` bypass AVFoundation itself sends them to every host the playlists name (cross-host variants, segments and `EXT-X-KEY` URIs) and carries them across 302 redirects, so credential headers there reach every such host and the engine cannot narrow that. The per-origin credential scoping described for `HLSLiveIngestReader` applies only on the routes the engine fetches itself: the ingest, the disc reader, the origin relay, the subtitle proxy, the audio tap and the live subtitle renditions. A credential that must not reach every host a playlist names should not ride in `httpHeaders` on the bypass. |
 | `isLive` | false | Treat the source as live. Set it explicitly; duration-based auto-detection is too noisy. |
 | `dvrWindowSeconds` | nil | Timeshift window. nil means live-only and `seek` is a no-op. The window is a ceiling: the disk budget (a quarter of the free space, at most 2 GiB) bounds what is actually kept, so a long window on a high-bitrate channel or a small volume holds less than it asks for. |
-| `liveJoinProfile` | `.standard` | A `LiveJoinProfile`. `.fastZap` collapses TARGETDURATION to the source GOP so an IPTV join costs seconds instead of a full holdback. |
+| `liveJoinProfile` | `.standard` | A `LiveJoinProfile`. `.fastZap` collapses TARGETDURATION to 1.5 x the source GOP (AE#670) so an IPTV join costs seconds instead of a full holdback. |
 | `clampsLiveResumeToWindow` | true | Whether `play()` may move a behind-live playhead by itself (edge snap on a live-only source more than 45 s behind, or a landing above the retained floor when a DVR window has slid past it). `false` hands the whole decision to the host, which then also owns the eviction case. |
 | `liveJoinStartsImmediately` | true | Cuts AVPlayer's stall-avoidance wait short once at the live join, over a buffer that is non-empty and at least 1.5 s deep. The join tail no host can otherwise reach; default since 6.55.0 on a device A/B, see the live-join section. |
 | `liveBlockingReload` | nil (auto) | LL-HLS blocking-reload override for loopback live sessions. Auto derives eligibility from observed upstream cadence, which is what keeps a bursty relay off a `-15410` loop. |
diff --git a/docs/cli.md b/docs/cli.md
index 40eadca3b..b0d7a81c5 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -149,7 +149,7 @@ load and `playing` at the roll (AE#440).
 
 `--live-ingest` loads the URL through `HLSLiveIngestReader` as a custom source, which is the shape a host uses for a live channel it ingests and re-serves itself (Sodalite's direct live path). Pair it with `--live`. It reaches the reader DIRECTLY, which is what a repro of the reader itself needs; since AE#363 plain `--live` also ends up there, but by way of the engine's own route (the raw live path detects the playlist and hands it to the ingest), so use `--live-ingest` when the reader is the subject and plain `--live` when the routing is. `hlslive` only serves local `.ts` files. AE#359 (the master's SUBTITLES renditions were parsed away) survived precisely because this path had no harness; `--live-ingest --subs <lang>` reproduces and verifies it in 40 s against a public broadcaster URL.
 
-`--fast-zap` sets `LoadOptions.liveJoinProfile = .fastZap` for the load. `live` has carried the flag for its own raw-TS fixture since AE#195, but that fixture has no upstream playlist, and the served `#EXT-X-TARGETDURATION` is floored by the UPSTREAM's observed arrival cadence (`LiveCadencePolicy`), which is what sizes the holdback the first serve waits for. So fastZap against an origin of one's own, the shape a downstream player actually ships, could not be driven from here at all. Measured on the same 1 s-GOP seed, `--preroll 0 --realtime`: raw TS with no playlist serves at 1.325 s on TARGETDURATION 1 (holdback 3 s, full cushion), the same content behind an `hlsfixture` origin cutting 2 s segments serves on TARGETDURATION **2** (holdback 6 s) although the engine re-cut it at 1 s. Pair it with `--live`, and read the first-serve line (AE#374) rather than a first-frame stopwatch.
+`--fast-zap` sets `LoadOptions.liveJoinProfile = .fastZap` for the load. `live` has carried the flag for its own raw-TS fixture since AE#195, but that fixture has no upstream playlist, and the served `#EXT-X-TARGETDURATION` is floored by the UPSTREAM's observed arrival cadence (`LiveCadencePolicy`), which is what sizes the holdback the first serve waits for. So fastZap against an origin of one's own, the shape a downstream player actually ships, could not be driven from here at all. Measured on the same 1 s-GOP seed, `--preroll 0 --realtime`: raw TS with no playlist serves at 1.325 s on TARGETDURATION 1 (holdback 3 s, full cushion; since AE#670 the engine's own GOP-bound cut carries 1.5x headroom, so that row now seals at 2), the same content behind an `hlsfixture` origin cutting 2 s segments serves on TARGETDURATION **2** (holdback 6 s) although the engine re-cut it at 1 s. Pair it with `--live`, and read the first-serve line (AE#374) rather than a first-frame stopwatch.
 
 `--live-start-immediately` / `--no-live-start-immediately` set `LoadOptions.liveJoinStartsImmediately`,
 which cuts AVPlayer's stall-avoidance hold short once at the live join (AE#440). It is **on by default**

From fb7afb2cd420898f9f29ad5dbfb9f7ae34b0faef Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 19:43:38 +0200
Subject: [PATCH 246/359] chore(release): prep 7.23.1 - fastZap seals headroom
 over the GOPs it cuts

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                    | 4 ++++
 Examples/README.md                              | 2 +-
 README.md                                       | 6 +++---
 Sources/AetherEngine/AetherEngine+Version.swift | 2 +-
 4 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 95ebf31b6..fe1bcdff6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,10 @@ the public-API contract.
 
 ## [Unreleased]
 
+_Nothing yet._
+
+## [7.23.1] - 2026-09-30
+
 ### Fixed
 
 - **`.fastZap` live froze on sources with irregular GOPs (#670).** The engine's sub-second cut makes every segment one whole GOP, and TARGETDURATION was sealed from the first few with no headroom over them: a broadcast whose GOPs run 1.0 to 2.4 s sealed 1 on three 1.000 s ones, then broke `EXTINF <= TD` on every longer GOP and held the playlist unchanged past AVPlayer's patience (-12888, #524 on 1.5 s of runway, and on macOS the playlist refused outright). Self-cut fastZap segments now seal `ceil(1.5 x max EXTINF)`, the headroom `.standard` always had from its cut-target floor, so 1 s GOPs serve TARGETDURATION 2 and a 6 s holdback. Ingested segments and `.standard` are unchanged.
diff --git a/Examples/README.md b/Examples/README.md
index 5cc7083ae..d8e586156 100644
--- a/Examples/README.md
+++ b/Examples/README.md
@@ -18,7 +18,7 @@ Three samples covering different audiences:
    ```
    https://github.com/superuser404notfound/AetherEngine
    ```
-   Dependency Rule: Up to Next Major Version, starting from `7.23.0`. Add the `AetherEngine` library product to your app target.
+   Dependency Rule: Up to Next Major Version, starting from `7.23.1`. Add the `AetherEngine` library product to your app target.
 
 3. **Drop the file in.** Replace the Xcode template's default `App.swift` (or whatever the generated `@main` file is called) with the contents of [`MinimalPlayerApp.swift`](MinimalPlayer/MinimalPlayerApp.swift). The file is self-contained: it defines both the `@main App` struct and the `ContentView`.
 
diff --git a/README.md b/README.md
index 58e2fb716..9267f66fd 100644
--- a/README.md
+++ b/README.md
@@ -384,7 +384,7 @@ Subtitle cues land in raw source PTS; render the overlay against `player.sourceT
 Install via Swift Package Manager:
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.23.0")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.23.1")
 ```
 
 Three samples ship in `Examples/`:
@@ -631,10 +631,10 @@ Browse all of this as a searchable site at **[aetherengine.superuser404.de](http
 AetherEngine uses [Semantic Versioning](https://semver.org). The public API surface, every `public` declaration in `Sources/AetherEngine/`, is the stability contract. **Major** removes / renames public symbols or breaks adopters; **Minor** adds public API or codec / format support; **Patch** fixes bugs with no public API change. `internal` types are not part of the contract.
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.23.0")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.23.1")
 ```
 
-Pin to `.upToNextMinor(from: "7.23.0")` for stricter teams that prefer to opt into minor bumps explicitly.
+Pin to `.upToNextMinor(from: "7.23.1")` for stricter teams that prefer to opt into minor bumps explicitly.
 
 ## Requirements
 
diff --git a/Sources/AetherEngine/AetherEngine+Version.swift b/Sources/AetherEngine/AetherEngine+Version.swift
index e6c4e8e8f..d277e023d 100644
--- a/Sources/AetherEngine/AetherEngine+Version.swift
+++ b/Sources/AetherEngine/AetherEngine+Version.swift
@@ -11,5 +11,5 @@ extension AetherEngine {
     ///
     /// Between releases, and in a consumer that pins an unreleased commit for a device test, this
     /// names the last PUBLISHED version the checkout descends from, not every patch in it.
-    public nonisolated static let version = "7.23.0"
+    public nonisolated static let version = "7.23.1"
 }

From cd579abeec3652146eaf0231eb393cfc4daeb2c2 Mon Sep 17 00:00:00 2001
From: Gary <gaz@gonkowonko.com>
Date: Wed, 30 Sep 2026 14:50:23 +0100
Subject: [PATCH 247/359] Cap the declared HEVC level at 5.1, and derive DV
 CODECS from the hvcC

A Dolby Vision Profile 8.1 source whose hvcC states level 5.2 (156) had its
master and reduced HDR master refused on Apple TV 4K with -11848 / CoreMedia
-15517, falling back to the media playlist with the DV upgrade dropped. The
stream was 1080p24; capping the declared level at L153 lets the DV master play.

The DV branches of resolveCodecRoute also hardcoded hvc1.2.4.L<level>, dropping
the constraint bytes the plain-HEVC branch has derived from the hvcC since
AE#187. They now go through plainHEVCCodecs like that branch.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 Sources/AetherEngine/Video/CodecRoutePolicy.swift | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/Sources/AetherEngine/Video/CodecRoutePolicy.swift b/Sources/AetherEngine/Video/CodecRoutePolicy.swift
index 8c9769699..8546c6c5f 100644
--- a/Sources/AetherEngine/Video/CodecRoutePolicy.swift
+++ b/Sources/AetherEngine/Video/CodecRoutePolicy.swift
@@ -174,7 +174,12 @@ extension HLSVideoEngine {
         var trimmedConstraints = constraintBytes
         while let last = trimmedConstraints.last, last == 0 { trimmedConstraints.removeLast() }
         let tier = tierFlag == 1 ? "H" : "L"
-        var s = "\(sampleEntry).\(spacePrefix)\(profileIDC).\(compatHex).\(tier)\(levelIDC)"
+        // Some encoders stamp level 5.2 (156) on 1080p24 streams. AVPlayer screens a master's declared
+        // level against the device and refuses 5.2 on an Apple TV 4K (-11848, CoreMedia -15517), while
+        // the same bytes decode fine media-direct, where nothing is declared. Level 5.1 covers up to
+        // 2160p60, so the attribute declares no more than that; the init segment's hvcC is untouched.
+        let declaredLevel = min(levelIDC, 153)
+        var s = "\(sampleEntry).\(spacePrefix)\(profileIDC).\(compatHex).\(tier)\(declaredLevel)"
         if !trimmedConstraints.isEmpty {
             s += "." + trimmedConstraints.map { String(format: "%02x", $0) }.joined(separator: ".")
         }
@@ -613,7 +618,7 @@ extension HLSVideoEngine {
             return CodecRoute(
                 codecTagOverride: "hvc1",
                 videoRange: .pq,
-                primaryCodecs: "hvc1.2.4.L\(hevcLevel)",
+                primaryCodecs: plainHEVCCodecs(codecpar: codecpar, fallbackLevel: hevcLevel),
                 supplementalCodecs: supplemental,
                 doviConfig: doviConfig,
                 convertP7ToProfile81: false,
@@ -635,7 +640,7 @@ extension HLSVideoEngine {
             return CodecRoute(
                 codecTagOverride: "hvc1",
                 videoRange: .hlg,
-                primaryCodecs: "hvc1.2.4.L\(hevcLevel)",
+                primaryCodecs: plainHEVCCodecs(codecpar: codecpar, fallbackLevel: hevcLevel),
                 supplementalCodecs: supplemental,
                 doviConfig: doviConfig,
                 convertP7ToProfile81: false,
@@ -657,7 +662,7 @@ extension HLSVideoEngine {
             return CodecRoute(
                 codecTagOverride: "hvc1",
                 videoRange: .pq,
-                primaryCodecs: "hvc1.2.4.L\(hevcLevel)",
+                primaryCodecs: plainHEVCCodecs(codecpar: codecpar, fallbackLevel: hevcLevel),
                 supplementalCodecs: supplemental,
                 doviConfig: doviConfig,
                 convertP7ToProfile81: effectiveDvMode,

From c415e2d8c5e73b0444fd6abe930561a2e362dddc Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 20:56:04 +0200
Subject: [PATCH 248/359] fix(video): cap the fallback HEVC level too, and pin
 AE#674 in tests

Follow-up to the reporter's commit. The level cap sat only in the hvcC
builder, so a source without a parseable hvcC still declared its
codecpar level verbatim through the hvc1.2.4.L<level> fallback. The cap
is now one named constant, maxDeclaredHEVCLevel, applied to both.

Tests pin the reporter's hvcC (level 156 -> hvc1.2.4.L153.90), levels up
to 5.1 declared as stated, and the DV Profile 8.1 route with and without
an hvcC.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../AetherEngine/Video/CodecRoutePolicy.swift | 22 +++--
 .../Issue674HEVCLevelCapTests.swift           | 96 +++++++++++++++++++
 2 files changed, 109 insertions(+), 9 deletions(-)
 create mode 100644 Tests/AetherEngineTests/Issue674HEVCLevelCapTests.swift

diff --git a/Sources/AetherEngine/Video/CodecRoutePolicy.swift b/Sources/AetherEngine/Video/CodecRoutePolicy.swift
index 8546c6c5f..70a04f3df 100644
--- a/Sources/AetherEngine/Video/CodecRoutePolicy.swift
+++ b/Sources/AetherEngine/Video/CodecRoutePolicy.swift
@@ -140,6 +140,14 @@ extension HLSVideoEngine {
     /// (media-direct, no CODECS) hid it, but once HEVC is signaled through a master (below) a strict
     /// Apple TV rejects the Main10 declaration against the Main hvcC in the init; macOS / the Simulator
     /// tolerate the mismatch. Deriving the string from the actual hvcC keeps master and init consistent.
+    /// AE#674: the highest `general_level_idc` a master's CODECS declares (5.1, which covers 2160p60).
+    /// Encoders stamp 5.2 (156) on 1080p24 streams, and AVPlayer screens a master variant's declared
+    /// level against the device: an Apple TV 4K refuses 5.2 with -11848 / CoreMedia -15517 on every
+    /// attempt, DV and reduced master alike, while the same bytes decode media-direct, where nothing
+    /// is declared. The init's hvcC keeps the stated level; only the attribute is capped. A stream
+    /// that genuinely needs more would end on the media playlist anyway, so capping costs it nothing.
+    static let maxDeclaredHEVCLevel = 153
+
     static func hevcCodecsString(
         fromConfigRecord hvcC: [UInt8],
         sampleEntry: String = "hvc1"
@@ -174,11 +182,7 @@ extension HLSVideoEngine {
         var trimmedConstraints = constraintBytes
         while let last = trimmedConstraints.last, last == 0 { trimmedConstraints.removeLast() }
         let tier = tierFlag == 1 ? "H" : "L"
-        // Some encoders stamp level 5.2 (156) on 1080p24 streams. AVPlayer screens a master's declared
-        // level against the device and refuses 5.2 on an Apple TV 4K (-11848, CoreMedia -15517), while
-        // the same bytes decode fine media-direct, where nothing is declared. Level 5.1 covers up to
-        // 2160p60, so the attribute declares no more than that; the init segment's hvcC is untouched.
-        let declaredLevel = min(levelIDC, 153)
+        let declaredLevel = min(Int(levelIDC), maxDeclaredHEVCLevel)
         var s = "\(sampleEntry).\(spacePrefix)\(profileIDC).\(compatHex).\(tier)\(declaredLevel)"
         if !trimmedConstraints.isEmpty {
             s += "." + trimmedConstraints.map { String(format: "%02x", $0) }.joined(separator: ".")
@@ -260,9 +264,9 @@ extension HLSVideoEngine {
             profile: codecpar.pointee.profile, level: codecpar.pointee.level)
     }
 
-    /// Derive the plain-HEVC CODECS string from the source hvcC (or the SPS of Annex-B extradata) when
-    /// parseable, else fall back to the legacy Main10 form. Used only by the non-DV `.none` / `.profile82` branch; DV variants keep their
-    /// deliberate `hvc1.2.4` (Main10 PQ base) declaration.
+    /// Derive the HEVC CODECS string from the source hvcC (or the SPS of Annex-B extradata) when
+    /// parseable, else fall back to the Main10 form. Every hvc1 route uses it, the DV ones included
+    /// (AE#674): their base layer is the hvcC in the init, so the master declares what that states.
     private func plainHEVCCodecs(
         codecpar: UnsafePointer<AVCodecParameters>,
         fallbackLevel hevcLevel: Int
@@ -481,7 +485,7 @@ extension HLSVideoEngine {
         let dvLevelRaw = Int(dvRecord?.dv_level ?? 0)
         let dvLevel = dvLevelRaw > 0 ? dvLevelRaw : 6
         let hevcLevelRaw = Int(codecpar.pointee.level)
-        let hevcLevel = hevcLevelRaw > 0 ? hevcLevelRaw : 150
+        let hevcLevel = hevcLevelRaw > 0 ? min(hevcLevelRaw, Self.maxDeclaredHEVCLevel) : 150
         let dvLevelStr = String(format: "%02d", dvLevel)
 
         if let r = dvRecord {
diff --git a/Tests/AetherEngineTests/Issue674HEVCLevelCapTests.swift b/Tests/AetherEngineTests/Issue674HEVCLevelCapTests.swift
new file mode 100644
index 000000000..0aafe1dbb
--- /dev/null
+++ b/Tests/AetherEngineTests/Issue674HEVCLevelCapTests.swift
@@ -0,0 +1,96 @@
+import Testing
+import Foundation
+import AetherLibavcodec
+import AetherLibavutil
+@testable import AetherEngine
+
+/// AE#674: a DV Profile 8.1 MKV whose hvcC states level 5.2 (156) on a 1080p24 picture. The level went
+/// into the master's CODECS verbatim, and an Apple TV 4K refused the DV master and the reduced HDR master
+/// with -11848 / CoreMedia -15517, ending on the media playlist with Dolby Vision dropped. Declared as
+/// 5.1 the same master is accepted and the panel engages DV (reporter, Sony X90L). The DV branches also
+/// hardcoded `hvc1.2.4.L<level>` and dropped the hvcC's constraint bytes, the disagreement AE#187 fixed
+/// for plain HEVC.
+@Suite("AE#674 declared HEVC level cap")
+struct Issue674HEVCLevelCapTests {
+
+    /// The reporter's hvcC header: profile_idc 2, compat 0x20000000, constraints 90 00.., level_idc 156.
+    static let duneHvcC: [UInt8] = [0x01, 0x02, 0x20, 0x00, 0x00, 0x00, 0x90,
+                                    0x00, 0x00, 0x00, 0x00, 0x00, 0x9c,
+                                    0xf0, 0x00, 0xfc, 0xfd, 0xfa, 0xfa, 0x00, 0x00, 0x0f, 0x00]
+
+    @Test("a stated level 5.2 is declared as 5.1")
+    func builderCapsLevel52() {
+        #expect(HLSVideoEngine.hevcCodecsString(fromConfigRecord: Self.duneHvcC) == "hvc1.2.4.L153.90")
+    }
+
+    @Test("levels up to 5.1 are declared as stated", arguments: [UInt8(93), 120, 150, 153])
+    func builderKeepsLowerLevels(level: UInt8) {
+        var hvcC = Self.duneHvcC
+        hvcC[12] = level
+        #expect(HLSVideoEngine.hevcCodecsString(fromConfigRecord: hvcC) == "hvc1.2.4.L\(level).90")
+    }
+
+    @Test("the DV Profile 8.1 route declares the capped level with the hvcC's constraint bytes")
+    func profile81RouteFromHvcC() throws {
+        let par = try Profile81Codecpar(level: 156, extradata: Self.duneHvcC)
+        let r = try Self.route(par)
+        #expect(r.primaryCodecs == "hvc1.2.4.L153.90")
+        #expect(r.supplementalCodecs == "dvh1.08.03/db1p")
+        #expect(r.dvVariant == .profile81)
+    }
+
+    @Test("without a parseable hvcC the fallback declaration is capped too")
+    func profile81RouteFallback() throws {
+        let par = try Profile81Codecpar(level: 156, extradata: nil)
+        #expect(try Self.route(par).primaryCodecs == "hvc1.2.4.L153")
+    }
+
+    // MARK: - Harness
+
+    private static func route(_ par: Profile81Codecpar) throws -> HLSVideoEngine.CodecRoute {
+        let engine = HLSVideoEngine(url: URL(fileURLWithPath: "/dev/null"), dvModeAvailable: true)
+        return try engine.resolveCodecRoute(codecpar: UnsafePointer(par.ptr))
+    }
+
+    /// 1920x802 HEVC with a DV Profile 8.1 (compat 1, dv_level 3) record, freed with the test.
+    private final class Profile81Codecpar {
+        let ptr: UnsafeMutablePointer<AVCodecParameters>
+
+        init(level: Int32, extradata: [UInt8]?) throws {
+            ptr = try #require(avcodec_parameters_alloc())
+            ptr.pointee.codec_type = AVMEDIA_TYPE_VIDEO
+            ptr.pointee.codec_id = AV_CODEC_ID_HEVC
+            ptr.pointee.width = 1920
+            ptr.pointee.height = 802
+            ptr.pointee.level = level
+            ptr.pointee.color_primaries = AVCOL_PRI_BT2020
+            ptr.pointee.color_trc = AVCOL_TRC_SMPTE2084
+            ptr.pointee.color_space = AVCOL_SPC_BT2020_NCL
+            if let bytes = extradata {
+                let ed = try #require(av_mallocz(bytes.count + Int(AV_INPUT_BUFFER_PADDING_SIZE)))
+                    .assumingMemoryBound(to: UInt8.self)
+                bytes.withUnsafeBufferPointer { ed.update(from: $0.baseAddress!, count: bytes.count) }
+                ptr.pointee.extradata = ed
+                ptr.pointee.extradata_size = Int32(bytes.count)
+            }
+            let size = MemoryLayout<AVDOVIDecoderConfigurationRecord>.size
+            let sd = try #require(av_packet_side_data_new(
+                &ptr.pointee.coded_side_data, &ptr.pointee.nb_coded_side_data,
+                AV_PKT_DATA_DOVI_CONF, size, 0))
+            memset(sd.pointee.data, 0, size)
+            sd.pointee.data.withMemoryRebound(to: AVDOVIDecoderConfigurationRecord.self, capacity: 1) { rec in
+                rec.pointee.dv_version_major = 1
+                rec.pointee.dv_profile = 8
+                rec.pointee.dv_level = 3
+                rec.pointee.rpu_present_flag = 1
+                rec.pointee.bl_present_flag = 1
+                rec.pointee.dv_bl_signal_compatibility_id = 1
+            }
+        }
+
+        deinit {
+            var p: UnsafeMutablePointer<AVCodecParameters>? = ptr
+            avcodec_parameters_free(&p)
+        }
+    }
+}

From 95b7c31d67858dee9ec677a98507464943141b8b Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 21:06:24 +0200
Subject: [PATCH 249/359] chore(release): prep 7.23.2 - HEVC level declared in
 the master is capped at 5.1

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                    | 6 ++++++
 Examples/README.md                              | 2 +-
 README.md                                       | 6 +++---
 Sources/AetherEngine/AetherEngine+Version.swift | 2 +-
 4 files changed, 11 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index fe1bcdff6..4be07d629 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,12 @@ the public-API contract.
 
 _Nothing yet._
 
+## [7.23.2] - 2026-09-30
+
+### Fixed
+
+- **A Dolby Vision master was refused when the source stated HEVC level 5.2 (#674).** Encoders stamp level 5.2 (156) on 1080p24 streams, the level went into the master's `CODECS` verbatim, and an Apple TV 4K screens a declared level against the device: the DV master and the reduced HDR master both failed with -11848 / CoreMedia -15517, and the session ended on the media playlist with Dolby Vision dropped. The declared level is now capped at 5.1 (`L153`, which covers 2160p60), for the hvcC-derived string and the fallback alike; the init's hvcC keeps the stated level. The DV routes (P8.1, P8.4, P7) also derive their `CODECS` from the hvcC now, so they carry its constraint bytes like the plain HEVC route has since AE#187. Contributed by @gonkowonko (#677).
+
 ## [7.23.1] - 2026-09-30
 
 ### Fixed
diff --git a/Examples/README.md b/Examples/README.md
index d8e586156..69abe01e5 100644
--- a/Examples/README.md
+++ b/Examples/README.md
@@ -18,7 +18,7 @@ Three samples covering different audiences:
    ```
    https://github.com/superuser404notfound/AetherEngine
    ```
-   Dependency Rule: Up to Next Major Version, starting from `7.23.1`. Add the `AetherEngine` library product to your app target.
+   Dependency Rule: Up to Next Major Version, starting from `7.23.2`. Add the `AetherEngine` library product to your app target.
 
 3. **Drop the file in.** Replace the Xcode template's default `App.swift` (or whatever the generated `@main` file is called) with the contents of [`MinimalPlayerApp.swift`](MinimalPlayer/MinimalPlayerApp.swift). The file is self-contained: it defines both the `@main App` struct and the `ContentView`.
 
diff --git a/README.md b/README.md
index 9267f66fd..6e81de4f1 100644
--- a/README.md
+++ b/README.md
@@ -384,7 +384,7 @@ Subtitle cues land in raw source PTS; render the overlay against `player.sourceT
 Install via Swift Package Manager:
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.23.1")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.23.2")
 ```
 
 Three samples ship in `Examples/`:
@@ -631,10 +631,10 @@ Browse all of this as a searchable site at **[aetherengine.superuser404.de](http
 AetherEngine uses [Semantic Versioning](https://semver.org). The public API surface, every `public` declaration in `Sources/AetherEngine/`, is the stability contract. **Major** removes / renames public symbols or breaks adopters; **Minor** adds public API or codec / format support; **Patch** fixes bugs with no public API change. `internal` types are not part of the contract.
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.23.1")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.23.2")
 ```
 
-Pin to `.upToNextMinor(from: "7.23.1")` for stricter teams that prefer to opt into minor bumps explicitly.
+Pin to `.upToNextMinor(from: "7.23.2")` for stricter teams that prefer to opt into minor bumps explicitly.
 
 ## Requirements
 
diff --git a/Sources/AetherEngine/AetherEngine+Version.swift b/Sources/AetherEngine/AetherEngine+Version.swift
index d277e023d..58dfa5296 100644
--- a/Sources/AetherEngine/AetherEngine+Version.swift
+++ b/Sources/AetherEngine/AetherEngine+Version.swift
@@ -11,5 +11,5 @@ extension AetherEngine {
     ///
     /// Between releases, and in a consumer that pins an unreleased commit for a device test, this
     /// names the last PUBLISHED version the checkout descends from, not every patch in it.
-    public nonisolated static let version = "7.23.1"
+    public nonisolated static let version = "7.23.2"
 }

From d6f4d399073d0dbfd2eaba65d86561032676138f Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 21:42:14 +0200
Subject: [PATCH 250/359] fix(live): the ingest join carries the loopback
 cushion, and the ingest honours the origin request budget (AE#678)

The served TARGETDURATION on an ingest is floored by the longest upstream segment
(ceil(longest / 1.5), AE#447), so a 10 s provider seals TD 7 and the first serve wants 21 s.
The join covered max(8, 1.5 x advertised TD), two 10 s segments, 19 s cut once the last GOP
stays open: short by construction for every segment above ~5 s, so every fastZap zap ended at
the bounded start's grace. The join now covers that holdback plus one GOP (bounded at 4 s).

HLSLiveIngestReader charged nothing to OriginRequestBudget and fetched four segments in
parallel, so maxConcurrentSourceRequests = 1 meant four connections to a single-connection
provider. Every playlist, segment and key fetch now takes a ticket, notes refusals and
redirects, and the prefetch window narrows to the origin's limit. A direct .custom ingest load
registers the declared ceiling on the playlist URL.

Measured, hlsfixture 10 s segments / 1 s GOP behind a proxy (50 ms, 40 Mbit/s shared),
play --live --fast-zap, 3 runs per arm:
- loopback: first picture t+2.24..2.52 s -> t+0.22 s, full cushion instead of bounded start
- 40 Mbit/s: t+4.11..4.39 s -> t+2.87..2.90 s
- single-connection proxy, --max-concurrent-requests 1: peak inflight 2 and two 429 per zap
  -> peak inflight 1, no refusal

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 Sources/AetherEngine/AetherEngine.swift       |  4 ++
 .../IO/HLSIngest/HLSLiveIngestReader.swift    | 67 +++++++++++++++++--
 .../IO/HLSIngest/HLSPlaylistTracker.swift     | 24 ++++++-
 .../HLSPlaylistTrackerTests.swift             | 44 ++++++++----
 .../Issue177IngestPrefetchTests.swift         | 32 +++++++++
 5 files changed, 148 insertions(+), 23 deletions(-)

diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index 9cff56189..ee2862db1 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -3898,6 +3898,10 @@ public final class AetherEngine: ObservableObject {
         // later reopen of the same source are bound by it too.
         if !isCustomSource {
             OriginRequestBudget.shared.setHostLimit(options.maxConcurrentSourceRequests, for: url)
+        } else if let ingest = customReader as? HLSLiveIngestReader {
+            // AE#678: the ingest fetches from the playlist's origin, not from `aether-custom://`.
+            OriginRequestBudget.shared.setHostLimit(
+                options.maxConcurrentSourceRequests, for: ingest.budgetOriginURL)
         }
         // #170: the carryover is consumed by THIS load only (registration site below, or never on
         // the branches that return before it); it must not persist into loadedOptions where a later
diff --git a/Sources/AetherEngine/IO/HLSIngest/HLSLiveIngestReader.swift b/Sources/AetherEngine/IO/HLSIngest/HLSLiveIngestReader.swift
index e272bbf06..905cc990b 100644
--- a/Sources/AetherEngine/IO/HLSIngest/HLSLiveIngestReader.swift
+++ b/Sources/AetherEngine/IO/HLSIngest/HLSLiveIngestReader.swift
@@ -65,6 +65,17 @@ public final class HLSLiveIngestReader: IOReader, LiveIngestSourceInfo, @uncheck
     /// fetches saturate the link while bounding in-memory segment bytes to the window size.
     static let maxConcurrentSegmentFetches = 4
 
+    /// AE#678: the prefetch window narrowed to the origin's request budget. A host that declares
+    /// `maxConcurrentSourceRequests = 1` for a single-connection provider meant every request this
+    /// reader makes, and four parallel segment fetches were four connections to it.
+    static func segmentFetchConcurrency(budgetLimit: Int?) -> Int {
+        guard let budgetLimit else { return maxConcurrentSegmentFetches }
+        return max(1, min(maxConcurrentSegmentFetches, budgetLimit))
+    }
+
+    /// The URL the host loaded, which is what `OriginRequestBudget` keys the declared ceiling on.
+    var budgetOriginURL: URL { playlistURL }
+
     /// First-segment classification latch; touched only from the ingest task's ordered commit path.
     private var sniffedFirstSegment = false
 
@@ -342,13 +353,15 @@ public final class HLSLiveIngestReader: IOReader, LiveIngestSourceInfo, @uncheck
             }
             return (segment, url)
         }
+        let window = Self.segmentFetchConcurrency(
+            budgetLimit: OriginRequestBudget.shared.limit(for: mediaURL))
         return try await withThrowingTaskGroup(of: (Int, Data).self) { group -> Bool in
             var nextToSpawn = 0
             var nextToCommit = 0
             var ready: [Int: Data] = [:]
 
             while nextToSpawn < resolved.count,
-                  nextToSpawn < nextToCommit + Self.maxConcurrentSegmentFetches {
+                  nextToSpawn < nextToCommit + window {
                 spawnFetch(into: &group, index: nextToSpawn, item: resolved[nextToSpawn], mediaURL: mediaURL)
                 nextToSpawn += 1
             }
@@ -375,7 +388,7 @@ public final class HLSLiveIngestReader: IOReader, LiveIngestSourceInfo, @uncheck
                     }
                 }
                 while nextToSpawn < resolved.count,
-                      nextToSpawn < nextToCommit + Self.maxConcurrentSegmentFetches {
+                      nextToSpawn < nextToCommit + window {
                     spawnFetch(into: &group, index: nextToSpawn, item: resolved[nextToSpawn], mediaURL: mediaURL)
                     nextToSpawn += 1
                 }
@@ -556,6 +569,40 @@ public final class HLSLiveIngestReader: IOReader, LiveIngestSourceInfo, @uncheck
         try await Task.sleep(nanoseconds: UInt64(delay * 1_000_000_000))
     }
 
+    /// AE#678: every ingest request is charged to `OriginRequestBudget` like the reader's and the relay's,
+    /// so the host's declared ceiling and a ceiling learned from a refusal bind this path too. The slot
+    /// wait blocks, so it runs off the cooperative pool; no ticket is ever held across another acquire.
+    private func budgeted(
+        _ url: URL, label: String, _ fetch: () async throws -> (Data, URLResponse)
+    ) async throws -> (Data, URLResponse) {
+        let ticket: OriginRequestBudget.Ticket? = await withCheckedContinuation { continuation in
+            DispatchQueue.global(qos: .userInitiated).async { [weak self] in
+                continuation.resume(returning: OriginRequestBudget.shared.acquire(
+                    for: url, label: label, timeout: Self.budgetSlotWaitSeconds,
+                    shouldAbort: { self?.isClosed ?? true }))
+            }
+        }
+        defer { OriginRequestBudget.shared.release(ticket) }
+        try Task.checkCancellation()
+        let (data, response) = try await fetch()
+        if let http = response as? HTTPURLResponse {
+            if let finalURL = http.url, finalURL != url {
+                OriginRequestBudget.shared.noteRedirect(from: url, to: finalURL)
+            }
+            if Self.refusalStatuses.contains(http.statusCode) {
+                OriginRequestBudget.shared.noteRefusal(
+                    for: http.url ?? url, status: http.statusCode,
+                    retryAfter: http.value(forHTTPHeaderField: "Retry-After").flatMap(TimeInterval.init))
+            }
+        }
+        return (data, response)
+    }
+
+    static let budgetSlotWaitSeconds: TimeInterval = 10
+    static let refusalStatuses: Set<Int> = [429, 503, 509]
+
+    private var isClosed: Bool { startLock.withLock { closed } }
+
     /// Applies the configured origin headers to every ingest fetch, credentials only where the host's
     /// origin is (audit NET-7). Internal for the header-contract tests.
     func makeRequest(_ url: URL) -> URLRequest {
@@ -569,8 +616,10 @@ public final class HLSLiveIngestReader: IOReader, LiveIngestSourceInfo, @uncheck
 
     /// Fetch + parse a playlist. Returns parsed playlist and final URL after redirects (relative segment URIs resolve against it).
     private func fetchPlaylist(_ url: URL) async throws -> (HLSPlaylist, URL) {
-        let (data, response) = try await BoundedPlaylistFetch.data(
-            for: makeRequest(url), session: session, limit: Self.maximumPlaylistBytes)
+        let (data, response) = try await budgeted(url, label: "ingest-playlist") {
+            try await BoundedPlaylistFetch.data(
+                for: self.makeRequest(url), session: self.session, limit: Self.maximumPlaylistBytes)
+        }
         let status = (response as? HTTPURLResponse)?.statusCode ?? -1
         guard (200..<300).contains(status) else {
             throw HLSIngestError.playlistUnreachable(status: status)
@@ -589,7 +638,9 @@ public final class HLSLiveIngestReader: IOReader, LiveIngestSourceInfo, @uncheck
             do {
                 let (data, response): (Data, URLResponse)
                 do {
-                    (data, response) = try await BoundedFetch.data(for: makeRequest(url), session: session, limit: limit)
+                    (data, response) = try await budgeted(url, label: "ingest-segment") {
+                        try await BoundedFetch.data(for: self.makeRequest(url), session: self.session, limit: limit)
+                    }
                 } catch is BoundedFetch.Exceeded {
                     // Audit NET-112: an endless body is the origin's answer, not a blip to retry.
                     throw HLSIngestError.playlistInvalid(reason: "segment exceeds \(limit) bytes")
@@ -629,8 +680,10 @@ public final class HLSLiveIngestReader: IOReader, LiveIngestSourceInfo, @uncheck
         let data: Data
         let response: URLResponse
         do {
-            (data, response) = try await BoundedFetch.data(
-                for: makeRequest(url), session: session, limit: BoundedFetch.keyLimit)
+            (data, response) = try await budgeted(url, label: "ingest-key") {
+                try await BoundedFetch.data(
+                    for: self.makeRequest(url), session: self.session, limit: BoundedFetch.keyLimit)
+            }
         } catch is BoundedFetch.Exceeded {
             throw HLSIngestError.segmentDecryptFailed(reason: "key exceeds \(BoundedFetch.keyLimit) bytes")
         }
diff --git a/Sources/AetherEngine/IO/HLSIngest/HLSPlaylistTracker.swift b/Sources/AetherEngine/IO/HLSIngest/HLSPlaylistTracker.swift
index 3e48c225a..c12015839 100644
--- a/Sources/AetherEngine/IO/HLSIngest/HLSPlaylistTracker.swift
+++ b/Sources/AetherEngine/IO/HLSIngest/HLSPlaylistTracker.swift
@@ -2,7 +2,7 @@ import Foundation
 
 /// Pure cursor over successive live playlist refreshes. Returns each segment exactly once. Handles join, forward growth, and window-slide (rejoin + discontinuity flag for downstream PTS rebase).
 ///
-/// Join policy: target duration coverage `max(minJoinCoverageSeconds, 1.5 * targetDuration)`, bounded by `edgeOffset` segments and by the eviction margin. Count-only join burst up to 36s of backlog on long-segment providers, which caused a one-time AVPlayer pacing stall a few seconds into every direct session (device repro 2026-06-11). The 1.5x term ensures at least one upstream cadence of buffer across the bursty inter-batch arrival gap (device repro 2026-06-11: ~5s stalls every ~20s with a single-segment join). A shrinking playlist (spec-violating server) is treated as a stall.
+/// Join policy: target duration coverage `max(minJoinCoverageSeconds, 1.5 * targetDuration, loopback cushion)`, bounded by `edgeOffset` segments and by the eviction margin. Count-only join burst up to 36s of backlog on long-segment providers, which caused a one-time AVPlayer pacing stall a few seconds into every direct session (device repro 2026-06-11). The 1.5x term ensures at least one upstream cadence of buffer across the bursty inter-batch arrival gap (device repro 2026-06-11: ~5s stalls every ~20s with a single-segment join). A shrinking playlist (spec-violating server) is treated as a stall.
 ///
 /// `edgeOffset` is a sanity bound on the burst, not the policy. It used to be 3, which is a COUNT standing in for a burst measured in SECONDS, and the coverage term above already bounds long segments on its own (6s segments break at 12s, 12s segments at 24s). So the count only ever bound SHORT segments, which are exactly the sources the 8s coverage floor was written for, and it cut them to a third of it. The cost was not only buffer: three joined segments yield only TWO finalized ones downstream, because the last one is still open until the next arrives, and the loopback startup cushion wants three. The live join therefore waited one upstream segment duration in wall clock for content the origin was already holding. Measured on `hlsfixture --window 8` with `play --live --fast-zap` (three runs per row, engine 6.76.1 against this change): first picture on a 2s-segment channel 2.22s before, 0.20s after; on 1s segments 0.41 to 1.22s before (it depended on where in the upstream segment cycle the tune landed) against 0.18 to 0.20s after, the phase dependency gone with it. A window three segments deep has nothing deeper to join into and is unchanged. The origin request log is what says the depth is not paid back later: both arms fetch up to the same upstream segment number at the same wall clock, so the burst is caught up at I/O speed rather than becoming a standing lag behind the live edge.
 struct HLSPlaylistTracker {
@@ -34,6 +34,25 @@ struct HLSPlaylistTracker {
         return min(edgeOffset, windowSegmentCount - 1)
     }
 
+    /// AE#678: the join has to carry the cushion the loopback's first serve will ask for, or every zap
+    /// ends at the bounded start's grace. The served TARGETDURATION is floored by the longest upstream
+    /// segment (`ceil(longest / 1.5)`, AE#447), so the gate wants `3 x` that, and `1.5 x TD` alone is
+    /// always a hair short of it: two 10 s segments are 20 s against a 21 s holdback. The last joined
+    /// segment's final GOP also stays open downstream until the next upstream segment arrives, so one
+    /// GOP of margin on top, bounded by the segment and by `openGOPMarginSeconds`. A whole segment of
+    /// margin would be the strict bound, and on a 10 s provider it is a fourth 10 s download the start
+    /// then waits for on a shared link (measured 3.7 s to first picture against 40 Mbit/s).
+    static func loopbackCushionCoverageSeconds(segments: [HLSMediaSegment]) -> Double {
+        guard let longest = segments.map(\.duration).max(), longest > 0 else { return 0 }
+        let targetDuration = LiveEdgePolicy.targetDurationForCadence(longest)
+        return LiveEdgePolicy.holdBackSeconds(targetDuration: targetDuration)
+            + min(longest, openGOPMarginSeconds)
+    }
+
+    /// Longest GOP the join margin plans for. IPTV and broadcast GOPs run 0.5 to 4 s; a longer one
+    /// only costs the bounded start's grace, which is what every join paid before AE#678.
+    static let openGOPMarginSeconds: Double = 4
+
     init(edgeOffset: Int = 8, minJoinCoverageSeconds: Double = 8) {
         self.edgeOffset = edgeOffset
         self.minJoinCoverageSeconds = minJoinCoverageSeconds
@@ -62,7 +81,8 @@ struct HLSPlaylistTracker {
         }
 
         func joinStart() -> Int {
-            let coverage = max(minJoinCoverageSeconds, 1.5 * playlist.targetDuration)
+            let coverage = max(minJoinCoverageSeconds, 1.5 * playlist.targetDuration,
+                               Self.loopbackCushionCoverageSeconds(segments: playlist.segments))
             let limit = Self.joinSegmentLimit(edgeOffset: edgeOffset,
                                               windowSegmentCount: playlist.segments.count)
             var taken = 0
diff --git a/Tests/AetherEngineTests/HLSPlaylistTrackerTests.swift b/Tests/AetherEngineTests/HLSPlaylistTrackerTests.swift
index b33128edb..836589b71 100644
--- a/Tests/AetherEngineTests/HLSPlaylistTrackerTests.swift
+++ b/Tests/AetherEngineTests/HLSPlaylistTrackerTests.swift
@@ -16,10 +16,11 @@ final class HLSPlaylistTrackerTests: XCTestCase {
     }
 
     func testPrimesAtLiveEdgeWithCoverageTarget() {
-        // 4s segments: coverage = max(8, 1.5*4) = 8s -> join takes exactly two segments.
+        // 4s segments: the loopback cushion wants 3 x ceil(4 / 1.5) = 9s plus a 4s GOP margin, so
+        // 13s; edgeOffset caps the join at three segments.
         var tracker = HLSPlaylistTracker(edgeOffset: 3, minJoinCoverageSeconds: 8)
         let new = tracker.newSegments(in: playlist(sequence: 100, uris: ["a", "b", "c", "d", "e", "f"]))
-        XCTAssertEqual(new.map(\.uri), ["e", "f"])
+        XCTAssertEqual(new.map(\.uri), ["d", "e", "f"])
         XCTAssertEqual(tracker.stallCount, 0)
     }
 
@@ -31,17 +32,19 @@ final class HLSPlaylistTrackerTests: XCTestCase {
     }
 
     func testPrimeCoversUpstreamCadenceForLongSegments() {
-        // 12s segments: coverage = max(8, 1.5*12) = 18s -> two segments (24s) cover a full upstream gap.
+        // 12s segments: 1.5 x 12 = 18s covers one upstream gap, but the loopback seals TD 8 and wants
+        // 24s + 4s of margin, so the whole three-segment window.
         var tracker = HLSPlaylistTracker(edgeOffset: 3, minJoinCoverageSeconds: 8)
         let new = tracker.newSegments(in: playlist(sequence: 50, uris: ["a", "b", "c"], duration: 12))
-        XCTAssertEqual(new.map(\.uri), ["b", "c"])
+        XCTAssertEqual(new.map(\.uri), ["a", "b", "c"])
     }
 
     func testPrimeCoversBurstyTenSecondUpstream() {
-        // Device-repro shape: 10s segments. Coverage = max(8, 1.5*10) = 15s -> two segments / 20s.
+        // Device-repro shape: 10s segments. 1.5 x 10 = 15s took two segments / 20s, one short of the
+        // 21s holdback TD 7 seals (AE#678); 21s + 4s of margin takes three.
         var tracker = HLSPlaylistTracker(edgeOffset: 3, minJoinCoverageSeconds: 8)
         let new = tracker.newSegments(in: playlist(sequence: 7, uris: ["a", "b", "c", "d"], duration: 10))
-        XCTAssertEqual(new.map(\.uri), ["c", "d"])
+        XCTAssertEqual(new.map(\.uri), ["b", "c", "d"])
     }
 
     func testPrimesAtWindowStartWhenWindowIsShort() {
@@ -71,9 +74,9 @@ final class HLSPlaylistTrackerTests: XCTestCase {
     func testWindowSlidePastCursorRejoinsAtEdgeWithDiscontinuity() {
         var tracker = HLSPlaylistTracker(edgeOffset: 3, minJoinCoverageSeconds: 8)
         _ = tracker.newSegments(in: playlist(sequence: 100, uris: ["a", "b", "c"]))
-        // Window slid past cursor: rejoin at edge (duration-capped to two 4s segments).
+        // Window slid past cursor: rejoin at edge with the same depth as a join (three 4s segments).
         let new = tracker.newSegments(in: playlist(sequence: 500, uris: ["x", "y", "z", "w", "v", "u"]))
-        XCTAssertEqual(new.map(\.uri), ["v", "u"])
+        XCTAssertEqual(new.map(\.uri), ["w", "v", "u"])
         XCTAssertTrue(new[0].discontinuityBefore, "rejoin must be marked as a discontinuity")
     }
 
@@ -87,7 +90,7 @@ final class HLSPlaylistTrackerTests: XCTestCase {
         XCTAssertTrue(tracker.newSegments(in: playlist(sequence: 0, uris: ["x", "y", "z"])).isEmpty)
         XCTAssertTrue(tracker.newSegments(in: playlist(sequence: 0, uris: ["x", "y", "z"])).isEmpty)
         let rejoined = tracker.newSegments(in: playlist(sequence: 0, uris: ["x", "y", "z"]))
-        XCTAssertEqual(rejoined.map(\.uri), ["y", "z"], "third consecutive regression rejoins at the new edge")
+        XCTAssertEqual(rejoined.map(\.uri), ["x", "y", "z"], "third consecutive regression rejoins at the new edge")
         XCTAssertTrue(rejoined[0].discontinuityBefore, "reset rejoin must be marked as a discontinuity")
         // Cursor continues normally on the new sequence axis.
         let next = tracker.newSegments(in: playlist(sequence: 1, uris: ["y", "z", "w"]))
@@ -151,14 +154,27 @@ final class HLSPlaylistTrackerTests: XCTestCase {
         XCTAssertEqual(new.map(\.uri), ["a", "b", "c"])
     }
 
-    func testDefaultJoinIsUnchangedForLongSegments() {
-        // The raised cap moves nothing here: the coverage term breaks a 6s-segment provider at 12s
-        // on its own, which is why the count was only ever binding on short segments.
+    func testDefaultJoinCoversTheLoopbackCushionForLongSegments() {
+        // AE#678: a 6s provider seals TD 4 downstream, so the first serve wants 12s, and two joined
+        // segments finalize only 12s minus the open GOP. The cushion term takes a third.
         var tracker = HLSPlaylistTracker()
         let new = tracker.newSegments(
             in: playlist(sequence: 3, uris: ["a", "b", "c", "d", "e", "f"], duration: 6)
         )
-        XCTAssertEqual(new.map(\.uri), ["e", "f"])
+        XCTAssertEqual(new.map(\.uri), ["d", "e", "f"])
+    }
+
+    func testLoopbackCushionCoverageIsTheSealedHoldbackPlusAGOP() {
+        func coverage(_ durations: [Double]) -> Double {
+            HLSPlaylistTracker.loopbackCushionCoverageSeconds(segments: durations.enumerated().map {
+                HLSMediaSegment(uri: "s\($0.offset)", duration: $0.element, discontinuityBefore: false)
+            })
+        }
+        XCTAssertEqual(coverage([10, 10, 10]), 25)       // TD 7, 21s holdback, 4s margin
+        XCTAssertEqual(coverage([12, 13.5, 12]), 31)     // TD 9 from the longest, 27s + 4s
+        XCTAssertEqual(coverage([2, 2, 2]), 8)           // TD 2, 6s + a 2s GOP bounded by the segment
+        XCTAssertEqual(coverage([1, 1, 1]), 4)           // below the 8s floor, which then decides
+        XCTAssertEqual(coverage([]), 0)
     }
 
     // audit NET-3: a MEDIA-SEQUENCE the parser somehow let through near Int.max used to trap
@@ -167,7 +183,7 @@ final class HLSPlaylistTrackerTests: XCTestCase {
     func testDoesNotTrapOnMediaSequenceNearIntMax() {
         var tracker = HLSPlaylistTracker(edgeOffset: 3, minJoinCoverageSeconds: 8)
         let new = tracker.newSegments(in: playlist(sequence: Int.max - 1, uris: ["a", "b", "c"]))
-        XCTAssertEqual(new.map(\.uri), ["b", "c"])
+        XCTAssertEqual(new.map(\.uri), ["a", "b", "c"])
     }
 
     func testJoinSegmentLimitAppliesTheMarginOnlyBelowTheCap() {
diff --git a/Tests/AetherEngineTests/Issue177IngestPrefetchTests.swift b/Tests/AetherEngineTests/Issue177IngestPrefetchTests.swift
index ee0512791..aac0ef0b6 100644
--- a/Tests/AetherEngineTests/Issue177IngestPrefetchTests.swift
+++ b/Tests/AetherEngineTests/Issue177IngestPrefetchTests.swift
@@ -285,6 +285,38 @@ struct Issue177IngestPrefetchTests {
         #expect(origin.concurrencyHighWater <= HLSLiveIngestReader.maxConcurrentSegmentFetches)
     }
 
+    @Test("a declared single-request origin gets its segments one at a time (AE#678)")
+    func declaredRequestCeilingSerializesTheBacklog() throws {
+        let segmentCount = 16
+        let segments = (0..<segmentCount).map { makeSegment(index: $0) }
+        var delays = [Int](repeating: 20, count: segmentCount)
+        delays[9] = 400
+        let origin = try #require(LoopbackHLSOrigin(
+            segments: segments, delaysMs: delays, initialWindow: 8))
+        defer { origin.stop() }
+
+        let url = try #require(URL(string: "http://127.0.0.1:\(origin.port)/media.m3u8"))
+        OriginRequestBudget.shared.setHostLimit(1, for: url)
+        defer { OriginRequestBudget.shared.setHostLimit(nil, for: url) }
+        let reader = HLSLiveIngestReader(playlistURL: url)
+        defer { reader.close() }
+
+        let expected = segments[1...].reduce(Data(), +)
+        let got = drain(reader, expectedBytes: expected.count, timeout: 90)
+
+        #expect(reader.terminalError == nil)
+        #expect(got == expected)
+        #expect(origin.concurrencyHighWater == 1, "the ingest overran the host's declared request ceiling")
+    }
+
+    @Test("the prefetch window narrows to the origin's request budget")
+    func prefetchWindowFollowsTheBudget() {
+        #expect(HLSLiveIngestReader.segmentFetchConcurrency(budgetLimit: nil) == 4)
+        #expect(HLSLiveIngestReader.segmentFetchConcurrency(budgetLimit: 1) == 1)
+        #expect(HLSLiveIngestReader.segmentFetchConcurrency(budgetLimit: 2) == 2)
+        #expect(HLSLiveIngestReader.segmentFetchConcurrency(budgetLimit: 12) == 4)
+    }
+
     @Test("single-segment playlists still ingest correctly through the pipeline")
     func singleSegmentStillWorks() throws {
         let segments = [makeSegment(index: 7)]

From 75f81a3c5b4990fb7ba18df93b0268e5b5df7cea Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 21:58:15 +0200
Subject: [PATCH 251/359] fix(live): known HLS URLs skip the raw probe,
 criteria cleared by the host are written again, and every open states its
 timings (AE#678)

- A live URL with a .m3u8/.m3u path, or one that already took the AE#363 route in this process,
  goes straight onto the ingest instead of spending a discarded raw request per zap.
- DisplayCriteriaController reads preferredDisplayCriteria back before the unchanged skip, so a
  host that cleared it itself (leaving full screen) gets its frame rate on the next same-format
  load instead of the UI mode.
- [Demuxer] open timings: connect / open_input / find_stream_info / total, stream count and probe
  budget, also when the stream analysis fails.
- LoadOptions.probesize no longer claims an over-tight budget always fails open.

Measured against a proxy that answers a second concurrent request with 403 (--max-concurrent-requests 1,
10 s segments, 40 Mbit/s): main fails 3 of 3 zaps with the reporter's exact line, 'probe failed
(Demuxer: stream info failed (Operation not permitted (-1)))' after '[HLSIngest] terminal:
playlistUnreachable(403)'; this branch plays 3 of 3 at t+3.54..3.71 s with peak inflight 1.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                  | 10 +++-
 Sources/AetherEngine/AetherEngine.swift       | 21 +++++++
 Sources/AetherEngine/Demuxer/Demuxer.swift    | 58 +++++++++++++++++--
 .../Display/DisplayCriteriaController.swift   | 20 ++++++-
 .../Native/RemoteHLSMediaSelection.swift      | 28 +++++++++
 Sources/AetherEngine/PlayerState.swift        |  2 +-
 .../DisplayCriteriaUnchangedSkipTests.swift   | 12 ++++
 .../KnownLivePlaylistRouteTests.swift         | 29 ++++++++++
 docs/api.md                                   |  4 +-
 9 files changed, 172 insertions(+), 12 deletions(-)
 create mode 100644 Tests/AetherEngineTests/KnownLivePlaylistRouteTests.swift

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4be07d629..e627d2886 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,7 +10,15 @@ the public-API contract.
 
 ## [Unreleased]
 
-_Nothing yet._
+### Fixed
+
+- **`.fastZap` on an HLS upstream with long segments always ended at the bounded start (#678).** The served TARGETDURATION on an ingest is floored by the longest upstream segment (`ceil(longest / 1.5)`, AE#447), so a 10 s provider seals 7 and the first serve wants 21 s, but the join covered `1.5 x` the advertised target duration: two 10 s segments, 19 s once the last GOP stays open. Short by construction for every segment above ~5 s, so every zap waited out the grace on content the origin already held. The join now covers that holdback plus one GOP (at most 4 s). Measured on 10 s segments: first picture t+2.2 to 2.5 s -> t+0.22 s on loopback, t+4.1 to 4.4 s -> t+2.9 s behind a 40 Mbit/s link.
+- **The HLS live ingest ignored `maxConcurrentSourceRequests` (#678).** It charged nothing to the origin request budget and fetched four segments in parallel, so a host declaring `1` for a single-connection provider still opened four requests to it. Playlist, segment and key fetches now take a budget ticket, report refusals and redirects, and the prefetch window narrows to the limit; a direct `.custom(HLSLiveIngestReader(...))` load registers the ceiling on its playlist URL.
+- **A same-format load kept the panel in its UI mode after the host cleared the display criteria itself (#678).** The unchanged skip compared against the engine's own record only; it now also reads `preferredDisplayCriteria` back and writes again when it finds nothing set.
+
+### Added
+
+- **`[Demuxer] open timings`** on every playback, probe and restart open: connect, `open_input` and `find_stream_info` separately, the stream count and the probe budget, also when the stream analysis fails (#678).
 
 ## [7.23.2] - 2026-09-30
 
diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index ee2862db1..ce544c171 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -4097,6 +4097,26 @@ public final class AetherEngine: ObservableObject {
             + (options.panelPresentsDolbyVision ? " (session dv asserted true)" : ""),
             category: .session
         )
+        if options.isLive, !options.nativeRemoteHLS, case .url(let livePlaylistURL) = source,
+           RemoteHLSMediaSelection.isKnownLivePlaylist(livePlaylistURL) {
+            EngineLog.emit(
+                "[AetherEngine] AE#678: known HLS playlist URL on the live path; straight onto the "
+                + "live-ingest reader, no raw probe",
+                category: .engine
+            )
+            continueStartupAcrossReroute()
+            return try await load(
+                source: .custom(
+                    HLSLiveIngestReader(playlistURL: livePlaylistURL,
+                                        httpHeaders: loadedOptions.httpHeaders),
+                    formatHint: "mpegts"
+                ),
+                startPosition: startPosition,
+                options: loadedOptions,
+                audioSourceStreamIndex: audioSourceStreamIndex,
+                discTitleID: discTitleID
+            )
+        }
         let probe = Demuxer()
         // Register so stopInternal can markClosed(): avformat_open_input/find_stream_info can block for the
         // full AVIOReader reconnect budget (device repro: a 500-looping channel kept reconnecting across three
@@ -4265,6 +4285,7 @@ public final class AetherEngine: ObservableObject {
                 + "live-ingest reader (headers ride every fetch)",
                 category: .engine
             )
+            RemoteHLSMediaSelection.noteLivePlaylist(livePlaylistURL)
             // #361: the host is still waiting for the load it asked for, so this is the same startup
             // taking a different route, not a second one.
             continueStartupAcrossReroute()
diff --git a/Sources/AetherEngine/Demuxer/Demuxer.swift b/Sources/AetherEngine/Demuxer/Demuxer.swift
index 17fa29e68..327d8cc72 100644
--- a/Sources/AetherEngine/Demuxer/Demuxer.swift
+++ b/Sources/AetherEngine/Demuxer/Demuxer.swift
@@ -399,6 +399,51 @@ public final class Demuxer: @unchecked Sendable {
     /// leaves it nil and emits nothing.
     var onOpenProgress: (@Sendable (DemuxerOpenStage) -> Void)?
 
+    /// AE#678: when this open started and when each stage finished, for the one timing line an open
+    /// emits. `#361`'s checkpoints carry the same boundaries to the host, but only as a ladder with no
+    /// durations, and a downstream integrator had to guess whether the connect, the container or the
+    /// stream analysis was the slow leg.
+    private var openStartedAt: DispatchTime?
+    private var openStageTimes: [DemuxerOpenStage: DispatchTime] = [:]
+
+    private func beginOpenTiming() {
+        openStartedAt = DispatchTime.now()
+        openStageTimes = [:]
+    }
+
+    private func reportOpenStage(_ stage: DemuxerOpenStage) {
+        openStageTimes[stage] = DispatchTime.now()
+        onOpenProgress?(stage)
+        if stage == .streamsProbed { emitOpenTimings(outcome: nil) }
+    }
+
+    /// Stills and the subtitle side reader open far too often to narrate, and the latter skips the
+    /// stream analysis the line exists to time.
+    private var reportsOpenTimings: Bool {
+        openProfile.readerLabel != DemuxerOpenProfile.stillExtraction.readerLabel && !openProfile.skipStreamInfo
+    }
+
+    private func emitOpenTimings(outcome: String?) {
+        guard reportsOpenTimings, let start = openStartedAt else { return }
+        openStartedAt = nil
+        func ms(_ from: DispatchTime?, _ to: DispatchTime?) -> String {
+            guard let from, let to, to.uptimeNanoseconds >= from.uptimeNanoseconds else { return "-" }
+            return "\((to.uptimeNanoseconds - from.uptimeNanoseconds) / 1_000_000)ms"
+        }
+        let source = openStageTimes[.sourceOpened]
+        let container = openStageTimes[.containerOpened]
+        let probed = openStageTimes[.streamsProbed] ?? (outcome == nil ? nil : DispatchTime.now())
+        let streams = formatContext.map { Int($0.pointee.nb_streams) } ?? 0
+        EngineLog.emit(
+            "[Demuxer] open timings (\(openProfile.readerLabel)): connect \(ms(start, source)), "
+            + "open_input \(ms(source ?? start, container)), find_stream_info \(ms(container, probed)), "
+            + "total \(ms(start, probed)); \(streams) stream(s), probesize \(openProfile.probesize / 1_048_576) MiB, "
+            + "analyzeduration \(openProfile.maxAnalyzeDuration / 1_000_000) s"
+            + (outcome.map { "; \($0)" } ?? ""),
+            category: .demux
+        )
+    }
+
     // MARK: - Disc titles / chapters (#67)
 
     private(set) var discTitles: [DiscTitle] = []
@@ -577,6 +622,7 @@ public final class Demuxer: @unchecked Sendable {
     func open(url: URL, extraHeaders: [String: String] = [:], profile: DemuxerOpenProfile = .playback, isLive: Bool = false, selectTitleID: Int? = nil) throws {
         if isCloseRequested { throw DemuxerError.openFailed(code: -1) }
         self.openProfile = profile
+        beginOpenTiming()
         self.auditSource = isLive ? nil : (url, extraHeaders)
         let isHTTP = url.scheme == "http" || url.scheme == "https"
 
@@ -618,13 +664,13 @@ public final class Demuxer: @unchecked Sendable {
         formatContext = openedCtx
         // #361: a local file has no connection to come up, so the source stage is credited by this
         // one rather than reported separately.
-        onOpenProgress?(.containerOpened)
+        reportOpenStage(.containerOpened)
 
         try probeStreams(openedCtx)
         accessLock.lock()
         refreshStreamTableLocked()
         accessLock.unlock()
-        onOpenProgress?(.streamsProbed)
+        reportOpenStage(.streamsProbed)
     }
 
     /// Open a custom `IOReader` source. `formatHint` disambiguates probing when
@@ -635,6 +681,7 @@ public final class Demuxer: @unchecked Sendable {
     func open(reader: IOReader, formatHint: String? = nil, profile: DemuxerOpenProfile = .playback, isLive: Bool = false, selectTitleID: Int? = nil, discCacheKey: String? = nil) throws {
         if isCloseRequested { throw DemuxerError.openFailed(code: -1) }
         self.openProfile = profile
+        beginOpenTiming()
         self.auditSource = nil
         if reader.discImageProbeEnabled,
            let discInfo = try DiscReader.wrap(reader, selectTitleID: selectTitleID, cacheKey: discCacheKey) {
@@ -746,7 +793,7 @@ public final class Demuxer: @unchecked Sendable {
             abandonProvider(provider)
             throw DemuxerError.openFailed(code: -1)
         }
-        onOpenProgress?(.sourceOpened)   // #361
+        reportOpenStage(.sourceOpened)   // #361
 
         // AE#460 follow-up: a live source rebuilt on a RETAINED reader resumes where that reader
         // is, not at the host's base. A fresh AVIOContext starts its byte axis at 0 regardless, so
@@ -823,14 +870,14 @@ public final class Demuxer: @unchecked Sendable {
             throw DemuxerError.openFailed(code: ret)
         }
         formatContext = ctxPtr  // avformat_open_input may reallocate
-        onOpenProgress?(.containerOpened)   // #361
+        reportOpenStage(.containerOpened)   // #361
         declareDiscSubpictureStreams(ctxPtr!)
 
         try probeStreams(ctxPtr!)
         accessLock.lock()
         refreshStreamTableLocked()
         accessLock.unlock()
-        onOpenProgress?(.streamsProbed)     // #361
+        reportOpenStage(.streamsProbed)     // #361
         // #281: every parse seek this open performs has happened by now, so the provider can drop
         // the cold-start state that only exists to serve them. Deliberately after probeStreams:
         // find_stream_info is where the trailing-index ping-pong lives, not avformat_open_input.
@@ -973,6 +1020,7 @@ public final class Demuxer: @unchecked Sendable {
         let findRet = avformat_find_stream_info(ctx, nil)
         unparkUnresolvableAudio(ctx, parked)
         guard findRet >= 0 else {
+            emitOpenTimings(outcome: "find_stream_info failed (\(findRet))")
             throw DemuxerError.streamInfoFailed(code: findRet)
         }
         logStreams(ctx)
diff --git a/Sources/AetherEngine/Display/DisplayCriteriaController.swift b/Sources/AetherEngine/Display/DisplayCriteriaController.swift
index 0b0bb5504..8d1d181e6 100644
--- a/Sources/AetherEngine/Display/DisplayCriteriaController.swift
+++ b/Sources/AetherEngine/Display/DisplayCriteriaController.swift
@@ -72,8 +72,14 @@ final class DisplayCriteriaController {
 
     /// #133 pure decision: skip only when we previously applied (`didApply`) exactly these criteria and have
     /// not reset since. Otherwise write, returning whether a dynamic-range switch is expected (HDR) or not (SDR).
-    nonisolated static func applyOutcome(didApply: Bool, last: AppliedCriteria?, target: AppliedCriteria) -> ApplyResult {
-        if didApply, last == target { return .unchanged }
+    ///
+    /// AE#678: `managerHoldsCriteria` is the display manager's own answer. A host that wrote
+    /// `preferredDisplayCriteria = nil` itself (leaving full screen for a preview) leaves `lastApplied`
+    /// describing criteria the panel no longer has, and the skip then kept the UI mode on a channel that
+    /// needed its frame rate.
+    nonisolated static func applyOutcome(didApply: Bool, last: AppliedCriteria?, target: AppliedCriteria,
+                                         managerHoldsCriteria: Bool = true) -> ApplyResult {
+        if didApply, managerHoldsCriteria, last == target { return .unchanged }
         return target.isHDR ? .willSwitch : .applied
     }
 
@@ -794,7 +800,15 @@ final class DisplayCriteriaController {
                 category: .engine
             )
         }
-        if case .unchanged = Self.applyOutcome(didApply: didApply, last: lastApplied, target: target) {
+        let managerHoldsCriteria = displayManager.preferredDisplayCriteria != nil
+        if didApply, !managerHoldsCriteria {
+            EngineLog.emit(
+                "[DisplayCriteria] criteria were cleared outside the engine since its last SET; writing again",
+                category: .engine
+            )
+        }
+        if case .unchanged = Self.applyOutcome(didApply: didApply, last: lastApplied, target: target,
+                                               managerHoldsCriteria: managerHoldsCriteria) {
             // Keep lastCriteriaWasHDR consistent with the still-active criteria for any waitForSwitch classification.
             lastCriteriaWasHDR = isHDR
             EngineLog.emit(
diff --git a/Sources/AetherEngine/Native/RemoteHLSMediaSelection.swift b/Sources/AetherEngine/Native/RemoteHLSMediaSelection.swift
index d9e0307cd..addb12117 100644
--- a/Sources/AetherEngine/Native/RemoteHLSMediaSelection.swift
+++ b/Sources/AetherEngine/Native/RemoteHLSMediaSelection.swift
@@ -96,6 +96,34 @@ enum RemoteHLSMediaSelection {
     /// Same two guards as the VOD side: only the typed misroute, and only for URL sources, because a
     /// custom reader has no playlist URL to ingest from and keeps the typed rejection. The reader only
     /// classifies as `hlsPlaylistOnRawLivePath` on the live path, so `isLive` needs no guard here.
+    /// AE#678: a live URL already known to answer with a playlist goes straight onto the ingest. The
+    /// raw path would open it, read `#EXTM3U`, throw it away and send the load around through AE#363,
+    /// which is one discarded request per zap, and against a single-connection origin one more request
+    /// the ingest's own playlist fetch has to queue behind. Known means a `.m3u8` / `.m3u` path, or a
+    /// URL that has taken the AE#363 route in this process before (IPTV channel URLs often carry no
+    /// extension at all). Keyed on the whole URL: one Xtream path serves TS or HLS depending on its query.
+    static func isKnownLivePlaylist(_ url: URL) -> Bool {
+        if ["m3u8", "m3u"].contains(url.pathExtension.lowercased()) { return true }
+        return knownPlaylistLock.withLock { knownPlaylistURLs.contains(url.absoluteString) }
+    }
+
+    static func noteLivePlaylist(_ url: URL) {
+        knownPlaylistLock.withLock {
+            let key = url.absoluteString
+            knownPlaylistURLs.removeAll { $0 == key }
+            knownPlaylistURLs.append(key)
+            if knownPlaylistURLs.count > knownPlaylistCapacity { knownPlaylistURLs.removeFirst() }
+        }
+    }
+
+    static func forgetKnownLivePlaylistsForTesting() {
+        knownPlaylistLock.withLock { knownPlaylistURLs.removeAll() }
+    }
+
+    private static let knownPlaylistLock = NSLock()
+    nonisolated(unsafe) private static var knownPlaylistURLs: [String] = []
+    private static let knownPlaylistCapacity = 512
+
     static func shouldRouteLiveOntoIngest(failure: Error?, isCustomSource: Bool) -> Bool {
         guard !isCustomSource,
               let readerError = failure as? AVIOReaderError,
diff --git a/Sources/AetherEngine/PlayerState.swift b/Sources/AetherEngine/PlayerState.swift
index b1fc8d63f..4b37d5824 100644
--- a/Sources/AetherEngine/PlayerState.swift
+++ b/Sources/AetherEngine/PlayerState.swift
@@ -735,7 +735,7 @@ public struct LoadOptions: Sendable, Equatable {
     /// window length outright). nil keeps the demuxer's own value. Default nil.
     public var declaredDurationSeconds: Double? = nil
 
-    /// Caller-bounded demux probe budget in bytes, mapped to `AVFormatContext.probesize` for the main playback open. nil keeps the engine default (50 MB). A smaller value speeds `find_stream_info` on slow remote sources whose sparse streams (PGS, mjpeg cover art) would otherwise read to the full budget. An over-tight budget fails OPEN, not closed: `find_stream_info` still returns success with a logged warning, so the session loads with late-resolving tracks silently missing rather than throwing a load error. The value is written to the context verbatim (FFmpeg's AVOption floor of 32 is bypassed), so validate track presence after load if you set this aggressively. The routing `probe(url:)` API and still extraction keep the full budget; the embedded subtitle side-demuxer caps its own probe (it only needs codec ids, not resolved sparse tracks) and tightens to this value when it is smaller (#76). Default nil (#68).
+    /// Caller-bounded demux probe budget in bytes, mapped to `AVFormatContext.probesize` for the main playback open. nil keeps the engine default (50 MB). A smaller value speeds `find_stream_info` on slow remote sources whose sparse streams (PGS, mjpeg cover art) would otherwise read to the full budget. An over-tight budget fails OPEN only while some stream resolves inside it: `find_stream_info` then returns success with a logged warning, and the session loads with late-resolving tracks silently missing. When NO stream resolves inside the budget it returns an error (`-1`, rendered "Operation not permitted") and the load throws. `[Demuxer] open timings` prints the connect / open_input / find_stream_info split of every open, which is the measurement to take before and after tightening it (AE#678). The value is written to the context verbatim (FFmpeg's AVOption floor of 32 is bypassed), so validate track presence after load if you set this aggressively. The routing `probe(url:)` API and still extraction keep the full budget; the embedded subtitle side-demuxer caps its own probe (it only needs codec ids, not resolved sparse tracks) and tightens to this value when it is smaller (#76). Default nil (#68).
     public var probesize: Int64?
 
     /// Caller-bounded demux probe budget in microseconds, mapped to `AVFormatContext.max_analyze_duration` for the main playback open. nil keeps the engine default (60 s). Pass a positive value to set an explicit cap; do NOT pass `0` expecting "no cap": FFmpeg maps `0` to a container-dependent heuristic (~5-7 s for MPEG-TS, longer elsewhere) that is SHORTER than the engine's 60 s default. Same scope and fail-open trade-off as `probesize`. Default nil (#68).
diff --git a/Tests/AetherEngineTests/DisplayCriteriaUnchangedSkipTests.swift b/Tests/AetherEngineTests/DisplayCriteriaUnchangedSkipTests.swift
index 5728beeb6..4d792d004 100644
--- a/Tests/AetherEngineTests/DisplayCriteriaUnchangedSkipTests.swift
+++ b/Tests/AetherEngineTests/DisplayCriteriaUnchangedSkipTests.swift
@@ -69,4 +69,16 @@ struct DisplayCriteriaUnchangedSkipTests {
         #expect(DisplayCriteriaController.applyOutcome(
             didApply: false, last: nil, target: sdr50()) == .applied)
     }
+
+    @Test("Identical criteria are written again when the display manager no longer holds any (AE#678)")
+    func hostClearedCriteriaAreRewritten() {
+        // A host that nils preferredDisplayCriteria itself (leaving full screen) left lastApplied stale,
+        // and the next same-format load kept the panel in its UI mode.
+        #expect(DisplayCriteriaController.applyOutcome(
+            didApply: true, last: sdr50(), target: sdr50(), managerHoldsCriteria: false) == .applied)
+        let hdr = DisplayCriteriaController.AppliedCriteria(
+            isHDR: true, effectiveRate: 50, codecType: dvh1, hasExtensions: true)
+        #expect(DisplayCriteriaController.applyOutcome(
+            didApply: true, last: hdr, target: hdr, managerHoldsCriteria: false) == .willSwitch)
+    }
 }
diff --git a/Tests/AetherEngineTests/KnownLivePlaylistRouteTests.swift b/Tests/AetherEngineTests/KnownLivePlaylistRouteTests.swift
new file mode 100644
index 000000000..dbd00de37
--- /dev/null
+++ b/Tests/AetherEngineTests/KnownLivePlaylistRouteTests.swift
@@ -0,0 +1,29 @@
+import Testing
+import Foundation
+@testable import AetherEngine
+
+/// AE#678: a live URL known to answer with a playlist skips the raw probe and its discarded request.
+@Suite("Known live HLS playlist routing (AE#678)", .serialized)
+struct KnownLivePlaylistRouteTests {
+
+    @Test("an m3u8 or m3u path is known without having been seen")
+    func extensionIsEnough() throws {
+        RemoteHLSMediaSelection.forgetKnownLivePlaylistsForTesting()
+        #expect(RemoteHLSMediaSelection.isKnownLivePlaylist(try #require(URL(string: "http://p.example/live/1/index.m3u8?token=a"))))
+        #expect(RemoteHLSMediaSelection.isKnownLivePlaylist(try #require(URL(string: "http://p.example/list.M3U"))))
+        #expect(!RemoteHLSMediaSelection.isKnownLivePlaylist(try #require(URL(string: "http://p.example/live/u/p/1.ts"))))
+    }
+
+    @Test("an extensionless channel URL is known once it has taken the AE#363 route")
+    func rerouteIsRemembered() throws {
+        RemoteHLSMediaSelection.forgetKnownLivePlaylistsForTesting()
+        let channel = try #require(URL(string: "http://p.example/live/u/p/1234"))
+        #expect(!RemoteHLSMediaSelection.isKnownLivePlaylist(channel))
+        RemoteHLSMediaSelection.noteLivePlaylist(channel)
+        #expect(RemoteHLSMediaSelection.isKnownLivePlaylist(channel))
+        // The whole URL is the key: one Xtream path serves TS or HLS depending on its query.
+        let tsVariant = try #require(URL(string: "http://p.example/live/u/p/1234?output=ts"))
+        #expect(!RemoteHLSMediaSelection.isKnownLivePlaylist(tsVariant))
+        RemoteHLSMediaSelection.forgetKnownLivePlaylistsForTesting()
+    }
+}
diff --git a/docs/api.md b/docs/api.md
index 4e29c6923..2d41d7364 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -971,7 +971,7 @@ All flags default to safe values; the table is the full set. Depth for the media
 | `preserveASSMarkup` | false | Emit raw ASS event lines instead of extracted text; pair with `TrackInfo.assHeader`. ASS / SSA codecs only, embedded and sidecar alike, so a session mixing an ASS track with a SubRip one needs no reload to cross between them (AE#587). |
 | `teletextPage` | nil | Fix the DVB teletext caption page instead of letting libzvbi auto-detect. |
 | `audioDelaySeconds` | 0 | Start the session with a lip-sync offset already in force; positive presents audio later. Same value `setAudioDelay(_:)` reads and writes, and a `reloadAtCurrentPosition(applying:)` can correct it. |
-| `suppressDisplayCriteria` | false | Skip the display-criteria handshake entirely. For previews and headless runs. |
+| `suppressDisplayCriteria` | false | Skip the display-criteria handshake entirely. For previews and headless runs. A host that clears `preferredDisplayCriteria` itself between loads (leaving full screen for a preview) no longer strands the engine's same-format skip: the next non-suppressed load reads the display manager, finds nothing set and writes again (AE#678). Clearing through `stop()` stays the cleaner path, because it resets the engine's record in the same step. |
 | `matchContentEnabled` | true | Mirror of `AVDisplayManager.isDisplayCriteriaMatchingEnabled`. False routes HDR through the auto-tonemap path. |
 | `panelIsInHDRMode` | false | **Host assertion** that the panel is presenting HDR right now, and the gate on whether the HDR10-to-DV upgrade is accepted upfront. It is an OR term over the engine's own readout on every platform, not a replacement for it and no longer confined to `suppressDisplayCriteria` hosts (AE#459). The readout it backs up is `currentEDRHeadroom > 1`, which answers only around a dynamic-range transition: an Apple TV whose output format is locked to HDR never makes one and reads as an SDR panel forever, and on tvOS 27 the property has stopped answering at all on at least one box. A wrong assertion costs one in-place media-playlist fallback (`-11848`), not the item. An in-place rebuild (an audio pick, a custom-source reload) runs no handshake, so it routes on the load's readout and display eligibility together with the session's current assertion and the refusal latch, rather than on this option alone (AE#541). |
 | `attemptsHDRMasterOnUnprovenPanel` | true | Serve the HDR master to an HDR-eligible display whose panel state is unproven, and let AVFoundation's acceptance or refusal be the readout `UIScreen` will not give (AE#459). VOD only. The proxy this replaces is `currentEDRHeadroom`, which is measurably unreliable: on one Apple TV 4K 3rd gen on tvOS 26.6 it read a flat 1.00 across 46 samples of HDR content while the TV's own info display reported HDR, and later the same day, same box, same output format, same title, it read 1.20. The panel was presenting HDR and the property was wrong about it; what moves it is not established. What media-direct costs there is not the picture but the manifest: the SUBTITLES rendition, the AUDIO rendition that is the only place AVFoundation reads an HLS language from, and SUPPLEMENTAL-CODECS. A panel that proves itself through the headroom short-circuits and attempts nothing. A refusal costs one in-place media fallback, measured at 223 ms end to end (`-11868` after 54 ms, zero `errorLog` events, position kept, no visible black frame), and is latched for the process, so a genuinely SDR display pays it once rather than per title. Set it false on a host that knows its display is SDR. Live never attempts regardless: a live fallback is a rejoin at the edge rather than a restored position, and that cost is unmeasured. The published `videoFormat` is not moved by an ATTEMPT. It is moved by an ACCEPTANCE: a master AVFoundation has not refused after the settle window publishes the presented format, which is a stronger reading than the headroom rather than a substitute for it. |
@@ -988,7 +988,7 @@ All flags default to safe values; the table is the full set. Depth for the media
 | `forwardBufferSegments` | nil (10, about 40 s) | How far the producer may race ahead and how much the cache keeps resident. Clamped to 4...2700; past the historical 150 the real bound is the session's disk budget, so a "buffer without limit" option can pass `Int.max`. Ignored on `nativeRemoteHLS`. Native HLS retention is readable as `$residentRanges` (see Time). Software VOD uses the same forward-window and volume-budget policy for compressed packet read-ahead; its continuous selected A/V frontier is `bufferedPosition`, not native `residentRanges`. |
 | `sequentialOrigin` | false | Declare an origin that fabricates range answers: one long-lived unranged GET, no ranged probes, non-seekable pb. **Seeking is unavailable**; re-request the archive at a shifted start instead. A URL source the reader finds forward-only by itself (`Range` ignored, so it can only stream front to back; the open confirms a 200 answer with a one byte range, because some CDNs answer a cache miss that way) is served this way without the declaration when its container states a duration, which a stated `Content-Length` lets an MPEG-TS source estimate; `loadedOptions` then reads `true` with that duration declared, and without a duration it stays on the software path. An AirPlay hop on such a session swaps the item onto the LAN address instead of reopening the source, since a reopen could only start again from byte 0. |
 | `declaredDurationSeconds` | nil | Trusted duration, overriding the container's. Required alongside `sequentialOrigin` on VOD, where the tail read is gone. |
-| `maxConcurrentSourceRequests` | nil | Most requests the reader may have open against this origin at once, across every path it fetches on (pump ranges, detour blocks, size probes, tail prefetch, subtitle side reader). nil counts without capping and lowers the ceiling on its own after a 429/503/509. Set it when the provider states a limit; `1` also switches off the speculative parallel paths, which exist only to overlap with the pump. Counts **requests**, not TCP connections, because over HTTP/2 a session multiplexes every request onto one connection while the origin still counts each one (AE#377). It is also the only ceiling: several engines playing from one origin are bounded by this value and by what the origin refuses, not by a transport pool underneath it (AE#450). |
+| `maxConcurrentSourceRequests` | nil | Most requests the reader may have open against this origin at once, across every path it fetches on (pump ranges, detour blocks, size probes, tail prefetch, subtitle side reader, and the HLS live ingest's playlist, segment and key fetches, whose prefetch window narrows to it, AE#678). nil counts without capping and lowers the ceiling on its own after a 429/503/509. Set it when the provider states a limit; `1` also switches off the speculative parallel paths, which exist only to overlap with the pump. Counts **requests**, not TCP connections, because over HTTP/2 a session multiplexes every request onto one connection while the origin still counts each one (AE#377). It is also the only ceiling: several engines playing from one origin are bounded by this value and by what the origin refuses, not by a transport pool underneath it (AE#450). |
 | `heldSourceConnection` | false | Ask the source **once** and pull it, instead of ending the connection at the reader's window high water and asking again every 8 to 16 MB of drain (AE#377). For an origin that punishes repeated requests rather than concurrency: some CDNs refuse new requests for minutes at a stretch while serving an already open connection at full rate, and against one of those the request cadence is the defect, at any range size (measured at the reporting origin: 32 MB ranges raised to 256 MB, eight times fewer requests, the refusals unchanged). Where `maxConcurrentSourceRequests` bounds how many requests are in flight, this removes the second request. The read path is the engine's own HTTP/1.1 over a demand-driven stream task, so: **HTTP/1.1 only** (no ALPN, an HTTP/2-only origin is out of scope), the **system proxy configuration does not apply**, and TLS is the OS's through the same host trust decision as every other engine session but has not been exercised against a self-signed origin. A viewer who pauses ends the connection after five seconds and resuming costs one request at the frontier, because a held flow nobody reads is the process-wide Network.framework starvation of AE#310. Applies to the playback reader; the subtitle and enrichment side readers keep the default transport, since they park for minutes at a time. The open-time detection of an origin that ignores `Range` (see `sequentialOrigin`) does not cover it, because its open is open-ended. **Names the session**: the transport is chosen at open, so a reload that changes it is refused. |
 | `autoplay` | true | False mounts paused: the load skips the terminal `play()` and settles at `.paused` for a host that resumes later. It describes THIS MOUNT and nothing after it: the rebuilds a session makes on its own (`reloadAtCurrentPosition`, an option correction, the AirPlay LAN swap, an audio-delay nudge) come back in the transport state the session is in, not in this one. Correcting it through `reloadAtCurrentPosition(applying:)` therefore does nothing (the log names it as not applied rather than as applied, AE#464 round 3, and the call returns it as `sessionOwned` with `rebuilt` false rather than spending a teardown on it, AE#464 round 4); call `play()` or `pause()` instead. |
 

From 9bd0096892569c53c88b17219c8d259347082d30 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 30 Sep 2026 22:10:51 +0200
Subject: [PATCH 252/359] chore(release): prep 7.24.0 - fastZap ingest joins
 the cushion it seals and honours the request budget

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                    | 8 ++++++++
 Examples/README.md                              | 2 +-
 README.md                                       | 6 +++---
 Sources/AetherEngine/AetherEngine+Version.swift | 2 +-
 4 files changed, 13 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index e627d2886..43c06fef9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,12 +10,20 @@ the public-API contract.
 
 ## [Unreleased]
 
+_Nothing yet._
+
+## [7.24.0] - 2026-09-30
+
 ### Fixed
 
 - **`.fastZap` on an HLS upstream with long segments always ended at the bounded start (#678).** The served TARGETDURATION on an ingest is floored by the longest upstream segment (`ceil(longest / 1.5)`, AE#447), so a 10 s provider seals 7 and the first serve wants 21 s, but the join covered `1.5 x` the advertised target duration: two 10 s segments, 19 s once the last GOP stays open. Short by construction for every segment above ~5 s, so every zap waited out the grace on content the origin already held. The join now covers that holdback plus one GOP (at most 4 s). Measured on 10 s segments: first picture t+2.2 to 2.5 s -> t+0.22 s on loopback, t+4.1 to 4.4 s -> t+2.9 s behind a 40 Mbit/s link.
 - **The HLS live ingest ignored `maxConcurrentSourceRequests` (#678).** It charged nothing to the origin request budget and fetched four segments in parallel, so a host declaring `1` for a single-connection provider still opened four requests to it. Playlist, segment and key fetches now take a budget ticket, report refusals and redirects, and the prefetch window narrows to the limit; a direct `.custom(HLSLiveIngestReader(...))` load registers the ceiling on its playlist URL.
 - **A same-format load kept the panel in its UI mode after the host cleared the display criteria itself (#678).** The unchanged skip compared against the engine's own record only; it now also reads `preferredDisplayCriteria` back and writes again when it finds nothing set.
 
+### Changed
+
+- **A live URL known to be an HLS playlist skips the raw probe (#678).** A `.m3u8` / `.m3u` path, or a URL that already took the AE#363 reroute in this process, goes straight onto the live ingest instead of spending one discarded request per zap.
+
 ### Added
 
 - **`[Demuxer] open timings`** on every playback, probe and restart open: connect, `open_input` and `find_stream_info` separately, the stream count and the probe budget, also when the stream analysis fails (#678).
diff --git a/Examples/README.md b/Examples/README.md
index 69abe01e5..d840201d7 100644
--- a/Examples/README.md
+++ b/Examples/README.md
@@ -18,7 +18,7 @@ Three samples covering different audiences:
    ```
    https://github.com/superuser404notfound/AetherEngine
    ```
-   Dependency Rule: Up to Next Major Version, starting from `7.23.2`. Add the `AetherEngine` library product to your app target.
+   Dependency Rule: Up to Next Major Version, starting from `7.24.0`. Add the `AetherEngine` library product to your app target.
 
 3. **Drop the file in.** Replace the Xcode template's default `App.swift` (or whatever the generated `@main` file is called) with the contents of [`MinimalPlayerApp.swift`](MinimalPlayer/MinimalPlayerApp.swift). The file is self-contained: it defines both the `@main App` struct and the `ContentView`.
 
diff --git a/README.md b/README.md
index 6e81de4f1..b906ccb1c 100644
--- a/README.md
+++ b/README.md
@@ -384,7 +384,7 @@ Subtitle cues land in raw source PTS; render the overlay against `player.sourceT
 Install via Swift Package Manager:
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.23.2")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.24.0")
 ```
 
 Three samples ship in `Examples/`:
@@ -631,10 +631,10 @@ Browse all of this as a searchable site at **[aetherengine.superuser404.de](http
 AetherEngine uses [Semantic Versioning](https://semver.org). The public API surface, every `public` declaration in `Sources/AetherEngine/`, is the stability contract. **Major** removes / renames public symbols or breaks adopters; **Minor** adds public API or codec / format support; **Patch** fixes bugs with no public API change. `internal` types are not part of the contract.
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.23.2")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.24.0")
 ```
 
-Pin to `.upToNextMinor(from: "7.23.2")` for stricter teams that prefer to opt into minor bumps explicitly.
+Pin to `.upToNextMinor(from: "7.24.0")` for stricter teams that prefer to opt into minor bumps explicitly.
 
 ## Requirements
 
diff --git a/Sources/AetherEngine/AetherEngine+Version.swift b/Sources/AetherEngine/AetherEngine+Version.swift
index 58dfa5296..89c662e7f 100644
--- a/Sources/AetherEngine/AetherEngine+Version.swift
+++ b/Sources/AetherEngine/AetherEngine+Version.swift
@@ -11,5 +11,5 @@ extension AetherEngine {
     ///
     /// Between releases, and in a consumer that pins an unreleased commit for a device test, this
     /// names the last PUBLISHED version the checkout descends from, not every patch in it.
-    public nonisolated static let version = "7.23.2"
+    public nonisolated static let version = "7.24.0"
 }

From 3179aec3a40cb6283c91ceb38e4b31ad362f726a Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 1 Oct 2026 05:07:54 +0200
Subject: [PATCH 253/359] feat(engine): sharedOutputRole keeps a secondary
 engine off the panel and Now Playing (Sodalite#175)

Sodalite#175 requires multiple engines running in a single process, with only the
primary driving the panel and Now Playing session. This implements the role enum
and wiring:

- Adds SharedOutputRole enum (primary/secondary) with default primary
- Adds sharedOutputRole field to LoadOptions
- Adds applyingSharedOutputRole() to suppress display criteria for secondary
- Adds ownsNowPlaying() to gate Now Playing ownership on role
- Wires role through loadSession and makeNativeHost
- Marks sharedOutputRole as an identity field (cannot change mid-session)

TDD: GREEN - all 3947 tests pass, including new SharedOutputRoleTests
and Issue460 inventory tests.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../AetherEngine/AetherEngine+Loading.swift   |  3 +-
 Sources/AetherEngine/AetherEngine+Probe.swift | 13 +++++++
 .../AetherEngine+ReloadWithOptions.swift      |  3 +-
 Sources/AetherEngine/AetherEngine.swift       |  1 +
 Sources/AetherEngine/PlayerState.swift        |  7 +++-
 Sources/AetherEngine/SharedOutputRole.swift   |  9 +++++
 .../SharedOutputRoleTests.swift               | 37 +++++++++++++++++++
 7 files changed, 70 insertions(+), 3 deletions(-)
 create mode 100644 Sources/AetherEngine/SharedOutputRole.swift
 create mode 100644 Tests/AetherEngineTests/SharedOutputRoleTests.swift

diff --git a/Sources/AetherEngine/AetherEngine+Loading.swift b/Sources/AetherEngine/AetherEngine+Loading.swift
index 483f90d11..c7975f28a 100644
--- a/Sources/AetherEngine/AetherEngine+Loading.swift
+++ b/Sources/AetherEngine/AetherEngine+Loading.swift
@@ -320,7 +320,8 @@ extension AetherEngine {
     /// which is the point, since re-creating it is what breaks AVKit's MediaRemote registration.
     func makeNativeHost() -> NativeAVPlayerHost {
         #if os(tvOS) || os(iOS)
-        return NativeAVPlayerHost(ownsNowPlayingSession: ownsVideoNowPlayingSession)
+        return NativeAVPlayerHost(ownsNowPlayingSession: Self.ownsNowPlaying(
+            hostOptIn: ownsVideoNowPlayingSession, role: loadedOptions.sharedOutputRole))
         #else
         return NativeAVPlayerHost()
         #endif
diff --git a/Sources/AetherEngine/AetherEngine+Probe.swift b/Sources/AetherEngine/AetherEngine+Probe.swift
index e4040421c..8f5e49fcb 100644
--- a/Sources/AetherEngine/AetherEngine+Probe.swift
+++ b/Sources/AetherEngine/AetherEngine+Probe.swift
@@ -579,6 +579,19 @@ extension AetherEngine {
         return effectiveFormat == .sdr ? .brief : .full
     }
 
+    /// Sodalite#175: a secondary never writes criteria, whatever the host passed.
+    nonisolated static func applyingSharedOutputRole(_ options: LoadOptions) -> LoadOptions {
+        guard options.sharedOutputRole == .secondary else { return options }
+        var adjusted = options
+        adjusted.suppressDisplayCriteria = true
+        return adjusted
+    }
+
+    /// Sodalite#175: Now Playing belongs to the primary; a secondary never takes it.
+    nonisolated static func ownsNowPlaying(hostOptIn: Bool, role: SharedOutputRole) -> Bool {
+        hostOptIn && role == .primary
+    }
+
     /// Whitelist (not blacklist) of AVPlayer-native audio codecs: AAC, MP3, MP2, ALAC, AC-3/E-AC-3, LPCM, FLAC (native since iOS/tvOS 11). Anything else falls back to `AudioPlaybackHost` (FFmpeg).
     nonisolated static func avPlayerCanDecodeAudio(_ codecID: AVCodecID) -> Bool {
         switch codecID {
diff --git a/Sources/AetherEngine/AetherEngine+ReloadWithOptions.swift b/Sources/AetherEngine/AetherEngine+ReloadWithOptions.swift
index e77f79875..52cb50020 100644
--- a/Sources/AetherEngine/AetherEngine+ReloadWithOptions.swift
+++ b/Sources/AetherEngine/AetherEngine+ReloadWithOptions.swift
@@ -275,6 +275,7 @@ enum SessionOptionCorrection {
         "nativeRemoteHLS",
         "sequentialOrigin",
         "heldSourceConnection",
+        "sharedOutputRole",
     ]
 
     /// The fields a running SESSION owns, which a correction may name and the rebuild then decides
@@ -400,6 +401,6 @@ enum SessionOptionCorrection {
         "declaredDurationSeconds", "probesize", "maxAnalyzeDuration", "preferredAudioLanguages",
         "preferredSubtitleLanguages", "externalSubtitles", "forwardBufferSegments", "autoplay",
         "audioDelaySeconds", "teletextPage", "deinterlaceMode", "deinterlaceFieldRate", "preferredDecodePath",
-        "escalatesToSoftwarePath", "isLiveRejoin", "subtitleSessionCarryover",
+        "escalatesToSoftwarePath", "sharedOutputRole", "isLiveRejoin", "subtitleSessionCarryover",
     ]
 }
diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index ce544c171..99f484da3 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -3808,6 +3808,7 @@ public final class AetherEngine: ObservableObject {
     ) async throws -> SourceProbe? {
         var source = source
         var options = options
+        options = Self.applyingSharedOutputRole(options)
         // #436: a speed the host set belongs to the item it was set on. The rebuilds a session makes
         // on its own (reload at position, audio-track switch, AirPlay LAN swap, background return)
         // reopen the same source and keep it; a different item starts at 1.0, so a host whose speed
diff --git a/Sources/AetherEngine/PlayerState.swift b/Sources/AetherEngine/PlayerState.swift
index 4b37d5824..7bb0bdc60 100644
--- a/Sources/AetherEngine/PlayerState.swift
+++ b/Sources/AetherEngine/PlayerState.swift
@@ -859,6 +859,9 @@ public struct LoadOptions: Sendable, Equatable {
     /// A tuning field: correctable on a playing session through `reloadAtCurrentPosition(applying:)`.
     public var escalatesToSoftwarePath: Bool = true
 
+    /// Sodalite#175: `.secondary` for an engine running beside the one that owns the panel. Default `.primary`.
+    public var sharedOutputRole: SharedOutputRole
+
     /// ENGINE-INTERNAL: marks this load as a live REJOIN (`reloadAtCurrentPosition`). Not settable from the public initializer. When true, the native load path skips its explicit initial seek so AVPlayer picks edge-minus-holdback (see `LiveReloadPolicy`); without it the reloaded item can wedge in `waitingToPlay` against Jellyfin's re-served backlog. Meaningful only when `isLive` is true.
     var isLiveRejoin: Bool = false
 
@@ -911,7 +914,8 @@ public struct LoadOptions: Sendable, Equatable {
         deinterlaceMode: DeinterlaceMode = .auto,
         deinterlaceFieldRate: DeinterlaceFieldRate = .field,
         preferredDecodePath: DecodePath = .automatic,
-        escalatesToSoftwarePath: Bool = true
+        escalatesToSoftwarePath: Bool = true,
+        sharedOutputRole: SharedOutputRole = .primary
     ) {
         self.omitCriteriaColorExtensions = omitCriteriaColorExtensions
         self.suppressDisplayCriteria = suppressDisplayCriteria
@@ -955,6 +959,7 @@ public struct LoadOptions: Sendable, Equatable {
         self.deinterlaceFieldRate = deinterlaceFieldRate
         self.preferredDecodePath = preferredDecodePath
         self.escalatesToSoftwarePath = escalatesToSoftwarePath
+        self.sharedOutputRole = sharedOutputRole
     }
 }
 
diff --git a/Sources/AetherEngine/SharedOutputRole.swift b/Sources/AetherEngine/SharedOutputRole.swift
new file mode 100644
index 000000000..e7e83cfdc
--- /dev/null
+++ b/Sources/AetherEngine/SharedOutputRole.swift
@@ -0,0 +1,9 @@
+/// Which of the process-wide outputs a load may drive (Sodalite#175). One engine is `.primary`; an
+/// engine running beside it, such as a multiview tile, is `.secondary`. See `SharedOutputCoordinator`.
+public enum SharedOutputRole: String, Sendable, Equatable {
+    /// Drives the panel (display criteria) and may own Now Playing. The default, and the only role a
+    /// host with one engine ever needs.
+    case primary
+    /// Never writes display criteria and never owns Now Playing, whatever the host set for either.
+    case secondary
+}
diff --git a/Tests/AetherEngineTests/SharedOutputRoleTests.swift b/Tests/AetherEngineTests/SharedOutputRoleTests.swift
new file mode 100644
index 000000000..cadf0d9df
--- /dev/null
+++ b/Tests/AetherEngineTests/SharedOutputRoleTests.swift
@@ -0,0 +1,37 @@
+import Testing
+@testable import AetherEngine
+
+/// Sodalite#175: a multiview tile runs beside the engine that owns the panel and Now Playing.
+@Suite("Shared output role (Sodalite#175)")
+struct SharedOutputRoleTests {
+
+    @Test("the default role is primary, so a single-instance host is untouched")
+    func defaultIsPrimary() {
+        #expect(LoadOptions().sharedOutputRole == .primary)
+    }
+
+    @Test("a secondary load never writes display criteria")
+    func secondarySuppressesCriteria() {
+        var options = LoadOptions()
+        options.sharedOutputRole = .secondary
+        #expect(AetherEngine.applyingSharedOutputRole(options).suppressDisplayCriteria)
+    }
+
+    @Test("a primary load keeps whatever the host asked for")
+    func primaryKeepsHostChoice() {
+        #expect(!AetherEngine.applyingSharedOutputRole(LoadOptions()).suppressDisplayCriteria)
+        #expect(AetherEngine.applyingSharedOutputRole(LoadOptions(suppressDisplayCriteria: true)).suppressDisplayCriteria)
+    }
+
+    @Test("only a primary may own Now Playing, and only when the host opted in")
+    func nowPlayingOwnership() {
+        #expect(AetherEngine.ownsNowPlaying(hostOptIn: true, role: .primary))
+        #expect(!AetherEngine.ownsNowPlaying(hostOptIn: true, role: .secondary))
+        #expect(!AetherEngine.ownsNowPlaying(hostOptIn: false, role: .primary))
+    }
+
+    @Test("the role names the session, so a correction may not flip it")
+    func roleIsIdentity() {
+        #expect(SessionOptionCorrection.loadIdentityFields.contains("sharedOutputRole"))
+    }
+}

From 63f2df5b9d91cc825fcf593160a8d5fc9dd98a03 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 1 Oct 2026 05:10:46 +0200
Subject: [PATCH 254/359] docs(api): name sharedOutputRole (Sodalite#175)

Document the new sharedOutputRole field in LoadOptions table.
A secondary engine never writes display criteria and never owns
Now Playing, whatever suppressDisplayCriteria and
ownsVideoNowPlayingSession say. Identity field: a correction
cannot flip it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 docs/api.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/api.md b/docs/api.md
index 2d41d7364..e84a2062d 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -982,6 +982,7 @@ All flags default to safe values; the table is the full set. Depth for the media
 | `dolbyVisionHandling` | `.automatic` | A `DolbyVisionHandling`. `.baseLayerOnly` presents the HDR10 / HLG base layer of a Dolby Vision source and leaves the Dolby Vision out of the container on every display: plain `hvc1` / `av01` sample entry, `dvcC` stripped, no `SUPPLEMENTAL-CODECS`, HDR10 / HLG display criteria, `videoFormat` reads the base layer's format while `sourceVideoFormat` and `sourceDVProfile` keep saying what the file carries. The route a host offers as "Dolby Vision: off (HDR10)", for a source whose Dolby Vision is wrong and whose base layer is right: the reported shape is a remux carrying a Profile 7 RPU under a container record claiming Profile 5, where a player that believes the record decodes YCbCr as IPT and the picture comes out green / violet. Applies to HEVC Profile 7 / 8.1 / 8.4, AV1 Profile 10.1 / 10.4, and a Profile 5 (or AV1 10.0) record whose VUI declares a BT.2020 YCbCr PQ or HLG base; a Profile 5 whose VUI is unspecified carries IPT-PQ-c2, has no base layer to present, keeps its route, and the engine says so in the log. Takes precedence over `forceDolbyVisionOnNonDVDisplay`. A tuning field, correctable through `reloadAtCurrentPosition(applying:)`; a Profile 5 record the VUI contradicts also stops refusing the software path under it. See [formats.md](formats.md#dolby-vision-signaling). |
 | `preferredDecodePath` | `.automatic` | A `DecodePath`. `.software` serves this source through `SoftwarePlaybackHost` whatever the routing concluded, scoped to this session and costing the source nothing (seeks, the audio switch and the title switch all keep working). The escape for the formats `VTCapabilityProbe` deliberately cannot classify, and for live H.264 / HEVC, which never reaches that gate at all. One-way: there is no `.native`. See [Overriding the decode path](#overriding-the-decode-path). |
 | `escalatesToSoftwarePath` | `true` | Whether a native session AVPlayer refuses on its merits (`CoreMediaErrorDomain`), or a live join without an entry point the native route can open (`AetherEngine.LiveJoin`, AE#627), may be rebuilt once on the software path (AE#561). `false` surfaces the failure as `.error` instead, for a host with its own fallback ladder (AE#629). Correctable. |
+| `sharedOutputRole` | `.primary` (default) or `.secondary` | A `SharedOutputRole`. A secondary engine never writes display criteria and never owns Now Playing, whatever `suppressDisplayCriteria` and `ownsVideoNowPlayingSession` say. Identity field: a correction cannot flip it (Sodalite#175). |
 | `deinterlaceMode` | `.auto` | A `DeinterlaceMode` for the software path: the Metal / VideoToolbox graph with a CPU bwdif fallback, or `.software` to force the CPU path. |
 | `deinterlaceFieldRate` | `.field` | A `DeinterlaceFieldRate`: the hardware deinterlacer emits one frame per field (25i to 50p) or per frame. The software fallback is always frame rate, because doubling a CPU bwdif is the wrong trade and a fallback should not change cost class. |
 | `probesize`, `maxAnalyzeDuration` | nil | Caller-bounded open-time probe budget (defaults 50 MB / 60 s). They fail **open**: an over-tight budget loads with late-resolving tracks silently missing rather than throwing, so validate track presence if you tighten them. Do not pass `0` for `maxAnalyzeDuration`; FFmpeg maps it to a shorter heuristic. |

From 8360388726faed8d60e149e033bfd87705ba623e Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 1 Oct 2026 05:15:42 +0200
Subject: [PATCH 255/359] feat(engine): SharedOutputCoordinator tracks who
 still uses the process-wide outputs (Sodalite#175)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../SharedOutputCoordinator.swift             |  91 ++++++++++
 .../SharedOutputCoordinatorTests.swift        | 167 ++++++++++++++++++
 2 files changed, 258 insertions(+)
 create mode 100644 Sources/AetherEngine/SharedOutputCoordinator.swift
 create mode 100644 Tests/AetherEngineTests/SharedOutputCoordinatorTests.swift

diff --git a/Sources/AetherEngine/SharedOutputCoordinator.swift b/Sources/AetherEngine/SharedOutputCoordinator.swift
new file mode 100644
index 000000000..8aab8dc65
--- /dev/null
+++ b/Sources/AetherEngine/SharedOutputCoordinator.swift
@@ -0,0 +1,91 @@
+import Foundation
+
+/// The outputs every `AetherEngine` in a process shares, and who is still using them (Sodalite#175).
+///
+/// The audio session, its channel preference and the panel's display criteria are process-wide, and
+/// each engine used to act on them as if it were alone. Measured on an Apple TV with two live tiles:
+/// every stop that released the session paused the OTHER engine within 10 ms, picture and all, 4 of 4.
+/// Engines join here when a load starts and leave on a final teardown; the decisions below are the
+/// ones that need to know whether anybody is left.
+@MainActor
+final class SharedOutputCoordinator {
+    static let shared = SharedOutputCoordinator()
+
+    struct Member: Equatable {
+        var role: SharedOutputRole
+        var tag: String?
+        var sourceChannels: Int?
+    }
+
+    enum LeaveOutcome: Equatable, Sendable {
+        case notMember
+        case othersRemain(Int)
+        case lastOut(releaseSession: Bool)
+    }
+
+    private var members: [ObjectIdentifier: Member] = [:]
+    /// Set by any leaver that asked for the session to be released, paid by the last one out. Without
+    /// it, the engine that opted in could leave first and the one that did not would close the round.
+    private var releaseOwed = false
+    /// Criteria writers that stopped while others still played. Keyed by engine, so one that loads
+    /// again drops its own reset instead of having it wipe the criteria it has just written.
+    private var deferredCriteriaResets: [ObjectIdentifier: @MainActor () -> Void] = [:]
+    private var lastTransition: Task<Void, Never>?
+
+    init() {}
+
+    var isEmpty: Bool { members.isEmpty }
+
+    var preferredSourceChannels: Int? { members.values.compactMap(\.sourceChannels).max() }
+
+    func join(_ id: ObjectIdentifier, role: SharedOutputRole, tag: String?) {
+        let channels = members[id]?.sourceChannels
+        members[id] = Member(role: role, tag: tag, sourceChannels: channels)
+        deferredCriteriaResets[id] = nil
+    }
+
+    func noteSourceChannels(_ channels: Int?, for id: ObjectIdentifier) {
+        guard members[id] != nil else { return }
+        members[id]?.sourceChannels = channels
+    }
+
+    func leave(_ id: ObjectIdentifier, releasesSession: Bool) -> LeaveOutcome {
+        guard members.removeValue(forKey: id) != nil else { return .notMember }
+        if releasesSession { releaseOwed = true }
+        guard members.isEmpty else { return .othersRemain(members.count) }
+        let release = releaseOwed
+        releaseOwed = false
+        let resets = deferredCriteriaResets.values
+        deferredCriteriaResets.removeAll()
+        resets.forEach { $0() }
+        return .lastOut(releaseSession: release)
+    }
+
+    func othersActive(besides id: ObjectIdentifier) -> Bool {
+        members.keys.contains { $0 != id }
+    }
+
+    /// Defers a criteria reset to run when the last engine leaves, unless nobody else is playing now.
+    /// If `id` is alone or not a member, the reset runs immediately.
+    func deferCriteriaReset(for id: ObjectIdentifier, _ body: @escaping @MainActor () -> Void) {
+        guard othersActive(besides: id) else { body(); return }
+        deferredCriteriaResets[id] = body
+    }
+
+    /// One queue for every engine's activation and release. AE#538 ordered them per engine; with two
+    /// engines the release of one and the activation of the other had no order between them.
+    func enqueueTransition(_ body: @escaping @Sendable () async -> Void) -> Task<Void, Never> {
+        let previous = lastTransition
+        let transition = Task.detached(priority: .userInitiated) {
+            await previous?.value
+            await body()
+        }
+        lastTransition = transition
+        return transition
+    }
+
+    /// Log label for an engine: its host-given tag, or the identifier's hash when there is none.
+    func label(for id: ObjectIdentifier) -> String {
+        members[id]?.tag ?? "engine-\(UInt(bitPattern: id.hashValue) % 10_000)"
+    }
+}
diff --git a/Tests/AetherEngineTests/SharedOutputCoordinatorTests.swift b/Tests/AetherEngineTests/SharedOutputCoordinatorTests.swift
new file mode 100644
index 000000000..7ae5ad779
--- /dev/null
+++ b/Tests/AetherEngineTests/SharedOutputCoordinatorTests.swift
@@ -0,0 +1,167 @@
+import Testing
+import Foundation
+@testable import AetherEngine
+
+/// Sodalite#175 spike: every stop that released the audio session paused the OTHER engine within
+/// 10 ms (4 of 4 on an Apple TV). The coordinator is the one place that knows whether anyone is left.
+@Suite("Shared output coordinator (Sodalite#175)")
+@MainActor
+struct SharedOutputCoordinatorTests {
+
+    private final class Token {}
+    // Held, not temporary: an ObjectIdentifier of a freed object can be reused by the next allocation.
+    private let tokenA = Token()
+    private let tokenB = Token()
+    private var a: ObjectIdentifier { ObjectIdentifier(tokenA) }
+    private var b: ObjectIdentifier { ObjectIdentifier(tokenB) }
+
+    @Test("a lone engine leaving is last out and releases as it did before")
+    func loneLeaveReleases() {
+        let c = SharedOutputCoordinator()
+        c.join(a, role: .primary, tag: nil)
+        #expect(c.leave(a, releasesSession: true) == .lastOut(releaseSession: true))
+        #expect(c.isEmpty)
+    }
+
+    @Test("leaving while another engine plays keeps the session")
+    func leaveWithOthersRemainingKeepsSession() {
+        let c = SharedOutputCoordinator()
+        c.join(a, role: .primary, tag: nil)
+        c.join(b, role: .secondary, tag: "tile2")
+        #expect(c.leave(b, releasesSession: true) == .othersRemain(1))
+        #expect(!c.isEmpty)
+    }
+
+    @Test("an opt-in from an earlier leaver is owed to the last one out")
+    func releaseOwedToLastOut() {
+        let c = SharedOutputCoordinator()
+        c.join(a, role: .primary, tag: nil)
+        c.join(b, role: .secondary, tag: "tile2")
+        _ = c.leave(a, releasesSession: true)
+        #expect(c.leave(b, releasesSession: false) == .lastOut(releaseSession: true))
+    }
+
+    @Test("the flag at leave time counts, not the one at join")
+    func releaseFlagAtLeaveCounts() {
+        let c = SharedOutputCoordinator()
+        c.join(a, role: .primary, tag: nil)
+        #expect(c.leave(a, releasesSession: false) == .lastOut(releaseSession: false))
+    }
+
+    @Test("the owed release does not survive into the next round")
+    func owedReleaseResetsWhenEmpty() {
+        let c = SharedOutputCoordinator()
+        c.join(a, role: .primary, tag: nil)
+        _ = c.leave(a, releasesSession: true)
+        c.join(b, role: .primary, tag: nil)
+        #expect(c.leave(b, releasesSession: false) == .lastOut(releaseSession: false))
+    }
+
+    @Test("leaving twice, or without joining, does nothing")
+    func leaveOfNonMemberIsInert() {
+        let c = SharedOutputCoordinator()
+        #expect(c.leave(a, releasesSession: true) == .notMember)
+        c.join(a, role: .primary, tag: nil)
+        _ = c.leave(a, releasesSession: true)
+        #expect(c.leave(a, releasesSession: true) == .notMember)
+    }
+
+    @Test("joining twice is one membership")
+    func joinIsIdempotent() {
+        let c = SharedOutputCoordinator()
+        c.join(a, role: .primary, tag: nil)
+        c.join(a, role: .primary, tag: nil)
+        #expect(c.leave(a, releasesSession: true) == .lastOut(releaseSession: true))
+    }
+
+    @Test("the preferred channel count is the widest source, so a stereo tile cannot downmix 5.1")
+    func channelsAreMax() {
+        let c = SharedOutputCoordinator()
+        c.join(a, role: .primary, tag: nil)
+        c.join(b, role: .secondary, tag: "tile2")
+        #expect(c.preferredSourceChannels == nil)
+        c.noteSourceChannels(6, for: a)
+        c.noteSourceChannels(2, for: b)
+        #expect(c.preferredSourceChannels == 6)
+        _ = c.leave(a, releasesSession: true)
+        #expect(c.preferredSourceChannels == 2)
+    }
+
+    @Test("channels noted for a non-member are ignored")
+    func channelsOfNonMemberIgnored() {
+        let c = SharedOutputCoordinator()
+        c.noteSourceChannels(8, for: a)
+        #expect(c.preferredSourceChannels == nil)
+    }
+
+    @Test("a deferred criteria reset runs when the last engine leaves")
+    func deferredResetRunsOnLastOut() {
+        let c = SharedOutputCoordinator()
+        var resets = 0
+        c.join(a, role: .primary, tag: nil)
+        c.join(b, role: .secondary, tag: "tile2")
+        #expect(c.othersActive(besides: a))
+        _ = c.leave(a, releasesSession: true)
+        c.deferCriteriaReset(for: a) { resets += 1 }
+        #expect(resets == 0)
+        _ = c.leave(b, releasesSession: true)
+        #expect(resets == 1)
+    }
+
+    @Test("an engine that loads again cancels its own deferred reset")
+    func rejoinCancelsDeferredReset() {
+        let c = SharedOutputCoordinator()
+        var resets = 0
+        c.join(a, role: .primary, tag: nil)
+        c.join(b, role: .secondary, tag: "tile2")
+        _ = c.leave(a, releasesSession: true)
+        c.deferCriteriaReset(for: a) { resets += 1 }
+        c.join(a, role: .primary, tag: nil)
+        _ = c.leave(b, releasesSession: true)
+        #expect(resets == 0)
+    }
+
+    @Test("a reset deferred when nobody else is playing runs at once instead of leaking into a later round")
+    func deferWithNobodyLeftRunsImmediately() {
+        let c = SharedOutputCoordinator()
+        var resets = 0
+        c.join(a, role: .primary, tag: nil)
+        _ = c.leave(a, releasesSession: true)
+        c.deferCriteriaReset(for: a) { resets += 1 }
+        #expect(resets == 1)
+        c.join(b, role: .primary, tag: nil)
+        _ = c.leave(b, releasesSession: true)
+        #expect(resets == 1)
+    }
+
+    private actor Journal {
+        private(set) var entries: [String] = []
+        func note(_ entry: String) { entries.append(entry) }
+    }
+
+    @Test("transitions from any engine run in the order they were asked for")
+    func transitionsAreOrderedAcrossEngines() async {
+        let c = SharedOutputCoordinator()
+        let journal = Journal()
+        _ = c.enqueueTransition {
+            try? await Task.sleep(for: .milliseconds(100))
+            await journal.note("activation by A")
+        }
+        let release = c.enqueueTransition { await journal.note("release by B") }
+        await release.value
+        #expect(await journal.entries == ["activation by A", "release by B"])
+    }
+
+    // Nonisolated probe: LeaveOutcome must be usable from a nonisolated context (Task 3 needs this)
+    @Test("LeaveOutcome is usable from nonisolated context")
+    func leaveOutcomeIsUsableNonisolated() {
+        #expect(Self.isRelease(.lastOut(releaseSession: true)))
+        #expect(!Self.isRelease(.lastOut(releaseSession: false)))
+        #expect(!Self.isRelease(.notMember))
+        #expect(!Self.isRelease(.othersRemain(2)))
+    }
+
+    nonisolated static func isRelease(_ o: SharedOutputCoordinator.LeaveOutcome) -> Bool {
+        o == .lastOut(releaseSession: true)
+    }
+}

From e04caa86150cbedc51280117595007f71d20dc6a Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 1 Oct 2026 05:24:45 +0200
Subject: [PATCH 256/359] fix(engine): a stop releases the session and resets
 the panel only when no other engine is playing (Sodalite#175)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../AetherEngine/AetherEngine+Loading.swift   |  8 ++-
 Sources/AetherEngine/AetherEngine.swift       | 65 ++++++++++++++-----
 .../SharedOutputEngineWiringTests.swift       | 36 ++++++++++
 docs/api.md                                   |  3 +-
 4 files changed, 93 insertions(+), 19 deletions(-)
 create mode 100644 Tests/AetherEngineTests/SharedOutputEngineWiringTests.swift

diff --git a/Sources/AetherEngine/AetherEngine+Loading.swift b/Sources/AetherEngine/AetherEngine+Loading.swift
index c7975f28a..a024633d5 100644
--- a/Sources/AetherEngine/AetherEngine+Loading.swift
+++ b/Sources/AetherEngine/AetherEngine+Loading.swift
@@ -1785,6 +1785,10 @@ extension AetherEngine {
         forceNativeLegibleDeselectedUntilHostSelects()
         // AE#458: what AVFoundation makes of the audio rendition this load just served, which is the
         // half of the exchange no log has ever carried.
+        SharedOutputCoordinator.shared.noteSourceChannels(
+            activeAudioTrackIndex.flatMap { index in audioTracks.first { $0.id == index }?.channels }
+                .flatMap { $0 > 0 ? $0 : nil },
+            for: ObjectIdentifier(self))
         logAudibleReadback(host: host)
     }
 
@@ -1810,8 +1814,10 @@ extension AetherEngine {
         } else {
             nil
         }
+        SharedOutputCoordinator.shared.noteSourceChannels(sourceChannels, for: ObjectIdentifier(self))
+        let preferred = SharedOutputCoordinator.shared.preferredSourceChannels ?? sourceChannels
         await enqueueAudioSessionTransition {
-            AetherEngine.applyRendererAudioSession(sourceChannels: sourceChannels)
+            AetherEngine.applyRendererAudioSession(sourceChannels: preferred)
         }.value
         #endif
     }
diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index 99f484da3..85c11080d 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -62,6 +62,7 @@ public final class AetherEngine: ObservableObject {
             recomputePlaybackPhase()
             resolveLoadingStashedSeek(from: oldValue)
             settleOwedBackgroundAction()
+            if let logTag { EngineLog.emit("[AetherEngine:\(logTag)] state=\(state)", category: .engine) }
         }
     }
 
@@ -498,6 +499,10 @@ public final class AetherEngine: ObservableObject {
     /// software or audio-only load is still activating releases the session after that activation (AE#538).
     public var deactivatesAudioSessionOnStop: Bool = false
 
+    /// Sodalite#175: a short name for this instance ("tile2") carried by the shared-output lines and the
+    /// state transitions, so a log with several engines in it can be read. nil for a lone engine.
+    public var logTag: String?
+
     @Published public internal(set) var duration: Double = 0
 
     /// Forwarder; see `clock.progress`.
@@ -3564,9 +3569,6 @@ public final class AetherEngine: ObservableObject {
     private var audioSessionDeactivationTask: Task<Void, Never>?
     #endif
 
-    /// The most recent off-main activation or release of the shared session. See `enqueueAudioSessionTransition`.
-    private var audioSessionTransition: Task<Void, Never>?
-
     /// Run a session activation or release off the main actor, after every one asked for before it.
     ///
     /// Since AE#538 both halves are detached tasks, and two detached tasks carry no order between them.
@@ -3575,14 +3577,9 @@ public final class AetherEngine: ObservableObject {
     /// audio-only load's activation can send `setActive(false)` first and leave the session active after a
     /// final teardown. Each transition awaits its predecessor, including a cancelled one, which then drops
     /// on its own guard. Not platform-gated, so the order is testable where the session does not exist.
+    /// Since Sodalite#175 the queue is the process-wide one in `SharedOutputCoordinator`.
     func enqueueAudioSessionTransition(_ body: @escaping @Sendable () async -> Void) -> Task<Void, Never> {
-        let previous = audioSessionTransition
-        let transition = Task.detached(priority: .userInitiated) {
-            await previous?.value
-            await body()
-        }
-        audioSessionTransition = transition
-        return transition
+        SharedOutputCoordinator.shared.enqueueTransition(body)
     }
 
     #if os(iOS) || os(tvOS)
@@ -3809,6 +3806,7 @@ public final class AetherEngine: ObservableObject {
         var source = source
         var options = options
         options = Self.applyingSharedOutputRole(options)
+        SharedOutputCoordinator.shared.join(ObjectIdentifier(self), role: options.sharedOutputRole, tag: logTag)
         // #436: a speed the host set belongs to the item it was set on. The rebuilds a session makes
         // on its own (reload at position, audio-track switch, AirPlay LAN swap, background return)
         // reopen the same source and keep it; a different item starts at 1.0, so a host whose speed
@@ -6919,12 +6917,23 @@ public final class AetherEngine: ObservableObject {
     /// - `!keepNativeHost`: belt and braces. A preserved host means audio keeps flowing into the next load.
     /// - `hostOptedIn`: `deactivatesAudioSessionOnStop`. The session is process-global state the engine
     ///   mostly does not own, so releasing it is the host app's call.
+    /// Since Sodalite#175 the host opt-in is folded into `SharedOutputCoordinator.leave`, which owes it to the last engine out.
     nonisolated static func shouldDeactivateAudioSessionOnTeardown(finalTeardown: Bool,
                                                                    keepNativeHost: Bool,
                                                                    hostOptedIn: Bool) -> Bool {
         finalTeardown && !keepNativeHost && hostOptedIn
     }
 
+    /// Sodalite#175: the session goes only with the last engine out, and only when a release is owed.
+    nonisolated static func shouldDeactivateAudioSession(after outcome: SharedOutputCoordinator.LeaveOutcome) -> Bool {
+        outcome == .lastOut(releaseSession: true)
+    }
+
+    /// Sodalite#175: a scheduled release is stale once another engine has joined in the meantime.
+    nonisolated static func releaseStillWanted(coordinatorIsEmpty: Bool) -> Bool {
+        coordinatorIsEmpty
+    }
+
     #if os(iOS) || os(tvOS)
     /// Counterpart to the activations the engine takes part in (#215). The native path never activates the
     /// session itself (AVKit does it per playback, #24); the software and audio renderer paths do, in
@@ -6984,6 +6993,10 @@ public final class AetherEngine: ObservableObject {
         audioSessionDeactivationTask = enqueueAudioSessionTransition { [weak self] in
             guard let self else { return }
             guard !Task.isCancelled, await self.loadGeneration == generation else { return }
+            guard await Self.releaseStillWanted(coordinatorIsEmpty: SharedOutputCoordinator.shared.isEmpty) else {
+                EngineLog.emit("[SharedOutput] release dropped: another engine joined before it ran", category: .engine)
+                return
+            }
             AetherEngine.deactivateSharedAudioSession()
         }
     }
@@ -7144,13 +7157,24 @@ public final class AetherEngine: ObservableObject {
         // before the session goes away, and scheduled rather than called because the release itself can
         // block for ~0.5 s on a MAT passthrough route. Opt-in twice over: the caller must declare an
         // actual final teardown, AND the host must have set deactivatesAudioSessionOnStop.
-        #if os(iOS) || os(tvOS)
-        if Self.shouldDeactivateAudioSessionOnTeardown(finalTeardown: finalTeardown,
-                                                       keepNativeHost: keepNativeHost,
-                                                       hostOptedIn: deactivatesAudioSessionOnStop) {
-            scheduleAudioSessionDeactivation()
+        if finalTeardown && !keepNativeHost {
+            let coordinator = SharedOutputCoordinator.shared
+            let label = coordinator.label(for: ObjectIdentifier(self))
+            let outcome = coordinator.leave(ObjectIdentifier(self), releasesSession: deactivatesAudioSessionOnStop)
+            switch outcome {
+            case .othersRemain(let count):
+                EngineLog.emit("[SharedOutput] \(label) left, \(count) still active, session kept", category: .engine)
+            case .lastOut(let release):
+                EngineLog.emit("[SharedOutput] \(label) left last, release=\(release)", category: .engine)
+            case .notMember:
+                break
+            }
+            #if os(iOS) || os(tvOS)
+            if Self.shouldDeactivateAudioSession(after: outcome) {
+                scheduleAudioSessionDeactivation()
+            }
+            #endif
         }
-        #endif
 
         // Close custom reader on final teardown. Internal reloads pass keepCustomReader=true to survive for reuse.
         if !keepCustomReader {
@@ -7161,7 +7185,14 @@ public final class AetherEngine: ObservableObject {
         }
 
         if resetDisplayCriteria {
-            displayCriteria.reset()
+            let id = ObjectIdentifier(self)
+            if SharedOutputCoordinator.shared.othersActive(besides: id) {
+                // Sodalite#175: the panel mode belongs to every engine still playing; reset once the last one goes.
+                let controller = displayCriteria
+                SharedOutputCoordinator.shared.deferCriteriaReset(for: id) { controller.reset() }
+            } else {
+                displayCriteria.reset()
+            }
         }
         playbackBackend = .none
         activeVideoDecoder = nil
diff --git a/Tests/AetherEngineTests/SharedOutputEngineWiringTests.swift b/Tests/AetherEngineTests/SharedOutputEngineWiringTests.swift
new file mode 100644
index 000000000..f30f17fde
--- /dev/null
+++ b/Tests/AetherEngineTests/SharedOutputEngineWiringTests.swift
@@ -0,0 +1,36 @@
+import Testing
+import Foundation
+@testable import AetherEngine
+
+@Suite("Engine wiring to the shared output coordinator (Sodalite#175)")
+@MainActor
+struct SharedOutputEngineWiringTests {
+
+    @Test("only the last engine out, with a release owed, deactivates the session")
+    func deactivationFollowsOnlyLastOut() {
+        #expect(AetherEngine.shouldDeactivateAudioSession(after: .lastOut(releaseSession: true)))
+        #expect(!AetherEngine.shouldDeactivateAudioSession(after: .lastOut(releaseSession: false)))
+        #expect(!AetherEngine.shouldDeactivateAudioSession(after: .othersRemain(1)))
+        #expect(!AetherEngine.shouldDeactivateAudioSession(after: .notMember))
+    }
+
+    @Test("a release scheduled by the last engine drops when another engine joined meanwhile")
+    func pendingReleaseDropsWhenSomeoneJoined() async {
+        let c = SharedOutputCoordinator()
+        final class Token {}
+        let tokenA = Token(), tokenB = Token()
+        let a = ObjectIdentifier(tokenA), b = ObjectIdentifier(tokenB)
+        c.join(a, role: .primary, tag: nil)
+        let outcome = c.leave(a, releasesSession: true)
+        #expect(outcome == .lastOut(releaseSession: true))
+        c.join(b, role: .secondary, tag: "tile2")
+        #expect(!AetherEngine.releaseStillWanted(coordinatorIsEmpty: c.isEmpty))
+    }
+
+    @Test("an engine's log tag is the host's")
+    func logTagIsHostSet() throws {
+        let engine = try AetherEngine()
+        engine.logTag = "tile2"
+        #expect(engine.logTag == "tile2")
+    }
+}
diff --git a/docs/api.md b/docs/api.md
index e84a2062d..e61479b85 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -884,7 +884,8 @@ say so on the tracker rather than working around it.
 | `videoNowPlayingSession`, `setVideoNowPlayingInfo(_:)` | The session and its staged identity dictionary. Elapsed / rate / duration are merged from the player; do not stage them. |
 | `audioNowPlayingSession`, `setAudioNowPlayingInfo(_:)` | The same pair for the audio-only path, which owns its session unconditionally (there is no AVKit fork there). Pass an empty dictionary to clear. |
 | `setExternalMetadata(_:)` | AVKit's on-screen info pane on the video path. Safe before `load()`; replayed at host creation. |
-| `deactivatesAudioSessionOnStop` | Off by default. The engine declares the audio-session category at init and never activates it on the native path, because AVKit activates per playback and that is what lets tvOS negotiate the HDMI route (#24), so it never deactivates it either. Set true only when the app owns the session outright; the engine then releases it on a genuine final teardown, meaning `stop()` and never a reload, handoff or live retune. |
+| `deactivatesAudioSessionOnStop` | Off by default. The engine declares the audio-session category at init and never activates it on the native path, because AVKit activates per playback and that is what lets tvOS negotiate the HDMI route (#24), so it never deactivates it either. Set true only when the app owns the session outright; the engine then releases it on a genuine final teardown, meaning `stop()` and never a reload, handoff or live retune. With several engines in one process the release belongs to the last one out: a stop while another engine is still active keeps the session and logs `[SharedOutput] ... still active, session kept`. |
+| `logTag` | A short name for this instance (`tile2`), carried by the `[SharedOutput]` lines and a `[AetherEngine:<tag>] state=` line per transition. Set it on every engine of a host that runs several at once. |
 
 ## Stills and thumbnails
 

From b838d552dc6e3afdbb7d82b33914770e42a84305 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 1 Oct 2026 05:29:45 +0200
Subject: [PATCH 257/359] fix(engine): an engine released without stop() no
 longer holds the shared outputs (Sodalite#175)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 Sources/AetherEngine/AetherEngine.swift       |  7 ++--
 .../SharedOutputCoordinator.swift             | 34 +++++++++++++++----
 .../SharedOutputCoordinatorTests.swift        | 20 +++++++++++
 docs/api.md                                   |  2 +-
 4 files changed, 53 insertions(+), 10 deletions(-)

diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index 85c11080d..63933f749 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -3806,7 +3806,7 @@ public final class AetherEngine: ObservableObject {
         var source = source
         var options = options
         options = Self.applyingSharedOutputRole(options)
-        SharedOutputCoordinator.shared.join(ObjectIdentifier(self), role: options.sharedOutputRole, tag: logTag)
+        SharedOutputCoordinator.shared.join(ObjectIdentifier(self), role: options.sharedOutputRole, tag: logTag, owner: self)
         // #436: a speed the host set belongs to the item it was set on. The rebuilds a session makes
         // on its own (reload at position, audio-track switch, AirPlay LAN swap, background return)
         // reopen the same source and keep it; a different item starts at 1.0, so a host whose speed
@@ -7155,8 +7155,9 @@ public final class AetherEngine: ObservableObject {
         // #215: release the shared AVAudioSession once every render path above is quiesced. Scheduled
         // last so the item is unloaded, the AVPlayer released and the software/audio outputs stopped
         // before the session goes away, and scheduled rather than called because the release itself can
-        // block for ~0.5 s on a MAT passthrough route. Opt-in twice over: the caller must declare an
-        // actual final teardown, AND the host must have set deactivatesAudioSessionOnStop.
+        // block for ~0.5 s on a MAT passthrough route. The caller must declare an actual final teardown;
+        // the host opt-in (deactivatesAudioSessionOnStop) goes to SharedOutputCoordinator.leave, and the
+        // release belongs to the last engine out.
         if finalTeardown && !keepNativeHost {
             let coordinator = SharedOutputCoordinator.shared
             let label = coordinator.label(for: ObjectIdentifier(self))
diff --git a/Sources/AetherEngine/SharedOutputCoordinator.swift b/Sources/AetherEngine/SharedOutputCoordinator.swift
index 8aab8dc65..cfc7d966e 100644
--- a/Sources/AetherEngine/SharedOutputCoordinator.swift
+++ b/Sources/AetherEngine/SharedOutputCoordinator.swift
@@ -11,10 +11,13 @@ import Foundation
 final class SharedOutputCoordinator {
     static let shared = SharedOutputCoordinator()
 
-    struct Member: Equatable {
+    struct Member {
         var role: SharedOutputRole
         var tag: String?
         var sourceChannels: Int?
+        /// Weak, so an engine released without a final `stop()` does not stay a member forever.
+        weak var owner: AnyObject?
+        let tracksOwner: Bool
     }
 
     enum LeaveOutcome: Equatable, Sendable {
@@ -34,13 +37,30 @@ final class SharedOutputCoordinator {
 
     init() {}
 
-    var isEmpty: Bool { members.isEmpty }
+    var isEmpty: Bool {
+        pruneReleasedOwners()
+        return members.isEmpty
+    }
+
+    var preferredSourceChannels: Int? {
+        pruneReleasedOwners()
+        return members.values.compactMap(\.sourceChannels).max()
+    }
 
-    var preferredSourceChannels: Int? { members.values.compactMap(\.sourceChannels).max() }
+    /// Drops members whose engine was deallocated without a `stop()`. Leaves the deferred resets and
+    /// the owed release alone: the next `leave` or read decides.
+    private func pruneReleasedOwners() {
+        let gone = members.filter { $0.value.tracksOwner && $0.value.owner == nil }
+        for (id, member) in gone {
+            members[id] = nil
+            deferredCriteriaResets[id] = nil
+            EngineLog.emit("[SharedOutput] \(member.tag ?? "engine-\(UInt(bitPattern: id.hashValue) % 10_000)") was released without stop(), dropped", category: .engine)
+        }
+    }
 
-    func join(_ id: ObjectIdentifier, role: SharedOutputRole, tag: String?) {
+    func join(_ id: ObjectIdentifier, role: SharedOutputRole, tag: String?, owner: AnyObject? = nil) {
         let channels = members[id]?.sourceChannels
-        members[id] = Member(role: role, tag: tag, sourceChannels: channels)
+        members[id] = Member(role: role, tag: tag, sourceChannels: channels, owner: owner, tracksOwner: owner != nil)
         deferredCriteriaResets[id] = nil
     }
 
@@ -50,6 +70,7 @@ final class SharedOutputCoordinator {
     }
 
     func leave(_ id: ObjectIdentifier, releasesSession: Bool) -> LeaveOutcome {
+        pruneReleasedOwners()
         guard members.removeValue(forKey: id) != nil else { return .notMember }
         if releasesSession { releaseOwed = true }
         guard members.isEmpty else { return .othersRemain(members.count) }
@@ -62,7 +83,8 @@ final class SharedOutputCoordinator {
     }
 
     func othersActive(besides id: ObjectIdentifier) -> Bool {
-        members.keys.contains { $0 != id }
+        pruneReleasedOwners()
+        return members.keys.contains { $0 != id }
     }
 
     /// Defers a criteria reset to run when the last engine leaves, unless nobody else is playing now.
diff --git a/Tests/AetherEngineTests/SharedOutputCoordinatorTests.swift b/Tests/AetherEngineTests/SharedOutputCoordinatorTests.swift
index 7ae5ad779..a7a773889 100644
--- a/Tests/AetherEngineTests/SharedOutputCoordinatorTests.swift
+++ b/Tests/AetherEngineTests/SharedOutputCoordinatorTests.swift
@@ -164,4 +164,24 @@ struct SharedOutputCoordinatorTests {
     nonisolated static func isRelease(_ o: SharedOutputCoordinator.LeaveOutcome) -> Bool {
         o == .lastOut(releaseSession: true)
     }
+
+    @Test("an engine released without stop() no longer holds the session for everyone else")
+    func releasedOwnerIsPruned() {
+        let c = SharedOutputCoordinator()
+        var dropped: Token? = Token()
+        let droppedID = ObjectIdentifier(dropped!)
+        c.join(droppedID, role: .secondary, tag: "tile2", owner: dropped)
+        c.join(a, role: .primary, tag: nil, owner: tokenA)
+        dropped = nil
+        #expect(!c.othersActive(besides: a))
+        #expect(c.leave(a, releasesSession: true) == .lastOut(releaseSession: true))
+    }
+
+    @Test("a member joined without an owner is never pruned")
+    func ownerlessMemberStays() {
+        let c = SharedOutputCoordinator()
+        c.join(a, role: .primary, tag: nil)
+        c.join(b, role: .secondary, tag: "tile2")
+        #expect(c.leave(a, releasesSession: true) == .othersRemain(1))
+    }
 }
diff --git a/docs/api.md b/docs/api.md
index e61479b85..8a26f406a 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -885,7 +885,7 @@ say so on the tracker rather than working around it.
 | `audioNowPlayingSession`, `setAudioNowPlayingInfo(_:)` | The same pair for the audio-only path, which owns its session unconditionally (there is no AVKit fork there). Pass an empty dictionary to clear. |
 | `setExternalMetadata(_:)` | AVKit's on-screen info pane on the video path. Safe before `load()`; replayed at host creation. |
 | `deactivatesAudioSessionOnStop` | Off by default. The engine declares the audio-session category at init and never activates it on the native path, because AVKit activates per playback and that is what lets tvOS negotiate the HDMI route (#24), so it never deactivates it either. Set true only when the app owns the session outright; the engine then releases it on a genuine final teardown, meaning `stop()` and never a reload, handoff or live retune. With several engines in one process the release belongs to the last one out: a stop while another engine is still active keeps the session and logs `[SharedOutput] ... still active, session kept`. |
-| `logTag` | A short name for this instance (`tile2`), carried by the `[SharedOutput]` lines and a `[AetherEngine:<tag>] state=` line per transition. Set it on every engine of a host that runs several at once. |
+| `logTag` | A short name for this instance (`tile2`), carried by the `[SharedOutput]` lines and a `[AetherEngine:<tag>] state=` line per transition. Set it before `load()` (the tag is captured when the engine joins), on every engine of a host that runs several at once. |
 
 ## Stills and thumbnails
 

From 27ac60809ab573f0f42ef986d063f8425ec76459 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 1 Oct 2026 05:32:24 +0200
Subject: [PATCH 258/359] docs(api): running several engines at once
 (Sodalite#175)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 docs/api.md | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/docs/api.md b/docs/api.md
index 8a26f406a..34b99fd92 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -400,6 +400,17 @@ $ otool -L PlayerEngineKit.framework/PlayerEngineKit | grep -i libavcodec
 
 And the engine says it itself: the `[FFmpeg] libavcodec …` line at `init` reports the versions that actually answered, not the ones it was built against, so a wrong binding shows up in the log before it shows up as a defect.
 
+### Running several engines at once
+
+Each `AetherEngine` has its own loopback server, caches and lifecycle, so two or more can play side by side (a multiview grid). What they share is the process: the audio session, its channel preference and the panel's display criteria. The engine keeps one book of who is still playing (`SharedOutputCoordinator`, internal) and acts on it:
+
+- The audio session is released only by the last engine to stop, and only if some engine in that round had `deactivatesAudioSessionOnStop`.
+- The preferred output channel count is the widest source among the playing engines, so a muted stereo tile cannot downmix a 5.1 one.
+- A display-criteria reset waits until the last engine stops; an engine that loads again in the meantime cancels its own pending reset.
+- Stop every engine before you let go of it. An engine released without `stop()` is noticed and dropped the next time another engine asks, but until then it counts as playing.
+
+Load one engine as `.primary` and the others with `LoadOptions(sharedOutputRole: .secondary)`, set `logTag` (set before `load()`) on each, and control what is audible with `volume`. Every engine keeps decoding its audio, so switching the audible one is a volume change and not a reload.
+
 
 ## Constructing and binding
 

From 4a1f7189af0f5fd33d876edb2f380d10bd50efba Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 1 Oct 2026 05:43:59 +0200
Subject: [PATCH 259/359] fix(engine): a secondary engine never clears the
 panel, waits for a criteria write, or takes Now Playing (Sodalite#175)

- The two load-time criteria resets (audio-only path, suppressed clearStale path) go through the
  same coordinator gate as stopInternal, via one helper.
- join cancels the joiner's deferred reset only for a .primary rejoin.
- playGateGrace takes noWriterExpected; a .secondary load skips the play gate.
- AudioAVPlayerHost claims Now Playing only when the role allows it.
- The native path notes source channels from the session's own audio pick, so a track-switch
  reload no longer drops out of the channel max.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../AetherEngine/AetherEngine+Loading.swift   | 17 ++++++++----
 Sources/AetherEngine/AetherEngine+Probe.swift |  8 ++++--
 Sources/AetherEngine/AetherEngine.swift       | 27 +++++++++++--------
 .../Audio/AudioAVPlayerHost.swift             | 10 +++++--
 .../SharedOutputCoordinator.swift             |  5 ++--
 .../DisplayCriteriaPlayGateTests.swift        | 11 ++++++++
 .../SharedOutputCoordinatorTests.swift        | 15 +++++++++++
 7 files changed, 71 insertions(+), 22 deletions(-)

diff --git a/Sources/AetherEngine/AetherEngine+Loading.swift b/Sources/AetherEngine/AetherEngine+Loading.swift
index a024633d5..fbf3ee89c 100644
--- a/Sources/AetherEngine/AetherEngine+Loading.swift
+++ b/Sources/AetherEngine/AetherEngine+Loading.swift
@@ -1783,12 +1783,16 @@ extension AetherEngine {
                       // report the same two channels.
                       audioIsAtmosStreamCopy: nativeVideoSession?.audioIsAtmosStreamCopy == true))
         forceNativeLegibleDeselectedUntilHostSelects()
-        // AE#458: what AVFoundation makes of the audio rendition this load just served, which is the
-        // half of the exchange no log has ever carried.
+        // Sodalite#175: from the session's own pick, since a track-switch reload has no active index yet.
+        let sessionAudioPick = nativeVideoSession.map(\.activeAudioSourceStreamIndex).flatMap { $0 >= 0 ? Int($0) : nil }
+        let audioPick = sessionAudioPick ?? audioSourceStreamIndex.flatMap { Int(exactly: $0) } ?? activeAudioTrackIndex
+        let pickTracks = nativeVideoSession.map(\.companionAudioTracks).flatMap { $0.isEmpty ? nil : $0 } ?? audioTracks
         SharedOutputCoordinator.shared.noteSourceChannels(
-            activeAudioTrackIndex.flatMap { index in audioTracks.first { $0.id == index }?.channels }
+            audioPick.flatMap { index in pickTracks.first { $0.id == index }?.channels }
                 .flatMap { $0 > 0 ? $0 : nil },
             for: ObjectIdentifier(self))
+        // AE#458: what AVFoundation makes of the audio rendition this load just served, which is the
+        // half of the exchange no log has ever carried.
         logAudibleReadback(host: host)
     }
 
@@ -2106,7 +2110,9 @@ extension AetherEngine {
         // Reuse the persistent host (MPNowPlayingSession survives across tracks). host.load() swaps the item via replaceCurrentItem.
         await activateRendererAudioSession()
         try checkLoadCurrent(generation)
-        let host = audioAVPlayerHost ?? AudioAVPlayerHost()
+        let ownsNowPlaying = Self.ownsNowPlaying(hostOptIn: true, role: loadedOptions.sharedOutputRole)
+        let host = audioAVPlayerHost ?? AudioAVPlayerHost(ownsNowPlaying: ownsNowPlaying)
+        host.ownsNowPlaying = ownsNowPlaying
         self.audioAVPlayerHost = host
         applyDesiredVolume(to: host)
         self.audioAVPlayerActive = true
@@ -2528,7 +2534,8 @@ extension AetherEngine {
                         criteriaUnchanged: false,
                         engineIsCriteriaWriter: !loadedOptions.suppressDisplayCriteria,
                         formatKnown: true,
-                        effectiveFormat: videoFormat
+                        effectiveFormat: videoFormat,
+                        noWriterExpected: loadedOptions.sharedOutputRole == .secondary
                     ),
                     settleCap: loadedOptions.isLive ? .standard : .awaitObservedEnd,
                     isCurrent: { self.loadGeneration == gen })
diff --git a/Sources/AetherEngine/AetherEngine+Probe.swift b/Sources/AetherEngine/AetherEngine+Probe.swift
index 8f5e49fcb..73db43b4e 100644
--- a/Sources/AetherEngine/AetherEngine+Probe.swift
+++ b/Sources/AetherEngine/AetherEngine+Probe.swift
@@ -566,14 +566,18 @@ extension AetherEngine {
     ///
     /// `formatKnown` is false when the open-time probe failed: the real range is then unknown and a DV write
     /// may still be inbound, so a suppressed host keeps the full budget.
+    ///
+    /// `noWriterExpected` is a `.secondary` load (Sodalite#175): nobody writes criteria for it, so there is
+    /// no inbound switch to wait for.
     nonisolated static func playGateGrace(
         criteriaUnchanged: Bool,
         engineIsCriteriaWriter: Bool,
         formatKnown: Bool,
-        effectiveFormat: VideoFormat
+        effectiveFormat: VideoFormat,
+        noWriterExpected: Bool = false
     ) -> DisplayCriteriaController.StartGrace {
         // #133: the criteria were already active, nothing was written, nothing can settle.
-        if criteriaUnchanged { return .skip }
+        if criteriaUnchanged || noWriterExpected { return .skip }
         if engineIsCriteriaWriter { return .brief }
         guard formatKnown else { return .full }
         return effectiveFormat == .sdr ? .brief : .full
diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index 63933f749..65b695ce7 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -4428,7 +4428,7 @@ public final class AetherEngine: ObservableObject {
             // apply(), so clear a criteria the previous video session left applied. The engine is a
             // process-wide singleton; without this, music playback keeps the panel in DV/HDR.
             if Self.loadDisplayCriteriaAction(suppressDisplayCriteria: options.suppressDisplayCriteria, audioOnlyPath: true) == .clearStale {
-                displayCriteria.reset()
+                resetDisplayCriteriaRespectingOthers()
             }
             // Read codec before closing the probe; custom sources always use FFmpeg (AVPlayer can't consume a custom demuxer).
             let audioCodecID: AVCodecID = (probeOpened && resolvedInitialAudio >= 0)
@@ -4545,7 +4545,7 @@ public final class AetherEngine: ObservableObject {
             // Suppressed host: the load seam preserved the criteria (#128 follow-up), and AVKit writes its
             // own from the AVPlayerItem formatDescription later. Clear a leftover engine criteria now
             // (didApply-gated no-op for hosts that always suppress) so the two writers can't fight.
-            displayCriteria.reset()
+            resetDisplayCriteriaRespectingOthers()
             // #339: AVKit's write lands inside loadNative, so the observation has to be armed before the
             // load rather than when the play gate opens. After reset(), so a switch back to the default
             // mode is not recorded as this session's. Audio-only loads reach clearStale too and have no
@@ -5027,7 +5027,8 @@ public final class AetherEngine: ObservableObject {
                         criteriaUnchanged: criteriaUnchanged,
                         engineIsCriteriaWriter: !options.suppressDisplayCriteria,
                         formatKnown: probeOpened,
-                        effectiveFormat: effectiveFormat
+                        effectiveFormat: effectiveFormat,
+                        noWriterExpected: options.sharedOutputRole == .secondary
                     ),
                     // Sodalite#49: this gate runs after the item is ready, so waiting out an observed switch
                     // blocks nothing else, and the panel is dark until it ends either way. Live keeps the
@@ -7002,6 +7003,17 @@ public final class AetherEngine: ObservableObject {
     }
     #endif
 
+    /// Sodalite#175: the panel mode belongs to every engine still playing, so a reset waits for the last one out.
+    private func resetDisplayCriteriaRespectingOthers() {
+        let id = ObjectIdentifier(self)
+        if SharedOutputCoordinator.shared.othersActive(besides: id) {
+            let controller = displayCriteria
+            SharedOutputCoordinator.shared.deferCriteriaReset(for: id) { controller.reset() }
+        } else {
+            displayCriteria.reset()
+        }
+    }
+
     /// - Parameter resetDisplayCriteria: When `true` (default), release
     ///   the `AVDisplayManager.preferredDisplayCriteria` so the panel
     ///   returns to its default mode. Used by `load()` and the public
@@ -7186,14 +7198,7 @@ public final class AetherEngine: ObservableObject {
         }
 
         if resetDisplayCriteria {
-            let id = ObjectIdentifier(self)
-            if SharedOutputCoordinator.shared.othersActive(besides: id) {
-                // Sodalite#175: the panel mode belongs to every engine still playing; reset once the last one goes.
-                let controller = displayCriteria
-                SharedOutputCoordinator.shared.deferCriteriaReset(for: id) { controller.reset() }
-            } else {
-                displayCriteria.reset()
-            }
+            resetDisplayCriteriaRespectingOthers()
         }
         playbackBackend = .none
         activeVideoDecoder = nil
diff --git a/Sources/AetherEngine/Audio/AudioAVPlayerHost.swift b/Sources/AetherEngine/Audio/AudioAVPlayerHost.swift
index a877bdefb..c763c024c 100644
--- a/Sources/AetherEngine/Audio/AudioAVPlayerHost.swift
+++ b/Sources/AetherEngine/Audio/AudioAVPlayerHost.swift
@@ -43,6 +43,9 @@ final class AudioAVPlayerHost {
     /// shared singletons is what produces the half-working state.
     let nowPlayingSession: MPNowPlayingSession
     #endif
+    /// Sodalite#175: false for a `.secondary` engine, which never claims Now Playing. Set per load, the
+    /// host outlives a role change.
+    var ownsNowPlaying: Bool
 
     // MARK: - Private state
 
@@ -84,8 +87,10 @@ final class AudioAVPlayerHost {
 
     // MARK: - Init
 
-    init(diagnosticPool: ItemDiagnosticReadPool = .shared,
+    init(ownsNowPlaying: Bool = true,
+         diagnosticPool: ItemDiagnosticReadPool = .shared,
          diagnosticRead: @escaping AVPlayerItemDiagnostics.Read = ItemDiagnosticSnapshot.read) {
+        self.ownsNowPlaying = ownsNowPlaying
         self.diagnosticPool = diagnosticPool
         self.diagnosticRead = diagnosticRead
         #if os(tvOS) || os(iOS)
@@ -98,7 +103,7 @@ final class AudioAVPlayerHost {
         // manual-publish design whose MPMediaItemArtwork closure was non-@Sendable and tripped
         // dispatch_assert_queue_fail when MediaPlayer requested the bitmap off-actor.
         nowPlayingSession.automaticallyPublishesNowPlayingInfo = true
-        nowPlayingSession.becomeActiveIfPossible(completion: { _ in })
+        if ownsNowPlaying { nowPlayingSession.becomeActiveIfPossible(completion: { _ in }) }
         #endif
     }
 
@@ -106,6 +111,7 @@ final class AudioAVPlayerHost {
     /// Home overlay + remote commands alive across a background pause).
     func becomeActiveNowPlaying() {
         #if os(tvOS) || os(iOS)
+        guard ownsNowPlaying else { return }
         nowPlayingSession.becomeActiveIfPossible(completion: { _ in })
         #endif
     }
diff --git a/Sources/AetherEngine/SharedOutputCoordinator.swift b/Sources/AetherEngine/SharedOutputCoordinator.swift
index cfc7d966e..9c2c624c3 100644
--- a/Sources/AetherEngine/SharedOutputCoordinator.swift
+++ b/Sources/AetherEngine/SharedOutputCoordinator.swift
@@ -31,7 +31,7 @@ final class SharedOutputCoordinator {
     /// it, the engine that opted in could leave first and the one that did not would close the round.
     private var releaseOwed = false
     /// Criteria writers that stopped while others still played. Keyed by engine, so one that loads
-    /// again drops its own reset instead of having it wipe the criteria it has just written.
+    /// again as `.primary` drops its own reset instead of having it wipe the criteria it has just written.
     private var deferredCriteriaResets: [ObjectIdentifier: @MainActor () -> Void] = [:]
     private var lastTransition: Task<Void, Never>?
 
@@ -61,7 +61,8 @@ final class SharedOutputCoordinator {
     func join(_ id: ObjectIdentifier, role: SharedOutputRole, tag: String?, owner: AnyObject? = nil) {
         let channels = members[id]?.sourceChannels
         members[id] = Member(role: role, tag: tag, sourceChannels: channels, owner: owner, tracksOwner: owner != nil)
-        deferredCriteriaResets[id] = nil
+        // A secondary never writes criteria the pending reset could wipe, so it keeps the reset owed.
+        if role == .primary { deferredCriteriaResets[id] = nil }
     }
 
     func noteSourceChannels(_ channels: Int?, for id: ObjectIdentifier) {
diff --git a/Tests/AetherEngineTests/DisplayCriteriaPlayGateTests.swift b/Tests/AetherEngineTests/DisplayCriteriaPlayGateTests.swift
index 9423b168b..bfc6c12f5 100644
--- a/Tests/AetherEngineTests/DisplayCriteriaPlayGateTests.swift
+++ b/Tests/AetherEngineTests/DisplayCriteriaPlayGateTests.swift
@@ -58,6 +58,17 @@ struct DisplayCriteriaPlayGateTests {
             formatKnown: false, effectiveFormat: .sdr) == .full)
     }
 
+    @Test("A secondary load skips the gate: nobody writes criteria for it (Sodalite#175)")
+    func secondaryLoadSkips() {
+        for format: VideoFormat in [.sdr, .hdr10, .dolbyVision] {
+            for known in [true, false] {
+                #expect(AetherEngine.playGateGrace(
+                    criteriaUnchanged: false, engineIsCriteriaWriter: false,
+                    formatKnown: known, effectiveFormat: format, noWriterExpected: true) == .skip)
+            }
+        }
+    }
+
     @Test("Budgets are the documented millisecond values")
     func graceBudgets() {
         #expect(DisplayCriteriaController.StartGrace.skip.budgetMs == 0)
diff --git a/Tests/AetherEngineTests/SharedOutputCoordinatorTests.swift b/Tests/AetherEngineTests/SharedOutputCoordinatorTests.swift
index a7a773889..ec23bf332 100644
--- a/Tests/AetherEngineTests/SharedOutputCoordinatorTests.swift
+++ b/Tests/AetherEngineTests/SharedOutputCoordinatorTests.swift
@@ -121,6 +121,21 @@ struct SharedOutputCoordinatorTests {
         #expect(resets == 0)
     }
 
+    @Test("a secondary rejoin keeps the deferred reset")
+    func secondaryRejoinKeepsDeferredReset() {
+        let c = SharedOutputCoordinator()
+        var resets = 0
+        c.join(a, role: .primary, tag: nil)
+        c.join(b, role: .primary, tag: nil)
+        _ = c.leave(a, releasesSession: true)
+        c.deferCriteriaReset(for: a) { resets += 1 }
+        c.join(a, role: .secondary, tag: nil)
+        _ = c.leave(b, releasesSession: true)
+        #expect(resets == 0)
+        _ = c.leave(a, releasesSession: true)
+        #expect(resets == 1)
+    }
+
     @Test("a reset deferred when nobody else is playing runs at once instead of leaking into a later round")
     func deferWithNobodyLeftRunsImmediately() {
         let c = SharedOutputCoordinator()

From a385673116f1ff5278e1c622998abcd657aba7bc Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 1 Oct 2026 05:43:59 +0200
Subject: [PATCH 260/359] docs(api): what counts as playing, logTag and the
 role's lifetime for several engines (Sodalite#175)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 docs/api.md | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/docs/api.md b/docs/api.md
index 34b99fd92..03e98ed97 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -329,6 +329,7 @@ arrive together.
 | `LoadOptions.prepareNativeSubtitles`, `externalSubtitles` | the native renditions are declared in the init segment |
 | `LoadOptions.panelIsInHDRMode`, `panelPresentsDolbyVision`, `matchContentEnabled` | the display-criteria handshake and the format clamp both run synchronously inside `load` |
 | `pictureInPictureActive` | governs the background teardown decision at the moment it happens |
+| `logTag` | entered into the shared-output book when the load joins it, so a tag set later is missing from those log lines until the next `load()` |
 
 ### Isolation, and what runs off the main actor
 
@@ -406,8 +407,8 @@ Each `AetherEngine` has its own loopback server, caches and lifecycle, so two or
 
 - The audio session is released only by the last engine to stop, and only if some engine in that round had `deactivatesAudioSessionOnStop`.
 - The preferred output channel count is the widest source among the playing engines, so a muted stereo tile cannot downmix a 5.1 one.
-- A display-criteria reset waits until the last engine stops; an engine that loads again in the meantime cancels its own pending reset.
-- Stop every engine before you let go of it. An engine released without `stop()` is noticed and dropped the next time another engine asks, but until then it counts as playing.
+- A display-criteria reset waits until the last engine stops, the ones a load runs to clear stale criteria included; an engine that loads again as `.primary` in the meantime cancels its own pending reset, one that loads again as `.secondary` keeps it.
+- Stop every engine before you let go of it. An engine counts as playing from `load()` until `stop()`, whatever its state, `.error` and `.ended` included, so an engine kept for reuse must be stopped when its tile ends or fails, or the last real stop will not release the session. An engine released without `stop()` is noticed and dropped the next time another engine asks, but until then it counts as playing.
 
 Load one engine as `.primary` and the others with `LoadOptions(sharedOutputRole: .secondary)`, set `logTag` (set before `load()`) on each, and control what is audible with `volume`. Every engine keeps decoding its audio, so switching the audible one is a volume change and not a reload.
 
@@ -994,7 +995,7 @@ All flags default to safe values; the table is the full set. Depth for the media
 | `dolbyVisionHandling` | `.automatic` | A `DolbyVisionHandling`. `.baseLayerOnly` presents the HDR10 / HLG base layer of a Dolby Vision source and leaves the Dolby Vision out of the container on every display: plain `hvc1` / `av01` sample entry, `dvcC` stripped, no `SUPPLEMENTAL-CODECS`, HDR10 / HLG display criteria, `videoFormat` reads the base layer's format while `sourceVideoFormat` and `sourceDVProfile` keep saying what the file carries. The route a host offers as "Dolby Vision: off (HDR10)", for a source whose Dolby Vision is wrong and whose base layer is right: the reported shape is a remux carrying a Profile 7 RPU under a container record claiming Profile 5, where a player that believes the record decodes YCbCr as IPT and the picture comes out green / violet. Applies to HEVC Profile 7 / 8.1 / 8.4, AV1 Profile 10.1 / 10.4, and a Profile 5 (or AV1 10.0) record whose VUI declares a BT.2020 YCbCr PQ or HLG base; a Profile 5 whose VUI is unspecified carries IPT-PQ-c2, has no base layer to present, keeps its route, and the engine says so in the log. Takes precedence over `forceDolbyVisionOnNonDVDisplay`. A tuning field, correctable through `reloadAtCurrentPosition(applying:)`; a Profile 5 record the VUI contradicts also stops refusing the software path under it. See [formats.md](formats.md#dolby-vision-signaling). |
 | `preferredDecodePath` | `.automatic` | A `DecodePath`. `.software` serves this source through `SoftwarePlaybackHost` whatever the routing concluded, scoped to this session and costing the source nothing (seeks, the audio switch and the title switch all keep working). The escape for the formats `VTCapabilityProbe` deliberately cannot classify, and for live H.264 / HEVC, which never reaches that gate at all. One-way: there is no `.native`. See [Overriding the decode path](#overriding-the-decode-path). |
 | `escalatesToSoftwarePath` | `true` | Whether a native session AVPlayer refuses on its merits (`CoreMediaErrorDomain`), or a live join without an entry point the native route can open (`AetherEngine.LiveJoin`, AE#627), may be rebuilt once on the software path (AE#561). `false` surfaces the failure as `.error` instead, for a host with its own fallback ladder (AE#629). Correctable. |
-| `sharedOutputRole` | `.primary` (default) or `.secondary` | A `SharedOutputRole`. A secondary engine never writes display criteria and never owns Now Playing, whatever `suppressDisplayCriteria` and `ownsVideoNowPlayingSession` say. Identity field: a correction cannot flip it (Sodalite#175). |
+| `sharedOutputRole` | `.primary` (default) or `.secondary` | A `SharedOutputRole`. A secondary engine never writes display criteria and never owns Now Playing, whatever `suppressDisplayCriteria` and `ownsVideoNowPlayingSession` say, on the audio-only path too. It also skips the play gate's wait for a criteria write and the panel readout (`criteriaPanelReadout` is nil, as for any suppressed load), so its HDR labelling relies on `panelIsInHDRMode`. The role is fixed for a session, but a later `load()` may change it: as an identity field it only blocks corrections (Sodalite#175). A host that opted into `ownsVideoNowPlayingSession` and changes the role without a `stop()` keeps the native host's original Now Playing ownership until the next stop. |
 | `deinterlaceMode` | `.auto` | A `DeinterlaceMode` for the software path: the Metal / VideoToolbox graph with a CPU bwdif fallback, or `.software` to force the CPU path. |
 | `deinterlaceFieldRate` | `.field` | A `DeinterlaceFieldRate`: the hardware deinterlacer emits one frame per field (25i to 50p) or per frame. The software fallback is always frame rate, because doubling a CPU bwdif is the wrong trade and a fallback should not change cost class. |
 | `probesize`, `maxAnalyzeDuration` | nil | Caller-bounded open-time probe budget (defaults 50 MB / 60 s). They fail **open**: an over-tight budget loads with late-resolving tracks silently missing rather than throwing, so validate track presence if you tighten them. Do not pass `0` for `maxAnalyzeDuration`; FFmpeg maps it to a shorter heuristic. |

From 7e036dd22043a9ec4a4a1ca8c16e422b91a6eed1 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 1 Oct 2026 06:03:58 +0200
Subject: [PATCH 261/359] chore(release): prep 7.25.0 - several engines in one
 process share the audio session and panel correctly

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                    | 9 +++++++++
 Examples/README.md                              | 2 +-
 README.md                                       | 6 +++---
 Sources/AetherEngine/AetherEngine+Version.swift | 2 +-
 4 files changed, 14 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 43c06fef9..6a5f2b3d5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,15 @@ the public-API contract.
 
 _Nothing yet._
 
+## [7.25.0] - 2026-10-01
+
+### Added
+
+- **Several engines in one process share the audio session, its channel preference, the panel and Now Playing correctly (Sodalite#175, #681).** Measured with two live tiles on an Apple TV: every stop that released the session paused the OTHER engine within 10 ms, picture frozen, 4 of 4. An internal coordinator now tracks which engines are active (join on `load()`, leave on `stop()`): the session is released only by the last engine out and only when a release is owed in that round, the preferred output channel count is the widest playing source, display-criteria resets (on stop and the two load-time clears) wait for the last engine, and activation and release run on one process-wide queue (AE#538 ordering across engines). Owners are held weakly, so an engine released without `stop()` cannot pin the session. A host with one engine sees no change. See `docs/api.md`, "Running several engines at once".
+- **`LoadOptions.sharedOutputRole`** (`SharedOutputRole.primary` default, `.secondary`). A secondary never writes display criteria, skips the play-gate wait for a criteria write nobody will make, and never claims Now Playing, on the video and the audio-only path. Identity field.
+- **`AetherEngine.logTag`**: a short instance name carried by the `[SharedOutput]` lines and a `[AetherEngine:<tag>] state=` line per transition. Set it before `load()`.
+- **`aetherctl play` checks the served `.vtt` against the window its playlist declares (#680):** segments are picked at the playhead by walking EXTINF, `MISPLACED=N` names cues outside their segment's window, and an empty served `.vtt` is now a visible log line.
+
 ## [7.24.0] - 2026-09-30
 
 ### Fixed
diff --git a/Examples/README.md b/Examples/README.md
index d840201d7..c8656177f 100644
--- a/Examples/README.md
+++ b/Examples/README.md
@@ -18,7 +18,7 @@ Three samples covering different audiences:
    ```
    https://github.com/superuser404notfound/AetherEngine
    ```
-   Dependency Rule: Up to Next Major Version, starting from `7.24.0`. Add the `AetherEngine` library product to your app target.
+   Dependency Rule: Up to Next Major Version, starting from `7.25.0`. Add the `AetherEngine` library product to your app target.
 
 3. **Drop the file in.** Replace the Xcode template's default `App.swift` (or whatever the generated `@main` file is called) with the contents of [`MinimalPlayerApp.swift`](MinimalPlayer/MinimalPlayerApp.swift). The file is self-contained: it defines both the `@main App` struct and the `ContentView`.
 
diff --git a/README.md b/README.md
index b906ccb1c..764323133 100644
--- a/README.md
+++ b/README.md
@@ -384,7 +384,7 @@ Subtitle cues land in raw source PTS; render the overlay against `player.sourceT
 Install via Swift Package Manager:
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.24.0")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.25.0")
 ```
 
 Three samples ship in `Examples/`:
@@ -631,10 +631,10 @@ Browse all of this as a searchable site at **[aetherengine.superuser404.de](http
 AetherEngine uses [Semantic Versioning](https://semver.org). The public API surface, every `public` declaration in `Sources/AetherEngine/`, is the stability contract. **Major** removes / renames public symbols or breaks adopters; **Minor** adds public API or codec / format support; **Patch** fixes bugs with no public API change. `internal` types are not part of the contract.
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.24.0")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.25.0")
 ```
 
-Pin to `.upToNextMinor(from: "7.24.0")` for stricter teams that prefer to opt into minor bumps explicitly.
+Pin to `.upToNextMinor(from: "7.25.0")` for stricter teams that prefer to opt into minor bumps explicitly.
 
 ## Requirements
 
diff --git a/Sources/AetherEngine/AetherEngine+Version.swift b/Sources/AetherEngine/AetherEngine+Version.swift
index 89c662e7f..eadbe49f4 100644
--- a/Sources/AetherEngine/AetherEngine+Version.swift
+++ b/Sources/AetherEngine/AetherEngine+Version.swift
@@ -11,5 +11,5 @@ extension AetherEngine {
     ///
     /// Between releases, and in a consumer that pins an unreleased commit for a device test, this
     /// names the last PUBLISHED version the checkout descends from, not every patch in it.
-    public nonisolated static let version = "7.24.0"
+    public nonisolated static let version = "7.25.0"
 }

From a729779c92755844401d83c4943d3820d93b3b63 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 1 Oct 2026 10:27:07 +0200
Subject: [PATCH 262/359] fix(engine): cancelling the task that awaits load()
 ends the load at once (Sodalite#173)

A host that cancelled the Task awaiting load() (a zap past an unreachable
live origin) waited out the whole connect and retry budget, 19 s on the
reporter's box, and every zap queued behind it.

load() now installs a task cancellation handler that tears the in-flight
load down the way stop(resetDisplayCriteria: false, finalTeardown: false)
does, guarded on the load's own generation, so a cancellation that lands
after a newer load or after the load returned touches nothing. A load
started on an already cancelled task throws before it tears down the
running session, and a load following an AE#629 takeover cancels the
rebuild it follows. The AVIOReader size-probe ladder now polls isClosed
instead of waiting out a fallback's 0.75 s stagger.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 Sources/AetherEngine/AetherEngine.swift       |  48 +++-
 Sources/AetherEngine/Demuxer/AVIOReader.swift |   8 +-
 .../CancellableLoadTests.swift                | 240 ++++++++++++++++++
 docs/api.md                                   |   3 +
 4 files changed, 291 insertions(+), 8 deletions(-)
 create mode 100644 Tests/AetherEngineTests/CancellableLoadTests.swift

diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index 65b695ce7..32a1ad03c 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -3766,35 +3766,71 @@ public final class AetherEngine: ObservableObject {
         audioSourceStreamIndex: Int32? = nil,
         discTitleID: Int? = nil
     ) async throws -> SourceProbe? {
+        // Sodalite#173: a task cancelled before the load began has nothing to end; the running session stays.
+        try Task.checkCancellation()
         let attempt = LoadAttempt()
         defer { if let gen = attempt.generation { waitingLoadGenerations.remove(gen) } }
         do {
-            return try await loadSession(
-                source: source, startPosition: startPosition, options: options,
-                audioSourceStreamIndex: audioSourceStreamIndex, discTitleID: discTitleID,
-                attempt: attempt)
+            let probe = try await withTaskCancellationHandler {
+                try await loadSession(
+                    source: source, startPosition: startPosition, options: options,
+                    audioSourceStreamIndex: audioSourceStreamIndex, discTitleID: discTitleID,
+                    attempt: attempt)
+            } onCancel: {
+                Task { @MainActor [weak self] in self?.abandonCancelledLoad(attempt) }
+            }
+            if Task.isCancelled, abandonCancelledLoad(attempt) { throw CancellationError() }
+            return probe
         } catch is CancellationError {
             // AE#629: the engine took this startup over itself (the AE#561 / AE#641 rebuild), so the caller is
             // still waiting for the same thing and gets it, the way a #361 reroute keeps its wait. A
             // load the HOST superseded matches no takeover and unwinds as before.
             guard let generation = attempt.generation,
                   let takeover = softwarePathTakeover,
-                  takeover.supersededGeneration == generation else { throw CancellationError() }
+                  takeover.supersededGeneration == generation else {
+                if Task.isCancelled { abandonCancelledLoad(attempt) }
+                throw CancellationError()
+            }
             EngineLog.emit(
                 "[AetherEngine] #629 load (gen \(generation)) follows the engine's own rebuild "
                 + "instead of unwinding", category: .engine)
-            try await takeover.rebuild.value
+            // Sodalite#173: cancelling the follower cancels the rebuild it follows, whose own load then ends.
+            try await withTaskCancellationHandler {
+                try await takeover.rebuild.value
+            } onCancel: {
+                takeover.rebuild.cancel()
+            }
             return attempt.probe
+        } catch {
+            guard Task.isCancelled else { throw error }
+            abandonCancelledLoad(attempt)
+            throw CancellationError()
         }
     }
 
     /// What `loadSession` tells the public `load` about itself: the generation it ran under and the
     /// probe it assembled, which a load followed across a takeover still returns (AE#629).
+    @MainActor
     final class LoadAttempt {
         var generation: UInt64?
         var probe: SourceProbe?
     }
 
+    /// Sodalite#173: the caller cancelled the task awaiting this load. Ends it the way a `stop()` would, so
+    /// every blocking open is aborted and the load's next checkpoint throws, but only while this load is
+    /// still the one in flight: a newer load, or a session this one already returned, is not its to end.
+    /// The panel mode is left for the next load, as a load that fails leaves it.
+    @discardableResult
+    func abandonCancelledLoad(_ attempt: LoadAttempt) -> Bool {
+        guard let gen = attempt.generation, loadGeneration == gen,
+              waitingLoadGenerations.contains(gen) else { return false }
+        EngineLog.emit(
+            "[AetherEngine] Sodalite#173: load (gen \(gen)) cancelled by its caller; tearing it down",
+            category: .engine)
+        stop(resetDisplayCriteria: false, finalTeardown: false)
+        return true
+    }
+
     private func loadSession(
         source: MediaSource,
         startPosition: Double?,
diff --git a/Sources/AetherEngine/Demuxer/AVIOReader.swift b/Sources/AetherEngine/Demuxer/AVIOReader.swift
index df07763d5..808f02ebe 100644
--- a/Sources/AetherEngine/Demuxer/AVIOReader.swift
+++ b/Sources/AetherEngine/Demuxer/AVIOReader.swift
@@ -4127,10 +4127,14 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
 
         // Budget mirrors a single sequential probe (its own 20-25 s ceiling) plus the stagger;
         // isClosed teardown breaks the individual probes, which then signal outstanding down.
+        // Sodalite#173: the wait polls isClosed itself, since a fallback still asleep in its stagger
+        // would otherwise hold a closed open for up to the full stagger.
         let deadline = Date(timeIntervalSinceNow: Self.sizeProbeStaggerSeconds + min(25, chunkRequestTimeout) + 2)
         state.cond.lock()
-        while state.resolvedSize <= 0 && state.outstanding > 0 {
-            if !state.cond.wait(until: deadline) { break }
+        while state.resolvedSize <= 0 && state.outstanding > 0 && !isClosed {
+            let now = Date()
+            if now >= deadline { break }
+            _ = state.cond.wait(until: min(deadline, now.addingTimeInterval(0.05)))
         }
         let size = state.resolvedSize
         state.cond.unlock()
diff --git a/Tests/AetherEngineTests/CancellableLoadTests.swift b/Tests/AetherEngineTests/CancellableLoadTests.swift
new file mode 100644
index 000000000..41a515a8e
--- /dev/null
+++ b/Tests/AetherEngineTests/CancellableLoadTests.swift
@@ -0,0 +1,240 @@
+import Foundation
+import Testing
+@testable import AetherEngine
+
+/// Sodalite#173: a host that cancels the Task awaiting `load()` (a zap past an unreachable channel)
+/// waited out the whole connect budget, 19 s on the reporter's box, and every zap queued behind it.
+/// Cancelling that Task now ends the load at once, the way a `stop()` would have.
+@Suite("Cancelling the task that awaits load() ends the load", .serialized, .timeLimit(.minutes(2)))
+@MainActor
+struct CancellableLoadTests {
+
+    /// Parks its first read until the engine closes or cancels it, or until `fallback` runs out,
+    /// which only an engine that never reaches it lets happen.
+    final class ParkedReader: IOReader, @unchecked Sendable {
+        private let condition = NSCondition()
+        private let fallback: TimeInterval
+        private var arrivals = 0
+        private var releasedByEngine = false
+
+        init(fallback: TimeInterval = 10) { self.fallback = fallback }
+
+        var entered: Bool { condition.withLock { arrivals > 0 } }
+        var wasReleasedByEngine: Bool { condition.withLock { releasedByEngine } }
+
+        func read(_ buffer: UnsafeMutablePointer<UInt8>?, size: Int32) -> Int32 {
+            condition.lock()
+            defer { condition.unlock() }
+            arrivals += 1
+            let deadline = Date().addingTimeInterval(fallback)
+            while !releasedByEngine, condition.wait(until: deadline) {}
+            return -1
+        }
+        func seek(offset: Int64, whence: Int32) -> Int64 { -1 }
+        func close() { condition.withLock { releasedByEngine = true; condition.broadcast() } }
+        func cancel() { close() }
+        func makeIndependentReader() -> IOReader? { nil }
+        var discImageProbeEnabled: Bool { false }
+    }
+
+    enum Outcome: Equatable { case returned, cancelled, failed(String) }
+
+    final class OutcomeBox {
+        var outcome: Outcome?
+    }
+
+    private static func start(_ engine: AetherEngine, _ source: MediaSource,
+                              options: LoadOptions = .init()) -> (Task<Void, Never>, OutcomeBox) {
+        let box = OutcomeBox()
+        let task = Task { @MainActor in
+            do {
+                _ = try await engine.load(source: source, options: options)
+                box.outcome = .returned
+            } catch is CancellationError {
+                box.outcome = .cancelled
+            } catch {
+                box.outcome = .failed("\(error)")
+            }
+        }
+        return (task, box)
+    }
+
+    /// Cancels after the load has been held a moment, and reports whether it ended within `budget`.
+    private static func cancelAndTime(_ task: Task<Void, Never>, _ box: OutcomeBox,
+                                      budget: Duration = .milliseconds(1500)) async throws -> Duration {
+        try await Task.sleep(for: .milliseconds(200))
+        let clock = ContinuousClock()
+        let cancelledAt = clock.now
+        task.cancel()
+        _ = try await waitFor(upTo: budget) { box.outcome != nil }
+        return clock.now - cancelledAt
+    }
+
+    private static func fixture() throws -> Data { try ProbeTestFixtures.hdr10Plus() }
+
+    @Test("A custom source blocked in its read ends with CancellationError once its task is cancelled")
+    func customSourceBlockedInRead() async throws {
+        let engine = try AetherEngine()
+        defer { engine.stop() }
+        let reader = ParkedReader()
+        let (task, box) = Self.start(engine, .custom(reader, formatHint: "mpegts"))
+        try await waitFor { reader.entered }
+
+        let elapsed = try await Self.cancelAndTime(task, box)
+        #expect(box.outcome == .cancelled, "ended \(String(describing: box.outcome)) after \(elapsed)")
+        #expect(elapsed < .milliseconds(1500))
+        #expect(reader.wasReleasedByEngine)
+        await task.value
+        #expect(engine.state == .idle)
+        #expect(engine.loadedURL == nil)
+    }
+
+    @Test("A URL source whose origin never answers ends with CancellationError once its task is cancelled")
+    func urlSourceWithSilentOrigin() async throws {
+        let origin = try ProbeHTTPTestOrigin(data: try Self.fixture())
+        origin.holdLaterRequests()
+        defer { origin.stop() }
+        let engine = try AetherEngine()
+        defer { engine.stop() }
+        let url = try #require(URL(string: "http://127.0.0.1:\(origin.port)/silent.mp4"))
+        let (task, box) = Self.start(engine, .url(url))
+        try await waitFor { !origin.requests.isEmpty }
+
+        let elapsed = try await Self.cancelAndTime(task, box)
+        #expect(box.outcome == .cancelled, "ended \(String(describing: box.outcome)) after \(elapsed)")
+        #expect(elapsed < .milliseconds(1500))
+        origin.stop()
+        await task.value
+        #expect(engine.state == .idle)
+    }
+
+    @Test("A live HLS ingest whose origin never answers ends with CancellationError once its task is cancelled")
+    func liveIngestWithSilentOrigin() async throws {
+        let origin = try ProbeHTTPTestOrigin(data: Data("#EXTM3U\n".utf8))
+        origin.holdLaterRequests()
+        defer { origin.stop() }
+        let engine = try AetherEngine()
+        defer { engine.stop() }
+        let url = try #require(URL(string: "http://127.0.0.1:\(origin.port)/live/index.m3u8"))
+        let reader = HLSLiveIngestReader(playlistURL: url)
+        let (task, box) = Self.start(engine, .custom(reader, formatHint: "mpegts"),
+                                     options: LoadOptions(isLive: true))
+        try await waitFor { !origin.requests.isEmpty }
+
+        let elapsed = try await Self.cancelAndTime(task, box)
+        #expect(box.outcome == .cancelled, "ended \(String(describing: box.outcome)) after \(elapsed)")
+        #expect(elapsed < .milliseconds(1500))
+        origin.stop()
+        await task.value
+        #expect(engine.state == .idle)
+    }
+
+    @Test("A live playlist URL rerouted onto the ingest ends with CancellationError once its task is cancelled")
+    func liveURLWithSilentOrigin() async throws {
+        let origin = try ProbeHTTPTestOrigin(data: Data("#EXTM3U\n".utf8))
+        origin.holdLaterRequests()
+        defer { origin.stop() }
+        let engine = try AetherEngine()
+        defer { engine.stop() }
+        let url = try #require(URL(string: "http://127.0.0.1:\(origin.port)/live/index.m3u8"))
+        var options = LoadOptions(isLive: true)
+        options.nativeRemoteHLS = false
+        let (task, box) = Self.start(engine, .url(url), options: options)
+        try await waitFor { !origin.requests.isEmpty }
+
+        let elapsed = try await Self.cancelAndTime(task, box)
+        #expect(box.outcome == .cancelled, "ended \(String(describing: box.outcome)) after \(elapsed)")
+        #expect(elapsed < .milliseconds(1500))
+        origin.stop()
+        await task.value
+        #expect(engine.state == .idle)
+    }
+
+    @Test("A load issued after a cancelled one plays normally")
+    func loadAfterCancelledLoad() async throws {
+        let engine = try AetherEngine()
+        defer { engine.stop() }
+        let reader = ParkedReader()
+        let (task, box) = Self.start(engine, .custom(reader, formatHint: "mpegts"))
+        try await waitFor { reader.entered }
+        try await Task.sleep(for: .milliseconds(200))
+        task.cancel()
+        await task.value
+        #expect(box.outcome == .cancelled)
+
+        let probe = try await engine.load(source: .custom(DataIOReader(data: try Self.fixture()), formatHint: "mp4"))
+        #expect(probe != nil)
+        #expect(engine.loadedURL != nil)
+        #expect(engine.state != .idle)
+        #expect(engine.errorInfo == nil)
+    }
+
+    @Test("Cancelling a load and starting the next in the same turn leaves the next one alone")
+    func cancelThenLoadInTheSameTurn() async throws {
+        let engine = try AetherEngine()
+        defer { engine.stop() }
+        let reader = ParkedReader()
+        let (first, firstBox) = Self.start(engine, .custom(reader, formatHint: "mpegts"))
+        try await waitFor { reader.entered }
+
+        first.cancel()
+        let (second, secondBox) = Self.start(
+            engine, .custom(DataIOReader(data: try Self.fixture()), formatHint: "mp4"))
+        await first.value
+        await second.value
+        #expect(firstBox.outcome == .cancelled)
+        #expect(secondBox.outcome == .returned)
+        #expect(engine.loadedURL != nil)
+        #expect(engine.state != .idle)
+    }
+
+    @Test("A cancellation that lands after a newer load took over does not touch it")
+    func staleCancellationSparesTheSuccessor() async throws {
+        let engine = try AetherEngine()
+        defer { engine.stop() }
+        let stale = AetherEngine.LoadAttempt()
+        stale.generation = engine.loadGeneration
+        let reader = ParkedReader()
+        let (task, box) = Self.start(engine, .custom(reader, formatHint: "mpegts"))
+        try await waitFor { reader.entered }
+
+        engine.abandonCancelledLoad(stale)
+        let touched = try await waitFor(upTo: .milliseconds(300)) { reader.wasReleasedByEngine }
+        #expect(!touched)
+        #expect(engine.state == .loading)
+        task.cancel()
+        await task.value
+        #expect(box.outcome == .cancelled)
+    }
+
+    @Test("A cancellation that lands after the load returned leaves the session playing")
+    func lateCancellationSparesTheLoadedSession() async throws {
+        let engine = try AetherEngine()
+        defer { engine.stop() }
+        let attempt = AetherEngine.LoadAttempt()
+        _ = try await engine.load(source: .custom(DataIOReader(data: try Self.fixture()), formatHint: "mp4"))
+        attempt.generation = engine.loadGeneration
+
+        engine.abandonCancelledLoad(attempt)
+        #expect(engine.loadedURL != nil)
+        #expect(engine.state != .idle)
+    }
+
+    @Test("A load started on an already cancelled task throws without tearing down the running session")
+    func alreadyCancelledTaskLeavesTheRunningSession() async throws {
+        let engine = try AetherEngine()
+        defer { engine.stop() }
+        _ = try await engine.load(source: .custom(DataIOReader(data: try Self.fixture()), formatHint: "mp4"))
+        let generation = engine.loadGeneration
+        let reader = ParkedReader(fallback: 2)
+
+        let task = Task { @MainActor in
+            withUnsafeCurrentTask { $0?.cancel() }
+            _ = try await engine.load(source: .custom(reader, formatHint: "mpegts"))
+        }
+        await #expect(throws: CancellationError.self) { try await task.value }
+        #expect(!reader.entered)
+        #expect(engine.loadGeneration == generation)
+        #expect(engine.loadedURL != nil)
+    }
+}
diff --git a/docs/api.md b/docs/api.md
index 03e98ed97..50276711f 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -35,6 +35,7 @@ A working shape for the live contracts below, compiled against the engine: [`Exa
 | --- | --- | --- |
 | The source could not be opened, probed, or routed | throws | `.error(message)` is published as well |
 | A newer `load()` or a `stop()` superseded this one | throws `CancellationError` | belongs to the successor, untouched |
+| The Task awaiting it was cancelled while it ran (Sodalite#173) | throws `CancellationError` | `.idle`, as after a `stop()` |
 | AVPlayer refused the media during startup and the engine rebuilt the session on the software path (AE#561) | keeps waiting, then returns (or throws what the rebuild threw) | whatever the rebuilt session reaches; `softwarePathEscalations` fires with `duringStartup` |
 | A custom `IOReader` whose initial probe failed | throws | `.error` |
 | Dolby Vision with no compatible base layer on the software path | throws `AetherEngineError.dolbyVisionUnplayableOnSoftwarePath` | `.error` |
@@ -453,6 +454,8 @@ try await player.reloadAtCurrentPosition()
 | `ProbeError` | `invalidLimits`, `inputLimit`, `packetLimit`, `packetSizeLimit`, `timedOut`, `invalidReaderResult`, `unsupportedURL`, `sourceBusy`; `errorDescription` describes the stop. Explicit caller cancellation throws `CancellationError` instead. |
 | `AetherEngine.externalSubtitleTrackIDBase` | `100_000`. Synthetic ids of external subtitle tracks start here. |
 
+Cancelling the Task that awaits `load()` ends the load at once: it throws `CancellationError` within milliseconds instead of running its connect, open, retry and probe budgets to the end (an unreachable live origin used to hold it for about 19 s). The engine tears the load down the way `stop(resetDisplayCriteria: false, finalTeardown: false)` would, so a blocked network read, `avformat_open_input` / `find_stream_info`, a size probe, an `HLSLiveIngestReader` retry and a custom reader's blocking `read` are all aborted (a custom reader is closed), `state` becomes `.idle`, and the panel keeps its mode for the next load. A cancellation only ends the load it belongs to: one that arrives after a newer `load()` or `stop()` took over, or after the load returned, changes nothing. A `load()` called from a Task that is already cancelled throws before it touches the running session. The same holds for a `reloadAtCurrentPosition()` of a URL source, which goes through `load()`. A load that returned before the cancellation is not undone; on the `nativeRemoteHLS` bypass `load()` returns at the mount, so a host leaving that startup calls `stop()`. Not cancelling changes nothing.
+
 ### Whole-probe limits and cancellation
 
 Existing calls retain their open policy: `limits: nil, cancellation: nil`. Passing `limits: .init()`

From 65a6e429b3468fc68dec3825ac0840fb1261cd2a Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 1 Oct 2026 10:43:25 +0200
Subject: [PATCH 263/359] fix(engine): a cancelled load leaves the session the
 way a newer load would (Sodalite#173)

The first round ended a cancelled load with a host stop(), which dropped
the native host and AVPlayer (#15) and an AE#158 handover item that the
next load's own teardown would have kept, so every zap that cancelled a
load lost AVPlayer reuse. The cancelled generation is now ended with the
supersede teardown (native host and handover item kept, panel mode kept,
no audio-session release) plus the published reset to .idle.

A load following an AE#629 rebuild no longer cancels the rebuild's Task,
which the retained-reader branch never observed; it ends the rebuild's
generation instead, and the rebuild unwinds at its own checkpoints. A
load cancelled before it began withdraws a reroute's #361 continuation,
and AVIOReader no longer logs streaming mode for a closed size ladder.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 Sources/AetherEngine/AetherEngine.swift       |  66 ++++++--
 Sources/AetherEngine/Demuxer/AVIOReader.swift |   2 +-
 .../Native/SoftwarePathEscalation.swift       |   2 +
 .../CancellableLoadTests.swift                | 144 ++++++++++++++++++
 docs/api.md                                   |   4 +-
 5 files changed, 202 insertions(+), 16 deletions(-)

diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index 32a1ad03c..8fa9a6251 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -3767,7 +3767,11 @@ public final class AetherEngine: ObservableObject {
         discTitleID: Int? = nil
     ) async throws -> SourceProbe? {
         // Sodalite#173: a task cancelled before the load began has nothing to end; the running session stays.
-        try Task.checkCancellation()
+        // A reroute's #361 continuation armed for this load is withdrawn with it.
+        if Task.isCancelled {
+            abandonStartupContinuation()
+            throw CancellationError()
+        }
         let attempt = LoadAttempt()
         defer { if let gen = attempt.generation { waitingLoadGenerations.remove(gen) } }
         do {
@@ -3794,11 +3798,21 @@ public final class AetherEngine: ObservableObject {
             EngineLog.emit(
                 "[AetherEngine] #629 load (gen \(generation)) follows the engine's own rebuild "
                 + "instead of unwinding", category: .engine)
-            // Sodalite#173: cancelling the follower cancels the rebuild it follows, whose own load then ends.
-            try await withTaskCancellationHandler {
-                try await takeover.rebuild.value
-            } onCancel: {
-                takeover.rebuild.cancel()
+            // Sodalite#173: a cancelled follower ends the rebuild's generation, not the rebuild's Task, so
+            // the rebuild unwinds at its own checkpoints on either branch (load() or the retained reader).
+            do {
+                try await withTaskCancellationHandler {
+                    try await takeover.rebuild.value
+                } onCancel: {
+                    Task { @MainActor [weak self] in self?.abandonFollowedRebuild(takeover, follower: attempt) }
+                }
+            } catch {
+                if Task.isCancelled { throw CancellationError() }
+                throw error
+            }
+            if Task.isCancelled {
+                abandonFollowedRebuild(takeover, follower: attempt)
+                throw CancellationError()
             }
             return attempt.probe
         } catch {
@@ -3816,19 +3830,45 @@ public final class AetherEngine: ObservableObject {
         var probe: SourceProbe?
     }
 
-    /// Sodalite#173: the caller cancelled the task awaiting this load. Ends it the way a `stop()` would, so
-    /// every blocking open is aborted and the load's next checkpoint throws, but only while this load is
-    /// still the one in flight: a newer load, or a session this one already returned, is not its to end.
-    /// The panel mode is left for the next load, as a load that fails leaves it.
+    /// Sodalite#173: the caller cancelled the task awaiting this load. Ends it only while it is still the
+    /// load in flight: a newer load, or a session this one already returned, is not its to end.
     @discardableResult
     func abandonCancelledLoad(_ attempt: LoadAttempt) -> Bool {
         guard let gen = attempt.generation, loadGeneration == gen,
               waitingLoadGenerations.contains(gen) else { return false }
+        endCancelledGeneration(gen)
+        return true
+    }
+
+    /// Sodalite#173: the same for a load following an AE#629 rebuild, whose generation is the one the
+    /// rebuild's teardown opened. Only while the follower still waits and nothing newer took over.
+    func abandonFollowedRebuild(_ takeover: SoftwarePathEscalation.Takeover, follower: LoadAttempt) {
+        guard let followed = follower.generation, waitingLoadGenerations.contains(followed),
+              loadGeneration == takeover.rebuildGeneration else { return }
+        endCancelledGeneration(takeover.rebuildGeneration)
+    }
+
+    /// Leaves the engine the way the next `load()`'s teardown would: the generation moves on, every
+    /// blocking open is aborted and the custom reader closed, while the native host (#15) and an AE#158
+    /// handover item are kept for that load and the panel keeps its mode. `state` reads `.idle`; a host
+    /// that is leaving playback calls `stop()` to release the rest.
+    private func endCancelledGeneration(_ gen: UInt64) {
         EngineLog.emit(
-            "[AetherEngine] Sodalite#173: load (gen \(gen)) cancelled by its caller; tearing it down",
+            "[AetherEngine] Sodalite#173: load (gen \(gen)) cancelled by its caller; ending it",
             category: .engine)
-        stop(resetDisplayCriteria: false, finalTeardown: false)
-        return true
+        let keepNativeHost = Self.shouldPreserveNativeHostAcrossLoad(
+            backend: playbackBackend, nativeHostSurvives: nativeHost != nil,
+            mediaServicesWereReset: mediaServicesResetPending)
+        stopInternal(resetDisplayCriteria: false, keepNativeHost: keepNativeHost,
+                     keepCurrentItem: keepNativeHost && pendingInPlaceItemHandover)
+        pendingInPlaceItemHandover = false
+        state = .idle
+        startupProgress = nil
+        clock.currentTime = 0
+        clock.bufferedPosition = 0
+        clock.progress = 0
+        loadedURL = nil
+        isCustomSource = false
     }
 
     private func loadSession(
diff --git a/Sources/AetherEngine/Demuxer/AVIOReader.swift b/Sources/AetherEngine/Demuxer/AVIOReader.swift
index 808f02ebe..fa73cb5fb 100644
--- a/Sources/AetherEngine/Demuxer/AVIOReader.swift
+++ b/Sources/AetherEngine/Demuxer/AVIOReader.swift
@@ -4138,7 +4138,7 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
         }
         let size = state.resolvedSize
         state.cond.unlock()
-        if size <= 0 {
+        if size <= 0, !isClosed {
             EngineLog.emit("[AVIOReader] no probe resolved a size, streaming mode (forward-only)", category: .demux)
         }
         return size > 0 ? size : -1
diff --git a/Sources/AetherEngine/Native/SoftwarePathEscalation.swift b/Sources/AetherEngine/Native/SoftwarePathEscalation.swift
index a3bae67c5..c4c61e744 100644
--- a/Sources/AetherEngine/Native/SoftwarePathEscalation.swift
+++ b/Sources/AetherEngine/Native/SoftwarePathEscalation.swift
@@ -92,6 +92,8 @@ enum SoftwarePathEscalation {
     struct Takeover {
         let supersededGeneration: UInt64
         let rebuild: Task<Void, Error>
+        /// The claim runs immediately before the rebuild's own `stopInternal`, which moves the generation by one.
+        var rebuildGeneration: UInt64 { supersededGeneration &+ 1 }
     }
 
     /// The domain of a media failure, i.e. AVFoundation could not make sense of what it was served.
diff --git a/Tests/AetherEngineTests/CancellableLoadTests.swift b/Tests/AetherEngineTests/CancellableLoadTests.swift
index 41a515a8e..82d35b665 100644
--- a/Tests/AetherEngineTests/CancellableLoadTests.swift
+++ b/Tests/AetherEngineTests/CancellableLoadTests.swift
@@ -1,3 +1,4 @@
+import Combine
 import Foundation
 import Testing
 @testable import AetherEngine
@@ -237,4 +238,147 @@ struct CancellableLoadTests {
         #expect(engine.loadGeneration == generation)
         #expect(engine.loadedURL != nil)
     }
+    @Test("A plain cancel publishes no error on its way to idle")
+    func cancelPublishesNoError() async throws {
+        let engine = try AetherEngine()
+        defer { engine.stop() }
+        var states: [PlaybackState] = []
+        let sub = engine.$state.sink { states.append($0) }
+        defer { sub.cancel() }
+        let reader = ParkedReader()
+        let (task, box) = Self.start(engine, .custom(reader, formatHint: "mpegts"))
+        try await waitFor { reader.entered }
+        task.cancel()
+        await task.value
+
+        #expect(box.outcome == .cancelled)
+        #expect(!states.contains { if case .error = $0 { return true } else { return false } }, "\(states)")
+        #expect(states.last == .idle)
+        #expect(engine.errorInfo == nil)
+    }
+
+    @Test("Cancel-then-load keeps the native player the way a newer load would (#15)")
+    func cancelKeepsTheNativePlayer() async throws {
+        let engine = try AetherEngine()
+        defer { engine.stop() }
+        _ = try await engine.load(source: .custom(DataIOReader(data: try Self.fixture()), formatHint: "mp4"))
+        let host = try #require(engine.nativeHost)
+        let player = try #require(engine.currentAVPlayer)
+
+        let reader = ParkedReader()
+        let (task, box) = Self.start(engine, .custom(reader, formatHint: "mpegts"))
+        try await waitFor { reader.entered }
+        task.cancel()
+        await task.value
+        #expect(box.outcome == .cancelled)
+        #expect(engine.nativeHost === host)
+        #expect(engine.currentAVPlayer === player)
+
+        _ = try await engine.load(source: .custom(DataIOReader(data: try Self.fixture()), formatHint: "mp4"))
+        #expect(engine.nativeHost === host)
+        #expect(engine.currentAVPlayer === player)
+    }
+
+    @Test("Cancelling a load that follows an engine rebuild ends the rebuild's load and throws (AE#629)")
+    func cancelledFollowerEndsTheRebuild() async throws {
+        let engine = try AetherEngine()
+        defer { engine.stop() }
+        let hostReader = ParkedReader()
+        let (hostLoad, hostBox) = Self.start(engine, .custom(hostReader, formatHint: "mpegts"))
+        try await waitFor { hostReader.entered }
+        let generation = engine.loadGeneration
+
+        // The escalation's rebuild: armed for the live generation, claimed by its own load's teardown.
+        let rebuildReader = ParkedReader()
+        let rebuild = Task { @MainActor in
+            _ = try await engine.load(source: .custom(rebuildReader, formatHint: "mpegts"))
+        }
+        engine.softwarePathRebuild = rebuild
+        engine.softwarePathTakeoverArm = generation
+        try await waitFor { rebuildReader.entered }
+        #expect(engine.softwarePathTakeover?.supersededGeneration == generation)
+        #expect(hostBox.outcome == nil)
+
+        let elapsed = try await Self.cancelAndTime(hostLoad, hostBox)
+        #expect(hostBox.outcome == .cancelled, "ended \(String(describing: hostBox.outcome)) after \(elapsed)")
+        #expect(rebuildReader.wasReleasedByEngine)
+        await #expect(throws: CancellationError.self) { try await rebuild.value }
+        #expect(engine.state == .idle)
+        #expect(engine.errorInfo == nil)
+    }
+    @Test("A reroute's startup continuation does not outlive a load that was cancelled before it began (#361)")
+    func cancelledRerouteWithdrawsItsContinuation() async throws {
+        let engine = try AetherEngine()
+        defer { engine.stop() }
+        let before = engine.startupGeneration
+        let task = Task { @MainActor in
+            withUnsafeCurrentTask { $0?.cancel() }
+            engine.continueStartupAcrossReroute()
+            _ = try await engine.load(source: .custom(ParkedReader(fallback: 2), formatHint: "mpegts"))
+        }
+        await #expect(throws: CancellationError.self) { try await task.value }
+
+        _ = try await engine.load(source: .custom(DataIOReader(data: try Self.fixture()), formatHint: "mp4"))
+        #expect(engine.startupGeneration == before &+ 1)
+    }
+    /// A reader whose `cancel()` only unblocks the read in flight (the IOReader contract) and whose
+    /// `close()` ends it, so a rebuild can park on it again after the probe that preceded it was aborted.
+    final class RetainedReader: IOReader, @unchecked Sendable {
+        private let condition = NSCondition()
+        private var cancels = 0
+        private var arrivals = 0
+        private var closed = false
+
+        var arrivalCount: Int { condition.withLock { arrivals } }
+        var isClosed: Bool { condition.withLock { closed } }
+
+        func read(_ buffer: UnsafeMutablePointer<UInt8>?, size: Int32) -> Int32 {
+            condition.lock()
+            defer { condition.unlock() }
+            let epoch = cancels
+            arrivals += 1
+            let deadline = Date().addingTimeInterval(10)
+            while !closed, cancels == epoch, condition.wait(until: deadline) {}
+            return -1
+        }
+        func seek(offset: Int64, whence: Int32) -> Int64 { -1 }
+        func close() { condition.withLock { closed = true; condition.broadcast() } }
+        func cancel() { condition.withLock { cancels += 1; condition.broadcast() } }
+        func makeIndependentReader() -> IOReader? { nil }
+        var discImageProbeEnabled: Bool { false }
+    }
+
+    /// The custom-source rebuild runs `reloadWithAudioOverride` on the retained reader with its probe
+    /// detached, which cancelling the rebuild's Task does not reach. Modelled here by that shape.
+    @Test("Cancelling a follower ends a retained-reader rebuild that Task cancellation cannot reach (AE#629)")
+    func cancelledFollowerEndsARetainedReaderRebuild() async throws {
+        let engine = try AetherEngine()
+        defer { engine.stop() }
+        let reader = RetainedReader()
+        let (hostLoad, hostBox) = Self.start(engine, .custom(reader, formatHint: "mpegts"))
+        try await waitFor { reader.arrivalCount > 0 }
+        let generation = engine.loadGeneration
+
+        let rebuild = Task { @MainActor in
+            engine.claimSoftwarePathTakeover()
+            engine.stopInternal(resetDisplayCriteria: false, keepCustomReader: true)
+            let gen = engine.loadGeneration
+            await Task.detached {
+                var byte: UInt8 = 0
+                _ = reader.read(&byte, size: 1)
+            }.value
+            try engine.checkLoadCurrent(gen)
+        }
+        engine.softwarePathRebuild = rebuild
+        engine.softwarePathTakeoverArm = generation
+        try await waitFor { engine.softwarePathTakeover != nil && reader.arrivalCount > 1 }
+
+        let elapsed = try await Self.cancelAndTime(hostLoad, hostBox)
+        #expect(hostBox.outcome == .cancelled, "ended \(String(describing: hostBox.outcome)) after \(elapsed)")
+        #expect(elapsed < .milliseconds(1500))
+        #expect(reader.isClosed)
+        await #expect(throws: CancellationError.self) { try await rebuild.value }
+        await hostLoad.value
+        #expect(engine.state == .idle)
+    }
 }
diff --git a/docs/api.md b/docs/api.md
index 50276711f..8037c4953 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -35,7 +35,7 @@ A working shape for the live contracts below, compiled against the engine: [`Exa
 | --- | --- | --- |
 | The source could not be opened, probed, or routed | throws | `.error(message)` is published as well |
 | A newer `load()` or a `stop()` superseded this one | throws `CancellationError` | belongs to the successor, untouched |
-| The Task awaiting it was cancelled while it ran (Sodalite#173) | throws `CancellationError` | `.idle`, as after a `stop()` |
+| The Task awaiting it was cancelled while it ran (Sodalite#173) | throws `CancellationError` | `.idle`; the native host is kept for the next load, as a newer `load()` would keep it |
 | AVPlayer refused the media during startup and the engine rebuilt the session on the software path (AE#561) | keeps waiting, then returns (or throws what the rebuild threw) | whatever the rebuilt session reaches; `softwarePathEscalations` fires with `duringStartup` |
 | A custom `IOReader` whose initial probe failed | throws | `.error` |
 | Dolby Vision with no compatible base layer on the software path | throws `AetherEngineError.dolbyVisionUnplayableOnSoftwarePath` | `.error` |
@@ -454,7 +454,7 @@ try await player.reloadAtCurrentPosition()
 | `ProbeError` | `invalidLimits`, `inputLimit`, `packetLimit`, `packetSizeLimit`, `timedOut`, `invalidReaderResult`, `unsupportedURL`, `sourceBusy`; `errorDescription` describes the stop. Explicit caller cancellation throws `CancellationError` instead. |
 | `AetherEngine.externalSubtitleTrackIDBase` | `100_000`. Synthetic ids of external subtitle tracks start here. |
 
-Cancelling the Task that awaits `load()` ends the load at once: it throws `CancellationError` within milliseconds instead of running its connect, open, retry and probe budgets to the end (an unreachable live origin used to hold it for about 19 s). The engine tears the load down the way `stop(resetDisplayCriteria: false, finalTeardown: false)` would, so a blocked network read, `avformat_open_input` / `find_stream_info`, a size probe, an `HLSLiveIngestReader` retry and a custom reader's blocking `read` are all aborted (a custom reader is closed), `state` becomes `.idle`, and the panel keeps its mode for the next load. A cancellation only ends the load it belongs to: one that arrives after a newer `load()` or `stop()` took over, or after the load returned, changes nothing. A `load()` called from a Task that is already cancelled throws before it touches the running session. The same holds for a `reloadAtCurrentPosition()` of a URL source, which goes through `load()`. A load that returned before the cancellation is not undone; on the `nativeRemoteHLS` bypass `load()` returns at the mount, so a host leaving that startup calls `stop()`. Not cancelling changes nothing.
+Cancelling the Task that awaits `load()` ends the load at once: it throws `CancellationError` instead of running its connect, open, retry and probe budgets to the end (an unreachable live origin used to hold it for about 19 s). A blocked network read, `avformat_open_input` / `find_stream_info`, a size probe, an `HLSLiveIngestReader` retry and a custom reader's blocking `read` are all aborted, typically within tens of milliseconds; the one stretch it cannot cut short is the AE#532 Dolby Vision record audit, a detached read the load waits out before it throws. The load is left the way a newer `load()` leaves it: the generation moves on, a custom reader is closed, `state` becomes `.idle`, and the native host and AVPlayer (#15), an AE#158 handover item and the panel mode are kept for the next load. A host that is leaving playback rather than loading the next item calls `stop()` afterwards to release them. A cancellation only ends the load it belongs to: one that arrives after a newer `load()` or `stop()` took over, or after the load returned, changes nothing. A load that follows an engine rebuild (AE#629) ends that rebuild when cancelled. A `load()` called from a Task that is already cancelled throws before it touches the running session. A real failure that coincides with the cancellation is reported as `CancellationError` too, and `state` ends `.idle`, though a transient `.error` may have been published on the way. The same holds for a `reloadAtCurrentPosition()` of a URL source, which goes through `load()`. A load that returned before the cancellation is not undone; on the `nativeRemoteHLS` bypass `load()` returns at the mount, so a host leaving that startup calls `stop()`. Not cancelling changes nothing.
 
 ### Whole-probe limits and cancellation
 

From 155540a8c61cd9deb76a0fc26b84121cc3a5ca29 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 1 Oct 2026 10:51:09 +0200
Subject: [PATCH 264/359] fix(engine): a cancelled software-path rebuild ends
 with its nested reroutes (Sodalite#173)

A load following an AE#629 rebuild ended only the generation the rebuild's
teardown opened, which misses a rebuild whose load() rerouted into a
nested load() (AE#678, AE#363, AE#246/268, #168/#199): the follower threw
over a session that kept starting. Cancelling the follower now also
cancels the rebuild's Task, so load() and its reroutes end through their
own generation-guarded handlers, while the retained-reader branch is
still ended by its generation.

A custom-source reloadAtCurrentPosition() that a stop() or a cancelled
load superseded returned as if it had rebuilt, so the escalation logged
"rebuilt on the software path"; it now throws CancellationError, and a
retained-reader reopen aborted by that supersede is no longer published
as a failed reload. The docs say what a cancel leaves held until the next
load() or stop().

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../AetherEngine/AetherEngine+Loading.swift   | 10 ++
 Sources/AetherEngine/AetherEngine.swift       | 10 +-
 .../CancellableLoadTests.swift                | 99 +++++++++++++++++++
 docs/api.md                                   |  2 +-
 4 files changed, 118 insertions(+), 3 deletions(-)

diff --git a/Sources/AetherEngine/AetherEngine+Loading.swift b/Sources/AetherEngine/AetherEngine+Loading.swift
index fbf3ee89c..79154f246 100644
--- a/Sources/AetherEngine/AetherEngine+Loading.swift
+++ b/Sources/AetherEngine/AetherEngine+Loading.swift
@@ -2359,6 +2359,11 @@ extension AetherEngine {
                     return d
                 }.value
             } catch {
+                // Sodalite#173: a reopen a stop() or a cancelled load aborted is not a failed reload.
+                if loadGeneration != gen {
+                    EngineLog.emit("[AetherEngine] reload superseded during custom reader reopen; unwinding", category: .engine)
+                    return nil
+                }
                 EngineLog.emit("[AetherEngine] reload: custom reader reopen failed: \(error)", category: .engine)
                 activeAudioTrackIndex = previousAudioIndex
                 publishError(.reloadFailed, "Reload failed: \(error.localizedDescription)", underlying: error)
@@ -2384,6 +2389,11 @@ extension AetherEngine {
                     return d
                 }.value
             } catch {
+                // Sodalite#173: a reopen a stop() or a cancelled load aborted is not a failed reload.
+                if loadGeneration != gen {
+                    EngineLog.emit("[AetherEngine] reload superseded during disc URL reopen; unwinding", category: .engine)
+                    return nil
+                }
                 EngineLog.emit("[AetherEngine] reload: disc URL reopen failed: \(error)", category: .engine)
                 activeAudioTrackIndex = previousAudioIndex
                 publishError(.reloadFailed, "Reload failed: \(error.localizedDescription)", underlying: error)
diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index 8fa9a6251..e7cef3c6d 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -3798,12 +3798,14 @@ public final class AetherEngine: ObservableObject {
             EngineLog.emit(
                 "[AetherEngine] #629 load (gen \(generation)) follows the engine's own rebuild "
                 + "instead of unwinding", category: .engine)
-            // Sodalite#173: a cancelled follower ends the rebuild's generation, not the rebuild's Task, so
-            // the rebuild unwinds at its own checkpoints on either branch (load() or the retained reader).
+            // Sodalite#173: a cancelled follower cancels the rebuild's Task, which ends a load() rebuild and
+            // any reroute nested in it through their own handlers, and ends the rebuild's generation, which
+            // the retained-reader branch observes only at its checkpoints. Both are generation-guarded.
             do {
                 try await withTaskCancellationHandler {
                     try await takeover.rebuild.value
                 } onCancel: {
+                    takeover.rebuild.cancel()
                     Task { @MainActor [weak self] in self?.abandonFollowedRebuild(takeover, follower: attempt) }
                 }
             } catch {
@@ -5312,6 +5314,9 @@ public final class AetherEngine: ObservableObject {
                 )
                 throw AetherEngineError.sessionNotReloadable(refusal)
             }
+            // Sodalite#173: the rebuild's own teardown moves the generation by one; anything further is a
+            // stop() or load() that superseded it, which a returned nil does not say.
+            let reloadGeneration = loadGeneration &+ 1
             // Audit LIF-102: the value written above, or the mount flag after a background teardown.
             let failure = await reloadWithAudioOverride(
                 url: placeholderURL,
@@ -5327,6 +5332,7 @@ public final class AetherEngine: ObservableObject {
             // source whose reader read `cancel()` as terminal: the rebuild failed on stream info
             // and the call still returned success.
             if let failure { throw failure }
+            if loadGeneration != reloadGeneration { throw CancellationError() }
             // The reload restores from its own pre-stopInternal snapshot, which a torn-down session
             // no longer had anything in; replay the parked subtitle pick on top of it.
             if resumesTornDownSession {
diff --git a/Tests/AetherEngineTests/CancellableLoadTests.swift b/Tests/AetherEngineTests/CancellableLoadTests.swift
index 82d35b665..2f2962210 100644
--- a/Tests/AetherEngineTests/CancellableLoadTests.swift
+++ b/Tests/AetherEngineTests/CancellableLoadTests.swift
@@ -381,4 +381,103 @@ struct CancellableLoadTests {
         await hostLoad.value
         #expect(engine.state == .idle)
     }
+    @Test("Cancelling a follower ends a rebuild whose load() rerouted into a nested load (AE#629, AE#678)")
+    func cancelledFollowerEndsANestedRerouteRebuild() async throws {
+        let origin = try ProbeHTTPTestOrigin(data: Data("#EXTM3U\n".utf8))
+        origin.holdLaterRequests()
+        defer { origin.stop() }
+        let engine = try AetherEngine()
+        defer { engine.stop() }
+        let hostReader = ParkedReader()
+        let (hostLoad, hostBox) = Self.start(engine, .custom(hostReader, formatHint: "mpegts"))
+        try await waitFor { hostReader.entered }
+        let generation = engine.loadGeneration
+
+        let url = try #require(URL(string: "http://127.0.0.1:\(origin.port)/live/index.m3u8"))
+        var options = LoadOptions(isLive: true)
+        options.nativeRemoteHLS = false
+        let rebuild = Task { @MainActor in
+            _ = try await engine.load(source: .url(url), options: options)
+        }
+        engine.softwarePathRebuild = rebuild
+        engine.softwarePathTakeoverArm = generation
+        try await waitFor { !origin.requests.isEmpty }
+        let takeover = try #require(engine.softwarePathTakeover)
+        #expect(engine.loadGeneration != takeover.rebuildGeneration)
+
+        let elapsed = try await Self.cancelAndTime(hostLoad, hostBox)
+        #expect(hostBox.outcome == .cancelled, "ended \(String(describing: hostBox.outcome)) after \(elapsed)")
+        #expect(elapsed < .milliseconds(1500))
+        await #expect(throws: CancellationError.self) { try await rebuild.value }
+        origin.stop()
+        await hostLoad.value
+        #expect(engine.state == .idle)
+    }
+
+    /// Serves the fixture, and once armed parks any read from the head of the file (where a reopen
+    /// starts) until the engine cancels or closes it.
+    final class HeadGatedReader: IOReader, @unchecked Sendable {
+        private let bytes: Data
+        private let condition = NSCondition()
+        private var position = 0
+        private var armed = false
+        private var parkedAtHead = 0
+
+        init(_ bytes: Data) { self.bytes = bytes }
+
+        func arm() { condition.withLock { armed = true } }
+        var parkedCount: Int { condition.withLock { parkedAtHead } }
+
+        func read(_ buffer: UnsafeMutablePointer<UInt8>?, size: Int32) -> Int32 {
+            guard let buffer, size > 0 else { return -1 }
+            condition.lock()
+            defer { condition.unlock() }
+            if armed, position == 0 {
+                parkedAtHead += 1
+                let parked = parkedAtHead
+                let deadline = Date().addingTimeInterval(10)
+                while armed, parkedAtHead == parked, condition.wait(until: deadline) {}
+                return -1
+            }
+            let n = min(Int(size), bytes.count - position)
+            guard n > 0 else { return -1 }
+            bytes.withUnsafeBytes { raw in _ = memcpy(buffer, raw.baseAddress! + position, n) }
+            position += n
+            return Int32(n)
+        }
+        func seek(offset: Int64, whence: Int32) -> Int64 {
+            condition.withLock {
+                switch whence {
+                case 65536: return Int64(bytes.count)
+                case SEEK_SET: position = Int(max(0, min(offset, Int64(bytes.count))))
+                case SEEK_CUR: position = max(0, min(position + Int(offset), bytes.count))
+                case SEEK_END: position = max(0, min(bytes.count + Int(offset), bytes.count))
+                default: return -1
+                }
+                return Int64(position)
+            }
+        }
+        func close() { condition.withLock { armed = false; condition.broadcast() } }
+        func cancel() { condition.withLock { parkedAtHead += 1; condition.broadcast() } }
+        func makeIndependentReader() -> IOReader? { nil }
+        var discImageProbeEnabled: Bool { false }
+    }
+
+    @Test("A custom-source reload a stop() supersedes mid-reopen throws CancellationError and publishes no error")
+    func supersededCustomReloadIsACancellation() async throws {
+        let engine = try AetherEngine()
+        defer { engine.stop() }
+        let reader = HeadGatedReader(try Self.fixture())
+        _ = try await engine.load(source: .custom(reader, formatHint: "mp4"))
+        reader.arm()
+        let parkedBefore = reader.parkedCount
+
+        let reload = Task { @MainActor in try await engine.reloadAtCurrentPosition() }
+        try await waitFor { reader.parkedCount > parkedBefore }
+        engine.stop()
+
+        await #expect(throws: CancellationError.self) { try await reload.value }
+        #expect(engine.state == .idle)
+        #expect(engine.errorInfo == nil)
+    }
 }
diff --git a/docs/api.md b/docs/api.md
index 8037c4953..e9db544ac 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -454,7 +454,7 @@ try await player.reloadAtCurrentPosition()
 | `ProbeError` | `invalidLimits`, `inputLimit`, `packetLimit`, `packetSizeLimit`, `timedOut`, `invalidReaderResult`, `unsupportedURL`, `sourceBusy`; `errorDescription` describes the stop. Explicit caller cancellation throws `CancellationError` instead. |
 | `AetherEngine.externalSubtitleTrackIDBase` | `100_000`. Synthetic ids of external subtitle tracks start here. |
 
-Cancelling the Task that awaits `load()` ends the load at once: it throws `CancellationError` instead of running its connect, open, retry and probe budgets to the end (an unreachable live origin used to hold it for about 19 s). A blocked network read, `avformat_open_input` / `find_stream_info`, a size probe, an `HLSLiveIngestReader` retry and a custom reader's blocking `read` are all aborted, typically within tens of milliseconds; the one stretch it cannot cut short is the AE#532 Dolby Vision record audit, a detached read the load waits out before it throws. The load is left the way a newer `load()` leaves it: the generation moves on, a custom reader is closed, `state` becomes `.idle`, and the native host and AVPlayer (#15), an AE#158 handover item and the panel mode are kept for the next load. A host that is leaving playback rather than loading the next item calls `stop()` afterwards to release them. A cancellation only ends the load it belongs to: one that arrives after a newer `load()` or `stop()` took over, or after the load returned, changes nothing. A load that follows an engine rebuild (AE#629) ends that rebuild when cancelled. A `load()` called from a Task that is already cancelled throws before it touches the running session. A real failure that coincides with the cancellation is reported as `CancellationError` too, and `state` ends `.idle`, though a transient `.error` may have been published on the way. The same holds for a `reloadAtCurrentPosition()` of a URL source, which goes through `load()`. A load that returned before the cancellation is not undone; on the `nativeRemoteHLS` bypass `load()` returns at the mount, so a host leaving that startup calls `stop()`. Not cancelling changes nothing.
+Cancelling the Task that awaits `load()` ends the load at once: it throws `CancellationError` instead of running its connect, open, retry and probe budgets to the end (an unreachable live origin used to hold it for about 19 s). A blocked network read, `avformat_open_input` / `find_stream_info`, a size probe, an `HLSLiveIngestReader` retry and a custom reader's blocking `read` are all aborted, typically within tens of milliseconds; the one stretch it cannot cut short is the AE#532 Dolby Vision record audit, a detached read the load waits out before it throws. The load is left the way a newer `load()` leaves it: the generation moves on, a custom reader is closed, `state` becomes `.idle`, and the native host and AVPlayer (#15), an AE#158 handover item and the panel mode are kept for the next load. Until that next `load()` or a `stop()`, the engine reads `.idle` but still holds the native host and its AVPlayer with the item unloaded, Now Playing may stay registered, the audio session stays active, and with an AE#158 handover the previous item can keep playing in PiP; a host that LEAVES on cancel (a dismissed view, say) must call `stop()`. A cancellation only ends the load it belongs to: one that arrives after a newer `load()` or `stop()` took over, or after the load returned, changes nothing. A load that follows an engine rebuild (AE#629) ends that rebuild when cancelled. A `load()` called from a Task that is already cancelled throws before it touches the running session. A real failure that coincides with the cancellation is reported as `CancellationError` too, and `state` ends `.idle`, though a transient `.error` may have been published on the way. The same holds for a `reloadAtCurrentPosition()` of a URL source, which goes through `load()`. A load that returned before the cancellation is not undone; on the `nativeRemoteHLS` bypass `load()` returns at the mount, so a host leaving that startup calls `stop()`. Not cancelling changes nothing.
 
 ### Whole-probe limits and cancellation
 

From 8f3e73cd4045ff3f4ea09b40b7f1ef3b7f5068e5 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 1 Oct 2026 10:59:22 +0200
Subject: [PATCH 265/359] chore(release): prep 7.25.1 - cancelling the task
 that awaits load() ends the load at once

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                    | 8 ++++++++
 Examples/README.md                              | 2 +-
 README.md                                       | 6 +++---
 Sources/AetherEngine/AetherEngine+Version.swift | 2 +-
 4 files changed, 13 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6a5f2b3d5..dc6e7a2a8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,14 @@ the public-API contract.
 
 _Nothing yet._
 
+## [7.25.1] - 2026-10-01
+
+### Fixed
+
+- **Cancelling the task that awaits `load()` now ends the load at once (Sodalite#173, #683).** A `.custom(HLSLiveIngestReader)` load against an unreachable provider kept running for 19 s (`open_input 18987ms` while the ingest retried its playlist), and a host that cancelled it to tune the next channel had to wait it out. The load now throws `CancellationError` within tens of milliseconds for URL and `.custom` sources, and leaves the engine the way a newer load would: `.idle`, native host and AVPlayer kept for the next load, display criteria and audio-session membership untouched; a host that leaves on cancel calls `stop()`. Generation-guarded, so a cancel never touches a session a newer `load()` or `stop()` started. A cancelled AE#629 follower also ends the software-path rebuild, nested reroutes included.
+- **A superseded custom-source `reloadAtCurrentPosition()` throws `CancellationError`** like the URL branch already did, instead of returning normally and logging a false "rebuilt on the software path".
+- **A closed `AVIOReader` no longer waits out the 0.75 s probe-fallback delay** (about 0.03 s now), which also shortens `stop()` during a URL open.
+
 ## [7.25.0] - 2026-10-01
 
 ### Added
diff --git a/Examples/README.md b/Examples/README.md
index c8656177f..5b4f0006a 100644
--- a/Examples/README.md
+++ b/Examples/README.md
@@ -18,7 +18,7 @@ Three samples covering different audiences:
    ```
    https://github.com/superuser404notfound/AetherEngine
    ```
-   Dependency Rule: Up to Next Major Version, starting from `7.25.0`. Add the `AetherEngine` library product to your app target.
+   Dependency Rule: Up to Next Major Version, starting from `7.25.1`. Add the `AetherEngine` library product to your app target.
 
 3. **Drop the file in.** Replace the Xcode template's default `App.swift` (or whatever the generated `@main` file is called) with the contents of [`MinimalPlayerApp.swift`](MinimalPlayer/MinimalPlayerApp.swift). The file is self-contained: it defines both the `@main App` struct and the `ContentView`.
 
diff --git a/README.md b/README.md
index 764323133..8fac33640 100644
--- a/README.md
+++ b/README.md
@@ -384,7 +384,7 @@ Subtitle cues land in raw source PTS; render the overlay against `player.sourceT
 Install via Swift Package Manager:
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.25.0")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.25.1")
 ```
 
 Three samples ship in `Examples/`:
@@ -631,10 +631,10 @@ Browse all of this as a searchable site at **[aetherengine.superuser404.de](http
 AetherEngine uses [Semantic Versioning](https://semver.org). The public API surface, every `public` declaration in `Sources/AetherEngine/`, is the stability contract. **Major** removes / renames public symbols or breaks adopters; **Minor** adds public API or codec / format support; **Patch** fixes bugs with no public API change. `internal` types are not part of the contract.
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.25.0")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.25.1")
 ```
 
-Pin to `.upToNextMinor(from: "7.25.0")` for stricter teams that prefer to opt into minor bumps explicitly.
+Pin to `.upToNextMinor(from: "7.25.1")` for stricter teams that prefer to opt into minor bumps explicitly.
 
 ## Requirements
 
diff --git a/Sources/AetherEngine/AetherEngine+Version.swift b/Sources/AetherEngine/AetherEngine+Version.swift
index eadbe49f4..f7ecb0749 100644
--- a/Sources/AetherEngine/AetherEngine+Version.swift
+++ b/Sources/AetherEngine/AetherEngine+Version.swift
@@ -11,5 +11,5 @@ extension AetherEngine {
     ///
     /// Between releases, and in a consumer that pins an unreleased commit for a device test, this
     /// names the last PUBLISHED version the checkout descends from, not every patch in it.
-    public nonisolated static let version = "7.25.0"
+    public nonisolated static let version = "7.25.1"
 }

From bfecd2d2fb23e3e67dd49d9b368f122405c81352 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 1 Oct 2026 18:49:53 +0200
Subject: [PATCH 266/359] fix(live): an ingest seals its TARGETDURATION over
 the upstream segment it is delivered in (#684)

A live HLS ingest under fastZap re-cuts every upstream segment at its
GOPs, so max EXTINF read the GOP (2.000 s) and the upstream's own
segment length reached the seal only through the cadence floor, as
ceil(segment / 1.5). That division is argued for a measured gap, which
is a robust maximum. A segment duration is the period the source
delivers at when nothing is late, so a 6 s provider sealed 4: a client
patience of exactly one delivery and a 12 s holdback against deliveries
that arrive 6 to 9 s apart (the ingest reloads the upstream every half
segment). AVPlayer drew -12888, skipped its next playlist reload (4.0 s
on macOS, 5.03 s on tvOS) and stalled with the content already listed.

The seal is now at least the longest segment the upstream has served,
taken whole (LiveEdgePolicy.targetDurationForUpstreamSegment), and the
join covers the holdback that follows from it. 2 s upstreams keep TD 2
and a 6 s holdback (AE#447), the self-cut headroom of AE#670 is
untouched, and the advertised target duration is still only reported.

Measured against Scripts/hls-burst-origin.py (6 s segments, deliveries
3.0 to 9.3 s apart on the loopback), three 180 s runs per arm,
alternated: 5 / 4 / 6 times -12888 and 2 / 2 / 3 stalls before, none of
either after. Cost: one more upstream segment at the join wherever a
segment is longer than 4 s (3.81 s -> 4.98 s to first picture behind an
8 Mbit/s link, not measurable on loopback) and 6 s more standing
holdback on a 6 s provider.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../IO/HLSIngest/HLSPlaylistTracker.swift     |  18 +-
 .../Video/LiveCadencePolicy.swift             |  13 ++
 .../Video/VideoSegmentProvider.swift          |  54 ++++-
 .../HLSPlaylistTrackerTests.swift             |  10 +-
 ...IngestSealCoversUpstreamSegmentTests.swift | 205 ++++++++++++++++++
 docs/api.md                                   |   8 +-
 6 files changed, 284 insertions(+), 24 deletions(-)
 create mode 100644 Tests/AetherEngineTests/Issue684IngestSealCoversUpstreamSegmentTests.swift

diff --git a/Sources/AetherEngine/IO/HLSIngest/HLSPlaylistTracker.swift b/Sources/AetherEngine/IO/HLSIngest/HLSPlaylistTracker.swift
index c12015839..b7e50bede 100644
--- a/Sources/AetherEngine/IO/HLSIngest/HLSPlaylistTracker.swift
+++ b/Sources/AetherEngine/IO/HLSIngest/HLSPlaylistTracker.swift
@@ -36,15 +36,19 @@ struct HLSPlaylistTracker {
 
     /// AE#678: the join has to carry the cushion the loopback's first serve will ask for, or every zap
     /// ends at the bounded start's grace. The served TARGETDURATION is floored by the longest upstream
-    /// segment (`ceil(longest / 1.5)`, AE#447), so the gate wants `3 x` that, and `1.5 x TD` alone is
-    /// always a hair short of it: two 10 s segments are 20 s against a 21 s holdback. The last joined
-    /// segment's final GOP also stays open downstream until the next upstream segment arrives, so one
-    /// GOP of margin on top, bounded by the segment and by `openGOPMarginSeconds`. A whole segment of
-    /// margin would be the strict bound, and on a 10 s provider it is a fourth 10 s download the start
-    /// then waits for on a shared link (measured 3.7 s to first picture against 40 Mbit/s).
+    /// segment, the whole of it (AE#684; `ceil(longest / 1.5)` when this was written), so the gate
+    /// wants `3 x` that. The last joined segment's final GOP also stays open downstream until the next
+    /// upstream segment arrives, so one GOP of margin on top, bounded by the segment and by
+    /// `openGOPMarginSeconds`. A whole segment of margin would be the strict bound, and it is one
+    /// download more than the start needs.
+    ///
+    /// The depth is four upstream segments wherever a segment is longer than the margin. AE#678 measured
+    /// the fourth on a 10 s provider at 3.7 s to first picture against 2.8 s on a 40 Mbit/s link and
+    /// declined it as MARGIN. AE#684 takes it as HOLDBACK: the three it kept left the client a patience
+    /// of one upstream segment, which every ordinary delivery overran.
     static func loopbackCushionCoverageSeconds(segments: [HLSMediaSegment]) -> Double {
         guard let longest = segments.map(\.duration).max(), longest > 0 else { return 0 }
-        let targetDuration = LiveEdgePolicy.targetDurationForCadence(longest)
+        let targetDuration = LiveEdgePolicy.targetDurationForUpstreamSegment(longest)
         return LiveEdgePolicy.holdBackSeconds(targetDuration: targetDuration)
             + min(longest, openGOPMarginSeconds)
     }
diff --git a/Sources/AetherEngine/Video/LiveCadencePolicy.swift b/Sources/AetherEngine/Video/LiveCadencePolicy.swift
index affdba151..a11ba7b53 100644
--- a/Sources/AetherEngine/Video/LiveCadencePolicy.swift
+++ b/Sources/AetherEngine/Video/LiveCadencePolicy.swift
@@ -53,6 +53,8 @@ final class LiveCadencePolicy: @unchecked Sendable {
     /// AE#447: the running floor, the monotonic max of the CLOSED evidence. Not "the observed cadence":
     /// the open gap the gate holds open is deliberately not in here.
     private var measuredFloorSeconds: Double
+    /// AE#684: the served-segment term of that floor, kept apart. Monotonic like the floor.
+    private var longestUpstreamSegmentSeconds: Double = 0
 
     /// - Parameters:
     ///   - observe: reader's current `observedLiveCadenceSeconds`; nil until the first upstream arrival.
@@ -96,6 +98,7 @@ final class LiveCadencePolicy: @unchecked Sendable {
         if let evidence = observeSealEvidence?() {
             if let served = evidence.servedSegmentDurationSeconds, served > 0 {
                 measuredFloorSeconds = max(measuredFloorSeconds, served)
+                longestUpstreamSegmentSeconds = max(longestUpstreamSegmentSeconds, served)
             }
             if let closed = evidence.closedCadenceSeconds, closed > 0 {
                 measuredFloorSeconds = max(measuredFloorSeconds, closed)
@@ -119,6 +122,16 @@ final class LiveCadencePolicy: @unchecked Sendable {
         }
     }
 
+    /// AE#684: the longest segment the upstream has served, on its own. Inside the floor above it is
+    /// one more term of a max that is divided by the client's patience; a segment duration is the
+    /// period the upstream delivers at, not a worst case, so the seal takes it whole
+    /// (`LiveEdgePolicy.targetDurationForUpstreamSegment`). nil until the first arrival.
+    var upstreamSegmentDurationSeconds: Double? {
+        lock.lock(); defer { lock.unlock() }
+        advanceLocked()
+        return longestUpstreamSegmentSeconds > 0 ? longestUpstreamSegmentSeconds : nil
+    }
+
     var blockingReloadEnabled: Bool {
         lock.lock(); defer { lock.unlock() }
         advanceLocked()
diff --git a/Sources/AetherEngine/Video/VideoSegmentProvider.swift b/Sources/AetherEngine/Video/VideoSegmentProvider.swift
index e8be6f34e..cde7409b1 100644
--- a/Sources/AetherEngine/Video/VideoSegmentProvider.swift
+++ b/Sources/AetherEngine/Video/VideoSegmentProvider.swift
@@ -275,6 +275,26 @@ enum LiveEdgePolicy {
         wholeSecondsCovering(cadenceSeconds / unchangedPlaylistPatienceMultiplier)
     }
 
+    /// AE#684: the TARGETDURATION an ingested upstream's segment duration requires, which is the whole
+    /// of it and not `targetDurationForCadence`'s two thirds.
+    ///
+    /// The division by 1.5 is right for a measured gap because the meter hands over a robust maximum.
+    /// A segment duration is the other end of the distribution: the period the upstream delivers at
+    /// when nothing at all is late, since it cannot publish a segment before it has finished one. Every
+    /// real delivery is that period plus the upstream's jitter plus this reader's own reload interval
+    /// (half a segment, the RFC's), so a patience of exactly one period is under all of them. It only
+    /// looked covered while the served segments were the upstream's own, where `ceil(max EXTINF)` puts
+    /// the whole segment into the value anyway. `.fastZap` re-cuts each upstream segment at its GOPs,
+    /// that term then reads the GOP, and a 6 s upstream sealed at `ceil(6 / 1.5)` = 4: a 6.0 s patience
+    /// for deliveries measured in the field at 6.17 to 6.83 s, -12888 on the first one that also missed
+    /// a poll, a skipped reload after it and a stall with the content already listed.
+    ///
+    /// Re-cutting changes how finely the window is listed, not how often it changes, so the playlist
+    /// promises what a playlist of the upstream's segments would: at least their longest duration.
+    static func targetDurationForUpstreamSegment(_ segmentSeconds: Double) -> Int {
+        wholeSecondsCovering(segmentSeconds)
+    }
+
     /// A duration as the playlist actually serves it: `#EXTINF` is written with `%.3f`, so a millisecond
     /// is the finest distinction any client can ever read, and nothing below it may decide anything.
     ///
@@ -338,24 +358,28 @@ enum LiveEdgePolicy {
     }
 
     /// Served `#EXT-X-TARGETDURATION`, in whole seconds: `>= ceil(max EXTINF)` (HLS requirement), floored
-    /// by `ceil(1.5 x cut target)` (widens AVPlayer's unchanged-playlist patience, anti -12888) and by
-    /// what the observed cadence needs to stay inside that patience. `cutTargetSeconds` /
-    /// `cadenceFloorSeconds` are nil for VOD/EVENT. Every term is taken at the resolution the playlist
-    /// serves (`servedSeconds`), so the value covers the EXTINFs the client is actually handed and no
-    /// sub-millisecond noise can buy a whole second of holdback.
+    /// by `ceil(1.5 x cut target)` (widens AVPlayer's unchanged-playlist patience, anti -12888), by
+    /// what the observed cadence needs to stay inside that patience, and by the longest segment an
+    /// ingested upstream delivers in (`targetDurationForUpstreamSegment`, AE#684). `cutTargetSeconds` /
+    /// `cadenceFloorSeconds` are nil for VOD/EVENT, `upstreamSegmentSeconds` for everything but an
+    /// ingest. Every term is taken at the resolution the playlist serves (`servedSeconds`), so the
+    /// value covers the EXTINFs the client is actually handed and no sub-millisecond noise can buy a
+    /// whole second of holdback.
     ///
     /// AE#670: `segmentsAreCutHere` adds `ceil(1.5 x max EXTINF)` where that headroom has no other source
     /// (`gopHeadroomApplies`).
     static func targetDurationSeconds(maxSegmentDuration: Double,
                                       cutTargetSeconds: Double?,
                                       cadenceFloorSeconds: Double?,
-                                      segmentsAreCutHere: Bool = false) -> Int {
+                                      segmentsAreCutHere: Bool = false,
+                                      upstreamSegmentSeconds: Double? = nil) -> Int {
         var td = wholeSecondsCovering(max(1.0, maxSegmentDuration))
         if let cut = cutTargetSeconds { td = max(td, wholeSecondsCovering(cut * 1.5)) }
         if gopHeadroomApplies(cutTargetSeconds: cutTargetSeconds, segmentsAreCutHere: segmentsAreCutHere) {
             td = max(td, wholeSecondsCovering(maxSegmentDuration * 1.5))
         }
         if let floor = cadenceFloorSeconds { td = max(td, targetDurationForCadence(floor)) }
+        if let upstream = upstreamSegmentSeconds { td = max(td, targetDurationForUpstreamSegment(upstream)) }
         return td
     }
 
@@ -365,9 +389,10 @@ enum LiveEdgePolicy {
     /// every segment it cuts is one whole source GOP, and the value is sealed from the first few of them.
     /// A broadcast's GOPs are not regular (reported: 1.0 to 2.4 s, sealed on three 1.000 s ones), and a
     /// later longer one then breaks `EXTINF <= TD` and holds the playlist unchanged past AVPlayer's
-    /// patience. `.standard` has that headroom already in its `1.5 x cut target` floor, and ingested
-    /// segments are bounded by the upstream's own target duration (AE#447 keeps TD 2 on those), so only
-    /// the engine's own sub-second cut needs it from the segments.
+    /// patience. `.standard` has that headroom already in its `1.5 x cut target` floor, and an ingest
+    /// is bounded by the upstream segment its GOPs were cut from (`targetDurationForUpstreamSegment`;
+    /// AE#447 keeps TD 2 on 2.000 s ones), so only the engine's own sub-second cut needs it from the
+    /// segments.
     static func gopHeadroomApplies(cutTargetSeconds: Double?, segmentsAreCutHere: Bool) -> Bool {
         guard segmentsAreCutHere, let cut = cutTargetSeconds else { return false }
         return cut < 1.0
@@ -546,6 +571,8 @@ struct LiveTargetDurationDerivation {
     let cutTargetFloor: Double?
     var gopHeadroomApplies = false
     let cadenceFloor: CadenceFloorTerm
+    /// AE#684: the longest segment an ingested upstream has served, nil off the ingest path.
+    var upstreamSegment: Double? = nil
     let selfReported: Double?
 
     /// One line, in the order the terms are maxed. Reads as an argument for the number it reports.
@@ -559,6 +586,10 @@ struct LiveTargetDurationDerivation {
                 + "(each segment is one whole GOP)")
         }
         terms.append(cadenceFloor.account)
+        if let upstreamSegment {
+            terms.append("upstream segment \(LiveEdgePolicy.seconds(upstreamSegment))s "
+                + "(one delivery, however finely it is cut here)")
+        }
         let claim = selfReported.map {
             "; upstream advertises \(LiveEdgePolicy.seconds($0))s (reported, not used)"
         } ?? ""
@@ -2311,18 +2342,21 @@ final class VideoSegmentProvider: HLSSegmentProvider, @unchecked Sendable {
             policy.targetDurationFloorSeconds.map { CadenceFloorTerm.measured($0) } ?? .pending
         } ?? .unmeasurable
         let cutHere = liveCadencePolicy == nil
+        let upstreamSegment = liveCadencePolicy?.upstreamSegmentDurationSeconds
         return LiveTargetDurationDerivation(
             value: LiveEdgePolicy.targetDurationSeconds(
                 maxSegmentDuration: maxSegmentDuration,
                 cutTargetSeconds: cutTarget,
                 cadenceFloorSeconds: floor.seconds,
-                segmentsAreCutHere: cutHere
+                segmentsAreCutHere: cutHere,
+                upstreamSegmentSeconds: upstreamSegment
             ),
             maxSegmentDuration: maxSegmentDuration,
             cutTargetFloor: cutTarget,
             gopHeadroomApplies: LiveEdgePolicy.gopHeadroomApplies(cutTargetSeconds: cutTarget,
                                                                   segmentsAreCutHere: cutHere),
             cadenceFloor: floor,
+            upstreamSegment: upstreamSegment,
             selfReported: liveCadencePolicy?.selfReportedTargetDurationSeconds
         )
     }
diff --git a/Tests/AetherEngineTests/HLSPlaylistTrackerTests.swift b/Tests/AetherEngineTests/HLSPlaylistTrackerTests.swift
index 836589b71..7bb667a5c 100644
--- a/Tests/AetherEngineTests/HLSPlaylistTrackerTests.swift
+++ b/Tests/AetherEngineTests/HLSPlaylistTrackerTests.swift
@@ -155,13 +155,13 @@ final class HLSPlaylistTrackerTests: XCTestCase {
     }
 
     func testDefaultJoinCoversTheLoopbackCushionForLongSegments() {
-        // AE#678: a 6s provider seals TD 4 downstream, so the first serve wants 12s, and two joined
-        // segments finalize only 12s minus the open GOP. The cushion term takes a third.
+        // AE#678, at AE#684's seal: a 6s provider seals TD 6 downstream, so the first serve wants 18s,
+        // and three joined segments finalize only 18s minus the open GOP. The cushion term takes a fourth.
         var tracker = HLSPlaylistTracker()
         let new = tracker.newSegments(
             in: playlist(sequence: 3, uris: ["a", "b", "c", "d", "e", "f"], duration: 6)
         )
-        XCTAssertEqual(new.map(\.uri), ["d", "e", "f"])
+        XCTAssertEqual(new.map(\.uri), ["c", "d", "e", "f"])
     }
 
     func testLoopbackCushionCoverageIsTheSealedHoldbackPlusAGOP() {
@@ -170,8 +170,8 @@ final class HLSPlaylistTrackerTests: XCTestCase {
                 HLSMediaSegment(uri: "s\($0.offset)", duration: $0.element, discontinuityBefore: false)
             })
         }
-        XCTAssertEqual(coverage([10, 10, 10]), 25)       // TD 7, 21s holdback, 4s margin
-        XCTAssertEqual(coverage([12, 13.5, 12]), 31)     // TD 9 from the longest, 27s + 4s
+        XCTAssertEqual(coverage([10, 10, 10]), 34)       // TD 10 (AE#684), 30s holdback, 4s margin
+        XCTAssertEqual(coverage([12, 13.5, 12]), 46)     // TD 14 from the longest, 42s + 4s
         XCTAssertEqual(coverage([2, 2, 2]), 8)           // TD 2, 6s + a 2s GOP bounded by the segment
         XCTAssertEqual(coverage([1, 1, 1]), 4)           // below the 8s floor, which then decides
         XCTAssertEqual(coverage([]), 0)
diff --git a/Tests/AetherEngineTests/Issue684IngestSealCoversUpstreamSegmentTests.swift b/Tests/AetherEngineTests/Issue684IngestSealCoversUpstreamSegmentTests.swift
new file mode 100644
index 000000000..e18d76862
--- /dev/null
+++ b/Tests/AetherEngineTests/Issue684IngestSealCoversUpstreamSegmentTests.swift
@@ -0,0 +1,205 @@
+// Tests/AetherEngineTests/Issue684IngestSealCoversUpstreamSegmentTests.swift
+// AE#684: a live HLS ingest under `.fastZap` whose upstream cuts 6 s segments sealed the served
+// TARGETDURATION at 4 (`max EXTINF 2.000s, measured floor 6.000s needs 4s of patience`), because the
+// engine re-cuts each upstream segment at its 2 s GOPs and the upstream's own segment duration entered
+// only through the cadence floor, as `ceil(6 / 1.5)`. That division belongs to a MEASURED gap, a robust
+// maximum that is a worst case already. An upstream segment duration is the opposite: the period the
+// source delivers at when nothing is late, so `1.5 x TD` came out at exactly one period, 6.0 s, and every
+// ordinary delivery (6.17 to 6.83 s in the field capture, 63 of 110 gaps above 6.0 s) was past the
+// client's patience. The session drew -12888, AVPlayer then skipped a playlist reload (5.03 s between two
+// polls instead of 2 s), and the 12 s holdback ran out 2.4 s after the content it was waiting for had
+// been listed.
+//
+// The upstream delivers in whole segments however finely they are re-cut here, so the served playlist
+// changes once per upstream segment and has to promise what a playlist of those segments promises:
+// TARGETDURATION >= the longest upstream segment.
+import XCTest
+@testable import AetherEngine
+
+private final class ScriptedIngest: @unchecked Sendable {
+    var now: Double = 0
+    var cadence: Double?
+    var closedCadence: Double?
+    var segmentDuration: Double?
+}
+
+final class Issue684IngestSealCoversUpstreamSegmentTests: XCTestCase {
+
+    private let fastZapCut = HLSVideoEngine.liveCutTargetSeconds(for: .fastZap)
+    private let standardCut = HLSVideoEngine.liveCutTargetSeconds(for: .standard)
+
+    private func makePolicy(_ s: ScriptedIngest, advertised: Double?) -> LiveCadencePolicy {
+        LiveCadencePolicy(
+            observe: { s.cadence },
+            cutTargetSeconds: 0.5,
+            observeSealEvidence: {
+                LiveCadenceEvidence(closedCadenceSeconds: s.closedCadence,
+                                    servedSegmentDurationSeconds: s.segmentDuration)
+            },
+            selfReportedTargetDurationSeconds: advertised,
+            clock: { s.now }
+        )
+    }
+
+    // MARK: - The reported seal
+
+    /// 6 s upstream segments, re-cut at 2.000 s GOPs, sealed inside the join burst.
+    func testSixSecondUpstreamRecutAtTwoSecondGOPsSealsAtSix() {
+        let td = LiveEdgePolicy.targetDurationSeconds(maxSegmentDuration: 2.0,
+                                                      cutTargetSeconds: fastZapCut,
+                                                      cadenceFloorSeconds: 6.0,
+                                                      upstreamSegmentSeconds: 6.0)
+        XCTAssertEqual(td, 6)
+        XCTAssertEqual(LiveEdgePolicy.holdBackSeconds(targetDuration: td), 18.0, accuracy: 1e-9)
+    }
+
+    /// The deliveries the field capture shows for one upstream segment, and the later candidate the
+    /// session itself logged (`measured floor 8.492s needs 6s of patience`).
+    func testPatienceCoversTheFieldDeliveries() {
+        let td = LiveEdgePolicy.targetDurationSeconds(maxSegmentDuration: 2.0,
+                                                      cutTargetSeconds: fastZapCut,
+                                                      cadenceFloorSeconds: 6.0,
+                                                      upstreamSegmentSeconds: 6.0)
+        let patience = Double(td) * LiveEdgePolicy.unchangedPlaylistPatienceMultiplier
+        for gap in [6.17, 6.54, 6.83, 7.36, 8.32, 8.492] {
+            XCTAssertGreaterThan(patience, gap)
+        }
+        XCTAssertGreaterThanOrEqual(td, LiveEdgePolicy.targetDurationForCadence(8.492),
+                                    "the seal must not be under what the session measured afterwards")
+    }
+
+    /// A period is not a worst case: the patience has to clear it by the same half the RFC gives a
+    /// playlist of those segments, for every segment length and not only where `ceil` happens to help.
+    func testPatienceIsOneAndAHalfUpstreamSegmentsAtEveryLength() {
+        for upstream in [1.0, 1.92, 2.0, 3.0, 4.0, 4.5, 6.0, 9.0, 10.0] {
+            let td = LiveEdgePolicy.targetDurationSeconds(maxSegmentDuration: min(upstream, 2.0),
+                                                          cutTargetSeconds: fastZapCut,
+                                                          cadenceFloorSeconds: upstream,
+                                                          upstreamSegmentSeconds: upstream)
+            XCTAssertGreaterThanOrEqual(Double(td) * LiveEdgePolicy.unchangedPlaylistPatienceMultiplier,
+                                        upstream * 1.5, "upstream \(upstream)s sealed at \(td)s")
+        }
+    }
+
+    // MARK: - What stays
+
+    /// AE#447: 2.000 s and 1.920 s ingests keep TARGETDURATION 2 and a 6 s holdback.
+    func testTwoSecondIngestKeepsTargetDurationTwo() {
+        for upstream in [2.0, 1.92] {
+            let td = LiveEdgePolicy.targetDurationSeconds(maxSegmentDuration: upstream,
+                                                          cutTargetSeconds: fastZapCut,
+                                                          cadenceFloorSeconds: 2.142,
+                                                          upstreamSegmentSeconds: upstream)
+            XCTAssertEqual(td, 2, "upstream \(upstream)s")
+        }
+    }
+
+    /// A measured gap is a robust maximum and still enters as the patience it needs.
+    func testClosedCadenceStillEntersAsThePatienceItNeeds() {
+        XCTAssertEqual(LiveEdgePolicy.targetDurationSeconds(maxSegmentDuration: 2.0,
+                                                            cutTargetSeconds: fastZapCut,
+                                                            cadenceFloorSeconds: 20.0,
+                                                            upstreamSegmentSeconds: 2.0), 14)
+    }
+
+    /// No upstream playlist, no term: AE#670's self-cut seal and the raw-TS seal are what they were.
+    func testSelfCutSessionsAreUnchanged() {
+        XCTAssertEqual(LiveEdgePolicy.targetDurationSeconds(maxSegmentDuration: 1.0,
+                                                            cutTargetSeconds: fastZapCut,
+                                                            cadenceFloorSeconds: nil,
+                                                            segmentsAreCutHere: true,
+                                                            upstreamSegmentSeconds: nil), 2)
+        XCTAssertEqual(LiveEdgePolicy.targetDurationSeconds(maxSegmentDuration: 5.76,
+                                                            cutTargetSeconds: standardCut,
+                                                            cadenceFloorSeconds: nil,
+                                                            segmentsAreCutHere: true,
+                                                            upstreamSegmentSeconds: nil), 6)
+    }
+
+    /// `.standard` on the same 6 s upstream already sat at 6 through its `1.5 x cut target` floor.
+    func testStandardProfileOnSixSecondUpstreamIsUnchanged() {
+        XCTAssertEqual(LiveEdgePolicy.targetDurationSeconds(maxSegmentDuration: 6.0,
+                                                            cutTargetSeconds: standardCut,
+                                                            cadenceFloorSeconds: 6.0,
+                                                            upstreamSegmentSeconds: 6.0), 6)
+    }
+
+    /// Taken at the served resolution like every other term (AE#447 round 2).
+    func testUpstreamSegmentIsTakenAtTheServedResolution() {
+        XCTAssertEqual(LiveEdgePolicy.targetDurationForUpstreamSegment(6.0000000000000009), 6)
+        XCTAssertEqual(LiveEdgePolicy.targetDurationForUpstreamSegment(6.006), 7)
+        XCTAssertEqual(LiveEdgePolicy.targetDurationForUpstreamSegment(.infinity),
+                       LiveEdgePolicy.maxCoveredWholeSeconds)
+        XCTAssertEqual(LiveEdgePolicy.targetDurationForUpstreamSegment(.nan), 0)
+    }
+
+    // MARK: - Where the term comes from
+
+    /// Measured, not advertised: the longest segment the upstream actually served.
+    func testPolicyReportsTheLongestServedUpstreamSegment() {
+        let s = ScriptedIngest()
+        let policy = makePolicy(s, advertised: 9)
+        XCTAssertNil(policy.upstreamSegmentDurationSeconds, "an advert alone is not a served segment")
+        s.now = 1; s.cadence = 0.2; s.segmentDuration = 4.0
+        XCTAssertEqual(try XCTUnwrap(policy.upstreamSegmentDurationSeconds), 4.0, accuracy: 1e-9)
+        s.now = 2; s.segmentDuration = 6.0
+        XCTAssertEqual(try XCTUnwrap(policy.upstreamSegmentDurationSeconds), 6.0, accuracy: 1e-9)
+        s.now = 3; s.segmentDuration = nil
+        XCTAssertEqual(try XCTUnwrap(policy.upstreamSegmentDurationSeconds), 6.0, accuracy: 1e-9,
+                       "monotonic, like the floor it sits beside")
+    }
+
+    // MARK: - The join carries the cushion the seal asks for
+
+    func testJoinCoversTheDeeperHoldback() {
+        func coverage(_ durations: [Double]) -> Double {
+            HLSPlaylistTracker.loopbackCushionCoverageSeconds(segments: durations.map {
+                HLSMediaSegment(uri: "s", duration: $0, discontinuityBefore: false)
+            })
+        }
+        XCTAssertEqual(coverage([6, 6, 6]), 22)     // TD 6, 18 s holdback, 4 s of open GOP
+        XCTAssertEqual(coverage([6, 4, 6, 4]), 22)  // the field shape, sealed from the longest
+        XCTAssertEqual(coverage([2, 2, 2]), 8)      // AE#447's shape, unchanged
+    }
+
+    // MARK: - The seal says why
+
+    func testSealAccountNamesTheUpstreamSegmentTerm() {
+        let derivation = LiveTargetDurationDerivation(
+            value: 6, maxSegmentDuration: 2.0, cutTargetFloor: fastZapCut,
+            cadenceFloor: .measured(6.0), upstreamSegment: 6.0, selfReported: 6.0)
+        let account = derivation.account
+        XCTAssertTrue(account.contains("sealed at 6s"), account)
+        XCTAssertTrue(account.contains("holdback 18.000s"), account)
+        XCTAssertTrue(account.contains("upstream segment 6.000s"), account)
+        XCTAssertTrue(account.contains("upstream advertises 6.000s (reported, not used)"), account)
+    }
+
+    /// AE#447 round 2's property, with the new term in the sum: the line adds up to its own number.
+    func testSealAccountStillRecomputesTheValueItReports() throws {
+        func number(after label: String, in text: String) -> Double? {
+            guard let r = text.range(of: label + "[0-9]+\\.?[0-9]*", options: .regularExpression) else {
+                return nil
+            }
+            return Double(text[r].dropFirst(label.count))
+        }
+        for upstream in [2.0, 4.0, 6.0, 6.006, 10.0] {
+            for floor in [upstream, 8.492, 20.0] {
+                let value = LiveEdgePolicy.targetDurationSeconds(
+                    maxSegmentDuration: 2.0, cutTargetSeconds: fastZapCut,
+                    cadenceFloorSeconds: floor, upstreamSegmentSeconds: upstream)
+                let account = LiveTargetDurationDerivation(
+                    value: value, maxSegmentDuration: 2.0, cutTargetFloor: fastZapCut,
+                    cadenceFloor: .measured(floor), upstreamSegment: upstream, selfReported: 6.0).account
+                var recomputed = Int(ceil(try XCTUnwrap(number(after: "max EXTINF ", in: account))))
+                recomputed = max(recomputed,
+                                 Int(ceil(try XCTUnwrap(number(after: "1.5 x cut target ", in: account)))))
+                recomputed = max(recomputed,
+                                 Int(ceil(try XCTUnwrap(number(after: "upstream segment ", in: account)))))
+                recomputed = max(recomputed, Int(try XCTUnwrap(number(after: "needs ", in: account))))
+                XCTAssertEqual(Int(try XCTUnwrap(number(after: "sealed at ", in: account))), recomputed,
+                               account)
+            }
+        }
+    }
+}
diff --git a/docs/api.md b/docs/api.md
index e9db544ac..2fffbdb3c 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -707,8 +707,12 @@ cadence and the holdback follows it down, so the win belongs to the source GOP r
 its runway under either profile. Where the engine cuts the segments itself, each one is a whole GOP and
 the value is sealed from the first few, so it carries `ceil(1.5 x max EXTINF)` of headroom: a broadcast
 whose GOPs run 1.0 to 2.4 s sealed TARGETDURATION 1 on its first three and then broke `EXTINF <= TD`
-on every longer one (AE#670). 1 s GOPs therefore serve TARGETDURATION 2 and a 6 s holdback. Ingested
-segments are bounded by the upstream's own target duration and keep `ceil(max EXTINF)`.
+on every longer one (AE#670). 1 s GOPs therefore serve TARGETDURATION 2 and a 6 s holdback. An
+ingested HLS upstream is re-cut at its GOPs too, but it still arrives one upstream segment at a
+time, so its floor is the longest segment the upstream has served, whole (AE#684): 2 and a 6 s
+holdback on 2 s segments as before, 6 and 18 s on 6 s ones, where `ceil(6 / 1.5)` used to seal 4 and
+left the client a patience of exactly one delivery. The upstream's advertised target duration is
+still not read.
 
 **An HLS source with a window of its own now fills that cushion at the join rather than in wall clock**
 (6.77.0). The ingest used to enter a live playlist three segments behind the edge, and three joined

From 134cd476a6d918b683dddf50ded1e458a397b1dd Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 1 Oct 2026 18:50:02 +0200
Subject: [PATCH 267/359] fix(native): the AE#440 start is not forced on an
 item that cannot play yet (#684)

The live-join guard measures its cushion from the item's currentTime(),
and before readyToPlay that is where the loader began fetching, not
where playback will begin. On a rejoin placed by EXT-X-START AVPlayer
fetches from about 6 s below the target first, so the reading is the
lookback itself. Captured on a device: an item placed at 53.908 s read
"buffer ahead 4.00s" from a playhead of 48.00 s, every second of it
behind the start, and playImmediately was called 36 ms before the item
became ready. It was the one item of five in that capture to be forced,
and the one its viewer reported out of sync.

The decision now requires readyToPlay, says so when the depth alone
would have fired, and is asked again at readiness from the playhead the
item really starts on. Whether the forced start is what moved sound
against picture is not proven: it cannot be observed on macOS, and the
loopback never holds long enough to reach the cut.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../Native/NativeAVPlayerHost.swift           | 46 +++++++++++-
 .../Issue684LiveJoinNotReadyTests.swift       | 70 +++++++++++++++++++
 docs/api.md                                   | 13 +++-
 3 files changed, 125 insertions(+), 4 deletions(-)
 create mode 100644 Tests/AetherEngineTests/Issue684LiveJoinNotReadyTests.swift

diff --git a/Sources/AetherEngine/Native/NativeAVPlayerHost.swift b/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
index 84fcc481e..5f44b171d 100644
--- a/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
+++ b/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
@@ -91,6 +91,8 @@ final class NativeAVPlayerHost {
     private var liveJoinThinBufferLogged: Bool = false
     /// AE#440 round 5: keeps the "the hold was over before the reading came back" line to one per load.
     private var liveJoinNoDecisionLogged: Bool = false
+    /// AE#684: one line per load for a hold the depth would have cut and the item's status refused.
+    private var liveJoinNotReadyLogged: Bool = false
     /// AE#440 round 3: one witness per load for a hold that was refused, so the bound is read while the
     /// hold stands and not only at its edges. Observes, never acts (see `startLiveJoinHoldWitness`).
     private var liveJoinHoldWitnessStarted: Bool = false
@@ -473,6 +475,7 @@ final class NativeAVPlayerHost {
         self.liveJoinImmediateStartProbeInFlight = false
         self.liveJoinThinBufferLogged = false
         self.liveJoinNoDecisionLogged = false
+        self.liveJoinNotReadyLogged = false
         // AE#440 round 4: both of these are per LOAD, and the host is reused across loads on the
         // keepNativeHost path. Left standing, the second live join of a reused host would arm no witness
         // at all and read the previous join's spend reason.
@@ -648,6 +651,11 @@ final class NativeAVPlayerHost {
                         self.hasEverPlayed = true
                         self.inPlaceSwapMountPending = false
                         self.startLiveJoinImmediatelyIfHolding(waitingReason: "-")
+                    } else if self.timeControlStatus == .waitingToPlayAtSpecifiedRate {
+                        // AE#684: a hold refused for an item that could not play yet is asked again
+                        // now that it can, on the playhead the item actually starts from.
+                        self.startLiveJoinImmediatelyIfHolding(
+                            waitingReason: self.avPlayer.reasonForWaitingToPlay?.rawValue ?? "-")
                     }
                     // #168: publish the item's real dynamic range for the probe-free remote-HLS badge.
                     await self.publishDetectedVideoFormat(from: item)
@@ -1266,16 +1274,26 @@ final class NativeAVPlayerHost {
     ///   behind the same `false` a genuinely starved join holds a fraction of a second, and starting
     ///   there trades a still picture for an immediate stall. The depth is the axis that separates the
     ///   two mechanisms, so it is the one the guard reads.
+    /// - `itemIsReadyToPlay` (AE#684): the depth is measured from `currentTime()`, and until the item
+    ///   is ready that is where the loader started fetching, not where playback will begin. Under an
+    ///   `EXT-X-START` placement AVPlayer fetches from about 6 s below the target first, so the reading
+    ///   is the lookback itself: captured on a rejoin placed at 53.908 s as `buffer ahead 4.00s` from a
+    ///   playhead of 48.00 s, every second of it behind the start point, on an item whose status had
+    ///   not left `unknown`, 36 ms before it did. That is the starved start the depth guard exists to
+    ///   refuse, read as a four-second cushion, and it was the one item of five in that capture to
+    ///   be forced, and the one its viewer reported out of sync. The hold is asked again at readiness.
     nonisolated static func shouldStartLiveJoinImmediately(
         armed: Bool,
         alreadySpent: Bool,
         hostWantsToPlay: Bool,
         isWaitingToMinimizeStalls: Bool,
         playbackBufferEmpty: Bool,
-        bufferedAheadSeconds: Double
+        bufferedAheadSeconds: Double,
+        itemIsReadyToPlay: Bool = true
     ) -> Bool {
         guard armed, !alreadySpent, hostWantsToPlay else { return false }
         guard isWaitingToMinimizeStalls else { return false }
+        guard itemIsReadyToPlay else { return false }
         guard !playbackBufferEmpty else { return false }
         // NaN fails every comparison silently, and an unresolved item's currentTime() is NaN, so an
         // absent reading has to be rejected rather than fall through the bound below.
@@ -1354,8 +1372,14 @@ final class NativeAVPlayerHost {
                 hostWantsToPlay: self.playIntent,
                 isWaitingToMinimizeStalls: true,
                 playbackBufferEmpty: reading.bufferEmpty,
-                bufferedAheadSeconds: reading.aheadSeconds
+                bufferedAheadSeconds: reading.aheadSeconds,
+                itemIsReadyToPlay: reading.itemStatus == .readyToPlay
             ) else {
+                // AE#684: a refusal the depth alone would have granted says which fact refused it.
+                if let line = Self.liveJoinNotReadyRefusal(reading: reading), !self.liveJoinNotReadyLogged {
+                    self.liveJoinNotReadyLogged = true
+                    EngineLog.emit("[NativeAVPlayerHost] #\(self.sessionID) " + line, category: .engine)
+                }
                 // The cushion, not the decision, is what a later report needs: it separates a join
                 // waiting on AVPlayer's rate estimate from one genuinely starved at the edge.
                 if !self.liveJoinThinBufferLogged {
@@ -1461,7 +1485,8 @@ final class NativeAVPlayerHost {
                 guard Self.shouldStartLiveJoinImmediately(
                     armed: true, alreadySpent: false, hostWantsToPlay: true,
                     isWaitingToMinimizeStalls: true,
-                    playbackBufferEmpty: reading.bufferEmpty, bufferedAheadSeconds: reading.aheadSeconds
+                    playbackBufferEmpty: reading.bufferEmpty, bufferedAheadSeconds: reading.aheadSeconds,
+                    itemIsReadyToPlay: reading.itemStatus == .readyToPlay
                 ) else { continue }
                 account(.crossed)
                 return
@@ -1664,6 +1689,21 @@ final class NativeAVPlayerHost {
         }
     }
 
+    /// AE#684: the refusal line for a hold that had the depth and not the item. nil for every other
+    /// refusal, which the thin-buffer line already accounts for.
+    nonisolated static func liveJoinNotReadyRefusal(reading: LiveJoinBufferReading) -> String? {
+        guard reading.itemStatus != .readyToPlay, !reading.bufferEmpty,
+              reading.aheadSeconds.isFinite, reading.aheadSeconds >= minimumLiveJoinBufferAhead
+        else { return nil }
+        let head = reading.playheadSeconds.isFinite
+            ? String(format: "%.2f", reading.playheadSeconds) + "s"
+            : "an unreadable position"
+        return "AE#440 live join: leaving the stall-avoidance wait alone on an item that cannot play "
+            + "yet (buffer ahead " + String(format: "%.2f", reading.aheadSeconds) + "s of playhead "
+            + head + ", which until readiness is where the fetch began and not where playback will); "
+            + "asked again at readiness"
+    }
+
     /// The placement clause the two accounts below carry when the cushion reads zero. nil when a range
     /// contains the playhead: there the depth is the whole story and this would only add noise.
     nonisolated static func liveJoinPlacementClause(reading: LiveJoinBufferReading) -> String? {
diff --git a/Tests/AetherEngineTests/Issue684LiveJoinNotReadyTests.swift b/Tests/AetherEngineTests/Issue684LiveJoinNotReadyTests.swift
new file mode 100644
index 000000000..4edfba43a
--- /dev/null
+++ b/Tests/AetherEngineTests/Issue684LiveJoinNotReadyTests.swift
@@ -0,0 +1,70 @@
+// Tests/AetherEngineTests/Issue684LiveJoinNotReadyTests.swift
+// AE#684: the AE#440 forced start was taken on a rejoin item that could not play yet. The capture:
+//
+//     14:51:15.650  #454 placing the fresh item at 31871.11s in its own playlist: segment 26 + 1.91s
+//     14:51:15.716  #7 AE#440 live join: leaving the stall-avoidance wait alone (buffer ahead 0.00s,
+//                   empty=true ...) (playhead 48.00s), and the item's own status has not left unknown
+//     14:51:15.731  #7 AE#440 live join: cutting the stall-avoidance wait short at rate 1.0
+//                   (buffer ahead 4.00s)
+//     14:51:15.767  #7 item.status=readyToPlay
+//     14:51:15.778  #454 the playlist already placed this item at its own 53.91s
+//
+// The item was placed at 53.908 s by `EXT-X-START`, AVPlayer fetched from 48.00 s first (its own
+// lookback), and the guard measured its cushion from `currentTime()`, which before readiness is that
+// 48.00 s: two fetched segments, 4.00 s, all of it behind the point playback was about to start at.
+// It is the only one of the five item starts in that capture the engine forced, and the one the
+// viewer reported out of sync. AE#440 round 7 had named the shape before any capture showed it.
+import AVFoundation
+import Testing
+@testable import AetherEngine
+
+@Suite("AE#684: the AE#440 start is not forced on an item that cannot play yet")
+struct Issue684LiveJoinNotReadyTests {
+
+    @Test("the captured reading is refused: 4.00 s ahead of a playhead the item has not taken yet")
+    func refusesTheCapturedReading() {
+        #expect(!NativeAVPlayerHost.shouldStartLiveJoinImmediately(
+            armed: true, alreadySpent: false, hostWantsToPlay: true,
+            isWaitingToMinimizeStalls: true, playbackBufferEmpty: false, bufferedAheadSeconds: 4.0,
+            itemIsReadyToPlay: false))
+    }
+
+    @Test("the same hold on a ready item is still the case AE#440 exists for")
+    func firesOnceTheItemCanPlay() {
+        #expect(NativeAVPlayerHost.shouldStartLiveJoinImmediately(
+            armed: true, alreadySpent: false, hostWantsToPlay: true,
+            isWaitingToMinimizeStalls: true, playbackBufferEmpty: false, bufferedAheadSeconds: 4.0,
+            itemIsReadyToPlay: true))
+    }
+
+    @Test("a caller that states no readiness keeps the decision it had")
+    func defaultIsUnchanged() {
+        #expect(NativeAVPlayerHost.shouldStartLiveJoinImmediately(
+            armed: true, alreadySpent: false, hostWantsToPlay: true,
+            isWaitingToMinimizeStalls: true, playbackBufferEmpty: false, bufferedAheadSeconds: 4.0))
+    }
+
+    @Test("the refusal names the playhead the cushion was read from")
+    func refusalNamesThePlayhead() throws {
+        let reading = NativeAVPlayerHost.LiveJoinBufferReading(
+            bufferEmpty: false, aheadSeconds: 4.0, playheadSeconds: 48.0,
+            loadedRangeCount: 1, nearestRangeOffsetSeconds: nil, itemStatus: .unknown)
+        let line = try #require(NativeAVPlayerHost.liveJoinNotReadyRefusal(reading: reading))
+        #expect(line.contains("buffer ahead 4.00s of playhead 48.00s"))
+        #expect(line.contains("cannot play yet"))
+        #expect(line.contains("asked again at readiness"))
+    }
+
+    /// The thin-buffer line already accounts for these; a second line would say the same refusal twice.
+    @Test("no extra line for a refusal the depth explains, or for a ready item")
+    func refusalIsOnlyForTheDepthThatWouldHaveFired() {
+        let thin = NativeAVPlayerHost.LiveJoinBufferReading(
+            bufferEmpty: true, aheadSeconds: 0, playheadSeconds: 48.0,
+            loadedRangeCount: 0, nearestRangeOffsetSeconds: nil, itemStatus: .unknown)
+        #expect(NativeAVPlayerHost.liveJoinNotReadyRefusal(reading: thin) == nil)
+        let ready = NativeAVPlayerHost.LiveJoinBufferReading(
+            bufferEmpty: false, aheadSeconds: 4.0, playheadSeconds: 53.908,
+            loadedRangeCount: 1, nearestRangeOffsetSeconds: nil, itemStatus: .readyToPlay)
+        #expect(NativeAVPlayerHost.liveJoinNotReadyRefusal(reading: ready) == nil)
+    }
+}
diff --git a/docs/api.md b/docs/api.md
index 2fffbdb3c..145fded7b 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -778,6 +778,17 @@ The depth is the contiguous span ahead of the playhead, so an island past a gap
 floor is not met the engine says so once per load (`leaving the stall-avoidance wait alone (buffer ahead
 ...s, ...)`), which is what separates the two mechanisms in a report after the fact.
 
+**And the item has to be able to play (AE#684).** The depth is measured from the item's own
+`currentTime()`, and before `readyToPlay` that is where the loader began fetching, not where playback
+will begin. Under an `EXT-X-START` placement, which is how a rejoin lands a fresh item at the place the
+session held, AVPlayer fetches from about 6 s below the target first, so the reading is the lookback
+itself: one device capture shows `buffer ahead 4.00s` from a playhead of 48.00 s on an item placed at
+53.908 s, every second of it behind the start, and `playImmediately` 36 ms before the item was ready. It
+was the one item of five in that capture to be forced and the one its viewer reported out of sync, which
+is a correlation and not yet a mechanism. A hold on an item that cannot play yet is now left alone
+(`leaving the stall-avoidance wait alone on an item that cannot play yet ...; asked again at readiness`)
+and decided again when the item becomes ready, from the playhead it really starts on.
+
 ### The rewind depth a live session really has
 
 `seekableLiveRange` used to be `max(0, edgeTime - dvrWindowSeconds) ... edgeTime`, pure arithmetic that
@@ -975,7 +986,7 @@ All flags default to safe values; the table is the full set. Depth for the media
 | `dvrWindowSeconds` | nil | Timeshift window. nil means live-only and `seek` is a no-op. The window is a ceiling: the disk budget (a quarter of the free space, at most 2 GiB) bounds what is actually kept, so a long window on a high-bitrate channel or a small volume holds less than it asks for. |
 | `liveJoinProfile` | `.standard` | A `LiveJoinProfile`. `.fastZap` collapses TARGETDURATION to 1.5 x the source GOP (AE#670) so an IPTV join costs seconds instead of a full holdback. |
 | `clampsLiveResumeToWindow` | true | Whether `play()` may move a behind-live playhead by itself (edge snap on a live-only source more than 45 s behind, or a landing above the retained floor when a DVR window has slid past it). `false` hands the whole decision to the host, which then also owns the eviction case. |
-| `liveJoinStartsImmediately` | true | Cuts AVPlayer's stall-avoidance wait short once at the live join, over a buffer that is non-empty and at least 1.5 s deep. The join tail no host can otherwise reach; default since 6.55.0 on a device A/B, see the live-join section. |
+| `liveJoinStartsImmediately` | true | Cuts AVPlayer's stall-avoidance wait short once at the live join, over a buffer that is non-empty and at least 1.5 s deep, on an item that has reached `readyToPlay` (AE#684). The join tail no host can otherwise reach; default since 6.55.0 on a device A/B, see the live-join section. |
 | `liveBlockingReload` | nil (auto) | LL-HLS blocking-reload override for loopback live sessions. Auto derives eligibility from observed upstream cadence, which is what keeps a bursty relay off a `-15410` loop. |
 | `nativeRemoteHLS` | false | Hand a remote `master.m3u8` straight to AVPlayer: no demuxer probe, no loopback. Built for `isLive: true`; a remote HLS VOD URL reaches this route regardless (AE#154). The clock here is item time, see `clock.$sourceTime` (AE#616). |
 | `nativeRemoteHLSIngestFallback` | true | The #168 / #293 carriage recovery and the #363 401/403 bypass refusal recovery. Setting it false turns both off. |

From 3abefe0e040fd95179c7d39d17a658d2295a118a Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 1 Oct 2026 18:50:02 +0200
Subject: [PATCH 268/359] diag(live): each native live item says what it
 started on (#684)

A viewer saw sound and picture slightly apart after an item rebuild
placed mid-segment and together again after the next. The served media
measures aligned (beep against flash -0.3 ms on 147 of 148 seconds
across an outage), and what AVPlayer's renderer does with it cannot be
observed on macOS: an MTAudioProcessingTap on an HLS item is never
called.

So the session states the facts a device capture needs. Every finalized
live segment carries the span of its sound (it opens up to 208 ms
before its picture on a TS source, because the cut is taken on the
video keyframe), each item start names its segment, the offset into it
and that segment's sound against its picture, and the audio route line
adds the route's output latency.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 Sources/AetherEngine/AetherEngine+Live.swift  | 39 +++++++++++
 .../AetherEngine/AetherEngine+Loading.swift   |  1 +
 .../Native/NativeAVPlayerHost.swift           |  5 +-
 .../Video/HLSSegmentProducer.swift            | 13 ++++
 .../AetherEngine/Video/HLSVideoEngine.swift   |  9 +++
 .../AetherEngine/Video/MP4SegmentMuxer.swift  | 18 +++++
 .../Video/VideoSegmentProvider.swift          | 23 +++++++
 .../Issue684LiveItemStartAccountTests.swift   | 69 +++++++++++++++++++
 8 files changed, 176 insertions(+), 1 deletion(-)
 create mode 100644 Tests/AetherEngineTests/Issue684LiveItemStartAccountTests.swift

diff --git a/Sources/AetherEngine/AetherEngine+Live.swift b/Sources/AetherEngine/AetherEngine+Live.swift
index fcd45fcd1..903be119e 100644
--- a/Sources/AetherEngine/AetherEngine+Live.swift
+++ b/Sources/AetherEngine/AetherEngine+Live.swift
@@ -396,6 +396,45 @@ extension AetherEngine {
         Swift.max(0, producerFloorSession - (itemSeekableStart + shift))
     }
 
+    /// AE#684: what a native live item starts ON, once per item.
+    ///
+    /// Reported from the field: after an item rebuild placed mid-segment (`segment 26 + 1.91s`) sound
+    /// and picture were slightly apart, and together again after the next rebuild, which landed on a
+    /// boundary (`segment 129 + 0.03s`). The served media measures aligned on the harness (see
+    /// `docs/cli.md`), and nothing on macOS can observe what AVPlayer's audio renderer does with it,
+    /// so the line states the two facts a device capture needs beside the viewer's verdict: where in
+    /// which segment the item started, and where that segment's sound begins against its picture.
+    /// The AE#440 line beside it says whether the start was forced with `playImmediately`, which in
+    /// that capture was true for the one item reported out of sync and for none of the other four.
+    @MainActor
+    func noteLiveItemStart() {
+        guard isLive, let host = nativeHost, let session = nativeVideoSession else { return }
+        let itemSeconds = host.currentTime
+        let outputSeconds = itemSeconds + liveItemAxisOffsetSeconds
+        EngineLog.emit(
+            Self.liveItemStartAccount(
+                item: host.itemGeneration, itemSeconds: itemSeconds,
+                heads: session.liveSegmentHeads(atOutputSeconds: outputSeconds)),
+            category: .engine)
+    }
+
+    nonisolated static func liveItemStartAccount(
+        item: Int, itemSeconds: Double,
+        heads: (index: Int, secondsIntoSegment: Double, pictureStart: Double, sound: (first: Double, last: Double)?)?
+    ) -> String {
+        let head = "[AetherEngine] #684 item #\(item) starts at its own "
+            + "\(String(format: "%.3f", itemSeconds))s"
+        guard let heads else { return head + ", in no segment the producer lists yet" }
+        let place = ": segment \(heads.index) + \(String(format: "%.3f", heads.secondsIntoSegment))s, "
+            + "whose picture opens at \(String(format: "%.3f", heads.pictureStart))s"
+        guard let sound = heads.sound else { return head + place + " and whose sound was not recorded" }
+        let lead = (heads.pictureStart - sound.first) * 1000
+        return head + place + " and whose sound runs "
+            + "\(String(format: "%.3f", sound.first))..\(String(format: "%.3f", sound.last))s "
+            + "(it opens \(String(format: "%.0f", abs(lead))) ms "
+            + (lead >= 0 ? "before" : "after") + " the picture)"
+    }
+
     /// AE#446 round 4: the three readings a rejoin's placement is argued from, on one line.
     ///
     /// They were only ever available separately, which is why an item's clock and an item's seekable
diff --git a/Sources/AetherEngine/AetherEngine+Loading.swift b/Sources/AetherEngine/AetherEngine+Loading.swift
index 79154f246..61dbd3823 100644
--- a/Sources/AetherEngine/AetherEngine+Loading.swift
+++ b/Sources/AetherEngine/AetherEngine+Loading.swift
@@ -220,6 +220,7 @@ extension AetherEngine {
                 // it can play, nothing it reports is a reading of where the session is; see
                 // `liveItemPlacementPending`.
                 if ready {
+                    self.noteLiveItemStart()
                     // The placement is spent here, on every path rather than only on the one that
                     // replays the stashed seek: a pre-ready seek can be superseded by a host scrub
                     // (latest-wins), and an arm left standing would be inherited by whatever item the
diff --git a/Sources/AetherEngine/Native/NativeAVPlayerHost.swift b/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
index 5f44b171d..52e538717 100644
--- a/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
+++ b/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
@@ -2706,7 +2706,10 @@ final class NativeAVPlayerHost {
         }.joined(separator: ", ")
         EngineLog.emit(
             "[NativeAVPlayerHost] #\(sid) audioRoute output=\(out) preferred=\(pref) max=\(maxCh) "
-            + "ports=[\(outputDescs)] (\(phase))",
+            + "ports=[\(outputDescs)] "
+            // AE#684: what the route says it delays sound by, per item, beside the item's start.
+            + "latency=\(String(format: "%.0f", session.outputLatency * 1000))ms "
+            + "io=\(String(format: "%.1f", session.ioBufferDuration * 1000))ms (\(phase))",
             category: .engine
         )
         #endif
diff --git a/Sources/AetherEngine/Video/HLSSegmentProducer.swift b/Sources/AetherEngine/Video/HLSSegmentProducer.swift
index 7903129f2..cb016d6c8 100644
--- a/Sources/AetherEngine/Video/HLSSegmentProducer.swift
+++ b/Sources/AetherEngine/Video/HLSSegmentProducer.swift
@@ -208,6 +208,11 @@ final class HLSSegmentProducer: @unchecked Sendable {
 
     /// Fires synchronously on the pump thread per finalized live segment (index, duration, startSeconds, discontinuous).
     var onLiveSegmentFinalized: (@Sendable (Int, Double, Double, Bool) -> Void)?
+    /// AE#684: the sound a finalized live segment carries (index, first and last audio packet on the
+    /// output axis, seconds). Fired just before `onLiveSegmentFinalized` for the same index.
+    var onLiveSegmentSound: (@Sendable (Int, Double, Double) -> Void)?
+    /// Keyed by segment index; a nil value is a segment cut with no audio packet in it.
+    private var liveSegmentSoundByIndex: [Int: (first: Double, last: Double)?] = [:]
 
     /// AE#443: the resident segment count the live runaway park may use, from the session that owns the
     /// window (`VideoSegmentProvider.liveResidentParkCap`). Unset leaves the static floor, which is the
@@ -2369,6 +2374,11 @@ final class HLSSegmentProducer: @unchecked Sendable {
             // credit this pump with the previous epoch's production.
             pumpEpochHighestStored = max(pumpEpochHighestStored, currentMuxerSegmentIndex)
             if isLive {
+                let tb = muxer.muxerAudioTimeBase
+                let tick = tb.den > 0 ? Double(tb.num) / Double(tb.den) : 0
+                liveSegmentSoundByIndex.updateValue(
+                    muxer.takeSegmentSoundSpan().map { (Double($0.first) * tick, Double($0.last) * tick) },
+                    forKey: currentMuxerSegmentIndex)
                 reportLiveSegmentFinalized(index: currentMuxerSegmentIndex,
                                            nextIndex: newIdx)
             } else if onSequentialSegmentFinalized != nil {
@@ -2531,15 +2541,18 @@ final class HLSSegmentProducer: @unchecked Sendable {
             duration = targetSegmentDurationSeconds
         }
         let discontinuous = liveSegmentDiscontinuousByIndex[index] ?? false
+        let sound = liveSegmentSoundByIndex.removeValue(forKey: index)
         liveSegmentStartByIndex.removeValue(forKey: index)
         liveSegmentDiscontinuousByIndex.removeValue(forKey: index)
         stampLiveSegmentFinalize()
         EngineLog.emit(
             "[HLSSegmentProducer] live seg-\(index) finalized: start=\(String(format: "%.3f", startSeconds))s "
             + "dur=\(String(format: "%.3f", duration))s"
+            + (sound.map { $0.map { String(format: " sound=%.3f..%.3fs", $0.first, $0.last) } ?? " sound=none" } ?? "")
             + (discontinuous ? " [DISCONTINUITY]" : ""),
             category: .session
         )
+        if let span = sound ?? nil { onLiveSegmentSound?(index, span.first, span.last) }
         onLiveSegmentFinalized?(index, duration, startSeconds, discontinuous)
     }
 
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine.swift b/Sources/AetherEngine/Video/HLSVideoEngine.swift
index 8e53f8b30..af6130939 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine.swift
@@ -2713,6 +2713,9 @@ public final class HLSVideoEngine: @unchecked Sendable {
                                         durationSeconds: durationSeconds,
                                         discontinuous: discontinuous)
             }
+            prod.onLiveSegmentSound = { [weak prov] index, first, last in
+                prov?.noteLiveSegmentSound(index: index, firstSeconds: first, lastSeconds: last)
+            }
             // AE#443: the runaway park has to sit above the window this session actually serves, or it
             // bounds the window instead of backstopping it, and its enforcement (a sleeping read
             // thread) stops the origin from being drained.
@@ -3838,6 +3841,12 @@ public final class HLSVideoEngine: @unchecked Sendable {
     /// AE#454: the placement is spent once the item that asked for it is running.
     func clearLiveRejoinStart() { provider?.clearLiveRejoinStart() }
 
+    /// See `VideoSegmentProvider.liveSegmentHeads(atOutputSeconds:)`.
+    func liveSegmentHeads(atOutputSeconds seconds: Double)
+        -> (index: Int, secondsIntoSegment: Double, pictureStart: Double, sound: (first: Double, last: Double)?)? {
+        provider?.liveSegmentHeads(atOutputSeconds: seconds)
+    }
+
     /// See `VideoSegmentProvider.servedLiveRejoinPlacement`.
     var servedLiveRejoinPlacement: (timeOffset: Double, playlistStartOutputSeconds: Double)? {
         provider?.servedLiveRejoinPlacement
diff --git a/Sources/AetherEngine/Video/MP4SegmentMuxer.swift b/Sources/AetherEngine/Video/MP4SegmentMuxer.swift
index b7e370fbb..1c59008e6 100644
--- a/Sources/AetherEngine/Video/MP4SegmentMuxer.swift
+++ b/Sources/AetherEngine/Video/MP4SegmentMuxer.swift
@@ -243,6 +243,20 @@ final class MP4SegmentMuxer {
     /// Output-TB DTS of the first video packet since the last flush; Int64.min = no window open yet.
     private var fragmentWindowFirstVideoDts: Int64 = Int64.min
 
+    /// AE#684: the sound handed to the segment being cut, first and last packet, in
+    /// `muxerAudioTimeBase`. A segment opens on a video keyframe and carries whatever audio the
+    /// source interleaved up to there, so where its sound begins against its picture is a property
+    /// of the source's mux, and it is what an item placed in that segment starts its audio from.
+    private var segmentSoundFirstPts: Int64 = Int64.min
+    private var segmentSoundLastPts: Int64 = Int64.min
+
+    /// The span since the last call, nil when the segment carried no audio packet. Consumes it.
+    func takeSegmentSoundSpan() -> (first: Int64, last: Int64)? {
+        defer { segmentSoundFirstPts = Int64.min; segmentSoundLastPts = Int64.min }
+        guard segmentSoundFirstPts != Int64.min else { return nil }
+        return (segmentSoundFirstPts, segmentSoundLastPts)
+    }
+
     let videoOutputStreamIndex: Int32 = 0
     let audioOutputStreamIndex: Int32 = 1
 
@@ -694,6 +708,10 @@ final class MP4SegmentMuxer {
         // must keep the exact stock code path, no extra early fragment flush, so nothing perturbs its audio.
         if streamIndex == audioOutputStreamIndex {
             audioPacketWritten = true
+            if rc >= 0, clean.pts != Int64.min {
+                if segmentSoundFirstPts == Int64.min { segmentSoundFirstPts = clean.pts }
+                segmentSoundLastPts = clean.pts
+            }
             if audioNeedsParsedPacketForMoov, !moovFlushed, fragmentWindowFirstVideoDts != Int64.min {
                 flushPendingFragment()
             }
diff --git a/Sources/AetherEngine/Video/VideoSegmentProvider.swift b/Sources/AetherEngine/Video/VideoSegmentProvider.swift
index cde7409b1..9e7efe057 100644
--- a/Sources/AetherEngine/Video/VideoSegmentProvider.swift
+++ b/Sources/AetherEngine/Video/VideoSegmentProvider.swift
@@ -920,6 +920,29 @@ final class VideoSegmentProvider: HLSSegmentProvider, @unchecked Sendable {
         self.segmentServedHandler = segmentServedHandler
     }
 
+    /// AE#684: where a live segment's sound begins and ends on the output axis, by segment index.
+    /// Diagnostic only: it lets an item start say what it started its audio from. Bounded, oldest out.
+    private var _liveSegmentSound: [Int: (first: Double, last: Double)] = [:]
+    static let liveSegmentSoundRetained = 1024
+
+    func noteLiveSegmentSound(index: Int, firstSeconds: Double, lastSeconds: Double) {
+        stateLock.lock()
+        _liveSegmentSound[index] = (firstSeconds, lastSeconds)
+        _liveSegmentSound.removeValue(forKey: index - Self.liveSegmentSoundRetained)
+        stateLock.unlock()
+    }
+
+    /// AE#684: the segment an output-axis position falls in, with its picture's start and its
+    /// sound's span. nil for a position no listed segment covers.
+    func liveSegmentHeads(atOutputSeconds seconds: Double)
+        -> (index: Int, secondsIntoSegment: Double, pictureStart: Double, sound: (first: Double, last: Double)?)? {
+        stateLock.lock()
+        defer { stateLock.unlock() }
+        guard let idx = Self.thumbnailSegmentIndex(atSeconds: seconds, segments: segments) else { return nil }
+        return (idx, Swift.max(0, seconds - segments[idx].startSeconds), segments[idx].startSeconds,
+                _liveSegmentSound[idx])
+    }
+
     /// Append a finalized live segment. Index must equal segments.count; out-of-order ignored.
     func appendLiveSegment(index: Int, startSeconds: Double, durationSeconds: Double,
                            discontinuous: Bool = false) {
diff --git a/Tests/AetherEngineTests/Issue684LiveItemStartAccountTests.swift b/Tests/AetherEngineTests/Issue684LiveItemStartAccountTests.swift
new file mode 100644
index 000000000..40f188309
--- /dev/null
+++ b/Tests/AetherEngineTests/Issue684LiveItemStartAccountTests.swift
@@ -0,0 +1,69 @@
+// Tests/AetherEngineTests/Issue684LiveItemStartAccountTests.swift
+// AE#684, second half: a viewer saw sound and picture slightly apart after an item rebuild placed
+// mid-segment (`segment 26 + 1.91s`) and together again after the next one (`segment 129 + 0.03s`).
+// The served media measures aligned and macOS cannot observe AVPlayer's audio renderer, so the session
+// states what each native live item started on: the segment, the offset into it, and where that
+// segment's sound begins against its picture. These pin the line and the lookup it reads.
+import XCTest
+@testable import AetherEngine
+
+final class Issue684LiveItemStartAccountTests: XCTestCase {
+
+    func testAccountNamesThePlacementAndTheSoundAgainstThePicture() {
+        let line = AetherEngine.liveItemStartAccount(
+            item: 7, itemSeconds: 53.908,
+            heads: (index: 26, secondsIntoSegment: 1.908, pictureStart: 52.0, sound: (first: 51.921, last: 53.905)))
+        XCTAssertTrue(line.contains("#684 item #7 starts at its own 53.908s"), line)
+        XCTAssertTrue(line.contains("segment 26 + 1.908s"), line)
+        XCTAssertTrue(line.contains("picture opens at 52.000s"), line)
+        XCTAssertTrue(line.contains("sound runs 51.921..53.905s"), line)
+        XCTAssertTrue(line.contains("opens 79 ms before the picture"), line)
+    }
+
+    func testAccountSaysWhenTheSoundOpensAfterThePicture() {
+        let line = AetherEngine.liveItemStartAccount(
+            item: 1, itemSeconds: 6.0,
+            heads: (index: 3, secondsIntoSegment: 0, pictureStart: 6.0, sound: (first: 6.013, last: 7.997)))
+        XCTAssertTrue(line.contains("opens 13 ms after the picture"), line)
+    }
+
+    /// An absence is stated, not printed as a zero that would read as "aligned".
+    func testAccountDoesNotInventWhatWasNotRecorded() {
+        let unrecorded = AetherEngine.liveItemStartAccount(
+            item: 2, itemSeconds: 4.0,
+            heads: (index: 2, secondsIntoSegment: 0, pictureStart: 4.0, sound: nil))
+        XCTAssertTrue(unrecorded.contains("sound was not recorded"), unrecorded)
+        XCTAssertFalse(unrecorded.contains(" ms "), unrecorded)
+        let unlisted = AetherEngine.liveItemStartAccount(item: 2, itemSeconds: 400.0, heads: nil)
+        XCTAssertTrue(unlisted.contains("in no segment the producer lists yet"), unlisted)
+    }
+
+    func testProviderResolvesAPositionToItsSegmentAndItsSound() throws {
+        let provider = VideoSegmentProvider(
+            cache: SegmentCache(forwardWindow: 10, backwardWindow: 10),
+            segments: [],
+            codecsString: "avc1.4D001E,mp4a.40.2",
+            supplementalCodecs: nil,
+            resolution: (720, 576),
+            videoRange: .sdr,
+            frameRate: 25,
+            hdcpLevel: nil,
+            sourceBitrate: 1_500_000,
+            isLive: true,
+            liveWindowSizing: LiveWindowSizing(targetSegmentDurationSeconds: 0.5, dvrWindowSeconds: nil),
+            liveCadencePolicy: nil
+        )
+        for index in 0..<4 {
+            provider.appendLiveSegment(index: index, startSeconds: Double(index) * 2, durationSeconds: 2)
+            provider.noteLiveSegmentSound(index: index,
+                                          firstSeconds: Double(index) * 2 - 0.079,
+                                          lastSeconds: Double(index) * 2 + 1.899)
+        }
+        let heads = try XCTUnwrap(provider.liveSegmentHeads(atOutputSeconds: 5.908))
+        XCTAssertEqual(heads.index, 2)
+        XCTAssertEqual(heads.secondsIntoSegment, 1.908, accuracy: 1e-9)
+        XCTAssertEqual(heads.pictureStart, 4.0, accuracy: 1e-9)
+        XCTAssertEqual(try XCTUnwrap(heads.sound).first, 3.921, accuracy: 1e-9)
+        XCTAssertNil(provider.liveSegmentHeads(atOutputSeconds: 8.5), "past the last listed segment")
+    }
+}

From b01fcd6cb465042a4db66d2de4a425a75cb45b1a Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 1 Oct 2026 18:50:03 +0200
Subject: [PATCH 269/359] test(aetherctl): an HLS origin with a scripted
 delivery rhythm, and the served URL (#684)

hlsfixture publishes on a metronome, so a defect that only exists when
a delivery arrives later than the segment is long could not be
reproduced. Scripts/hls-burst-origin.py publishes each segment on a
schedule (jitter cycle, outage, alternating segment lengths, a link
rate shared by all responses) while keeping the mean cadence at the
segment duration.

play --served-url prints the loopback URL of each native item, so the
init segment can be fetched and the cached fMP4 segments read with
ffprobe. docs/cli.md carries the measurements of both halves of #684.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 Scripts/hls-burst-origin.py         | 162 ++++++++++++++++++++++++++++
 Sources/aetherctl/PlaybackCmd.swift |  13 ++-
 Sources/aetherctl/main.swift        |   4 +-
 docs/cli.md                         |  40 +++++++
 4 files changed, 215 insertions(+), 4 deletions(-)
 create mode 100755 Scripts/hls-burst-origin.py

diff --git a/Scripts/hls-burst-origin.py b/Scripts/hls-burst-origin.py
new file mode 100755
index 000000000..8cc0d439e
--- /dev/null
+++ b/Scripts/hls-burst-origin.py
@@ -0,0 +1,162 @@
+#!/usr/bin/env python3
+r"""A live HLS origin whose DELIVERY RHYTHM is scripted (AE#684).
+
+`aetherctl hlsfixture` publishes on a metronome, and a metronome is the one thing no IPTV origin is:
+the defect this was written for only exists when a delivery arrives later than the segment is long.
+This serves a sliding playlist over pre-cut TS segments and publishes segment k at
+
+    end of segment k  -  what was prefilled  +  delays[k % len(delays)]
+
+seconds after it starts, so the mean cadence stays the segment duration (the origin never falls
+behind real time) and the jitter is the delay cycle. `--freeze-at K --freeze-seconds F` holds
+everything from segment K on for F seconds: an outage, after which the backlog lands at once.
+Every request is one stderr line stamped with seconds since start.
+
+    # 720x576 25 fps, 2 s GOPs, 6 s segments, a white frame and a 40 ms beep on every whole second
+    ffmpeg -f lavfi -i "color=c=black:s=720x576:r=25:d=600,drawbox=x=0:y=0:w=720:h=576:color=white:\
+t=fill:enable='lt(mod(t,1),0.039)',format=yuv420p" \
+           -f lavfi -i "aevalsrc='if(lt(mod(t,1),0.04),0.8*sin(2*PI*1000*t),0)':s=48000:d=600:c=stereo" \
+           -c:v libx264 -preset ultrafast -profile:v main -g 50 -keyint_min 50 -sc_threshold 0 -bf 0 \
+           -b:v 1500k -maxrate 1500k -bufsize 3000k -x264-params nal-hrd=cbr \
+           -c:a aac -b:a 128k -ar 48000 -f hls -hls_time 6 -hls_list_size 0 -hls_segment_type mpegts \
+           -hls_flags independent_segments -hls_segment_filename 'seg6/seg%d.ts' seg6/out.m3u8
+
+    Scripts/hls-burst-origin.py --dir seg6 --delays 0,0.3,2.6,0.2,0.6,2.4,0.1,0.5 &
+    aetherctl play --live --live-ingest --fast-zap --seconds 180 http://127.0.0.1:8684/live.m3u8
+
+Threaded and HTTP/1.0 on purpose: the ingest fetches up to four segments at once, and a
+keep-alive connection would hide which request paid for what.
+"""
+import argparse, os, sys, threading, time
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+ap = argparse.ArgumentParser()
+ap.add_argument("--dir", required=True)
+ap.add_argument("--port", type=int, default=8684)
+ap.add_argument("--dur", type=float, default=6.0)
+ap.add_argument("--durs", default="", help="comma list of per-segment durations, cycled (overrides --dur)")
+ap.add_argument("--target-duration", type=int, default=6)
+ap.add_argument("--window", type=int, default=6)
+ap.add_argument("--prefill", type=int, default=6, help="segments already published at start")
+ap.add_argument("--delays", default="0", help="comma list of per-segment publish delays, cycled")
+ap.add_argument("--freeze-at", type=int, default=-1)
+ap.add_argument("--freeze-seconds", type=float, default=0)
+ap.add_argument("--latency-ms", type=float, default=0, help="delay before every response header")
+ap.add_argument("--rate-kbps", type=float, default=0, help="link rate shared by all in-flight responses")
+args = ap.parse_args()
+
+delays = [float(x) for x in args.delays.split(",")]
+count = len([f for f in os.listdir(args.dir) if f.startswith("seg") and f.endswith(".ts")])
+durs = [float(x) for x in args.durs.split(",")] if args.durs else [args.dur]
+seg_dur = [durs[k % len(durs)] for k in range(count)]
+ends = []
+acc = 0.0
+for k in range(count):
+    acc += seg_dur[k]
+    ends.append(acc)
+prefill_end = ends[args.prefill - 1] if args.prefill > 0 else 0.0
+publish = []
+for k in range(count):
+    p = 0.0 if k < args.prefill else ends[k] - prefill_end + delays[k % len(delays)]
+    publish.append(p)
+if args.freeze_at >= 0:
+    thaw = publish[args.freeze_at] + args.freeze_seconds
+    for k in range(args.freeze_at, count):
+        publish[k] = max(publish[k], thaw)
+for k in range(1, count):
+    publish[k] = max(publish[k], publish[k - 1])
+
+t0 = time.monotonic()
+lock = threading.Lock()
+
+
+def log(msg):
+    with lock:
+        sys.stderr.write("%8.3f %s\n" % (time.monotonic() - t0, msg))
+        sys.stderr.flush()
+
+
+rate_lock = threading.Lock()
+rate_clock = [0.0]
+
+
+def send_paced(wfile, body):
+    """One virtual clock for every response: a second connection gets no bandwidth of its own."""
+    if args.rate_kbps <= 0:
+        wfile.write(body)
+        return
+    chunk = 16 * 1024
+    for i in range(0, len(body), chunk):
+        part = body[i:i + chunk]
+        with rate_lock:
+            now = time.monotonic()
+            start = max(now, rate_clock[0])
+            rate_clock[0] = start + len(part) * 8 / (args.rate_kbps * 1000.0)
+            due = rate_clock[0]
+        wait = due - time.monotonic()
+        if wait > 0:
+            time.sleep(wait)
+        wfile.write(part)
+
+
+def playlist():
+    now = time.monotonic() - t0
+    last = -1
+    for k in range(count):
+        if publish[k] <= now:
+            last = k
+        else:
+            break
+    first = max(0, last - args.window + 1)
+    lines = ["#EXTM3U", "#EXT-X-VERSION:3", "#EXT-X-TARGETDURATION:%d" % args.target_duration,
+             "#EXT-X-MEDIA-SEQUENCE:%d" % first]
+    for k in range(first, last + 1):
+        lines.append("#EXTINF:%.3f," % seg_dur[k])
+        lines.append("seg%d.ts" % k)
+    return ("\n".join(lines) + "\n").encode(), last
+
+
+class H(BaseHTTPRequestHandler):
+    protocol_version = "HTTP/1.0"
+
+    def log_message(self, *a):
+        pass
+
+    def do_GET(self):
+        if args.latency_ms > 0:
+            time.sleep(args.latency_ms / 1000.0)
+        path = self.path.split("?")[0]
+        if path.endswith(".m3u8"):
+            body, last = playlist()
+            log("REQ playlist last=seg%d" % last)
+            self.send_response(200)
+            self.send_header("Content-Type", "application/vnd.apple.mpegurl")
+        elif path.endswith(".ts"):
+            name = os.path.basename(path)
+            try:
+                with open(os.path.join(args.dir, name), "rb") as f:
+                    body = f.read()
+            except OSError:
+                log("REQ %s 404" % name)
+                self.send_response(404)
+                self.end_headers()
+                return
+            log("REQ %s" % name)
+            self.send_response(200)
+            self.send_header("Content-Type", "video/mp2t")
+        else:
+            self.send_response(404)
+            self.end_headers()
+            return
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        try:
+            send_paced(self.wfile, body)
+        except OSError:
+            pass
+
+
+gaps = [publish[k] - publish[k - 1] for k in range(args.prefill, min(count, args.prefill + 40))]
+log("origin up: %d segments, publish gaps (first 40 after prefill): %s" % (
+    count, " ".join("%.1f" % g for g in gaps)))
+ThreadingHTTPServer(("127.0.0.1", args.port), H).serve_forever()
diff --git a/Sources/aetherctl/PlaybackCmd.swift b/Sources/aetherctl/PlaybackCmd.swift
index ce4399c7d..fe5ec7c23 100644
--- a/Sources/aetherctl/PlaybackCmd.swift
+++ b/Sources/aetherctl/PlaybackCmd.swift
@@ -99,7 +99,7 @@ enum LoadOptionChange {
 /// and log every overlay cue that arrives. Repro harness for "loads but never
 /// plays" reports and for live teletext end-to-end validation (#107).
 func runPlay(url: URL, seconds: Double, live: Bool, nativeHLS: Bool = false, liveIngest: Bool = false, fastZap: Bool = false, liveStartImmediately: Bool = true, dvrWindow: Double?, subsPick: String?, hostCalls: [String], audioStats: Bool = false, seekEvery: Double? = nil, seekPattern: [Double] = [], seekCount: Int? = nil, startPosition: Double? = nil, mallocCensus: Bool = false, forceSoftware: Bool = false, softwareEscalation: Bool = true,
-                    censusThresholdMB: Int? = nil, censusHz: Double? = nil, frameTimes: Bool = false, presentTimes: Bool = false, pictureProbe: Bool = false, pictureOrigin: Double = 0,
+                    censusThresholdMB: Int? = nil, censusHz: Double? = nil, frameTimes: Bool = false, presentTimes: Bool = false, servedURL: Bool = false, pictureProbe: Bool = false, pictureOrigin: Double = 0,
                     sidecars: [ExternalSubtitleTrack] = [], audioSwitch: AudioSwitchRequest? = nil,
                     teletextPage: Int? = nil, teletextSwitch: TeletextPageSwitchRequest? = nil,
                     audioDelayMs: Int = 0, audioDelaySwitches: [AudioDelaySwitchRequest] = [],
@@ -132,7 +132,7 @@ func runPlay(url: URL, seconds: Double, live: Bool, nativeHLS: Bool = false, liv
     // CFRunLoopRun, not a blocking semaphore: AetherEngine is @MainActor, so parking the main thread would deadlock the executor.
     let box = UncheckedBox<Int32?>(nil)
     Task { @MainActor in
-        box.value = await playSmokeTest(url: url, seconds: seconds, live: live, forceSoftware: forceSoftware, softwareEscalation: softwareEscalation, nativeHLS: nativeHLS, liveIngest: liveIngest, fastZap: fastZap, liveStartImmediately: liveStartImmediately, dvrWindow: dvrWindow, subsPick: subsPick, hostCalls: hostCalls, audioStats: audioStats, seekEvery: seekEvery, seekPattern: seekPattern, seekCount: seekCount, startPosition: startPosition, frameTimes: frameTimes, presentTimes: presentTimes, pictureProbe: pictureProbe, pictureOrigin: pictureOrigin, sidecars: sidecars, audioSwitch: audioSwitch, teletextPage: teletextPage, teletextSwitch: teletextSwitch, audioDelayMs: audioDelayMs, audioDelaySwitches: audioDelaySwitches, pausedMount: pausedMount, optionCorrection: optionCorrection, sequentialOrigin: sequentialOrigin, maxConcurrentRequests: maxConcurrentRequests, heldConnection: heldConnection, declaredDuration: declaredDuration, httpHeaders: httpHeaders, deinterlaceFieldRate: deinterlaceFieldRate, assertDolbyVision: assertDolbyVision, preserveASSMarkup: preserveASSMarkup, dolbyVisionHandling: dolbyVisionHandling, record: record)
+        box.value = await playSmokeTest(url: url, seconds: seconds, live: live, forceSoftware: forceSoftware, softwareEscalation: softwareEscalation, nativeHLS: nativeHLS, liveIngest: liveIngest, fastZap: fastZap, liveStartImmediately: liveStartImmediately, dvrWindow: dvrWindow, subsPick: subsPick, hostCalls: hostCalls, audioStats: audioStats, seekEvery: seekEvery, seekPattern: seekPattern, seekCount: seekCount, startPosition: startPosition, frameTimes: frameTimes, presentTimes: presentTimes, servedURL: servedURL, pictureProbe: pictureProbe, pictureOrigin: pictureOrigin, sidecars: sidecars, audioSwitch: audioSwitch, teletextPage: teletextPage, teletextSwitch: teletextSwitch, audioDelayMs: audioDelayMs, audioDelaySwitches: audioDelaySwitches, pausedMount: pausedMount, optionCorrection: optionCorrection, sequentialOrigin: sequentialOrigin, maxConcurrentRequests: maxConcurrentRequests, heldConnection: heldConnection, declaredDuration: declaredDuration, httpHeaders: httpHeaders, deinterlaceFieldRate: deinterlaceFieldRate, assertDolbyVision: assertDolbyVision, preserveASSMarkup: preserveASSMarkup, dolbyVisionHandling: dolbyVisionHandling, record: record)
         CFRunLoopStop(CFRunLoopGetMain())
     }
     CFRunLoopRun()
@@ -453,7 +453,7 @@ private func seekIntentDrill(
 }
 
 @MainActor
-private func playSmokeTest(url: URL, seconds: Double, live: Bool, forceSoftware: Bool = false, softwareEscalation: Bool = true, nativeHLS: Bool = false, liveIngest: Bool = false, fastZap: Bool = false, liveStartImmediately: Bool = true, dvrWindow: Double?, subsPick: String?, hostCalls: [String], audioStats: Bool, seekEvery: Double? = nil, seekPattern: [Double] = [], seekCount: Int? = nil, startPosition: Double? = nil, frameTimes: Bool = false, presentTimes: Bool = false, pictureProbe: Bool = false, pictureOrigin: Double = 0, sidecars: [ExternalSubtitleTrack] = [], audioSwitch: AudioSwitchRequest? = nil, teletextPage: Int? = nil, teletextSwitch: TeletextPageSwitchRequest? = nil, audioDelayMs: Int = 0, audioDelaySwitches: [AudioDelaySwitchRequest] = [], pausedMount: Bool = false, optionCorrection: LoadOptionCorrectionRequest? = nil, sequentialOrigin: Bool = false, maxConcurrentRequests: Int? = nil, heldConnection: Bool = false, declaredDuration: Double? = nil, httpHeaders: [String: String] = [:], deinterlaceFieldRate: DeinterlaceFieldRate = .field, assertDolbyVision: Bool = false, preserveASSMarkup: Bool = false, dolbyVisionHandling: DolbyVisionHandling = .automatic, record: URL? = nil) async -> Int32 {
+private func playSmokeTest(url: URL, seconds: Double, live: Bool, forceSoftware: Bool = false, softwareEscalation: Bool = true, nativeHLS: Bool = false, liveIngest: Bool = false, fastZap: Bool = false, liveStartImmediately: Bool = true, dvrWindow: Double?, subsPick: String?, hostCalls: [String], audioStats: Bool, seekEvery: Double? = nil, seekPattern: [Double] = [], seekCount: Int? = nil, startPosition: Double? = nil, frameTimes: Bool = false, presentTimes: Bool = false, servedURL: Bool = false, pictureProbe: Bool = false, pictureOrigin: Double = 0, sidecars: [ExternalSubtitleTrack] = [], audioSwitch: AudioSwitchRequest? = nil, teletextPage: Int? = nil, teletextSwitch: TeletextPageSwitchRequest? = nil, audioDelayMs: Int = 0, audioDelaySwitches: [AudioDelaySwitchRequest] = [], pausedMount: Bool = false, optionCorrection: LoadOptionCorrectionRequest? = nil, sequentialOrigin: Bool = false, maxConcurrentRequests: Int? = nil, heldConnection: Bool = false, declaredDuration: Double? = nil, httpHeaders: [String: String] = [:], deinterlaceFieldRate: DeinterlaceFieldRate = .field, assertDolbyVision: Bool = false, preserveASSMarkup: Bool = false, dolbyVisionHandling: DolbyVisionHandling = .automatic, record: URL? = nil) async -> Int32 {
     let engine: AetherEngine
     do {
         engine = try AetherEngine()
@@ -605,6 +605,7 @@ private func playSmokeTest(url: URL, seconds: Double, live: Bool, forceSoftware:
     // which is the documented usage and the part a host would otherwise have to re-do per load.
     let frameProbe = frameTimes ? FrameTimeProbe() : nil
     let presentProbe = presentTimes ? PresentedFrameProbe() : nil
+    var servedURLItem: ObjectIdentifier?
     let picture = pictureProbe ? PictureProbe(sourceOrigin: pictureOrigin) : nil
     if let frameProbe {
         engine.setSoftwareVideoFrameTimeObserver { [weak frameProbe] frame in
@@ -944,6 +945,12 @@ private func playSmokeTest(url: URL, seconds: Double, live: Bool, forceSoftware:
             presentProbe.attachIfNeeded(engine.currentAVPlayerItem)
             line += " pres=\(presentProbe.drainTick())"
         }
+        if servedURL, let item = engine.currentAVPlayerItem, ObjectIdentifier(item) != servedURLItem,
+           let asset = item.asset as? AVURLAsset {
+            servedURLItem = ObjectIdentifier(item)
+            // Deliberately unredacted: the path token is the only way in, and this is a local harness.
+            FileHandle.standardOutput.write(Data("  SERVED \(asset.url.absoluteString)\n".utf8))
+        }
         // AE#441: the live rewind surfaces a host actually scales its strip on. Sampling them needed a
         // patched copy of this CLI before, which is how an over-promising lower bound stayed unseen.
         if engine.isLive {
diff --git a/Sources/aetherctl/main.swift b/Sources/aetherctl/main.swift
index c485905f7..8c75b3011 100644
--- a/Sources/aetherctl/main.swift
+++ b/Sources/aetherctl/main.swift
@@ -696,6 +696,8 @@ if first == "play" {
     // per-frame boundaries and the clock a host would pace an overlay against are both observable.
     let frameTimes = takeFlag("--frame-times", from: &rest)
     let presentTimes = takeFlag("--present-times", from: &rest)
+    // AE#684: print the loopback URL of every native item, so its init and segments can be fetched.
+    let servedURL = takeFlag("--served-url", from: &rest)
     let pictureProbe = takeFlag("--picture-probe", from: &rest)
     // AE#534: the source axis's origin, for a container whose timeline does not start at zero.
     // The picture states a frame index, which an -output_ts_offset remux does not move.
@@ -878,7 +880,7 @@ if first == "play" {
         done.wait()
     }
     exit(runPlay(url: parseSourceURL(urlArg), seconds: seconds, live: live, nativeHLS: nativeHLS, liveIngest: liveIngest, fastZap: playFastZap, liveStartImmediately: liveStartImmediately, dvrWindow: dvrWindow, subsPick: subsPick, hostCalls: hostCalls, audioStats: audioStats, seekEvery: seekEvery, seekPattern: seekPattern, seekCount: seekCount, startPosition: playStartPosition, mallocCensus: mallocCensus, forceSoftware: playForceSW, softwareEscalation: playSoftwareEscalation,
-                 censusThresholdMB: censusThresholdMB, censusHz: censusHz, frameTimes: frameTimes, presentTimes: presentTimes, pictureProbe: pictureProbe, pictureOrigin: pictureOrigin, sidecars: sidecars,
+                 censusThresholdMB: censusThresholdMB, censusHz: censusHz, frameTimes: frameTimes, presentTimes: presentTimes, servedURL: servedURL, pictureProbe: pictureProbe, pictureOrigin: pictureOrigin, sidecars: sidecars,
                  audioSwitch: audioSwitch,
                  teletextPage: teletextPage, teletextSwitch: teletextSwitch,
                  audioDelayMs: audioDelayMs, audioDelaySwitches: audioDelaySwitches,
diff --git a/docs/cli.md b/docs/cli.md
index b0d7a81c5..eb81bd74d 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -143,6 +143,8 @@ load and `playing` at the roll (AE#440).
 
 `--subs <codec-or-lang>` matches against the track's libavcodec name or language and logs every overlay cue and cue trim as it lands. `--host-calls` replays host post-load behavior against the fresh session: `play`, `extractor` (`makeFrameExtractor`), `setrate` (`setRate(1.0)`), `pausestart` (Sodalite#104 round 4: `pause()` the instant load returns, before any frame exists, and `play()` at t=8; the shape of a host that holds a fresh load paused, and a software session used to answer it with eight ticks of `enq=+0 status=unknown r4d=n`, a black picture under a paused clock; now the `[SWHost] #104` lines show the first frame presented at a stopped clock and `startup 8/8 presenting` arrives while paused), `ratehold` (set 1.5, pause at tick 3, resume at tick 5, then read the rate back off the transport itself: the #436 drill, and it fails the run if the resume came back at 1.0), `reloadlive` (reload the URL on the live path when the probe flags it live, the AetherPlayer Open URL flow), `reloadnext` (a host's episode seam: the same URL loaded again at t=4 on the still-playing engine with no `stop()` in between, so the native host is reused, and every published `state` printed as `STATE <state> t=<s>`; the second load must go `loading`, `playing` with no `paused` between them, which it did not while the reused host still carried the outgoing item's `.playing` status and every host raised its transport over the next episode), `seekback` (rewind 20 s into the DVR window at t=15, return to the live edge at t=30), `overlapseek` (the #292 seek-window drills below), `pausehold` (Sodalite#104: pause at t=10 and HOLD until ten seconds before the end, printing the playhead, the edge and the resident depth every second, which is how a session paused for longer than its own DVR window is measured without waiting out a real one: pair it with `--dvr-window 30` and `--seconds 90` and the ninety minute question becomes a ninety second run), `still` (#544: asks for a scrub still at three aims, 20 s behind the playhead at t=15, 5 s behind at t=20 and at the edge at t=25, writing each to `aetherctl-still-<tick>.png` in aetherctl's private per-user temporary directory (the path is printed) and reporting hit or MISS with the decode time; pair it with `--sw --dvr-window N`, where the picture comes out of the DVR packet ring rather than a segment cache, and read the FILE as well as the count, because the bundled seed burns its own second into the frame so a still asked for 14.85 s showing `14` is the verdict that it decoded the right moment and not merely an image; exit 6 when nothing hit, 5 when the session ended before the first aim; on a VOD session (AE#605) the three aims are 10.5 s behind the playhead, 4.5 s ahead of it and 600 s past it, through `scrubThumbnail`, and the third is EXPECTED to miss, because a frame the cache does not hold yet must not be answered with the one before it: `--sw` against an HTTP source is the software packet-cache case, and the testsrc fixture's counter in the PNG is the verdict that the still decoded to the target rather than snapping to its keyframe), `stallclock` (AE#549: stop the master clock at t=4 behind the host's back, the way an interrupted audio session does, then call a plain `play()` at t=7 and read whether the playhead moves again; the interruption itself cannot be staged on macOS, its outcome can, and without the `RendererClockResume` branch the run ends with the clock standing exactly where the stall left it, which is the field log's shape; the drill drives DEBUG-only engine hooks, so a Release `aetherctl` prints a notice and ends inconclusive, build it with `swift build --product aetherctl`), `pausereload`, `playreload` and `extplayreload` (#623: force the #93/#65 stage-2 item reload at t=10, on a session paused at t=6, on one left playing, and on one paused through the engine at t=6 and resumed at t=8 straight on the `AVPlayer` the way AVKit's transport does, which leaves the engine's intent reading paused while the player runs; the run fails with exit 4 if the clock moves after the paused reload or stands still after either playing one, and before #623 `pausereload` ended `+7.20 s, state=playing`), and `pauseseek` (pause at t=12, seek at t=15 while paused, resume at t=20; with `--sw` the five paused ticks between landing and resume show what the `[SWDiag]` line reports while the pump is parked and has not heard of the seek, the AE#479 shape); this is how the pre-arming `setRate` wedge was isolated.
 
+`--served-url` prints `SERVED <url>` whenever the session mounts a native item, with the loopback path token in clear. Every other line redacts it, which is right for a log and leaves no way to look at what was actually served. With the URL, `init.mp4` is one `curl` away, and the fMP4 segments are already on disk under `$TMPDIR/aether-segments/<session>/seg-N-M.m4s`: `cat init.mp4 seg-26-27.m4s > s.mp4` is a file `ffprobe -show_packets` reads, which is how AE#684 measured the sound against the picture in the bytes rather than in the log. Fetch the init segment only: a second client asking for the playlist or for segments is a consumer the session then accounts for.
+
 `--seek-every N` seeks once every N ticks past tick 10, walking `--seek-pattern <abs,abs,...>` if one is given (a short backward hop otherwise), and `--seek-count K` stops after K seeks so a run can be a BURST and then play. Both halves are needed for anything about what a seek sequence leaves behind: the burst puts the store in the state under test, and only the playing half shows what the overlay carries through it. That pairing is what made AE#362's second mechanism reproducible (a hole between a restarted pump and the island the previous run left ahead of it, decoded across and then never re-read).
 
 `--host-calls overlapseek` (pair it with `--sw`) runs three drills at t=8, each making a transport call while a seek's demuxer reposition is still in flight, which is the window #254 opened by moving that reposition off the main actor: **A** a second same-target seek (the #292 report: a scrub arriving as two seeks, the second superseding the first), **B** a `pause()`, **C** a `play()` from paused. `seektest` cannot reach any of this because it awaits every seek, so its bursts are strictly serial. Each drill heals the session with pause + play first, so a defect one drill provokes is not inherited by the next, and each reports its own PASS / FAIL / INCONCLUSIVE (`inWindow=NO` means the call arrived after the landing and the run proves nothing). Exit 4 when any drill fails, 5 when any is inconclusive. Before the #292 fix, A and C land the clock at `rate=0.0` while the engine reports `.playing` and B silently keeps playing through the pause.
@@ -715,6 +717,44 @@ entered. The per-tick `edge=` and `behind=` are not usable as a check on that: `
 its first value for the whole run and `behind` is derived from it, with or without `--dvr-window`.
 The stall half needs a field capture or an origin that reproduces the seek, not this table.
 
+### An origin that delivers late (AE#684)
+
+`hlsfixture` publishes on a metronome, and a metronome is the one thing an IPTV origin is not. The defect AE#684 reported only exists when a delivery arrives later than the segment is long, so it could be read off a device log and reproduced nowhere. `Scripts/hls-burst-origin.py` serves a sliding playlist over pre-cut segments and publishes segment k at `end of k - prefill + delays[k % n]`: the MEAN cadence stays the segment duration (the origin never falls behind real time) while the gap between two deliveries follows the cycle. `--freeze-at K --freeze-seconds F` is an outage with the backlog landing at once, `--durs 6,4` alternates segment lengths, and `--rate-kbps` / `--latency-ms` are a link shared by every in-flight response. Its docstring carries the fixture command: 720x576 at 25 fps, 2 s GOPs, 6 s segments, and a white frame plus a 40 ms beep on every whole second, which is what makes the sound measurable against the picture afterwards.
+
+```bash
+Scripts/hls-burst-origin.py --dir seg6 --delays 0,0.3,2.6,0.2,0.6,2.4,0.1,0.5 &
+aetherctl play --live --live-ingest --fast-zap --seconds 180 http://127.0.0.1:8684/live.m3u8
+```
+
+That cycle makes the origin's own gaps run 3.6 to 8.3 s. On the loopback they arrive 3.0 to 9.3 s apart, because the ingest reloads the upstream playlist every half segment and a delivery that just missed a reload waits for the next: **the served window changes once per UPSTREAM segment, up to one and a half of them apart, however finely the engine re-cuts it.** Under `.fastZap` the cut is the 2 s GOP, `max EXTINF` reads 2.000 s, and through 7.25.1 the upstream's 6 s entered only through the cadence floor, as `ceil(6 / 1.5)` = 4. That division is right for a MEASURED gap, which is a robust maximum; a segment duration is the other end of the distribution, the period the source delivers at when nothing is late. So the client's patience (`1.5 x 4` = 6.0 s) was exactly one period, and the 12 s holdback left 2.7 s at the low point of the sawtooth.
+
+What that costs is not the `-12888` itself but what AVPlayer does next: it skips a reload. Measured here and on an Apple TV alike, polls every 2.00 s, then 4.00 s (macOS) or 5.03 s (tvOS) of nothing after the error, and the stall lands inside that hole with the next delivery already listed 1.9 to 2.6 s earlier. Three 180 s runs per arm, arms alternated:
+
+| | sealed | join | `-12888` | `playbackStalled` |
+|---|---|---|---|---|
+| 7.25.1 | TD 4, holdback 12 s | 3 segments | 5 / 4 / 6 | 2 / 2 / 3 |
+| with the upstream segment in the seal | TD 6, holdback 18 s | 4 segments | 0 / 0 / 0 | 0 / 0 / 0 |
+
+Both arms saw the same deliveries (four to six gaps of 9.0 to 9.3 s per run). The seal line states the new term, and the advert is still only reported:
+
+```
+[HLSVideoEngine] live TARGETDURATION sealed at 6s (holdback 18.000s): max EXTINF 2.000s,
+  1.5 x cut target 0.750s, measured floor 6.000s needs 4s of patience,
+  upstream segment 6.000s (one delivery, however finely it is cut here);
+  upstream advertises 6.000s (reported, not used)
+```
+
+Controls and prices, same harness. A 2 s upstream advertising a padded 3 (AE#447's shape) seals 2 and a 6 s holdback in both arms. Alternating 6 s / 4 s segments with under a second of jitter (`--durs 6,4`, the reporting channel's shape) draws one `-12888` and no stall in 180 s before and nothing after, which is why the field capture looks healthy between its outliers. An outage on top (`--freeze-at 14 --freeze-seconds 10`, about 12 s on the loopback) costs 2 to 3 stalls before and the one stall that IS the outage after: 18 s of holdback absorbs lateness, not a freeze longer than its low point of 8.7 s. And the join deepens by one upstream segment wherever a segment is longer than 4 s, which behind a link is one more download before the first picture: `--rate-kbps 8000 --latency-ms 30`, five runs per arm, **3.81 s before and 4.98 s after** (median), the 1.13 MB segment and nothing else. At memory speed it does not show (0.22 to 0.30 s against 0.23 to 0.55 s).
+
+**The same fixture measures sound against picture, in the bytes.** `play --served-url` hands over the init segment, the cache holds the rest, and decoding their concatenation gives the presentation time of every flash and every beep onset: 147 of 148 seconds of a served session read **-0.3 ms** (the very first beep reads +19.7 ms, the decoder starting), across a 12 s outage, with no audio frame of any duration but 1024 samples and no gap at any segment seam. A fresh item re-fetches the same cached segments, so a rebuild cannot change that. What a rebuild does change is which segment the item starts on and where in it, and a segment's sound does not begin where its picture does: the cut is taken on the video keyframe and a transport stream interleaves audio behind video, so on this fixture the sound opens between 11 ms after and 208 ms before the picture, segment by segment. Each item now says what it started on,
+
+```
+[AetherEngine] #684 item #1 starts at its own 4.000s: segment 2 + 0.000s, whose picture
+  opens at 4.000s and whose sound runs 3.979..5.963s (it opens 21 ms before the picture)
+```
+
+and each `live seg-N finalized` line carries `sound=first..last`. The PICTURE half of the question is measurable here: the same origin over a 24 fps twin that carries `Scripts/timecode-fixture.sh`'s block row, `play --picture-probe`, and an outage long enough to close the window (`--freeze-at 14 --freeze-seconds 14`). Four runs, each rebuilt with `#EXT-X-START:TIME-OFFSET=41.95,PRECISE=YES` at `segment 34 + 1.95s`, each fetching seg31 first, whose sound opens 208 ms before its picture: `axisErr` reads +12.000 on all 70 ticks of the first item and +40.000 on all 38 of the rebuilt one, whose playlist begins 28 s later. The picture sits on the item clock to the frame on both, so AVPlayer does not anchor an item on the earliest sample of the first segment it loads, and a mid-segment placement moves nothing on the video side. **What AVPlayer's audio renderer makes of it is not observable from a Mac**: an `MTAudioProcessingTap` on an HLS item is created without error and never called (0 callbacks in 12 s), and capturing the output needs a grant no headless run has. A report of sound and picture drifting apart after a rebuild therefore needs a device, this fixture (a beep that should land on a flash is the one sync test a viewer can read without instruments), and the three lines above it in the log: the `#454 placing` line, the `#684 item` line, and the AE#440 line that says whether the start was forced.
+
 ### The header-enforcing origin (AE#363)
 
 A tokenized IPTV origin refuses anything that arrives without its per-request header, which is a shape none of the fixtures could produce, so neither live client could be driven against one:

From 622d6f6991d39671756eaa3568d8e20b2791d1ef Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 1 Oct 2026 19:12:19 +0200
Subject: [PATCH 270/359] fix(live): the first-serve gate holds the first
 playlist request only (#684)

Every /media.m3u8 request without an _HLS_msn re-enters the first-serve
gate, and AVPlayer opens a session with two of them back to back. With
the cushion satisfied both pass at once. On a fastZap bounded start
(the window under the holdback, served after its grace) the second
request waited out a second grace before init.mp4 was ever asked for.

Measured on a three-segment 6 s upstream: first manifest after 2.012 s,
first picture at 4.47 s; with the gate open once a manifest has gone
out, 2.24 s. This is the "+2.07 s at the picture" AE#594 priced the
bounded start at without naming where it came from.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../Video/VideoSegmentProvider.swift          |  9 +++
 .../Issue684FirstServeLatchTests.swift        | 62 +++++++++++++++++++
 2 files changed, 71 insertions(+)
 create mode 100644 Tests/AetherEngineTests/Issue684FirstServeLatchTests.swift

diff --git a/Sources/AetherEngine/Video/VideoSegmentProvider.swift b/Sources/AetherEngine/Video/VideoSegmentProvider.swift
index 9e7efe057..3e6b33444 100644
--- a/Sources/AetherEngine/Video/VideoSegmentProvider.swift
+++ b/Sources/AetherEngine/Video/VideoSegmentProvider.swift
@@ -639,6 +639,13 @@ final class VideoSegmentProvider: HLSSegmentProvider, @unchecked Sendable {
     /// AE#374: whether the first-serve gate has already reported the interval it held. Read and written
     /// only under `firstSegmentCondition`, inside `waitForFirstLiveSegment` and its two account helpers.
     private var didAccountForFirstServe = false
+    /// AE#684: the gate is a FIRST-serve gate. Every `/media.m3u8` request without an `_HLS_msn`
+    /// re-enters it, and AVPlayer opens a session with two of them back to back, so a bounded start
+    /// (served under the holdback, after its grace) held the second request for a whole second grace:
+    /// measured 2.012 s to the first manifest and 2.02 s more before `init.mp4` was asked for, on
+    /// every shallow start. Once a manifest has gone out, the cushion is the client's to manage.
+    /// Same lock as the flag above.
+    private var firstManifestServed = false
     /// Host override for blocking-reload (`LoadOptions.liveBlockingReload`): nil = auto (observed policy for
     /// ingest, on by default for signal-less live), true/false = force. Wins over the policy (#167).
     private let blockingReloadOverride: Bool?
@@ -2469,6 +2476,7 @@ final class VideoSegmentProvider: HLSSegmentProvider, @unchecked Sendable {
         defer { parkedWaiters -= 1 }
         while true {
             if waitersCancelled { return false }
+            if firstManifestServed { return true }
             let snap = liveCushionSnapshot()
             let target = currentLiveTargetDuration(maxSegmentDuration: snap.maxDuration)
             if LiveEdgePolicy.startupCushionSatisfied(segmentCount: snap.count,
@@ -2551,6 +2559,7 @@ final class VideoSegmentProvider: HLSSegmentProvider, @unchecked Sendable {
         warning: Bool = false,
         note: String? = nil
     ) {
+        firstManifestServed = true
         guard !didAccountForFirstServe else { return }
         didAccountForFirstServe = true
         let account = LiveEdgePolicy.firstServeAccount(
diff --git a/Tests/AetherEngineTests/Issue684FirstServeLatchTests.swift b/Tests/AetherEngineTests/Issue684FirstServeLatchTests.swift
new file mode 100644
index 000000000..438408c63
--- /dev/null
+++ b/Tests/AetherEngineTests/Issue684FirstServeLatchTests.swift
@@ -0,0 +1,62 @@
+// Tests/AetherEngineTests/Issue684FirstServeLatchTests.swift
+// AE#684 review: the first-serve gate held the SECOND playlist request too. AVPlayer opens a session
+// with two `/media.m3u8` requests back to back, each without an `_HLS_msn`, so each re-enters the gate.
+// With the cushion satisfied both pass at once. On a bounded start (the window under the holdback,
+// served after its grace) the second one waited out a second grace: measured on a three-segment 6 s
+// upstream as 2.012 s to the first manifest, then 2.02 s more before `init.mp4`, 4.47 s to the first
+// picture where one grace is 2.24 s.
+import XCTest
+@testable import AetherEngine
+
+final class Issue684FirstServeLatchTests: XCTestCase {
+
+    private func makeProvider() -> (VideoSegmentProvider, SegmentCache) {
+        let cache = SegmentCache(forwardWindow: 10, backwardWindow: 10)
+        let provider = VideoSegmentProvider(
+            cache: cache,
+            segments: [],
+            codecsString: "avc1.4D001E,mp4a.40.2",
+            supplementalCodecs: nil,
+            resolution: (720, 576),
+            videoRange: .sdr,
+            frameRate: 25,
+            hdcpLevel: nil,
+            sourceBitrate: 1_500_000,
+            isLive: true,
+            liveWindowSizing: LiveWindowSizing(targetSegmentDurationSeconds: 0.5, dvrWindowSeconds: nil),
+            allowsBoundedDegradedStart: true
+        )
+        return (provider, cache)
+    }
+
+    private func seconds(_ body: () -> Void) -> Double {
+        let start = DispatchTime.now()
+        body()
+        return Double(DispatchTime.now().uptimeNanoseconds - start.uptimeNanoseconds) / 1_000_000_000
+    }
+
+    /// Two 0.2 s segments against a 3 s holdback: the bounded start, grace 0.5 s.
+    func testASecondRequestIsNotHeldForASecondGrace() {
+        let (provider, cache) = makeProvider()
+        defer { cache.close() }
+        provider.appendLiveSegment(index: 0, startSeconds: 0, durationSeconds: 0.2)
+        provider.appendLiveSegment(index: 1, startSeconds: 0.2, durationSeconds: 0.2)
+
+        var served = false
+        let first = seconds { served = provider.waitForFirstLiveSegment(timeout: 3) }
+        XCTAssertTrue(served)
+        XCTAssertGreaterThanOrEqual(first, 0.45, "the first request pays the grace, as before")
+
+        let second = seconds { served = provider.waitForFirstLiveSegment(timeout: 3) }
+        XCTAssertTrue(served)
+        XCTAssertLessThan(second, 0.2, "a manifest has gone out; the gate is open")
+    }
+
+    /// The latch is on a SERVED manifest. A gate that gave up with nothing cut has served none.
+    func testAnUnservedGateStaysAGate() {
+        let (provider, cache) = makeProvider()
+        defer { cache.close() }
+        XCTAssertFalse(provider.waitForFirstLiveSegment(timeout: 0.1))
+        XCTAssertFalse(provider.waitForFirstLiveSegment(timeout: 0.1))
+    }
+}

From fe3b924c1f8ce2f765c7f1b4a8f0cec9e1f4aa9f Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 1 Oct 2026 19:20:13 +0200
Subject: [PATCH 271/359] fix(native): a not-ready refusal asks again once the
 item is ready (#684)

The readiness sink puts the AE#440 question again when an item becomes
ready, but startLiveJoinImmediatelyIfHolding returns silently while a
buffer reading is in flight. An item that turned ready during that
reading therefore got the stale reading's refusal and nobody asked
again. A refusal taken for readiness now checks the item's status as it
is and asks once more, once per load.

The not-ready refusal no longer falls through to the thin-buffer line,
which printed the same depth as its reason for leaving the wait alone
and spent that line's once-per-load flag. itemIsReadyToPlay is a
required argument, so no caller can decide without stating it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../Native/NativeAVPlayerHost.swift           | 38 ++++++++++++++---
 .../Issue440LiveJoinRollTests.swift           | 42 ++++++++++++-------
 .../Issue684LiveJoinNotReadyTests.swift       | 15 ++++---
 3 files changed, 71 insertions(+), 24 deletions(-)

diff --git a/Sources/AetherEngine/Native/NativeAVPlayerHost.swift b/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
index 52e538717..97ba2adcb 100644
--- a/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
+++ b/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
@@ -93,6 +93,8 @@ final class NativeAVPlayerHost {
     private var liveJoinNoDecisionLogged: Bool = false
     /// AE#684: one line per load for a hold the depth would have cut and the item's status refused.
     private var liveJoinNotReadyLogged: Bool = false
+    /// AE#684: the one repeat a not-ready refusal gets when the item turned ready under it.
+    private var liveJoinNotReadyAskedAgain: Bool = false
     /// AE#440 round 3: one witness per load for a hold that was refused, so the bound is read while the
     /// hold stands and not only at its edges. Observes, never acts (see `startLiveJoinHoldWitness`).
     private var liveJoinHoldWitnessStarted: Bool = false
@@ -476,6 +478,7 @@ final class NativeAVPlayerHost {
         self.liveJoinThinBufferLogged = false
         self.liveJoinNoDecisionLogged = false
         self.liveJoinNotReadyLogged = false
+        self.liveJoinNotReadyAskedAgain = false
         // AE#440 round 4: both of these are per LOAD, and the host is reused across loads on the
         // keepNativeHost path. Left standing, the second live join of a reused host would arm no witness
         // at all and read the previous join's spend reason.
@@ -1289,7 +1292,7 @@ final class NativeAVPlayerHost {
         isWaitingToMinimizeStalls: Bool,
         playbackBufferEmpty: Bool,
         bufferedAheadSeconds: Double,
-        itemIsReadyToPlay: Bool = true
+        itemIsReadyToPlay: Bool
     ) -> Bool {
         guard armed, !alreadySpent, hostWantsToPlay else { return false }
         guard isWaitingToMinimizeStalls else { return false }
@@ -1375,10 +1378,26 @@ final class NativeAVPlayerHost {
                 bufferedAheadSeconds: reading.aheadSeconds,
                 itemIsReadyToPlay: reading.itemStatus == .readyToPlay
             ) else {
-                // AE#684: a refusal the depth alone would have granted says which fact refused it.
-                if let line = Self.liveJoinNotReadyRefusal(reading: reading), !self.liveJoinNotReadyLogged {
-                    self.liveJoinNotReadyLogged = true
-                    EngineLog.emit("[NativeAVPlayerHost] #\(self.sessionID) " + line, category: .engine)
+                // AE#684: a refusal the depth alone would have granted is the item's, not the
+                // cushion's. It has its own line, and the thin-buffer line below would contradict it
+                // (it prints the same depth as the reason for leaving the wait alone).
+                if let line = Self.liveJoinNotReadyRefusal(reading: reading) {
+                    if !self.liveJoinNotReadyLogged {
+                        self.liveJoinNotReadyLogged = true
+                        EngineLog.emit("[NativeAVPlayerHost] #\(self.sessionID) " + line, category: .engine)
+                    }
+                    self.startLiveJoinHoldWitness(item: item)
+                    // The item can turn ready while this reading is in flight. The readiness sink
+                    // asked at that moment and was turned away by the in-flight flag, so the stale
+                    // reading above is the last word unless the question is put again here.
+                    if Self.liveJoinAsksAgainAfterNotReadyRefusal(
+                        itemIsReadyNow: item.status == .readyToPlay,
+                        alreadyAskedAgain: self.liveJoinNotReadyAskedAgain) {
+                        self.liveJoinNotReadyAskedAgain = true
+                        self.startLiveJoinImmediatelyIfHolding(
+                            waitingReason: self.avPlayer.reasonForWaitingToPlay?.rawValue ?? "-")
+                    }
+                    return
                 }
                 // The cushion, not the decision, is what a later report needs: it separates a join
                 // waiting on AVPlayer's rate estimate from one genuinely starved at the edge.
@@ -1689,6 +1708,15 @@ final class NativeAVPlayerHost {
         }
     }
 
+    /// AE#684: whether a not-ready refusal puts the question again. Once per load, and only when the
+    /// item has become ready since the reading was taken: the reading is asynchronous, the readiness
+    /// sink's own question is dropped while one is in flight, and without this a hold that outlives
+    /// readiness on that race is never judged on the playhead it starts from.
+    nonisolated static func liveJoinAsksAgainAfterNotReadyRefusal(itemIsReadyNow: Bool,
+                                                                  alreadyAskedAgain: Bool) -> Bool {
+        itemIsReadyNow && !alreadyAskedAgain
+    }
+
     /// AE#684: the refusal line for a hold that had the depth and not the item. nil for every other
     /// refusal, which the thin-buffer line already accounts for.
     nonisolated static func liveJoinNotReadyRefusal(reading: LiveJoinBufferReading) -> String? {
diff --git a/Tests/AetherEngineTests/Issue440LiveJoinRollTests.swift b/Tests/AetherEngineTests/Issue440LiveJoinRollTests.swift
index 0ba7358d7..2a3f88d41 100644
--- a/Tests/AetherEngineTests/Issue440LiveJoinRollTests.swift
+++ b/Tests/AetherEngineTests/Issue440LiveJoinRollTests.swift
@@ -79,14 +79,16 @@ struct Issue440LiveJoinRollTests {
     func firesOnTheHold() {
         #expect(NativeAVPlayerHost.shouldStartLiveJoinImmediately(
             armed: true, alreadySpent: false, hostWantsToPlay: true,
-            isWaitingToMinimizeStalls: true, playbackBufferEmpty: false, bufferedAheadSeconds: 4.0))
+            isWaitingToMinimizeStalls: true, playbackBufferEmpty: false, bufferedAheadSeconds: 4.0,
+            itemIsReadyToPlay: true))
     }
 
     @Test("never without the opt-in")
     func offByDefault() {
         #expect(!NativeAVPlayerHost.shouldStartLiveJoinImmediately(
             armed: false, alreadySpent: false, hostWantsToPlay: true,
-            isWaitingToMinimizeStalls: true, playbackBufferEmpty: false, bufferedAheadSeconds: 4.0))
+            isWaitingToMinimizeStalls: true, playbackBufferEmpty: false, bufferedAheadSeconds: 4.0,
+            itemIsReadyToPlay: true))
     }
 
     /// One shot, and it belongs to the join. Past it AVPlayer's stall policy is the right one: a live
@@ -95,7 +97,8 @@ struct Issue440LiveJoinRollTests {
     func onceOnly() {
         #expect(!NativeAVPlayerHost.shouldStartLiveJoinImmediately(
             armed: true, alreadySpent: true, hostWantsToPlay: true,
-            isWaitingToMinimizeStalls: true, playbackBufferEmpty: false, bufferedAheadSeconds: 4.0))
+            isWaitingToMinimizeStalls: true, playbackBufferEmpty: false, bufferedAheadSeconds: 4.0,
+            itemIsReadyToPlay: true))
     }
 
     /// An empty buffer is the documented failure shape: `AVPlayer.h` says the call then behaves as if
@@ -104,7 +107,8 @@ struct Issue440LiveJoinRollTests {
     func refusesEmptyBuffer() {
         #expect(!NativeAVPlayerHost.shouldStartLiveJoinImmediately(
             armed: true, alreadySpent: false, hostWantsToPlay: true,
-            isWaitingToMinimizeStalls: true, playbackBufferEmpty: true, bufferedAheadSeconds: 0.0))
+            isWaitingToMinimizeStalls: true, playbackBufferEmpty: true, bufferedAheadSeconds: 0.0,
+            itemIsReadyToPlay: true))
     }
 
     /// `EvaluatingBufferingRate` is the brief monitoring period Apple documents as not worth showing a
@@ -113,7 +117,8 @@ struct Issue440LiveJoinRollTests {
     func refusesEvaluatingReason() {
         #expect(!NativeAVPlayerHost.shouldStartLiveJoinImmediately(
             armed: true, alreadySpent: false, hostWantsToPlay: true,
-            isWaitingToMinimizeStalls: false, playbackBufferEmpty: false, bufferedAheadSeconds: 4.0))
+            isWaitingToMinimizeStalls: false, playbackBufferEmpty: false, bufferedAheadSeconds: 4.0,
+            itemIsReadyToPlay: true))
     }
 
     /// A host that paused during the join asked for a still picture; overriding into motion would
@@ -122,7 +127,8 @@ struct Issue440LiveJoinRollTests {
     func refusesWithoutPlayIntent() {
         #expect(!NativeAVPlayerHost.shouldStartLiveJoinImmediately(
             armed: true, alreadySpent: false, hostWantsToPlay: false,
-            isWaitingToMinimizeStalls: true, playbackBufferEmpty: false, bufferedAheadSeconds: 4.0))
+            isWaitingToMinimizeStalls: true, playbackBufferEmpty: false, bufferedAheadSeconds: 4.0,
+            itemIsReadyToPlay: true))
     }
 
     /// The reason string the host compares against is AVFoundation's own, not a literal of ours.
@@ -142,7 +148,8 @@ struct Issue440LiveJoinRollTests {
             #expect(NativeAVPlayerHost.shouldStartLiveJoinImmediately(
                 armed: true, alreadySpent: false, hostWantsToPlay: true,
                 isWaitingToMinimizeStalls: true, playbackBufferEmpty: false,
-                bufferedAheadSeconds: ahead))
+                bufferedAheadSeconds: ahead,
+            itemIsReadyToPlay: true))
         }
     }
 
@@ -157,7 +164,8 @@ struct Issue440LiveJoinRollTests {
             #expect(!NativeAVPlayerHost.shouldStartLiveJoinImmediately(
                 armed: true, alreadySpent: false, hostWantsToPlay: true,
                 isWaitingToMinimizeStalls: true, playbackBufferEmpty: false,
-                bufferedAheadSeconds: ahead))
+                bufferedAheadSeconds: ahead,
+            itemIsReadyToPlay: true))
         }
     }
 
@@ -166,7 +174,8 @@ struct Issue440LiveJoinRollTests {
         #expect(NativeAVPlayerHost.shouldStartLiveJoinImmediately(
             armed: true, alreadySpent: false, hostWantsToPlay: true,
             isWaitingToMinimizeStalls: true, playbackBufferEmpty: false,
-            bufferedAheadSeconds: NativeAVPlayerHost.minimumLiveJoinBufferAhead))
+            bufferedAheadSeconds: NativeAVPlayerHost.minimumLiveJoinBufferAhead,
+            itemIsReadyToPlay: true))
     }
 
     /// A non-finite reading is an absent one. `currentTime()` on an item that has not resolved yields
@@ -177,11 +186,13 @@ struct Issue440LiveJoinRollTests {
         #expect(!NativeAVPlayerHost.shouldStartLiveJoinImmediately(
             armed: true, alreadySpent: false, hostWantsToPlay: true,
             isWaitingToMinimizeStalls: true, playbackBufferEmpty: false,
-            bufferedAheadSeconds: .nan))
+            bufferedAheadSeconds: .nan,
+            itemIsReadyToPlay: true))
         #expect(!NativeAVPlayerHost.shouldStartLiveJoinImmediately(
             armed: true, alreadySpent: false, hostWantsToPlay: true,
             isWaitingToMinimizeStalls: true, playbackBufferEmpty: false,
-            bufferedAheadSeconds: .infinity))
+            bufferedAheadSeconds: .infinity,
+            itemIsReadyToPlay: true))
     }
 
     /// Both readings have to agree. AVPlayer calling the buffer empty outranks a span that looks deep,
@@ -191,7 +202,8 @@ struct Issue440LiveJoinRollTests {
         #expect(!NativeAVPlayerHost.shouldStartLiveJoinImmediately(
             armed: true, alreadySpent: false, hostWantsToPlay: true,
             isWaitingToMinimizeStalls: true, playbackBufferEmpty: true,
-            bufferedAheadSeconds: 4.0))
+            bufferedAheadSeconds: 4.0,
+            itemIsReadyToPlay: true))
     }
 
     /// The depth is the CONTIGUOUS span ahead of the playhead, not the sum of every loaded range: an
@@ -205,7 +217,8 @@ struct Issue440LiveJoinRollTests {
         #expect(!NativeAVPlayerHost.shouldStartLiveJoinImmediately(
             armed: true, alreadySpent: false, hostWantsToPlay: true,
             isWaitingToMinimizeStalls: true, playbackBufferEmpty: false,
-            bufferedAheadSeconds: ahead))
+            bufferedAheadSeconds: ahead,
+            itemIsReadyToPlay: true))
     }
 
     /// The default is what a host gets without asking, and since 6.55.0 that is on: the device A/B
@@ -272,7 +285,8 @@ struct Issue440LiveJoinRollTests {
             #expect(NativeAVPlayerHost.shouldStartLiveJoinImmediately(
                 armed: true, alreadySpent: false, hostWantsToPlay: true,
                 isWaitingToMinimizeStalls: true, playbackBufferEmpty: empty,
-                bufferedAheadSeconds: ahead) == expected)
+                bufferedAheadSeconds: ahead,
+            itemIsReadyToPlay: true) == expected)
         }
     }
 
diff --git a/Tests/AetherEngineTests/Issue684LiveJoinNotReadyTests.swift b/Tests/AetherEngineTests/Issue684LiveJoinNotReadyTests.swift
index 4edfba43a..6d861b8a8 100644
--- a/Tests/AetherEngineTests/Issue684LiveJoinNotReadyTests.swift
+++ b/Tests/AetherEngineTests/Issue684LiveJoinNotReadyTests.swift
@@ -37,11 +37,16 @@ struct Issue684LiveJoinNotReadyTests {
             itemIsReadyToPlay: true))
     }
 
-    @Test("a caller that states no readiness keeps the decision it had")
-    func defaultIsUnchanged() {
-        #expect(NativeAVPlayerHost.shouldStartLiveJoinImmediately(
-            armed: true, alreadySpent: false, hostWantsToPlay: true,
-            isWaitingToMinimizeStalls: true, playbackBufferEmpty: false, bufferedAheadSeconds: 4.0))
+    /// The reading is asynchronous and the readiness sink's question is dropped while one is in
+    /// flight, so a refusal taken on a stale `unknown` has to notice the item is ready now.
+    @Test("a not-ready refusal asks once more when the item turned ready under it")
+    func asksAgainOnceWhenTheItemTurnedReady() {
+        #expect(NativeAVPlayerHost.liveJoinAsksAgainAfterNotReadyRefusal(
+            itemIsReadyNow: true, alreadyAskedAgain: false))
+        #expect(!NativeAVPlayerHost.liveJoinAsksAgainAfterNotReadyRefusal(
+            itemIsReadyNow: false, alreadyAskedAgain: false))
+        #expect(!NativeAVPlayerHost.liveJoinAsksAgainAfterNotReadyRefusal(
+            itemIsReadyNow: true, alreadyAskedAgain: true))
     }
 
     @Test("the refusal names the playhead the cushion was read from")

From 85ac3cec03f9b9304a72e7ad75b04f9c423e99c6 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 1 Oct 2026 19:20:13 +0200
Subject: [PATCH 272/359] fix(live): a segment finalized without a recorded
 start drops its sound span too (#684)

reportLiveSegmentFinalized returns early when a segment has no recorded
start, and the sound span stored for that index at the cut stayed in
the map for the life of the producer.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 Sources/AetherEngine/Video/HLSSegmentProducer.swift | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Sources/AetherEngine/Video/HLSSegmentProducer.swift b/Sources/AetherEngine/Video/HLSSegmentProducer.swift
index cb016d6c8..4e9839af0 100644
--- a/Sources/AetherEngine/Video/HLSSegmentProducer.swift
+++ b/Sources/AetherEngine/Video/HLSSegmentProducer.swift
@@ -2527,6 +2527,7 @@ final class HLSSegmentProducer: @unchecked Sendable {
 
     private func reportLiveSegmentFinalized(index: Int, nextIndex: Int?) {
         guard let startSeconds = liveSegmentStartByIndex[index] else {
+            liveSegmentSoundByIndex.removeValue(forKey: index)
             EngineLog.emit(
                 "[HLSSegmentProducer] live finalize: no recorded start for seg-\(index); skipping append",
                 category: .session

From 36ebbe2868d68ae393ffadd34826ff3239fdbde1 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 1 Oct 2026 20:30:36 +0200
Subject: [PATCH 273/359] fix(live): the upstream-segment seal is taken as far
 as the join can pay, under a ceiling (#684)

Sealing over the upstream segment asked for a holdback some first
windows cannot hold. An upstream that lists three or four 6 s segments
joins 18 s and cuts 16 (the last GOP stays open until the next
delivery), so against an 18 s holdback the gate waited out the fastZap
grace for content that could not arrive: 4.47 s to first picture where
7.25.1 took 0.18 s. The gate now recognises a join that has handed over
everything it will and seals the largest value its cut content covers,
never under what the seal was without the upstream term: TD 5 there, a
holdback the window holds, first picture 0.19 to 0.22 s. The reader
states what it joined (joinBacklogSeconds) and the seal line says what
was paid of what was asked.

The term is bounded by LiveEdgePolicy.upstreamSegmentSealCeilingSeconds
(10 s): a 20 s segment taken whole would be a holdback as long as the
live-only window, so above the ceiling the seal is what it was. The
same constant is the one switch for 10 s providers (at 6 they seal 7
again, as 7.24.0 did). The join sizes its cushion from both terms.

.standard is pinned: unchanged up to 6 s segments, sealed whole above.
Measured, three 60 s runs per arm and cell, main against this: fastZap
6 s shallow 2 to 3 x -12888 and 1 to 2 stalls -> 1 to 2 x -12888 and no
stall; 10 s shallow window closed and item rebuilt in 4 of 6 runs ->
none; .standard 10 s item rebuilt in 6 of 6 -> none; .standard 6 s on a
deep window first picture 6.3 s -> 0.18 s, on a shallow one unchanged.

The drift line names the upstream-segment term as well.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../AetherEngine/AetherEngine+Loading.swift   |   4 +
 .../IO/HLSIngest/HLSLiveIngestReader.swift    |   7 +
 .../IO/HLSIngest/HLSPlaylistTracker.swift     |   4 +-
 .../IO/HLSIngest/LiveIngestSourceInfo.swift   |  11 +-
 .../AetherEngine/Video/HLSVideoEngine.swift   |   4 +-
 .../Video/LiveCadencePolicy.swift             |  15 ++
 .../Video/VideoSegmentProvider.swift          | 117 +++++++++++++-
 .../HLSPlaylistTrackerTests.swift             |   2 +-
 ...IngestSealCoversUpstreamSegmentTests.swift | 109 ++++++++++++-
 .../Issue684JoinBoundSealTests.swift          | 152 ++++++++++++++++++
 10 files changed, 409 insertions(+), 16 deletions(-)
 create mode 100644 Tests/AetherEngineTests/Issue684JoinBoundSealTests.swift

diff --git a/Sources/AetherEngine/AetherEngine+Loading.swift b/Sources/AetherEngine/AetherEngine+Loading.swift
index 61dbd3823..10259b4b5 100644
--- a/Sources/AetherEngine/AetherEngine+Loading.swift
+++ b/Sources/AetherEngine/AetherEngine+Loading.swift
@@ -788,7 +788,9 @@ extension AetherEngine {
         // served), the advert rides along for the seal log only. Both weak, same reason as above.
         let liveClosedCadenceObservation: (@Sendable () -> Double?)?
         let liveUpstreamSegmentDurationObservation: (@Sendable () -> Double?)?
+        let liveJoinBacklogObservation: (@Sendable () -> Double?)?
         if let liveIngest {
+            liveJoinBacklogObservation = { [weak liveIngest] in liveIngest?.joinBacklogSeconds }
             liveClosedCadenceObservation = { [weak liveIngest] in liveIngest?.closedLiveCadenceSeconds }
             liveUpstreamSegmentDurationObservation = { [weak liveIngest] in
                 liveIngest?.upstreamSegmentDurationSeconds
@@ -796,6 +798,7 @@ extension AetherEngine {
         } else {
             liveClosedCadenceObservation = nil
             liveUpstreamSegmentDurationObservation = nil
+            liveJoinBacklogObservation = nil
         }
         let upstreamSelfReportedTargetDuration = liveIngest?.upstreamTargetDuration
         // #199: in-engine reopen transport for live ingest sessions. Only HLSLiveIngestReader main
@@ -839,6 +842,7 @@ extension AetherEngine {
             liveCadenceObservation: liveCadenceObservation,
             liveClosedCadenceObservation: liveClosedCadenceObservation,
             liveUpstreamSegmentDurationObservation: liveUpstreamSegmentDurationObservation,
+            liveJoinBacklogObservation: liveJoinBacklogObservation,
             upstreamSelfReportedTargetDuration: upstreamSelfReportedTargetDuration,
             preopenedDemuxer: preopenedDemuxer,
             sourceReopenableByURL: !isCustomSource,
diff --git a/Sources/AetherEngine/IO/HLSIngest/HLSLiveIngestReader.swift b/Sources/AetherEngine/IO/HLSIngest/HLSLiveIngestReader.swift
index 905cc990b..6613e5841 100644
--- a/Sources/AetherEngine/IO/HLSIngest/HLSLiveIngestReader.swift
+++ b/Sources/AetherEngine/IO/HLSIngest/HLSLiveIngestReader.swift
@@ -41,6 +41,8 @@ public final class HLSLiveIngestReader: IOReader, LiveIngestSourceInfo, @uncheck
     /// AE#447: longest EXTINF the upstream has actually served, the measured counterpart to
     /// `_upstreamTargetDuration`. Monotonic; read via `upstreamSegmentDurationSeconds`.
     private var _upstreamSegmentDurationSeconds: Double?
+    /// AE#684: summed EXTINF of the join batch. Written with the join line, before its bytes flow.
+    private var _joinBacklogSeconds: Double?
     /// Installed by the resolver before the first FIFO byte; nil = muxed audio.
     private var _companionAudioReader: HLSLiveIngestReader?
     /// AE#359: SUBTITLES renditions of the picked variant, resolved to absolute URLs. Metadata only.
@@ -96,6 +98,10 @@ public final class HLSLiveIngestReader: IOReader, LiveIngestSourceInfo, @uncheck
         startLock.withLock { _upstreamSegmentDurationSeconds }
     }
 
+    var joinBacklogSeconds: Double? {
+        startLock.withLock { _joinBacklogSeconds }
+    }
+
     public var closedLiveCadenceSeconds: Double? {
         startLock.withLock { _cadenceMeter.closedCadence }
     }
@@ -301,6 +307,7 @@ public final class HLSLiveIngestReader: IOReader, LiveIngestSourceInfo, @uncheck
                         startLock.withLock { _joinWallClock = joinDate }
                     }
                     let backlog = fresh.reduce(0.0) { $0 + $1.duration }
+                    startLock.withLock { _joinBacklogSeconds = backlog }
                     EngineLog.emit(
                         "[HLSIngest] joined \(fresh.count) segment(s), ~\(String(format: "%.0f", backlog))s behind the live edge"
                         + " pdt=\(fresh.first?.programDateTime.map { "\($0)" } ?? "nil")",
diff --git a/Sources/AetherEngine/IO/HLSIngest/HLSPlaylistTracker.swift b/Sources/AetherEngine/IO/HLSIngest/HLSPlaylistTracker.swift
index b7e50bede..81be7187d 100644
--- a/Sources/AetherEngine/IO/HLSIngest/HLSPlaylistTracker.swift
+++ b/Sources/AetherEngine/IO/HLSIngest/HLSPlaylistTracker.swift
@@ -36,7 +36,7 @@ struct HLSPlaylistTracker {
 
     /// AE#678: the join has to carry the cushion the loopback's first serve will ask for, or every zap
     /// ends at the bounded start's grace. The served TARGETDURATION is floored by the longest upstream
-    /// segment, the whole of it (AE#684; `ceil(longest / 1.5)` when this was written), so the gate
+    /// segment, the whole of it up to a ceiling (AE#684; `ceil(longest / 1.5)` when this was written), so the gate
     /// wants `3 x` that. The last joined segment's final GOP also stays open downstream until the next
     /// upstream segment arrives, so one GOP of margin on top, bounded by the segment and by
     /// `openGOPMarginSeconds`. A whole segment of margin would be the strict bound, and it is one
@@ -48,7 +48,7 @@ struct HLSPlaylistTracker {
     /// of one upstream segment, which every ordinary delivery overran.
     static func loopbackCushionCoverageSeconds(segments: [HLSMediaSegment]) -> Double {
         guard let longest = segments.map(\.duration).max(), longest > 0 else { return 0 }
-        let targetDuration = LiveEdgePolicy.targetDurationForUpstreamSegment(longest)
+        let targetDuration = LiveEdgePolicy.targetDurationForIngestedSegment(longest)
         return LiveEdgePolicy.holdBackSeconds(targetDuration: targetDuration)
             + min(longest, openGOPMarginSeconds)
     }
diff --git a/Sources/AetherEngine/IO/HLSIngest/LiveIngestSourceInfo.swift b/Sources/AetherEngine/IO/HLSIngest/LiveIngestSourceInfo.swift
index 9bc7fe827..028932395 100644
--- a/Sources/AetherEngine/IO/HLSIngest/LiveIngestSourceInfo.swift
+++ b/Sources/AetherEngine/IO/HLSIngest/LiveIngestSourceInfo.swift
@@ -27,11 +27,16 @@ protocol LiveIngestSourceInfo: AnyObject, Sendable {
     var closedLiveCadenceSeconds: Double? { get }
 
     /// Longest segment duration (EXTINF) the upstream has actually SERVED, nil until the first arrival.
-    /// The measured counterpart to `upstreamTargetDuration`, and the term that keeps the served
-    /// TARGETDURATION honest when a join burst makes the arrival intervals look shorter than the steady
-    /// state ever will be: an upstream cutting 4 s segments cannot sustain a 0.5 s cadence (AE#447).
+    /// The measured counterpart to `upstreamTargetDuration`. Two things are read off it: a bound on
+    /// the steady-state cadence when a join burst makes the arrival intervals look shorter than they
+    /// will ever be (an upstream cutting 4 s segments cannot sustain 0.5 s, AE#447), and the unit the
+    /// source delivers in, which the served TARGETDURATION covers whole (AE#684).
     var upstreamSegmentDurationSeconds: Double? { get }
 
+    /// Summed EXTINF of the segments this reader joined with, nil until it has joined. What the
+    /// first-serve gate measures the cut content against to know the join is spent (AE#684).
+    var joinBacklogSeconds: Double? { get }
+
     /// OBSERVED upstream segment-arrival cadence in seconds (recent max inter-arrival interval, widened by
     /// the currently-open gap), nil until the first arrival. Unlike `upstreamTargetDuration` this reflects
     /// how the origin actually delivers, so the engine can detect bursty relays that advertise a normal
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine.swift b/Sources/AetherEngine/Video/HLSVideoEngine.swift
index af6130939..b2f501ef6 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine.swift
@@ -916,6 +916,7 @@ public final class HLSVideoEngine: @unchecked Sendable {
         liveCadenceObservation: (@Sendable () -> Double?)? = nil,
         liveClosedCadenceObservation: (@Sendable () -> Double?)? = nil,
         liveUpstreamSegmentDurationObservation: (@Sendable () -> Double?)? = nil,
+        liveJoinBacklogObservation: (@Sendable () -> Double?)? = nil,
         upstreamSelfReportedTargetDuration: Double? = nil,
         preopenedDemuxer: Demuxer? = nil,
         sourceReopenableByURL: Bool = true,
@@ -973,7 +974,8 @@ public final class HLSVideoEngine: @unchecked Sendable {
                 observeSealEvidence: {
                     LiveCadenceEvidence(
                         closedCadenceSeconds: liveClosedCadenceObservation?(),
-                        servedSegmentDurationSeconds: liveUpstreamSegmentDurationObservation?()
+                        servedSegmentDurationSeconds: liveUpstreamSegmentDurationObservation?(),
+                        joinBacklogSeconds: liveJoinBacklogObservation?()
                     )
                 },
                 selfReportedTargetDurationSeconds: upstreamSelfReportedTargetDuration
diff --git a/Sources/AetherEngine/Video/LiveCadencePolicy.swift b/Sources/AetherEngine/Video/LiveCadencePolicy.swift
index a11ba7b53..6e4c6290c 100644
--- a/Sources/AetherEngine/Video/LiveCadencePolicy.swift
+++ b/Sources/AetherEngine/Video/LiveCadencePolicy.swift
@@ -7,6 +7,8 @@ struct LiveCadenceEvidence: Sendable, Equatable {
     var closedCadenceSeconds: Double?
     /// Longest segment duration (EXTINF) the upstream has actually served, nil until the first arrival.
     var servedSegmentDurationSeconds: Double?
+    /// AE#684: the media the join took, summed EXTINF, nil until it has joined.
+    var joinBacklogSeconds: Double? = nil
 }
 
 /// Turns the OBSERVED arrival cadence of a live ingest source (`LiveArrivalCadenceMeter`, surfaced by the
@@ -55,6 +57,8 @@ final class LiveCadencePolicy: @unchecked Sendable {
     private var measuredFloorSeconds: Double
     /// AE#684: the served-segment term of that floor, kept apart. Monotonic like the floor.
     private var longestUpstreamSegmentSeconds: Double = 0
+    /// AE#684: what the join took. First value wins: a reopen joins again, and its seal is long taken.
+    private var joinedBacklogSeconds: Double?
 
     /// - Parameters:
     ///   - observe: reader's current `observedLiveCadenceSeconds`; nil until the first upstream arrival.
@@ -100,6 +104,9 @@ final class LiveCadencePolicy: @unchecked Sendable {
                 measuredFloorSeconds = max(measuredFloorSeconds, served)
                 longestUpstreamSegmentSeconds = max(longestUpstreamSegmentSeconds, served)
             }
+            if joinedBacklogSeconds == nil, let joined = evidence.joinBacklogSeconds, joined > 0 {
+                joinedBacklogSeconds = joined
+            }
             if let closed = evidence.closedCadenceSeconds, closed > 0 {
                 measuredFloorSeconds = max(measuredFloorSeconds, closed)
             }
@@ -132,6 +139,14 @@ final class LiveCadencePolicy: @unchecked Sendable {
         return longestUpstreamSegmentSeconds > 0 ? longestUpstreamSegmentSeconds : nil
     }
 
+    /// AE#684 review: the media the join took, so the first-serve gate can tell a join that has
+    /// handed over everything from one still arriving. nil until the reader has joined.
+    var joinBacklogSeconds: Double? {
+        lock.lock(); defer { lock.unlock() }
+        advanceLocked()
+        return joinedBacklogSeconds
+    }
+
     var blockingReloadEnabled: Bool {
         lock.lock(); defer { lock.unlock() }
         advanceLocked()
diff --git a/Sources/AetherEngine/Video/VideoSegmentProvider.swift b/Sources/AetherEngine/Video/VideoSegmentProvider.swift
index 3e6b33444..7ac55d8e8 100644
--- a/Sources/AetherEngine/Video/VideoSegmentProvider.swift
+++ b/Sources/AetherEngine/Video/VideoSegmentProvider.swift
@@ -291,8 +291,62 @@ enum LiveEdgePolicy {
     ///
     /// Re-cutting changes how finely the window is listed, not how often it changes, so the playlist
     /// promises what a playlist of the upstream's segments would: at least their longest duration.
+    ///
+    /// Bounded by `upstreamSegmentSealCeilingSeconds`: above it the term stops growing and
+    /// `targetDurationForCadence` (two thirds of the segment) is the larger one again.
     static func targetDurationForUpstreamSegment(_ segmentSeconds: Double) -> Int {
-        wholeSecondsCovering(segmentSeconds)
+        guard !segmentSeconds.isNaN else { return 0 }
+        return wholeSecondsCovering(Swift.min(segmentSeconds, upstreamSegmentSealCeilingSeconds))
+    }
+
+    /// AE#684: the longest upstream segment the seal takes whole. The ONE place that separates
+    /// "seal over the upstream segment" from "keep `ceil(segment / 1.5)`".
+    ///
+    /// It is a ceiling for two reasons. A holdback is `3 x` the value, and the live-only window is
+    /// 60 s (`LiveWindowSizing.liveOnlyFloorSeconds`): a 20 s segment taken whole would ask the client
+    /// to sit a whole window behind an edge that window can barely list. And the deeper join it buys
+    /// is one more upstream segment before the first picture, which grows with the segment: AE#678
+    /// measured that on a 10 s provider and declined it. At 10, segments up to 10 s seal whole (TD 10,
+    /// 30 s holdback) and a 20 s one seals 14, as it did before. At 6, a 10 s provider seals 7 again,
+    /// exactly as 7.24.0 did, and 6 s providers keep the fix.
+    static let upstreamSegmentSealCeilingSeconds: Double = 10
+
+    /// Everything an ingested segment length asks of the seal, both terms. What the join sizes its
+    /// cushion from, so the two cannot drift.
+    static func targetDurationForIngestedSegment(_ segmentSeconds: Double) -> Int {
+        Swift.max(targetDurationForCadence(segmentSeconds), targetDurationForUpstreamSegment(segmentSeconds))
+    }
+
+    /// AE#684 review: has the join handed over everything it will, bar the segment still open?
+    ///
+    /// The last GOP of a join stays open until the next upstream delivery brings the keyframe that
+    /// closes it, so once the cut content plus one segment reaches what was joined, nothing more
+    /// finalizes before that delivery, and waiting for a deeper cushion is waiting one upstream
+    /// segment of wall clock. The tolerance covers an upstream whose EXTINF and media disagree by a
+    /// frame or two.
+    static func joinIsExhausted(finalizedSeconds: Double, longestCutSegmentSeconds: Double,
+                                joinBacklogSeconds: Double) -> Bool {
+        guard joinBacklogSeconds > 0, finalizedSeconds > 0 else { return false }
+        return finalizedSeconds + longestCutSegmentSeconds + joinExhaustionToleranceSeconds
+            >= joinBacklogSeconds
+    }
+
+    static let joinExhaustionToleranceSeconds: Double = 0.5
+
+    /// AE#684 review: the upstream-segment seal, as far as the join can pay for it.
+    ///
+    /// A seal is a holdback of `3 x` itself, and a holdback the first window cannot hold is not
+    /// protection, it is a start the client spends waiting: an upstream that lists three 6 s segments
+    /// joins 18 s, cuts 16, and against an 18 s holdback took the bounded start after its grace
+    /// (measured 4.25 s to first picture where 7.25.1 took 0.18 s). So an exhausted join seals the
+    /// largest value its cut content covers, never under what the seal was without the upstream
+    /// term and never over the full one: 16 s of window pays for 5, a patience of 7.5 s where the old
+    /// rule gave 6.0 s and the full one 9.0 s.
+    static func targetDurationTheJoinCanPay(full: Int, withoutUpstreamSegment base: Int,
+                                            finalizedSeconds: Double) -> Int {
+        guard finalizedSeconds.isFinite, finalizedSeconds > 0 else { return Swift.max(base, 0) }
+        let affordable = Int((servedSeconds(finalizedSeconds) / 3).rounded(.down))
+        return Swift.max(base, Swift.min(full, affordable))
     }
 
     /// A duration as the playlist actually serves it: `#EXTINF` is written with `%.3f`, so a millisecond
@@ -566,15 +620,35 @@ enum CadenceFloorTerm {
 /// line why the session will hold this value for its whole life. Every term but `selfReported` feeds
 /// the max; `selfReported` is what the upstream CLAIMED, printed beside what was measured.
 struct LiveTargetDurationDerivation {
-    let value: Int
+    var value: Int
     let maxSegmentDuration: Double
     let cutTargetFloor: Double?
     var gopHeadroomApplies = false
     let cadenceFloor: CadenceFloorTerm
     /// AE#684: the longest segment an ingested upstream has served, nil off the ingest path.
     var upstreamSegment: Double? = nil
+    /// AE#684 review: set when the join could not pay for the full upstream-segment seal: what it
+    /// held, what of that is cut, and the value the terms alone would have sealed.
+    var joinBound: (backlogSeconds: Double, finalizedSeconds: Double, full: Int)? = nil
     let selfReported: Double?
 
+    /// The upstream-segment term as both seal lines state it, nil off the ingest path.
+    var upstreamSegmentAccount: String? {
+        guard let upstreamSegment else { return nil }
+        var text = "upstream segment \(LiveEdgePolicy.seconds(upstreamSegment))s "
+            + "(one delivery, however finely it is cut here"
+        if upstreamSegment > LiveEdgePolicy.upstreamSegmentSealCeilingSeconds {
+            text += ", taken up to \(LiveEdgePolicy.seconds(LiveEdgePolicy.upstreamSegmentSealCeilingSeconds))s"
+        }
+        text += ")"
+        if let joinBound {
+            text += ", of which the join pays \(value)s of \(joinBound.full)s "
+                + "(\(LiveEdgePolicy.seconds(joinBound.finalizedSeconds))s cut of the "
+                + "\(LiveEdgePolicy.seconds(joinBound.backlogSeconds))s it held)"
+        }
+        return text
+    }
+
     /// One line, in the order the terms are maxed. Reads as an argument for the number it reports.
     var account: String {
         var terms = ["max EXTINF \(LiveEdgePolicy.seconds(maxSegmentDuration))s"]
@@ -586,10 +660,7 @@ struct LiveTargetDurationDerivation {
                 + "(each segment is one whole GOP)")
         }
         terms.append(cadenceFloor.account)
-        if let upstreamSegment {
-            terms.append("upstream segment \(LiveEdgePolicy.seconds(upstreamSegment))s "
-                + "(one delivery, however finely it is cut here)")
-        }
+        if let upstreamSegmentAccount { terms.append(upstreamSegmentAccount) }
         let claim = selfReported.map {
             "; upstream advertises \(LiveEdgePolicy.seconds($0))s (reported, not used)"
         } ?? ""
@@ -2391,6 +2462,35 @@ final class VideoSegmentProvider: HLSSegmentProvider, @unchecked Sendable {
         )
     }
 
+    /// AE#684 review: the derivation the first-serve gate judges its cushion against, which is the
+    /// full one unless an ingest's join is exhausted short of it
+    /// (`LiveEdgePolicy.targetDurationTheJoinCanPay`). Only the gate asks this: once it has sealed,
+    /// the value is frozen, and a later build's fuller candidate is the drift line's to report.
+    func firstServeTargetDuration(
+        _ snap: (count: Int, summed: Double, maxDuration: Double)
+    ) -> LiveTargetDurationDerivation {
+        var derivation = currentLiveTargetDuration(maxSegmentDuration: snap.maxDuration)
+        guard derivation.upstreamSegment != nil,
+              let backlog = liveCadencePolicy?.joinBacklogSeconds,
+              snap.count >= LiveEdgePolicy.minStartupSegments,
+              LiveEdgePolicy.joinIsExhausted(finalizedSeconds: snap.summed,
+                                             longestCutSegmentSeconds: snap.maxDuration,
+                                             joinBacklogSeconds: backlog)
+        else { return derivation }
+        let base = LiveEdgePolicy.targetDurationSeconds(
+            maxSegmentDuration: snap.maxDuration,
+            cutTargetSeconds: derivation.cutTargetFloor,
+            cadenceFloorSeconds: derivation.cadenceFloor.seconds,
+            segmentsAreCutHere: false,
+            upstreamSegmentSeconds: nil)
+        let paid = LiveEdgePolicy.targetDurationTheJoinCanPay(
+            full: derivation.value, withoutUpstreamSegment: base, finalizedSeconds: snap.summed)
+        guard paid < derivation.value else { return derivation }
+        derivation.joinBound = (backlog, snap.summed, derivation.value)
+        derivation.value = paid
+        return derivation
+    }
+
     /// Takes the seal and, on the call that actually takes it, publishes the derivation. The value is
     /// frozen for the session (RFC 8216 forbids a changing TARGETDURATION, AE#209), so the one line that
     /// explains it has to be emitted here or nowhere: a host reading a 9 s holdback later has no way to
@@ -2420,6 +2520,7 @@ final class VideoSegmentProvider: HLSSegmentProvider, @unchecked Sendable {
                 + "\(resolved.value)s, later candidate \(candidate.value)s "
                 + "(max segment \(String(format: "%.3f", maxSegmentDuration))s, "
                 + candidate.cadenceFloor.account
+                + (candidate.upstreamSegmentAccount.map { ", " + $0 } ?? "")
                 + ")",
                 category: .session
             )
@@ -2478,7 +2579,7 @@ final class VideoSegmentProvider: HLSSegmentProvider, @unchecked Sendable {
             if waitersCancelled { return false }
             if firstManifestServed { return true }
             let snap = liveCushionSnapshot()
-            let target = currentLiveTargetDuration(maxSegmentDuration: snap.maxDuration)
+            let target = firstServeTargetDuration(snap)
             if LiveEdgePolicy.startupCushionSatisfied(segmentCount: snap.count,
                                                        summedDurationSeconds: snap.summed,
                                                        targetDuration: target.value,
@@ -2502,7 +2603,7 @@ final class VideoSegmentProvider: HLSSegmentProvider, @unchecked Sendable {
                 // Re-read after the timed-out wait: an append racing the deadline would otherwise be judged
                 // on the stale snapshot (waitForLiveSegment below already does this).
                 let after = liveCushionSnapshot()
-                let afterTarget = currentLiveTargetDuration(maxSegmentDuration: after.maxDuration)
+                let afterTarget = firstServeTargetDuration(after)
                 if LiveEdgePolicy.startupCushionSatisfied(segmentCount: after.count,
                                                           summedDurationSeconds: after.summed,
                                                           targetDuration: afterTarget.value,
diff --git a/Tests/AetherEngineTests/HLSPlaylistTrackerTests.swift b/Tests/AetherEngineTests/HLSPlaylistTrackerTests.swift
index 7bb667a5c..3a93d8417 100644
--- a/Tests/AetherEngineTests/HLSPlaylistTrackerTests.swift
+++ b/Tests/AetherEngineTests/HLSPlaylistTrackerTests.swift
@@ -171,7 +171,7 @@ final class HLSPlaylistTrackerTests: XCTestCase {
             })
         }
         XCTAssertEqual(coverage([10, 10, 10]), 34)       // TD 10 (AE#684), 30s holdback, 4s margin
-        XCTAssertEqual(coverage([12, 13.5, 12]), 46)     // TD 14 from the longest, 42s + 4s
+        XCTAssertEqual(coverage([12, 13.5, 12]), 34)     // above the 10s ceiling: TD 10, 30s + 4s
         XCTAssertEqual(coverage([2, 2, 2]), 8)           // TD 2, 6s + a 2s GOP bounded by the segment
         XCTAssertEqual(coverage([1, 1, 1]), 4)           // below the 8s floor, which then decides
         XCTAssertEqual(coverage([]), 0)
diff --git a/Tests/AetherEngineTests/Issue684IngestSealCoversUpstreamSegmentTests.swift b/Tests/AetherEngineTests/Issue684IngestSealCoversUpstreamSegmentTests.swift
index e18d76862..a3aa3fbb5 100644
--- a/Tests/AetherEngineTests/Issue684IngestSealCoversUpstreamSegmentTests.swift
+++ b/Tests/AetherEngineTests/Issue684IngestSealCoversUpstreamSegmentTests.swift
@@ -129,10 +129,116 @@ final class Issue684IngestSealCoversUpstreamSegmentTests: XCTestCase {
         XCTAssertEqual(LiveEdgePolicy.targetDurationForUpstreamSegment(6.0000000000000009), 6)
         XCTAssertEqual(LiveEdgePolicy.targetDurationForUpstreamSegment(6.006), 7)
         XCTAssertEqual(LiveEdgePolicy.targetDurationForUpstreamSegment(.infinity),
-                       LiveEdgePolicy.maxCoveredWholeSeconds)
+                       Int(LiveEdgePolicy.upstreamSegmentSealCeilingSeconds))
         XCTAssertEqual(LiveEdgePolicy.targetDurationForUpstreamSegment(.nan), 0)
     }
 
+    // MARK: - `.standard`, which the term reaches above 6 s
+
+    /// `.standard` re-cuts too (4 s cut target), so a provider above its `1.5 x cut target` floor is
+    /// delivered in units longer than anything the floor covers. Measured on a 10 s origin with
+    /// jittered deliveries, three 60 s runs per arm and per window depth: at TD 7 one -12888 and one
+    /// item rebuild in every run, at TD 10 (or 9 where the join pays for no more) neither.
+    func testStandardProfileSealsLongUpstreamSegmentsWhole() {
+        func seal(_ upstream: Double) -> Int {
+            LiveEdgePolicy.targetDurationSeconds(maxSegmentDuration: 4.0,
+                                                 cutTargetSeconds: standardCut,
+                                                 cadenceFloorSeconds: upstream,
+                                                 upstreamSegmentSeconds: upstream)
+        }
+        XCTAssertEqual(seal(4.0), 6, "under the floor: unchanged")
+        XCTAssertEqual(seal(6.0), 6, "at the floor: unchanged")
+        XCTAssertEqual(seal(8.0), 8, "was 6")
+        XCTAssertEqual(seal(10.0), 10, "was 7")
+        XCTAssertEqual(LiveEdgePolicy.holdBackSeconds(targetDuration: seal(10.0)), 30.0, accuracy: 1e-9)
+    }
+
+    // MARK: - The ceiling
+
+    /// A degenerate upstream: a 20 s segment taken whole would be a 60 s holdback, the whole
+    /// live-only window. Above the ceiling the term stops growing and the seal is what it was.
+    func testVeryLongUpstreamSegmentsAreNotTakenWhole() {
+        let ceiling = Int(LiveEdgePolicy.upstreamSegmentSealCeilingSeconds)
+        for upstream in [12.0, 15.0, 20.0, 28.0] {
+            let td = LiveEdgePolicy.targetDurationSeconds(maxSegmentDuration: 2.0,
+                                                          cutTargetSeconds: fastZapCut,
+                                                          cadenceFloorSeconds: upstream,
+                                                          upstreamSegmentSeconds: upstream)
+            XCTAssertEqual(td, max(ceiling, LiveEdgePolicy.targetDurationForCadence(upstream)),
+                           "upstream \(upstream)s")
+            XCTAssertLessThan(LiveEdgePolicy.holdBackSeconds(targetDuration: td),
+                              LiveWindowSizing.liveOnlyFloorSeconds, "upstream \(upstream)s")
+        }
+        XCTAssertEqual(LiveEdgePolicy.targetDurationSeconds(maxSegmentDuration: 2.0,
+                                                            cutTargetSeconds: fastZapCut,
+                                                            cadenceFloorSeconds: 20.0,
+                                                            upstreamSegmentSeconds: 20.0), 14,
+                       "a 20 s segment seals what it sealed before the term existed")
+    }
+
+    /// The term on its own never asks for more than half the live-only window of holdback.
+    func testTheTermAloneStaysWellInsideTheLiveWindow() {
+        let most = LiveEdgePolicy.targetDurationForUpstreamSegment(.greatestFiniteMagnitude)
+        XCTAssertLessThanOrEqual(LiveEdgePolicy.holdBackSeconds(targetDuration: most),
+                                 LiveWindowSizing.liveOnlyFloorSeconds / 2)
+    }
+
+    /// The owner's switch: where the ceiling sits is the whole difference between this fix on 10 s
+    /// providers and 7.24.0's answer (AE#678). Pinned so moving it is a decision and not a side effect.
+    func testCeilingIsTheOneSwitchForLongSegmentProviders() {
+        XCTAssertEqual(LiveEdgePolicy.upstreamSegmentSealCeilingSeconds, 10)
+        XCTAssertEqual(LiveEdgePolicy.targetDurationForIngestedSegment(10.0), 10)
+        XCTAssertEqual(LiveEdgePolicy.targetDurationForCadence(10.0), 7, "what 7.24.0 sealed")
+    }
+
+    /// A fractional segment costs a whole second, like every other term (AE#447 round 2).
+    func testFractionalSegmentCost() {
+        let td = LiveEdgePolicy.targetDurationSeconds(maxSegmentDuration: 2.0,
+                                                      cutTargetSeconds: fastZapCut,
+                                                      cadenceFloorSeconds: 6.006,
+                                                      upstreamSegmentSeconds: 6.006)
+        XCTAssertEqual(td, 7)
+        XCTAssertEqual(LiveEdgePolicy.holdBackSeconds(targetDuration: td), 21.0, accuracy: 1e-9)
+        let coverage = HLSPlaylistTracker.loopbackCushionCoverageSeconds(segments: (0..<8).map { _ in
+            HLSMediaSegment(uri: "s", duration: 6.006, discontinuityBefore: false)
+        })
+        XCTAssertEqual(coverage, 25.0, accuracy: 1e-9, "21 s of holdback and 4 s of open GOP: five segments")
+    }
+
+    // MARK: - As far as the join can pay
+
+    func testAnExhaustedJoinSealsWhatItsWindowCovers() {
+        // Three 6 s segments: 18 s joined, 16 s cut, one 2 s GOP open.
+        XCTAssertEqual(LiveEdgePolicy.targetDurationTheJoinCanPay(
+            full: 6, withoutUpstreamSegment: 4, finalizedSeconds: 16.0), 5)
+        // Three 10 s segments: 28 s cut.
+        XCTAssertEqual(LiveEdgePolicy.targetDurationTheJoinCanPay(
+            full: 10, withoutUpstreamSegment: 7, finalizedSeconds: 28.0), 9)
+        // A join deep enough pays in full.
+        XCTAssertEqual(LiveEdgePolicy.targetDurationTheJoinCanPay(
+            full: 6, withoutUpstreamSegment: 4, finalizedSeconds: 22.0), 6)
+        // Never under what the seal was without the term, however little was joined.
+        XCTAssertEqual(LiveEdgePolicy.targetDurationTheJoinCanPay(
+            full: 6, withoutUpstreamSegment: 4, finalizedSeconds: 10.0), 4)
+        // Total.
+        XCTAssertEqual(LiveEdgePolicy.targetDurationTheJoinCanPay(
+            full: 6, withoutUpstreamSegment: 4, finalizedSeconds: .nan), 4)
+        XCTAssertEqual(LiveEdgePolicy.targetDurationTheJoinCanPay(
+            full: 6, withoutUpstreamSegment: 4, finalizedSeconds: .infinity), 4)
+    }
+
+    func testJoinExhaustionIsTheOpenSegmentAndNothingElse() {
+        XCTAssertTrue(LiveEdgePolicy.joinIsExhausted(
+            finalizedSeconds: 16, longestCutSegmentSeconds: 2, joinBacklogSeconds: 18))
+        XCTAssertFalse(LiveEdgePolicy.joinIsExhausted(
+            finalizedSeconds: 12, longestCutSegmentSeconds: 2, joinBacklogSeconds: 18),
+            "two more GOPs of the join are still to be cut")
+        XCTAssertFalse(LiveEdgePolicy.joinIsExhausted(
+            finalizedSeconds: 0, longestCutSegmentSeconds: 0, joinBacklogSeconds: 18))
+        XCTAssertFalse(LiveEdgePolicy.joinIsExhausted(
+            finalizedSeconds: 16, longestCutSegmentSeconds: 2, joinBacklogSeconds: 0))
+    }
+
     // MARK: - Where the term comes from
 
     /// Measured, not advertised: the longest segment the upstream actually served.
@@ -160,6 +266,7 @@ final class Issue684IngestSealCoversUpstreamSegmentTests: XCTestCase {
         XCTAssertEqual(coverage([6, 6, 6]), 22)     // TD 6, 18 s holdback, 4 s of open GOP
         XCTAssertEqual(coverage([6, 4, 6, 4]), 22)  // the field shape, sealed from the longest
         XCTAssertEqual(coverage([2, 2, 2]), 8)      // AE#447's shape, unchanged
+        XCTAssertEqual(coverage([20, 20, 20]), 46)  // above the ceiling: TD 14, as before the term
     }
 
     // MARK: - The seal says why
diff --git a/Tests/AetherEngineTests/Issue684JoinBoundSealTests.swift b/Tests/AetherEngineTests/Issue684JoinBoundSealTests.swift
new file mode 100644
index 000000000..4de121e82
--- /dev/null
+++ b/Tests/AetherEngineTests/Issue684JoinBoundSealTests.swift
@@ -0,0 +1,152 @@
+// Tests/AetherEngineTests/Issue684JoinBoundSealTests.swift
+// AE#684 review: sealing over the upstream segment made every zap on a SHALLOW upstream window slower.
+// An upstream that lists three 6 s segments joins 18 s; the last GOP stays open until the next upstream
+// delivery, so 16 s are cut, and the 18 s holdback of a TARGETDURATION 6 is not reachable from the join
+// at all. The gate waited out the fastZap grace and served under its own holdback: measured 4.25 s to
+// first picture where 7.25.1 took 0.18 s (2.24 s with the first-serve latch alone). `.standard` has no
+// bounded start and waits for the next upstream segment instead.
+//
+// A join that has handed over everything it will seals the largest value its cut content covers, between
+// what the seal was without the upstream term and the full one.
+import XCTest
+@testable import AetherEngine
+
+private final class JoinedUpstream: @unchecked Sendable {
+    var segmentDuration: Double?
+    var joinBacklog: Double?
+}
+
+final class Issue684JoinBoundSealTests: XCTestCase {
+
+    private func makeProvider(_ upstream: JoinedUpstream, cutTarget: Double,
+                              boundedStart: Bool) -> (VideoSegmentProvider, SegmentCache) {
+        let cache = SegmentCache(forwardWindow: 10, backwardWindow: 10)
+        let policy = LiveCadencePolicy(
+            observe: { 0.1 },
+            cutTargetSeconds: cutTarget,
+            observeSealEvidence: {
+                LiveCadenceEvidence(closedCadenceSeconds: nil,
+                                    servedSegmentDurationSeconds: upstream.segmentDuration,
+                                    joinBacklogSeconds: upstream.joinBacklog)
+            },
+            selfReportedTargetDurationSeconds: upstream.segmentDuration,
+            clock: { 0 }
+        )
+        let provider = VideoSegmentProvider(
+            cache: cache,
+            segments: [],
+            codecsString: "avc1.4D001E,mp4a.40.2",
+            supplementalCodecs: nil,
+            resolution: (720, 576),
+            videoRange: .sdr,
+            frameRate: 25,
+            hdcpLevel: nil,
+            sourceBitrate: 1_500_000,
+            isLive: true,
+            liveWindowSizing: LiveWindowSizing(targetSegmentDurationSeconds: cutTarget, dvrWindowSeconds: nil),
+            allowsBoundedDegradedStart: boundedStart,
+            liveCadencePolicy: policy
+        )
+        return (provider, cache)
+    }
+
+    private func append(_ provider: VideoSegmentProvider, count: Int, each: Double) {
+        for index in 0..<count {
+            provider.appendLiveSegment(index: index, startSeconds: Double(index) * each, durationSeconds: each)
+        }
+    }
+
+    private func seconds(_ body: () -> Void) -> Double {
+        let start = DispatchTime.now()
+        body()
+        return Double(DispatchTime.now().uptimeNanoseconds - start.uptimeNanoseconds) / 1_000_000_000
+    }
+
+    /// The reviewer's shape: three 6 s segments, fastZap, eight 2 s GOPs cut.
+    func testShallowFastZapJoinServesAtOnceOnTheSealItCanPay() {
+        let upstream = JoinedUpstream()
+        upstream.segmentDuration = 6.0
+        upstream.joinBacklog = 18.0
+        let (provider, cache) = makeProvider(upstream, cutTarget: 0.5, boundedStart: true)
+        defer { cache.close() }
+        append(provider, count: 8, each: 2.0)
+
+        var served = false
+        let waited = seconds { served = provider.waitForFirstLiveSegment(timeout: 5) }
+        XCTAssertTrue(served)
+        XCTAssertLessThan(waited, 0.5, "no grace: the join has nothing more to give")
+        let td = provider.liveTargetDurationSeconds(maxSegmentDuration: 2.0)
+        XCTAssertEqual(td, 5, "16 s of window pays for 5, between the old 4 and the full 6")
+        XCTAssertLessThanOrEqual(LiveEdgePolicy.holdBackSeconds(targetDuration: td), 16.0,
+                                 "and the holdback it advertises is one the window holds")
+    }
+
+    /// The same join one upstream segment deeper pays in full.
+    func testDeepJoinKeepsTheFullSeal() {
+        let upstream = JoinedUpstream()
+        upstream.segmentDuration = 6.0
+        upstream.joinBacklog = 24.0
+        let (provider, cache) = makeProvider(upstream, cutTarget: 0.5, boundedStart: true)
+        defer { cache.close() }
+        append(provider, count: 11, each: 2.0)
+        XCTAssertTrue(provider.waitForFirstLiveSegment(timeout: 5))
+        XCTAssertEqual(provider.liveTargetDurationSeconds(maxSegmentDuration: 2.0), 6)
+    }
+
+    /// A join still arriving is not exhausted: the gate keeps waiting for the cushion, as before.
+    func testAJoinStillArrivingIsNotSealedShort() {
+        let upstream = JoinedUpstream()
+        upstream.segmentDuration = 6.0
+        upstream.joinBacklog = 24.0
+        let (provider, cache) = makeProvider(upstream, cutTarget: 0.5, boundedStart: false)
+        defer { cache.close() }
+        append(provider, count: 5, each: 2.0)
+        let derivation = provider.firstServeTargetDuration((count: 5, summed: 10.0, maxDuration: 2.0))
+        XCTAssertEqual(derivation.value, 6)
+        XCTAssertNil(derivation.joinBound)
+    }
+
+    /// `.standard` on a 10 s provider listing three segments: 4 s cuts, 28 s of them. It has no
+    /// bounded start, so without this it waits for the next upstream segment, up to 10 s of wall clock.
+    func testShallowStandardJoinOnTenSecondSegmentsServesAtOnce() {
+        let upstream = JoinedUpstream()
+        upstream.segmentDuration = 10.0
+        upstream.joinBacklog = 30.0
+        let (provider, cache) = makeProvider(upstream, cutTarget: 4.0, boundedStart: false)
+        defer { cache.close() }
+        append(provider, count: 7, each: 4.0)
+
+        var served = false
+        let waited = seconds { served = provider.waitForFirstLiveSegment(timeout: 5) }
+        XCTAssertTrue(served)
+        XCTAssertLessThan(waited, 0.5)
+        XCTAssertEqual(provider.liveTargetDurationSeconds(maxSegmentDuration: 4.0), 9,
+                       "28 s of window pays for 9, between the old 7 and the full 10")
+    }
+
+    /// `.standard` on 6 s segments was at 6 before the term and is at 6 with it: nothing to pay down.
+    func testStandardOnSixSecondSegmentsIsWhatItWas() {
+        let upstream = JoinedUpstream()
+        upstream.segmentDuration = 6.0
+        upstream.joinBacklog = 18.0
+        let (provider, cache) = makeProvider(upstream, cutTarget: 4.0, boundedStart: false)
+        defer { cache.close() }
+        append(provider, count: 4, each: 4.0)
+        let derivation = provider.firstServeTargetDuration((count: 4, summed: 16.0, maxDuration: 4.0))
+        XCTAssertEqual(derivation.value, 6)
+        XCTAssertNil(derivation.joinBound)
+    }
+
+    /// The seal line says what was paid and what was asked, and the drift line names the term too.
+    func testSealAccountStatesWhatTheJoinPaid() {
+        var derivation = LiveTargetDurationDerivation(
+            value: 5, maxSegmentDuration: 2.0, cutTargetFloor: 0.5,
+            cadenceFloor: .measured(6.0), upstreamSegment: 6.0, selfReported: 6.0)
+        derivation.joinBound = (backlogSeconds: 18.0, finalizedSeconds: 16.0, full: 6)
+        let account = derivation.account
+        XCTAssertTrue(account.contains("sealed at 5s (holdback 15.000s)"), account)
+        XCTAssertTrue(account.contains("upstream segment 6.000s"), account)
+        XCTAssertTrue(account.contains("of which the join pays 5s of 6s (16.000s cut of the 18.000s it held)"),
+                      account)
+    }
+}

From 063752189cf54df9f3c2bce12d7f65e839ad82ec Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 1 Oct 2026 20:30:36 +0200
Subject: [PATCH 274/359] docs(live): what the ingest seal does on shallow
 windows, .standard and long segments (#684)

api.md said the term was fastZap's and that long-segment providers were
untouched by the join; both were wrong. It now states the rule for both
profiles, the ceiling, what a join that cannot pay seals instead, the
fractional case, the measured matrix and the cost behind a link. The
"none" of the first measurement is put as what it is: this origin's
number, where the device capture had 10 of 110 gaps above 9 s.

cli.md records where the 4 s of a shallow start went, including the
second grace the gate charged the second playlist request.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/api.md | 55 +++++++++++++++++++++++++++++++++++++++++++++--------
 docs/cli.md | 13 ++++++++++++-
 2 files changed, 59 insertions(+), 9 deletions(-)

diff --git a/docs/api.md b/docs/api.md
index 145fded7b..302743f7a 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -707,12 +707,50 @@ cadence and the holdback follows it down, so the win belongs to the source GOP r
 its runway under either profile. Where the engine cuts the segments itself, each one is a whole GOP and
 the value is sealed from the first few, so it carries `ceil(1.5 x max EXTINF)` of headroom: a broadcast
 whose GOPs run 1.0 to 2.4 s sealed TARGETDURATION 1 on its first three and then broke `EXTINF <= TD`
-on every longer one (AE#670). 1 s GOPs therefore serve TARGETDURATION 2 and a 6 s holdback. An
-ingested HLS upstream is re-cut at its GOPs too, but it still arrives one upstream segment at a
-time, so its floor is the longest segment the upstream has served, whole (AE#684): 2 and a 6 s
-holdback on 2 s segments as before, 6 and 18 s on 6 s ones, where `ceil(6 / 1.5)` used to seal 4 and
-left the client a patience of exactly one delivery. The upstream's advertised target duration is
-still not read.
+on every longer one (AE#670). 1 s GOPs therefore serve TARGETDURATION 2 and a 6 s holdback.
+
+**An ingested HLS upstream seals over the segment it is delivered in, under either profile (AE#684).**
+The engine re-cuts an upstream segment (at its GOPs under `.fastZap`, at about 4 s under `.standard`),
+but the window still changes once per UPSTREAM segment, so the floor is the longest segment the upstream
+has served, whole: 2 and a 6 s holdback on 2 s segments as before, 6 and 18 s on 6 s ones under
+`.fastZap`, where `ceil(6 / 1.5)` used to seal 4 and left the client a patience of exactly one delivery.
+`.standard` already sat at 6 through its `1.5 x cut target` floor, so the term only reaches it above
+6 s: a 10 s provider goes from 7 to 10. The upstream's advertised target duration is still not read.
+Three things bound it:
+
+- **A ceiling.** Segments longer than `LiveEdgePolicy.upstreamSegmentSealCeilingSeconds` (10 s) are not
+  taken whole: a 20 s one seals 14, as it did before, because a holdback is `3 x` the value and the
+  live-only window is 60 s. That constant is also the one place that decides whether 10 s providers get
+  this at all: at 6 they seal 7 again, exactly as 7.24.0 did.
+- **What the join can pay.** A holdback the first window cannot hold is not protection, it is a slow
+  start. An upstream that lists three or four 6 s segments joins 18 s and cuts 16 (the last GOP stays
+  open until the next delivery), so it seals 5, not 6: the largest value whose holdback the window
+  covers, never under what the seal was without the term. The seal line says so (`of which the join
+  pays 5s of 6s (16.000s cut of the 18.000s it held)`). A window deep enough joins one segment more
+  and pays in full.
+- **A whole second per fraction**, like every other term: 6.006 s segments seal 7, a 21 s holdback and
+  a five-segment join.
+
+Measured on loopback against `Scripts/hls-burst-origin.py` (deliveries 3 to 9.3 s apart on 6 s
+segments), 60 s per run, three runs per arm, 7.25.1 against this:
+
+| upstream, profile, window | 7.25.1 | now |
+|---|---|---|
+| 6 s, `.fastZap`, 8 listed | TD 4, first picture 0.18 to 0.20 s, 3 x `-12888` and 2 stalls per run | TD 6, 0.19 to 0.22 s, none |
+| 6 s, `.fastZap`, 3 or 4 listed | TD 4, 0.19 to 0.25 s, 2 to 3 x `-12888`, 1 to 2 stalls | TD 5, 0.19 to 0.22 s, 1 to 2 x `-12888`, no stall |
+| 10 s, `.fastZap`, 8 listed | TD 7, 0.18 to 0.20 s, 1 x `-12888` | TD 10, 0.19 to 0.20 s, none |
+| 10 s, `.fastZap`, 3 or 4 listed | TD 7, 0.18 to 0.21 s, window closed and item rebuilt in 4 of 6 runs | TD 9, 0.18 to 0.20 s, none |
+| 6 s, `.standard`, 8 listed | TD 6, 6.29 to 6.43 s (the join was one segment short of its own holdback) | TD 6, 0.17 to 0.19 s |
+| 6 s, `.standard`, 3 listed | TD 6, 6.23 to 6.41 s | TD 6, 6.27 to 6.37 s (unchanged: nothing to pay down) |
+| 10 s, `.standard`, 3 or 8 listed | TD 7, 0.17 to 0.18 s, item rebuilt in 6 of 6 runs | TD 9 or 10, 0.18 to 0.19 s, none |
+
+What it costs is the join: one more upstream segment before the first picture wherever the window is
+deep enough to offer it and a segment is longer than 4 s. Loopback does not show that. Behind an
+8 Mbit/s link shared by all responses, 1.5 Mbit/s content, median of five: **3.81 s to 4.98 s** on 6 s
+segments and **6.16 s to 8.11 s** on 10 s ones, the segment's bytes over the link rate. And the viewer
+sits one holdback behind the upstream's edge, so 6 s further back on a 6 s provider and 9 s on a 10 s
+one. "None" in the table is a statement about this origin: a real outage longer than the holdback's low
+point still stalls, and the capture that started this had 10 of its 110 delivery gaps above 9 s.
 
 **An HLS source with a window of its own now fills that cushion at the join rather than in wall clock**
 (6.77.0). The ingest used to enter a live playlist three segments behind the edge, and three joined
@@ -723,8 +761,9 @@ short segments is several times three. Measured against `hlsfixture --window 8`
 --fast-zap`, three runs per row: first picture on a 2 s-segment channel **2.22 s before, 0.20 s after**;
 on 1 s segments **0.41 to 1.22 s before, 0.18 to 0.20 s after**, and the spread is the second half of
 the finding, since before the change the number depended on where in the upstream segment cycle the tune
-landed. A window at the three-segment floor has nothing deeper to offer and is unchanged, and so is a
-long-segment provider, whose coverage target was already met inside the old bound. The deeper entry is
+landed. A window at the three-segment floor has nothing deeper to offer and is unchanged. A
+long-segment provider was unchanged by this too, and is not any more: since AE#684 its join is one
+upstream segment deeper, see above. The deeper entry is
 not paid back later: both arms fetch up to the same upstream segment number at the same wall clock, so
 it is caught up at I/O speed instead of becoming a standing lag behind the live edge. What it does not
 touch is a source with no playlist at all (raw MPEG-TS over HTTP), where there is no window to enter
diff --git a/docs/cli.md b/docs/cli.md
index eb81bd74d..757d7f295 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -735,7 +735,7 @@ What that costs is not the `-12888` itself but what AVPlayer does next: it skips
 | 7.25.1 | TD 4, holdback 12 s | 3 segments | 5 / 4 / 6 | 2 / 2 / 3 |
 | with the upstream segment in the seal | TD 6, holdback 18 s | 4 segments | 0 / 0 / 0 | 0 / 0 / 0 |
 
-Both arms saw the same deliveries (four to six gaps of 9.0 to 9.3 s per run). The seal line states the new term, and the advert is still only reported:
+Both arms saw the same deliveries (four to six gaps of 9.0 to 9.3 s per run), and they differ in two things, not one: the sealed value and the join it sizes (three segments against four). Zero is this origin's number, not a promise. Its worst gap is 9.3 s, which a patience of 9.0 s plus one 3 s poll absorbs; the device capture this came from had 10 of its 110 gaps above 9 s and 5 above 12 s, so the field expectation is far fewer `-12888`, not none. The seal line states the new term, and the advert is still only reported:
 
 ```
 [HLSVideoEngine] live TARGETDURATION sealed at 6s (holdback 18.000s): max EXTINF 2.000s,
@@ -746,6 +746,17 @@ Both arms saw the same deliveries (four to six gaps of 9.0 to 9.3 s per run). Th
 
 Controls and prices, same harness. A 2 s upstream advertising a padded 3 (AE#447's shape) seals 2 and a 6 s holdback in both arms. Alternating 6 s / 4 s segments with under a second of jitter (`--durs 6,4`, the reporting channel's shape) draws one `-12888` and no stall in 180 s before and nothing after, which is why the field capture looks healthy between its outliers. An outage on top (`--freeze-at 14 --freeze-seconds 10`, about 12 s on the loopback) costs 2 to 3 stalls before and the one stall that IS the outage after: 18 s of holdback absorbs lateness, not a freeze longer than its low point of 8.7 s. And the join deepens by one upstream segment wherever a segment is longer than 4 s, which behind a link is one more download before the first picture: `--rate-kbps 8000 --latency-ms 30`, five runs per arm, **3.81 s before and 4.98 s after** (median), the 1.13 MB segment and nothing else. At memory speed it does not show (0.22 to 0.30 s against 0.23 to 0.55 s).
 
+**`--window 3` is the arm that keeps a seal honest.** An upstream that lists three or four segments can be joined 18 s deep and no deeper, 16 s of which are cut before the next delivery, so a seal of 6 asks for a holdback the first window cannot hold. Two things were hiding in that start. The gate held the SECOND playlist request as well as the first (AVPlayer opens with two, each re-enters `waitForFirstLiveSegment`, and on a bounded start each waited its own grace: `GET /media.m3u8` at 2.81 s, `GET /init.mp4` at 4.83 s), which is the "+2.07 s at the picture" the AE#594 table above priced without naming; and the grace itself waited for content the join could not deliver. One run per row, 6 s segments, `--window 3 --prefill 3`:
+
+| | sealed | first manifest | first picture |
+|---|---|---|---|
+| 7.25.1 | TD 4 | at once | 0.18 s |
+| the upstream segment taken whole, nothing else | TD 6 | 2.011 s, bounded start after 2.000 s grace | 4.47 s |
+| + the gate opens once a manifest has gone out | TD 6 | 2.011 s, bounded | 2.24 s |
+| + an exhausted join seals what its window covers | TD 5 | at once | 0.32 s |
+
+The full matrix (6 s and 10 s segments, windows of 3, 4 and 8, both profiles, three runs per arm) is in `api.md` under the live join; `.standard` drops `--fast-zap` from the `play` line.
+
 **The same fixture measures sound against picture, in the bytes.** `play --served-url` hands over the init segment, the cache holds the rest, and decoding their concatenation gives the presentation time of every flash and every beep onset: 147 of 148 seconds of a served session read **-0.3 ms** (the very first beep reads +19.7 ms, the decoder starting), across a 12 s outage, with no audio frame of any duration but 1024 samples and no gap at any segment seam. A fresh item re-fetches the same cached segments, so a rebuild cannot change that. What a rebuild does change is which segment the item starts on and where in it, and a segment's sound does not begin where its picture does: the cut is taken on the video keyframe and a transport stream interleaves audio behind video, so on this fixture the sound opens between 11 ms after and 208 ms before the picture, segment by segment. Each item now says what it started on,
 
 ```

From 9a1d9e6d211fa4d616d94a17ab0a9c3e1e4d3390 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 1 Oct 2026 21:11:43 +0200
Subject: [PATCH 275/359] fix(live): the first-serve latch is the ingest's
 alone (#684)

622d6f69 opened the gate for every live session once a manifest had
gone out. On a source the engine cuts itself (raw MPEG-TS under
fastZap) the second request's grace is part of where the session ends
up: without it the first picture comes about 2 s sooner (init.mp4 at
4.1 s instead of 6.1 s on the reviewer's runs) and the session sits up
to 2 s closer to the producing edge for its whole life, which nobody
has measured on a device. That is AE#594's open question, not this
issue's, so that path is back to exactly what 7.25.1 does and only an
ingest session, where the second grace waited for content the join had
already delivered, keeps the latch.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../Video/VideoSegmentProvider.swift          | 16 ++++---
 .../HLSPlaylistTrackerTests.swift             | 10 ++---
 .../Issue684FirstServeLatchTests.swift        | 44 ++++++++++++++-----
 3 files changed, 47 insertions(+), 23 deletions(-)

diff --git a/Sources/AetherEngine/Video/VideoSegmentProvider.swift b/Sources/AetherEngine/Video/VideoSegmentProvider.swift
index 7ac55d8e8..acd1ad757 100644
--- a/Sources/AetherEngine/Video/VideoSegmentProvider.swift
+++ b/Sources/AetherEngine/Video/VideoSegmentProvider.swift
@@ -710,12 +710,11 @@ final class VideoSegmentProvider: HLSSegmentProvider, @unchecked Sendable {
     /// AE#374: whether the first-serve gate has already reported the interval it held. Read and written
     /// only under `firstSegmentCondition`, inside `waitForFirstLiveSegment` and its two account helpers.
     private var didAccountForFirstServe = false
-    /// AE#684: the gate is a FIRST-serve gate. Every `/media.m3u8` request without an `_HLS_msn`
-    /// re-enters it, and AVPlayer opens a session with two of them back to back, so a bounded start
-    /// (served under the holdback, after its grace) held the second request for a whole second grace:
-    /// measured 2.012 s to the first manifest and 2.02 s more before `init.mp4` was asked for, on
-    /// every shallow start. Once a manifest has gone out, the cushion is the client's to manage.
-    /// Same lock as the flag above.
+    /// AE#684: on an ingest the gate is a FIRST-serve gate. Every `/media.m3u8` request without an
+    /// `_HLS_msn` re-enters it, and AVPlayer opens a session with two of them back to back, so a
+    /// bounded start (served under the holdback, after its grace) held the second request for a
+    /// whole second grace: measured 2.012 s to the first manifest and 2.02 s more before `init.mp4`
+    /// was asked for. Read for ingest sessions only (see the gate); same lock as the flag above.
     private var firstManifestServed = false
     /// Host override for blocking-reload (`LoadOptions.liveBlockingReload`): nil = auto (observed policy for
     /// ingest, on by default for signal-less live), true/false = force. Wins over the policy (#167).
@@ -2577,7 +2576,10 @@ final class VideoSegmentProvider: HLSSegmentProvider, @unchecked Sendable {
         defer { parkedWaiters -= 1 }
         while true {
             if waitersCancelled { return false }
-            if firstManifestServed { return true }
+            // Ingest sessions only. A source the engine cuts itself keeps the gate it had: there the
+            // second request's wait is part of where the session ends up behind the producing edge,
+            // which is AE#594's question and not this one's.
+            if firstManifestServed, liveCadencePolicy != nil { return true }
             let snap = liveCushionSnapshot()
             let target = firstServeTargetDuration(snap)
             if LiveEdgePolicy.startupCushionSatisfied(segmentCount: snap.count,
diff --git a/Tests/AetherEngineTests/HLSPlaylistTrackerTests.swift b/Tests/AetherEngineTests/HLSPlaylistTrackerTests.swift
index 3a93d8417..836589b71 100644
--- a/Tests/AetherEngineTests/HLSPlaylistTrackerTests.swift
+++ b/Tests/AetherEngineTests/HLSPlaylistTrackerTests.swift
@@ -155,13 +155,13 @@ final class HLSPlaylistTrackerTests: XCTestCase {
     }
 
     func testDefaultJoinCoversTheLoopbackCushionForLongSegments() {
-        // AE#678, at AE#684's seal: a 6s provider seals TD 6 downstream, so the first serve wants 18s,
-        // and three joined segments finalize only 18s minus the open GOP. The cushion term takes a fourth.
+        // AE#678: a 6s provider seals TD 4 downstream, so the first serve wants 12s, and two joined
+        // segments finalize only 12s minus the open GOP. The cushion term takes a third.
         var tracker = HLSPlaylistTracker()
         let new = tracker.newSegments(
             in: playlist(sequence: 3, uris: ["a", "b", "c", "d", "e", "f"], duration: 6)
         )
-        XCTAssertEqual(new.map(\.uri), ["c", "d", "e", "f"])
+        XCTAssertEqual(new.map(\.uri), ["d", "e", "f"])
     }
 
     func testLoopbackCushionCoverageIsTheSealedHoldbackPlusAGOP() {
@@ -170,8 +170,8 @@ final class HLSPlaylistTrackerTests: XCTestCase {
                 HLSMediaSegment(uri: "s\($0.offset)", duration: $0.element, discontinuityBefore: false)
             })
         }
-        XCTAssertEqual(coverage([10, 10, 10]), 34)       // TD 10 (AE#684), 30s holdback, 4s margin
-        XCTAssertEqual(coverage([12, 13.5, 12]), 34)     // above the 10s ceiling: TD 10, 30s + 4s
+        XCTAssertEqual(coverage([10, 10, 10]), 25)       // TD 7, 21s holdback, 4s margin
+        XCTAssertEqual(coverage([12, 13.5, 12]), 31)     // TD 9 from the longest, 27s + 4s
         XCTAssertEqual(coverage([2, 2, 2]), 8)           // TD 2, 6s + a 2s GOP bounded by the segment
         XCTAssertEqual(coverage([1, 1, 1]), 4)           // below the 8s floor, which then decides
         XCTAssertEqual(coverage([]), 0)
diff --git a/Tests/AetherEngineTests/Issue684FirstServeLatchTests.swift b/Tests/AetherEngineTests/Issue684FirstServeLatchTests.swift
index 438408c63..b3a529335 100644
--- a/Tests/AetherEngineTests/Issue684FirstServeLatchTests.swift
+++ b/Tests/AetherEngineTests/Issue684FirstServeLatchTests.swift
@@ -1,17 +1,22 @@
 // Tests/AetherEngineTests/Issue684FirstServeLatchTests.swift
-// AE#684 review: the first-serve gate held the SECOND playlist request too. AVPlayer opens a session
-// with two `/media.m3u8` requests back to back, each without an `_HLS_msn`, so each re-enters the gate.
-// With the cushion satisfied both pass at once. On a bounded start (the window under the holdback,
-// served after its grace) the second one waited out a second grace: measured on a three-segment 6 s
-// upstream as 2.012 s to the first manifest, then 2.02 s more before `init.mp4`, 4.47 s to the first
-// picture where one grace is 2.24 s.
+// AE#684 review: on an INGEST the first-serve gate held the second playlist request too. AVPlayer opens
+// a session with two `/media.m3u8` requests back to back, each without an `_HLS_msn`, so each re-enters
+// the gate. With the cushion satisfied both pass at once. On a bounded start (the window under the
+// holdback, served after its grace) the second one waited out a second grace: measured on a
+// three-segment 6 s upstream as 2.012 s to the first manifest, then 2.02 s more before `init.mp4`.
+//
+// Scoped to ingest sessions on purpose. On a source the engine cuts itself (raw MPEG-TS) the second
+// grace is part of where the session ends up behind the producing edge: without it the first picture
+// comes 2 s sooner and the session sits up to 2 s closer to the edge for its whole life, which nobody
+// has measured on a device. That is AE#594's open question, so that path behaves as it did in 7.25.1.
 import XCTest
 @testable import AetherEngine
 
 final class Issue684FirstServeLatchTests: XCTestCase {
 
-    private func makeProvider() -> (VideoSegmentProvider, SegmentCache) {
+    private func makeProvider(ingest: Bool) -> (VideoSegmentProvider, SegmentCache) {
         let cache = SegmentCache(forwardWindow: 10, backwardWindow: 10)
+        let policy = ingest ? LiveCadencePolicy(observe: { 0.1 }, cutTargetSeconds: 0.5, clock: { 0 }) : nil
         let provider = VideoSegmentProvider(
             cache: cache,
             segments: [],
@@ -24,7 +29,8 @@ final class Issue684FirstServeLatchTests: XCTestCase {
             sourceBitrate: 1_500_000,
             isLive: true,
             liveWindowSizing: LiveWindowSizing(targetSegmentDurationSeconds: 0.5, dvrWindowSeconds: nil),
-            allowsBoundedDegradedStart: true
+            allowsBoundedDegradedStart: true,
+            liveCadencePolicy: policy
         )
         return (provider, cache)
     }
@@ -36,8 +42,8 @@ final class Issue684FirstServeLatchTests: XCTestCase {
     }
 
     /// Two 0.2 s segments against a 3 s holdback: the bounded start, grace 0.5 s.
-    func testASecondRequestIsNotHeldForASecondGrace() {
-        let (provider, cache) = makeProvider()
+    func testOnAnIngestASecondRequestIsNotHeldForASecondGrace() {
+        let (provider, cache) = makeProvider(ingest: true)
         defer { cache.close() }
         provider.appendLiveSegment(index: 0, startSeconds: 0, durationSeconds: 0.2)
         provider.appendLiveSegment(index: 1, startSeconds: 0.2, durationSeconds: 0.2)
@@ -52,9 +58,25 @@ final class Issue684FirstServeLatchTests: XCTestCase {
         XCTAssertLessThan(second, 0.2, "a manifest has gone out; the gate is open")
     }
 
+    /// A source the engine cuts itself keeps 7.25.1's gate: the second request waits its own grace.
+    func testOnASelfCutSourceTheSecondRequestStillWaitsItsGrace() {
+        let (provider, cache) = makeProvider(ingest: false)
+        defer { cache.close() }
+        provider.appendLiveSegment(index: 0, startSeconds: 0, durationSeconds: 0.2)
+        provider.appendLiveSegment(index: 1, startSeconds: 0.2, durationSeconds: 0.2)
+
+        var served = false
+        let first = seconds { served = provider.waitForFirstLiveSegment(timeout: 3) }
+        XCTAssertTrue(served)
+        XCTAssertGreaterThanOrEqual(first, 0.45)
+        let second = seconds { served = provider.waitForFirstLiveSegment(timeout: 3) }
+        XCTAssertTrue(served)
+        XCTAssertGreaterThanOrEqual(second, 0.45, "unchanged from 7.25.1")
+    }
+
     /// The latch is on a SERVED manifest. A gate that gave up with nothing cut has served none.
     func testAnUnservedGateStaysAGate() {
-        let (provider, cache) = makeProvider()
+        let (provider, cache) = makeProvider(ingest: true)
         defer { cache.close() }
         XCTAssertFalse(provider.waitForFirstLiveSegment(timeout: 0.1))
         XCTAssertFalse(provider.waitForFirstLiveSegment(timeout: 0.1))

From c7cc16682652d72bab16f8a8d82ffd5768c6694e Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 1 Oct 2026 21:11:43 +0200
Subject: [PATCH 276/359] fix(native): a thin reading on a not-ready item asks
 again too (#684)

The re-ask added in fe3b924c only covered a not-ready refusal the depth
would have granted. A reading that was both not-ready and thin took the
thin-buffer branch and returned without asking again, although it is
just as stale: the item it was taken on could not say where it starts.
The readiness of the reading now decides the re-ask, whichever line the
refusal prints.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../Native/NativeAVPlayerHost.swift           | 45 ++++++++++---------
 .../Issue684LiveJoinNotReadyTests.swift       | 21 +++++++--
 2 files changed, 41 insertions(+), 25 deletions(-)

diff --git a/Sources/AetherEngine/Native/NativeAVPlayerHost.swift b/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
index 97ba2adcb..e08afb71a 100644
--- a/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
+++ b/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
@@ -1379,29 +1379,16 @@ final class NativeAVPlayerHost {
                 itemIsReadyToPlay: reading.itemStatus == .readyToPlay
             ) else {
                 // AE#684: a refusal the depth alone would have granted is the item's, not the
-                // cushion's. It has its own line, and the thin-buffer line below would contradict it
-                // (it prints the same depth as the reason for leaving the wait alone).
+                // cushion's. It has its own line, and the thin-buffer line would contradict it (it
+                // prints the same depth as the reason for leaving the wait alone).
                 if let line = Self.liveJoinNotReadyRefusal(reading: reading) {
                     if !self.liveJoinNotReadyLogged {
                         self.liveJoinNotReadyLogged = true
                         EngineLog.emit("[NativeAVPlayerHost] #\(self.sessionID) " + line, category: .engine)
                     }
-                    self.startLiveJoinHoldWitness(item: item)
-                    // The item can turn ready while this reading is in flight. The readiness sink
-                    // asked at that moment and was turned away by the in-flight flag, so the stale
-                    // reading above is the last word unless the question is put again here.
-                    if Self.liveJoinAsksAgainAfterNotReadyRefusal(
-                        itemIsReadyNow: item.status == .readyToPlay,
-                        alreadyAskedAgain: self.liveJoinNotReadyAskedAgain) {
-                        self.liveJoinNotReadyAskedAgain = true
-                        self.startLiveJoinImmediatelyIfHolding(
-                            waitingReason: self.avPlayer.reasonForWaitingToPlay?.rawValue ?? "-")
-                    }
-                    return
-                }
-                // The cushion, not the decision, is what a later report needs: it separates a join
-                // waiting on AVPlayer's rate estimate from one genuinely starved at the edge.
-                if !self.liveJoinThinBufferLogged {
+                } else if !self.liveJoinThinBufferLogged {
+                    // The cushion, not the decision, is what a later report needs: it separates a join
+                    // waiting on AVPlayer's rate estimate from one genuinely starved at the edge.
                     self.liveJoinThinBufferLogged = true
                     EngineLog.emit(
                         "[NativeAVPlayerHost] #\(self.sessionID) AE#440 live join: leaving the "
@@ -1414,6 +1401,18 @@ final class NativeAVPlayerHost {
                     )
                 }
                 self.startLiveJoinHoldWitness(item: item)
+                // The item can turn ready while this reading is in flight. The readiness sink asked
+                // at that moment and was turned away by the in-flight flag, so a reading taken on an
+                // item that could not play yet, thin or deep, is the last word unless the question
+                // is put again here.
+                if Self.liveJoinAsksAgainAfterNotReadyRefusal(
+                    readingWasNotReady: reading.itemStatus != .readyToPlay,
+                    itemIsReadyNow: item.status == .readyToPlay,
+                    alreadyAskedAgain: self.liveJoinNotReadyAskedAgain) {
+                    self.liveJoinNotReadyAskedAgain = true
+                    self.startLiveJoinImmediatelyIfHolding(
+                        waitingReason: self.avPlayer.reasonForWaitingToPlay?.rawValue ?? "-")
+                }
                 return
             }
             self.liveJoinImmediateStartSpent = true
@@ -1708,13 +1707,15 @@ final class NativeAVPlayerHost {
         }
     }
 
-    /// AE#684: whether a not-ready refusal puts the question again. Once per load, and only when the
-    /// item has become ready since the reading was taken: the reading is asynchronous, the readiness
+    /// AE#684: whether a refusal taken on a not-ready item puts the question again, whatever the
+    /// depth it read (a thin reading on such an item is as stale as a deep one). Once per load, and
+    /// only when the item has become ready since the reading was taken: the reading is asynchronous, the readiness
     /// sink's own question is dropped while one is in flight, and without this a hold that outlives
     /// readiness on that race is never judged on the playhead it starts from.
-    nonisolated static func liveJoinAsksAgainAfterNotReadyRefusal(itemIsReadyNow: Bool,
+    nonisolated static func liveJoinAsksAgainAfterNotReadyRefusal(readingWasNotReady: Bool,
+                                                                  itemIsReadyNow: Bool,
                                                                   alreadyAskedAgain: Bool) -> Bool {
-        itemIsReadyNow && !alreadyAskedAgain
+        readingWasNotReady && itemIsReadyNow && !alreadyAskedAgain
     }
 
     /// AE#684: the refusal line for a hold that had the depth and not the item. nil for every other
diff --git a/Tests/AetherEngineTests/Issue684LiveJoinNotReadyTests.swift b/Tests/AetherEngineTests/Issue684LiveJoinNotReadyTests.swift
index 6d861b8a8..866af0ae8 100644
--- a/Tests/AetherEngineTests/Issue684LiveJoinNotReadyTests.swift
+++ b/Tests/AetherEngineTests/Issue684LiveJoinNotReadyTests.swift
@@ -42,11 +42,26 @@ struct Issue684LiveJoinNotReadyTests {
     @Test("a not-ready refusal asks once more when the item turned ready under it")
     func asksAgainOnceWhenTheItemTurnedReady() {
         #expect(NativeAVPlayerHost.liveJoinAsksAgainAfterNotReadyRefusal(
-            itemIsReadyNow: true, alreadyAskedAgain: false))
+            readingWasNotReady: true, itemIsReadyNow: true, alreadyAskedAgain: false))
         #expect(!NativeAVPlayerHost.liveJoinAsksAgainAfterNotReadyRefusal(
-            itemIsReadyNow: false, alreadyAskedAgain: false))
+            readingWasNotReady: true, itemIsReadyNow: false, alreadyAskedAgain: false))
         #expect(!NativeAVPlayerHost.liveJoinAsksAgainAfterNotReadyRefusal(
-            itemIsReadyNow: true, alreadyAskedAgain: true))
+            readingWasNotReady: true, itemIsReadyNow: true, alreadyAskedAgain: true))
+    }
+
+    /// A reading that is both thin and not ready is no less stale than a deep one: the item it was
+    /// taken on could not say where it starts. It keeps the thin-buffer line and still asks again.
+    @Test("a thin reading on a not-ready item asks again too, and a refusal on a ready item does not")
+    func thinAndNotReadyStillAsksAgain() {
+        let thin = NativeAVPlayerHost.LiveJoinBufferReading(
+            bufferEmpty: true, aheadSeconds: 0, playheadSeconds: 48.0,
+            loadedRangeCount: 0, nearestRangeOffsetSeconds: nil, itemStatus: .unknown)
+        #expect(NativeAVPlayerHost.liveJoinNotReadyRefusal(reading: thin) == nil)
+        #expect(NativeAVPlayerHost.liveJoinAsksAgainAfterNotReadyRefusal(
+            readingWasNotReady: thin.itemStatus != .readyToPlay, itemIsReadyNow: true,
+            alreadyAskedAgain: false))
+        #expect(!NativeAVPlayerHost.liveJoinAsksAgainAfterNotReadyRefusal(
+            readingWasNotReady: false, itemIsReadyNow: true, alreadyAskedAgain: false))
     }
 
     @Test("the refusal names the playhead the cushion was read from")

From 611067ab8809de47fb9fe1f49c8d94612b977d2e Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 1 Oct 2026 21:11:43 +0200
Subject: [PATCH 277/359] fix(live): the join keeps its 7.24.0 depth, and a
 spent join is the reader's fact (#684)

Owner's rule: the join is never extended for the upstream-segment
term. loopbackCushionCoverageSeconds is sized from
targetDurationForCadence again, as before this branch, so no zap pays
an extra upstream segment, and the seal rises only as far as what was
joined can pay (targetDurationTheJoinCanPay).

That makes the join-bound seal the path of every ingest start, and its
trigger was arithmetic: cut content plus one segment against the summed
EXTINF, with a 0.5 s tolerance. A playlist whose EXTINF over-reports
its media (6.3 for 6 s, measured in review) never added up, sealed the
full TD 7 with a 21 s holdback and took the bounded start: 2.23 s to
first picture where 7.25.1 took 0.20 s. The reader now states the fact
itself: the whole join batch is committed, its FIFO is empty and its
consumer is parked waiting for the next upstream delivery
(joinIsSpent). The gate has no event for that, so while a join is not
yet spent it looks again every 25 ms.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../AetherEngine/AetherEngine+Loading.swift   |   4 +
 .../AetherEngine/IO/HLSIngest/ByteFIFO.swift  |   8 ++
 .../IO/HLSIngest/HLSLiveIngestReader.swift    |  12 ++
 .../IO/HLSIngest/HLSPlaylistTracker.swift     |  21 +--
 .../IO/HLSIngest/LiveIngestSourceInfo.swift   |  11 +-
 .../AetherEngine/Video/HLSVideoEngine.swift   |   4 +-
 .../Video/LiveCadencePolicy.swift             |  19 ++-
 .../Video/VideoSegmentProvider.swift          |  78 +++++------
 ...IngestSealCoversUpstreamSegmentTests.swift |  49 ++++---
 .../Issue684JoinBoundSealTests.swift          | 124 ++++++++++++++++--
 10 files changed, 230 insertions(+), 100 deletions(-)

diff --git a/Sources/AetherEngine/AetherEngine+Loading.swift b/Sources/AetherEngine/AetherEngine+Loading.swift
index 10259b4b5..cb885a744 100644
--- a/Sources/AetherEngine/AetherEngine+Loading.swift
+++ b/Sources/AetherEngine/AetherEngine+Loading.swift
@@ -789,8 +789,10 @@ extension AetherEngine {
         let liveClosedCadenceObservation: (@Sendable () -> Double?)?
         let liveUpstreamSegmentDurationObservation: (@Sendable () -> Double?)?
         let liveJoinBacklogObservation: (@Sendable () -> Double?)?
+        let liveJoinSpentObservation: (@Sendable () -> Bool?)?
         if let liveIngest {
             liveJoinBacklogObservation = { [weak liveIngest] in liveIngest?.joinBacklogSeconds }
+            liveJoinSpentObservation = { [weak liveIngest] in liveIngest?.joinIsSpent }
             liveClosedCadenceObservation = { [weak liveIngest] in liveIngest?.closedLiveCadenceSeconds }
             liveUpstreamSegmentDurationObservation = { [weak liveIngest] in
                 liveIngest?.upstreamSegmentDurationSeconds
@@ -799,6 +801,7 @@ extension AetherEngine {
             liveClosedCadenceObservation = nil
             liveUpstreamSegmentDurationObservation = nil
             liveJoinBacklogObservation = nil
+            liveJoinSpentObservation = nil
         }
         let upstreamSelfReportedTargetDuration = liveIngest?.upstreamTargetDuration
         // #199: in-engine reopen transport for live ingest sessions. Only HLSLiveIngestReader main
@@ -843,6 +846,7 @@ extension AetherEngine {
             liveClosedCadenceObservation: liveClosedCadenceObservation,
             liveUpstreamSegmentDurationObservation: liveUpstreamSegmentDurationObservation,
             liveJoinBacklogObservation: liveJoinBacklogObservation,
+            liveJoinSpentObservation: liveJoinSpentObservation,
             upstreamSelfReportedTargetDuration: upstreamSelfReportedTargetDuration,
             preopenedDemuxer: preopenedDemuxer,
             sourceReopenableByURL: !isCustomSource,
diff --git a/Sources/AetherEngine/IO/HLSIngest/ByteFIFO.swift b/Sources/AetherEngine/IO/HLSIngest/ByteFIFO.swift
index 625fe2f58..7ee1e936b 100644
--- a/Sources/AetherEngine/IO/HLSIngest/ByteFIFO.swift
+++ b/Sources/AetherEngine/IO/HLSIngest/ByteFIFO.swift
@@ -27,6 +27,14 @@ final class ByteFIFO: @unchecked Sendable {
         return parked
     }
 
+    /// AE#684: nothing queued and a caller waiting for more. A writer only parks at capacity, so with
+    /// the queue empty the parked caller is the reader, and everything written so far is consumed.
+    var isEmptyWithReaderParked: Bool {
+        condition.lock()
+        defer { condition.unlock() }
+        return queue.isEmpty && parked > 0 && !finished && !cancelled
+    }
+
     init(capacity: Int) {
         self.capacity = capacity
     }
diff --git a/Sources/AetherEngine/IO/HLSIngest/HLSLiveIngestReader.swift b/Sources/AetherEngine/IO/HLSIngest/HLSLiveIngestReader.swift
index 6613e5841..11fbbb822 100644
--- a/Sources/AetherEngine/IO/HLSIngest/HLSLiveIngestReader.swift
+++ b/Sources/AetherEngine/IO/HLSIngest/HLSLiveIngestReader.swift
@@ -43,6 +43,9 @@ public final class HLSLiveIngestReader: IOReader, LiveIngestSourceInfo, @uncheck
     private var _upstreamSegmentDurationSeconds: Double?
     /// AE#684: summed EXTINF of the join batch. Written with the join line, before its bytes flow.
     private var _joinBacklogSeconds: Double?
+    /// AE#684: the join batch has been committed to the FIFO in full / has been seen consumed.
+    private var _joinBatchCommitted = false
+    private var _joinSpent = false
     /// Installed by the resolver before the first FIFO byte; nil = muxed audio.
     private var _companionAudioReader: HLSLiveIngestReader?
     /// AE#359: SUBTITLES renditions of the picked variant, resolved to absolute URLs. Metadata only.
@@ -102,6 +105,14 @@ public final class HLSLiveIngestReader: IOReader, LiveIngestSourceInfo, @uncheck
         startLock.withLock { _joinBacklogSeconds }
     }
 
+    var joinIsSpent: Bool {
+        let (spent, committed) = startLock.withLock { (_joinSpent, _joinBatchCommitted) }
+        if spent { return true }
+        guard committed, fifo.isEmptyWithReaderParked else { return false }
+        startLock.withLock { _joinSpent = true }
+        return true
+    }
+
     public var closedLiveCadenceSeconds: Double? {
         startLock.withLock { _cadenceMeter.closedCadence }
     }
@@ -319,6 +330,7 @@ public final class HLSLiveIngestReader: IOReader, LiveIngestSourceInfo, @uncheck
                     guard try await ingestSegmentBatch(fresh, mediaURL: mediaURL) else {
                         return // FIFO closed underneath us
                     }
+                    if isJoin { startLock.withLock { _joinBatchCommitted = true } }
                 }
 
                 if media.hasEndList {
diff --git a/Sources/AetherEngine/IO/HLSIngest/HLSPlaylistTracker.swift b/Sources/AetherEngine/IO/HLSIngest/HLSPlaylistTracker.swift
index 81be7187d..5d0f18c3c 100644
--- a/Sources/AetherEngine/IO/HLSIngest/HLSPlaylistTracker.swift
+++ b/Sources/AetherEngine/IO/HLSIngest/HLSPlaylistTracker.swift
@@ -36,19 +36,20 @@ struct HLSPlaylistTracker {
 
     /// AE#678: the join has to carry the cushion the loopback's first serve will ask for, or every zap
     /// ends at the bounded start's grace. The served TARGETDURATION is floored by the longest upstream
-    /// segment, the whole of it up to a ceiling (AE#684; `ceil(longest / 1.5)` when this was written), so the gate
-    /// wants `3 x` that. The last joined segment's final GOP also stays open downstream until the next
-    /// upstream segment arrives, so one GOP of margin on top, bounded by the segment and by
-    /// `openGOPMarginSeconds`. A whole segment of margin would be the strict bound, and it is one
-    /// download more than the start needs.
+    /// segment (`ceil(longest / 1.5)`, AE#447), so the gate wants `3 x` that, and `1.5 x TD` alone is
+    /// always a hair short of it: two 10 s segments are 20 s against a 21 s holdback. The last joined
+    /// segment's final GOP also stays open downstream until the next upstream segment arrives, so one
+    /// GOP of margin on top, bounded by the segment and by `openGOPMarginSeconds`. A whole segment of
+    /// margin would be the strict bound, and on a 10 s provider it is a fourth 10 s download the start
+    /// then waits for on a shared link (measured 3.7 s to first picture against 40 Mbit/s).
     ///
-    /// The depth is four upstream segments wherever a segment is longer than the margin. AE#678 measured
-    /// the fourth on a 10 s provider at 3.7 s to first picture against 2.8 s on a 40 Mbit/s link and
-    /// declined it as MARGIN. AE#684 takes it as HOLDBACK: the three it kept left the client a patience
-    /// of one upstream segment, which every ordinary delivery overran.
+    /// AE#684: the seal now also covers the upstream segment whole, and this coverage deliberately
+    /// does NOT follow it. A join one segment deeper is one more download before the first picture on
+    /// every zap (the fourth segment AE#678 declined above), so the join keeps this depth and the seal
+    /// rises only as far as what was joined can pay (`LiveEdgePolicy.targetDurationTheJoinCanPay`).
     static func loopbackCushionCoverageSeconds(segments: [HLSMediaSegment]) -> Double {
         guard let longest = segments.map(\.duration).max(), longest > 0 else { return 0 }
-        let targetDuration = LiveEdgePolicy.targetDurationForIngestedSegment(longest)
+        let targetDuration = LiveEdgePolicy.targetDurationForCadence(longest)
         return LiveEdgePolicy.holdBackSeconds(targetDuration: targetDuration)
             + min(longest, openGOPMarginSeconds)
     }
diff --git a/Sources/AetherEngine/IO/HLSIngest/LiveIngestSourceInfo.swift b/Sources/AetherEngine/IO/HLSIngest/LiveIngestSourceInfo.swift
index 028932395..5f131952d 100644
--- a/Sources/AetherEngine/IO/HLSIngest/LiveIngestSourceInfo.swift
+++ b/Sources/AetherEngine/IO/HLSIngest/LiveIngestSourceInfo.swift
@@ -33,10 +33,17 @@ protocol LiveIngestSourceInfo: AnyObject, Sendable {
     /// source delivers in, which the served TARGETDURATION covers whole (AE#684).
     var upstreamSegmentDurationSeconds: Double? { get }
 
-    /// Summed EXTINF of the segments this reader joined with, nil until it has joined. What the
-    /// first-serve gate measures the cut content against to know the join is spent (AE#684).
+    /// Summed EXTINF of the segments this reader joined with, nil until it has joined. Reported in
+    /// the seal line; nothing is decided from it, because an upstream's EXTINF and its media need
+    /// not agree (AE#684).
     var joinBacklogSeconds: Double? { get }
 
+    /// Whether the join has been handed over in full AND consumed: every byte of the join batch has
+    /// been committed to the reader, the reader is empty, and its consumer is parked waiting for the
+    /// next upstream delivery. From then on nothing more can be cut until that delivery, which is
+    /// what the first-serve gate needs to know before it waits for a deeper cushion (AE#684).
+    var joinIsSpent: Bool { get }
+
     /// OBSERVED upstream segment-arrival cadence in seconds (recent max inter-arrival interval, widened by
     /// the currently-open gap), nil until the first arrival. Unlike `upstreamTargetDuration` this reflects
     /// how the origin actually delivers, so the engine can detect bursty relays that advertise a normal
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine.swift b/Sources/AetherEngine/Video/HLSVideoEngine.swift
index b2f501ef6..a7b670501 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine.swift
@@ -917,6 +917,7 @@ public final class HLSVideoEngine: @unchecked Sendable {
         liveClosedCadenceObservation: (@Sendable () -> Double?)? = nil,
         liveUpstreamSegmentDurationObservation: (@Sendable () -> Double?)? = nil,
         liveJoinBacklogObservation: (@Sendable () -> Double?)? = nil,
+        liveJoinSpentObservation: (@Sendable () -> Bool?)? = nil,
         upstreamSelfReportedTargetDuration: Double? = nil,
         preopenedDemuxer: Demuxer? = nil,
         sourceReopenableByURL: Bool = true,
@@ -975,7 +976,8 @@ public final class HLSVideoEngine: @unchecked Sendable {
                     LiveCadenceEvidence(
                         closedCadenceSeconds: liveClosedCadenceObservation?(),
                         servedSegmentDurationSeconds: liveUpstreamSegmentDurationObservation?(),
-                        joinBacklogSeconds: liveJoinBacklogObservation?()
+                        joinBacklogSeconds: liveJoinBacklogObservation?(),
+                        joinIsSpent: liveJoinSpentObservation?()
                     )
                 },
                 selfReportedTargetDurationSeconds: upstreamSelfReportedTargetDuration
diff --git a/Sources/AetherEngine/Video/LiveCadencePolicy.swift b/Sources/AetherEngine/Video/LiveCadencePolicy.swift
index 6e4c6290c..8b97338ab 100644
--- a/Sources/AetherEngine/Video/LiveCadencePolicy.swift
+++ b/Sources/AetherEngine/Video/LiveCadencePolicy.swift
@@ -9,6 +9,9 @@ struct LiveCadenceEvidence: Sendable, Equatable {
     var servedSegmentDurationSeconds: Double?
     /// AE#684: the media the join took, summed EXTINF, nil until it has joined.
     var joinBacklogSeconds: Double? = nil
+    /// AE#684: the reader has handed over the whole join and its consumer is waiting on it for more.
+    /// nil where nothing can say.
+    var joinIsSpent: Bool? = nil
 }
 
 /// Turns the OBSERVED arrival cadence of a live ingest source (`LiveArrivalCadenceMeter`, surfaced by the
@@ -59,6 +62,8 @@ final class LiveCadencePolicy: @unchecked Sendable {
     private var longestUpstreamSegmentSeconds: Double = 0
     /// AE#684: what the join took. First value wins: a reopen joins again, and its seal is long taken.
     private var joinedBacklogSeconds: Double?
+    /// AE#684: latched once true, so a later delivery that fills the reader again cannot unspend it.
+    private var joinSpent: Bool?
 
     /// - Parameters:
     ///   - observe: reader's current `observedLiveCadenceSeconds`; nil until the first upstream arrival.
@@ -107,6 +112,9 @@ final class LiveCadencePolicy: @unchecked Sendable {
             if joinedBacklogSeconds == nil, let joined = evidence.joinBacklogSeconds, joined > 0 {
                 joinedBacklogSeconds = joined
             }
+            if let spent = evidence.joinIsSpent, joinSpent != true {
+                joinSpent = spent
+            }
             if let closed = evidence.closedCadenceSeconds, closed > 0 {
                 measuredFloorSeconds = max(measuredFloorSeconds, closed)
             }
@@ -139,8 +147,15 @@ final class LiveCadencePolicy: @unchecked Sendable {
         return longestUpstreamSegmentSeconds > 0 ? longestUpstreamSegmentSeconds : nil
     }
 
-    /// AE#684 review: the media the join took, so the first-serve gate can tell a join that has
-    /// handed over everything from one still arriving. nil until the reader has joined.
+    /// AE#684: whether the join has been handed over and consumed, bar the GOP the next upstream
+    /// delivery will close. A fact from the reader, nil where there is none to ask.
+    var joinIsSpent: Bool? {
+        lock.lock(); defer { lock.unlock() }
+        advanceLocked()
+        return joinSpent
+    }
+
+    /// AE#684: the media the join listed (summed EXTINF), for the seal line. nil until it has joined.
     var joinBacklogSeconds: Double? {
         lock.lock(); defer { lock.unlock() }
         advanceLocked()
diff --git a/Sources/AetherEngine/Video/VideoSegmentProvider.swift b/Sources/AetherEngine/Video/VideoSegmentProvider.swift
index acd1ad757..ecd2ed787 100644
--- a/Sources/AetherEngine/Video/VideoSegmentProvider.swift
+++ b/Sources/AetherEngine/Video/VideoSegmentProvider.swift
@@ -299,49 +299,31 @@ enum LiveEdgePolicy {
         return wholeSecondsCovering(Swift.min(segmentSeconds, upstreamSegmentSealCeilingSeconds))
     }
 
-    /// AE#684: the longest upstream segment the seal takes whole. The ONE place that separates
-    /// "seal over the upstream segment" from "keep `ceil(segment / 1.5)`".
-    ///
-    /// It is a ceiling for two reasons. A holdback is `3 x` the value, and the live-only window is
-    /// 60 s (`LiveWindowSizing.liveOnlyFloorSeconds`): a 20 s segment taken whole would ask the client
-    /// to sit a whole window behind an edge that window can barely list. And the deeper join it buys
-    /// is one more upstream segment before the first picture, which grows with the segment: AE#678
-    /// measured that on a 10 s provider and declined it. At 10, segments up to 10 s seal whole (TD 10,
-    /// 30 s holdback) and a 20 s one seals 14, as it did before. At 6, a 10 s provider seals 7 again,
-    /// exactly as 7.24.0 did, and 6 s providers keep the fix.
+    /// AE#684: the longest upstream segment the seal takes whole.
+    ///
+    /// A holdback is `3 x` the value, and the live-only window is 60 s
+    /// (`LiveWindowSizing.liveOnlyFloorSeconds`): a 20 s segment taken whole would ask the client to
+    /// sit a whole window behind an edge that window can barely list. At 10, segments up to 10 s are
+    /// asked for whole and a 20 s one seals 14, as it did before the term existed. What is asked for
+    /// is then paid only as far as the join reaches (`targetDurationTheJoinCanPay`), and the join is
+    /// not deepened for it, so in practice a 10 s provider lands at 9.
     static let upstreamSegmentSealCeilingSeconds: Double = 10
 
-    /// Everything an ingested segment length asks of the seal, both terms. What the join sizes its
-    /// cushion from, so the two cannot drift.
-    static func targetDurationForIngestedSegment(_ segmentSeconds: Double) -> Int {
-        Swift.max(targetDurationForCadence(segmentSeconds), targetDurationForUpstreamSegment(segmentSeconds))
-    }
-
-    /// AE#684 review: has the join handed over everything it will, bar the segment still open?
-    ///
-    /// The last GOP of a join stays open until the next upstream delivery brings the keyframe that
-    /// closes it, so once the cut content plus one segment reaches what was joined, nothing more
-    /// finalizes before that delivery, and waiting for a deeper cushion is waiting one upstream
-    /// segment of wall clock. The tolerance covers an upstream whose EXTINF and media disagree by a
-    /// frame or two.
-    static func joinIsExhausted(finalizedSeconds: Double, longestCutSegmentSeconds: Double,
-                                joinBacklogSeconds: Double) -> Bool {
-        guard joinBacklogSeconds > 0, finalizedSeconds > 0 else { return false }
-        return finalizedSeconds + longestCutSegmentSeconds + joinExhaustionToleranceSeconds
-            >= joinBacklogSeconds
-    }
-
-    static let joinExhaustionToleranceSeconds: Double = 0.5
-
-    /// AE#684 review: the upstream-segment seal, as far as the join can pay for it.
+    /// AE#684: the upstream-segment seal, as far as the join can pay for it.
     ///
     /// A seal is a holdback of `3 x` itself, and a holdback the first window cannot hold is not
-    /// protection, it is a start the client spends waiting: an upstream that lists three 6 s segments
-    /// joins 18 s, cuts 16, and against an 18 s holdback took the bounded start after its grace
-    /// (measured 4.25 s to first picture where 7.25.1 took 0.18 s). So an exhausted join seals the
-    /// largest value its cut content covers, never under what the seal was without the upstream
-    /// term and never over the full one: 16 s of window pays for 5, a patience of 7.5 s where the old
-    /// rule gave 6.0 s and the full one 9.0 s.
+    /// protection, it is a start the client spends waiting. The join is three upstream segments on
+    /// anything longer than about 5 s and stays that deep (one more would be one more download on
+    /// every zap, AE#678), and its last GOP stays open until the next upstream delivery: three 6 s
+    /// segments are 18 s joined and 16 s cut, against the 18 s a seal of 6 asks for. So once the
+    /// reader has handed the whole join over and the cutter has nothing left to read, the seal is the
+    /// largest value that cut content covers, never under what it was without the upstream term and
+    /// never over the full one: 16 s pays for 5 (patience 7.5 s where the old rule gave 6.0 s), 28 s
+    /// of a 10 s provider for 9.
+    ///
+    /// Whether the join is spent is a FACT the reader states (`joinIsSpent`), not arithmetic on
+    /// EXTINF: a playlist that rounds its durations up (6.3 for 6 s of media) never adds up to what
+    /// was cut, and a tolerance on the sum decided every such start wrongly.
     static func targetDurationTheJoinCanPay(full: Int, withoutUpstreamSegment base: Int,
                                             finalizedSeconds: Double) -> Int {
         guard finalizedSeconds.isFinite, finalizedSeconds > 0 else { return Swift.max(base, 0) }
@@ -644,7 +626,7 @@ struct LiveTargetDurationDerivation {
         if let joinBound {
             text += ", of which the join pays \(value)s of \(joinBound.full)s "
                 + "(\(LiveEdgePolicy.seconds(joinBound.finalizedSeconds))s cut of the "
-                + "\(LiveEdgePolicy.seconds(joinBound.backlogSeconds))s it held)"
+                + "\(LiveEdgePolicy.seconds(joinBound.backlogSeconds))s it listed)"
         }
         return text
     }
@@ -2470,12 +2452,10 @@ final class VideoSegmentProvider: HLSSegmentProvider, @unchecked Sendable {
     ) -> LiveTargetDurationDerivation {
         var derivation = currentLiveTargetDuration(maxSegmentDuration: snap.maxDuration)
         guard derivation.upstreamSegment != nil,
-              let backlog = liveCadencePolicy?.joinBacklogSeconds,
               snap.count >= LiveEdgePolicy.minStartupSegments,
-              LiveEdgePolicy.joinIsExhausted(finalizedSeconds: snap.summed,
-                                             longestCutSegmentSeconds: snap.maxDuration,
-                                             joinBacklogSeconds: backlog)
+              liveCadencePolicy?.joinIsSpent == true
         else { return derivation }
+        let backlog = liveCadencePolicy?.joinBacklogSeconds ?? 0
         let base = LiveEdgePolicy.targetDurationSeconds(
             maxSegmentDuration: snap.maxDuration,
             cutTargetSeconds: derivation.cutTargetFloor,
@@ -2600,7 +2580,12 @@ final class VideoSegmentProvider: HLSSegmentProvider, @unchecked Sendable {
                 degradedGrace = grace
                 degradedDeadline = Date().addingTimeInterval(grace)
             }
-            let effectiveDeadline = degradedDeadline.map { min(deadline, $0) } ?? deadline
+            var effectiveDeadline = degradedDeadline.map { min(deadline, $0) } ?? deadline
+            // AE#684: a join becomes spent when the cutter parks on an empty reader, which is no
+            // event this condition hears. While that is still to come, look again shortly.
+            if liveCadencePolicy?.joinIsSpent == false {
+                effectiveDeadline = min(effectiveDeadline, Date().addingTimeInterval(Self.joinSpentPollSeconds))
+            }
             if !firstSegmentCondition.wait(until: effectiveDeadline) {
                 // Re-read after the timed-out wait: an append racing the deadline would otherwise be judged
                 // on the stale snapshot (waitForLiveSegment below already does this).
@@ -2650,6 +2635,9 @@ final class VideoSegmentProvider: HLSSegmentProvider, @unchecked Sendable {
         }
     }
 
+    /// How often the gate asks an ingest whether its join is spent. Well under a frame of start latency.
+    static let joinSpentPollSeconds: TimeInterval = 0.025
+
     /// AE#374: one account per live session, emitted at whichever exit ends the first-serve gate.
     ///
     /// Every `/media.m3u8` request without an `_HLS_msn` re-enters the gate, so without the latch a
diff --git a/Tests/AetherEngineTests/Issue684IngestSealCoversUpstreamSegmentTests.swift b/Tests/AetherEngineTests/Issue684IngestSealCoversUpstreamSegmentTests.swift
index a3aa3fbb5..899af75af 100644
--- a/Tests/AetherEngineTests/Issue684IngestSealCoversUpstreamSegmentTests.swift
+++ b/Tests/AetherEngineTests/Issue684IngestSealCoversUpstreamSegmentTests.swift
@@ -183,14 +183,6 @@ final class Issue684IngestSealCoversUpstreamSegmentTests: XCTestCase {
                                  LiveWindowSizing.liveOnlyFloorSeconds / 2)
     }
 
-    /// The owner's switch: where the ceiling sits is the whole difference between this fix on 10 s
-    /// providers and 7.24.0's answer (AE#678). Pinned so moving it is a decision and not a side effect.
-    func testCeilingIsTheOneSwitchForLongSegmentProviders() {
-        XCTAssertEqual(LiveEdgePolicy.upstreamSegmentSealCeilingSeconds, 10)
-        XCTAssertEqual(LiveEdgePolicy.targetDurationForIngestedSegment(10.0), 10)
-        XCTAssertEqual(LiveEdgePolicy.targetDurationForCadence(10.0), 7, "what 7.24.0 sealed")
-    }
-
     /// A fractional segment costs a whole second, like every other term (AE#447 round 2).
     func testFractionalSegmentCost() {
         let td = LiveEdgePolicy.targetDurationSeconds(maxSegmentDuration: 2.0,
@@ -202,7 +194,8 @@ final class Issue684IngestSealCoversUpstreamSegmentTests: XCTestCase {
         let coverage = HLSPlaylistTracker.loopbackCushionCoverageSeconds(segments: (0..<8).map { _ in
             HLSMediaSegment(uri: "s", duration: 6.006, discontinuityBefore: false)
         })
-        XCTAssertEqual(coverage, 25.0, accuracy: 1e-9, "21 s of holdback and 4 s of open GOP: five segments")
+        XCTAssertEqual(coverage, 19.0, accuracy: 1e-9,
+                       "the join is not sized from the seal: ceil(6.006 / 1.5) = 5, 15 s and a 4 s GOP")
     }
 
     // MARK: - As far as the join can pay
@@ -227,18 +220,6 @@ final class Issue684IngestSealCoversUpstreamSegmentTests: XCTestCase {
             full: 6, withoutUpstreamSegment: 4, finalizedSeconds: .infinity), 4)
     }
 
-    func testJoinExhaustionIsTheOpenSegmentAndNothingElse() {
-        XCTAssertTrue(LiveEdgePolicy.joinIsExhausted(
-            finalizedSeconds: 16, longestCutSegmentSeconds: 2, joinBacklogSeconds: 18))
-        XCTAssertFalse(LiveEdgePolicy.joinIsExhausted(
-            finalizedSeconds: 12, longestCutSegmentSeconds: 2, joinBacklogSeconds: 18),
-            "two more GOPs of the join are still to be cut")
-        XCTAssertFalse(LiveEdgePolicy.joinIsExhausted(
-            finalizedSeconds: 0, longestCutSegmentSeconds: 0, joinBacklogSeconds: 18))
-        XCTAssertFalse(LiveEdgePolicy.joinIsExhausted(
-            finalizedSeconds: 16, longestCutSegmentSeconds: 2, joinBacklogSeconds: 0))
-    }
-
     // MARK: - Where the term comes from
 
     /// Measured, not advertised: the longest segment the upstream actually served.
@@ -255,18 +236,32 @@ final class Issue684IngestSealCoversUpstreamSegmentTests: XCTestCase {
                        "monotonic, like the floor it sits beside")
     }
 
-    // MARK: - The join carries the cushion the seal asks for
+    // MARK: - The join keeps its depth
 
-    func testJoinCoversTheDeeperHoldback() {
+    /// Owner's rule: the join is never extended for the upstream-segment term. One more upstream
+    /// segment is one more download before the first picture on every zap (AE#678 declined it), so
+    /// the coverage is what 7.24.0 sized it to and the seal rises only as far as that pays.
+    func testJoinIsNotExtendedForTheUpstreamSegmentTerm() {
         func coverage(_ durations: [Double]) -> Double {
             HLSPlaylistTracker.loopbackCushionCoverageSeconds(segments: durations.map {
                 HLSMediaSegment(uri: "s", duration: $0, discontinuityBefore: false)
             })
         }
-        XCTAssertEqual(coverage([6, 6, 6]), 22)     // TD 6, 18 s holdback, 4 s of open GOP
-        XCTAssertEqual(coverage([6, 4, 6, 4]), 22)  // the field shape, sealed from the longest
-        XCTAssertEqual(coverage([2, 2, 2]), 8)      // AE#447's shape, unchanged
-        XCTAssertEqual(coverage([20, 20, 20]), 46)  // above the ceiling: TD 14, as before the term
+        XCTAssertEqual(coverage([6, 6, 6]), 16)     // ceil(6 / 1.5) = 4, 12 s and a 4 s GOP: three segments
+        XCTAssertEqual(coverage([10, 10, 10]), 25)  // 7, 21 s + 4 s: three segments
+        XCTAssertEqual(coverage([2, 2, 2]), 8)
+        XCTAssertEqual(coverage([20, 20, 20]), 46)
+        var tracker = HLSPlaylistTracker()
+        let uris = ["a", "b", "c", "d", "e", "f", "g", "h"]
+        let joined = tracker.newSegments(in: HLSMediaPlaylist(
+            targetDuration: 6,
+            mediaSequence: 0,
+            segments: uris.map { HLSMediaSegment(uri: $0, duration: 6, discontinuityBefore: false) },
+            hasEndList: false,
+            isEncrypted: false,
+            hasUnsupportedEncryption: false,
+            hasMap: false))
+        XCTAssertEqual(joined.map(\.uri), ["f", "g", "h"], "three 6 s segments, as before this issue")
     }
 
     // MARK: - The seal says why
diff --git a/Tests/AetherEngineTests/Issue684JoinBoundSealTests.swift b/Tests/AetherEngineTests/Issue684JoinBoundSealTests.swift
index 4de121e82..6ae725540 100644
--- a/Tests/AetherEngineTests/Issue684JoinBoundSealTests.swift
+++ b/Tests/AetherEngineTests/Issue684JoinBoundSealTests.swift
@@ -1,19 +1,23 @@
 // Tests/AetherEngineTests/Issue684JoinBoundSealTests.swift
-// AE#684 review: sealing over the upstream segment made every zap on a SHALLOW upstream window slower.
-// An upstream that lists three 6 s segments joins 18 s; the last GOP stays open until the next upstream
-// delivery, so 16 s are cut, and the 18 s holdback of a TARGETDURATION 6 is not reachable from the join
-// at all. The gate waited out the fastZap grace and served under its own holdback: measured 4.25 s to
-// first picture where 7.25.1 took 0.18 s (2.24 s with the first-serve latch alone). `.standard` has no
-// bounded start and waits for the next upstream segment instead.
+// AE#684: the seal over the upstream segment, as far as the join can pay for it.
 //
-// A join that has handed over everything it will seals the largest value its cut content covers, between
-// what the seal was without the upstream term and the full one.
+// The join is three upstream segments on anything longer than about 5 s and is not deepened for the
+// seal. Three 6 s segments are 18 s joined; the last GOP stays open until the next upstream delivery,
+// so 16 s are cut, and the 18 s holdback of a TARGETDURATION 6 is not reachable from the join at all.
+// Waiting for it is waiting for the next upstream segment: measured 4.25 s to first picture where
+// 7.25.1 took 0.18 s. A join that has handed over everything it will seals the largest value its cut
+// content covers, between what the seal was without the upstream term and the full one.
+//
+// "Has handed over everything" is a fact the reader states. Round 1 derived it from EXTINF sums with
+// a tolerance, and a playlist whose EXTINF over-reports its media (6.3 for 6 s, measured in review)
+// never added up: TD 7, a 21 s holdback, bounded start after the grace, 2.23 s to first picture.
 import XCTest
 @testable import AetherEngine
 
 private final class JoinedUpstream: @unchecked Sendable {
     var segmentDuration: Double?
     var joinBacklog: Double?
+    var joinSpent: Bool?
 }
 
 final class Issue684JoinBoundSealTests: XCTestCase {
@@ -27,7 +31,8 @@ final class Issue684JoinBoundSealTests: XCTestCase {
             observeSealEvidence: {
                 LiveCadenceEvidence(closedCadenceSeconds: nil,
                                     servedSegmentDurationSeconds: upstream.segmentDuration,
-                                    joinBacklogSeconds: upstream.joinBacklog)
+                                    joinBacklogSeconds: upstream.joinBacklog,
+                                    joinIsSpent: upstream.joinSpent)
             },
             selfReportedTargetDurationSeconds: upstream.segmentDuration,
             clock: { 0 }
@@ -67,6 +72,7 @@ final class Issue684JoinBoundSealTests: XCTestCase {
         let upstream = JoinedUpstream()
         upstream.segmentDuration = 6.0
         upstream.joinBacklog = 18.0
+        upstream.joinSpent = true
         let (provider, cache) = makeProvider(upstream, cutTarget: 0.5, boundedStart: true)
         defer { cache.close() }
         append(provider, count: 8, each: 2.0)
@@ -81,11 +87,13 @@ final class Issue684JoinBoundSealTests: XCTestCase {
                                  "and the holdback it advertises is one the window holds")
     }
 
-    /// The same join one upstream segment deeper pays in full.
-    func testDeepJoinKeepsTheFullSeal() {
+    /// A join that does cover the full holdback pays in full (the reporting channel's own shape:
+    /// 6 s and 4 s segments alternating, four joined, 18 s cut or more).
+    func testAJoinThatCoversTheHoldbackKeepsTheFullSeal() {
         let upstream = JoinedUpstream()
         upstream.segmentDuration = 6.0
         upstream.joinBacklog = 24.0
+        upstream.joinSpent = true
         let (provider, cache) = makeProvider(upstream, cutTarget: 0.5, boundedStart: true)
         defer { cache.close() }
         append(provider, count: 11, each: 2.0)
@@ -93,11 +101,12 @@ final class Issue684JoinBoundSealTests: XCTestCase {
         XCTAssertEqual(provider.liveTargetDurationSeconds(maxSegmentDuration: 2.0), 6)
     }
 
-    /// A join still arriving is not exhausted: the gate keeps waiting for the cushion, as before.
+    /// A join still arriving is not spent: the gate keeps waiting for the cushion, as before.
     func testAJoinStillArrivingIsNotSealedShort() {
         let upstream = JoinedUpstream()
         upstream.segmentDuration = 6.0
         upstream.joinBacklog = 24.0
+        upstream.joinSpent = false
         let (provider, cache) = makeProvider(upstream, cutTarget: 0.5, boundedStart: false)
         defer { cache.close() }
         append(provider, count: 5, each: 2.0)
@@ -112,6 +121,7 @@ final class Issue684JoinBoundSealTests: XCTestCase {
         let upstream = JoinedUpstream()
         upstream.segmentDuration = 10.0
         upstream.joinBacklog = 30.0
+        upstream.joinSpent = true
         let (provider, cache) = makeProvider(upstream, cutTarget: 4.0, boundedStart: false)
         defer { cache.close() }
         append(provider, count: 7, each: 4.0)
@@ -129,6 +139,7 @@ final class Issue684JoinBoundSealTests: XCTestCase {
         let upstream = JoinedUpstream()
         upstream.segmentDuration = 6.0
         upstream.joinBacklog = 18.0
+        upstream.joinSpent = true
         let (provider, cache) = makeProvider(upstream, cutTarget: 4.0, boundedStart: false)
         defer { cache.close() }
         append(provider, count: 4, each: 4.0)
@@ -137,6 +148,93 @@ final class Issue684JoinBoundSealTests: XCTestCase {
         XCTAssertNil(derivation.joinBound)
     }
 
+    // MARK: - EXTINF and media need not agree
+
+    /// The re-review's shape: 6 s of media per segment listed as 6.3 (advertised 7). EXTINF says
+    /// 18.9 s were joined; 16 s are cut and nothing more is coming. Arithmetic on the sum (16 + 2 +
+    /// tolerance against 18.9) said "still arriving" and sealed the full 7.
+    func testInflatedExtinfStillSealsWhatTheJoinPays() {
+        let upstream = JoinedUpstream()
+        upstream.segmentDuration = 6.3
+        upstream.joinBacklog = 18.9
+        upstream.joinSpent = true
+        let (provider, cache) = makeProvider(upstream, cutTarget: 0.5, boundedStart: true)
+        defer { cache.close() }
+        append(provider, count: 8, each: 2.0)
+
+        var served = false
+        let waited = seconds { served = provider.waitForFirstLiveSegment(timeout: 5) }
+        XCTAssertTrue(served)
+        XCTAssertLessThan(waited, 0.5)
+        XCTAssertEqual(provider.liveTargetDurationSeconds(maxSegmentDuration: 2.0), 5,
+                       "what 7.25.1 sealed here too: ceil(6.3 / 1.5)")
+    }
+
+    /// The other way round: the media runs longer than its EXTINF says. The sum is already reached
+    /// (16 + 2 against 18) while the reader is still handing media over, so the arithmetic called
+    /// the join exhausted and would have sealed short of what the rest of it pays for.
+    func testMediaLongerThanExtinfIsNotSealedBeforeTheJoinIsSpent() {
+        let upstream = JoinedUpstream()
+        upstream.segmentDuration = 6.0
+        upstream.joinBacklog = 18.0
+        upstream.joinSpent = false
+        let (provider, cache) = makeProvider(upstream, cutTarget: 0.5, boundedStart: false)
+        defer { cache.close() }
+        append(provider, count: 8, each: 2.0)
+        let arriving = provider.firstServeTargetDuration((count: 8, summed: 16.0, maxDuration: 2.0))
+        XCTAssertEqual(arriving.value, 6)
+        XCTAssertNil(arriving.joinBound)
+
+        // One more GOP lands, the reader runs dry: 18 s cut pays for the full 6.
+        provider.appendLiveSegment(index: 8, startSeconds: 16.0, durationSeconds: 2.0)
+        upstream.joinSpent = true
+        XCTAssertTrue(provider.waitForFirstLiveSegment(timeout: 5))
+        XCTAssertEqual(provider.liveTargetDurationSeconds(maxSegmentDuration: 2.0), 6)
+    }
+
+    /// The gate has no event for "the cutter parked on an empty reader", so it has to look again by
+    /// itself: a join that turns spent while a request is waiting is served then, not at the grace.
+    func testAWaitingRequestIsServedWhenTheJoinTurnsSpent() {
+        let upstream = JoinedUpstream()
+        upstream.segmentDuration = 10.0
+        upstream.joinBacklog = 30.0
+        upstream.joinSpent = false
+        let (provider, cache) = makeProvider(upstream, cutTarget: 4.0, boundedStart: false)
+        defer { cache.close() }
+        append(provider, count: 7, each: 4.0)
+        DispatchQueue.global().asyncAfter(deadline: .now() + 0.2) { upstream.joinSpent = true }
+        var served = false
+        let waited = seconds { served = provider.waitForFirstLiveSegment(timeout: 5) }
+        XCTAssertTrue(served)
+        XCTAssertGreaterThanOrEqual(waited, 0.15)
+        XCTAssertLessThan(waited, 1.5, "not the 5 s deadline: the gate noticed")
+        XCTAssertEqual(provider.liveTargetDurationSeconds(maxSegmentDuration: 4.0), 9)
+    }
+
+    /// The reader's half of the fact: nothing queued and its consumer parked.
+    func testAnEmptyFIFOWithAParkedReaderIsTheSpentSignal() {
+        let fifo = ByteFIFO(capacity: 1024)
+        XCTAssertFalse(fifo.isEmptyWithReaderParked, "nobody is reading")
+        XCTAssertTrue(fifo.write(Data([1, 2, 3])))
+        XCTAssertFalse(fifo.isEmptyWithReaderParked, "bytes are waiting")
+        let buffer = UnsafeMutablePointer<UInt8>.allocate(capacity: 16)
+        defer { buffer.deallocate() }
+        XCTAssertEqual(fifo.read(into: buffer, maxLength: 16), 3)
+        XCTAssertFalse(fifo.isEmptyWithReaderParked, "drained, but the consumer has not come back for more")
+        let done = expectation(description: "reader returned")
+        Thread.detachNewThread {
+            let scratch = UnsafeMutablePointer<UInt8>.allocate(capacity: 16)
+            _ = fifo.read(into: scratch, maxLength: 16)
+            scratch.deallocate()
+            done.fulfill()
+        }
+        while fifo.parkedWaiterCount == 0 { usleep(200) }
+        XCTAssertTrue(fifo.isEmptyWithReaderParked)
+        fifo.cancel()
+        wait(for: [done], timeout: 2)
+        XCTAssertFalse(fifo.isEmptyWithReaderParked, "a cancelled reader is not a spent join")
+    }
+
     /// The seal line says what was paid and what was asked, and the drift line names the term too.
     func testSealAccountStatesWhatTheJoinPaid() {
         var derivation = LiveTargetDurationDerivation(
@@ -146,7 +244,7 @@ final class Issue684JoinBoundSealTests: XCTestCase {
         let account = derivation.account
         XCTAssertTrue(account.contains("sealed at 5s (holdback 15.000s)"), account)
         XCTAssertTrue(account.contains("upstream segment 6.000s"), account)
-        XCTAssertTrue(account.contains("of which the join pays 5s of 6s (16.000s cut of the 18.000s it held)"),
+        XCTAssertTrue(account.contains("of which the join pays 5s of 6s (16.000s cut of the 18.000s it listed)"),
                       account)
     }
 }

From 0a7849e74c47087fb26c7125649aad10ffa74293 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 1 Oct 2026 22:41:55 +0200
Subject: [PATCH 278/359] docs(live): the ingest seal under the join-bound
 rule, measured (#684)

api.md and cli.md described a join one segment deeper and a seal of 6
on 6 s providers. The join is not deepened; the docs now state what is
sealed (5 on 6 s segments, 9 on 10 s), what it costs (3 s and 6 s of
standing latency, nothing at the join) and what it does not do: on a
6 s provider -12888 still comes (5 and a stall before, 3 and no stall
after over 180 s), and .standard on 6 s segments still waits for the
next upstream segment as it did. The matrix is re-measured against
7.25.1 on this rule, including the inflated-EXTINF cells and the
raw-TS control that shows the AE#594 table unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 ...IngestSealCoversUpstreamSegmentTests.swift | 12 +--
 docs/api.md                                   | 87 ++++++++++---------
 docs/cli.md                                   | 37 ++++----
 3 files changed, 70 insertions(+), 66 deletions(-)

diff --git a/Tests/AetherEngineTests/Issue684IngestSealCoversUpstreamSegmentTests.swift b/Tests/AetherEngineTests/Issue684IngestSealCoversUpstreamSegmentTests.swift
index 899af75af..da8fc4af9 100644
--- a/Tests/AetherEngineTests/Issue684IngestSealCoversUpstreamSegmentTests.swift
+++ b/Tests/AetherEngineTests/Issue684IngestSealCoversUpstreamSegmentTests.swift
@@ -11,8 +11,9 @@
 // been listed.
 //
 // The upstream delivers in whole segments however finely they are re-cut here, so the served playlist
-// changes once per upstream segment and has to promise what a playlist of those segments promises:
-// TARGETDURATION >= the longest upstream segment.
+// changes once per upstream segment and the seal asks for what a playlist of those segments promises:
+// TARGETDURATION >= the longest upstream segment. These pin what is ASKED. What is sealed is that,
+// as far as the join pays for it (`Issue684JoinBoundSealTests`), and the join is not deepened.
 import XCTest
 @testable import AetherEngine
 
@@ -136,9 +137,10 @@ final class Issue684IngestSealCoversUpstreamSegmentTests: XCTestCase {
     // MARK: - `.standard`, which the term reaches above 6 s
 
     /// `.standard` re-cuts too (4 s cut target), so a provider above its `1.5 x cut target` floor is
-    /// delivered in units longer than anything the floor covers. Measured on a 10 s origin with
-    /// jittered deliveries, three 60 s runs per arm and per window depth: at TD 7 one -12888 and one
-    /// item rebuild in every run, at TD 10 (or 9 where the join pays for no more) neither.
+    /// delivered in units longer than anything the floor covers. This is what the terms ASK for; the
+    /// three-segment join then pays 9 of the 10 (`Issue684JoinBoundSealTests`). Measured on a 10 s
+    /// origin with jittered deliveries, three 60 s runs per arm and window depth: at TD 7 the item
+    /// was rebuilt in 6 of 6 runs, at TD 9 in none.
     func testStandardProfileSealsLongUpstreamSegmentsWhole() {
         func seal(_ upstream: Double) -> Int {
             LiveEdgePolicy.targetDurationSeconds(maxSegmentDuration: 4.0,
diff --git a/docs/api.md b/docs/api.md
index 302743f7a..d9091ed8e 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -709,48 +709,54 @@ the value is sealed from the first few, so it carries `ceil(1.5 x max EXTINF)` o
 whose GOPs run 1.0 to 2.4 s sealed TARGETDURATION 1 on its first three and then broke `EXTINF <= TD`
 on every longer one (AE#670). 1 s GOPs therefore serve TARGETDURATION 2 and a 6 s holdback.
 
-**An ingested HLS upstream seals over the segment it is delivered in, under either profile (AE#684).**
-The engine re-cuts an upstream segment (at its GOPs under `.fastZap`, at about 4 s under `.standard`),
-but the window still changes once per UPSTREAM segment, so the floor is the longest segment the upstream
-has served, whole: 2 and a 6 s holdback on 2 s segments as before, 6 and 18 s on 6 s ones under
-`.fastZap`, where `ceil(6 / 1.5)` used to seal 4 and left the client a patience of exactly one delivery.
-`.standard` already sat at 6 through its `1.5 x cut target` floor, so the term only reaches it above
-6 s: a 10 s provider goes from 7 to 10. The upstream's advertised target duration is still not read.
-Three things bound it:
-
-- **A ceiling.** Segments longer than `LiveEdgePolicy.upstreamSegmentSealCeilingSeconds` (10 s) are not
-  taken whole: a 20 s one seals 14, as it did before, because a holdback is `3 x` the value and the
-  live-only window is 60 s. That constant is also the one place that decides whether 10 s providers get
-  this at all: at 6 they seal 7 again, exactly as 7.24.0 did.
-- **What the join can pay.** A holdback the first window cannot hold is not protection, it is a slow
-  start. An upstream that lists three or four 6 s segments joins 18 s and cuts 16 (the last GOP stays
-  open until the next delivery), so it seals 5, not 6: the largest value whose holdback the window
-  covers, never under what the seal was without the term. The seal line says so (`of which the join
-  pays 5s of 6s (16.000s cut of the 18.000s it held)`). A window deep enough joins one segment more
-  and pays in full.
-- **A whole second per fraction**, like every other term: 6.006 s segments seal 7, a 21 s holdback and
-  a five-segment join.
+**An ingested HLS upstream seals over the segment it is delivered in, as far as its join pays for it,
+under either profile (AE#684).** The engine re-cuts an upstream segment (at its GOPs under `.fastZap`,
+at about 4 s under `.standard`), but the window still changes once per UPSTREAM segment, so what the
+seal asks for is the longest segment the upstream has served, whole, where `ceil(segment / 1.5)` used
+to leave the client a patience of exactly one delivery. The upstream's advertised target duration is
+still not read. What it gets is bounded three ways:
+
+- **By the join, which is not deepened for it.** A seal is a holdback of `3 x` itself, and the join is
+  the three upstream segments it was before (one more would be one more download before the first
+  picture on every zap, which AE#678 measured and declined). Their last GOP stays open until the next
+  delivery, so three 6 s segments are 18 s joined and 16 s cut: the seal is 5, the largest value whose
+  holdback that window holds, not 6. Three 10 s segments cut 28 s and seal 9. A join that does cover
+  the full holdback (segments of mixed length, say) seals the full value. The seal line says which
+  (`of which the join pays 5s of 6s (16.000s cut of the 18.000s it listed)`), and "the join has no
+  more to give" is a fact the reader states (its join batch is handed over and its consumer is
+  waiting), not arithmetic on EXTINF, which a playlist that rounds its durations up would fail.
+- **By a ceiling.** Segments longer than 10 s (`LiveEdgePolicy.upstreamSegmentSealCeilingSeconds`) are
+  not asked for whole: a 20 s one seals 14, as it did before, because the live-only window is 60 s.
+- **Never under what it was.** Where the old value already covered the segment nothing moves: 2 s
+  segments keep 2 and a 6 s holdback, and `.standard` keeps its 6 on anything up to 6 s.
+
+So on a 6 s provider under `.fastZap` the seal goes from 4 to 5 (holdback 12 to 15 s), and on a 10 s
+provider under either profile from 7 to 9 (21 to 27 s). The join, and with it the time to the first
+picture, is what it was: behind an 8 Mbit/s link, three runs per arm, 3.81 to 4.04 s before and 3.80 to
+3.85 s after on 6 s segments, 6.15 to 6.36 s and 6.18 to 6.28 s on 10 s ones. The cost is standing
+latency, 3 s more behind the upstream's edge on a 6 s provider and 6 s on a 10 s one.
 
 Measured on loopback against `Scripts/hls-burst-origin.py` (deliveries 3 to 9.3 s apart on 6 s
-segments), 60 s per run, three runs per arm, 7.25.1 against this:
+segments), 60 s per run, three runs per arm and row, 7.25.1 against this; first picture is 0.17 to
+0.51 s in both arms wherever a row does not say otherwise:
 
-| upstream, profile, window | 7.25.1 | now |
+| upstream, profile, segments listed | 7.25.1 | now |
 |---|---|---|
-| 6 s, `.fastZap`, 8 listed | TD 4, first picture 0.18 to 0.20 s, 3 x `-12888` and 2 stalls per run | TD 6, 0.19 to 0.22 s, none |
-| 6 s, `.fastZap`, 3 or 4 listed | TD 4, 0.19 to 0.25 s, 2 to 3 x `-12888`, 1 to 2 stalls | TD 5, 0.19 to 0.22 s, 1 to 2 x `-12888`, no stall |
-| 10 s, `.fastZap`, 8 listed | TD 7, 0.18 to 0.20 s, 1 x `-12888` | TD 10, 0.19 to 0.20 s, none |
-| 10 s, `.fastZap`, 3 or 4 listed | TD 7, 0.18 to 0.21 s, window closed and item rebuilt in 4 of 6 runs | TD 9, 0.18 to 0.20 s, none |
-| 6 s, `.standard`, 8 listed | TD 6, 6.29 to 6.43 s (the join was one segment short of its own holdback) | TD 6, 0.17 to 0.19 s |
-| 6 s, `.standard`, 3 listed | TD 6, 6.23 to 6.41 s | TD 6, 6.27 to 6.37 s (unchanged: nothing to pay down) |
-| 10 s, `.standard`, 3 or 8 listed | TD 7, 0.17 to 0.18 s, item rebuilt in 6 of 6 runs | TD 9 or 10, 0.18 to 0.19 s, none |
-
-What it costs is the join: one more upstream segment before the first picture wherever the window is
-deep enough to offer it and a segment is longer than 4 s. Loopback does not show that. Behind an
-8 Mbit/s link shared by all responses, 1.5 Mbit/s content, median of five: **3.81 s to 4.98 s** on 6 s
-segments and **6.16 s to 8.11 s** on 10 s ones, the segment's bytes over the link rate. And the viewer
-sits one holdback behind the upstream's edge, so 6 s further back on a 6 s provider and 9 s on a 10 s
-one. "None" in the table is a statement about this origin: a real outage longer than the holdback's low
-point still stalls, and the capture that started this had 10 of its 110 delivery gaps above 9 s.
+| 6 s, `.fastZap`, 3 | TD 4, 1 x `-12888` per run, 2 stalls in 3 runs | TD 5, none |
+| 6 s, `.fastZap`, 4 | TD 4, 2 x `-12888` per run, 2 stalls in 3 runs | TD 5, 1 to 2 x `-12888`, no stall |
+| 6 s, `.fastZap`, 8 | TD 4, 1 to 3 x `-12888`, 3 stalls in 3 runs | TD 5, 0 to 2 x `-12888`, no stall |
+| 10 s, `.fastZap`, 3 / 4 / 8 | TD 7, 1 x `-12888` in 7 of 9 runs, window closed and item rebuilt in 4 of 9 | TD 9, none in 9 of 9 |
+| 10 s, `.standard`, 3 / 8 | TD 7, item rebuilt in 6 of 6 runs | TD 9, none in 6 of 6 |
+| 6 s, `.standard`, 3 / 8 | TD 6, first picture 6.18 to 6.53 s | unchanged: TD 6, 6.28 to 6.46 s |
+
+Two things this does not do, said plainly. On a 6 s provider `-12888` still comes: over one 180 s run
+5 of them and a stall before, 3 and no stall after, because 7.5 s of patience still loses to a 9 s gap
+and what changed is the holdback under it. (A join one segment deeper seals 6 and drew none in three
+such runs; it was measured and not shipped, for the download it costs.) And `.standard` on 6 s segments
+still takes about 6.3 s to its first picture, waiting for the next upstream segment, exactly as it did:
+its seal there is its own `1.5 x cut target` floor, which three joined segments never covered. A real
+outage longer than the holdback's low point stalls under any of these; the capture that started this
+had 10 of its 110 delivery gaps above 9 s.
 
 **An HLS source with a window of its own now fills that cushion at the join rather than in wall clock**
 (6.77.0). The ingest used to enter a live playlist three segments behind the edge, and three joined
@@ -761,9 +767,8 @@ short segments is several times three. Measured against `hlsfixture --window 8`
 --fast-zap`, three runs per row: first picture on a 2 s-segment channel **2.22 s before, 0.20 s after**;
 on 1 s segments **0.41 to 1.22 s before, 0.18 to 0.20 s after**, and the spread is the second half of
 the finding, since before the change the number depended on where in the upstream segment cycle the tune
-landed. A window at the three-segment floor has nothing deeper to offer and is unchanged. A
-long-segment provider was unchanged by this too, and is not any more: since AE#684 its join is one
-upstream segment deeper, see above. The deeper entry is
+landed. A window at the three-segment floor has nothing deeper to offer and is unchanged, and so is a
+long-segment provider, whose coverage target was already met inside the old bound. The deeper entry is
 not paid back later: both arms fetch up to the same upstream segment number at the same wall clock, so
 it is caught up at I/O speed instead of becoming a standing lag behind the live edge. What it does not
 touch is a source with no playlist at all (raw MPEG-TS over HTTP), where there is no window to enter
diff --git a/docs/cli.md b/docs/cli.md
index 757d7f295..3c39cb54b 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -719,7 +719,7 @@ The stall half needs a field capture or an origin that reproduces the seek, not
 
 ### An origin that delivers late (AE#684)
 
-`hlsfixture` publishes on a metronome, and a metronome is the one thing an IPTV origin is not. The defect AE#684 reported only exists when a delivery arrives later than the segment is long, so it could be read off a device log and reproduced nowhere. `Scripts/hls-burst-origin.py` serves a sliding playlist over pre-cut segments and publishes segment k at `end of k - prefill + delays[k % n]`: the MEAN cadence stays the segment duration (the origin never falls behind real time) while the gap between two deliveries follows the cycle. `--freeze-at K --freeze-seconds F` is an outage with the backlog landing at once, `--durs 6,4` alternates segment lengths, and `--rate-kbps` / `--latency-ms` are a link shared by every in-flight response. Its docstring carries the fixture command: 720x576 at 25 fps, 2 s GOPs, 6 s segments, and a white frame plus a 40 ms beep on every whole second, which is what makes the sound measurable against the picture afterwards.
+`hlsfixture` publishes on a metronome, and a metronome is the one thing an IPTV origin is not. The defect AE#684 reported only exists when a delivery arrives later than the segment is long, so it could be read off a device log and reproduced nowhere. `Scripts/hls-burst-origin.py` serves a sliding playlist over pre-cut segments and publishes segment k at `end of k - prefill + delays[k % n]`: the MEAN cadence stays the segment duration (the origin never falls behind real time) while the gap between two deliveries follows the cycle. `--freeze-at K --freeze-seconds F` is an outage with the backlog landing at once, `--durs 6,4` alternates segment lengths, `--dur 6.3` over 6 s of media is a playlist that rounds its EXTINF up, `--window` / `--prefill` set how many segments the upstream lists, and `--rate-kbps` / `--latency-ms` are a link shared by every in-flight response. Its docstring carries the fixture command: 720x576 at 25 fps, 2 s GOPs, 6 s segments, and a white frame plus a 40 ms beep on every whole second, which is what makes the sound measurable against the picture afterwards.
 
 ```bash
 Scripts/hls-burst-origin.py --dir seg6 --delays 0,0.3,2.6,0.2,0.6,2.4,0.1,0.5 &
@@ -728,34 +728,31 @@ aetherctl play --live --live-ingest --fast-zap --seconds 180 http://127.0.0.1:86
 
 That cycle makes the origin's own gaps run 3.6 to 8.3 s. On the loopback they arrive 3.0 to 9.3 s apart, because the ingest reloads the upstream playlist every half segment and a delivery that just missed a reload waits for the next: **the served window changes once per UPSTREAM segment, up to one and a half of them apart, however finely the engine re-cuts it.** Under `.fastZap` the cut is the 2 s GOP, `max EXTINF` reads 2.000 s, and through 7.25.1 the upstream's 6 s entered only through the cadence floor, as `ceil(6 / 1.5)` = 4. That division is right for a MEASURED gap, which is a robust maximum; a segment duration is the other end of the distribution, the period the source delivers at when nothing is late. So the client's patience (`1.5 x 4` = 6.0 s) was exactly one period, and the 12 s holdback left 2.7 s at the low point of the sawtooth.
 
-What that costs is not the `-12888` itself but what AVPlayer does next: it skips a reload. Measured here and on an Apple TV alike, polls every 2.00 s, then 4.00 s (macOS) or 5.03 s (tvOS) of nothing after the error, and the stall lands inside that hole with the next delivery already listed 1.9 to 2.6 s earlier. Three 180 s runs per arm, arms alternated:
+What that costs is not the `-12888` itself but what AVPlayer does next: it skips a reload. Measured here and on an Apple TV alike, polls every 2.00 s, then 4.00 s (macOS) or 5.03 s (tvOS) of nothing after the error, and the stall lands inside that hole with the next delivery already listed 1.9 to 2.6 s earlier.
 
-| | sealed | join | `-12888` | `playbackStalled` |
-|---|---|---|---|---|
-| 7.25.1 | TD 4, holdback 12 s | 3 segments | 5 / 4 / 6 | 2 / 2 / 3 |
-| with the upstream segment in the seal | TD 6, holdback 18 s | 4 segments | 0 / 0 / 0 | 0 / 0 / 0 |
-
-Both arms saw the same deliveries (four to six gaps of 9.0 to 9.3 s per run), and they differ in two things, not one: the sealed value and the join it sizes (three segments against four). Zero is this origin's number, not a promise. Its worst gap is 9.3 s, which a patience of 9.0 s plus one 3 s poll absorbs; the device capture this came from had 10 of its 110 gaps above 9 s and 5 above 12 s, so the field expectation is far fewer `-12888`, not none. The seal line states the new term, and the advert is still only reported:
+The seal now asks for the upstream segment whole and takes as much of it as the join pays for. The join itself is not deepened (one more upstream segment would be one more download before the first picture on every zap, which AE#678 measured and declined), so three 6 s segments are 18 s joined, 16 s cut, and a seal of 5:
 
 ```
-[HLSVideoEngine] live TARGETDURATION sealed at 6s (holdback 18.000s): max EXTINF 2.000s,
+[HLSVideoEngine] live TARGETDURATION sealed at 5s (holdback 15.000s): max EXTINF 2.000s,
   1.5 x cut target 0.750s, measured floor 6.000s needs 4s of patience,
-  upstream segment 6.000s (one delivery, however finely it is cut here);
-  upstream advertises 6.000s (reported, not used)
+  upstream segment 6.000s (one delivery, however finely it is cut here), of which the join
+  pays 5s of 6s (16.000s cut of the 18.000s it listed); upstream advertises 6.000s (reported, not used)
 ```
 
-Controls and prices, same harness. A 2 s upstream advertising a padded 3 (AE#447's shape) seals 2 and a 6 s holdback in both arms. Alternating 6 s / 4 s segments with under a second of jitter (`--durs 6,4`, the reporting channel's shape) draws one `-12888` and no stall in 180 s before and nothing after, which is why the field capture looks healthy between its outliers. An outage on top (`--freeze-at 14 --freeze-seconds 10`, about 12 s on the loopback) costs 2 to 3 stalls before and the one stall that IS the outage after: 18 s of holdback absorbs lateness, not a freeze longer than its low point of 8.7 s. And the join deepens by one upstream segment wherever a segment is longer than 4 s, which behind a link is one more download before the first picture: `--rate-kbps 8000 --latency-ms 30`, five runs per arm, **3.81 s before and 4.98 s after** (median), the 1.13 MB segment and nothing else. At memory speed it does not show (0.22 to 0.30 s against 0.23 to 0.55 s).
+One 180 s run per arm on that origin, same deliveries (four gaps above 9.0 s in each):
+
+| | sealed | join | `-12888` | `playbackStalled` | `#524` running thin |
+|---|---|---|---|---|---|
+| 7.25.1 | TD 4, holdback 12 s | 3 segments | 5 | 1 | 4 |
+| join-bound seal | TD 5, holdback 15 s | 3 segments | 3 | 0 | 0 |
 
-**`--window 3` is the arm that keeps a seal honest.** An upstream that lists three or four segments can be joined 18 s deep and no deeper, 16 s of which are cut before the next delivery, so a seal of 6 asks for a holdback the first window cannot hold. Two things were hiding in that start. The gate held the SECOND playlist request as well as the first (AVPlayer opens with two, each re-enters `waitForFirstLiveSegment`, and on a bounded start each waited its own grace: `GET /media.m3u8` at 2.81 s, `GET /init.mp4` at 4.83 s), which is the "+2.07 s at the picture" the AE#594 table above priced without naming; and the grace itself waited for content the join could not deliver. One run per row, 6 s segments, `--window 3 --prefill 3`:
+That is fewer, not none, and it is the honest size of what a seal one second higher buys: 7.5 s of patience still loses to a 9 s gap, but the 15 s holdback leaves 5.7 s at the low point where 12 s left 2.7 s, which is the difference between surviving AVPlayer's skipped reload and not. A join one segment deeper (TD 6, holdback 18 s) drew none of either in three such runs and was not shipped: it cost 3.81 s against 4.98 s to the first picture behind an 8 Mbit/s link. The device capture this came from had 10 of its 110 gaps above 9 s and 5 above 12 s, so the field expectation is fewer `-12888` and far fewer stalls, not zero.
 
-| | sealed | first manifest | first picture |
-|---|---|---|---|
-| 7.25.1 | TD 4 | at once | 0.18 s |
-| the upstream segment taken whole, nothing else | TD 6 | 2.011 s, bounded start after 2.000 s grace | 4.47 s |
-| + the gate opens once a manifest has gone out | TD 6 | 2.011 s, bounded | 2.24 s |
-| + an exhausted join seals what its window covers | TD 5 | at once | 0.32 s |
+**Whether a join is spent is a fact, not arithmetic.** The seal may only be taken short once the join has nothing more to give, and "cut content plus one segment reaches the summed EXTINF" is not that fact: `--dur 6.3` over 6 s of media never adds up, and a first version built on the sum sealed the full value there and took the bounded start (2.23 s to first picture against 0.20 s). The reader states it instead: the whole join batch is committed, its FIFO is empty, and the cutter is parked waiting for the next delivery. Three runs per arm on each inflated shape with three segments listed: served at once in all six (0.000 to 0.034 s of hold), TD 5 on 6 s media and TD 9 on 10 s.
+
+**The gate held the second playlist request too.** AVPlayer opens with two `/media.m3u8` requests, each re-enters `waitForFirstLiveSegment`, and on a bounded start each waited its own grace (`GET /media.m3u8` at 2.81 s, `GET /init.mp4` at 4.83 s). On an ingest the gate now opens for good once a manifest has gone out. On a source the engine cuts itself it does not: that second grace is the "+2.07 s at the picture" of the AE#594 table above, and removing it there also leaves the session up to 2 s closer to the producing edge, which is that issue's open question. The raw-TS control (`live --fast-zap --realtime --preroll 0`, two seeds, two runs per arm) reads the same in both arms: first manifest at 3.84 to 3.96 s, `init.mp4` at 6.11 to 6.33 s, first picture at 6.20 to 6.58 s, playhead 6.3 to 6.8 s behind the wall clock. The AE#594 table stands as printed.
 
-The full matrix (6 s and 10 s segments, windows of 3, 4 and 8, both profiles, three runs per arm) is in `api.md` under the live join; `.standard` drops `--fast-zap` from the `play` line.
+The full matrix (6 s and 10 s segments, 3, 4 and 8 listed, both profiles, three runs per arm) is in `api.md` under the live join; `.standard` drops `--fast-zap` from the `play` line.
 
 **The same fixture measures sound against picture, in the bytes.** `play --served-url` hands over the init segment, the cache holds the rest, and decoding their concatenation gives the presentation time of every flash and every beep onset: 147 of 148 seconds of a served session read **-0.3 ms** (the very first beep reads +19.7 ms, the decoder starting), across a 12 s outage, with no audio frame of any duration but 1024 samples and no gap at any segment seam. A fresh item re-fetches the same cached segments, so a rebuild cannot change that. What a rebuild does change is which segment the item starts on and where in it, and a segment's sound does not begin where its picture does: the cut is taken on the video keyframe and a transport stream interleaves audio behind video, so on this fixture the sound opens between 11 ms after and 208 ms before the picture, segment by segment. Each item now says what it started on,
 

From f22e1d9e0ad71db64a78f8c2c4b2184c87e0c283 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 1 Oct 2026 23:19:34 +0200
Subject: [PATCH 279/359] fix(live): the spent join is the pump's fact, read
 before the snapshot (#684)

joinIsSpent looked at the video reader's FIFO alone. With a demuxed
audio rendition the cutter merges two readers on one thread and parks
on whichever runs dry first; a rendition whose segments end 0.2 s
before the video's runs dry first every time, the video reader is
never parked, and the fact never became true. The gate then took the
old path with the full seal over a window that cannot hold it:
measured on three listed segments as 2.17 to 2.24 s to first picture
under fastZap and 10.4 to 10.7 s under .standard, where 7.25.1 took
0.18 to 0.20 s.

The fact is now stated for the pump: both join batches committed, and
the cutter parked on either empty reader (it holds a packet of the
other one it cannot place until the dry one delivers). A companion
nobody reads does not count.

The gate also asked in the wrong order: cushion snapshot first, spent
second. The cutter could append its last segment and park between the
two reads, and the seal was paid from the sum without it. The fact is
monotone, so it is read first.

Tests drive the reader itself against a loopback origin whose
responses are released by hand: not spent while its own join batch is
still arriving, spent when parked on the audio with video queued, not
spent while the audio rendition's join is still arriving.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../IO/HLSIngest/HLSLiveIngestReader.swift    |  33 +-
 .../IO/HLSIngest/LiveIngestSourceInfo.swift   |   5 +-
 .../Video/VideoSegmentProvider.swift          |  19 +-
 .../Issue684JoinBoundSealTests.swift          |   6 +-
 .../Issue684PumpJoinSpentTests.swift          | 322 ++++++++++++++++++
 5 files changed, 373 insertions(+), 12 deletions(-)
 create mode 100644 Tests/AetherEngineTests/Issue684PumpJoinSpentTests.swift

diff --git a/Sources/AetherEngine/IO/HLSIngest/HLSLiveIngestReader.swift b/Sources/AetherEngine/IO/HLSIngest/HLSLiveIngestReader.swift
index 11fbbb822..bf595ee5f 100644
--- a/Sources/AetherEngine/IO/HLSIngest/HLSLiveIngestReader.swift
+++ b/Sources/AetherEngine/IO/HLSIngest/HLSLiveIngestReader.swift
@@ -106,13 +106,42 @@ public final class HLSLiveIngestReader: IOReader, LiveIngestSourceInfo, @uncheck
     }
 
     var joinIsSpent: Bool {
-        let (spent, committed) = startLock.withLock { (_joinSpent, _joinBatchCommitted) }
+        let (spent, committed, companion) = startLock.withLock {
+            (_joinSpent, _joinBatchCommitted, _companionAudioReader)
+        }
         if spent { return true }
-        guard committed, fifo.isEmptyWithReaderParked else { return false }
+        guard Self.pumpJoinIsSpent(
+            main: (committed, fifo.isEmptyWithReaderParked),
+            companion: companion?.pumpJoinState
+        ) else { return false }
         startLock.withLock { _joinSpent = true }
         return true
     }
 
+    /// One reader's half of `joinIsSpent`: whether its ingest ever started, whether its join batch
+    /// is committed, and whether it is empty with its consumer parked on it.
+    var pumpJoinState: (started: Bool, committed: Bool, parked: Bool) {
+        let (isStarted, committed) = startLock.withLock { (started, _joinBatchCommitted) }
+        return (isStarted, committed, fifo.isEmptyWithReaderParked)
+    }
+
+    /// AE#684: the fact is the PUMP's, not one reader's. With a demuxed audio rendition the cutter
+    /// merges two readers on one thread and parks on whichever runs dry first, and a rendition whose
+    /// segments end a little before the video's runs dry first every time: the video reader is then
+    /// never parked, and a fact read off it alone never becomes true (measured: the full seal over a
+    /// window that cannot hold it, 2.2 s to first picture under `.fastZap` and 10.4 s under
+    /// `.standard`, where 7.25.1 took 0.18 s). So both join batches have to be committed, and the
+    /// cutter has to be parked on EITHER empty reader: it holds a packet of the other one it cannot
+    /// place until the dry one delivers, so nothing more is cut either way. A companion that was
+    /// never started is not being read at all and does not count.
+    static func pumpJoinIsSpent(main: (committed: Bool, parked: Bool),
+                                companion: (started: Bool, committed: Bool, parked: Bool)?) -> Bool {
+        guard main.committed else { return false }
+        guard let companion, companion.started else { return main.parked }
+        guard companion.committed else { return false }
+        return main.parked || companion.parked
+    }
+
     public var closedLiveCadenceSeconds: Double? {
         startLock.withLock { _cadenceMeter.closedCadence }
     }
diff --git a/Sources/AetherEngine/IO/HLSIngest/LiveIngestSourceInfo.swift b/Sources/AetherEngine/IO/HLSIngest/LiveIngestSourceInfo.swift
index 5f131952d..35fa2be48 100644
--- a/Sources/AetherEngine/IO/HLSIngest/LiveIngestSourceInfo.swift
+++ b/Sources/AetherEngine/IO/HLSIngest/LiveIngestSourceInfo.swift
@@ -39,8 +39,9 @@ protocol LiveIngestSourceInfo: AnyObject, Sendable {
     var joinBacklogSeconds: Double? { get }
 
     /// Whether the join has been handed over in full AND consumed: every byte of the join batch has
-    /// been committed to the reader, the reader is empty, and its consumer is parked waiting for the
-    /// next upstream delivery. From then on nothing more can be cut until that delivery, which is
+    /// been committed to the reader (and to its companion audio reader, where there is one), and the
+    /// consumer is parked on an empty reader, either of the two, waiting for the next upstream
+    /// delivery. From then on nothing more can be cut until that delivery, which is
     /// what the first-serve gate needs to know before it waits for a deeper cushion (AE#684).
     var joinIsSpent: Bool { get }
 
diff --git a/Sources/AetherEngine/Video/VideoSegmentProvider.swift b/Sources/AetherEngine/Video/VideoSegmentProvider.swift
index ecd2ed787..95b392701 100644
--- a/Sources/AetherEngine/Video/VideoSegmentProvider.swift
+++ b/Sources/AetherEngine/Video/VideoSegmentProvider.swift
@@ -2447,13 +2447,19 @@ final class VideoSegmentProvider: HLSSegmentProvider, @unchecked Sendable {
     /// full one unless an ingest's join is exhausted short of it
     /// (`LiveEdgePolicy.targetDurationTheJoinCanPay`). Only the gate asks this: once it has sealed,
     /// the value is frozen, and a later build's fuller candidate is the drift line's to report.
+    ///
+    /// `joinIsSpent` has to have been read BEFORE `snap` was taken. The fact is monotone, so a
+    /// snapshot taken after it was true holds everything the join will ever cut; asked the other way
+    /// round, the cutter can append its last segment and park between the two reads, and the seal is
+    /// paid from the sum without it (4 where the window holds 5).
     func firstServeTargetDuration(
-        _ snap: (count: Int, summed: Double, maxDuration: Double)
+        _ snap: (count: Int, summed: Double, maxDuration: Double),
+        joinIsSpent: Bool?
     ) -> LiveTargetDurationDerivation {
         var derivation = currentLiveTargetDuration(maxSegmentDuration: snap.maxDuration)
         guard derivation.upstreamSegment != nil,
               snap.count >= LiveEdgePolicy.minStartupSegments,
-              liveCadencePolicy?.joinIsSpent == true
+              joinIsSpent == true
         else { return derivation }
         let backlog = liveCadencePolicy?.joinBacklogSeconds ?? 0
         let base = LiveEdgePolicy.targetDurationSeconds(
@@ -2560,8 +2566,10 @@ final class VideoSegmentProvider: HLSSegmentProvider, @unchecked Sendable {
             // second request's wait is part of where the session ends up behind the producing edge,
             // which is AE#594's question and not this one's.
             if firstManifestServed, liveCadencePolicy != nil { return true }
+            // Spent first, snapshot second (see `firstServeTargetDuration`).
+            let spent = liveCadencePolicy?.joinIsSpent
             let snap = liveCushionSnapshot()
-            let target = firstServeTargetDuration(snap)
+            let target = firstServeTargetDuration(snap, joinIsSpent: spent)
             if LiveEdgePolicy.startupCushionSatisfied(segmentCount: snap.count,
                                                        summedDurationSeconds: snap.summed,
                                                        targetDuration: target.value,
@@ -2583,14 +2591,15 @@ final class VideoSegmentProvider: HLSSegmentProvider, @unchecked Sendable {
             var effectiveDeadline = degradedDeadline.map { min(deadline, $0) } ?? deadline
             // AE#684: a join becomes spent when the cutter parks on an empty reader, which is no
             // event this condition hears. While that is still to come, look again shortly.
-            if liveCadencePolicy?.joinIsSpent == false {
+            if spent == false {
                 effectiveDeadline = min(effectiveDeadline, Date().addingTimeInterval(Self.joinSpentPollSeconds))
             }
             if !firstSegmentCondition.wait(until: effectiveDeadline) {
                 // Re-read after the timed-out wait: an append racing the deadline would otherwise be judged
                 // on the stale snapshot (waitForLiveSegment below already does this).
+                let afterSpent = liveCadencePolicy?.joinIsSpent
                 let after = liveCushionSnapshot()
-                let afterTarget = firstServeTargetDuration(after)
+                let afterTarget = firstServeTargetDuration(after, joinIsSpent: afterSpent)
                 if LiveEdgePolicy.startupCushionSatisfied(segmentCount: after.count,
                                                           summedDurationSeconds: after.summed,
                                                           targetDuration: afterTarget.value,
diff --git a/Tests/AetherEngineTests/Issue684JoinBoundSealTests.swift b/Tests/AetherEngineTests/Issue684JoinBoundSealTests.swift
index 6ae725540..ae925c4f8 100644
--- a/Tests/AetherEngineTests/Issue684JoinBoundSealTests.swift
+++ b/Tests/AetherEngineTests/Issue684JoinBoundSealTests.swift
@@ -110,7 +110,7 @@ final class Issue684JoinBoundSealTests: XCTestCase {
         let (provider, cache) = makeProvider(upstream, cutTarget: 0.5, boundedStart: false)
         defer { cache.close() }
         append(provider, count: 5, each: 2.0)
-        let derivation = provider.firstServeTargetDuration((count: 5, summed: 10.0, maxDuration: 2.0))
+        let derivation = provider.firstServeTargetDuration((count: 5, summed: 10.0, maxDuration: 2.0), joinIsSpent: upstream.joinSpent)
         XCTAssertEqual(derivation.value, 6)
         XCTAssertNil(derivation.joinBound)
     }
@@ -143,7 +143,7 @@ final class Issue684JoinBoundSealTests: XCTestCase {
         let (provider, cache) = makeProvider(upstream, cutTarget: 4.0, boundedStart: false)
         defer { cache.close() }
         append(provider, count: 4, each: 4.0)
-        let derivation = provider.firstServeTargetDuration((count: 4, summed: 16.0, maxDuration: 4.0))
+        let derivation = provider.firstServeTargetDuration((count: 4, summed: 16.0, maxDuration: 4.0), joinIsSpent: upstream.joinSpent)
         XCTAssertEqual(derivation.value, 6)
         XCTAssertNil(derivation.joinBound)
     }
@@ -181,7 +181,7 @@ final class Issue684JoinBoundSealTests: XCTestCase {
         let (provider, cache) = makeProvider(upstream, cutTarget: 0.5, boundedStart: false)
         defer { cache.close() }
         append(provider, count: 8, each: 2.0)
-        let arriving = provider.firstServeTargetDuration((count: 8, summed: 16.0, maxDuration: 2.0))
+        let arriving = provider.firstServeTargetDuration((count: 8, summed: 16.0, maxDuration: 2.0), joinIsSpent: upstream.joinSpent)
         XCTAssertEqual(arriving.value, 6)
         XCTAssertNil(arriving.joinBound)
 
diff --git a/Tests/AetherEngineTests/Issue684PumpJoinSpentTests.swift b/Tests/AetherEngineTests/Issue684PumpJoinSpentTests.swift
new file mode 100644
index 000000000..c7f92701d
--- /dev/null
+++ b/Tests/AetherEngineTests/Issue684PumpJoinSpentTests.swift
@@ -0,0 +1,322 @@
+// Tests/AetherEngineTests/Issue684PumpJoinSpentTests.swift
+// AE#684: "the join has nothing more to give" is a fact the reader states, and the seal on every
+// ingest start hangs on it. Two ways it was wrong or untested:
+//
+// - It was read off the VIDEO reader alone. With a demuxed audio rendition the cutter merges two
+//   readers on one thread and parks on whichever runs dry first. A rendition whose segments end 0.2 s
+//   before the video's runs dry first every time, the video reader is never parked, and the fact never
+//   became true: measured on a three-segment window as the full seal over a window that cannot hold it,
+//   2.17 to 2.24 s to first picture under `.fastZap` and 10.4 to 10.7 s under `.standard`, against
+//   0.18 to 0.20 s on 7.25.1.
+// - It was only ever tested through a provider fake. These drive the reader itself against a loopback
+//   origin whose responses the test releases by hand, so nothing here depends on how long a sleep is.
+import XCTest
+@testable import AetherEngine
+
+/// Loopback origin: a master, a video and an audio media playlist of three 6 s segments each, and
+/// TS-shaped segment bodies. A path named in `hold` is answered only once `release` names it.
+private final class HeldSegmentOrigin: @unchecked Sendable {
+    let port: UInt16
+    private let listenFD: Int32
+    private let lock = NSCondition()
+    private var held: Set<String>
+    private var stopped = false
+
+    static let segmentBytes = 4 * 188
+
+    init?(hold: Set<String>) {
+        held = hold
+        let fd = socket(AF_INET, SOCK_STREAM, 0)
+        guard fd >= 0 else { return nil }
+        var one: Int32 = 1
+        setsockopt(fd, SOL_SOCKET, SO_REUSEADDR, &one, socklen_t(MemoryLayout<Int32>.size))
+        var addr = sockaddr_in()
+        addr.sin_family = sa_family_t(AF_INET)
+        addr.sin_port = 0
+        addr.sin_addr.s_addr = inet_addr("127.0.0.1")
+        let bound = withUnsafePointer(to: &addr) {
+            $0.withMemoryRebound(to: sockaddr.self, capacity: 1) {
+                bind(fd, $0, socklen_t(MemoryLayout<sockaddr_in>.size))
+            }
+        }
+        guard bound == 0, listen(fd, 16) == 0 else { close(fd); return nil }
+        var name = sockaddr_in()
+        var len = socklen_t(MemoryLayout<sockaddr_in>.size)
+        let named = withUnsafeMutablePointer(to: &name) {
+            $0.withMemoryRebound(to: sockaddr.self, capacity: 1) { getsockname(fd, $0, &len) }
+        }
+        guard named == 0 else { close(fd); return nil }
+        listenFD = fd
+        port = UInt16(bigEndian: name.sin_port)
+        Thread.detachNewThread { [weak self] in self?.acceptLoop() }
+    }
+
+    func url(_ path: String) -> URL { URL(string: "http://127.0.0.1:\(port)/\(path)")! }
+
+    func release(_ path: String) {
+        lock.lock()
+        held.remove(path)
+        lock.broadcast()
+        lock.unlock()
+    }
+
+    func stop() {
+        lock.lock()
+        stopped = true
+        held.removeAll()
+        lock.broadcast()
+        lock.unlock()
+        close(listenFD)
+    }
+
+    private func acceptLoop() {
+        while true {
+            let conn = accept(listenFD, nil, nil)
+            guard conn >= 0 else { return }
+            var noSigPipe: Int32 = 1
+            setsockopt(conn, SOL_SOCKET, SO_NOSIGPIPE, &noSigPipe, socklen_t(MemoryLayout<Int32>.size))
+            Thread.detachNewThread { [weak self] in self?.serve(conn) }
+        }
+    }
+
+    private func mediaPlaylist(prefix: String) -> Data {
+        var lines = ["#EXTM3U", "#EXT-X-VERSION:3", "#EXT-X-TARGETDURATION:6", "#EXT-X-MEDIA-SEQUENCE:0"]
+        for index in 0..<3 {
+            lines.append("#EXTINF:6.000,")
+            lines.append("\(prefix)\(index).ts")
+        }
+        return Data((lines.joined(separator: "\n") + "\n").utf8)
+    }
+
+    private func segment(tag: UInt8) -> Data {
+        var data = Data(capacity: Self.segmentBytes)
+        for packet in 0..<4 {
+            var ts = [UInt8](repeating: tag, count: 188)
+            ts[0] = 0x47
+            ts[1] = UInt8(packet)
+            data.append(contentsOf: ts)
+        }
+        return data
+    }
+
+    private func serve(_ conn: Int32) {
+        defer { close(conn) }
+        var request = Data()
+        var buf = [UInt8](repeating: 0, count: 4096)
+        while request.range(of: Data("\r\n\r\n".utf8)) == nil {
+            let n = read(conn, &buf, buf.count)
+            guard n > 0 else { return }
+            request.append(contentsOf: buf[0..<n])
+            if request.count > 64 * 1024 { return }
+        }
+        guard let head = String(data: request, encoding: .utf8),
+              let line = head.components(separatedBy: "\r\n").first else { return }
+        let parts = line.components(separatedBy: " ")
+        guard parts.count >= 2 else { return }
+        let path = String(parts[1].dropFirst())
+
+        lock.lock()
+        while held.contains(path), !stopped { lock.wait() }
+        lock.unlock()
+
+        let body: Data
+        switch path {
+        case "master.m3u8":
+            body = Data("""
+            #EXTM3U
+            #EXT-X-MEDIA:TYPE=AUDIO,GROUP-ID="a",NAME="de",LANGUAGE="de",DEFAULT=YES,AUTOSELECT=YES,URI="a.m3u8"
+            #EXT-X-STREAM-INF:BANDWIDTH=1800000,CODECS="avc1.4d401e,mp4a.40.2",RESOLUTION=720x576,AUDIO="a"
+            v.m3u8
+
+            """.utf8)
+        case "v.m3u8": body = mediaPlaylist(prefix: "v")
+        case "a.m3u8": body = mediaPlaylist(prefix: "a")
+        default:
+            guard path.hasSuffix(".ts"), let index = Int(path.dropFirst(1).dropLast(3)) else {
+                let missing = "HTTP/1.1 404 Not Found\r\nContent-Length: 0\r\nConnection: close\r\n\r\n"
+                _ = missing.withCString { write(conn, $0, strlen($0)) }
+                return
+            }
+            body = segment(tag: UInt8(truncatingIfNeeded: (path.hasPrefix("a") ? 100 : 0) + index))
+        }
+        let header = "HTTP/1.1 200 OK\r\nContent-Length: \(body.count)\r\nConnection: close\r\n\r\n"
+        _ = header.withCString { write(conn, $0, strlen($0)) }
+        body.withUnsafeBytes { raw in
+            var offset = 0
+            while offset < raw.count {
+                let n = write(conn, raw.baseAddress!.advanced(by: offset), raw.count - offset)
+                guard n > 0 else { return }
+                offset += n
+            }
+        }
+    }
+}
+
+/// Reads a reader on a thread of its own, optionally stopping at a byte budget WITHOUT parking (a
+/// consumer that holds what it has and asks for no more, like the cutter's lookahead).
+private final class ReaderDrain: @unchecked Sendable {
+    private let lock = NSLock()
+    private var _bytes = 0
+    var bytes: Int { lock.lock(); defer { lock.unlock() }; return _bytes }
+
+    init(_ reader: IOReader, stopAfter budget: Int? = nil) {
+        Thread.detachNewThread { [self] in
+            var buf = [UInt8](repeating: 0, count: 64)
+            while true {
+                if let budget, bytes >= budget { return }
+                let want = budget.map { min(buf.count, $0 - bytes) } ?? buf.count
+                let n = buf.withUnsafeMutableBufferPointer { reader.read($0.baseAddress, size: Int32(want)) }
+                if n <= 0 { return }
+                lock.lock()
+                _bytes += Int(n)
+                lock.unlock()
+            }
+        }
+    }
+}
+
+final class Issue684PumpJoinSpentTests: XCTestCase {
+
+    private func waitUntil(_ what: String, timeout: TimeInterval = 60, _ condition: () -> Bool) {
+        let deadline = Date().addingTimeInterval(timeout)
+        while !condition() {
+            if Date() >= deadline { return XCTFail("timed out waiting for: \(what)") }
+            usleep(2_000)
+        }
+    }
+
+    // MARK: - The rule
+
+    func testVideoOnlyIsTheVideoReaderParkedOnACommittedJoin() {
+        XCTAssertTrue(HLSLiveIngestReader.pumpJoinIsSpent(main: (true, true), companion: nil))
+        XCTAssertFalse(HLSLiveIngestReader.pumpJoinIsSpent(main: (true, false), companion: nil))
+        XCTAssertFalse(HLSLiveIngestReader.pumpJoinIsSpent(main: (false, true), companion: nil),
+                       "parked between two segments of a join still arriving")
+    }
+
+    /// The reported shape: the audio rendition ends before the video does, so the cutter parks on
+    /// the AUDIO reader while video bytes are still queued. That is a spent join.
+    func testShortAudioParksTheCutterOnTheCompanion() {
+        XCTAssertTrue(HLSLiveIngestReader.pumpJoinIsSpent(
+            main: (committed: true, parked: false), companion: (started: true, committed: true, parked: true)))
+    }
+
+    /// The audio playlist publishes a little after the video one, so at the join the companion's
+    /// batch is still arriving while the cutter already sits on an empty reader.
+    func testAudioPublishedLaterIsNotSpentUntilItsOwnJoinIsCommitted() {
+        XCTAssertFalse(HLSLiveIngestReader.pumpJoinIsSpent(
+            main: (true, true), companion: (started: true, committed: false, parked: false)))
+        XCTAssertFalse(HLSLiveIngestReader.pumpJoinIsSpent(
+            main: (true, false), companion: (started: true, committed: false, parked: true)),
+            "parked on the companion between two of its join segments")
+        XCTAssertTrue(HLSLiveIngestReader.pumpJoinIsSpent(
+            main: (true, true), companion: (started: true, committed: true, parked: false)))
+    }
+
+    func testACompanionNobodyReadsDoesNotCount() {
+        XCTAssertTrue(HLSLiveIngestReader.pumpJoinIsSpent(
+            main: (true, true), companion: (started: false, committed: false, parked: false)))
+    }
+
+    func testBothCommittedAndNeitherParkedIsACutterStillWorking() {
+        XCTAssertFalse(HLSLiveIngestReader.pumpJoinIsSpent(
+            main: (true, false), companion: (started: true, committed: true, parked: false)))
+    }
+
+    // MARK: - The reader itself
+
+    /// A consumer parked on an empty reader is not a spent join while the join batch is still being
+    /// fetched: the third segment is held at the origin, the reader has drained the first two and
+    /// waits, and the fact has to stay false until that segment is committed and drained too.
+    func testReaderIsNotSpentWhileItsJoinBatchIsStillArriving() throws {
+        let origin = try XCTUnwrap(HeldSegmentOrigin(hold: ["v2.ts"]))
+        defer { origin.stop() }
+        let reader = HLSLiveIngestReader(playlistURL: origin.url("v.m3u8"))
+        defer { reader.close() }
+        XCTAssertFalse(reader.joinIsSpent, "nothing has been read")
+
+        let drain = ReaderDrain(reader)
+        let two = 2 * HeldSegmentOrigin.segmentBytes
+        waitUntil("two segments drained and the consumer parked") {
+            drain.bytes == two && reader.pumpJoinState.parked
+        }
+        XCTAssertFalse(reader.pumpJoinState.committed)
+        XCTAssertFalse(reader.joinIsSpent, "empty and parked, but the join is not all here")
+
+        origin.release("v2.ts")
+        waitUntil("the join to be spent") { reader.joinIsSpent }
+        XCTAssertEqual(drain.bytes, 3 * HeldSegmentOrigin.segmentBytes)
+        XCTAssertTrue(reader.pumpJoinState.committed)
+    }
+
+    /// Demuxed audio, the reported shape: the cutter holds video it cannot place and waits on the
+    /// audio reader. The video reader is never parked.
+    func testReaderWithACompanionIsSpentWhenTheCutterParksOnTheAudio() throws {
+        let origin = try XCTUnwrap(HeldSegmentOrigin(hold: []))
+        defer { origin.stop() }
+        let reader = HLSLiveIngestReader(playlistURL: origin.url("master.m3u8"))
+        defer { reader.close() }
+
+        // The video side takes one segment and asks for no more: two stay queued, nobody is parked.
+        let video = ReaderDrain(reader, stopAfter: HeldSegmentOrigin.segmentBytes)
+        waitUntil("the companion to be installed") { reader.companionAudioReader != nil }
+        waitUntil("the video join to be committed") { reader.pumpJoinState.committed }
+        waitUntil("the video side to stop") { video.bytes == HeldSegmentOrigin.segmentBytes }
+        XCTAssertFalse(reader.pumpJoinState.parked)
+        XCTAssertFalse(reader.joinIsSpent, "video queued, nobody waiting, audio not yet read")
+
+        let companion = try XCTUnwrap(reader.companionAudioReader)
+        let audio = ReaderDrain(companion)
+        waitUntil("the join to be spent on the audio side") { reader.joinIsSpent }
+        XCTAssertEqual(audio.bytes, 3 * HeldSegmentOrigin.segmentBytes)
+        XCTAssertFalse(reader.pumpJoinState.parked, "the video reader never parked, and it did not have to")
+    }
+
+    /// Audio published a moment after video: the cutter has drained the video and parked on it
+    /// while the audio rendition's last join segment is still at the origin.
+    func testReaderWithACompanionWaitsForTheAudioJoinToBeCommitted() throws {
+        let origin = try XCTUnwrap(HeldSegmentOrigin(hold: ["a2.ts"]))
+        defer { origin.stop() }
+        let reader = HLSLiveIngestReader(playlistURL: origin.url("master.m3u8"))
+        defer { reader.close() }
+
+        let video = ReaderDrain(reader)
+        waitUntil("the companion to be installed") { reader.companionAudioReader != nil }
+        let companion = try XCTUnwrap(reader.companionAudioReader)
+        let audio = ReaderDrain(companion)
+        let three = 3 * HeldSegmentOrigin.segmentBytes
+        waitUntil("the video drained and parked, the audio parked two segments in") {
+            video.bytes == three && reader.pumpJoinState.parked
+                && audio.bytes == 2 * HeldSegmentOrigin.segmentBytes
+        }
+        XCTAssertFalse(reader.joinIsSpent, "the audio rendition's join is not all here")
+
+        origin.release("a2.ts")
+        waitUntil("the join to be spent") { reader.joinIsSpent }
+        XCTAssertEqual(audio.bytes, three)
+    }
+
+    // MARK: - The gate asks in the right order
+
+    /// The fact is monotone, so a snapshot taken AFTER it read true holds everything the join will
+    /// cut. Taken before, the cutter can append its last segment and park between the two reads and
+    /// the seal is paid from the sum without it. A race two reads wide is not something a policy
+    /// test can stage, so this reads the site, as `Issue588RefusalLatchLifetimeTests` does.
+    func testTheGateAsksSpentBeforeItTakesTheSnapshot() throws {
+        let source = URL(fileURLWithPath: #filePath)
+            .deletingLastPathComponent().deletingLastPathComponent().deletingLastPathComponent()
+            .appendingPathComponent("Sources/AetherEngine/Video/VideoSegmentProvider.swift")
+        let text = try String(contentsOf: source, encoding: .utf8)
+        let gateStart = try XCTUnwrap(text.range(of: "func waitForFirstLiveSegment(timeout: TimeInterval) -> Bool {"))
+        let gateEnd = try XCTUnwrap(text.range(of: "private func accountForFirstServe(",
+                                               range: gateStart.upperBound..<text.endIndex))
+        let lines = text[gateStart.upperBound..<gateEnd.lowerBound]
+            .split(separator: "\n").map { $0.trimmingCharacters(in: .whitespaces) }
+        let snapshots = lines.indices.filter { lines[$0].contains("= liveCushionSnapshot()") }
+        XCTAssertEqual(snapshots.count, 2, "the loop's read and the timed-out re-read")
+        for index in snapshots {
+            XCTAssertTrue(lines[index - 1].contains("liveCadencePolicy?.joinIsSpent"),
+                          "snapshot at gate line \(index) is not preceded by the spent read: \(lines[index - 1])")
+        }
+    }
+}

From 5424e29021845acced4e5432480aad41796e2e07 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Thu, 1 Oct 2026 23:36:39 +0200
Subject: [PATCH 280/359] docs(live): the spent join with a demuxed audio
 rendition, and a join slower than the grace (#684)

Two shapes the join-bound seal has to be read with. With a companion
audio rendition the fact is the cutter's, both join batches committed
and either reader dry, measured back at 7.25.1's first picture in six
cells. And a join that outlasts the fastZap grace takes the bounded
start before it is spent, seals the full upstream-segment value over a
window under its holdback and draws a -16832 warning, measured not
worse than 7.25.1.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/api.md | 11 +++++++++++
 docs/cli.md |  2 +-
 2 files changed, 12 insertions(+), 1 deletion(-)

diff --git a/docs/api.md b/docs/api.md
index d9091ed8e..c398225ff 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -725,6 +725,17 @@ still not read. What it gets is bounded three ways:
   (`of which the join pays 5s of 6s (16.000s cut of the 18.000s it listed)`), and "the join has no
   more to give" is a fact the reader states (its join batch is handed over and its consumer is
   waiting), not arithmetic on EXTINF, which a playlist that rounds its durations up would fail.
+  With a demuxed audio rendition the fact is the cutter's rather than one reader's: both join
+  batches handed over and the cutter waiting on either of them, because an audio rendition whose
+  segments end a little before the video's runs dry first and the video reader is then never the
+  one being waited on (three runs per arm on three listed segments, audio aligned and audio 0.2 s
+  short: first picture 0.18 to 0.21 s against 0.17 to 0.36 s on 7.25.1, TD 5 on 6 s and 9 on 10 s
+  under both profiles). A join that is SLOWER than the `.fastZap` grace, a single-connection
+  provider or a slow link, takes the bounded start before it is spent and then seals the full
+  value (6 or 10, not 5 or 9) over a window shorter than its holdback, which AVPlayer notes with a
+  `-16832` warning at the start; measured one request at a time behind a 4 to 5 Mbit/s link that
+  start is not worse than 7.25.1's (first picture 5.05 to 6.08 s against 7.05 to 8.26 s, no
+  `-12888` where 7.25.1 drew 1 to 3).
 - **By a ceiling.** Segments longer than 10 s (`LiveEdgePolicy.upstreamSegmentSealCeilingSeconds`) are
   not asked for whole: a 20 s one seals 14, as it did before, because the live-only window is 60 s.
 - **Never under what it was.** Where the old value already covered the segment nothing moves: 2 s
diff --git a/docs/cli.md b/docs/cli.md
index 3c39cb54b..bf7f8d426 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -748,7 +748,7 @@ One 180 s run per arm on that origin, same deliveries (four gaps above 9.0 s in
 
 That is fewer, not none, and it is the honest size of what a seal one second higher buys: 7.5 s of patience still loses to a 9 s gap, but the 15 s holdback leaves 5.7 s at the low point where 12 s left 2.7 s, which is the difference between surviving AVPlayer's skipped reload and not. A join one segment deeper (TD 6, holdback 18 s) drew none of either in three such runs and was not shipped: it cost 3.81 s against 4.98 s to the first picture behind an 8 Mbit/s link. The device capture this came from had 10 of its 110 gaps above 9 s and 5 above 12 s, so the field expectation is fewer `-12888` and far fewer stalls, not zero.
 
-**Whether a join is spent is a fact, not arithmetic.** The seal may only be taken short once the join has nothing more to give, and "cut content plus one segment reaches the summed EXTINF" is not that fact: `--dur 6.3` over 6 s of media never adds up, and a first version built on the sum sealed the full value there and took the bounded start (2.23 s to first picture against 0.20 s). The reader states it instead: the whole join batch is committed, its FIFO is empty, and the cutter is parked waiting for the next delivery. Three runs per arm on each inflated shape with three segments listed: served at once in all six (0.000 to 0.034 s of hold), TD 5 on 6 s media and TD 9 on 10 s.
+**Whether a join is spent is a fact, not arithmetic.** The seal may only be taken short once the join has nothing more to give, and "cut content plus one segment reaches the summed EXTINF" is not that fact: `--dur 6.3` over 6 s of media never adds up, and a first version built on the sum sealed the full value there and took the bounded start (2.23 s to first picture against 0.20 s). The reader states it instead: the whole join batch is committed, its FIFO is empty, and the cutter is parked waiting for the next delivery. Three runs per arm on each inflated shape with three segments listed: served at once in all six (0.000 to 0.034 s of hold), TD 5 on 6 s media and TD 9 on 10 s. Two more shapes belong to the same fact. A demuxed audio rendition (run the origin twice, video-only and audio-only segments behind a master) makes the cutter park on the AUDIO reader when the audio ends a little before the video, so the fact is stated for the cutter and not for the video reader: both join batches committed and either reader dry. Read off the video reader alone it never became true, 2.2 s to first picture under `.fastZap` and 10.4 s under `.standard`; now 0.18 to 0.21 s in all six cells (6 s and 10 s `.fastZap`, 10 s `.standard`, audio aligned and 0.2 s short, three runs each), as on 7.25.1. And a join slower than the `.fastZap` grace (`play --max-concurrent-requests 1` behind `--rate-kbps 4000`) is served by the bounded start before it is spent, seals the full 6 or 10 over a window under its holdback and draws a `-16832` warning at the start: first picture 5.05 to 6.08 s against 7.05 to 8.26 s on 7.25.1, which still pays the second grace there, and no `-12888` against 1 to 3.
 
 **The gate held the second playlist request too.** AVPlayer opens with two `/media.m3u8` requests, each re-enters `waitForFirstLiveSegment`, and on a bounded start each waited its own grace (`GET /media.m3u8` at 2.81 s, `GET /init.mp4` at 4.83 s). On an ingest the gate now opens for good once a manifest has gone out. On a source the engine cuts itself it does not: that second grace is the "+2.07 s at the picture" of the AE#594 table above, and removing it there also leaves the session up to 2 s closer to the producing edge, which is that issue's open question. The raw-TS control (`live --fast-zap --realtime --preroll 0`, two seeds, two runs per arm) reads the same in both arms: first manifest at 3.84 to 3.96 s, `init.mp4` at 6.11 to 6.33 s, first picture at 6.20 to 6.58 s, playhead 6.3 to 6.8 s behind the wall clock. The AE#594 table stands as printed.
 

From d4891e3454e67219589cf74f2e445ef0c8ae1ab8 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 2 Oct 2026 04:49:41 +0200
Subject: [PATCH 281/359] fix(live): a mixed-length upstream joins the same
 depth in either phase (#684)

The channel this issue was reported on alternates 6 s and 4 s
segments. The join counts seconds back from the newest segment, so its
depth depended on which of the two was newest: 4 + 6 + 4 is under the
16 s coverage target and a fourth segment is taken (20 s listed, 18 s
cut, seal 6), while 6 + 4 + 6 meets it at three (16 s listed, 14 s
cut, seal 4, 7.25.1's value and its stalls). About four tunes in ten
landed in the second phase and got none of the fix.

When the joined segments differ in length by more than a second and
their summed EXTINF is not above the holdback of the seal the longest
listed segment asks for, the join takes one segment more, once. On the
reported shape that is the short segment the other phase already
loads. Uniform upstreams are outside the rule and keep the exact
7.24.0 join (three 6 s or 10 s segments, seal 5 or 9).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../IO/HLSIngest/HLSPlaylistTracker.swift     |  38 ++++++
 .../Issue684MixedLengthJoinTests.swift        | 121 ++++++++++++++++++
 2 files changed, 159 insertions(+)
 create mode 100644 Tests/AetherEngineTests/Issue684MixedLengthJoinTests.swift

diff --git a/Sources/AetherEngine/IO/HLSIngest/HLSPlaylistTracker.swift b/Sources/AetherEngine/IO/HLSIngest/HLSPlaylistTracker.swift
index 5d0f18c3c..4f3f1a44a 100644
--- a/Sources/AetherEngine/IO/HLSIngest/HLSPlaylistTracker.swift
+++ b/Sources/AetherEngine/IO/HLSIngest/HLSPlaylistTracker.swift
@@ -54,6 +54,39 @@ struct HLSPlaylistTracker {
             + min(longest, openGOPMarginSeconds)
     }
 
+    /// AE#684: on an upstream of MIXED segment lengths, the join takes one segment more when what it
+    /// would otherwise list cannot pay the seal its longest segment asks for.
+    ///
+    /// The coverage loop counts seconds from the newest segment back, so on an upstream alternating
+    /// 6 s and 4 s segments (the channel this issue was reported on) the depth depends on which one
+    /// happens to be newest: `4 + 6 + 4` is under the 16 s target and a fourth is taken (20 s listed,
+    /// 18 s cut, seal 6), while `6 + 4 + 6` meets it at three (16 s listed, 14 s cut, seal 4, which
+    /// is 7.25.1's value and its stalls). About four tunes in ten land in the second phase, and the
+    /// same channel then behaves differently from one zap to the next.
+    ///
+    /// The rule, exactly: the joined segments differ in length by more than
+    /// `mixedLengthSpreadSeconds`, AND their summed EXTINF is not above the holdback of the seal the
+    /// longest listed segment asks for (`3 x` it; the last GOP stays open, so a join has to list MORE
+    /// than a holdback to pay for it). Then one more segment, once. It costs that phase one
+    /// additional segment at the join, the short one on the reported shape, which the other phase
+    /// already loads.
+    ///
+    /// Uniform upstreams are deliberately outside it. There the join keeps the depth it had in
+    /// 7.24.0 and the seal is what that depth pays (5 on 6 s segments, 9 on 10 s), because a fourth
+    /// full-length segment on EVERY tune is the cost AE#678 declined.
+    static func mixedLengthJoinTakesOneMore(joinedDurations: [Double], longestListed: Double) -> Bool {
+        guard let longest = joinedDurations.max(), let shortest = joinedDurations.min(),
+              longest - shortest > mixedLengthSpreadSeconds, longestListed > 0 else { return false }
+        let asked = max(LiveEdgePolicy.targetDurationForCadence(longestListed),
+                        LiveEdgePolicy.targetDurationForUpstreamSegment(longestListed))
+        return joinedDurations.reduce(0, +) <= LiveEdgePolicy.holdBackSeconds(targetDuration: asked)
+    }
+
+    /// Lengths closer than this are one length. A packager's EXTINF wanders by frames around its
+    /// nominal value (5.96, 6.04), and that is a uniform upstream; a whole second is the resolution a
+    /// TARGETDURATION is taken at.
+    static let mixedLengthSpreadSeconds: Double = 1.0
+
     /// Longest GOP the join margin plans for. IPTV and broadcast GOPs run 0.5 to 4 s; a longer one
     /// only costs the bounded start's grace, which is what every join paid before AE#678.
     static let openGOPMarginSeconds: Double = 4
@@ -98,6 +131,11 @@ struct HLSPlaylistTracker {
                 taken += 1
                 seconds += segment.duration
             }
+            if taken < limit, taken < playlist.segments.count,
+               Self.mixedLengthJoinTakesOneMore(joinedDurations: playlist.segments.suffix(taken).map(\.duration),
+                                                longestListed: playlist.segments.map(\.duration).max() ?? 0) {
+                taken += 1
+            }
             return windowEnd &- taken
         }
 
diff --git a/Tests/AetherEngineTests/Issue684MixedLengthJoinTests.swift b/Tests/AetherEngineTests/Issue684MixedLengthJoinTests.swift
new file mode 100644
index 000000000..d04a163a2
--- /dev/null
+++ b/Tests/AetherEngineTests/Issue684MixedLengthJoinTests.swift
@@ -0,0 +1,121 @@
+// Tests/AetherEngineTests/Issue684MixedLengthJoinTests.swift
+// AE#684, the reporter's own channel: its upstream alternates 6 s and 4 s segments. The join counts
+// seconds back from the newest segment, so its depth depended on which of the two was newest. With a
+// 4 s one newest, `4 + 6 + 4` is under the 16 s coverage target and a fourth segment is taken: 20 s
+// listed, 18 s cut, seal 6. With a 6 s one newest, `6 + 4 + 6` meets the target at three: 16 s listed,
+// 14 s cut, seal 4, 7.25.1's value and its stalls. Measured on `--durs 6,4 --window 8`: `--prefill 8`
+// sealed 6 with no -12888 and no stall, `--prefill 7` sealed 4 in both arms and stalled as before.
+// About four tunes in ten land in that phase.
+//
+// On an upstream of mixed segment lengths the join takes one segment more when what it lists cannot pay
+// the seal its longest segment asks for. Uniform upstreams keep the exact 7.24.0 join.
+import XCTest
+@testable import AetherEngine
+
+final class Issue684MixedLengthJoinTests: XCTestCase {
+
+    /// The join a fresh tracker takes from a playlist listing these durations, oldest first.
+    private func joined(_ durations: [Double]) -> [Double] {
+        var tracker = HLSPlaylistTracker()
+        let playlist = HLSMediaPlaylist(
+            targetDuration: (durations.max() ?? 0).rounded(.up),
+            mediaSequence: 100,
+            segments: durations.enumerated().map {
+                HLSMediaSegment(uri: "s\($0.offset)", duration: $0.element, discontinuityBefore: false)
+            },
+            hasEndList: false,
+            isEncrypted: false,
+            hasUnsupportedEncryption: false,
+            hasMap: false
+        )
+        return tracker.newSegments(in: playlist).map(\.duration)
+    }
+
+    /// What the gate seals from a spent join of these segments at 2 s GOPs under `.fastZap`.
+    private func seal(_ join: [Double]) -> Int {
+        let longest = join.max() ?? 0
+        let cut = join.reduce(0, +) - 2.0
+        let full = LiveEdgePolicy.targetDurationSeconds(maxSegmentDuration: 2.0, cutTargetSeconds: 0.5,
+                                                        cadenceFloorSeconds: longest,
+                                                        upstreamSegmentSeconds: longest)
+        let base = LiveEdgePolicy.targetDurationSeconds(maxSegmentDuration: 2.0, cutTargetSeconds: 0.5,
+                                                        cadenceFloorSeconds: longest)
+        return LiveEdgePolicy.targetDurationTheJoinCanPay(full: full, withoutUpstreamSegment: base,
+                                                          finalizedSeconds: cut)
+    }
+
+    // MARK: - Both phases of the reported channel
+
+    func testSixFourAlternationJoinsFourSegmentsInBothPhases() {
+        let newestIsFour = joined([6, 4, 6, 4, 6, 4, 6, 4])
+        XCTAssertEqual(newestIsFour, [6, 4, 6, 4], "under the coverage target at three, as before")
+        let newestIsSix = joined([4, 6, 4, 6, 4, 6, 4, 6])
+        XCTAssertEqual(newestIsSix, [4, 6, 4, 6], "three met the target; the fourth is this rule's")
+        XCTAssertEqual(seal(newestIsFour), 6)
+        XCTAssertEqual(seal(newestIsSix), 6)
+    }
+
+    /// The phase is where the tune lands, not how the playlist began.
+    func testFourSixOrderIsTheSameChannel() {
+        XCTAssertEqual(joined([4, 6, 4, 6, 4, 6, 4]).reduce(0, +), 20)
+        XCTAssertEqual(joined([6, 4, 6, 4, 6, 4, 6]).reduce(0, +), 20)
+        XCTAssertEqual(joined([4, 6, 4, 6, 4, 6, 4]).count, 4)
+        XCTAssertEqual(joined([6, 4, 6, 4, 6, 4, 6]).count, 4)
+    }
+
+    func testSixSixFourPatternSealsSixInEveryPhase() {
+        let phases: [[Double]] = [
+            [6, 6, 4, 6, 6, 4, 6, 6, 4],
+            [6, 4, 6, 6, 4, 6, 6, 4, 6],
+            [4, 6, 6, 4, 6, 6, 4, 6, 6],
+        ]
+        for phase in phases {
+            let join = joined(phase)
+            XCTAssertEqual(join.count, 4, "\(phase)")
+            XCTAssertEqual(seal(join), 6, "\(phase)")
+        }
+    }
+
+    // MARK: - Uniform upstreams keep the 7.24.0 join
+
+    func testUniformSixAndTenSecondJoinsAreUnchanged() {
+        XCTAssertEqual(joined(Array(repeating: 6, count: 8)), [6, 6, 6])
+        XCTAssertEqual(joined(Array(repeating: 10, count: 8)), [10, 10, 10])
+        XCTAssertEqual(joined(Array(repeating: 2, count: 8)), [2, 2, 2, 2])
+        XCTAssertEqual(seal([6, 6, 6]), 5)
+        XCTAssertEqual(seal([10, 10, 10]), 9)
+    }
+
+    /// EXTINF that wanders by frames around its nominal value is a uniform upstream.
+    func testFrameJitterInExtinfIsNotMixedLength() {
+        XCTAssertEqual(joined([6.0, 5.96, 5.92, 6.0, 5.96, 5.92, 6.0, 5.96]).count, 3)
+        XCTAssertFalse(HLSPlaylistTracker.mixedLengthJoinTakesOneMore(
+            joinedDurations: [6.0, 5.96, 5.92], longestListed: 6.0))
+        XCTAssertFalse(HLSPlaylistTracker.mixedLengthJoinTakesOneMore(
+            joinedDurations: [6, 5, 6], longestListed: 6), "exactly the spread is still one length")
+    }
+
+    // MARK: - The rule's edges
+
+    /// A mixed join that already lists more than the holdback it is asked for takes nothing more.
+    func testAMixedJoinThatAlreadyPaysIsLeftAlone() {
+        XCTAssertFalse(HLSPlaylistTracker.mixedLengthJoinTakesOneMore(
+            joinedDurations: [6, 4, 6, 4], longestListed: 6))
+        XCTAssertTrue(HLSPlaylistTracker.mixedLengthJoinTakesOneMore(
+            joinedDurations: [4, 6, 6], longestListed: 6))
+        XCTAssertTrue(HLSPlaylistTracker.mixedLengthJoinTakesOneMore(
+            joinedDurations: [6, 6, 6.5], longestListed: 6.5) == false, "spread under a second")
+    }
+
+    /// One more, once, and never past what the playlist offers or the eviction margin allows.
+    func testTheExtraSegmentRespectsTheWindow() {
+        XCTAssertEqual(joined([4, 6, 4, 6]), [6, 4, 6], "four listed: the oldest stays where it is")
+        XCTAssertEqual(joined([6, 4, 6]), [6, 4, 6], "three listed: all of them, nothing more to take")
+        XCTAssertEqual(joined([6, 4, 6, 4, 6]).count, 4)
+    }
+
+    /// A short last segment before a boundary is mixed too, and is already deep enough.
+    func testAShortNewestSegmentDoesNotDeepenTheJoinFurther() {
+        XCTAssertEqual(joined([6, 6, 6, 6, 6, 3]), [6, 6, 6, 3])
+    }
+}

From c243fa2d20820bc8b9e0fb446f5d7b1a9f561460 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 2 Oct 2026 04:49:41 +0200
Subject: [PATCH 282/359] fix(live): the merged read asserts that one thread
 reads both readers (#684)

pumpJoinIsSpent takes "the cutter is parked on either reader" to mean
that nothing more is cut. That holds only while one thread reads the
main and the side reader in turn, which was a comment. It is a debug
assertion at the merged read now.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 Sources/AetherEngine/Video/HLSSegmentProducer.swift | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/Sources/AetherEngine/Video/HLSSegmentProducer.swift b/Sources/AetherEngine/Video/HLSSegmentProducer.swift
index 4e9839af0..a1a5dfc80 100644
--- a/Sources/AetherEngine/Video/HLSSegmentProducer.swift
+++ b/Sources/AetherEngine/Video/HLSSegmentProducer.swift
@@ -213,6 +213,8 @@ final class HLSSegmentProducer: @unchecked Sendable {
     var onLiveSegmentSound: (@Sendable (Int, Double, Double) -> Void)?
     /// Keyed by segment index; a nil value is a segment cut with no audio packet in it.
     private var liveSegmentSoundByIndex: [Int: (first: Double, last: Double)?] = [:]
+    /// AE#684: set for the length of one merged read, so a second reader thread trips the assertion there.
+    private var mergedReadInFlight = false
 
     /// AE#443: the resident segment count the live runaway park may use, from the session that owns the
     /// window (`VideoSegmentProvider.liveResidentParkCap`). Unset leaves the static floor, which is the
@@ -2789,6 +2791,11 @@ final class HLSSegmentProducer: @unchecked Sendable {
     }
 
     private func readNextSourcePacketMerged() throws -> (packet: UnsafeMutablePointer<AVPacket>, origin: PacketOrigin)? {
+        // AE#684: `HLSLiveIngestReader.pumpJoinIsSpent` reads "parked on EITHER reader" as "nothing
+        // more is cut", which holds only while one thread reads both of them in turn.
+        assert(!mergedReadInFlight, "the main and side readers are read by one thread, one at a time")
+        mergedReadInFlight = true
+        defer { mergedReadInFlight = false }
         guard let side = sideAudioDemuxer else {
             guard let packet = try demuxer.readPacket() else { return nil }
             boundSourceTimestamps(packet)

From 731771cf8d730dd65fa17064ee5aa42d193d4f06 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 2 Oct 2026 05:26:56 +0200
Subject: [PATCH 283/359] docs(live): mixed-length upstreams, the
 single-connection start, and what uniform means (#684)

"A 6 s provider seals 5" is true of uniform segment lengths only; the
docs now say what a mixed-length upstream gets (6 in both phases, with
one additional short segment at the join on about four tunes in ten)
and that 3 s providers with 1 s GOPs are unchanged at 2. "The join and
the time to the first picture are what they were" is qualified: a host
with fewer parallel requests than the join has segments starts later
than before (2.79 to 3.08 s against 3.27 to 3.49 s, one request at a
time behind 14 Mbit/s).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/api.md | 40 +++++++++++++++++++++++++++++-----------
 docs/cli.md | 13 ++++++++++++-
 2 files changed, 41 insertions(+), 12 deletions(-)

diff --git a/docs/api.md b/docs/api.md
index c398225ff..1e4c341d0 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -716,12 +716,21 @@ seal asks for is the longest segment the upstream has served, whole, where `ceil
 to leave the client a patience of exactly one delivery. The upstream's advertised target duration is
 still not read. What it gets is bounded three ways:
 
-- **By the join, which is not deepened for it.** A seal is a holdback of `3 x` itself, and the join is
-  the three upstream segments it was before (one more would be one more download before the first
-  picture on every zap, which AE#678 measured and declined). Their last GOP stays open until the next
-  delivery, so three 6 s segments are 18 s joined and 16 s cut: the seal is 5, the largest value whose
-  holdback that window holds, not 6. Three 10 s segments cut 28 s and seal 9. A join that does cover
-  the full holdback (segments of mixed length, say) seals the full value. The seal line says which
+- **By the join, which is not deepened for it on an upstream of uniform segment length.** A seal is a
+  holdback of `3 x` itself, and the join there is the three upstream segments it was before (one more
+  would be one more download before the first picture on every zap, which AE#678 measured and
+  declined). Their last GOP stays open until the next delivery, so three 6 s segments are 18 s joined
+  and 16 s cut: the seal is 5, the largest value whose holdback that window holds, not 6. Three 10 s
+  segments cut 28 s and seal 9. An upstream of MIXED segment lengths is the one exception, because
+  there the join's depth used to depend on which segment happened to be newest: alternating 6 s and
+  4 s segments joined four (20 s listed, 18 s cut, seal 6) with a 4 s one newest and three (16 s
+  listed, 14 s cut, seal 4, as in 7.25.1) with a 6 s one newest, so the same channel behaved
+  differently from one tune to the next. When the joined segments differ by more than a second and
+  their summed EXTINF is not above the holdback the longest listed segment asks for, the join takes
+  one segment more, once; both phases then join four and seal 6. That costs the three-segment phase
+  (about four tunes in ten on that shape) one additional short segment at the join, which the other
+  six already load: 3.47 s to 4.21 s to first picture behind an 8 Mbit/s link, median of five, against
+  4.27 s in the other phase on either build. The seal line says what was paid
   (`of which the join pays 5s of 6s (16.000s cut of the 18.000s it listed)`), and "the join has no
   more to give" is a fact the reader states (its join batch is handed over and its consumer is
   waiting), not arithmetic on EXTINF, which a playlist that rounds its durations up would fail.
@@ -741,11 +750,20 @@ still not read. What it gets is bounded three ways:
 - **Never under what it was.** Where the old value already covered the segment nothing moves: 2 s
   segments keep 2 and a 6 s holdback, and `.standard` keeps its 6 on anything up to 6 s.
 
-So on a 6 s provider under `.fastZap` the seal goes from 4 to 5 (holdback 12 to 15 s), and on a 10 s
-provider under either profile from 7 to 9 (21 to 27 s). The join, and with it the time to the first
-picture, is what it was: behind an 8 Mbit/s link, three runs per arm, 3.81 to 4.04 s before and 3.80 to
-3.85 s after on 6 s segments, 6.15 to 6.36 s and 6.18 to 6.28 s on 10 s ones. The cost is standing
-latency, 3 s more behind the upstream's edge on a 6 s provider and 6 s on a 10 s one.
+So on a provider of uniform 6 s segments under `.fastZap` the seal goes from 4 to 5 (holdback 12 to
+15 s), on a uniform 10 s one under either profile from 7 to 9 (21 to 27 s), and on mixed 6 s / 4 s
+segments from 4 to 6 (12 to 18 s) in both phases. A provider of 3 s segments with 1 s GOPs is
+unchanged at 2: three joined segments cut 8 s, which pays for no more, so the patience of one
+delivery this issue is about stays as it is there. On uniform upstreams the join, and with a host that
+fetches in parallel the time to the first picture, is what it was: behind an 8 Mbit/s link, three runs
+per arm, 3.81 to 4.04 s before and 3.80 to 3.85 s after on 6 s segments, 6.15 to 6.36 s and 6.18 to
+6.28 s on 10 s ones. A host that allows fewer parallel requests than the join has segments
+(`maxConcurrentSourceRequests` of 3 or less) sees its first picture later than before, because the
+gate now waits for the join to be handed over where it used to serve at 12 s of cut content: one
+request at a time behind 14 Mbit/s on the mixed shape, three runs per arm, 2.79 to 3.08 s before and
+3.27 to 3.28 s after in the four-segment phase, 2.80 to 2.83 s and 3.44 to 3.49 s in the phase that
+now also loads the extra segment. The other cost is standing latency: 3 s more behind the upstream's
+edge on uniform 6 s segments, 6 s on mixed 6 s / 4 s and on 10 s ones.
 
 Measured on loopback against `Scripts/hls-burst-origin.py` (deliveries 3 to 9.3 s apart on 6 s
 segments), 60 s per run, three runs per arm and row, 7.25.1 against this; first picture is 0.17 to
diff --git a/docs/cli.md b/docs/cli.md
index bf7f8d426..1a4f02d81 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -730,7 +730,7 @@ That cycle makes the origin's own gaps run 3.6 to 8.3 s. On the loopback they ar
 
 What that costs is not the `-12888` itself but what AVPlayer does next: it skips a reload. Measured here and on an Apple TV alike, polls every 2.00 s, then 4.00 s (macOS) or 5.03 s (tvOS) of nothing after the error, and the stall lands inside that hole with the next delivery already listed 1.9 to 2.6 s earlier.
 
-The seal now asks for the upstream segment whole and takes as much of it as the join pays for. The join itself is not deepened (one more upstream segment would be one more download before the first picture on every zap, which AE#678 measured and declined), so three 6 s segments are 18 s joined, 16 s cut, and a seal of 5:
+The seal now asks for the upstream segment whole and takes as much of it as the join pays for. On an upstream of uniform segment length the join itself is not deepened (one more upstream segment would be one more download before the first picture on every zap, which AE#678 measured and declined), so three 6 s segments are 18 s joined, 16 s cut, and a seal of 5:
 
 ```
 [HLSVideoEngine] live TARGETDURATION sealed at 5s (holdback 15.000s): max EXTINF 2.000s,
@@ -748,6 +748,17 @@ One 180 s run per arm on that origin, same deliveries (four gaps above 9.0 s in
 
 That is fewer, not none, and it is the honest size of what a seal one second higher buys: 7.5 s of patience still loses to a 9 s gap, but the 15 s holdback leaves 5.7 s at the low point where 12 s left 2.7 s, which is the difference between surviving AVPlayer's skipped reload and not. A join one segment deeper (TD 6, holdback 18 s) drew none of either in three such runs and was not shipped: it cost 3.81 s against 4.98 s to the first picture behind an 8 Mbit/s link. The device capture this came from had 10 of its 110 gaps above 9 s and 5 above 12 s, so the field expectation is fewer `-12888` and far fewer stalls, not zero.
 
+**`--durs 6,4` is the reporting channel, and its two phases have to read alike.** The join counts seconds back from the newest segment, so `--prefill 8` (a 4 s segment newest) joined four segments and sealed 6 while `--prefill 7` (a 6 s one newest) met the 16 s coverage at three, cut 14 s and sealed 4, 7.25.1's value, on about four tunes in ten. A join over segments of mixed length (differing by more than a second) whose summed EXTINF is not above the holdback its longest segment asks for now takes one segment more, once. `--window 8`, mild jitter (`--delays 0.2,0.5,0.3,0.8,0.25,0.6`), three 60 s runs per arm and phase plus one 150 s run on the S1 cycle:
+
+| phase | | sealed | join | `-12888` (3 x 60 s, 150 s) | `playbackStalled` |
+|---|---|---|---|---|---|
+| `--prefill 7` | 7.25.1 | TD 4, holdback 12 s | 3 segments, 16 s | 0 / 1 / 0, 1 | 0 |
+| `--prefill 7` | now | TD 6, holdback 18 s | 4 segments, 20 s | 0 / 0 / 0, 0 | 0 |
+| `--prefill 8` | 7.25.1 | TD 4, holdback 12 s | 4 segments, 20 s | 1 / 1 / 1, 1 | 0 |
+| `--prefill 8` | now | TD 6, holdback 18 s | 4 segments, 20 s | 0 / 0 / 0, 0 | 0 |
+
+The extra segment is the short one, and the other phase already loads it: behind `--rate-kbps 8000 --latency-ms 30`, median of five, 3.47 s before and 4.21 s after to the first picture in the `--prefill 7` phase, 4.27 s and 4.26 s in the other. Uniform upstreams are outside the rule and keep their three segments (`--dur 6`: TD 5, `--dur 10`: TD 9). One start does get slower: a host that fetches fewer segments at a time than the join has (`play --max-concurrent-requests 1 ... --rate-kbps 14000`) used to be served at 12 s of cut content and now waits for the join to be handed over or for the grace, 2.79 to 3.08 s before and 3.27 to 3.28 s after with `--prefill 8`, 2.80 to 2.83 s and 3.44 to 3.49 s with `--prefill 7`.
+
 **Whether a join is spent is a fact, not arithmetic.** The seal may only be taken short once the join has nothing more to give, and "cut content plus one segment reaches the summed EXTINF" is not that fact: `--dur 6.3` over 6 s of media never adds up, and a first version built on the sum sealed the full value there and took the bounded start (2.23 s to first picture against 0.20 s). The reader states it instead: the whole join batch is committed, its FIFO is empty, and the cutter is parked waiting for the next delivery. Three runs per arm on each inflated shape with three segments listed: served at once in all six (0.000 to 0.034 s of hold), TD 5 on 6 s media and TD 9 on 10 s. Two more shapes belong to the same fact. A demuxed audio rendition (run the origin twice, video-only and audio-only segments behind a master) makes the cutter park on the AUDIO reader when the audio ends a little before the video, so the fact is stated for the cutter and not for the video reader: both join batches committed and either reader dry. Read off the video reader alone it never became true, 2.2 s to first picture under `.fastZap` and 10.4 s under `.standard`; now 0.18 to 0.21 s in all six cells (6 s and 10 s `.fastZap`, 10 s `.standard`, audio aligned and 0.2 s short, three runs each), as on 7.25.1. And a join slower than the `.fastZap` grace (`play --max-concurrent-requests 1` behind `--rate-kbps 4000`) is served by the bounded start before it is spent, seals the full 6 or 10 over a window under its holdback and draws a `-16832` warning at the start: first picture 5.05 to 6.08 s against 7.05 to 8.26 s on 7.25.1, which still pays the second grace there, and no `-12888` against 1 to 3.
 
 **The gate held the second playlist request too.** AVPlayer opens with two `/media.m3u8` requests, each re-enters `waitForFirstLiveSegment`, and on a bounded start each waited its own grace (`GET /media.m3u8` at 2.81 s, `GET /init.mp4` at 4.83 s). On an ingest the gate now opens for good once a manifest has gone out. On a source the engine cuts itself it does not: that second grace is the "+2.07 s at the picture" of the AE#594 table above, and removing it there also leaves the session up to 2 s closer to the producing edge, which is that issue's open question. The raw-TS control (`live --fast-zap --realtime --preroll 0`, two seeds, two runs per arm) reads the same in both arms: first manifest at 3.84 to 3.96 s, `init.mp4` at 6.11 to 6.33 s, first picture at 6.20 to 6.58 s, playhead 6.3 to 6.8 s behind the wall clock. The AE#594 table stands as printed.

From 67c12a3c7013dd753f263d79a912a2070e5932d2 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 2 Oct 2026 05:49:02 +0200
Subject: [PATCH 284/359] fix(live): the join is equalised over the phases of
 one upstream, and nothing else (#684)

d4891e34 took one segment more on any mixed-length join that could not
pay its seal. That also deepened shapes with no phase asymmetry, on
every tune: 10 s / 8 s segments went from three to four (6.19 s to
8.12 s to first picture behind 8 Mbit/s) and 6 s / 6 s / 4 s likewise
(3.81 s to 4.98 s), which is the join cost this branch declined for
uniform providers.

The rule is now what was decided: a tune never loads more than the
deepest tune of the same channel already did. The depth is the deepest
the 7.24.0 coverage rule takes over the actual tune and the tunes one,
two, ... segments earlier whose newest segment this join still takes
itself, bounded at one above the tune's own depth. 6 s / 4 s joins
four in both phases and seals 6; 10 s / 8 s and 6 s / 6 s / 4 s keep
three segments and seal what three pay (8 and 4); uniform upstreams
are unchanged. The spread threshold is gone with its float edge.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../IO/HLSIngest/HLSPlaylistTracker.swift     | 94 +++++++++++--------
 .../Video/VideoSegmentProvider.swift          |  8 +-
 .../Issue684MixedLengthJoinTests.swift        | 87 ++++++++++++-----
 3 files changed, 124 insertions(+), 65 deletions(-)

diff --git a/Sources/AetherEngine/IO/HLSIngest/HLSPlaylistTracker.swift b/Sources/AetherEngine/IO/HLSIngest/HLSPlaylistTracker.swift
index 4f3f1a44a..0bbabc0fc 100644
--- a/Sources/AetherEngine/IO/HLSIngest/HLSPlaylistTracker.swift
+++ b/Sources/AetherEngine/IO/HLSIngest/HLSPlaylistTracker.swift
@@ -47,6 +47,8 @@ struct HLSPlaylistTracker {
     /// does NOT follow it. A join one segment deeper is one more download before the first picture on
     /// every zap (the fourth segment AE#678 declined above), so the join keeps this depth and the seal
     /// rises only as far as what was joined can pay (`LiveEdgePolicy.targetDurationTheJoinCanPay`).
+    /// The one thing added on top is `phaseEqualisedJoinDepth`, which never exceeds the depth this
+    /// same coverage already takes in another phase of the same listing.
     static func loopbackCushionCoverageSeconds(segments: [HLSMediaSegment]) -> Double {
         guard let longest = segments.map(\.duration).max(), longest > 0 else { return 0 }
         let targetDuration = LiveEdgePolicy.targetDurationForCadence(longest)
@@ -54,39 +56,60 @@ struct HLSPlaylistTracker {
             + min(longest, openGOPMarginSeconds)
     }
 
-    /// AE#684: on an upstream of MIXED segment lengths, the join takes one segment more when what it
-    /// would otherwise list cannot pay the seal its longest segment asks for.
+    /// The 7.24.0 coverage rule on its own: how many segments a tune takes when `durations` (oldest
+    /// first) is what the upstream lists. nil when the listing runs out before the coverage is met and
+    /// before the count limit, so the depth of that tune cannot be read off this listing.
+    static func coverageJoinDepth(durations: ArraySlice<Double>, coverage: Double, limit: Int) -> Int? {
+        var taken = 0
+        var seconds = 0.0
+        for duration in durations.reversed() {
+            if taken >= limit { return taken }
+            if taken > 0, seconds >= coverage { return taken }
+            taken += 1
+            seconds += duration
+        }
+        return (taken >= limit || seconds >= coverage) ? taken : nil
+    }
+
+    /// AE#684: the join, equalised over the phases of one upstream.
     ///
-    /// The coverage loop counts seconds from the newest segment back, so on an upstream alternating
-    /// 6 s and 4 s segments (the channel this issue was reported on) the depth depends on which one
-    /// happens to be newest: `4 + 6 + 4` is under the 16 s target and a fourth is taken (20 s listed,
-    /// 18 s cut, seal 6), while `6 + 4 + 6` meets it at three (16 s listed, 14 s cut, seal 4, which
-    /// is 7.25.1's value and its stalls). About four tunes in ten land in the second phase, and the
-    /// same channel then behaves differently from one zap to the next.
+    /// The coverage loop counts seconds back from the newest segment, so on an upstream whose segment
+    /// lengths alternate its depth depends on which one happens to be newest. The channel this issue
+    /// was reported on alternates 6 s and 4 s: `4 + 6 + 4` is under the 16 s target and a fourth is
+    /// taken (20 s listed, 18 s cut, seal 6), while `6 + 4 + 6` meets it at three (16 s listed, 14 s
+    /// cut, seal 4, which is 7.25.1's value and its stalls). About four tunes in ten landed in the
+    /// second phase, and the same channel behaved differently from one zap to the next.
     ///
-    /// The rule, exactly: the joined segments differ in length by more than
-    /// `mixedLengthSpreadSeconds`, AND their summed EXTINF is not above the holdback of the seal the
-    /// longest listed segment asks for (`3 x` it; the last GOP stays open, so a join has to list MORE
-    /// than a holdback to pay for it). Then one more segment, once. It costs that phase one
-    /// additional segment at the join, the short one on the reported shape, which the other phase
-    /// already loads.
+    /// The rule: a tune never loads more than the deepest tune of the same channel already did. The
+    /// depth is the deepest the coverage rule takes over the actual tune and the tunes that would
+    /// have happened one, two, ... segments earlier, as far back as the newest segment of such a tune
+    /// is still one this join takes itself (a rhythm shorter than the join shows all its phases in
+    /// that span; looking further back would let one stray segment anywhere in the listing deepen
+    /// every tune). So 6 s / 4 s joins four in both phases, and the three-segment phase pays one
+    /// additional short segment that the other phase always loaded.
     ///
-    /// Uniform upstreams are deliberately outside it. There the join keeps the depth it had in
-    /// 7.24.0 and the seal is what that depth pays (5 on 6 s segments, 9 on 10 s), because a fourth
-    /// full-length segment on EVERY tune is the cost AE#678 declined.
-    static func mixedLengthJoinTakesOneMore(joinedDurations: [Double], longestListed: Double) -> Bool {
-        guard let longest = joinedDurations.max(), let shortest = joinedDurations.min(),
-              longest - shortest > mixedLengthSpreadSeconds, longestListed > 0 else { return false }
-        let asked = max(LiveEdgePolicy.targetDurationForCadence(longestListed),
-                        LiveEdgePolicy.targetDurationForUpstreamSegment(longestListed))
-        return joinedDurations.reduce(0, +) <= LiveEdgePolicy.holdBackSeconds(targetDuration: asked)
+    /// It deliberately does nothing where no phase is deeper. 10 s / 8 s segments join three in both
+    /// phases and 6 s / 6 s / 4 s three in all three, exactly as before, and their seal is what that
+    /// join pays, as for a uniform upstream: a deeper join on EVERY tune is the cost AE#678 declined.
+    /// A lone short segment on an otherwise uniform upstream deepens the join only while it sits
+    /// within that span: for the tunes that needed the extra segment anyway, and the two after them.
+    ///
+    /// Bounded at one segment above the actual tune's own depth. Phases of one listing differ by more
+    /// than that only when lengths swing wildly (a run of 2 s segments behind a 10 s one), and there
+    /// the listing is describing a change of source, not a rhythm to equalise.
+    static func phaseEqualisedJoinDepth(durations: [Double], coverage: Double, limit: Int) -> Int {
+        guard let own = coverageJoinDepth(durations: durations[...], coverage: coverage, limit: limit) else {
+            return min(durations.count, limit)
+        }
+        var deepest = own
+        for earlier in 1..<max(1, own) {
+            guard let depth = coverageJoinDepth(durations: durations.dropLast(earlier),
+                                                coverage: coverage, limit: limit) else { break }
+            deepest = max(deepest, depth)
+        }
+        return min(deepest, own + 1, limit, durations.count)
     }
 
-    /// Lengths closer than this are one length. A packager's EXTINF wanders by frames around its
-    /// nominal value (5.96, 6.04), and that is a uniform upstream; a whole second is the resolution a
-    /// TARGETDURATION is taken at.
-    static let mixedLengthSpreadSeconds: Double = 1.0
-
     /// Longest GOP the join margin plans for. IPTV and broadcast GOPs run 0.5 to 4 s; a longer one
     /// only costs the bounded start's grace, which is what every join paid before AE#678.
     static let openGOPMarginSeconds: Double = 4
@@ -123,19 +146,8 @@ struct HLSPlaylistTracker {
                                Self.loopbackCushionCoverageSeconds(segments: playlist.segments))
             let limit = Self.joinSegmentLimit(edgeOffset: edgeOffset,
                                               windowSegmentCount: playlist.segments.count)
-            var taken = 0
-            var seconds = 0.0
-            for segment in playlist.segments.reversed() {
-                if taken >= limit { break }
-                if taken > 0, seconds >= coverage { break }
-                taken += 1
-                seconds += segment.duration
-            }
-            if taken < limit, taken < playlist.segments.count,
-               Self.mixedLengthJoinTakesOneMore(joinedDurations: playlist.segments.suffix(taken).map(\.duration),
-                                                longestListed: playlist.segments.map(\.duration).max() ?? 0) {
-                taken += 1
-            }
+            let taken = Self.phaseEqualisedJoinDepth(durations: playlist.segments.map(\.duration),
+                                                     coverage: coverage, limit: limit)
             return windowEnd &- taken
         }
 
diff --git a/Sources/AetherEngine/Video/VideoSegmentProvider.swift b/Sources/AetherEngine/Video/VideoSegmentProvider.swift
index 95b392701..7f25dc064 100644
--- a/Sources/AetherEngine/Video/VideoSegmentProvider.swift
+++ b/Sources/AetherEngine/Video/VideoSegmentProvider.swift
@@ -306,7 +306,9 @@ enum LiveEdgePolicy {
     /// sit a whole window behind an edge that window can barely list. At 10, segments up to 10 s are
     /// asked for whole and a 20 s one seals 14, as it did before the term existed. What is asked for
     /// is then paid only as far as the join reaches (`targetDurationTheJoinCanPay`), and the join is
-    /// not deepened for it, so in practice a 10 s provider lands at 9.
+    /// not deepened for it, so in practice a 10 s provider lands at 9. (The join's one addition,
+    /// `HLSPlaylistTracker.phaseEqualisedJoinDepth`, only lifts a tune to the depth another phase
+    /// of the same listing already takes.)
     static let upstreamSegmentSealCeilingSeconds: Double = 10
 
     /// AE#684: the upstream-segment seal, as far as the join can pay for it.
@@ -314,7 +316,9 @@ enum LiveEdgePolicy {
     /// A seal is a holdback of `3 x` itself, and a holdback the first window cannot hold is not
     /// protection, it is a start the client spends waiting. The join is three upstream segments on
     /// anything longer than about 5 s and stays that deep (one more would be one more download on
-    /// every zap, AE#678), and its last GOP stays open until the next upstream delivery: three 6 s
+    /// every zap, AE#678; the exception is an upstream whose segment lengths alternate, where a tune
+    /// is lifted to the depth its other phase already takes, 6 s / 4 s to four), and its last GOP
+    /// stays open until the next upstream delivery: three 6 s
     /// segments are 18 s joined and 16 s cut, against the 18 s a seal of 6 asks for. So once the
     /// reader has handed the whole join over and the cutter has nothing left to read, the seal is the
     /// largest value that cut content covers, never under what it was without the upstream term and
diff --git a/Tests/AetherEngineTests/Issue684MixedLengthJoinTests.swift b/Tests/AetherEngineTests/Issue684MixedLengthJoinTests.swift
index d04a163a2..f68a6cca1 100644
--- a/Tests/AetherEngineTests/Issue684MixedLengthJoinTests.swift
+++ b/Tests/AetherEngineTests/Issue684MixedLengthJoinTests.swift
@@ -7,8 +7,11 @@
 // sealed 6 with no -12888 and no stall, `--prefill 7` sealed 4 in both arms and stalled as before.
 // About four tunes in ten land in that phase.
 //
-// On an upstream of mixed segment lengths the join takes one segment more when what it lists cannot pay
-// the seal its longest segment asks for. Uniform upstreams keep the exact 7.24.0 join.
+// The join is equalised over the phases of one listing: a tune never loads more than the deepest tune
+// of the same channel already did. A first version of this took one segment more on ANY mixed-length
+// join that could not pay its seal, which also deepened shapes with no phase asymmetry at all, on
+// every tune: 10 s / 8 s from three to four segments (6.19 s to 8.12 s to first picture behind
+// 8 Mbit/s) and 6 s / 6 s / 4 s likewise (3.81 s to 4.98 s). Those keep their join now.
 import XCTest
 @testable import AetherEngine
 
@@ -63,7 +66,11 @@ final class Issue684MixedLengthJoinTests: XCTestCase {
         XCTAssertEqual(joined([6, 4, 6, 4, 6, 4, 6]).count, 4)
     }
 
-    func testSixSixFourPatternSealsSixInEveryPhase() {
+    // MARK: - Shapes with no deeper phase keep their join
+
+    /// Three segments are 16 s in every phase, so no tune of this channel ever loaded a fourth, and
+    /// none does now. Its seal is what three pay: 14 s cut, 4.
+    func testSixSixFourPatternKeepsThreeSegmentsInEveryPhase() {
         let phases: [[Double]] = [
             [6, 6, 4, 6, 6, 4, 6, 6, 4],
             [6, 4, 6, 6, 4, 6, 6, 4, 6],
@@ -71,11 +78,33 @@ final class Issue684MixedLengthJoinTests: XCTestCase {
         ]
         for phase in phases {
             let join = joined(phase)
-            XCTAssertEqual(join.count, 4, "\(phase)")
-            XCTAssertEqual(seal(join), 6, "\(phase)")
+            XCTAssertEqual(join.count, 3, "\(phase)")
+            XCTAssertEqual(join.reduce(0, +), 16, "\(phase)")
+            XCTAssertEqual(seal(join), 4, "\(phase)")
         }
     }
 
+    /// 28 s and 26 s both meet the 25 s target at three. Seal 8 in both phases (26 s and 24 s cut).
+    func testTenEightAlternationKeepsThreeSegmentsInBothPhases() {
+        let newestIsTen = joined([8, 10, 8, 10, 8, 10, 8, 10])
+        let newestIsEight = joined([10, 8, 10, 8, 10, 8, 10, 8])
+        XCTAssertEqual(newestIsTen, [10, 8, 10])
+        XCTAssertEqual(newestIsEight, [8, 10, 8])
+        XCTAssertEqual(seal(newestIsTen), 8)
+        XCTAssertEqual(seal(newestIsEight), 8)
+    }
+
+    /// Equalising phases is about depth, not about the seal: 6 s / 5 s joins three either way
+    /// (17 s and 16 s), and its seal still follows the phase, 5 and 4.
+    func testAShapeWhosePhasesJoinAlikeKeepsItsPhaseDependentSeal() {
+        let newestIsSix = joined([5, 6, 5, 6, 5, 6, 5, 6])
+        let newestIsFive = joined([6, 5, 6, 5, 6, 5, 6, 5])
+        XCTAssertEqual(newestIsSix.count, 3)
+        XCTAssertEqual(newestIsFive.count, 3)
+        XCTAssertEqual(seal(newestIsSix), 5)
+        XCTAssertEqual(seal(newestIsFive), 4)
+    }
+
     // MARK: - Uniform upstreams keep the 7.24.0 join
 
     func testUniformSixAndTenSecondJoinsAreUnchanged() {
@@ -87,24 +116,42 @@ final class Issue684MixedLengthJoinTests: XCTestCase {
     }
 
     /// EXTINF that wanders by frames around its nominal value is a uniform upstream.
-    func testFrameJitterInExtinfIsNotMixedLength() {
+    func testFrameJitterInExtinfIsNotAPhase() {
         XCTAssertEqual(joined([6.0, 5.96, 5.92, 6.0, 5.96, 5.92, 6.0, 5.96]).count, 3)
-        XCTAssertFalse(HLSPlaylistTracker.mixedLengthJoinTakesOneMore(
-            joinedDurations: [6.0, 5.96, 5.92], longestListed: 6.0))
-        XCTAssertFalse(HLSPlaylistTracker.mixedLengthJoinTakesOneMore(
-            joinedDurations: [6, 5, 6], longestListed: 6), "exactly the spread is still one length")
+        XCTAssertEqual(joined([5.96, 5.92, 6.0, 5.96, 5.92, 6.0, 5.96, 6.0]).count, 3)
     }
 
     // MARK: - The rule's edges
 
-    /// A mixed join that already lists more than the holdback it is asked for takes nothing more.
-    func testAMixedJoinThatAlreadyPaysIsLeftAlone() {
-        XCTAssertFalse(HLSPlaylistTracker.mixedLengthJoinTakesOneMore(
-            joinedDurations: [6, 4, 6, 4], longestListed: 6))
-        XCTAssertTrue(HLSPlaylistTracker.mixedLengthJoinTakesOneMore(
-            joinedDurations: [4, 6, 6], longestListed: 6))
-        XCTAssertTrue(HLSPlaylistTracker.mixedLengthJoinTakesOneMore(
-            joinedDurations: [6, 6, 6.5], longestListed: 6.5) == false, "spread under a second")
+    /// The depth is the deepest the coverage rule takes over the phases of the listing, and never
+    /// more than one above the tune's own.
+    func testDepthIsTheDeepestPhaseBoundedAtOneAboveTheTunesOwn() {
+        func depth(_ durations: [Double], coverage: Double) -> Int {
+            HLSPlaylistTracker.phaseEqualisedJoinDepth(durations: durations, coverage: coverage, limit: 8)
+        }
+        XCTAssertEqual(depth([4, 6, 4, 6, 4, 6, 4, 6], coverage: 16), 4)
+        XCTAssertEqual(depth([6, 4, 6, 4, 6, 4, 6, 4], coverage: 16), 4)
+        XCTAssertEqual(depth([6, 6, 6, 6, 6, 6, 6, 6], coverage: 16), 3)
+        // A run of short segments behind two long ones: the earlier phases need six and more, the
+        // tune's own two. Bounded at three.
+        XCTAssertEqual(depth([2, 2, 2, 2, 2, 2, 10, 10], coverage: 16), 3)
+        // The old rule alone, and a listing too short to decide a tune.
+        XCTAssertEqual(HLSPlaylistTracker.coverageJoinDepth(durations: [4, 6, 4, 6][...], coverage: 16, limit: 8), 3)
+        XCTAssertNil(HLSPlaylistTracker.coverageJoinDepth(durations: [4, 6][...], coverage: 16, limit: 8))
+    }
+
+    /// A lone short segment on a uniform upstream. While it is among the newest three the join is
+    /// four, as it always was (15 s is under the target). For the two tunes after that the join
+    /// still contains the newest segment of a tune that took four, so it stays four. After that it
+    /// is three again, although the short segment is still listed.
+    func testALoneShortSegmentOnAUniformUpstream() {
+        XCTAssertEqual(joined([6, 6, 6, 6, 6, 6, 6, 3]), [6, 6, 6, 3], "as before")
+        XCTAssertEqual(joined([6, 6, 6, 6, 6, 6, 3, 6]), [6, 6, 3, 6], "as before")
+        XCTAssertEqual(joined([6, 6, 6, 6, 6, 3, 6, 6]), [6, 3, 6, 6], "as before")
+        XCTAssertEqual(joined([6, 6, 6, 6, 3, 6, 6, 6]), [3, 6, 6, 6], "one tune after: lifted to four")
+        XCTAssertEqual(joined([6, 6, 6, 3, 6, 6, 6, 6]), [6, 6, 6, 6], "two tunes after: lifted to four")
+        XCTAssertEqual(joined([6, 6, 3, 6, 6, 6, 6, 6]), [6, 6, 6], "three after: its own depth again")
+        XCTAssertEqual(joined([6, 6, 6, 6, 6, 6, 6, 6]).count, 3)
     }
 
     /// One more, once, and never past what the playlist offers or the eviction margin allows.
@@ -114,8 +161,4 @@ final class Issue684MixedLengthJoinTests: XCTestCase {
         XCTAssertEqual(joined([6, 4, 6, 4, 6]).count, 4)
     }
 
-    /// A short last segment before a boundary is mixed too, and is already deep enough.
-    func testAShortNewestSegmentDoesNotDeepenTheJoinFurther() {
-        XCTAssertEqual(joined([6, 6, 6, 6, 6, 3]), [6, 6, 6, 3])
-    }
 }

From 48eb77c81f479228b45342860855d7d683e9c83c Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 2 Oct 2026 07:00:21 +0200
Subject: [PATCH 285/359] docs(live): the join rule is phase equalisation, with
 what it leaves alone (#684)

The docs described "one segment more on a mixed-length join that
cannot pay". The rule is narrower: a tune never loads more than the
deepest tune of the same channel already did. 6 s / 4 s joins four in
both phases and seals 6; 10 s / 8 s and 6 s / 6 s / 4 s keep three
segments in every phase (first picture equal to 7.25.1 behind
8 Mbit/s) and seal what three pay, 8 and 4; a shape like 6 s / 5 s
keeps a seal that follows the phase. Tables re-measured.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/api.md | 30 +++++++++++++++++-------------
 docs/cli.md | 24 ++++++++++++++----------
 2 files changed, 31 insertions(+), 23 deletions(-)

diff --git a/docs/api.md b/docs/api.md
index 1e4c341d0..f976833db 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -721,16 +721,20 @@ still not read. What it gets is bounded three ways:
   would be one more download before the first picture on every zap, which AE#678 measured and
   declined). Their last GOP stays open until the next delivery, so three 6 s segments are 18 s joined
   and 16 s cut: the seal is 5, the largest value whose holdback that window holds, not 6. Three 10 s
-  segments cut 28 s and seal 9. An upstream of MIXED segment lengths is the one exception, because
-  there the join's depth used to depend on which segment happened to be newest: alternating 6 s and
-  4 s segments joined four (20 s listed, 18 s cut, seal 6) with a 4 s one newest and three (16 s
-  listed, 14 s cut, seal 4, as in 7.25.1) with a 6 s one newest, so the same channel behaved
-  differently from one tune to the next. When the joined segments differ by more than a second and
-  their summed EXTINF is not above the holdback the longest listed segment asks for, the join takes
-  one segment more, once; both phases then join four and seal 6. That costs the three-segment phase
-  (about four tunes in ten on that shape) one additional short segment at the join, which the other
-  six already load: 3.47 s to 4.21 s to first picture behind an 8 Mbit/s link, median of five, against
-  4.27 s in the other phase on either build. The seal line says what was paid
+  segments cut 28 s and seal 9. The one addition is that the join is equalised over the PHASES of an
+  upstream whose segment lengths alternate: a tune never loads more than the deepest tune of the same
+  channel already did. Alternating 6 s and 4 s segments used to join four (20 s listed, 18 s cut,
+  seal 6) with a 4 s one newest and three (16 s listed, 14 s cut, seal 4, as in 7.25.1) with a 6 s
+  one newest, so the same channel behaved differently from one tune to the next. The depth is now the
+  deepest the coverage rule takes over the tune itself and the tunes one, two, ... segments earlier
+  that its own join still reaches, at most one segment above its own: both phases join four and seal
+  6. That costs the three-segment phase (about four tunes in ten on that shape) one additional short
+  segment at the join, which the other six already load: 3.47 s to 4.23 s to first picture behind an
+  8 Mbit/s link, median of five, against 4.27 s in the other phase on either build. Shapes whose
+  phases already joined alike keep their join and what it pays: 10 s / 8 s stays at three segments
+  and seals 8 (7 before), 6 s / 6 s / 4 s stays at three and seals 4, unchanged, and a shape like
+  6 s / 5 s keeps a seal that follows the phase (5 in one, 4 in the other), because equalising is
+  about how much a tune loads, not about what it seals. The seal line says what was paid
   (`of which the join pays 5s of 6s (16.000s cut of the 18.000s it listed)`), and "the join has no
   more to give" is a fact the reader states (its join batch is handed over and its consumer is
   waiting), not arithmetic on EXTINF, which a playlist that rounds its durations up would fail.
@@ -751,8 +755,8 @@ still not read. What it gets is bounded three ways:
   segments keep 2 and a 6 s holdback, and `.standard` keeps its 6 on anything up to 6 s.
 
 So on a provider of uniform 6 s segments under `.fastZap` the seal goes from 4 to 5 (holdback 12 to
-15 s), on a uniform 10 s one under either profile from 7 to 9 (21 to 27 s), and on mixed 6 s / 4 s
-segments from 4 to 6 (12 to 18 s) in both phases. A provider of 3 s segments with 1 s GOPs is
+15 s), on a uniform 10 s one under either profile from 7 to 9 (21 to 27 s), and on alternating
+6 s / 4 s segments from 4 to 6 (12 to 18 s) in both phases. A provider of 3 s segments with 1 s GOPs is
 unchanged at 2: three joined segments cut 8 s, which pays for no more, so the patience of one
 delivery this issue is about stays as it is there. On uniform upstreams the join, and with a host that
 fetches in parallel the time to the first picture, is what it was: behind an 8 Mbit/s link, three runs
@@ -763,7 +767,7 @@ gate now waits for the join to be handed over where it used to serve at 12 s of
 request at a time behind 14 Mbit/s on the mixed shape, three runs per arm, 2.79 to 3.08 s before and
 3.27 to 3.28 s after in the four-segment phase, 2.80 to 2.83 s and 3.44 to 3.49 s in the phase that
 now also loads the extra segment. The other cost is standing latency: 3 s more behind the upstream's
-edge on uniform 6 s segments, 6 s on mixed 6 s / 4 s and on 10 s ones.
+edge on uniform 6 s segments, 6 s on alternating 6 s / 4 s and on 10 s ones, 3 s on 10 s / 8 s.
 
 Measured on loopback against `Scripts/hls-burst-origin.py` (deliveries 3 to 9.3 s apart on 6 s
 segments), 60 s per run, three runs per arm and row, 7.25.1 against this; first picture is 0.17 to
diff --git a/docs/cli.md b/docs/cli.md
index 1a4f02d81..c8fc4e157 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -748,16 +748,20 @@ One 180 s run per arm on that origin, same deliveries (four gaps above 9.0 s in
 
 That is fewer, not none, and it is the honest size of what a seal one second higher buys: 7.5 s of patience still loses to a 9 s gap, but the 15 s holdback leaves 5.7 s at the low point where 12 s left 2.7 s, which is the difference between surviving AVPlayer's skipped reload and not. A join one segment deeper (TD 6, holdback 18 s) drew none of either in three such runs and was not shipped: it cost 3.81 s against 4.98 s to the first picture behind an 8 Mbit/s link. The device capture this came from had 10 of its 110 gaps above 9 s and 5 above 12 s, so the field expectation is fewer `-12888` and far fewer stalls, not zero.
 
-**`--durs 6,4` is the reporting channel, and its two phases have to read alike.** The join counts seconds back from the newest segment, so `--prefill 8` (a 4 s segment newest) joined four segments and sealed 6 while `--prefill 7` (a 6 s one newest) met the 16 s coverage at three, cut 14 s and sealed 4, 7.25.1's value, on about four tunes in ten. A join over segments of mixed length (differing by more than a second) whose summed EXTINF is not above the holdback its longest segment asks for now takes one segment more, once. `--window 8`, mild jitter (`--delays 0.2,0.5,0.3,0.8,0.25,0.6`), three 60 s runs per arm and phase plus one 150 s run on the S1 cycle:
-
-| phase | | sealed | join | `-12888` (3 x 60 s, 150 s) | `playbackStalled` |
-|---|---|---|---|---|---|
-| `--prefill 7` | 7.25.1 | TD 4, holdback 12 s | 3 segments, 16 s | 0 / 1 / 0, 1 | 0 |
-| `--prefill 7` | now | TD 6, holdback 18 s | 4 segments, 20 s | 0 / 0 / 0, 0 | 0 |
-| `--prefill 8` | 7.25.1 | TD 4, holdback 12 s | 4 segments, 20 s | 1 / 1 / 1, 1 | 0 |
-| `--prefill 8` | now | TD 6, holdback 18 s | 4 segments, 20 s | 0 / 0 / 0, 0 | 0 |
-
-The extra segment is the short one, and the other phase already loads it: behind `--rate-kbps 8000 --latency-ms 30`, median of five, 3.47 s before and 4.21 s after to the first picture in the `--prefill 7` phase, 4.27 s and 4.26 s in the other. Uniform upstreams are outside the rule and keep their three segments (`--dur 6`: TD 5, `--dur 10`: TD 9). One start does get slower: a host that fetches fewer segments at a time than the join has (`play --max-concurrent-requests 1 ... --rate-kbps 14000`) used to be served at 12 s of cut content and now waits for the join to be handed over or for the grace, 2.79 to 3.08 s before and 3.27 to 3.28 s after with `--prefill 8`, 2.80 to 2.83 s and 3.44 to 3.49 s with `--prefill 7`.
+**`--durs 6,4` is the reporting channel, and its two phases have to read alike.** The join counts seconds back from the newest segment, so `--prefill 8` (a 4 s segment newest) joined four segments and sealed 6 while `--prefill 7` (a 6 s one newest) met the 16 s coverage at three, cut 14 s and sealed 4, 7.25.1's value, on about four tunes in ten. The join is now equalised over the phases of one listing: a tune never loads more than the deepest tune of the same channel already did (the deepest the coverage rule takes over the tune and the tunes one, two, ... segments earlier that its own join still reaches, at most one above its own depth). `--window 8`, mild jitter (`--delays 0.2,0.5,0.3,0.8,0.25,0.6`), three 60 s runs per arm and phase:
+
+| `--durs` | phase | | sealed | join | `-12888` | first picture behind 8 Mbit/s (median) |
+|---|---|---|---|---|---|---|
+| 6,4 | `--prefill 7` | 7.25.1 | TD 4, holdback 12 s | 3 segments, 16 s | 1 / 0 / 1 | 3.47 s |
+| 6,4 | `--prefill 7` | now | TD 6, holdback 18 s | 4 segments, 20 s | 0 / 0 / 0 | 4.23 s |
+| 6,4 | `--prefill 8` | 7.25.1 | TD 4, holdback 12 s | 4 segments, 20 s | 1 / 1 / 0 | 4.27 s |
+| 6,4 | `--prefill 8` | now | TD 6, holdback 18 s | 4 segments, 20 s | 0 / 0 / 0 | 4.26 s |
+| 10,8 | both | 7.25.1 | TD 7, holdback 21 s | 3 segments, 28 or 26 s | 0 / 0 / 0, 1 / 1 / 1 | 5.86 s, 5.52 s |
+| 10,8 | both | now | TD 8, holdback 24 s | 3 segments, 28 or 26 s | 0 / 0 / 0, 1 / 1 / 1 | 5.88 s, 5.59 s |
+| 6,6,4 | all three | 7.25.1 | TD 4, holdback 12 s | 3 segments, 16 s | 0 to 2 per run | 3.45 s, 3.43 s, 3.46 s |
+| 6,6,4 | all three | now | TD 4, holdback 12 s | 3 segments, 16 s | 0 to 1 per run | 3.47 s, 3.47 s, 3.48 s |
+
+No run stalled in either arm. The extra segment on 6,4 is the short one, and the other phase already loads it. The equalising stops there on purpose: 10,8 and 6,6,4 join three in every phase, so nothing is added and their first picture is main's; 10,8 seals what its three segments pay (8), and 6,6,4 cuts 14 s in every phase and keeps 4, which is to say it is not helped. A first version took one segment more on any mixed-length join that could not pay its seal, and that cost those two shapes a segment on every tune (6.19 s to 8.12 s and 3.81 s to 4.98 s). Uniform upstreams keep their three segments (`--dur 6`: TD 5, `--dur 10`: TD 9), and a demuxed audio rendition is joined by the same rule (6,4 behind a master: 4 + 4 in both phases). One start does get slower: a host that fetches fewer segments at a time than the join has (`play --max-concurrent-requests 1 ... --rate-kbps 14000`) used to be served at 12 s of cut content and now waits for the join to be handed over or for the grace, 2.79 to 3.08 s before and 3.27 to 3.28 s after with `--prefill 8`, 2.80 to 2.83 s and 3.44 to 3.49 s with `--prefill 7`.
 
 **Whether a join is spent is a fact, not arithmetic.** The seal may only be taken short once the join has nothing more to give, and "cut content plus one segment reaches the summed EXTINF" is not that fact: `--dur 6.3` over 6 s of media never adds up, and a first version built on the sum sealed the full value there and took the bounded start (2.23 s to first picture against 0.20 s). The reader states it instead: the whole join batch is committed, its FIFO is empty, and the cutter is parked waiting for the next delivery. Three runs per arm on each inflated shape with three segments listed: served at once in all six (0.000 to 0.034 s of hold), TD 5 on 6 s media and TD 9 on 10 s. Two more shapes belong to the same fact. A demuxed audio rendition (run the origin twice, video-only and audio-only segments behind a master) makes the cutter park on the AUDIO reader when the audio ends a little before the video, so the fact is stated for the cutter and not for the video reader: both join batches committed and either reader dry. Read off the video reader alone it never became true, 2.2 s to first picture under `.fastZap` and 10.4 s under `.standard`; now 0.18 to 0.21 s in all six cells (6 s and 10 s `.fastZap`, 10 s `.standard`, audio aligned and 0.2 s short, three runs each), as on 7.25.1. And a join slower than the `.fastZap` grace (`play --max-concurrent-requests 1` behind `--rate-kbps 4000`) is served by the bounded start before it is spent, seals the full 6 or 10 over a window under its holdback and draws a `-16832` warning at the start: first picture 5.05 to 6.08 s against 7.05 to 8.26 s on 7.25.1, which still pays the second grace there, and no `-12888` against 1 to 3.
 

From f5f9a7372b452485f1bb33e1a071b9f927864026 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 2 Oct 2026 07:12:14 +0200
Subject: [PATCH 286/359] chore(release): prep 7.25.2 - a live ingest seals its
 patience over the upstream segment its join can pay

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                  | 24 +++++++++++++++++++
 Examples/README.md                            |  2 +-
 README.md                                     |  6 ++---
 .../AetherEngine/AetherEngine+Version.swift   |  2 +-
 4 files changed, 29 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index dc6e7a2a8..0605d6db4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,30 @@ the public-API contract.
 
 _Nothing yet._
 
+## [7.25.2] - 2026-10-02
+
+### Fixed
+
+- **A live HLS ingest sealed its TARGETDURATION under the upstream's own segment length (#684).** The engine re-cuts each upstream segment (at its GOPs under `.fastZap`), so the upstream's segment entered the seal only as `ceil(segment / 1.5)`: a 6 s provider sealed 4, a client patience of exactly one delivery and a 12 s holdback against deliveries that arrive 6 to 9 s apart. AVPlayer drew `-12888`, skipped its next playlist reload and stalled with the content already listed. The seal now asks for the longest upstream segment served (up to 10 s) and takes as much of it as the join pays for:
+  - uniform 6 s segments under `.fastZap` seal 5 (holdback 15 s), uniform 10 s segments under either profile seal 9 (27 s), with the join unchanged (three segments);
+  - alternating lengths: the join is equalised over the phases of one upstream, so a tune never loads more than the deepest tune of the same channel already did. The reporting channel alternates 6 s and 4 s; its join used to be three or four segments depending on which was newest, and only the four-segment phase got more than 7.25.1's value. Both phases now join four and seal 6 (18 s). Shapes whose phases already joined alike keep their join and what it pays: 10 s / 8 s seals 8 (7 before), 6 s / 6 s / 4 s keeps 4, and a shape like 6 s / 5 s keeps a seal that follows the phase (5 or 4);
+  - 2 s providers keep 2, 3 s providers with 1 s GOPs keep 2 (their join pays for no more), and `.standard` is unchanged up to 6 s segments.
+
+  Measured on a uniform 6 s origin with jittered deliveries over 180 s: 5 `-12888` and a stall before, 3 and no stall after; over nine 60 s runs 7 stalls before and none after. On the alternating 6 s / 4 s shape: 0 to 1 `-12888` per run before, none after, in both phases. On 10 s segments the window close and item rebuild that 7.25.1 produced in 4 of 9 `.fastZap` runs and 6 of 6 `.standard` runs did not occur. Expect far fewer stalls and fewer `-12888`, not none: the reporting capture had 10 of 110 delivery gaps above 9 s.
+
+  Costs. Standing latency: 3 s more behind the upstream's edge on uniform 6 s segments and on 10 s / 8 s, 6 s on alternating 6 s / 4 s and on 10 s ones. Join: unchanged on uniform upstreams and on every shape whose phases joined alike; on alternating 6 s / 4 s about four tunes in ten load one additional short segment (3.47 s to 4.23 s to first picture behind an 8 Mbit/s link; the other six tunes already took 4.27 s). A host that allows fewer parallel requests than the join has segments (`maxConcurrentSourceRequests` of 3 or less) sees its first picture later, because the gate waits for the join to be handed over where it used to serve at 12 s of cut content: 2.79 to 3.08 s before and 3.27 to 3.49 s after, one request at a time behind 14 Mbit/s on the 6 s / 4 s shape. A join slower than the `.fastZap` grace is still served by the bounded start and then seals the full value over a window under its holdback (a `-16832` warning at the start).
+- **On an ingest the first-serve gate held the second playlist request too (#684).** On a `.fastZap` bounded start AVPlayer's second opening request waited out a second grace: 4.47 s to first picture where one grace is 2.24 s. Sources the engine cuts itself (raw MPEG-TS) are unchanged.
+- **The AE#440 forced start is no longer taken on an item that cannot play yet (#684).** On a rejoin placed by `EXT-X-START`, AVPlayer fetches from about 6 s below the target first, and the guard read that lookback as its cushion (`buffer ahead 4.00s` from a playhead the item never played from) and called `playImmediately` 36 ms before the item was ready. The decision now waits for `readyToPlay` and is asked again there. Whether this is what put sound and picture apart on the reporting device is not confirmed.
+
+### Added
+
+- **Each native live item says what it started on (#684):** `#684 item #N starts at its own Xs: segment K + Ys, whose picture opens at ... and whose sound runs ...`, and every `live seg-N finalized` line carries `sound=first..last`. The audio route line adds the route's output latency.
+- **`aetherctl play --served-url`** prints the loopback URL of each native item, and **`Scripts/hls-burst-origin.py`** is a live HLS origin whose delivery rhythm is scripted (jitter cycle, outage, window depth, mixed and inflated EXTINF, shared link rate).
+
+### Changed
+
+- `HLSVideoEngine`'s public initializer gained two defaulted parameters, `liveJoinBacklogObservation` and `liveJoinSpentObservation`. Source compatible; a host that constructs the session itself passes nothing new.
+
 ## [7.25.1] - 2026-10-01
 
 ### Fixed
diff --git a/Examples/README.md b/Examples/README.md
index 5b4f0006a..097b42744 100644
--- a/Examples/README.md
+++ b/Examples/README.md
@@ -18,7 +18,7 @@ Three samples covering different audiences:
    ```
    https://github.com/superuser404notfound/AetherEngine
    ```
-   Dependency Rule: Up to Next Major Version, starting from `7.25.1`. Add the `AetherEngine` library product to your app target.
+   Dependency Rule: Up to Next Major Version, starting from `7.25.2`. Add the `AetherEngine` library product to your app target.
 
 3. **Drop the file in.** Replace the Xcode template's default `App.swift` (or whatever the generated `@main` file is called) with the contents of [`MinimalPlayerApp.swift`](MinimalPlayer/MinimalPlayerApp.swift). The file is self-contained: it defines both the `@main App` struct and the `ContentView`.
 
diff --git a/README.md b/README.md
index 8fac33640..0f53c954f 100644
--- a/README.md
+++ b/README.md
@@ -384,7 +384,7 @@ Subtitle cues land in raw source PTS; render the overlay against `player.sourceT
 Install via Swift Package Manager:
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.25.1")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.25.2")
 ```
 
 Three samples ship in `Examples/`:
@@ -631,10 +631,10 @@ Browse all of this as a searchable site at **[aetherengine.superuser404.de](http
 AetherEngine uses [Semantic Versioning](https://semver.org). The public API surface, every `public` declaration in `Sources/AetherEngine/`, is the stability contract. **Major** removes / renames public symbols or breaks adopters; **Minor** adds public API or codec / format support; **Patch** fixes bugs with no public API change. `internal` types are not part of the contract.
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.25.1")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.25.2")
 ```
 
-Pin to `.upToNextMinor(from: "7.25.1")` for stricter teams that prefer to opt into minor bumps explicitly.
+Pin to `.upToNextMinor(from: "7.25.2")` for stricter teams that prefer to opt into minor bumps explicitly.
 
 ## Requirements
 
diff --git a/Sources/AetherEngine/AetherEngine+Version.swift b/Sources/AetherEngine/AetherEngine+Version.swift
index f7ecb0749..2d617f1f6 100644
--- a/Sources/AetherEngine/AetherEngine+Version.swift
+++ b/Sources/AetherEngine/AetherEngine+Version.swift
@@ -11,5 +11,5 @@ extension AetherEngine {
     ///
     /// Between releases, and in a consumer that pins an unreleased commit for a device test, this
     /// names the last PUBLISHED version the checkout descends from, not every patch in it.
-    public nonisolated static let version = "7.25.1"
+    public nonisolated static let version = "7.25.2"
 }

From 4e12c8e59c7dc554f853c6ec4d9ce585a0db6121 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 2 Oct 2026 15:58:50 +0200
Subject: [PATCH 287/359] fix(retention): a session is sized from the free
 space the other sessions leave (#687)

Every session took min(2 GiB, a quarter of the free space), measured at its
own start. An allowance another session had claimed but not yet written was
still free then, so four engines started together claimed four quarters of
the same space: on 4 GiB free, the whole volume.

RetentionClaims is one process-wide ledger of the running sessions'
allowances. A new session is sized from the free space minus what the others
may still write. A session alone is unchanged; n sessions leave at least
(3/4)^n of the volume. Used by the native session, the software live ring
and the software VOD read-ahead, released on stop.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                  |  4 +-
 .../Native/SoftwarePlaybackHost.swift         | 34 ++++++--
 .../AetherEngine/Video/HLSVideoEngine.swift   | 17 +++-
 .../AetherEngine/Video/RetentionClaims.swift  | 68 +++++++++++++++
 .../Issue687RetentionClaimsTests.swift        | 83 +++++++++++++++++++
 docs/api.md                                   |  3 +-
 docs/architecture.md                          |  3 +-
 7 files changed, 197 insertions(+), 15 deletions(-)
 create mode 100644 Sources/AetherEngine/Video/RetentionClaims.swift
 create mode 100644 Tests/AetherEngineTests/Issue687RetentionClaimsTests.swift

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0605d6db4..ef89f70e3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,7 +10,9 @@ the public-API contract.
 
 ## [Unreleased]
 
-_Nothing yet._
+### Fixed
+
+- **Engines running side by side each claimed a quarter of the same free space (#687).** A session sizes its disk allowance once, at its start, as `min(2 GiB, a quarter of the tmp volume's free space)`. An allowance another session had claimed but not yet written was still free at that moment, so four engines started together (a multiview host) could claim four quarters: on 4 GiB free, the whole volume. A session is now sized from the free space minus what the other running sessions may still write. One session alone gets exactly what it got; four on 4 GiB free take 2.7 GiB instead of 4, and n sessions always leave at least `(3/4)^n` of the volume. The live window already follows its allowance (#443), so a smaller share means a shorter timeshift depth on the later tiles, and the session log says how much was held back. Covers the native session, the software live ring and the software VOD read-ahead; no API change.
 
 ## [7.25.2] - 2026-10-02
 
diff --git a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
index 3798b0924..aae095d69 100644
--- a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
+++ b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
@@ -125,6 +125,8 @@ final class SoftwarePlaybackHost {
     private var audioOutput: AudioOutput?
     private var demuxer: Demuxer?
     private var vodPacketReadAhead: SoftwarePacketReadAhead?
+    /// #687: this host's entries in the process-wide retention ledger, released on `stop()`.
+    private var retentionClaims: [RetentionClaims.Claim] = []
 
     /// The same public buffered-position axis as the live and native hosts, but backed by
     /// actual compressed A/V packet coverage. nil when no continuous cache span contains the clock.
@@ -793,8 +795,14 @@ final class SoftwarePlaybackHost {
                 // window on a small volume shrinks instead of filling the disk.
                 let available = (try? baseDir.resourceValues(forKeys: [.volumeAvailableCapacityKey]))?
                     .volumeAvailableCapacity.map(Int64.init)
-                let budget = PacketRingBuffer.liveByteBudget(volumeAvailableBytes: available)
-                self.dvrRing = try PacketRingBuffer(windowSeconds: window, scratch: scratch, byteBudget: budget)
+                let claim = RetentionClaims.shared.claim(volumeAvailableBytes: available) {
+                    PacketRingBuffer.liveByteBudget(volumeAvailableBytes: $0)
+                }
+                let budget = claim.bytes
+                let ring = try PacketRingBuffer(windowSeconds: window, scratch: scratch, byteBudget: budget)
+                claim.track { [weak ring] in ring?.diskBytes ?? 0 }
+                self.retentionClaims.append(claim)
+                self.dvrRing = ring
                 EngineLog.emit("[SWHost] DVR ring armed window=\(String(format: "%.0f", window))s budget=\(budget >> 20)MiB scratch=\(scratch.lastPathComponent)", category: .swPlayback)
             } catch {
                 EngineLog.emit("[SWHost] DVR ring create failed (\(error)); live-only fallback", category: .swPlayback)
@@ -1010,18 +1018,20 @@ final class SoftwarePlaybackHost {
                 } : nil
             let initialSourceClock = initialClockTime.seconds
             let videoReorderDepth = Self.presentationReorderDepth(codecID: vCodecID)
-            let cacheResult = await Task.detached(priority: .utility) { () throws -> SoftwarePacketReadAhead? in
+            let cacheResult = await Task.detached(priority: .utility) { () throws -> (SoftwarePacketReadAhead, RetentionClaims.Claim)? in
                 let temp = URL(fileURLWithPath: NSTemporaryDirectory(), isDirectory: true)
                 let available = (try? temp.resourceValues(forKeys: [.volumeAvailableCapacityKey]))?
                     .volumeAvailableCapacity.map(Int64.init)
                 let segments = HLSVideoEngine.clampedForwardWindow(forwardBufferSegments)
-                let bytes = HLSVideoEngine.sessionRetentionBudgetBytes(
-                    volumeAvailableBytes: available,
-                    capRelaxed: HLSVideoEngine.retentionCapRelaxed(forwardWindowSegments: segments))
-                guard bytes > 0 else { return Optional<SoftwarePacketReadAhead>.none }
+                let capRelaxed = HLSVideoEngine.retentionCapRelaxed(forwardWindowSegments: segments)
+                let claim = RetentionClaims.shared.claim(volumeAvailableBytes: available) {
+                    HLSVideoEngine.sessionRetentionBudgetBytes(volumeAvailableBytes: $0, capRelaxed: capRelaxed)
+                }
+                let bytes = claim.bytes
+                guard bytes > 0 else { return nil }
                 let fifo = try SoftwarePacketDiskFIFO(
                     chunkTargetBytes: min(4 << 20, max(8, bytes)), retainConsumed: true)
-                return SoftwarePacketReadAhead(
+                let readAhead = SoftwarePacketReadAhead(
                     video: video, audio: audio, byteBudget: bytes,
                     forwardSeconds: Double(segments) * 4,
                     initialSourceClock: initialSourceClock, fifo: fifo,
@@ -1031,10 +1041,14 @@ final class SoftwarePlaybackHost {
                     defer { av_packet_unref(packet); av_packet_free_safe(packet) }
                     return try SoftwareStoredPacket(copying: packet)
                 }
+                claim.track { [weak readAhead] in readAhead?.snapshot.residentBytes ?? 0 }
+                return (readAhead, claim)
             }.result
             let readAhead: SoftwarePacketReadAhead?
             switch cacheResult {
-            case .success(let cache): readAhead = cache
+            case .success(let cache):
+                readAhead = cache?.0
+                if !stopRequested, let claim = cache?.1 { retentionClaims.append(claim) }
             case .failure:
                 // A cache-directory failure must not stop a source that the old direct loop can
                 // still play. Runtime spool corruption is explicit, never silently skipped.
@@ -1641,6 +1655,8 @@ final class SoftwarePlaybackHost {
         }
         dvrRing?.close()
         dvrRing = nil
+        retentionClaims.forEach { $0.release() }
+        retentionClaims.removeAll()
         liveEdgeLock.lock()
         sessionStartPts = .nan
         newestSourcePts = .nan
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine.swift b/Sources/AetherEngine/Video/HLSVideoEngine.swift
index a7b670501..b865fbfff 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine.swift
@@ -1001,6 +1001,8 @@ public final class HLSVideoEngine: @unchecked Sendable {
     /// playlist advertises stays resident; the producer-side prefetch park it also feeds is
     /// VOD-only (`advanceMuxer`), so live cannot park on it.
     private var retentionBudgetBytes: Int = 0
+    /// #687: this session's entry in the process-wide ledger, released on `stop()`.
+    private var retentionClaim: RetentionClaims.Claim?
 
     /// Clamp for `forwardWindowSegments`: below 4 the window would undercut AVPlayer's own ~5-7-segment
     /// prefetch and starve it (see `LiveWindowSizing.minSafeSegments`). The 2700 ceiling (~3 h at 4 s
@@ -1478,20 +1480,27 @@ public final class HLSVideoEngine: @unchecked Sendable {
             .volumeAvailableCapacityForImportantUsage
         #endif
         let capRelaxed = Self.retentionCapRelaxed(forwardWindowSegments: forwardWindowSegments)
-        let retentionBudget = Self.sessionRetentionBudgetBytes(volumeAvailableBytes: availableBytes,
-                                                               capRelaxed: capRelaxed)
+        // #687: sized from what the other running sessions leave, not from the raw free space.
+        let claim = RetentionClaims.shared.claim(volumeAvailableBytes: availableBytes) {
+            Self.sessionRetentionBudgetBytes(volumeAvailableBytes: $0, capRelaxed: capRelaxed)
+        }
+        let retentionBudget = claim.bytes
         self.retentionBudgetBytes = retentionBudget
         let segmentCache = SegmentCache(
             forwardWindow: forwardWindowSegments,
             retentionBudgetBytes: retentionBudget,
             onResidentSetChanged: { [weak self] in self?.noteResidentSetChanged() }
         )
+        claim.track { [weak segmentCache] in segmentCache?.totalBytes ?? 0 }
+        self.retentionClaim = claim
         self.cache = segmentCache
         EngineLog.emit(
             "[HLSVideoEngine] segment retention budget: \(retentionBudget / (1 << 20)) MiB "
             + "(volumeAvailable=\(availableBytes.map { "\($0 / (1 << 20)) MiB" } ?? "unknown"), "
             + "forwardWindow=\(forwardWindowSegments) seg"
-            + (capRelaxed ? ", opt-in prefetch: default cap relaxed" : "") + ")",
+            + (capRelaxed ? ", opt-in prefetch: default cap relaxed" : "")
+            + (claim.heldBackBytes > 0
+                ? ", \(claim.heldBackBytes / (1 << 20)) MiB held back for other sessions" : "") + ")",
             category: .session
         )
 
@@ -2479,6 +2488,8 @@ public final class HLSVideoEngine: @unchecked Sendable {
         // while the pump exits a parked HTTP byte-range read).
         restartLock.lock()
         sessionEpoch &+= 1
+        retentionClaim?.release()
+        retentionClaim = nil
         let p = producer
         producer = nil
         let s = server
diff --git a/Sources/AetherEngine/Video/RetentionClaims.swift b/Sources/AetherEngine/Video/RetentionClaims.swift
new file mode 100644
index 000000000..d42a7b3f6
--- /dev/null
+++ b/Sources/AetherEngine/Video/RetentionClaims.swift
@@ -0,0 +1,68 @@
+import Foundation
+
+/// What the running sessions may still write to the tmp volume (#687).
+///
+/// A session sizes its retention from the volume's free space, measured once at its start. A claim
+/// another session has made but not yet written is still free at that moment, so several sessions
+/// started together each took a quarter of the same space: four engines (a multiview host) claimed
+/// four quarters, i.e. the volume the clamp exists to protect.
+///
+/// So every session claims here, and a new one is sized from what is really left: the free space
+/// minus what the others have claimed and not yet written. A session alone gets what it always got;
+/// n sessions together leave at least `(3/4)^n` of the volume.
+final class RetentionClaims: @unchecked Sendable {
+
+    static let shared = RetentionClaims()
+
+    /// One session's allowance. Released by `release()` or when dropped.
+    final class Claim: @unchecked Sendable {
+        let bytes: Int
+        /// What the other sessions could still write when this claim was sized; for the log.
+        let heldBackBytes: Int
+        private let id = UUID()
+        private let ledger: RetentionClaims
+
+        fileprivate init(bytes: Int, heldBackBytes: Int, ledger: RetentionClaims) {
+            self.bytes = bytes
+            self.heldBackBytes = heldBackBytes
+            self.ledger = ledger
+            ledger.entries[id] = Entry(bytes: bytes, used: nil)
+        }
+
+        /// Reports what the session has written so far. Until it is set the whole claim counts as
+        /// unwritten, which only ever sizes a later session smaller.
+        func track(_ used: @escaping @Sendable () -> Int) {
+            ledger.lock.lock()
+            defer { ledger.lock.unlock() }
+            ledger.entries[id]?.used = used
+        }
+
+        func release() {
+            ledger.lock.lock()
+            defer { ledger.lock.unlock() }
+            ledger.entries.removeValue(forKey: id)
+        }
+
+        deinit { release() }
+    }
+
+    private struct Entry {
+        let bytes: Int
+        var used: (@Sendable () -> Int)?
+    }
+
+    private let lock = NSLock()
+    private var entries: [UUID: Entry] = [:]
+
+    /// Sizes a session with `sizing` over the free space the other claims leave, and records the
+    /// result. Unknown capacity is passed through as unknown.
+    ///
+    /// The `used` closures of the other claims run under this ledger's lock; they must not claim.
+    func claim(volumeAvailableBytes: Int64?, sizing: (Int64?) -> Int) -> Claim {
+        lock.lock()
+        defer { lock.unlock() }
+        let heldBack = entries.values.reduce(0) { $0 + max(0, $1.bytes - ($1.used?() ?? 0)) }
+        let left = volumeAvailableBytes.map { max(0, $0 - Int64(heldBack)) }
+        return Claim(bytes: max(0, sizing(left)), heldBackBytes: heldBack, ledger: self)
+    }
+}
diff --git a/Tests/AetherEngineTests/Issue687RetentionClaimsTests.swift b/Tests/AetherEngineTests/Issue687RetentionClaimsTests.swift
new file mode 100644
index 000000000..af446d216
--- /dev/null
+++ b/Tests/AetherEngineTests/Issue687RetentionClaimsTests.swift
@@ -0,0 +1,83 @@
+// Tests/AetherEngineTests/Issue687RetentionClaimsTests.swift
+// #687: every session sized its retention from the raw free space, so sessions started together each
+// took a quarter of the same space. A claim is now sized from what the other running claims leave.
+import Foundation
+import Testing
+@testable import AetherEngine
+
+@Suite("Retention claims across concurrent sessions")
+struct Issue687RetentionClaimsTests {
+
+    private func session(_ ledger: RetentionClaims, free: Int64?) -> RetentionClaims.Claim {
+        ledger.claim(volumeAvailableBytes: free) {
+            HLSVideoEngine.sessionRetentionBudgetBytes(volumeAvailableBytes: $0)
+        }
+    }
+
+    @Test("A session alone gets what it always got")
+    func aloneIsUnchanged() {
+        let ledger = RetentionClaims()
+        let claim = session(ledger, free: 4 << 30)
+        #expect(claim.bytes == 1 << 30)
+        #expect(claim.heldBackBytes == 0)
+    }
+
+    @Test("Four sessions on a tight volume no longer claim all of it")
+    func fourSessionsLeaveTheVolumeRoom() {
+        let ledger = RetentionClaims()
+        let free: Int64 = 4 << 30
+        let claims = (0..<4).map { _ in session(ledger, free: free) }
+        let total = claims.reduce(0) { $0 + $1.bytes }
+        #expect(claims[0].bytes == 1 << 30)
+        #expect(claims[1].bytes == (3 << 30) / 4)
+        #expect(Double(total) / Double(free) < 0.69)
+        #expect(claims.allSatisfy { $0.bytes > 0 })
+    }
+
+    @Test("A roomy volume still gives every session the cap")
+    func roomyVolumeKeepsTheCap() {
+        let ledger = RetentionClaims()
+        let claims = (0..<4).map { _ in session(ledger, free: 32 << 30) }
+        #expect(claims.allSatisfy { $0.bytes == 2 << 30 })
+    }
+
+    @Test("What a session has written is not held back twice")
+    func writtenBytesAreNotHeldBack() {
+        let ledger = RetentionClaims()
+        let first = session(ledger, free: 4 << 30)
+        first.track { 1 << 30 }
+        // The first session's GiB is on disk, so the measurement already misses it.
+        let second = session(ledger, free: 3 << 30)
+        #expect(second.heldBackBytes == 0)
+        #expect(second.bytes == (3 << 30) / 4)
+    }
+
+    @Test("A released claim frees its share, and a dropped one does too")
+    func releaseFreesTheShare() {
+        let ledger = RetentionClaims()
+        let first = session(ledger, free: 4 << 30)
+        first.release()
+        first.release()
+        #expect(session(ledger, free: 4 << 30).bytes == 1 << 30)
+        #expect(session(ledger, free: 4 << 30).bytes == 1 << 30)
+    }
+
+    @Test("Unknown capacity stays unknown and keeps the cap")
+    func unknownCapacityKeepsTheCap() {
+        let ledger = RetentionClaims()
+        let first = session(ledger, free: nil)
+        let second = session(ledger, free: nil)
+        #expect(first.bytes == 2 << 30)
+        #expect(second.bytes == 2 << 30)
+    }
+
+    @Test("The software live ring keeps its floor when others hold everything back")
+    func liveRingKeepsItsFloor() {
+        let ledger = RetentionClaims()
+        let first = session(ledger, free: 1 << 30)
+        let ring = ledger.claim(volumeAvailableBytes: Int64(first.bytes) / 2) {
+            PacketRingBuffer.liveByteBudget(volumeAvailableBytes: $0)
+        }
+        #expect(ring.bytes == PacketRingBuffer.minimumLiveByteBudget)
+    }
+}
diff --git a/docs/api.md b/docs/api.md
index f976833db..6027a078d 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -409,6 +409,7 @@ Each `AetherEngine` has its own loopback server, caches and lifecycle, so two or
 - The audio session is released only by the last engine to stop, and only if some engine in that round had `deactivatesAudioSessionOnStop`.
 - The preferred output channel count is the widest source among the playing engines, so a muted stereo tile cannot downmix a 5.1 one.
 - A display-criteria reset waits until the last engine stops, the ones a load runs to clear stale criteria included; an engine that loads again as `.primary` in the meantime cancels its own pending reset, one that loads again as `.secondary` keeps it.
+- The disk allowance for seek and timeshift history (a quarter of the free space, at most 2 GiB per session) is taken from what the other running engines have not already claimed, so side-by-side engines cannot claim the same space twice. A claim ends with the session.
 - Stop every engine before you let go of it. An engine counts as playing from `load()` until `stop()`, whatever its state, `.error` and `.ended` included, so an engine kept for reuse must be stopped when its tile ends or fails, or the last real stop will not release the session. An engine released without `stop()` is noticed and dropped the next time another engine asks, but until then it counts as playing.
 
 Load one engine as `.primary` and the others with `LoadOptions(sharedOutputRole: .secondary)`, set `logTag` (set before `load()`) on each, and control what is audible with `volume`. Every engine keeps decoding its audio, so switching the audible one is a volume change and not a reload.
@@ -1060,7 +1061,7 @@ All flags default to safe values; the table is the full set. Depth for the media
 | --- | --- | --- |
 | `httpHeaders` | empty | Extra headers on every probe, range and segment fetch. On `nativeRemoteHLS` they ride into the `AVURLAsset`, so header-enforcing IPTV origins work. Forwarded to sidecar subtitle fetches unless overridden. **Scoping differs by route.** On the plain `nativeRemoteHLS` bypass AVFoundation itself sends them to every host the playlists name (cross-host variants, segments and `EXT-X-KEY` URIs) and carries them across 302 redirects, so credential headers there reach every such host and the engine cannot narrow that. The per-origin credential scoping described for `HLSLiveIngestReader` applies only on the routes the engine fetches itself: the ingest, the disc reader, the origin relay, the subtitle proxy, the audio tap and the live subtitle renditions. A credential that must not reach every host a playlist names should not ride in `httpHeaders` on the bypass. |
 | `isLive` | false | Treat the source as live. Set it explicitly; duration-based auto-detection is too noisy. |
-| `dvrWindowSeconds` | nil | Timeshift window. nil means live-only and `seek` is a no-op. The window is a ceiling: the disk budget (a quarter of the free space, at most 2 GiB) bounds what is actually kept, so a long window on a high-bitrate channel or a small volume holds less than it asks for. |
+| `dvrWindowSeconds` | nil | Timeshift window. nil means live-only and `seek` is a no-op. The window is a ceiling: the disk budget (a quarter of the free space, at most 2 GiB) bounds what is actually kept, so a long window on a high-bitrate channel or a small volume holds less than it asks for. With several engines running, each one's quarter is taken from the free space the others have not already claimed, so a tile added on a tight volume holds less history than the first one (AE#687). |
 | `liveJoinProfile` | `.standard` | A `LiveJoinProfile`. `.fastZap` collapses TARGETDURATION to 1.5 x the source GOP (AE#670) so an IPTV join costs seconds instead of a full holdback. |
 | `clampsLiveResumeToWindow` | true | Whether `play()` may move a behind-live playhead by itself (edge snap on a live-only source more than 45 s behind, or a landing above the retained floor when a DVR window has slid past it). `false` hands the whole decision to the host, which then also owns the eviction case. |
 | `liveJoinStartsImmediately` | true | Cuts AVPlayer's stall-avoidance wait short once at the live join, over a buffer that is non-empty and at least 1.5 s deep, on an item that has reached `readyToPlay` (AE#684). The join tail no host can otherwise reach; default since 6.55.0 on a device A/B, see the live-join section. |
diff --git a/docs/architecture.md b/docs/architecture.md
index 20683f4b3..57c7f23f2 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -496,7 +496,8 @@ Sources/AetherEngine/
 │   ├── SegmentCache.swift                   Native path: producer/consumer segment store with backpressure, scrub-aware eviction + byte-budgeted VOD backward retention (restart-free back-seeks)
 │   ├── VTCapabilityProbe.swift              AV1 system-decode probe + per-format `canHardwareDecode` HW-decodability check for H.264 / HEVC profiles (Intel Macs, older chips, #2); gates codec routing (VP9 / VP8 / MPEG-4 Part 2 / MPEG-2 / VC-1 and interlaced H.264 always route SW, see VideoRoutingPolicy)
 │   ├── LiveCadencePolicy.swift              Turns the observed arrival cadence into the two LL-HLS decisions (served TARGETDURATION, blocking-reload eligibility), re-evaluated on every manifest render, instead of trusting a bursty origin's own number
-│   └── PrefetchDiskBudget.swift             Disk bound for an opt-in whole-source prefetch: the hard window is never evicted, so the budget bounds only what lives outside it (#207)
+│   ├── PrefetchDiskBudget.swift             Disk bound for an opt-in whole-source prefetch: the hard window is never evicted, so the budget bounds only what lives outside it (#207)
+│   └── RetentionClaims.swift                Process-wide ledger of the running sessions' disk allowances: a new session is sized from the free space minus what the others may still write, so concurrent engines cannot each claim a quarter of the same space (#687)
 └── View/
     └── AetherPlayerView.swift               Polymorphic surface: hosts either AVPlayerLayer (native) or AVSampleBufferDisplayLayer (SW)
 ```

From de9fd838713f262838962c1be0fb1e853f31c498 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 2 Oct 2026 16:07:18 +0200
Subject: [PATCH 288/359] chore(release): prep 7.25.3 - engines running side by
 side no longer claim the same free space twice

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                    | 4 ++++
 Examples/README.md                              | 2 +-
 README.md                                       | 6 +++---
 Sources/AetherEngine/AetherEngine+Version.swift | 2 +-
 4 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index ef89f70e3..aa46c0578 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,10 @@ the public-API contract.
 
 ## [Unreleased]
 
+_Nothing yet._
+
+## [7.25.3] - 2026-10-02
+
 ### Fixed
 
 - **Engines running side by side each claimed a quarter of the same free space (#687).** A session sizes its disk allowance once, at its start, as `min(2 GiB, a quarter of the tmp volume's free space)`. An allowance another session had claimed but not yet written was still free at that moment, so four engines started together (a multiview host) could claim four quarters: on 4 GiB free, the whole volume. A session is now sized from the free space minus what the other running sessions may still write. One session alone gets exactly what it got; four on 4 GiB free take 2.7 GiB instead of 4, and n sessions always leave at least `(3/4)^n` of the volume. The live window already follows its allowance (#443), so a smaller share means a shorter timeshift depth on the later tiles, and the session log says how much was held back. Covers the native session, the software live ring and the software VOD read-ahead; no API change.
diff --git a/Examples/README.md b/Examples/README.md
index 097b42744..f95e763dd 100644
--- a/Examples/README.md
+++ b/Examples/README.md
@@ -18,7 +18,7 @@ Three samples covering different audiences:
    ```
    https://github.com/superuser404notfound/AetherEngine
    ```
-   Dependency Rule: Up to Next Major Version, starting from `7.25.2`. Add the `AetherEngine` library product to your app target.
+   Dependency Rule: Up to Next Major Version, starting from `7.25.3`. Add the `AetherEngine` library product to your app target.
 
 3. **Drop the file in.** Replace the Xcode template's default `App.swift` (or whatever the generated `@main` file is called) with the contents of [`MinimalPlayerApp.swift`](MinimalPlayer/MinimalPlayerApp.swift). The file is self-contained: it defines both the `@main App` struct and the `ContentView`.
 
diff --git a/README.md b/README.md
index 0f53c954f..ef43e150e 100644
--- a/README.md
+++ b/README.md
@@ -384,7 +384,7 @@ Subtitle cues land in raw source PTS; render the overlay against `player.sourceT
 Install via Swift Package Manager:
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.25.2")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.25.3")
 ```
 
 Three samples ship in `Examples/`:
@@ -631,10 +631,10 @@ Browse all of this as a searchable site at **[aetherengine.superuser404.de](http
 AetherEngine uses [Semantic Versioning](https://semver.org). The public API surface, every `public` declaration in `Sources/AetherEngine/`, is the stability contract. **Major** removes / renames public symbols or breaks adopters; **Minor** adds public API or codec / format support; **Patch** fixes bugs with no public API change. `internal` types are not part of the contract.
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.25.2")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.25.3")
 ```
 
-Pin to `.upToNextMinor(from: "7.25.2")` for stricter teams that prefer to opt into minor bumps explicitly.
+Pin to `.upToNextMinor(from: "7.25.3")` for stricter teams that prefer to opt into minor bumps explicitly.
 
 ## Requirements
 
diff --git a/Sources/AetherEngine/AetherEngine+Version.swift b/Sources/AetherEngine/AetherEngine+Version.swift
index 2d617f1f6..5d58ea83e 100644
--- a/Sources/AetherEngine/AetherEngine+Version.swift
+++ b/Sources/AetherEngine/AetherEngine+Version.swift
@@ -11,5 +11,5 @@ extension AetherEngine {
     ///
     /// Between releases, and in a consumer that pins an unreleased commit for a device test, this
     /// names the last PUBLISHED version the checkout descends from, not every patch in it.
-    public nonisolated static let version = "7.25.2"
+    public nonisolated static let version = "7.25.3"
 }

From cc31e0477dd9eb87ba2cd6531e2b580113005551 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 2 Oct 2026 16:31:03 +0200
Subject: [PATCH 289/359] test(load): the parked reader outlasts a loaded
 runner before the cancel arrives

The reader gave up after 10 s. On a busy CI runner the main actor needed
longer than that to reach the cancel, so the load had already failed with
the reader's own error and the test read it as a missed cancellation.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 Tests/AetherEngineTests/CancellableLoadTests.swift | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/Tests/AetherEngineTests/CancellableLoadTests.swift b/Tests/AetherEngineTests/CancellableLoadTests.swift
index 2f2962210..d081a50bc 100644
--- a/Tests/AetherEngineTests/CancellableLoadTests.swift
+++ b/Tests/AetherEngineTests/CancellableLoadTests.swift
@@ -11,14 +11,16 @@ import Testing
 struct CancellableLoadTests {
 
     /// Parks its first read until the engine closes or cancels it, or until `fallback` runs out,
-    /// which only an engine that never reaches it lets happen.
+    /// which only an engine that never reaches it lets happen. The fallback is far above the wait:
+    /// on a loaded CI runner the main actor took over 10 s to get from "entered" to the cancel, and
+    /// the read gave up first, so the load failed before it was cancelled.
     final class ParkedReader: IOReader, @unchecked Sendable {
         private let condition = NSCondition()
         private let fallback: TimeInterval
         private var arrivals = 0
         private var releasedByEngine = false
 
-        init(fallback: TimeInterval = 10) { self.fallback = fallback }
+        init(fallback: TimeInterval = 60) { self.fallback = fallback }
 
         var entered: Bool { condition.withLock { arrivals > 0 } }
         var wasReleasedByEngine: Bool { condition.withLock { releasedByEngine } }

From c4b1c66433500c671d2aa3e58759b51ea120410a Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 2 Oct 2026 20:59:16 +0200
Subject: [PATCH 290/359] feat(hls): decide when a session can serve an I-frame
 rendition (#682)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../AetherEngine/Video/HLSVideoEngine.swift   |  8 ++-
 .../Video/IFrameRenditionEligibility.swift    | 46 +++++++++++++++
 .../IFrameRenditionEligibilityTests.swift     | 56 +++++++++++++++++++
 .../MasterRoutingTests.swift                  | 22 +++++++-
 4 files changed, 128 insertions(+), 4 deletions(-)
 create mode 100644 Sources/AetherEngine/Video/IFrameRenditionEligibility.swift
 create mode 100644 Tests/AetherEngineTests/IFrameRenditionEligibilityTests.swift

diff --git a/Sources/AetherEngine/Video/HLSVideoEngine.swift b/Sources/AetherEngine/Video/HLSVideoEngine.swift
index b865fbfff..e0ff0ea3f 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine.swift
@@ -2116,6 +2116,9 @@ public final class HLSVideoEngine: @unchecked Sendable {
     /// symptom (htrung14, tvOS transport bar, Apple TV 4K 3rd gen). Routing-safety still decides: an
     /// unready HDR panel is a -11848 rejection, and a language is not worth one.
     ///
+    /// AE#682: `hasIFrameRendition` is a third reason of the same shape. `EXT-X-I-FRAME-STREAM-INF`
+    /// lives only in a master, and it is likewise not worth a display rejection.
+    ///
     /// #130: `frameRateKnown` gates PQ/HLG masters. AVPlayer filters a VIDEO-RANGE=PQ/HLG
     /// EXT-X-STREAM-INF that has no FRAME-RATE attribute out of the master at parse time and fails
     /// the item with NSURLErrorDomain -1002 without ever fetching media.m3u8 (byte-exact local
@@ -2131,7 +2134,8 @@ public final class HLSVideoEngine: @unchecked Sendable {
         builtInPanelEngagesOnDemand: Bool,
         frameRateKnown: Bool,
         videoCodecNeedsMasterSignaling: Bool = false,
-        hasAudioRendition: Bool = false
+        hasAudioRendition: Bool = false,
+        hasIFrameRendition: Bool = false
     ) -> Bool {
         let sourceIsHDR = videoRange != .sdr || effectiveDvMode
         let panelReadyForHDR = panelIsInHDRMode
@@ -2149,7 +2153,7 @@ public final class HLSVideoEngine: @unchecked Sendable {
         // before any media fetch (macOS / the Simulator build the track from the init hvcC and never
         // reproduce it). Forcing the master where it is routing-safe (SDR on any panel, HDR on a ready
         // one) closes that gap; the caller scopes the flag to tvOS + HEVC.
-        if (hasNativeSubs || videoCodecNeedsMasterSignaling || hasAudioRendition)
+        if (hasNativeSubs || videoCodecNeedsMasterSignaling || hasAudioRendition || hasIFrameRendition)
             && routingSafeForMaster { return true }
         return sourceIsHDR && panelReadyForHDR
     }
diff --git a/Sources/AetherEngine/Video/IFrameRenditionEligibility.swift b/Sources/AetherEngine/Video/IFrameRenditionEligibility.swift
new file mode 100644
index 000000000..58b2feec4
--- /dev/null
+++ b/Sources/AetherEngine/Video/IFrameRenditionEligibility.swift
@@ -0,0 +1,46 @@
+// Sources/AetherEngine/Video/IFrameRenditionEligibility.swift
+import Foundation
+
+/// AE#682: whether a session serves the I-frame rendition. Pure, so the rule is testable without a
+/// session. The rendition is all or nothing: AVKit shows a stale picture for a keyframe it cannot
+/// fetch, so a session that cannot answer every listed entry lists none.
+enum IFrameRenditionEligibility {
+    enum AbsentReason: String, Equatable {
+        case notRequested, live, planNotKeyframeAligned, sequentialOrigin, heldSourceConnection
+        case serialOrigin, discSource, noSecondReader, mediaPlaylistRouting
+    }
+
+    enum Verdict: Equatable {
+        case served
+        case absent(AbsentReason)
+    }
+
+    struct Inputs {
+        var requested: Bool
+        var isLive: Bool
+        var planBoundariesClaimRandomAccess: Bool
+        var sequentialOrigin: Bool
+        var heldSourceConnection: Bool
+        var originIsSerial: Bool
+        var isDiscSource: Bool
+        var secondReaderAvailable: Bool
+    }
+
+    /// Everything except the master decision, which needs this verdict as one of its inputs.
+    static func candidate(_ i: Inputs) -> Verdict {
+        guard i.requested else { return .absent(.notRequested) }
+        if i.isLive { return .absent(.live) }
+        guard i.planBoundariesClaimRandomAccess else { return .absent(.planNotKeyframeAligned) }
+        if i.sequentialOrigin { return .absent(.sequentialOrigin) }
+        if i.heldSourceConnection { return .absent(.heldSourceConnection) }
+        if i.originIsSerial { return .absent(.serialOrigin) }
+        if i.isDiscSource { return .absent(.discSource) }
+        guard i.secondReaderAvailable else { return .absent(.noSecondReader) }
+        return .served
+    }
+
+    static func resolve(candidate: Verdict, servingMaster: Bool) -> Verdict {
+        guard candidate == .served else { return candidate }
+        return servingMaster ? .served : .absent(.mediaPlaylistRouting)
+    }
+}
diff --git a/Tests/AetherEngineTests/IFrameRenditionEligibilityTests.swift b/Tests/AetherEngineTests/IFrameRenditionEligibilityTests.swift
new file mode 100644
index 000000000..61c1457b4
--- /dev/null
+++ b/Tests/AetherEngineTests/IFrameRenditionEligibilityTests.swift
@@ -0,0 +1,56 @@
+// Tests/AetherEngineTests/IFrameRenditionEligibilityTests.swift
+import Testing
+@testable import AetherEngine
+
+struct IFrameRenditionEligibilityTests {
+    private func inputs(_ change: (inout IFrameRenditionEligibility.Inputs) -> Void = { _ in })
+        -> IFrameRenditionEligibility.Inputs {
+        var i = IFrameRenditionEligibility.Inputs(
+            requested: true, isLive: false, planBoundariesClaimRandomAccess: true,
+            sequentialOrigin: false, heldSourceConnection: false, originIsSerial: false,
+            isDiscSource: false, secondReaderAvailable: true)
+        change(&i)
+        return i
+    }
+
+    @Test("every requirement met is a candidate")
+    func allMet() {
+        #expect(IFrameRenditionEligibility.candidate(inputs()) == .served)
+    }
+
+    @Test("each failed requirement names its own reason",
+          arguments: ["notRequested", "live", "planNotKeyframeAligned", "sequentialOrigin",
+                      "heldSourceConnection", "serialOrigin", "discSource", "noSecondReader"])
+    func eachReason(reason: String) throws {
+        let expected = try #require(IFrameRenditionEligibility.AbsentReason(rawValue: reason))
+        let verdict = IFrameRenditionEligibility.candidate(inputs { i in
+            switch expected {
+            case .notRequested: i.requested = false
+            case .live: i.isLive = true
+            case .planNotKeyframeAligned: i.planBoundariesClaimRandomAccess = false
+            case .sequentialOrigin: i.sequentialOrigin = true
+            case .heldSourceConnection: i.heldSourceConnection = true
+            case .serialOrigin: i.originIsSerial = true
+            case .discSource: i.isDiscSource = true
+            case .noSecondReader: i.secondReaderAvailable = false
+            case .mediaPlaylistRouting: break
+            }
+        })
+        #expect(verdict == .absent(expected))
+    }
+
+    @Test("not requested wins over every other reason, so an unflagged session logs nothing odd")
+    func notRequestedFirst() {
+        let v = IFrameRenditionEligibility.candidate(inputs { $0.requested = false; $0.isLive = true })
+        #expect(v == .absent(.notRequested))
+    }
+
+    @Test("a candidate without a master is absent for routing")
+    func mediaRouting() {
+        #expect(IFrameRenditionEligibility.resolve(candidate: .served, servingMaster: false)
+                == .absent(.mediaPlaylistRouting))
+        #expect(IFrameRenditionEligibility.resolve(candidate: .served, servingMaster: true) == .served)
+        #expect(IFrameRenditionEligibility.resolve(candidate: .absent(.live), servingMaster: true)
+                == .absent(.live))
+    }
+}
diff --git a/Tests/AetherEngineTests/MasterRoutingTests.swift b/Tests/AetherEngineTests/MasterRoutingTests.swift
index ebdecbc19..d263a95cc 100644
--- a/Tests/AetherEngineTests/MasterRoutingTests.swift
+++ b/Tests/AetherEngineTests/MasterRoutingTests.swift
@@ -17,14 +17,16 @@ struct MasterRoutingTests {
                        panelEngagesOnDemand: Bool = false,
                        frameRateKnown: Bool = true,
                        hevcNeedsMasterSignaling: Bool = false,
-                       audioRendition: Bool = false) -> Bool {
+                       audioRendition: Bool = false,
+                       iFrameRendition: Bool = false) -> Bool {
         HLSVideoEngine.resolveUseMasterPlaylist(
             videoRange: videoRange, effectiveDvMode: effectiveDvMode,
             panelIsInHDRMode: panelHDR, displaySupportsHDR: displayHDR,
             hasNativeSubs: nativeSubs, builtInPanelEngagesOnDemand: panelEngagesOnDemand,
             frameRateKnown: frameRateKnown,
             videoCodecNeedsMasterSignaling: hevcNeedsMasterSignaling,
-            hasAudioRendition: audioRendition)
+            hasAudioRendition: audioRendition,
+            hasIFrameRendition: iFrameRendition)
     }
 
     @Test("tvOS: HDR source on an SDR-parked panel stays media-direct (-11848 guard)")
@@ -162,4 +164,20 @@ struct MasterRoutingTests {
         #expect(!HLSVideoEngine.builtInPanelEngagesOnDemand)
         #endif
     }
+
+    @Test("AE#682: an I-frame rendition forces the master for an SDR source, like a subtitle rendition")
+    func iFrameRenditionForcesMasterOnSDR() {
+        #expect(!route(videoRange: .sdr))
+        #expect(route(videoRange: .sdr, iFrameRendition: true))
+    }
+
+    @Test("AE#682: an I-frame rendition never forces an HDR master onto an unready panel")
+    func iFrameRenditionRespectsRoutingSafety() {
+        #expect(!route(videoRange: .pq, displayHDR: true, iFrameRendition: true))
+    }
+
+    @Test("AE#682: an I-frame rendition cannot rescue a PQ master without a frame rate (#130)")
+    func iFrameRenditionRespectsFrameRateGate() {
+        #expect(!route(videoRange: .pq, panelHDR: true, frameRateKnown: false, iFrameRendition: true))
+    }
 }

From a7797a523e36c1a1d00d1dd245ef57bbd5dc43e6 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 2 Oct 2026 21:00:31 +0200
Subject: [PATCH 291/359] feat(hls): the loopback server can list and route an
 I-frame rendition (#682)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../AetherEngine/Network/HLSLocalServer.swift |  93 ++++++++++++++
 .../IFramePlaylistTextTests.swift             | 119 ++++++++++++++++++
 2 files changed, 212 insertions(+)
 create mode 100644 Tests/AetherEngineTests/IFramePlaylistTextTests.swift

diff --git a/Sources/AetherEngine/Network/HLSLocalServer.swift b/Sources/AetherEngine/Network/HLSLocalServer.swift
index 082a04d76..fa345c22f 100644
--- a/Sources/AetherEngine/Network/HLSLocalServer.swift
+++ b/Sources/AetherEngine/Network/HLSLocalServer.swift
@@ -94,6 +94,12 @@ protocol HLSSegmentProvider: AnyObject {
     /// has the cues for a segment in the store by the time AVPlayer fetches it.
     func nativeSubtitleVTT(ordinal: Int, segmentIndex: Int) -> String?
 
+    /// AE#682: true when this session lists an I-frame rendition in its master. The two calls below
+    /// answer `iframe_init.mp4` and `iframe{N}.mp4`; both may block on a source read.
+    var iFrameRenditionServed: Bool { get }
+    func iFrameInitSegment() -> Data?
+    func iFrameSegment(at index: Int) -> Data?
+
     /// Atomic snapshot at the top of each playlist build. discontinuitySequence = EXT-X-DISCONTINUITY-tagged segments that slid out of the window (RFC 8216 §6.2.2 requires incrementing it; omission slips AVPlayer's discontinuity tracking one window per boundary). firstVisible in the same snapshot: a separate lock acquisition let a concurrent slide produce MEDIA-SEQUENCE newer than the count.
     func notePlaylistBuild() -> (visibleCount: Int, firstVisible: Int, refreshCounter: Int, endlistAdded: Bool, discontinuitySequence: Int)
 
@@ -158,6 +164,9 @@ extension HLSSegmentProvider {
     var nativeSubtitleDefaultOrdinal: Int { 0 }
     var nativeSubtitleWholeProgram: Bool { false }
     func nativeSubtitleVTT(ordinal: Int, segmentIndex: Int) -> String? { nil }
+    var iFrameRenditionServed: Bool { false }
+    func iFrameInitSegment() -> Data? { nil }
+    func iFrameSegment(at index: Int) -> Data? { nil }
     var liveTargetSegmentDuration: Double? { nil }
     var liveRejoinStart: (segmentIndex: Int, secondsIntoSegment: Double)? { nil }
     func noteServedLiveRejoinPlacement(timeOffset: Double, firstVisible: Int) {}
@@ -1119,6 +1128,27 @@ final class HLSLocalServer: @unchecked Sendable {
                            data: Data(vtt.utf8),
                            contentType: "text/vtt")
 
+        case "/iframe.m3u8":
+            guard let prov = provider, prov.iFrameRenditionServed else {
+                return send404(fd: fd, path: normalizedPath, reason: "no I-frame rendition")
+            }
+            let body = Self.buildIFramePlaylistText(provider: prov, subResourceBaseURL: subResourceBaseURL)
+            return send200(fd: fd, path: normalizedPath, data: Data(body.utf8),
+                           contentType: "application/vnd.apple.mpegurl")
+
+        case "/iframe_init.mp4":
+            guard let data = provider?.iFrameInitSegment(), !data.isEmpty else {
+                return send404(fd: fd, path: normalizedPath, reason: "I-frame init unavailable")
+            }
+            return send200(fd: fd, path: normalizedPath, data: data, contentType: "video/mp4")
+
+        case let p where p.hasPrefix("/iframe") && p.hasSuffix(".mp4"):
+            guard let index = Self.parseIFramePath(p),
+                  let data = provider?.iFrameSegment(at: index), !data.isEmpty else {
+                return send404(fd: fd, path: normalizedPath, reason: "no I-frame for \(normalizedPath)")
+            }
+            return send200(fd: fd, path: normalizedPath, data: data, contentType: "video/mp4")
+
         case "/init.mp4":
             stateLock.lock(); servedMediaBytes = true; stateLock.unlock()
             let data = provider?.initSegment() ?? Data()
@@ -1661,6 +1691,69 @@ final class HLSLocalServer: @unchecked Sendable {
         }
         lines.append("#EXT-X-STREAM-INF:\(streamInfAttrs.joined(separator: ","))")
         lines.append("media.m3u8")
+        if provider.iFrameRenditionServed {
+            // AE#682: BANDWIDTH is the variant's, an honest ceiling (one keyframe cannot outweigh the
+            // segment it opens). A value below the real peak logs -12318 on every fetch.
+            var iFrameAttrs = ["BANDWIDTH=\(bandwidth)", "CODECS=\"\(videoCodecs(of: codecs))\""]
+            if variant == .primary, let supplemental = provider.masterSupplementalCodecs {
+                iFrameAttrs.append("SUPPLEMENTAL-CODECS=\"\(supplemental)\"")
+            }
+            if let resolution = provider.masterResolution {
+                iFrameAttrs.append("RESOLUTION=\(resolution.width)x\(resolution.height)")
+            }
+            if let range = provider.masterVideoRange {
+                iFrameAttrs.append("VIDEO-RANGE=\(range.rawValue)")
+            }
+            iFrameAttrs.append("URI=\"iframe.m3u8\"")
+            lines.append("#EXT-X-I-FRAME-STREAM-INF:\(iFrameAttrs.joined(separator: ","))")
+        }
+        return lines.joined(separator: "\n") + "\n"
+    }
+
+    /// The video entry of a master CODECS list. An I-frame variant carries no audio, and a CODECS
+    /// that names one makes AVPlayer look for a track the fragments do not have.
+    static func videoCodecs(of codecs: String) -> String {
+        let videoPrefixes = ["avc1", "avc3", "hvc1", "hev1", "dvh1", "dvhe", "av01", "vp09"]
+        let video = codecs.split(separator: ",")
+            .map { $0.trimmingCharacters(in: .whitespaces) }
+            .filter { entry in videoPrefixes.contains { entry.hasPrefix($0) } }
+        return video.isEmpty ? codecs : video.joined(separator: ",")
+    }
+
+    /// "/iframe{N}.mp4" -> N. nil for the init, for a negative or non-numeric index, and for any
+    /// other path.
+    static func parseIFramePath(_ path: String) -> Int? {
+        guard path.hasPrefix("/iframe"), path.hasSuffix(".mp4") else { return nil }
+        let digits = path.dropFirst("/iframe".count).dropLast(".mp4".count)
+        guard !digits.isEmpty, digits.allSatisfy(\.isNumber) else { return nil }
+        return Int(digits)
+    }
+
+    /// AE#682: one entry per plan segment, each a single keyframe in its own resource. Same count,
+    /// EXTINF and TARGETDURATION as the VOD media playlist, so both renditions describe one timeline.
+    /// VOD only; the caller never lists this rendition for a live or event session.
+    static func buildIFramePlaylistText(provider: HLSSegmentProvider,
+                                        subResourceBaseURL: URL? = nil) -> String {
+        let count = provider.segmentCount
+        var maxDuration: Double = 0
+        for i in 0..<count { maxDuration = max(maxDuration, provider.segmentDuration(at: i)) }
+        let targetDuration = LiveEdgePolicy.targetDurationSeconds(
+            maxSegmentDuration: maxDuration, cutTargetSeconds: nil, cadenceFloorSeconds: nil)
+        let prefix: String
+        if let base = subResourceBaseURL {
+            let baseStr = base.absoluteString
+            prefix = baseStr.hasSuffix("/") ? baseStr : baseStr + "/"
+        } else {
+            prefix = ""
+        }
+        var lines = ["#EXTM3U", "#EXT-X-VERSION:7", "#EXT-X-I-FRAMES-ONLY",
+                     "#EXT-X-TARGETDURATION:\(targetDuration)", "#EXT-X-MEDIA-SEQUENCE:0",
+                     "#EXT-X-PLAYLIST-TYPE:VOD", "#EXT-X-MAP:URI=\"\(prefix)iframe_init.mp4\""]
+        for i in 0..<count {
+            lines.append("#EXTINF:\(String(format: "%.3f", provider.segmentDuration(at: i))),")
+            lines.append("\(prefix)iframe\(i).mp4")
+        }
+        lines.append("#EXT-X-ENDLIST")
         return lines.joined(separator: "\n") + "\n"
     }
 
diff --git a/Tests/AetherEngineTests/IFramePlaylistTextTests.swift b/Tests/AetherEngineTests/IFramePlaylistTextTests.swift
new file mode 100644
index 000000000..27d320a1d
--- /dev/null
+++ b/Tests/AetherEngineTests/IFramePlaylistTextTests.swift
@@ -0,0 +1,119 @@
+// Tests/AetherEngineTests/IFramePlaylistTextTests.swift
+import Testing
+import Foundation
+@testable import AetherEngine
+
+private final class IFrameMockProvider: HLSSegmentProvider, @unchecked Sendable {
+    let served: Bool
+    let durations: [Double]
+    let supplemental: String?
+    init(served: Bool, durations: [Double] = [4.0, 4.0, 2.5], supplemental: String? = nil) {
+        self.served = served; self.durations = durations; self.supplemental = supplemental
+    }
+    func initSegment() -> Data? { Data([0x00]) }
+    func mediaSegment(at index: Int) -> Data? { Data([0x00]) }
+    var segmentCount: Int { durations.count }
+    func segmentDuration(at index: Int) -> Double { durations[index] }
+    var playlistType: HLSPlaylistType { .vod }
+    var masterCodecs: String? { "hvc1.2.4.L150.B0,ec-3" }
+    var masterSupplementalCodecs: String? { supplemental }
+    var masterResolution: (width: Int, height: Int)? { (3840, 2160) }
+    var masterVideoRange: HLSVideoRange? { .pq }
+    var masterBandwidth: Int? { 12_000_000 }
+    var masterFrameRate: Double? { 23.976 }
+    var iFrameRenditionServed: Bool { served }
+}
+
+struct IFramePlaylistTextTests {
+    @Test("master carries one I-frame line, after the variant, with the video codec only")
+    func masterLine() {
+        let m = HLSLocalServer.buildMasterPlaylistText(provider: IFrameMockProvider(served: true))
+        let lines = m.split(separator: "\n").map(String.init)
+        let tag = lines.filter { $0.hasPrefix("#EXT-X-I-FRAME-STREAM-INF:") }
+        #expect(tag.count == 1)
+        #expect(tag[0] == "#EXT-X-I-FRAME-STREAM-INF:BANDWIDTH=12000000,CODECS=\"hvc1.2.4.L150.B0\","
+                + "RESOLUTION=3840x2160,VIDEO-RANGE=PQ,URI=\"iframe.m3u8\"")
+        let variantURI = try! #require(lines.firstIndex(of: "media.m3u8"))
+        #expect(lines.firstIndex(of: tag[0])! > variantURI)
+    }
+
+    @Test("master is untouched when the rendition is not served")
+    func masterWithout() {
+        let m = HLSLocalServer.buildMasterPlaylistText(provider: IFrameMockProvider(served: false))
+        #expect(!m.contains("I-FRAME"))
+        #expect(m.hasSuffix("media.m3u8\n"))
+    }
+
+    @Test("SUPPLEMENTAL-CODECS rides on the primary master and is dropped on the reduced one")
+    func supplementalFollowsVariant() {
+        let p = IFrameMockProvider(served: true, supplemental: "dvh1.08.06/db1p")
+        let primary = HLSLocalServer.buildMasterPlaylistText(provider: p)
+        let reduced = HLSLocalServer.buildMasterPlaylistText(provider: p, variant: .reducedHDR)
+        let tag: (String) -> String = { text in
+            text.split(separator: "\n").map(String.init).first { $0.hasPrefix("#EXT-X-I-FRAME-STREAM-INF:") }!
+        }
+        #expect(tag(primary).contains("SUPPLEMENTAL-CODECS=\"dvh1.08.06/db1p\""))
+        #expect(!tag(reduced).contains("SUPPLEMENTAL-CODECS"))
+        #expect(tag(reduced).contains("URI=\"iframe.m3u8\""))
+    }
+
+    @Test("I-frame playlist mirrors the plan one entry per segment")
+    func playlist() {
+        let p = IFrameMockProvider(served: true)
+        let text = HLSLocalServer.buildIFramePlaylistText(provider: p)
+        #expect(text == """
+        #EXTM3U
+        #EXT-X-VERSION:7
+        #EXT-X-I-FRAMES-ONLY
+        #EXT-X-TARGETDURATION:4
+        #EXT-X-MEDIA-SEQUENCE:0
+        #EXT-X-PLAYLIST-TYPE:VOD
+        #EXT-X-MAP:URI="iframe_init.mp4"
+        #EXTINF:4.000,
+        iframe0.mp4
+        #EXTINF:4.000,
+        iframe1.mp4
+        #EXTINF:2.500,
+        iframe2.mp4
+        #EXT-X-ENDLIST
+
+        """)
+    }
+
+    @Test("I-frame playlist TARGETDURATION equals the media playlist's")
+    func targetDurationMatchesMedia() {
+        let p = IFrameMockProvider(served: true, durations: [4.0, 9.6, 4.0])
+        let media = HLSLocalServer.buildMediaPlaylistText(provider: p)
+        let iframe = HLSLocalServer.buildIFramePlaylistText(provider: p)
+        let td: (String) -> String? = { t in
+            t.split(separator: "\n").map(String.init).first { $0.hasPrefix("#EXT-X-TARGETDURATION:") }
+        }
+        #expect(td(media) != nil)
+        #expect(td(media) == td(iframe))
+    }
+
+    @Test("absolute sub-resource base is honoured like in the media playlist")
+    func absoluteBase() {
+        let p = IFrameMockProvider(served: true, durations: [4.0])
+        let text = HLSLocalServer.buildIFramePlaylistText(
+            provider: p, subResourceBaseURL: URL(string: "aether-hls://session/")!)
+        #expect(text.contains("#EXT-X-MAP:URI=\"aether-hls://session/iframe_init.mp4\""))
+        #expect(text.contains("\naether-hls://session/iframe0.mp4\n"))
+    }
+
+    @Test("I-frame segment paths parse to their index, and nothing else does",
+          arguments: [("/iframe0.mp4", 0), ("/iframe17.mp4", 17), ("/iframe_init.mp4", nil),
+                      ("/iframe-1.mp4", nil), ("/iframeX.mp4", nil), ("/iframe.mp4", nil),
+                      ("/iframe3.m4s", nil), ("/seg3.mp4", nil)] as [(String, Int?)])
+    func parsePath(path: String, expected: Int?) {
+        #expect(HLSLocalServer.parseIFramePath(path) == expected)
+    }
+
+    @Test("video codec extraction keeps the video entry and falls back to the whole string",
+          arguments: [("hvc1.2.4.L150.B0,ec-3", "hvc1.2.4.L150.B0"), ("mp4a.40.2,avc1.640028", "avc1.640028"),
+                      ("dvh1.05.06,ec-3", "dvh1.05.06"), ("av01.0.12M.10", "av01.0.12M.10"),
+                      ("xyz1.1", "xyz1.1")])
+    func videoCodecs(codecs: String, expected: String) {
+        #expect(HLSLocalServer.videoCodecs(of: codecs) == expected)
+    }
+}

From 2ef9222a30915a8efa97e8c53b6041b6ad76c076 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 2 Oct 2026 21:02:52 +0200
Subject: [PATCH 292/359] feat(hls): build a one-keyframe fragment on the
 plan's timeline (#682)

A fresh video-only muxer per fragment, because AVKit asks for I-frames in any order and the
session muxer needs strictly increasing dts. Measured on sdr-h264.mp4: 0.46 ms per fragment.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../Video/IFrameFragmentBuilder.swift         |  60 ++++++
 .../IFrameFragmentBuilderTests.swift          | 188 ++++++++++++++++++
 2 files changed, 248 insertions(+)
 create mode 100644 Sources/AetherEngine/Video/IFrameFragmentBuilder.swift
 create mode 100644 Tests/AetherEngineTests/IFrameFragmentBuilderTests.swift

diff --git a/Sources/AetherEngine/Video/IFrameFragmentBuilder.swift b/Sources/AetherEngine/Video/IFrameFragmentBuilder.swift
new file mode 100644
index 000000000..98d95312c
--- /dev/null
+++ b/Sources/AetherEngine/Video/IFrameFragmentBuilder.swift
@@ -0,0 +1,60 @@
+// Sources/AetherEngine/Video/IFrameFragmentBuilder.swift
+import Foundation
+import AetherLibavcodec
+
+/// AE#682: wraps one keyframe into one fMP4 fragment on the main rendition's timeline.
+///
+/// A fresh muxer per fragment, deliberately: the session muxer requires strictly increasing dts,
+/// and AVKit asks for I-frames in any order (an overview across the whole title first, then
+/// wherever the finger is). The init carries no timing, so every muxer writes the same one.
+final class IFrameFragmentBuilder {
+    struct Output {
+        let initSegment: Data
+        let fragment: Data
+    }
+
+    private let video: MP4SegmentMuxer.VideoConfig
+    private let stagingDir: URL
+
+    init(video: MP4SegmentMuxer.VideoConfig, stagingDir: URL) {
+        self.video = video
+        self.stagingDir = stagingDir
+    }
+
+    func build(payload: Data, index: Int, startSeconds: Double, durationSeconds: Double) -> Output? {
+        guard !payload.isEmpty, payload.count <= Int(Int32.max),
+              video.timeBase.num > 0, video.timeBase.den > 0 else { return nil }
+        var initBytes = Data()
+        guard let muxer = try? MP4SegmentMuxer(
+            initialSegmentIndex: index, sessionDir: stagingDir, video: video, audio: nil,
+            onInitCaptured: { initBytes = $0 }) else { return nil }
+        var completed: URL?
+        defer {
+            _ = muxer.finalize()
+            if let completed { try? FileManager.default.removeItem(at: completed) }
+        }
+
+        var packet = av_packet_alloc()
+        defer { av_packet_free(&packet) }
+        guard let packet, av_new_packet(packet, Int32(payload.count)) == 0,
+              let dst = packet.pointee.data else { return nil }
+        payload.copyBytes(to: dst, count: payload.count)
+
+        let ticksPerSecond = Double(video.timeBase.den) / Double(video.timeBase.num)
+        let start = Int64((startSeconds * ticksPerSecond).rounded())
+        packet.pointee.pts = start
+        packet.pointee.dts = start
+        packet.pointee.duration = max(1, Int64((durationSeconds * ticksPerSecond).rounded()))
+        packet.pointee.flags = AV_PKT_FLAG_KEY
+        packet.pointee.stream_index = muxer.videoOutputStreamIndex
+        av_packet_rescale_ts(packet, video.timeBase, muxer.muxerVideoTimeBase)
+
+        guard muxer.writePacket(packet).rc >= 0,
+              case .completed(let path, _) = muxer.cutFragmentForNextSegment(index + 1) else { return nil }
+        completed = path
+        guard let fragment = try? Data(contentsOf: path), !fragment.isEmpty, !initBytes.isEmpty else {
+            return nil
+        }
+        return Output(initSegment: initBytes, fragment: fragment)
+    }
+}
diff --git a/Tests/AetherEngineTests/IFrameFragmentBuilderTests.swift b/Tests/AetherEngineTests/IFrameFragmentBuilderTests.swift
new file mode 100644
index 000000000..7dc62f572
--- /dev/null
+++ b/Tests/AetherEngineTests/IFrameFragmentBuilderTests.swift
@@ -0,0 +1,188 @@
+// Tests/AetherEngineTests/IFrameFragmentBuilderTests.swift
+import Foundation
+import Testing
+import AetherLibavcodec
+@testable import AetherEngine
+
+private func fixtureURL(_ name: String) -> URL {
+    URL(fileURLWithPath: #filePath)
+        .deletingLastPathComponent().deletingLastPathComponent().deletingLastPathComponent()
+        .appendingPathComponent("Fixtures/\(name)")
+}
+private func fixtureExists(_ name: String) -> Bool {
+    FileManager.default.fileExists(atPath: fixtureURL(name).path)
+}
+
+/// Just enough ISO BMFF to read a track timescale, a fragment's base decode time and its sample count.
+enum IFrameTestBoxes {
+    static func u32(_ d: Data, _ off: Int) -> UInt32 {
+        d.withUnsafeBytes { UInt32(bigEndian: $0.loadUnaligned(fromByteOffset: off, as: UInt32.self)) }
+    }
+    static func u64(_ d: Data, _ off: Int) -> UInt64 {
+        d.withUnsafeBytes { UInt64(bigEndian: $0.loadUnaligned(fromByteOffset: off, as: UInt64.self)) }
+    }
+    /// Body range of the first box of `path` nested from the top of `range`.
+    static func find(_ path: [String], in d: Data, range: Range<Int>? = nil) -> Range<Int>? {
+        var range = range ?? 0..<d.count
+        for name in path {
+            var off = range.lowerBound
+            var found: Range<Int>?
+            while off + 8 <= range.upperBound {
+                let size = Int(u32(d, off))
+                guard size >= 8, off + size <= range.upperBound else { break }
+                if String(bytes: d[(d.startIndex + off + 4)..<(d.startIndex + off + 8)], encoding: .isoLatin1) == name {
+                    found = (off + 8)..<(off + size); break
+                }
+                off += size
+            }
+            guard let f = found else { return nil }
+            range = f
+        }
+        return range
+    }
+    static func topLevelTypes(_ d: Data) -> [String] {
+        var out: [String] = []; var off = 0
+        while off + 8 <= d.count {
+            let size = Int(u32(d, off)); guard size >= 8 else { break }
+            out.append(String(bytes: d[(d.startIndex + off + 4)..<(d.startIndex + off + 8)], encoding: .isoLatin1) ?? "?")
+            off += size
+        }
+        return out
+    }
+    static func timescale(initSegment d: Data) -> UInt32? {
+        guard let mdhd = find(["moov", "trak", "mdia", "mdhd"], in: d) else { return nil }
+        let version = d[d.startIndex + mdhd.lowerBound]
+        return u32(d, mdhd.lowerBound + (version == 1 ? 20 : 12))
+    }
+    static func baseDecodeTime(fragment d: Data) -> UInt64? {
+        guard let tfdt = find(["moof", "traf", "tfdt"], in: d) else { return nil }
+        let version = d[d.startIndex + tfdt.lowerBound]
+        return version == 1 ? u64(d, tfdt.lowerBound + 4) : UInt64(u32(d, tfdt.lowerBound + 4))
+    }
+    static func sampleCount(fragment d: Data) -> UInt32? {
+        guard let trun = find(["moof", "traf", "trun"], in: d) else { return nil }
+        return u32(d, trun.lowerBound + 4)
+    }
+}
+
+/// Opens a fixture and hands back its video config plus the first keyframe's bytes.
+struct IFrameFixture {
+    let demuxer: Demuxer
+    let config: MP4SegmentMuxer.VideoConfig
+    let keyframe: Data
+
+    init(_ name: String, codecTag: String) throws {
+        let dem = Demuxer()
+        try dem.open(url: fixtureURL(name))
+        let index = dem.videoStreamIndex
+        let stream = try #require(dem.stream(at: index))
+        config = MP4SegmentMuxer.VideoConfig(
+            codecpar: UnsafePointer(stream.pointee.codecpar),
+            timeBase: stream.pointee.time_base,
+            codecTagOverride: codecTag)
+        var found: Data?
+        for _ in 0..<200 {
+            guard let pkt = try dem.readPacket() else { break }
+            var owned: UnsafeMutablePointer<AVPacket>? = pkt
+            defer { av_packet_free(&owned) }
+            if pkt.pointee.stream_index == index, (pkt.pointee.flags & AV_PKT_FLAG_KEY) != 0,
+               let bytes = pkt.pointee.data {
+                found = Data(bytes: bytes, count: Int(pkt.pointee.size)); break
+            }
+        }
+        keyframe = try #require(found)
+        demuxer = dem
+    }
+}
+
+@Suite("I-frame fragment builder", .serialized)
+struct IFrameFragmentBuilderTests {
+    private func stagingDir() throws -> URL {
+        let dir = FileManager.default.temporaryDirectory
+            .appendingPathComponent("iframe-builder-\(UUID().uuidString)", isDirectory: true)
+        try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
+        return dir
+    }
+
+    @Test("one keyframe becomes one fragment with one sample at the requested time",
+          .enabled(if: fixtureExists("sdr-h264.mp4")))
+    func oneSampleAtRequestedTime() throws {
+        let fx = try IFrameFixture("sdr-h264.mp4", codecTag: "avc1")
+        defer { fx.demuxer.close() }
+        let dir = try stagingDir()
+        defer { try? FileManager.default.removeItem(at: dir) }
+        let builder = IFrameFragmentBuilder(video: fx.config, stagingDir: dir)
+
+        let out = try #require(builder.build(payload: fx.keyframe, index: 7,
+                                             startSeconds: 28.0, durationSeconds: 4.0))
+        #expect(IFrameTestBoxes.topLevelTypes(out.initSegment) == ["ftyp", "moov"])
+        #expect(IFrameTestBoxes.topLevelTypes(out.fragment).contains("moof"))
+        #expect(IFrameTestBoxes.topLevelTypes(out.fragment).contains("mdat"))
+        #expect(IFrameTestBoxes.sampleCount(fragment: out.fragment) == 1)
+        let timescale = Double(try #require(IFrameTestBoxes.timescale(initSegment: out.initSegment)))
+        let tfdt = Double(try #require(IFrameTestBoxes.baseDecodeTime(fragment: out.fragment)))
+        #expect(abs(tfdt / timescale - 28.0) < 0.002)
+    }
+
+    @Test("the init is byte-identical across fragments built out of order",
+          .enabled(if: fixtureExists("sdr-h264.mp4")))
+    func initIsStable() throws {
+        let fx = try IFrameFixture("sdr-h264.mp4", codecTag: "avc1")
+        defer { fx.demuxer.close() }
+        let dir = try stagingDir()
+        defer { try? FileManager.default.removeItem(at: dir) }
+        let builder = IFrameFragmentBuilder(video: fx.config, stagingDir: dir)
+
+        let late = try #require(builder.build(payload: fx.keyframe, index: 40,
+                                              startSeconds: 160.0, durationSeconds: 4.0))
+        let early = try #require(builder.build(payload: fx.keyframe, index: 2,
+                                               startSeconds: 8.0, durationSeconds: 4.0))
+        #expect(late.initSegment == early.initSegment)
+        let timescale = Double(try #require(IFrameTestBoxes.timescale(initSegment: early.initSegment)))
+        let tfdt = Double(try #require(IFrameTestBoxes.baseDecodeTime(fragment: early.fragment)))
+        #expect(abs(tfdt / timescale - 8.0) < 0.002)
+    }
+
+    @Test("nothing is left behind in the staging directory",
+          .enabled(if: fixtureExists("sdr-h264.mp4")))
+    func stagingIsCleaned() throws {
+        let fx = try IFrameFixture("sdr-h264.mp4", codecTag: "avc1")
+        defer { fx.demuxer.close() }
+        let dir = try stagingDir()
+        defer { try? FileManager.default.removeItem(at: dir) }
+        let builder = IFrameFragmentBuilder(video: fx.config, stagingDir: dir)
+        _ = builder.build(payload: fx.keyframe, index: 0, startSeconds: 0, durationSeconds: 4.0)
+        #expect(try FileManager.default.contentsOfDirectory(atPath: dir.path).isEmpty)
+    }
+
+    @Test("an empty payload builds nothing", .enabled(if: fixtureExists("sdr-h264.mp4")))
+    func emptyPayload() throws {
+        let fx = try IFrameFixture("sdr-h264.mp4", codecTag: "avc1")
+        defer { fx.demuxer.close() }
+        let dir = try stagingDir()
+        defer { try? FileManager.default.removeItem(at: dir) }
+        let builder = IFrameFragmentBuilder(video: fx.config, stagingDir: dir)
+        #expect(builder.build(payload: Data(), index: 0, startSeconds: 0, durationSeconds: 4.0) == nil)
+    }
+
+    @Test("building a fragment is cheap enough to do per request",
+          .enabled(if: fixtureExists("sdr-h264.mp4")))
+    func buildCost() throws {
+        let fx = try IFrameFixture("sdr-h264.mp4", codecTag: "avc1")
+        defer { fx.demuxer.close() }
+        let dir = try stagingDir()
+        defer { try? FileManager.default.removeItem(at: dir) }
+        let builder = IFrameFragmentBuilder(video: fx.config, stagingDir: dir)
+        let clock = ContinuousClock()
+        let elapsed = clock.measure {
+            for i in 0..<50 {
+                _ = builder.build(payload: fx.keyframe, index: i,
+                                  startSeconds: Double(i) * 4, durationSeconds: 4)
+            }
+        }
+        let perFragmentMs = Double(elapsed.components.attoseconds) / 1e15 / 50
+            + Double(elapsed.components.seconds) * 1000 / 50
+        print("IFrameFragmentBuilder: \(String(format: "%.2f", perFragmentMs)) ms per fragment")
+        #expect(perFragmentMs < 25)
+    }
+}

From ae88ed6c0f0e92c21f819f5cda4bf50dc0055a1f Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 2 Oct 2026 21:04:32 +0200
Subject: [PATCH 293/359] feat(hls): a byte-capped disk cache for I-frame
 payloads (#682)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../Video/IFramePayloadCache.swift            | 78 +++++++++++++++++++
 .../IFramePayloadCacheTests.swift             | 75 ++++++++++++++++++
 2 files changed, 153 insertions(+)
 create mode 100644 Sources/AetherEngine/Video/IFramePayloadCache.swift
 create mode 100644 Tests/AetherEngineTests/IFramePayloadCacheTests.swift

diff --git a/Sources/AetherEngine/Video/IFramePayloadCache.swift b/Sources/AetherEngine/Video/IFramePayloadCache.swift
new file mode 100644
index 000000000..71a230ad7
--- /dev/null
+++ b/Sources/AetherEngine/Video/IFramePayloadCache.swift
@@ -0,0 +1,78 @@
+// Sources/AetherEngine/Video/IFramePayloadCache.swift
+import Foundation
+
+/// AE#682: keyframe payloads read for the I-frame rendition, on disk with a byte cap. It holds the
+/// raw keyframe rather than the built fragment so a neighbour can be re-stamped for an index whose
+/// own read failed.
+final class IFramePayloadCache: @unchecked Sendable {
+    private let directory: URL
+    private let byteLimit: Int
+    private let lock = NSLock()
+    private var sizes: [Int: Int] = [:]
+    private var recency: [Int] = []
+    private var totalBytes = 0
+
+    init(directory: URL, byteLimit: Int = 64 * 1024 * 1024) {
+        self.directory = directory
+        self.byteLimit = byteLimit
+    }
+
+    private func url(_ index: Int) -> URL {
+        directory.appendingPathComponent("payload-\(index).bin")
+    }
+
+    private func forgetLocked(_ index: Int) {
+        guard let size = sizes.removeValue(forKey: index) else { return }
+        totalBytes -= size
+        recency.removeAll { $0 == index }
+        try? FileManager.default.removeItem(at: url(index))
+    }
+
+    func payload(for index: Int) -> Data? {
+        lock.lock(); defer { lock.unlock() }
+        guard sizes[index] != nil else { return nil }
+        guard let data = try? Data(contentsOf: url(index)), !data.isEmpty else {
+            forgetLocked(index)
+            return nil
+        }
+        recency.removeAll { $0 == index }
+        recency.append(index)
+        return data
+    }
+
+    func store(_ data: Data, for index: Int) {
+        guard !data.isEmpty else { return }
+        lock.lock(); defer { lock.unlock() }
+        forgetLocked(index)
+        do {
+            try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)
+            try data.write(to: url(index), options: .atomic)
+        } catch {
+            return
+        }
+        sizes[index] = data.count
+        totalBytes += data.count
+        recency.append(index)
+        while totalBytes > byteLimit, let oldest = recency.first, oldest != index {
+            forgetLocked(oldest)
+        }
+    }
+
+    func nearestIndex(to index: Int) -> Int? {
+        lock.lock(); defer { lock.unlock() }
+        return sizes.keys
+            .filter { FileManager.default.fileExists(atPath: url($0).path) }
+            .min { a, b in
+                let da = abs(a - index), db = abs(b - index)
+                return da != db ? da < db : a < b
+            }
+    }
+
+    func removeAll() {
+        lock.lock(); defer { lock.unlock() }
+        sizes.removeAll()
+        recency.removeAll()
+        totalBytes = 0
+        try? FileManager.default.removeItem(at: directory)
+    }
+}
diff --git a/Tests/AetherEngineTests/IFramePayloadCacheTests.swift b/Tests/AetherEngineTests/IFramePayloadCacheTests.swift
new file mode 100644
index 000000000..06aeac336
--- /dev/null
+++ b/Tests/AetherEngineTests/IFramePayloadCacheTests.swift
@@ -0,0 +1,75 @@
+// Tests/AetherEngineTests/IFramePayloadCacheTests.swift
+import Foundation
+import Testing
+@testable import AetherEngine
+
+struct IFramePayloadCacheTests {
+    private func makeCache(limit: Int) throws -> (IFramePayloadCache, URL) {
+        let dir = FileManager.default.temporaryDirectory
+            .appendingPathComponent("iframe-cache-\(UUID().uuidString)", isDirectory: true)
+        return (IFramePayloadCache(directory: dir, byteLimit: limit), dir)
+    }
+
+    @Test("a stored payload comes back byte for byte")
+    func roundTrip() throws {
+        let (cache, dir) = try makeCache(limit: 1000)
+        defer { try? FileManager.default.removeItem(at: dir) }
+        cache.store(Data([1, 2, 3]), for: 5)
+        #expect(cache.payload(for: 5) == Data([1, 2, 3]))
+        #expect(cache.payload(for: 6) == nil)
+    }
+
+    @Test("the least recently used payload goes first once the cap is passed")
+    func evictsLeastRecentlyUsed() throws {
+        let (cache, dir) = try makeCache(limit: 250)
+        defer { try? FileManager.default.removeItem(at: dir) }
+        cache.store(Data(count: 100), for: 0)
+        cache.store(Data(count: 100), for: 1)
+        _ = cache.payload(for: 0)
+        cache.store(Data(count: 100), for: 2)
+        #expect(cache.payload(for: 1) == nil)
+        #expect(cache.payload(for: 0) != nil)
+        #expect(cache.payload(for: 2) != nil)
+    }
+
+    @Test("a payload larger than the cap is kept alone rather than evicted into a miss")
+    func oversizedPayloadIsKeptAlone() throws {
+        let (cache, dir) = try makeCache(limit: 100)
+        defer { try? FileManager.default.removeItem(at: dir) }
+        cache.store(Data(count: 60), for: 0)
+        cache.store(Data(count: 500), for: 1)
+        #expect(cache.payload(for: 1)?.count == 500)
+        #expect(cache.payload(for: 0) == nil)
+    }
+
+    @Test("nearest prefers the closest index and the lower one on a tie")
+    func nearest() throws {
+        let (cache, dir) = try makeCache(limit: 1000)
+        defer { try? FileManager.default.removeItem(at: dir) }
+        #expect(cache.nearestIndex(to: 10) == nil)
+        cache.store(Data([1]), for: 4)
+        cache.store(Data([1]), for: 20)
+        #expect(cache.nearestIndex(to: 10) == 4)
+        #expect(cache.nearestIndex(to: 13) == 20)
+        #expect(cache.nearestIndex(to: 12) == 4)
+    }
+
+    @Test("removeAll forgets everything and deletes the directory")
+    func removeAll() throws {
+        let (cache, dir) = try makeCache(limit: 1000)
+        cache.store(Data([1]), for: 0)
+        cache.removeAll()
+        #expect(cache.payload(for: 0) == nil)
+        #expect(!FileManager.default.fileExists(atPath: dir.path))
+    }
+
+    @Test("a payload whose file vanished is a miss, not a crash")
+    func missingFileIsAMiss() throws {
+        let (cache, dir) = try makeCache(limit: 1000)
+        defer { try? FileManager.default.removeItem(at: dir) }
+        cache.store(Data([1]), for: 3)
+        try FileManager.default.removeItem(at: dir)
+        #expect(cache.payload(for: 3) == nil)
+        #expect(cache.nearestIndex(to: 3) == nil)
+    }
+}

From c72646f50093fc8b602732d5f4e3826626a75a29 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 2 Oct 2026 21:06:37 +0200
Subject: [PATCH 294/359] feat(hls): a side reader fetches the keyframe that
 opens a plan segment (#682)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 Sources/AetherEngine/Demuxer/Demuxer.swift    |  13 +-
 .../AetherEngine/Video/IFrameSideReader.swift | 114 ++++++++++++++++++
 .../IFrameSideReaderTests.swift               |  94 +++++++++++++++
 3 files changed, 220 insertions(+), 1 deletion(-)
 create mode 100644 Sources/AetherEngine/Video/IFrameSideReader.swift
 create mode 100644 Tests/AetherEngineTests/IFrameSideReaderTests.swift

diff --git a/Sources/AetherEngine/Demuxer/Demuxer.swift b/Sources/AetherEngine/Demuxer/Demuxer.swift
index 327d8cc72..6466a7e35 100644
--- a/Sources/AetherEngine/Demuxer/Demuxer.swift
+++ b/Sources/AetherEngine/Demuxer/Demuxer.swift
@@ -117,6 +117,17 @@ struct DemuxerOpenProfile: Sendable {
         auditsRecordlessDolbyVision: false
     )
 
+    /// AE#682: the I-frame rendition's side reader. Reads one keyframe per request, so it takes the
+    /// still extractor's tuning under a name of its own (#240: a connection line without a name
+    /// cannot say which reader opened it).
+    static let iFrameSideDemuxer = stillExtraction.withReaderLabel("iframe")
+
+    /// Readers that fetch single keyframes and publish no timestamp axis, so the #409 repair's
+    /// sample window would be packets read for nothing.
+    static let labelsWithoutCompositionRepair: Set<String> = [
+        stillExtraction.readerLabel, iFrameSideDemuxer.readerLabel,
+    ]
+
     /// A copy of `self` with only the open-time probe budget overridden (#68).
     /// A non-nil `probesize` / `maxAnalyzeDuration` replaces the matching field;
     /// nil keeps the receiver's value. The AVIO tuning (prefetch, chunk size,
@@ -1908,7 +1919,7 @@ public final class Demuxer: @unchecked Sendable {
         // reader, #104) has no pictures to sample at all, and a non-seekable source is a live feed,
         // where holding a dozen packets for a defect that lives in a VOD sample table is latency
         // spent for nothing.
-        guard openProfile.readerLabel != DemuxerOpenProfile.stillExtraction.readerLabel,
+        guard !DemuxerOpenProfile.labelsWithoutCompositionRepair.contains(openProfile.readerLabel),
               isSourceSeekable else { return nil }
         let index = max(-1, av_find_best_stream(ctx, AVMEDIA_TYPE_VIDEO, -1, -1, nil, 0))
         guard index >= 0, index < Int32(ctx.pointee.nb_streams),
diff --git a/Sources/AetherEngine/Video/IFrameSideReader.swift b/Sources/AetherEngine/Video/IFrameSideReader.swift
new file mode 100644
index 000000000..9f0673f0c
--- /dev/null
+++ b/Sources/AetherEngine/Video/IFrameSideReader.swift
@@ -0,0 +1,114 @@
+// Sources/AetherEngine/Video/IFrameSideReader.swift
+import Foundation
+import AetherLibavcodec
+
+/// AE#682: reads the keyframe that opens a plan segment, on a demuxer of its own. Only the bytes
+/// are used; the fragment is stamped from the plan, so this demuxer's timestamp ladder (DTS on mp4,
+/// PTS on Matroska, the #409 shift) never has to agree with the session's.
+final class IFrameSideReader: @unchecked Sendable {
+    private let openDemuxer: () throws -> Demuxer
+    private let convertP7ToProfile81: Bool
+    private let nalFraming: VideoNALFraming
+    private let readDeadlineSeconds: TimeInterval
+
+    private let lock = NSLock()
+    private var demuxer: Demuxer?
+    private var videoIndex: Int32 = -1
+    private var openFailed = false
+    private var interrupted = false
+
+    /// A keyframe sits at the seek target or right behind it; this bounds a source that claims an
+    /// index entry no keyframe backs.
+    private static let maxPacketsPerRead = 256
+
+    init(openDemuxer: @escaping () throws -> Demuxer,
+         convertP7ToProfile81: Bool = false,
+         nalFraming: VideoNALFraming = .lengthPrefixed(size: 4),
+         readDeadlineSeconds: TimeInterval = 8) {
+        self.openDemuxer = openDemuxer
+        self.convertP7ToProfile81 = convertP7ToProfile81
+        self.nalFraming = nalFraming
+        self.readDeadlineSeconds = readDeadlineSeconds
+    }
+
+    private func readyDemuxer() -> Demuxer? {
+        lock.lock()
+        if interrupted || openFailed { lock.unlock(); return nil }
+        if let demuxer { lock.unlock(); return demuxer }
+        lock.unlock()
+
+        let started = DispatchTime.now()
+        let opened: Demuxer
+        do {
+            opened = try openDemuxer()
+        } catch {
+            lock.lock(); openFailed = true; lock.unlock()
+            EngineLog.emit("[IFrameSideReader] open failed: \(error)", category: .session)
+            return nil
+        }
+        let index = opened.videoStreamIndex
+        guard index >= 0 else {
+            opened.close()
+            lock.lock(); openFailed = true; lock.unlock()
+            EngineLog.emit("[IFrameSideReader] open failed: no video stream", category: .session)
+            return nil
+        }
+        opened.discardAllStreamsExcept([index])
+        lock.lock()
+        if interrupted {
+            lock.unlock()
+            opened.close()
+            return nil
+        }
+        demuxer = opened
+        videoIndex = index
+        lock.unlock()
+        let ms = Double(DispatchTime.now().uptimeNanoseconds - started.uptimeNanoseconds) / 1_000_000
+        EngineLog.emit("[IFrameSideReader] opened in \(String(format: "%.0f", ms))ms", category: .session)
+        return opened
+    }
+
+    func payload(startPts: Int64) -> Data? {
+        guard let dem = readyDemuxer() else { return nil }
+        dem.beginReadDeadline(secondsFromNow: readDeadlineSeconds)
+        defer { dem.endReadDeadline() }
+        if dem.isDiscSource || !dem.seek(to: startPts, streamIndex: videoIndex) {
+            guard let stream = dem.stream(at: videoIndex) else { return nil }
+            let tb = stream.pointee.time_base
+            guard tb.den > 0, dem.seek(to: Double(startPts) * Double(tb.num) / Double(tb.den)) else {
+                return nil
+            }
+        }
+        for _ in 0..<Self.maxPacketsPerRead {
+            lock.lock(); let stop = interrupted; lock.unlock()
+            if stop { return nil }
+            guard let packet = try? dem.readPacket() else { return nil }
+            var owned: UnsafeMutablePointer<AVPacket>? = packet
+            defer { av_packet_free(&owned) }
+            guard packet.pointee.stream_index == videoIndex,
+                  (packet.pointee.flags & AV_PKT_FLAG_KEY) != 0 else { continue }
+            if convertP7ToProfile81 {
+                _ = DoviRpuConverter.convertPacketToProfile81(packet, framing: nalFraming)
+            }
+            guard let bytes = packet.pointee.data, packet.pointee.size > 0 else { return nil }
+            return Data(bytes: bytes, count: Int(packet.pointee.size))
+        }
+        return nil
+    }
+
+    func interrupt() {
+        lock.lock()
+        interrupted = true
+        let dem = demuxer
+        lock.unlock()
+        dem?.markClosed()
+    }
+
+    func close() {
+        lock.lock()
+        let dem = demuxer
+        demuxer = nil
+        lock.unlock()
+        dem?.close()
+    }
+}
diff --git a/Tests/AetherEngineTests/IFrameSideReaderTests.swift b/Tests/AetherEngineTests/IFrameSideReaderTests.swift
new file mode 100644
index 000000000..e743cd288
--- /dev/null
+++ b/Tests/AetherEngineTests/IFrameSideReaderTests.swift
@@ -0,0 +1,94 @@
+// Tests/AetherEngineTests/IFrameSideReaderTests.swift
+import Foundation
+import Testing
+import AetherLibavcodec
+@testable import AetherEngine
+
+private func fixtureURL(_ name: String) -> URL {
+    URL(fileURLWithPath: #filePath)
+        .deletingLastPathComponent().deletingLastPathComponent().deletingLastPathComponent()
+        .appendingPathComponent("Fixtures/\(name)")
+}
+private func fixtureExists(_ name: String) -> Bool {
+    FileManager.default.fileExists(atPath: fixtureURL(name).path)
+}
+
+/// Every keyframe of the fixture's video stream as (pts-or-dts index timestamp, bytes), read
+/// linearly on an independent demuxer: the reference the side reader is checked against.
+private func referenceKeyframes(_ name: String) throws -> (index: [Int64], packets: [Int64: Data]) {
+    let dem = Demuxer()
+    try dem.open(url: fixtureURL(name))
+    defer { dem.close() }
+    let video = dem.videoStreamIndex
+    var packets: [Int64: Data] = [:]
+    while let pkt = try dem.readPacket() {
+        var owned: UnsafeMutablePointer<AVPacket>? = pkt
+        defer { av_packet_free(&owned) }
+        guard pkt.pointee.stream_index == video, (pkt.pointee.flags & AV_PKT_FLAG_KEY) != 0,
+              let bytes = pkt.pointee.data else { continue }
+        let data = Data(bytes: bytes, count: Int(pkt.pointee.size))
+        packets[pkt.pointee.dts] = data
+        packets[pkt.pointee.pts] = data
+    }
+    return (dem.indexedKeyframes(streamIndex: video).sorted(), packets)
+}
+
+@Suite("I-frame side reader", .serialized)
+struct IFrameSideReaderTests {
+    private func reader(_ name: String) -> IFrameSideReader {
+        IFrameSideReader(openDemuxer: {
+            let dem = Demuxer()
+            try dem.open(url: fixtureURL(name), profile: .iFrameSideDemuxer)
+            return dem
+        })
+    }
+
+    /// mp4 indexes its keyframes by DTS and Matroska by PTS (`PlanBoundaryAxis`), so both containers
+    /// are read: the side reader must return the segment's own keyframe on either ladder.
+    @Test("the payload at an indexed keyframe is that keyframe, in any request order",
+          arguments: ["restart-witness-av.mp4", "restart-witness-subs.mkv"])
+    func readsTheIndexedKeyframe(fixture: String) throws {
+        guard fixtureExists(fixture) else { return }
+        let ref = try referenceKeyframes(fixture)
+        try #require(ref.index.count >= 2, "\(fixture) needs at least two indexed keyframes")
+        let r = reader(fixture)
+        defer { r.interrupt(); r.close() }
+        for ts in ref.index.prefix(3).reversed() {
+            let payload = try #require(r.payload(startPts: ts))
+            #expect(payload == ref.packets[ts], "\(fixture): keyframe at \(ts) differs")
+        }
+    }
+
+    @Test("a reader that cannot open answers nil every time, without retrying the open per call")
+    func openFailureIsSticky() {
+        var opens = 0
+        let r = IFrameSideReader(openDemuxer: {
+            opens += 1
+            throw NSError(domain: "test", code: 1)
+        })
+        #expect(r.payload(startPts: 0) == nil)
+        #expect(r.payload(startPts: 100) == nil)
+        #expect(opens == 1)
+    }
+
+    @Test("after interrupt every call answers nil",
+          .enabled(if: fixtureExists("restart-witness-av.mp4")))
+    func interruptEndsIt() throws {
+        let ref = try referenceKeyframes("restart-witness-av.mp4")
+        let r = reader("restart-witness-av.mp4")
+        #expect(r.payload(startPts: ref.index[0]) != nil)
+        r.interrupt()
+        #expect(r.payload(startPts: ref.index[0]) == nil)
+        r.close()
+    }
+
+    @Test("the I-frame side profile reads like the still extractor under its own log name")
+    func profile() {
+        let p = DemuxerOpenProfile.iFrameSideDemuxer
+        #expect(p.readerLabel == "iframe")
+        #expect(p.avioPrefetch == DemuxerOpenProfile.stillExtraction.avioPrefetch)
+        #expect(p.probesize == DemuxerOpenProfile.stillExtraction.probesize)
+        #expect(DemuxerOpenProfile.labelsWithoutCompositionRepair.contains("iframe"))
+        #expect(DemuxerOpenProfile.labelsWithoutCompositionRepair.contains("extract"))
+    }
+}

From 0638cfa25dd16aa9831af7ebcdfad2108e54d596 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 2 Oct 2026 21:08:25 +0200
Subject: [PATCH 295/359] feat(hls): the I-frame rendition serves, substitutes
 and shuts down (#682)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../AetherEngine/Video/IFrameRendition.swift  | 114 +++++++++++++++
 .../IFrameRenditionTests.swift                | 132 ++++++++++++++++++
 2 files changed, 246 insertions(+)
 create mode 100644 Sources/AetherEngine/Video/IFrameRendition.swift
 create mode 100644 Tests/AetherEngineTests/IFrameRenditionTests.swift

diff --git a/Sources/AetherEngine/Video/IFrameRendition.swift b/Sources/AetherEngine/Video/IFrameRendition.swift
new file mode 100644
index 000000000..cb9a19351
--- /dev/null
+++ b/Sources/AetherEngine/Video/IFrameRendition.swift
@@ -0,0 +1,114 @@
+// Sources/AetherEngine/Video/IFrameRendition.swift
+import Foundation
+
+/// What the segment provider needs from an I-frame rendition (AE#682).
+protocol IFrameSegmentSource: AnyObject, Sendable {
+    func initSegment() -> Data?
+    func fragment(at index: Int) -> Data?
+}
+
+/// AE#682: answers `iframe_init.mp4` and `iframe{N}.mp4`. One request at a time: there is one side
+/// demuxer, and AVKit asks for up to five keyframes at once.
+final class IFrameRendition: IFrameSegmentSource, @unchecked Sendable {
+    struct Entry {
+        let startPts: Int64
+        let startSeconds: Double
+        let durationSeconds: Double
+    }
+
+    private let entries: [Entry]
+    private let cache: IFramePayloadCache
+    private let readPayload: (Entry) -> Data?
+    private let buildFragment: (Data, Int, Entry) -> IFrameFragmentBuilder.Output?
+    private let waitForLink: () -> Void
+    private let interruptReads: () -> Void
+    private let closeReader: () -> Void
+
+    private let queue = DispatchQueue(label: "aether.iframe-rendition")
+    private let stateLock = NSLock()
+    private var isShutDown = false
+    private var capturedInit: Data?
+
+    init(entries: [Entry],
+         cache: IFramePayloadCache,
+         readPayload: @escaping (Entry) -> Data?,
+         buildFragment: @escaping (Data, Int, Entry) -> IFrameFragmentBuilder.Output?,
+         waitForLink: @escaping () -> Void = {},
+         interruptReads: @escaping () -> Void = {},
+         closeReader: @escaping () -> Void = {}) {
+        self.entries = entries
+        self.cache = cache
+        self.readPayload = readPayload
+        self.buildFragment = buildFragment
+        self.waitForLink = waitForLink
+        self.interruptReads = interruptReads
+        self.closeReader = closeReader
+    }
+
+    private var shutDown: Bool {
+        stateLock.lock(); defer { stateLock.unlock() }
+        return isShutDown
+    }
+
+    func initSegment() -> Data? {
+        queue.sync {
+            guard !shutDown else { return nil }
+            if capturedInit == nil { _ = buildLocked(at: 0) }
+            return capturedInit
+        }
+    }
+
+    func fragment(at index: Int) -> Data? {
+        queue.sync {
+            guard !shutDown else { return nil }
+            return buildLocked(at: index)
+        }
+    }
+
+    private func buildLocked(at index: Int) -> Data? {
+        guard entries.indices.contains(index) else { return nil }
+        let entry = entries[index]
+        var payload = cache.payload(for: index)
+        if payload == nil {
+            waitForLink()
+            guard !shutDown else { return nil }
+            let started = DispatchTime.now()
+            if let read = readPayload(entry) {
+                cache.store(read, for: index)
+                payload = read
+                let ms = Double(DispatchTime.now().uptimeNanoseconds - started.uptimeNanoseconds) / 1_000_000
+                EngineLog.emit("[IFrameRendition] read idx=\(index) bytes=\(read.count) "
+                               + "ms=\(String(format: "%.0f", ms))", category: .session, level: .verbose)
+            } else if let neighbour = cache.nearestIndex(to: index),
+                      let substitute = cache.payload(for: neighbour) {
+                // AVKit keeps the last good picture for a keyframe it cannot fetch, and rate trick
+                // play wedges on a 404, so a near keyframe at the right time beats no answer.
+                payload = substitute
+                EngineLog.emit("[IFrameRendition] read failed idx=\(index), serving idx=\(neighbour) in its place",
+                               category: .session)
+            } else {
+                EngineLog.emit("[IFrameRendition] read failed idx=\(index) with nothing cached to stand in",
+                               category: .session)
+                return nil
+            }
+        }
+        guard let payload, let output = buildFragment(payload, index, entry) else { return nil }
+        if capturedInit == nil { capturedInit = output.initSegment }
+        return output.fragment
+    }
+
+    /// Idempotent. Aborts a read in flight, waits for the request that owns it to return, then
+    /// closes the reader and drops the cache.
+    func shutdown() {
+        stateLock.lock()
+        let already = isShutDown
+        isShutDown = true
+        stateLock.unlock()
+        guard !already else { return }
+        interruptReads()
+        queue.sync {
+            closeReader()
+            cache.removeAll()
+        }
+    }
+}
diff --git a/Tests/AetherEngineTests/IFrameRenditionTests.swift b/Tests/AetherEngineTests/IFrameRenditionTests.swift
new file mode 100644
index 000000000..829be6dbf
--- /dev/null
+++ b/Tests/AetherEngineTests/IFrameRenditionTests.swift
@@ -0,0 +1,132 @@
+// Tests/AetherEngineTests/IFrameRenditionTests.swift
+import Foundation
+import Testing
+@testable import AetherEngine
+
+private final class Recorder: @unchecked Sendable {
+    private let lock = NSLock()
+    private var _reads: [Int64] = []
+    private var _closed = 0, _interrupted = 0, _waits = 0
+    var failing: Set<Int64> = []
+    func read(_ e: IFrameRendition.Entry) -> Data? {
+        lock.lock(); defer { lock.unlock() }
+        _reads.append(e.startPts)
+        return failing.contains(e.startPts) ? nil : Data("key\(e.startPts)".utf8)
+    }
+    func noteClose() { lock.lock(); _closed += 1; lock.unlock() }
+    func noteInterrupt() { lock.lock(); _interrupted += 1; lock.unlock() }
+    func noteWait() { lock.lock(); _waits += 1; lock.unlock() }
+    var reads: [Int64] { lock.lock(); defer { lock.unlock() }; return _reads }
+    var closed: Int { lock.lock(); defer { lock.unlock() }; return _closed }
+    var interrupted: Int { lock.lock(); defer { lock.unlock() }; return _interrupted }
+    var waits: Int { lock.lock(); defer { lock.unlock() }; return _waits }
+}
+
+struct IFrameRenditionTests {
+    private func make(_ rec: Recorder, count: Int = 5) -> (IFrameRendition, URL) {
+        let dir = FileManager.default.temporaryDirectory
+            .appendingPathComponent("iframe-rendition-\(UUID().uuidString)", isDirectory: true)
+        let entries = (0..<count).map {
+            IFrameRendition.Entry(startPts: Int64($0) * 1000, startSeconds: Double($0) * 4, durationSeconds: 4)
+        }
+        let rendition = IFrameRendition(
+            entries: entries,
+            cache: IFramePayloadCache(directory: dir, byteLimit: 1 << 20),
+            readPayload: rec.read,
+            buildFragment: { payload, index, entry in
+                // The fragment names the payload it was built from and the time it was stamped with.
+                IFrameFragmentBuilder.Output(
+                    initSegment: Data("init".utf8),
+                    fragment: payload + Data("@\(index):\(entry.startSeconds)".utf8))
+            },
+            waitForLink: rec.noteWait,
+            interruptReads: rec.noteInterrupt,
+            closeReader: rec.noteClose)
+        return (rendition, dir)
+    }
+
+    @Test("a fragment is the entry's own keyframe stamped with the entry's time")
+    func ownKeyframe() {
+        let rec = Recorder()
+        let (r, dir) = make(rec); defer { r.shutdown(); try? FileManager.default.removeItem(at: dir) }
+        #expect(r.fragment(at: 2) == Data("key2000@2:8.0".utf8))
+    }
+
+    @Test("a second request for the same index reads the source once")
+    func cachesPayload() {
+        let rec = Recorder()
+        let (r, dir) = make(rec); defer { r.shutdown(); try? FileManager.default.removeItem(at: dir) }
+        _ = r.fragment(at: 3)
+        _ = r.fragment(at: 3)
+        #expect(rec.reads == [3000])
+    }
+
+    @Test("the init arrives without any fragment having been requested, by building entry 0")
+    func initBuildsFirstEntry() {
+        let rec = Recorder()
+        let (r, dir) = make(rec); defer { r.shutdown(); try? FileManager.default.removeItem(at: dir) }
+        #expect(r.initSegment() == Data("init".utf8))
+        #expect(rec.reads == [0])
+        #expect(r.initSegment() == Data("init".utf8))
+        #expect(rec.reads == [0])
+    }
+
+    @Test("a failed read is answered with the nearest cached keyframe, stamped as the asked index")
+    func substitutesNearestPayloadWhenReadFails() {
+        let rec = Recorder()
+        let (r, dir) = make(rec); defer { r.shutdown(); try? FileManager.default.removeItem(at: dir) }
+        _ = r.fragment(at: 1)
+        rec.failing = [3000]
+        #expect(r.fragment(at: 3) == Data("key1000@3:12.0".utf8))
+    }
+
+    @Test("a failed read with nothing cached is nil")
+    func nothingToSubstitute() {
+        let rec = Recorder()
+        rec.failing = [2000]
+        let (r, dir) = make(rec); defer { r.shutdown(); try? FileManager.default.removeItem(at: dir) }
+        #expect(r.fragment(at: 2) == nil)
+    }
+
+    @Test("an index outside the plan is nil and reads nothing", arguments: [-1, 5, 9999])
+    func outOfRangeIndexIsNil(index: Int) {
+        let rec = Recorder()
+        let (r, dir) = make(rec); defer { r.shutdown(); try? FileManager.default.removeItem(at: dir) }
+        #expect(r.fragment(at: index) == nil)
+        #expect(rec.reads.isEmpty)
+    }
+
+    @Test("the link wait runs before a source read and not before a cache hit")
+    func waitsOnlyBeforeReads() {
+        let rec = Recorder()
+        let (r, dir) = make(rec); defer { r.shutdown(); try? FileManager.default.removeItem(at: dir) }
+        _ = r.fragment(at: 0)
+        _ = r.fragment(at: 0)
+        #expect(rec.waits == 1)
+    }
+
+    @Test("after shutdown every call is nil, the reader is interrupted and closed exactly once")
+    func answersNilAfterShutdown() {
+        let rec = Recorder()
+        let (r, dir) = make(rec); defer { try? FileManager.default.removeItem(at: dir) }
+        _ = r.fragment(at: 0)
+        r.shutdown()
+        r.shutdown()
+        #expect(r.fragment(at: 1) == nil)
+        #expect(r.initSegment() == nil)
+        #expect(rec.reads == [0])
+        #expect(rec.interrupted == 1)
+        #expect(rec.closed == 1)
+    }
+
+    @Test("concurrent requests are served one at a time and all complete")
+    func concurrentRequests() async {
+        let rec = Recorder()
+        let (r, dir) = make(rec, count: 40); defer { r.shutdown(); try? FileManager.default.removeItem(at: dir) }
+        await withTaskGroup(of: Bool.self) { group in
+            for i in 0..<40 { group.addTask { r.fragment(at: i) != nil } }
+            for await ok in group { #expect(ok) }
+        }
+        #expect(Set(rec.reads).count == 40)
+    }
+}

From 3ff4af5e8e5ab1230d5af11318f25c4767de8f6c Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 2 Oct 2026 21:09:53 +0200
Subject: [PATCH 296/359] feat(hls): a native VOD session serves the I-frame
 rendition when asked (#682)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../AetherEngine/Video/HLSVideoEngine.swift   | 126 +++++++++++++++++-
 .../Video/VideoSegmentProvider.swift          |  19 +++
 .../IFrameSessionTests.swift                  | 120 +++++++++++++++++
 3 files changed, 263 insertions(+), 2 deletions(-)
 create mode 100644 Tests/AetherEngineTests/IFrameSessionTests.swift

diff --git a/Sources/AetherEngine/Video/HLSVideoEngine.swift b/Sources/AetherEngine/Video/HLSVideoEngine.swift
index e0ff0ea3f..ac7b066cf 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine.swift
@@ -199,6 +199,15 @@ public final class HLSVideoEngine: @unchecked Sendable {
     /// Set before `start()`.
     var enableNativeSubtitleTrackForSession: Bool = false
 
+    /// AE#682: the host asked for an I-frame rendition. Whether the session can serve one is decided
+    /// in `start()` and read back as `iFrameRenditionVerdict`.
+    var iFramePlaylistRequested = false
+    /// AE#682: an independent reader for a custom-IO source, which this session cannot reopen by URL.
+    /// Set before `start()`.
+    var customIFrameReader: (reader: IOReader, formatHint: String?)?
+    private(set) var iFrameRenditionVerdict: IFrameRenditionEligibility.Verdict = .absent(.notRequested)
+    private var iFrameRendition: IFrameRendition?
+
     /// Native subtitle rendition marked DEFAULT=YES in the master (Sodalite#32). Set before `start()`; the
     /// provider advertises this ordinal as the group default so a host-selected legible track renders.
     var nativeSubtitleDefaultOrdinal: Int = 0
@@ -336,6 +345,12 @@ public final class HLSVideoEngine: @unchecked Sendable {
         enableNativeSubtitleTrackForSession = true
     }
 
+    /// Ask for an I-frame rendition in the master (AE#682), the `LoadOptions.serveIFramePlaylist`
+    /// path a full session uses. Must precede `start()`.
+    public func requestIFramePlaylist() {
+        iFramePlaylistRequested = true
+    }
+
     /// Attach `count` fresh cue stores (one per declared text track) to the current producer (#55).
     /// Call after `start()`. `languages` and `sourceStreamIndices` are ordinal-aligned, nil-padded.
     public func attachNativeSubtitleStores(count: Int, languages: [String?] = [],
@@ -2044,6 +2059,18 @@ public final class HLSVideoEngine: @unchecked Sendable {
         // the standard sourceIsHDR && panelReadyForHDR check routes them correctly.
         // #15: a SUBTITLES rendition lives only in a master; the pure decision below forces the
         // master for routing-safe subtitled sources so PiP can show subtitles.
+        // AE#682: decided before the routing below, because an I-frame rendition is one of the
+        // reasons to serve a master at all.
+        let iFrameCandidate = IFrameRenditionEligibility.candidate(.init(
+            requested: iFramePlaylistRequested,
+            isLive: isLiveSession,
+            planBoundariesClaimRandomAccess: planBoundariesClaimRandomAccess,
+            sequentialOrigin: sequentialOrigin,
+            heldSourceConnection: openProfile.avioHeldConnection,
+            originIsSerial: sourceReopenableByURL
+                && OriginRequestBudget.shared.requiresSerialRequests(sourceURL),
+            isDiscSource: dem.isDiscSource,
+            secondReaderAvailable: sourceReopenableByURL || customIFrameReader != nil))
         let hasNativeSubs = enableNativeSubtitleTrackForSession && !nativeSubtitleCueStoresForSession.isEmpty
         // AE#187: tvOS HW HEVC needs the codec advertised in a master's CODECS attribute; a bare media
         // playlist (H.264 is fine media-direct) fails the item with tracks count=0 / -12848. Scope to
@@ -2061,7 +2088,8 @@ public final class HLSVideoEngine: @unchecked Sendable {
             builtInPanelEngagesOnDemand: Self.builtInPanelEngagesOnDemand,
             frameRateKnown: frameRate != nil,
             videoCodecNeedsMasterSignaling: videoCodecNeedsMasterSignaling,
-            hasAudioRendition: servedAudioLanguage != nil)
+            hasAudioRendition: servedAudioLanguage != nil,
+            hasIFrameRendition: iFrameCandidate == .served)
         let resolvedURL: URL? = useMasterPlaylist
             ? srv.playlistURL
             : srv.mediaPlaylistURL
@@ -2070,6 +2098,20 @@ public final class HLSVideoEngine: @unchecked Sendable {
             throw HLSVideoEngineError.openFailed(reason: "server URL not ready")
         }
         self.servingMasterPlaylist = useMasterPlaylist
+        iFrameRenditionVerdict = IFrameRenditionEligibility.resolve(
+            candidate: iFrameCandidate, servingMaster: useMasterPlaylist)
+        if iFrameRenditionVerdict == .served, let rendition = makeIFrameRendition(plan: plan, cache: segmentCache) {
+            iFrameRendition = rendition
+            prov.setIFrameSource(rendition)
+            EngineLog.emit("[HLSVideoEngine] i-frame rendition: served segments=\(plan.count)",
+                           category: .session)
+        } else if iFramePlaylistRequested {
+            if iFrameRenditionVerdict == .served { iFrameRenditionVerdict = .absent(.noSecondReader) }
+            if case .absent(let reason) = iFrameRenditionVerdict {
+                EngineLog.emit("[HLSVideoEngine] i-frame rendition: absent reason=\(reason.rawValue)",
+                               category: .session)
+            }
+        }
         self.servedSourceIsHDR = videoRange != .sdr
         self.servedDolbyVisionConversion = convertP7ToProfile81 ? .profile7ToProfile81 : nil
         EngineLog.emit("[HLSVideoEngine] serving on \(url.absoluteString) (dvModeAvailable=\(dvModeAvailable) effectiveDvMode=\(effectiveDvMode) panelIsHDR=\(panelIsInHDRMode) displaySupportsHDR=\(displaySupportsHDR) matchContent=\(matchContentEnabled) sourceIsHDR=\(videoRange != .sdr || effectiveDvMode) useMaster=\(useMasterPlaylist) videoRange=\(videoRange) dvVariant=\(dvVariant) audioLang=\(servedAudioLanguage ?? "none"))")
@@ -2194,7 +2236,11 @@ public final class HLSVideoEngine: @unchecked Sendable {
     public var hasServedMediaSegment: Bool { server?.hasServedMediaSegment ?? false }
 
     /// Flip the serving flag after the engine has reloaded the media playlist on a display rejection.
-    func markServingMediaAfterFallback() { servingMasterPlaylist = false }
+    func markServingMediaAfterFallback() {
+        servingMasterPlaylist = false
+        // AE#682: the rendition lives only in the master this session just stopped serving.
+        tearDownIFrameRendition()
+    }
 
     // MARK: - Diagnostics
 
@@ -2511,6 +2557,8 @@ public final class HLSVideoEngine: @unchecked Sendable {
         preopenedDemuxer = nil
         let prov = provider
         provider = nil
+        let iFrames = iFrameRendition
+        iFrameRendition = nil
         savedVideoConfig = nil
         savedAudioConfig = nil
         let ownedParams = ownedCodecParams
@@ -2535,6 +2583,7 @@ public final class HLSVideoEngine: @unchecked Sendable {
 
         // Wake LL-HLS blocking-reload waiters; without this they sleep out their full 18-30 s timeout.
         prov?.cancelWaiters()
+        prov?.setIFrameSource(nil)
 
         // markClosed unblocks a live pump parked in the AVIO reconnect loop (exits on closed flag,
         // not the producer cancel flag). Without this, waitForFinish blocks ~3 s while reconnects
@@ -2546,6 +2595,7 @@ public final class HLSVideoEngine: @unchecked Sendable {
         // Detached cleanup: producer waitForFinish must precede demuxer/cache/server close
         // (pump accesses them during unwind). ownedParams released last (pump read them).
         Task.detached {
+            iFrames?.shutdown()
             _ = p?.waitForFinish(timeout: 3.0)
             s?.stop()
             c?.close()
@@ -2561,6 +2611,78 @@ public final class HLSVideoEngine: @unchecked Sendable {
         stop()
     }
 
+    // MARK: - I-frame rendition (AE#682)
+
+    private func makeIFrameRendition(plan: [Segment], cache segmentCache: SegmentCache) -> IFrameRendition? {
+        guard let cfg = savedVideoConfig, !plan.isEmpty else { return nil }
+        let directory = segmentCache.sessionDir.appendingPathComponent("iframes", isDirectory: true)
+        let staging = directory.appendingPathComponent("staging", isDirectory: true)
+        do {
+            try FileManager.default.createDirectory(at: staging, withIntermediateDirectories: true)
+        } catch {
+            EngineLog.emit("[HLSVideoEngine] i-frame rendition: staging dir failed: \(error)",
+                           category: .session)
+            return nil
+        }
+        let builder = IFrameFragmentBuilder(
+            video: MP4SegmentMuxer.VideoConfig(
+                codecpar: cfg.codecpar, timeBase: cfg.timeBase,
+                codecTagOverride: cfg.codecTagOverride, doviConfig: cfg.doviConfig,
+                colorOverride: cfg.colorOverride, extradataOverride: cfg.extradataOverride,
+                nalFramingLatch: cfg.nalFramingLatch),
+            stagingDir: staging)
+        let framing = cfg.nalFramingOverride ?? A53SEIParser.nalFraming(
+            codec: cfg.codecpar.pointee.codec_id == AV_CODEC_ID_HEVC ? .hevc : .h264,
+            extradata: cfg.codecpar.pointee.extradata.map { UnsafePointer($0) },
+            size: Int(cfg.codecpar.pointee.extradata_size))
+        let url = sourceURL, headers = sourceHTTPHeaders, custom = customIFrameReader
+        let reader = IFrameSideReader(
+            openDemuxer: {
+                let dem = Demuxer()
+                if let custom {
+                    try dem.open(reader: custom.reader, formatHint: custom.formatHint,
+                                 profile: .iFrameSideDemuxer)
+                } else {
+                    try dem.open(url: url, extraHeaders: headers, profile: .iFrameSideDemuxer, isLive: false)
+                }
+                return dem
+            },
+            convertP7ToProfile81: cfg.convertP7ToProfile81,
+            nalFraming: framing)
+        let entries = plan.map {
+            IFrameRendition.Entry(startPts: $0.startPts, startSeconds: $0.startSeconds,
+                                  durationSeconds: $0.durationSeconds)
+        }
+        return IFrameRendition(
+            entries: entries,
+            cache: IFramePayloadCache(directory: directory.appendingPathComponent("payloads", isDirectory: true)),
+            readPayload: { reader.payload(startPts: $0.startPts) },
+            buildFragment: { payload, index, entry in
+                builder.build(payload: payload, index: index,
+                              startSeconds: entry.startSeconds, durationSeconds: entry.durationSeconds)
+            },
+            waitForLink: { [weak self] in
+                // A seek or a producer restart owns the link for a moment; a thumbnail can wait that
+                // out, but not ordinary fetching, or it would stall whenever the pump is busy.
+                let deadline = Date().addingTimeInterval(2)
+                while Date() < deadline, let self,
+                      self.restartInFlight || (self.sideReaderLinkGate?.state.seeking ?? false) {
+                    Thread.sleep(forTimeInterval: 0.05)
+                }
+            },
+            interruptReads: { reader.interrupt() },
+            closeReader: { reader.close() })
+    }
+
+    /// Stop answering I-frame requests. The shutdown waits for a read in flight, so it runs off the
+    /// caller's thread; the provider is cleared first, so no new request reaches the rendition.
+    private func tearDownIFrameRendition() {
+        provider?.setIFrameSource(nil)
+        guard let rendition = iFrameRendition else { return }
+        iFrameRendition = nil
+        DispatchQueue.global(qos: .utility).async { rendition.shutdown() }
+    }
+
     // MARK: - Producer construction + restart
 
     /// Allocate a new `HLSSegmentProducer` at the given segment index (initial bring-up and scrub restarts).
diff --git a/Sources/AetherEngine/Video/VideoSegmentProvider.swift b/Sources/AetherEngine/Video/VideoSegmentProvider.swift
index 7f25dc064..01456ac5b 100644
--- a/Sources/AetherEngine/Video/VideoSegmentProvider.swift
+++ b/Sources/AetherEngine/Video/VideoSegmentProvider.swift
@@ -683,6 +683,8 @@ final class VideoSegmentProvider: HLSSegmentProvider, @unchecked Sendable {
     private let cache: SegmentCache
     /// Immutable for VOD; grows under stateLock for live (producer appends via appendLiveSegment).
     private var segments: [HLSVideoEngine.Segment]
+    private let iFrameSourceLock = NSLock()
+    private var _iFrameSource: IFrameSegmentSource?
     private let isLive: Bool
     /// Sequential-origin session: playlist grows with finalized real durations (see _seqDurations).
     private let sequentialAppendPlaylist: Bool
@@ -2743,6 +2745,23 @@ final class VideoSegmentProvider: HLSSegmentProvider, @unchecked Sendable {
 
     /// AE#446: how often a blocking-reload hold re-asks whether the source is still alive.
     static let liveHoldRecheckSeconds: TimeInterval = 1.0
+    /// AE#682. Set once by the session after the routing decision, before the playback URL leaves
+    /// `start()`; cleared when the session falls back to the media playlist or stops.
+    func setIFrameSource(_ source: IFrameSegmentSource?) {
+        iFrameSourceLock.lock()
+        _iFrameSource = source
+        iFrameSourceLock.unlock()
+    }
+
+    private var iFrameSource: IFrameSegmentSource? {
+        iFrameSourceLock.lock(); defer { iFrameSourceLock.unlock() }
+        return _iFrameSource
+    }
+
+    var iFrameRenditionServed: Bool { iFrameSource != nil }
+    func iFrameInitSegment() -> Data? { iFrameSource?.initSegment() }
+    func iFrameSegment(at index: Int) -> Data? { iFrameSource?.fragment(at: index) }
+
     var masterCodecs: String? { codecsString }
     var masterSupplementalCodecs: String? { supplementalCodecsString }
     var masterResolution: (width: Int, height: Int)? {
diff --git a/Tests/AetherEngineTests/IFrameSessionTests.swift b/Tests/AetherEngineTests/IFrameSessionTests.swift
new file mode 100644
index 000000000..c91a6b833
--- /dev/null
+++ b/Tests/AetherEngineTests/IFrameSessionTests.swift
@@ -0,0 +1,120 @@
+// Tests/AetherEngineTests/IFrameSessionTests.swift
+import Foundation
+import Testing
+@testable import AetherEngine
+
+private func fixtureURL(_ name: String) -> URL {
+    URL(fileURLWithPath: #filePath)
+        .deletingLastPathComponent().deletingLastPathComponent().deletingLastPathComponent()
+        .appendingPathComponent("Fixtures/\(name)")
+}
+private func fixtureExists(_ name: String) -> Bool {
+    FileManager.default.fileExists(atPath: fixtureURL(name).path)
+}
+
+@Suite("I-frame rendition on a real session", .serialized)
+struct IFrameSessionTests {
+    private static let fixture = "restart-witness-av.mp4"
+
+    @Test("a flagged VOD session lists the rendition and serves keyframes on the plan's timeline",
+          .enabled(if: fixtureExists(fixture)), .timeLimit(.minutes(2)))
+    func servesRendition() throws {
+        let engine = HLSVideoEngine(url: fixtureURL(Self.fixture), dvModeAvailable: false)
+        engine.requestIFramePlaylist()
+        let playbackURL = try engine.start()
+        defer { engine.stop() }
+        try #require(engine.planBoundariesClaimRandomAccess, "fixture must plan on its keyframe index")
+        #expect(engine.iFrameRenditionVerdict == .served)
+        #expect(playbackURL.lastPathComponent == "master.m3u8")
+        let prov = try #require(engine.provider)
+        #expect(prov.iFrameRenditionServed)
+        try #require(prov.segmentCount >= 2)
+
+        let initSegment = try #require(prov.iFrameInitSegment())
+        let timescale = Double(try #require(IFrameTestBoxes.timescale(initSegment: initSegment)))
+        // Deliberately out of order: the last entry first.
+        for index in [prov.segmentCount - 1, 0, 1] {
+            let fragment = try #require(prov.iFrameSegment(at: index))
+            #expect(IFrameTestBoxes.sampleCount(fragment: fragment) == 1)
+            let tfdt = Double(try #require(IFrameTestBoxes.baseDecodeTime(fragment: fragment)))
+            #expect(abs(tfdt / timescale - engine.segmentPlan[index].startSeconds) < 0.002,
+                    "iframe\(index) sits at \(tfdt / timescale), plan says \(engine.segmentPlan[index].startSeconds)")
+        }
+        #expect(prov.iFrameSegment(at: prov.segmentCount) == nil)
+    }
+
+    @Test("the loopback server answers the three new paths",
+          .enabled(if: fixtureExists(fixture)), .timeLimit(.minutes(2)))
+    func routes() throws {
+        let engine = HLSVideoEngine(url: fixtureURL(Self.fixture), dvModeAvailable: false)
+        engine.requestIFramePlaylist()
+        let playbackURL = try engine.start()
+        defer { engine.stop() }
+        let base = playbackURL.deletingLastPathComponent()
+        let master = try String(contentsOf: playbackURL, encoding: .utf8)
+        #expect(master.contains("#EXT-X-I-FRAME-STREAM-INF:"))
+        #expect(master.contains("URI=\"iframe.m3u8\""))
+        let playlist = try String(contentsOf: base.appendingPathComponent("iframe.m3u8"), encoding: .utf8)
+        #expect(playlist.contains("#EXT-X-I-FRAMES-ONLY"))
+        #expect(playlist.contains("iframe1.mp4"))
+        let initSegment = try Data(contentsOf: base.appendingPathComponent("iframe_init.mp4"))
+        #expect(IFrameTestBoxes.topLevelTypes(initSegment) == ["ftyp", "moov"])
+        let fragment = try Data(contentsOf: base.appendingPathComponent("iframe1.mp4"))
+        #expect(IFrameTestBoxes.sampleCount(fragment: fragment) == 1)
+        #expect((try? Data(contentsOf: base.appendingPathComponent("iframe99999.mp4"))) == nil)
+    }
+
+    @Test("without the request the session is what it was: no tag, no route, no reader",
+          .enabled(if: fixtureExists(fixture)), .timeLimit(.minutes(2)))
+    func flagOffLeavesMasterUntouched() throws {
+        let engine = HLSVideoEngine(url: fixtureURL(Self.fixture), dvModeAvailable: false)
+        _ = try engine.start()
+        defer { engine.stop() }
+        #expect(engine.iFrameRenditionVerdict == .absent(.notRequested))
+        let prov = try #require(engine.provider)
+        #expect(!prov.iFrameRenditionServed)
+        #expect(prov.iFrameInitSegment() == nil)
+        #expect(prov.iFrameSegment(at: 0) == nil)
+        #expect(!HLSLocalServer.buildMasterPlaylistText(provider: prov).contains("I-FRAME"))
+    }
+
+    @Test("the fallback to the media playlist takes the rendition down with it",
+          .enabled(if: fixtureExists(fixture)), .timeLimit(.minutes(2)))
+    func fallbackDropsRendition() throws {
+        let engine = HLSVideoEngine(url: fixtureURL(Self.fixture), dvModeAvailable: false)
+        engine.requestIFramePlaylist()
+        _ = try engine.start()
+        defer { engine.stop() }
+        let prov = try #require(engine.provider)
+        #expect(prov.iFrameSegment(at: 0) != nil)
+        engine.markServingMediaAfterFallback()
+        #expect(!prov.iFrameRenditionServed)
+        #expect(prov.iFrameSegment(at: 0) == nil)
+    }
+
+    @Test("stopping while a keyframe request is in flight neither crashes nor hangs",
+          .enabled(if: fixtureExists(fixture)), .timeLimit(.minutes(2)))
+    func stopWithRenditionInFlightDoesNotCrash() async throws {
+        let engine = HLSVideoEngine(url: fixtureURL(Self.fixture), dvModeAvailable: false)
+        engine.requestIFramePlaylist()
+        _ = try engine.start()
+        let prov = try #require(engine.provider)
+        let count = prov.segmentCount
+        await withTaskGroup(of: Void.self) { group in
+            for round in 0..<20 {
+                group.addTask { _ = prov.iFrameSegment(at: round % count) }
+            }
+            group.addTask { engine.stop() }
+        }
+        #expect(prov.iFrameSegment(at: 0) == nil)
+    }
+
+    @Test("a live session is never a candidate, whatever else is true")
+    func liveSessionServesNoRendition() {
+        let verdict = IFrameRenditionEligibility.candidate(.init(
+            requested: true, isLive: true, planBoundariesClaimRandomAccess: true,
+            sequentialOrigin: false, heldSourceConnection: false, originIsSerial: false,
+            isDiscSource: false, secondReaderAvailable: true))
+        #expect(verdict == .absent(.live))
+    }
+}

From db5f23631a9e6cdf1107fb4886cb9bedcecb2505 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 2 Oct 2026 21:11:08 +0200
Subject: [PATCH 297/359] feat(api): LoadOptions.serveIFramePlaylist turns on
 scrub thumbnails for stock-player hosts (#682)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                           |  4 +++-
 Sources/AetherEngine/AetherEngine+Loading.swift        |  9 +++++++++
 .../AetherEngine/AetherEngine+ReloadWithOptions.swift  |  2 +-
 Sources/AetherEngine/PlayerState.swift                 |  5 +++++
 Tests/AetherEngineTests/IFrameSessionTests.swift       | 10 ++++++++++
 docs/api.md                                            |  1 +
 6 files changed, 29 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index aa46c0578..1f8932fb5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,7 +10,9 @@ the public-API contract.
 
 ## [Unreleased]
 
-_Nothing yet._
+### Added
+
+- **Scrub thumbnails in the stock player (#682).** `LoadOptions.serveIFramePlaylist` makes a native VOD session list an I-frame rendition in its master, which is the one input `AVPlayerViewController` takes thumbnails from: a host that presents the system transport bar gets them, and I-frame fast forward and rewind, without writing any UI. Each entry is the source's own keyframe at full resolution, read by a second reader and stamped on the main rendition's timeline. Off by default. The rendition is left out entirely, never half-served, where the session cannot answer every keyframe (live, MPEG-TS, single-connection origins, discs, media-playlist routing); the log names the reason.
 
 ## [7.25.3] - 2026-10-02
 
diff --git a/Sources/AetherEngine/AetherEngine+Loading.swift b/Sources/AetherEngine/AetherEngine+Loading.swift
index cb885a744..2f1d2eb2a 100644
--- a/Sources/AetherEngine/AetherEngine+Loading.swift
+++ b/Sources/AetherEngine/AetherEngine+Loading.swift
@@ -867,6 +867,15 @@ extension AetherEngine {
         // #240: the pump claims the source link through this gate while it is fetching, so the
         // subtitle side readers can stay out of its way. Set before start().
         session.sideReaderLinkGate = sideReaderLinkGate
+        // AE#682: set before start(), where the session decides whether it can serve the rendition.
+        // A custom-IO source is not reopenable by URL, so the side reader gets a clone of its own;
+        // a reader that cannot clone leaves the rendition absent.
+        if loadedOptions.serveIFramePlaylist {
+            session.requestIFramePlaylist()
+            if isCustomSource, let clone = customReader?.makeIndependentReader() {
+                session.customIFrameReader = (reader: clone, formatHint: customFormatHint)
+            }
+        }
         // #260: an observer installed before load has to reach this session's producers too.
         session.setNativeVideoFrameTimeObserver(nativeVideoFrameTimeObserver)
         // Audit Vcore-101: every hop below is dropped once this session has ended (`hop(for:)`).
diff --git a/Sources/AetherEngine/AetherEngine+ReloadWithOptions.swift b/Sources/AetherEngine/AetherEngine+ReloadWithOptions.swift
index 52cb50020..acab6c69a 100644
--- a/Sources/AetherEngine/AetherEngine+ReloadWithOptions.swift
+++ b/Sources/AetherEngine/AetherEngine+ReloadWithOptions.swift
@@ -396,7 +396,7 @@ enum SessionOptionCorrection {
         "dvrWindowSeconds",
         "liveBlockingReload", "liveJoinProfile", "liveJoinStartsImmediately",
         "clampsLiveResumeToWindow", "nativeRemoteHLS", "nativeRemoteHLSIngestFallback",
-        "preserveASSMarkup", "prepareNativeSubtitles", "eagerNativeSubtitleReaders", "confirmAtmos",
+        "preserveASSMarkup", "prepareNativeSubtitles", "eagerNativeSubtitleReaders", "serveIFramePlaylist", "confirmAtmos",
         "nativeSubtitlePreferredLanguages", "sequentialOrigin", "maxConcurrentSourceRequests", "heldSourceConnection",
         "declaredDurationSeconds", "probesize", "maxAnalyzeDuration", "preferredAudioLanguages",
         "preferredSubtitleLanguages", "externalSubtitles", "forwardBufferSegments", "autoplay",
diff --git a/Sources/AetherEngine/PlayerState.swift b/Sources/AetherEngine/PlayerState.swift
index 7bb0bdc60..228a33a95 100644
--- a/Sources/AetherEngine/PlayerState.swift
+++ b/Sources/AetherEngine/PlayerState.swift
@@ -647,6 +647,9 @@ public struct LoadOptions: Sendable, Equatable {
     /// Start the native WebVTT subtitle readers eagerly at load (instead of lazily on `setNativeSubtitleSelected`), so the `/subs_N_M.vtt` segments are already populated when AVKit fetches them under a host-independent selection (e.g. an `EXT-X-MEDIA ... DEFAULT=YES` rendition that AVKit auto-selects). Equivalent to a fully-populated static VOD subtitle file. Only meaningful with `prepareNativeSubtitles`. Default `false` (Sodalite#32 probe).
     public var eagerNativeSubtitleReaders: Bool = false
 
+    /// Serve an I-frame rendition (`EXT-X-I-FRAME-STREAM-INF`) next to the master, so a stock `AVPlayerViewController` shows its own scrub thumbnails and can scan on I-frames, with no host code (AE#682). One keyframe per served segment, at the source's full resolution. Costs a second reader on the source for the whole session, opened shortly after load because AVKit asks for the first keyframe before anyone scrubs. Silently absent, with one log line naming the reason, when the session cannot answer every listed keyframe: live, a source without a trustworthy keyframe index (MPEG-TS), `sequentialOrigin`, `heldSourceConnection`, an origin limited to one request, a disc source, a custom reader that cannot clone, or media-playlist routing. A host with its own transport bar wants `scrubThumbnail` instead. A tuning field: correctable through `reloadAtCurrentPosition(applying:)`. Default `false`.
+    public var serveIFramePlaylist: Bool = false
+
     /// Confirm E-AC-3 JOC (Dolby Atmos) on this session's audio tracks, so `audioTracks` carries an honest
     /// `TrackInfo.isAtmos` for a badge instead of the pre-decode guess. No container reliably declares JOC, so
     /// this runs the same bounded decode pass as `AetherEngine.probeDetectingAtmos` (see `AtmosDetectionOptions`
@@ -896,6 +899,7 @@ public struct LoadOptions: Sendable, Equatable {
         preserveASSMarkup: Bool = false,
         prepareNativeSubtitles: Bool = false,
         eagerNativeSubtitleReaders: Bool = false,
+        serveIFramePlaylist: Bool = false,
         confirmAtmos: Bool = false,
         nativeSubtitlePreferredLanguages: [String] = [],
         sequentialOrigin: Bool = false,
@@ -940,6 +944,7 @@ public struct LoadOptions: Sendable, Equatable {
         self.preserveASSMarkup = preserveASSMarkup
         self.prepareNativeSubtitles = prepareNativeSubtitles
         self.eagerNativeSubtitleReaders = eagerNativeSubtitleReaders
+        self.serveIFramePlaylist = serveIFramePlaylist
         self.confirmAtmos = confirmAtmos
         self.nativeSubtitlePreferredLanguages = nativeSubtitlePreferredLanguages
         self.sequentialOrigin = sequentialOrigin
diff --git a/Tests/AetherEngineTests/IFrameSessionTests.swift b/Tests/AetherEngineTests/IFrameSessionTests.swift
index c91a6b833..cb5ca6407 100644
--- a/Tests/AetherEngineTests/IFrameSessionTests.swift
+++ b/Tests/AetherEngineTests/IFrameSessionTests.swift
@@ -117,4 +117,14 @@ struct IFrameSessionTests {
             isDiscSource: false, secondReaderAvailable: true))
         #expect(verdict == .absent(.live))
     }
+
+    @Test("the load option defaults to off and is a tuning field, not a session identity")
+    func loadOptionDefault() {
+        #expect(LoadOptions().serveIFramePlaylist == false)
+        var on = LoadOptions()
+        on.serveIFramePlaylist = true
+        #expect(LoadOptions(serveIFramePlaylist: true) == on)
+        #expect(SessionOptionCorrection.refusedFields(from: LoadOptions(), to: on).isEmpty)
+        #expect(SessionOptionCorrection.knownFields.contains("serveIFramePlaylist"))
+    }
 }
diff --git a/docs/api.md b/docs/api.md
index 6027a078d..0c1748f9b 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -1076,6 +1076,7 @@ All flags default to safe values; the table is the full set. Depth for the media
 | `externalSubtitles` | empty | Sidecar files registered at load, so they rank in the language preference and can join the native renditions. |
 | `prepareNativeSubtitles` | false | Declare WebVTT renditions so subtitles survive PiP / AirPlay / external display. |
 | `eagerNativeSubtitleReaders` | false | Populate those renditions at load instead of on first selection, for playlists AVKit auto-selects. Only meaningful with `prepareNativeSubtitles`. |
+| `serveIFramePlaylist` | false | Serve an I-frame rendition next to the master, so a stock `AVPlayerViewController` shows scrub thumbnails and scans on I-frames with no host code. One keyframe per segment at full resolution; opens a second reader on the source. Absent (one log line says why) for live, sources without a keyframe index, `sequentialOrigin`, `heldSourceConnection`, single-request origins, discs and media-playlist routing. Hosts with their own transport bar use `scrubThumbnail`. |
 | `nativeSubtitlePreferredLanguages` | empty | Which rendition is marked `DEFAULT=YES`. Resolved by the same BCP-47 matching as the overlay pick, so inline and PiP / AirPlay agree (#590). Read back as `nativeSubtitleDefaultOrdinal`. Does not activate the overlay path, so it cannot double up with the native render. |
 | `preserveASSMarkup` | false | Emit raw ASS event lines instead of extracted text; pair with `TrackInfo.assHeader`. ASS / SSA codecs only, embedded and sidecar alike, so a session mixing an ASS track with a SubRip one needs no reload to cross between them (AE#587). |
 | `teletextPage` | nil | Fix the DVB teletext caption page instead of letting libzvbi auto-detect. |

From 065713544648e293797104e1802d8d9f3324c417 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 2 Oct 2026 21:15:07 +0200
Subject: [PATCH 298/359] feat(aetherctl): serve --iframes lists the I-frame
 rendition (#682)

Checked against the real engine on macOS 27 with a headless AVPlayer (video output attached):

with --iframes, 30 min 1080p HEVC MKV, 900 keyframes, 450 segments:
  canPlayFastForward=true canPlayFastReverse=true
  1x t=2.87, 8x t=35.50, -8x t=8.03, 1x again t=10.87, status readyToPlay, no error
  iframe300.mp4: one packet, flagged K, pts 1200.000 = the sum of the first 300 EXTINF
  no substituted keyframe, no 404 on a listed entry
same source without the flag: canPlayFastForward=false canPlayFastReverse=false
4K HEVC MKV with the flag: same result as the 1080p run
a source with a single IRAP: 'i-frame rendition: absent reason=planNotKeyframeAligned',
  master unchanged, iframe routes 404

Full suite: swift test exit 0, 4043 swift-testing tests passed, XCTest 0 failures.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 Sources/aetherctl/Serve.swift | 7 ++++++-
 Sources/aetherctl/main.swift  | 6 ++++--
 docs/cli.md                   | 2 ++
 3 files changed, 12 insertions(+), 3 deletions(-)

diff --git a/Sources/aetherctl/Serve.swift b/Sources/aetherctl/Serve.swift
index b6f86ec64..8ad417e68 100644
--- a/Sources/aetherctl/Serve.swift
+++ b/Sources/aetherctl/Serve.swift
@@ -6,7 +6,7 @@ import AetherEngine
 func runServe(url: URL, dvModeAvailable: Bool, forceDVWithoutDisplay: Bool = false,
               dolbyVisionHandling: DolbyVisionHandling = .automatic,
               nativeSubsIndex: Int? = nil, startPosition: Double? = nil,
-              audioDelayMs: Int = 0) -> Never {
+              audioDelayMs: Int = 0, iFrames: Bool = false) -> Never {
     EngineLog.handler = { line in
         let timestamp = ISO8601DateFormatter.string(
             from: Date(),
@@ -22,6 +22,7 @@ func runServe(url: URL, dvModeAvailable: Bool, forceDVWithoutDisplay: Bool = fal
     if let idx = nativeSubsIndex { flagSuffix += " [--native-subs \(idx)]" }
     if let pos = startPosition { flagSuffix += " [--start-position \(pos)]" }
     if audioDelayMs != 0 { flagSuffix += " [--audio-delay \(audioDelayMs)]" }
+    if iFrames { flagSuffix += " [--iframes]" }
     print(EngineLog.redacted("aetherctl serve: \(url.absoluteString)\(flagSuffix)"))
     print("")
 
@@ -43,6 +44,10 @@ func runServe(url: URL, dvModeAvailable: Bool, forceDVWithoutDisplay: Bool = fal
     if nativeSubsIndex != nil {
         engine.requestNativeSubtitleTrack()
     }
+    // AE#682: the LoadOptions.serveIFramePlaylist path. Must precede start().
+    if iFrames {
+        engine.requestIFramePlaylist()
+    }
     let playbackURL: URL
     do {
         playbackURL = try engine.start()
diff --git a/Sources/aetherctl/main.swift b/Sources/aetherctl/main.swift
index 8c75b3011..92666af33 100644
--- a/Sources/aetherctl/main.swift
+++ b/Sources/aetherctl/main.swift
@@ -67,7 +67,7 @@ func printUsage() {
 
     Usage:
       aetherctl probe [--detect-hdr10plus] [--detect-atmos] <url>
-      aetherctl serve [--no-dv] [--force-dv] [--dv-base-layer] [--start-position S] <url>
+      aetherctl serve [--no-dv] [--force-dv] [--dv-base-layer] [--start-position S] [--iframes] <url>
       aetherctl validate [--no-dv] [--force-dv] [--dv-base-layer] <url>
       aetherctl swdecode [--frames N] <url>
       aetherctl play [--seconds N] [--live] [--no-sw-escalation] [--fast-zap] [--live-start-immediately] [--dvr-window N] [--subs <codec-or-lang>]
@@ -976,6 +976,8 @@ if ["probe", "serve", "validate", "swdecode", "extract", "audio", "customio"].co
     let audioSeconds = secondsFlag ?? 10
     // --native-subs: diagnostics affordance for mov_text subtitle track (#55); serve only.
     let nativeSubsIndex = takeIntFlag("--native-subs", from: &rest)
+    // AE#682: list an I-frame rendition in the master; serve only.
+    let serveIFrames = takeFlag("--iframes", from: &rest)
     // --throttle-kbps: slow-CDN simulation; starves the producer below real-time to provoke rebuffers.
     let throttleKbps = takeIntFlag("--throttle-kbps", from: &rest)
     // --start-position: anchor the first producer at a resume position like load(startPosition:) (#99); serve only.
@@ -1004,7 +1006,7 @@ if ["probe", "serve", "validate", "swdecode", "extract", "audio", "customio"].co
         runServe(url: url, dvModeAvailable: dvModeAvailable, forceDVWithoutDisplay: forceDV,
                  dolbyVisionHandling: dvHandling,
                  nativeSubsIndex: nativeSubsIndex, startPosition: startPosition,
-                 audioDelayMs: serveAudioDelayMs)
+                 audioDelayMs: serveAudioDelayMs, iFrames: serveIFrames)
     case "validate":
         exit(runValidate(url: url, dvModeAvailable: dvModeAvailable, forceDVWithoutDisplay: forceDV,
                          dolbyVisionHandling: dvHandling))
diff --git a/docs/cli.md b/docs/cli.md
index c8fc4e157..7664439d7 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -65,6 +65,8 @@ open 'http://127.0.0.1:<port>/<token>/master.m3u8'   # macOS QuickTime
 
 `--native-subs <index>` turns on the native WebVTT subtitle renditions (the `LoadOptions.prepareNativeSubtitles` path a full session uses): the engine calls `requestNativeSubtitleTrack()` before `start()`, then `attachAllNativeSubtitleStores()` after start. Every non-bitmap text track is served as a language-tagged `EXT-X-MEDIA:TYPE=SUBTITLES` rendition (`DEFAULT=NO,AUTOSELECT=NO`) in the master playlist, backed by a per-track `subs_N.m3u8` WebVTT media playlist. (An earlier design muxed `mov_text`/tx3g traks into the fMP4; in-band timed text is not HLS-conformant and AVPlayer rejected it, so the WebVTT rendition replaced it, see [formats.md › Native subtitle renditions](formats.md#native-subtitle-renditions-webvtt-for-pip-airplay-and-external-display).) The `<index>` value is legacy and now ignored, kept only for CLI compatibility: every non-bitmap track is always declared, and actual track selection happens via the host API in a full session, not from this flag. `curl` the `master.m3u8` (or open it in QuickTime) to verify the `SUBTITLES` group + `subs_N.m3u8` endpoints enumerate every language as a legible `AVMediaSelection` group. Omit the flag to reproduce the default behavior (no renditions, output identical to before).
 
+`--iframes` lists an I-frame rendition in the master (the `LoadOptions.serveIFramePlaylist` path a full session uses, AE#682): the engine calls `requestIFramePlaylist()` before `start()`. The master then carries `#EXT-X-I-FRAME-STREAM-INF` and the server answers `iframe.m3u8`, `iframe_init.mp4` and `iframe<N>.mp4`, one keyframe per segment. The log line `[HLSVideoEngine] i-frame rendition: served segments=<n>` or `absent reason=<reason>` says which it was. `curl` the playlist and a fragment next to the printed playback URL to look at them.
+
 `--prewarm` / `--prewarm-bytes N` (AE#551, `play` only) warm the source before the load, the way a host warms the next episode, and print what was retained and how long it took. The load that follows adopts those bytes: its reads inside the warm head cost no request, and its data connection starts at the warm frontier instead of byte zero. Measure it against a REAL origin. On loopback the round trip it removes costs nothing to begin with, which is exactly the trap the #281 tail prefetch was built out of.
 
 `--throttle-kbps N` is a TEST-ONLY slow-CDN simulation: it caps source-IO delivery to N kbit/s. Set it below the stream bitrate to starve the producer below real-time and provoke AVPlayer rebuffers (for example the #92 open-GOP repro). Also available on `seektest` and `play`.

From af2b5cbb55f3fd9c5bff7c866a0f25119e88475b Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 2 Oct 2026 21:40:44 +0200
Subject: [PATCH 299/359] fix(hls): the I-frame side reader closes its clone,
 aborts a slow open and backs off a failing source (#682)

From the whole-branch review, each reproduced by a test that failed first:

- A custom source's cloned reader was never closed. The session now owns it: the side reader
  closes it, an absent rendition closes it at start(), and stop() closes one nobody took.
- interrupt() could not reach a demuxer whose open was still in flight, so a stop right after
  load waited out the network open. The demuxer is published before the open.
- A failed open latched for the whole session, and every failed read cost a full read deadline
  with requests queued behind it. A failure now drops the demuxer and leaves the source alone
  for 5 s, then 30 s, and requests fall through to a cached neighbour meanwhile.
- An origin that turned serial or started metering mid-session is no longer read for
  thumbnails; requests are answered from the cache.
- A read aborted by teardown was answered with a neighbour, and a second shutdown() returned
  while the first was still draining, which let stop() free the codec parameters under a build
  after a fallback to the media playlist.
- The two failure lines are written once per 5 s with the count they swallowed.

swift test: exit 0 three times in a row (4053 swift-testing tests, XCTest 0 failures). The
package builds for tvOS and iOS. AVPlayer probe against aetherctl serve --iframes unchanged:
canPlayFastForward/Reverse true, 8x and -8x play.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../AetherEngine/Video/HLSVideoEngine.swift   |  32 +++--
 .../AetherEngine/Video/IFrameRendition.swift  |  73 +++++++++---
 .../AetherEngine/Video/IFrameSideReader.swift | 109 ++++++++++++++----
 .../IFrameRenditionTests.swift                |  80 ++++++++++++-
 .../IFrameSessionTests.swift                  |  88 ++++++++++++++
 .../IFrameSideReaderTests.swift               |  81 +++++++++++--
 6 files changed, 402 insertions(+), 61 deletions(-)

diff --git a/Sources/AetherEngine/Video/HLSVideoEngine.swift b/Sources/AetherEngine/Video/HLSVideoEngine.swift
index ac7b066cf..1fef0d550 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine.swift
@@ -203,7 +203,8 @@ public final class HLSVideoEngine: @unchecked Sendable {
     /// in `start()` and read back as `iFrameRenditionVerdict`.
     var iFramePlaylistRequested = false
     /// AE#682: an independent reader for a custom-IO source, which this session cannot reopen by URL.
-    /// Set before `start()`.
+    /// Set before `start()`. The session owns it from then on and closes it: through the side reader
+    /// that took it, at once when the rendition stays absent, or in `stop()`.
     var customIFrameReader: (reader: IOReader, formatHint: String?)?
     private(set) var iFrameRenditionVerdict: IFrameRenditionEligibility.Verdict = .absent(.notRequested)
     private var iFrameRendition: IFrameRendition?
@@ -2106,6 +2107,7 @@ public final class HLSVideoEngine: @unchecked Sendable {
             EngineLog.emit("[HLSVideoEngine] i-frame rendition: served segments=\(plan.count)",
                            category: .session)
         } else if iFramePlaylistRequested {
+            closeUnusedCustomIFrameReader()
             if iFrameRenditionVerdict == .served { iFrameRenditionVerdict = .absent(.noSecondReader) }
             if case .absent(let reason) = iFrameRenditionVerdict {
                 EngineLog.emit("[HLSVideoEngine] i-frame rendition: absent reason=\(reason.rawValue)",
@@ -2559,6 +2561,7 @@ public final class HLSVideoEngine: @unchecked Sendable {
         provider = nil
         let iFrames = iFrameRendition
         iFrameRendition = nil
+        closeUnusedCustomIFrameReader()
         savedVideoConfig = nil
         savedAudioConfig = nil
         let ownedParams = ownedCodecParams
@@ -2636,17 +2639,18 @@ public final class HLSVideoEngine: @unchecked Sendable {
             extradata: cfg.codecpar.pointee.extradata.map { UnsafePointer($0) },
             size: Int(cfg.codecpar.pointee.extradata_size))
         let url = sourceURL, headers = sourceHTTPHeaders, custom = customIFrameReader
+        // The side reader owns the clone from here; `stop()` must not close it a second time.
+        customIFrameReader = nil
         let reader = IFrameSideReader(
-            openDemuxer: {
-                let dem = Demuxer()
+            open: { dem in
                 if let custom {
                     try dem.open(reader: custom.reader, formatHint: custom.formatHint,
                                  profile: .iFrameSideDemuxer)
                 } else {
                     try dem.open(url: url, extraHeaders: headers, profile: .iFrameSideDemuxer, isLive: false)
                 }
-                return dem
             },
+            cleanup: { custom?.reader.close() },
             convertP7ToProfile81: cfg.convertP7ToProfile81,
             nalFraming: framing)
         let entries = plan.map {
@@ -2661,28 +2665,40 @@ public final class HLSVideoEngine: @unchecked Sendable {
                 builder.build(payload: payload, index: index,
                               startSeconds: entry.startSeconds, durationSeconds: entry.durationSeconds)
             },
-            waitForLink: { [weak self] in
+            waitForLink: { [weak self] shouldStop in
                 // A seek or a producer restart owns the link for a moment; a thumbnail can wait that
                 // out, but not ordinary fetching, or it would stall whenever the pump is busy.
                 let deadline = Date().addingTimeInterval(2)
-                while Date() < deadline, let self,
+                while Date() < deadline, !shouldStop(), let self,
                       self.restartInFlight || (self.sideReaderLinkGate?.state.seeking ?? false) {
                     Thread.sleep(forTimeInterval: 0.05)
                 }
             },
+            // The budget learns its limits mid-session (a 429 halves them and arms a pacer), so the
+            // check `start()` made is repeated before every read. A custom reader has no origin.
+            sourceReadsAllowed: {
+                custom != nil || !(OriginRequestBudget.shared.requiresSerialRequests(url)
+                                   || OriginRequestBudget.shared.isPaced(url))
+            },
             interruptReads: { reader.interrupt() },
             closeReader: { reader.close() })
     }
 
     /// Stop answering I-frame requests. The shutdown waits for a read in flight, so it runs off the
-    /// caller's thread; the provider is cleared first, so no new request reaches the rendition.
+    /// caller's thread; the provider is cleared first, so no new request reaches the rendition. The
+    /// reference stays, because `stop()` has to drain the same shutdown before it frees the codec
+    /// parameters the builder reads.
     private func tearDownIFrameRendition() {
         provider?.setIFrameSource(nil)
         guard let rendition = iFrameRendition else { return }
-        iFrameRendition = nil
         DispatchQueue.global(qos: .utility).async { rendition.shutdown() }
     }
 
+    private func closeUnusedCustomIFrameReader() {
+        customIFrameReader?.reader.close()
+        customIFrameReader = nil
+    }
+
     // MARK: - Producer construction + restart
 
     /// Allocate a new `HLSSegmentProducer` at the given segment index (initial bring-up and scrub restarts).
diff --git a/Sources/AetherEngine/Video/IFrameRendition.swift b/Sources/AetherEngine/Video/IFrameRendition.swift
index cb9a19351..ab38e9819 100644
--- a/Sources/AetherEngine/Video/IFrameRendition.swift
+++ b/Sources/AetherEngine/Video/IFrameRendition.swift
@@ -20,7 +20,8 @@ final class IFrameRendition: IFrameSegmentSource, @unchecked Sendable {
     private let cache: IFramePayloadCache
     private let readPayload: (Entry) -> Data?
     private let buildFragment: (Data, Int, Entry) -> IFrameFragmentBuilder.Output?
-    private let waitForLink: () -> Void
+    private let waitForLink: (_ shouldStop: () -> Bool) -> Void
+    private let sourceReadsAllowed: () -> Bool
     private let interruptReads: () -> Void
     private let closeReader: () -> Void
 
@@ -28,12 +29,14 @@ final class IFrameRendition: IFrameSegmentSource, @unchecked Sendable {
     private let stateLock = NSLock()
     private var isShutDown = false
     private var capturedInit: Data?
+    private var failureLog = IFrameLogThrottle()
 
     init(entries: [Entry],
          cache: IFramePayloadCache,
          readPayload: @escaping (Entry) -> Data?,
          buildFragment: @escaping (Data, Int, Entry) -> IFrameFragmentBuilder.Output?,
-         waitForLink: @escaping () -> Void = {},
+         waitForLink: @escaping (_ shouldStop: () -> Bool) -> Void = { _ in },
+         sourceReadsAllowed: @escaping () -> Bool = { true },
          interruptReads: @escaping () -> Void = {},
          closeReader: @escaping () -> Void = {}) {
         self.entries = entries
@@ -41,6 +44,7 @@ final class IFrameRendition: IFrameSegmentSource, @unchecked Sendable {
         self.readPayload = readPayload
         self.buildFragment = buildFragment
         self.waitForLink = waitForLink
+        self.sourceReadsAllowed = sourceReadsAllowed
         self.interruptReads = interruptReads
         self.closeReader = closeReader
     }
@@ -70,25 +74,39 @@ final class IFrameRendition: IFrameSegmentSource, @unchecked Sendable {
         let entry = entries[index]
         var payload = cache.payload(for: index)
         if payload == nil {
-            waitForLink()
-            guard !shutDown else { return nil }
-            let started = DispatchTime.now()
-            if let read = readPayload(entry) {
+            // An origin that went serial or started metering mid-session has one slot and a few
+            // tokens, and the pump needs them; AVKit's overview burst would take them all.
+            var read: Data?
+            if sourceReadsAllowed() {
+                waitForLink { self.shutDown }
+                guard !shutDown else { return nil }
+                let started = DispatchTime.now()
+                read = readPayload(entry)
+                // A read that teardown aborted is not a miss to paper over.
+                guard !shutDown else { return nil }
+                if let read {
+                    let ms = Double(DispatchTime.now().uptimeNanoseconds - started.uptimeNanoseconds) / 1_000_000
+                    EngineLog.emit("[IFrameRendition] read idx=\(index) bytes=\(read.count) "
+                                   + "ms=\(String(format: "%.0f", ms))", category: .session, level: .verbose)
+                }
+            }
+            if let read {
                 cache.store(read, for: index)
                 payload = read
-                let ms = Double(DispatchTime.now().uptimeNanoseconds - started.uptimeNanoseconds) / 1_000_000
-                EngineLog.emit("[IFrameRendition] read idx=\(index) bytes=\(read.count) "
-                               + "ms=\(String(format: "%.0f", ms))", category: .session, level: .verbose)
             } else if let neighbour = cache.nearestIndex(to: index),
                       let substitute = cache.payload(for: neighbour) {
                 // AVKit keeps the last good picture for a keyframe it cannot fetch, and rate trick
                 // play wedges on a 404, so a near keyframe at the right time beats no answer.
                 payload = substitute
-                EngineLog.emit("[IFrameRendition] read failed idx=\(index), serving idx=\(neighbour) in its place",
-                               category: .session)
+                if let suppressed = failureLog.shouldEmit(now: Date()) {
+                    EngineLog.emit("[IFrameRendition] no keyframe for idx=\(index), serving idx=\(neighbour) "
+                                   + "in its place (\(suppressed) more since the last line)", category: .session)
+                }
             } else {
-                EngineLog.emit("[IFrameRendition] read failed idx=\(index) with nothing cached to stand in",
-                               category: .session)
+                if let suppressed = failureLog.shouldEmit(now: Date()) {
+                    EngineLog.emit("[IFrameRendition] no keyframe for idx=\(index) and nothing cached to stand in "
+                                   + "(\(suppressed) more since the last line)", category: .session)
+                }
                 return nil
             }
         }
@@ -97,18 +115,37 @@ final class IFrameRendition: IFrameSegmentSource, @unchecked Sendable {
         return output.fragment
     }
 
-    /// Idempotent. Aborts a read in flight, waits for the request that owns it to return, then
-    /// closes the reader and drops the cache.
+    /// Idempotent, and every call drains: the session frees the codec parameters the builder reads
+    /// as soon as its own call returns, so a second caller must not come back while the first is
+    /// still waiting for a request to finish.
     func shutdown() {
         stateLock.lock()
-        let already = isShutDown
+        let first = !isShutDown
         isShutDown = true
         stateLock.unlock()
-        guard !already else { return }
-        interruptReads()
+        if first { interruptReads() }
         queue.sync {
+            guard first else { return }
             closeReader()
             cache.removeAll()
         }
     }
 }
+
+/// One line per window for a failure that repeats on every request (AVKit retries a missing
+/// keyframe several times a second), with the count of the ones it swallowed.
+struct IFrameLogThrottle {
+    var windowSeconds: TimeInterval = 5
+    private var lastEmit = Date.distantPast
+    private var suppressed = 0
+
+    /// The number of lines swallowed since the last one, when this one should be written.
+    mutating func shouldEmit(now: Date) -> Int? {
+        guard now.timeIntervalSince(lastEmit) >= windowSeconds else {
+            suppressed += 1
+            return nil
+        }
+        defer { suppressed = 0; lastEmit = now }
+        return suppressed
+    }
+}
diff --git a/Sources/AetherEngine/Video/IFrameSideReader.swift b/Sources/AetherEngine/Video/IFrameSideReader.swift
index 9f0673f0c..8e1bf2838 100644
--- a/Sources/AetherEngine/Video/IFrameSideReader.swift
+++ b/Sources/AetherEngine/Video/IFrameSideReader.swift
@@ -6,70 +6,132 @@ import AetherLibavcodec
 /// are used; the fragment is stamped from the plan, so this demuxer's timestamp ladder (DTS on mp4,
 /// PTS on Matroska, the #409 shift) never has to agree with the session's.
 final class IFrameSideReader: @unchecked Sendable {
-    private let openDemuxer: () throws -> Demuxer
+    private let open: (Demuxer) throws -> Void
+    private let cleanup: () -> Void
     private let convertP7ToProfile81: Bool
     private let nalFraming: VideoNALFraming
     private let readDeadlineSeconds: TimeInterval
+    private let now: () -> Date
 
     private let lock = NSLock()
     private var demuxer: Demuxer?
+    private var isOpen = false
     private var videoIndex: Int32 = -1
-    private var openFailed = false
     private var interrupted = false
+    private var cleanedUp = false
+    private var consecutiveFailures = 0
+    private var blockedUntil = Date.distantPast
 
     /// A keyframe sits at the seek target or right behind it; this bounds a source that claims an
     /// index entry no keyframe backs.
     private static let maxPacketsPerRead = 256
 
-    init(openDemuxer: @escaping () throws -> Demuxer,
+    /// How long the reader refuses to touch the source after a failed open or read. Requests are
+    /// served one at a time and AVKit sends five at once, so without this a stalled connection
+    /// answers them a full read deadline apart; with it they fall through to a cached neighbour.
+    static func coolDownSeconds(afterConsecutiveFailures failures: Int) -> TimeInterval {
+        failures <= 1 ? 5 : 30
+    }
+
+    /// `open` receives a demuxer that `interrupt()` can already reach, so a slow open is abortable.
+    /// `cleanup` runs once, from `close()`, whether or not the demuxer was ever opened.
+    init(open: @escaping (Demuxer) throws -> Void,
+         cleanup: @escaping () -> Void = {},
          convertP7ToProfile81: Bool = false,
          nalFraming: VideoNALFraming = .lengthPrefixed(size: 4),
-         readDeadlineSeconds: TimeInterval = 8) {
-        self.openDemuxer = openDemuxer
+         readDeadlineSeconds: TimeInterval = 8,
+         now: @escaping () -> Date = Date.init) {
+        self.open = open
+        self.cleanup = cleanup
         self.convertP7ToProfile81 = convertP7ToProfile81
         self.nalFraming = nalFraming
         self.readDeadlineSeconds = readDeadlineSeconds
+        self.now = now
+    }
+
+    private var isInterrupted: Bool {
+        lock.lock(); defer { lock.unlock() }
+        return interrupted
+    }
+
+    private func drop(_ dem: Demuxer) {
+        lock.lock()
+        if demuxer === dem {
+            demuxer = nil
+            isOpen = false
+        }
+        lock.unlock()
+        dem.markClosed()
+        dem.close()
+    }
+
+    private func noteFailure(_ what: String) {
+        lock.lock()
+        guard !interrupted else { lock.unlock(); return }
+        consecutiveFailures += 1
+        let coolDown = Self.coolDownSeconds(afterConsecutiveFailures: consecutiveFailures)
+        blockedUntil = now().addingTimeInterval(coolDown)
+        let failures = consecutiveFailures
+        lock.unlock()
+        EngineLog.emit("[IFrameSideReader] \(what); leaving the source alone for "
+                       + "\(Int(coolDown))s (consecutive failures: \(failures))", category: .session)
     }
 
     private func readyDemuxer() -> Demuxer? {
         lock.lock()
-        if interrupted || openFailed { lock.unlock(); return nil }
-        if let demuxer { lock.unlock(); return demuxer }
+        if interrupted { lock.unlock(); return nil }
+        if let demuxer, isOpen { lock.unlock(); return demuxer }
+        let dem = Demuxer()
+        demuxer = dem
         lock.unlock()
 
         let started = DispatchTime.now()
-        let opened: Demuxer
         do {
-            opened = try openDemuxer()
+            try open(dem)
         } catch {
-            lock.lock(); openFailed = true; lock.unlock()
-            EngineLog.emit("[IFrameSideReader] open failed: \(error)", category: .session)
+            drop(dem)
+            noteFailure("open failed: \(error)")
             return nil
         }
-        let index = opened.videoStreamIndex
+        let index = dem.videoStreamIndex
         guard index >= 0 else {
-            opened.close()
-            lock.lock(); openFailed = true; lock.unlock()
-            EngineLog.emit("[IFrameSideReader] open failed: no video stream", category: .session)
+            drop(dem)
+            noteFailure("open failed: no video stream")
             return nil
         }
-        opened.discardAllStreamsExcept([index])
+        dem.discardAllStreamsExcept([index])
         lock.lock()
         if interrupted {
             lock.unlock()
-            opened.close()
+            drop(dem)
             return nil
         }
-        demuxer = opened
+        isOpen = true
         videoIndex = index
         lock.unlock()
         let ms = Double(DispatchTime.now().uptimeNanoseconds - started.uptimeNanoseconds) / 1_000_000
         EngineLog.emit("[IFrameSideReader] opened in \(String(format: "%.0f", ms))ms", category: .session)
-        return opened
+        return dem
     }
 
     func payload(startPts: Int64) -> Data? {
+        lock.lock()
+        let held = interrupted || now() < blockedUntil
+        lock.unlock()
+        if held { return nil }
         guard let dem = readyDemuxer() else { return nil }
+        if let data = read(dem, startPts: startPts) {
+            lock.lock(); consecutiveFailures = 0; lock.unlock()
+            return data
+        }
+        guard !isInterrupted else { return nil }
+        // The session treats a demuxer whose read failed as suspect-dead and reopens; so does this.
+        drop(dem)
+        noteFailure("read failed at pts=\(startPts)")
+        return nil
+    }
+
+    private func read(_ dem: Demuxer, startPts: Int64) -> Data? {
         dem.beginReadDeadline(secondsFromNow: readDeadlineSeconds)
         defer { dem.endReadDeadline() }
         if dem.isDiscSource || !dem.seek(to: startPts, streamIndex: videoIndex) {
@@ -80,8 +142,7 @@ final class IFrameSideReader: @unchecked Sendable {
             }
         }
         for _ in 0..<Self.maxPacketsPerRead {
-            lock.lock(); let stop = interrupted; lock.unlock()
-            if stop { return nil }
+            if isInterrupted { return nil }
             guard let packet = try? dem.readPacket() else { return nil }
             var owned: UnsafeMutablePointer<AVPacket>? = packet
             defer { av_packet_free(&owned) }
@@ -96,6 +157,7 @@ final class IFrameSideReader: @unchecked Sendable {
         return nil
     }
 
+    /// Any thread. Aborts an open or a read in flight and makes every later call answer nil.
     func interrupt() {
         lock.lock()
         interrupted = true
@@ -104,11 +166,16 @@ final class IFrameSideReader: @unchecked Sendable {
         dem?.markClosed()
     }
 
+    /// The reading thread, after `interrupt()`.
     func close() {
         lock.lock()
         let dem = demuxer
         demuxer = nil
+        isOpen = false
+        let runCleanup = !cleanedUp
+        cleanedUp = true
         lock.unlock()
         dem?.close()
+        if runCleanup { cleanup() }
     }
 }
diff --git a/Tests/AetherEngineTests/IFrameRenditionTests.swift b/Tests/AetherEngineTests/IFrameRenditionTests.swift
index 829be6dbf..f9a7559a5 100644
--- a/Tests/AetherEngineTests/IFrameRenditionTests.swift
+++ b/Tests/AetherEngineTests/IFrameRenditionTests.swift
@@ -8,13 +8,18 @@ private final class Recorder: @unchecked Sendable {
     private var _reads: [Int64] = []
     private var _closed = 0, _interrupted = 0, _waits = 0
     var failing: Set<Int64> = []
+    var readsAllowed = true
+    /// Runs inside a read, before it answers. Lets a test park a read or stop the rendition under it.
+    var duringRead: (@Sendable (IFrameRendition.Entry) -> Void)?
     func read(_ e: IFrameRendition.Entry) -> Data? {
-        lock.lock(); defer { lock.unlock() }
-        _reads.append(e.startPts)
+        lock.lock(); _reads.append(e.startPts); lock.unlock()
+        duringRead?(e)
         return failing.contains(e.startPts) ? nil : Data("key\(e.startPts)".utf8)
     }
     func noteClose() { lock.lock(); _closed += 1; lock.unlock() }
-    func noteInterrupt() { lock.lock(); _interrupted += 1; lock.unlock() }
+    /// Signalled when shutdown has set its flag and is asking the reader to abort.
+    let interruptSeen = DispatchSemaphore(value: 0)
+    func noteInterrupt() { lock.lock(); _interrupted += 1; lock.unlock(); interruptSeen.signal() }
     func noteWait() { lock.lock(); _waits += 1; lock.unlock() }
     var reads: [Int64] { lock.lock(); defer { lock.unlock() }; return _reads }
     var closed: Int { lock.lock(); defer { lock.unlock() }; return _closed }
@@ -39,7 +44,8 @@ struct IFrameRenditionTests {
                     initSegment: Data("init".utf8),
                     fragment: payload + Data("@\(index):\(entry.startSeconds)".utf8))
             },
-            waitForLink: rec.noteWait,
+            waitForLink: { _ in rec.noteWait() },
+            sourceReadsAllowed: { rec.readsAllowed },
             interruptReads: rec.noteInterrupt,
             closeReader: rec.noteClose)
         return (rendition, dir)
@@ -129,4 +135,70 @@ struct IFrameRenditionTests {
         }
         #expect(Set(rec.reads).count == 40)
     }
+
+    @Test("a read that teardown interrupted is not answered with a neighbour")
+    func noSubstitutionAfterAnInterruptedRead() {
+        let rec = Recorder()
+        let (r, dir) = make(rec); defer { try? FileManager.default.removeItem(at: dir) }
+        _ = r.fragment(at: 1)
+        rec.failing = [3000]
+        let stopped = DispatchSemaphore(value: 0)
+        rec.duringRead = { entry in
+            guard entry.startPts == 3000 else { return }
+            // Teardown arrives while this read is in flight; the read then fails, as an aborted one does.
+            // Its own thread and a signal instead of a sleep: a loaded runner starves the global pool.
+            Thread.detachNewThread { r.shutdown(); stopped.signal() }
+            rec.interruptSeen.wait()
+        }
+        #expect(r.fragment(at: 3) == nil)
+        stopped.wait()
+    }
+
+    @Test("a second shutdown waits for the request the first one is still draining")
+    func aSecondShutdownWaitsForTheRequestInFlight() {
+        let rec = Recorder()
+        let (r, dir) = make(rec); defer { try? FileManager.default.removeItem(at: dir) }
+        let parked = DispatchSemaphore(value: 0), release = DispatchSemaphore(value: 0)
+        rec.duringRead = { _ in parked.signal(); release.wait() }
+        let requestDone = DispatchSemaphore(value: 0), firstDone = DispatchSemaphore(value: 0)
+        let secondDone = DispatchSemaphore(value: 0)
+        Thread.detachNewThread { _ = r.fragment(at: 0); requestDone.signal() }
+        parked.wait()
+        Thread.detachNewThread { r.shutdown(); firstDone.signal() }
+        Thread.sleep(forTimeInterval: 0.1)
+        Thread.detachNewThread { r.shutdown(); secondDone.signal() }
+        // The session frees the codec parameters right after its own shutdown() returns, so that
+        // call must not come back while a build can still be running.
+        #expect(secondDone.wait(timeout: .now() + 0.4) == .timedOut)
+        release.signal()
+        requestDone.wait(); firstDone.wait()
+        #expect(secondDone.wait(timeout: .now() + 10) == .success)
+    }
+
+    @Test("while source reads are held, a request is answered from the cache or not at all")
+    func servesFromCacheOnlyWhileSourceReadsAreHeld() {
+        let rec = Recorder()
+        let (r, dir) = make(rec); defer { r.shutdown(); try? FileManager.default.removeItem(at: dir) }
+        rec.readsAllowed = false
+        #expect(r.fragment(at: 2) == nil)
+        #expect(rec.reads.isEmpty)
+        rec.readsAllowed = true
+        _ = r.fragment(at: 1)
+        rec.readsAllowed = false
+        #expect(r.fragment(at: 1) == Data("key1000@1:4.0".utf8))
+        #expect(r.fragment(at: 3) == Data("key1000@3:12.0".utf8))
+        #expect(rec.reads == [1000])
+    }
+
+    @Test("the failure line is written once per window and counts what it swallowed")
+    func logThrottle() {
+        var throttle = IFrameLogThrottle()
+        let t0 = Date(timeIntervalSince1970: 1_000)
+        #expect(throttle.shouldEmit(now: t0) == 0)
+        #expect(throttle.shouldEmit(now: t0.addingTimeInterval(1)) == nil)
+        #expect(throttle.shouldEmit(now: t0.addingTimeInterval(4.9)) == nil)
+        #expect(throttle.shouldEmit(now: t0.addingTimeInterval(5)) == 2)
+        #expect(throttle.shouldEmit(now: t0.addingTimeInterval(6)) == nil)
+        #expect(throttle.shouldEmit(now: t0.addingTimeInterval(11)) == 1)
+    }
 }
diff --git a/Tests/AetherEngineTests/IFrameSessionTests.swift b/Tests/AetherEngineTests/IFrameSessionTests.swift
index cb5ca6407..d8cbb0c83 100644
--- a/Tests/AetherEngineTests/IFrameSessionTests.swift
+++ b/Tests/AetherEngineTests/IFrameSessionTests.swift
@@ -12,6 +12,50 @@ private func fixtureExists(_ name: String) -> Bool {
     FileManager.default.fileExists(atPath: fixtureURL(name).path)
 }
 
+/// A file-backed custom reader that counts its closes: the stand-in for a host's clone.
+private final class CountingFileReader: IOReader, @unchecked Sendable {
+    let discImageProbeEnabled = false
+    private let lock = NSLock()
+    private let handle: FileHandle
+    private let size: Int64
+    private var offset: Int64 = 0
+    private var _closes = 0
+    init(url: URL) throws {
+        handle = try FileHandle(forReadingFrom: url)
+        size = Int64((try FileManager.default.attributesOfItem(atPath: url.path)[.size] as? NSNumber)?.int64Value ?? 0)
+    }
+    var closes: Int { lock.withLock { _closes } }
+    func read(_ buffer: UnsafeMutablePointer<UInt8>?, size count: Int32) -> Int32 {
+        lock.withLock {
+            guard let buffer, count > 0, offset < size else { return 0 }
+            try? handle.seek(toOffset: UInt64(offset))
+            let data = handle.readData(ofLength: Int(min(Int64(count), size - offset)))
+            data.copyBytes(to: buffer, count: data.count)
+            offset += Int64(data.count)
+            return Int32(data.count)
+        }
+    }
+    func seek(offset requested: Int64, whence: Int32) -> Int64 {
+        lock.withLock {
+            if whence & 0x10000 != 0 { return size }
+            switch whence & ~0x20000 {
+            case SEEK_SET: offset = requested
+            case SEEK_CUR: offset += requested
+            case SEEK_END: offset = size + requested
+            default: return -1
+            }
+            return offset
+        }
+    }
+    func close() { lock.withLock { _closes += 1 } }
+}
+
+private func waitUntil(_ timeout: TimeInterval = 5, _ condition: () -> Bool) -> Bool {
+    let deadline = Date().addingTimeInterval(timeout)
+    while Date() < deadline { if condition() { return true }; Thread.sleep(forTimeInterval: 0.02) }
+    return condition()
+}
+
 @Suite("I-frame rendition on a real session", .serialized)
 struct IFrameSessionTests {
     private static let fixture = "restart-witness-av.mp4"
@@ -127,4 +171,48 @@ struct IFrameSessionTests {
         #expect(SessionOptionCorrection.refusedFields(from: LoadOptions(), to: on).isEmpty)
         #expect(SessionOptionCorrection.knownFields.contains("serveIFramePlaylist"))
     }
+
+    @Test("a custom source's clone feeds the side reader and is closed exactly once at stop",
+          .enabled(if: fixtureExists(fixture)), .timeLimit(.minutes(2)))
+    func customCloneIsClosedAtStop() throws {
+        let clone = try CountingFileReader(url: fixtureURL(Self.fixture))
+        let engine = HLSVideoEngine(url: fixtureURL(Self.fixture), dvModeAvailable: false)
+        engine.requestIFramePlaylist()
+        engine.customIFrameReader = (reader: clone, formatHint: "mp4")
+        _ = try engine.start()
+        let prov = try #require(engine.provider)
+        let fragment = try #require(prov.iFrameSegment(at: 1))
+        #expect(IFrameTestBoxes.sampleCount(fragment: fragment) == 1)
+        #expect(clone.closes == 0)
+        engine.stop()
+        #expect(waitUntil { clone.closes == 1 })
+        Thread.sleep(forTimeInterval: 0.2)
+        #expect(clone.closes == 1)
+    }
+
+    @Test("a clone nobody ever read from is still closed at stop",
+          .enabled(if: fixtureExists(fixture)), .timeLimit(.minutes(2)))
+    func untouchedCloneIsClosedAtStop() throws {
+        let clone = try CountingFileReader(url: fixtureURL(Self.fixture))
+        let engine = HLSVideoEngine(url: fixtureURL(Self.fixture), dvModeAvailable: false)
+        engine.requestIFramePlaylist()
+        engine.customIFrameReader = (reader: clone, formatHint: "mp4")
+        _ = try engine.start()
+        engine.stop()
+        #expect(waitUntil { clone.closes == 1 })
+    }
+
+    @Test("a clone handed to a session that cannot serve the rendition is closed at once",
+          .enabled(if: fixtureExists("sdr-h264.mp4")), .timeLimit(.minutes(2)))
+    func cloneOfAnAbsentRenditionIsClosed() throws {
+        // One IRAP in the whole file: no keyframe-aligned plan, so the rendition stays absent.
+        let clone = try CountingFileReader(url: fixtureURL("sdr-h264.mp4"))
+        let engine = HLSVideoEngine(url: fixtureURL("sdr-h264.mp4"), dvModeAvailable: false)
+        engine.requestIFramePlaylist()
+        engine.customIFrameReader = (reader: clone, formatHint: "mp4")
+        _ = try engine.start()
+        defer { engine.stop() }
+        #expect(engine.iFrameRenditionVerdict == .absent(.planNotKeyframeAligned))
+        #expect(clone.closes == 1)
+    }
 }
diff --git a/Tests/AetherEngineTests/IFrameSideReaderTests.swift b/Tests/AetherEngineTests/IFrameSideReaderTests.swift
index e743cd288..5df349ad0 100644
--- a/Tests/AetherEngineTests/IFrameSideReaderTests.swift
+++ b/Tests/AetherEngineTests/IFrameSideReaderTests.swift
@@ -36,10 +36,8 @@ private func referenceKeyframes(_ name: String) throws -> (index: [Int64], packe
 @Suite("I-frame side reader", .serialized)
 struct IFrameSideReaderTests {
     private func reader(_ name: String) -> IFrameSideReader {
-        IFrameSideReader(openDemuxer: {
-            let dem = Demuxer()
+        IFrameSideReader(open: { dem in
             try dem.open(url: fixtureURL(name), profile: .iFrameSideDemuxer)
-            return dem
         })
     }
 
@@ -59,16 +57,57 @@ struct IFrameSideReaderTests {
         }
     }
 
-    @Test("a reader that cannot open answers nil every time, without retrying the open per call")
-    func openFailureIsSticky() {
-        var opens = 0
-        let r = IFrameSideReader(openDemuxer: {
-            opens += 1
+    @Test("a failed open is retried only after its cool-down, which grows with the second failure")
+    func failedOpenIsRetriedAfterItsCoolDown() {
+        final class Clock: @unchecked Sendable { var now = Date(timeIntervalSince1970: 1_000); var opens = 0 }
+        let clock = Clock()
+        let r = IFrameSideReader(open: { _ in
+            clock.opens += 1
             throw NSError(domain: "test", code: 1)
-        })
+        }, now: { clock.now })
+        defer { r.interrupt(); r.close() }
         #expect(r.payload(startPts: 0) == nil)
         #expect(r.payload(startPts: 100) == nil)
-        #expect(opens == 1)
+        #expect(clock.opens == 1, "five parallel requests must not each pay for an open")
+        clock.now += 6
+        #expect(r.payload(startPts: 0) == nil)
+        #expect(clock.opens == 2)
+        clock.now += 6
+        #expect(r.payload(startPts: 0) == nil)
+        #expect(clock.opens == 2, "the second failure in a row holds for 30 s")
+        clock.now += 30
+        #expect(r.payload(startPts: 0) == nil)
+        #expect(clock.opens == 3)
+    }
+
+    @Test("a failed read cools down, then reopens a fresh demuxer and recovers",
+          .enabled(if: fixtureExists("restart-witness-av.mp4")))
+    func failedReadReopens() throws {
+        final class Clock: @unchecked Sendable { var now = Date(timeIntervalSince1970: 1_000); var opens = 0 }
+        let clock = Clock()
+        let ref = try referenceKeyframes("restart-witness-av.mp4")
+        let r = IFrameSideReader(open: { dem in
+            clock.opens += 1
+            try dem.open(url: fixtureURL("restart-witness-av.mp4"), profile: .iFrameSideDemuxer)
+        }, now: { clock.now })
+        defer { r.interrupt(); r.close() }
+        #expect(r.payload(startPts: ref.index[0]) != nil)
+        // Far past the end: no keyframe to land on, which is what a dead connection looks like here.
+        #expect(r.payload(startPts: Int64.max / 4) == nil)
+        #expect(r.payload(startPts: ref.index[0]) == nil, "inside the cool-down the source is left alone")
+        #expect(clock.opens == 1)
+        clock.now += 6
+        #expect(r.payload(startPts: ref.index[0]) == ref.packets[ref.index[0]])
+        #expect(clock.opens == 2)
+    }
+
+    @Test("cleanup runs exactly once on close, opened or not")
+    func cleanupRunsOnce() {
+        final class Count: @unchecked Sendable { var n = 0 }
+        let untouched = Count()
+        let never = IFrameSideReader(open: { _ in }, cleanup: { untouched.n += 1 })
+        never.interrupt(); never.close(); never.close()
+        #expect(untouched.n == 1)
     }
 
     @Test("after interrupt every call answers nil",
@@ -91,4 +130,26 @@ struct IFrameSideReaderTests {
         #expect(DemuxerOpenProfile.labelsWithoutCompositionRepair.contains("iframe"))
         #expect(DemuxerOpenProfile.labelsWithoutCompositionRepair.contains("extract"))
     }
+
+    @Test("interrupt aborts an open that is still in flight", .timeLimit(.minutes(1)))
+    func interruptAbortsAnOpenInFlight() {
+        let parked = ProbeParkedReader(operation: .read)
+        parked.mayReturn.open()
+        let entered = DispatchSemaphore(value: 0)
+        let r = IFrameSideReader(open: { dem in
+            entered.signal()
+            try dem.open(reader: parked, formatHint: "mp4", profile: .iFrameSideDemuxer)
+        })
+        let done = DispatchSemaphore(value: 0)
+        // A thread of its own: a loaded runner starves the global pool for seconds.
+        Thread.detachNewThread { _ = r.payload(startPts: 0); done.signal() }
+        entered.wait()
+        Thread.sleep(forTimeInterval: 0.2)
+        r.interrupt()
+        let returned = done.wait(timeout: .now() + 10) == .success
+        #expect(returned, "payload() was still inside the open ten seconds after interrupt()")
+        parked.release()
+        if !returned { done.wait() }
+        r.close()
+    }
 }

From 968ec09cf2034381e58d31518160e746da8d60c7 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Fri, 2 Oct 2026 22:15:34 +0200
Subject: [PATCH 300/359] chore(release): prep 7.26.0 - a stock
 AVPlayerViewController shows scrub thumbnails from an I-frame rendition

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                    | 4 ++++
 Examples/README.md                              | 2 +-
 README.md                                       | 6 +++---
 Sources/AetherEngine/AetherEngine+Version.swift | 2 +-
 4 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1f8932fb5..b5e8e2942 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,10 @@ the public-API contract.
 
 ## [Unreleased]
 
+_Nothing yet._
+
+## [7.26.0] - 2026-10-02
+
 ### Added
 
 - **Scrub thumbnails in the stock player (#682).** `LoadOptions.serveIFramePlaylist` makes a native VOD session list an I-frame rendition in its master, which is the one input `AVPlayerViewController` takes thumbnails from: a host that presents the system transport bar gets them, and I-frame fast forward and rewind, without writing any UI. Each entry is the source's own keyframe at full resolution, read by a second reader and stamped on the main rendition's timeline. Off by default. The rendition is left out entirely, never half-served, where the session cannot answer every keyframe (live, MPEG-TS, single-connection origins, discs, media-playlist routing); the log names the reason.
diff --git a/Examples/README.md b/Examples/README.md
index f95e763dd..a942fe222 100644
--- a/Examples/README.md
+++ b/Examples/README.md
@@ -18,7 +18,7 @@ Three samples covering different audiences:
    ```
    https://github.com/superuser404notfound/AetherEngine
    ```
-   Dependency Rule: Up to Next Major Version, starting from `7.25.3`. Add the `AetherEngine` library product to your app target.
+   Dependency Rule: Up to Next Major Version, starting from `7.26.0`. Add the `AetherEngine` library product to your app target.
 
 3. **Drop the file in.** Replace the Xcode template's default `App.swift` (or whatever the generated `@main` file is called) with the contents of [`MinimalPlayerApp.swift`](MinimalPlayer/MinimalPlayerApp.swift). The file is self-contained: it defines both the `@main App` struct and the `ContentView`.
 
diff --git a/README.md b/README.md
index ef43e150e..120e15094 100644
--- a/README.md
+++ b/README.md
@@ -384,7 +384,7 @@ Subtitle cues land in raw source PTS; render the overlay against `player.sourceT
 Install via Swift Package Manager:
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.25.3")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.26.0")
 ```
 
 Three samples ship in `Examples/`:
@@ -631,10 +631,10 @@ Browse all of this as a searchable site at **[aetherengine.superuser404.de](http
 AetherEngine uses [Semantic Versioning](https://semver.org). The public API surface, every `public` declaration in `Sources/AetherEngine/`, is the stability contract. **Major** removes / renames public symbols or breaks adopters; **Minor** adds public API or codec / format support; **Patch** fixes bugs with no public API change. `internal` types are not part of the contract.
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.25.3")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.26.0")
 ```
 
-Pin to `.upToNextMinor(from: "7.25.3")` for stricter teams that prefer to opt into minor bumps explicitly.
+Pin to `.upToNextMinor(from: "7.26.0")` for stricter teams that prefer to opt into minor bumps explicitly.
 
 ## Requirements
 
diff --git a/Sources/AetherEngine/AetherEngine+Version.swift b/Sources/AetherEngine/AetherEngine+Version.swift
index 5d58ea83e..6c6aeefd3 100644
--- a/Sources/AetherEngine/AetherEngine+Version.swift
+++ b/Sources/AetherEngine/AetherEngine+Version.swift
@@ -11,5 +11,5 @@ extension AetherEngine {
     ///
     /// Between releases, and in a consumer that pins an unreleased commit for a device test, this
     /// names the last PUBLISHED version the checkout descends from, not every patch in it.
-    public nonisolated static let version = "7.25.3"
+    public nonisolated static let version = "7.26.0"
 }

From 9365288b27770fcf9014c3f103019a24bf6e62ad Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sat, 3 Oct 2026 05:53:29 +0200
Subject: [PATCH 301/359] fix(native): a VOD mount past the head holds its
 clock until the mount seek lands (#629)

The #646 hold covered only an in-place swap. A fresh item a host load()
placed at 15.90 s published AVPlayer's pre-landing reading, the start of
the segment it decodes up from (12.00 s), and once that load had returned
nothing parked 15.90 s any more. An item refused in that window was
rebuilt on the software path at 12.00 s and replayed 3.9 s.

The host now holds the clock on every mount that seeks past the head on
VOD, and a fresh mount states the position it is mounted at until the
seek lands or the item plays. Live and head mounts are unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                  |  4 +-
 .../Native/NativeAVPlayerHost.swift           | 49 ++++++++++++-----
 .../InPlaceSwapRollTests.swift                |  2 +-
 .../Issue629MountClockHoldTests.swift         | 55 +++++++++++++++++++
 4 files changed, 94 insertions(+), 16 deletions(-)
 create mode 100644 Tests/AetherEngineTests/Issue629MountClockHoldTests.swift

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b5e8e2942..3af50f97d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,7 +10,9 @@ the public-API contract.
 
 ## [Unreleased]
 
-_Nothing yet._
+### Fixed
+
+- **A software-path rescue replayed the gap a host `load()` had skipped (#629).** A native VOD item mounted past the head reads, until its mount seek lands, the start of the segment AVPlayer decodes up from (12.00 s under 15.90 s on the reporter's Apple TV), and the session published that reading. Once the host's `load()` had returned nothing else remembered 15.90 s, so an item AVPlayer refused in that window was rebuilt at 12.00 s and the film replayed 3.9 s after the rescue. The clock hold #646 gave the in-place swap now covers that mount as well: the session reads the position it was mounted at until the mount seek lands or the item plays, and the rescue resumes there. No API change.
 
 ## [7.26.0] - 2026-10-02
 
diff --git a/Sources/AetherEngine/Native/NativeAVPlayerHost.swift b/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
index e08afb71a..18c8417cf 100644
--- a/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
+++ b/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
@@ -228,14 +228,16 @@ final class NativeAVPlayerHost {
     /// uses this as authoritative presented-frame evidence when that publication wins the MainActor
     /// queue race against the resumed deadline continuation.
     private(set) var latestSeekRenderedTimePublished = false
-    /// AE#629: an in-place swap whose fresh item has not landed its mount seek yet. The swap keeps the
-    /// outgoing item's clock and picture, and until the landing AVPlayer reads first the target, then
-    /// the start of the segment it decodes up from (12.00 s under a 15.97 s revive on the harness).
-    /// Published, that second reading rewinds the playhead, and a software-path rebuild raised in the
-    /// window resumed there and replayed the gap. So neither reading is a landing: only the seek's own
-    /// completion is, or the item playing, which it cannot do short of the target. A seek of the host's
-    /// own takes the clock over from here as well.
-    private var inPlaceSwapMountPending = false
+    /// AE#629: a mount whose item has not landed its mount seek yet. Until the landing AVPlayer reads
+    /// first the target, then the start of the segment it decodes up from (12.00 s under a 15.97 s
+    /// revive on the harness). Published, that second reading rewinds the playhead, and a
+    /// software-path rebuild raised in the window resumed there and replayed the gap. So neither
+    /// reading is a landing: only the seek's own completion is, or the item playing, which it cannot
+    /// do short of the target. A seek of the host's own takes the clock over from here as well.
+    /// Round 5: not only an in-place swap. A VOD mount a host `load()` placed past the head has the
+    /// same window, and there the rebuild resumed at 12.00 s once that load had returned. See
+    /// `mountHoldsClock`.
+    private var mountSeekPending = false
 
     // MARK: - Output
 
@@ -462,7 +464,14 @@ final class NativeAVPlayerHost {
 
         self.sessionContract = contract
         mountedStartPosition = skipInitialSeek ? nil : (startPosition ?? 0)
-        inPlaceSwapMountPending = inPlaceSwap && !skipInitialSeek
+        mountSeekPending = Self.mountHoldsClock(inPlaceSwap: inPlaceSwap, skipInitialSeek: skipInitialSeek,
+                                                startPosition: startPosition, isLive: contract.isLive)
+        // A swap keeps the outgoing item's clock, which already reads the place it holds. A fresh
+        // mount has nothing there yet, so it states the place it is mounted at until the landing.
+        if mountSeekPending, !inPlaceSwap, let startPosition {
+            currentTime = startPosition
+            renderedTime = startPosition
+        }
         let forwardBufferDuration = contract.forwardBufferDuration
         let httpHeaders = contract.httpHeaders
         let armIngestFallback = contract.armIngestFallback
@@ -652,7 +661,7 @@ final class NativeAVPlayerHost {
                         // Audit NAT-103: a carried `.playing` that never changes status on its way to
                         // motion is this item's roll from here, as for the AE#440 one-shot.
                         self.hasEverPlayed = true
-                        self.inPlaceSwapMountPending = false
+                        self.mountSeekPending = false
                         self.startLiveJoinImmediatelyIfHolding(waitingReason: "-")
                     } else if self.timeControlStatus == .waitingToPlayAtSpecifiedRate {
                         // AE#684: a hold refused for an item that could not play yet is asked again
@@ -722,7 +731,7 @@ final class NativeAVPlayerHost {
                 if status == .playing,
                    Self.playingIsThisItemsRoll(itemIsReadyToPlay: self.playerItem?.status == .readyToPlay) {
                     self.hasEverPlayed = true
-                    self.inPlaceSwapMountPending = false
+                    self.mountSeekPending = false
                 }
                 if status == .playing, !self.didSampleSettledRoute {
                     self.didSampleSettledRoute = true
@@ -842,7 +851,7 @@ final class NativeAVPlayerHost {
             let value = time.seconds.isFinite ? time.seconds : 0
             Task { @MainActor in
                 guard let self, self.sessionID == sid else { return }
-                if self.inPlaceSwapMountPending { return }
+                if self.mountSeekPending { return }
                 // renderedTime tracks the parked on-screen frame mid-seek (issue #49).
                 self.renderedTime = value
                 // seekInFlight suppresses currentTime: AVPlayer still reports pre-seek clock until physical landing (issue #37).
@@ -906,7 +915,7 @@ final class NativeAVPlayerHost {
                 guard finished else { return }
                 Task { @MainActor in
                     guard let self, self.sessionID == sid else { return }
-                    self.inPlaceSwapMountPending = false
+                    self.mountSeekPending = false
                 }
             }
         }
@@ -1442,6 +1451,18 @@ final class NativeAVPlayerHost {
         itemIsReadyToPlay
     }
 
+    /// AE#629 round 5: whether a mount holds the clock until its mount seek lands. Every in-place swap
+    /// that seeks does (#646). A fresh mount does when it is VOD placed past the head: at the head
+    /// there is no earlier segment start to read, and a live mount's anchor sits on the item axis
+    /// while its clock is folded through the session shift.
+    nonisolated static func mountHoldsClock(
+        inPlaceSwap: Bool, skipInitialSeek: Bool, startPosition: Double?, isLive: Bool
+    ) -> Bool {
+        if skipInitialSeek { return false }
+        if inPlaceSwap { return true }
+        return !isLive && (startPosition ?? 0) > 0
+    }
+
     /// AE#440 round 3: what a refused hold did next, reported and never acted on.
     ///
     /// The guard above answers one instant, and the bound it read is read only at the hold's edges: a
@@ -1883,7 +1904,7 @@ final class NativeAVPlayerHost {
         let gen = seekGeneration
         seekInFlight = true
         // AE#629: this seek's own landing publishes the clock from here on.
-        inPlaceSwapMountPending = false
+        mountSeekPending = false
         latestSeekRenderedTimePublished = false
         let resumeGuard = SeekResumeGuard()
         return await withCheckedContinuation { (cont: CheckedContinuation<Bool, Never>) in
diff --git a/Tests/AetherEngineTests/InPlaceSwapRollTests.swift b/Tests/AetherEngineTests/InPlaceSwapRollTests.swift
index 8f3c81fe9..b639b46f2 100644
--- a/Tests/AetherEngineTests/InPlaceSwapRollTests.swift
+++ b/Tests/AetherEngineTests/InPlaceSwapRollTests.swift
@@ -30,7 +30,7 @@ struct InPlaceSwapRollTests {
         let body = String(text[sink.upperBound...].prefix(3000))
         let gate = try #require(body.range(of: "Self.playingIsThisItemsRoll(itemIsReadyToPlay:"))
         let latch = try #require(body.range(of: "self.hasEverPlayed = true"))
-        let release = try #require(body.range(of: "self.inPlaceSwapMountPending = false"))
+        let release = try #require(body.range(of: "self.mountSeekPending = false"))
         #expect(gate.lowerBound < latch.lowerBound)
         #expect(gate.lowerBound < release.lowerBound)
     }
diff --git a/Tests/AetherEngineTests/Issue629MountClockHoldTests.swift b/Tests/AetherEngineTests/Issue629MountClockHoldTests.swift
new file mode 100644
index 000000000..5dedede41
--- /dev/null
+++ b/Tests/AetherEngineTests/Issue629MountClockHoldTests.swift
@@ -0,0 +1,55 @@
+import Foundation
+import Testing
+@testable import AetherEngine
+
+/// AE#629 round 5 (cmcpherson274, 2026-10-01): the #646 clock hold covered only an in-place swap. A VOD
+/// item a host `load()` mounted at 15.90 s published AVPlayer's pre-landing reading, the start of the
+/// segment it decodes up from (12.00 s), and once that load had returned nothing parked the 15.90 s any
+/// more. AVPlayer refused the item before the mount seek landed, the software rebuild resumed at 12.00 s
+/// and the film replayed 3.9 s after the rescue.
+@Suite("A mount holds the clock until its mount seek lands")
+struct Issue629MountClockHoldTests {
+
+    @Test("Every seeking swap holds, a fresh mount only on VOD past the head")
+    func whichMountsHold() {
+        #expect(NativeAVPlayerHost.mountHoldsClock(inPlaceSwap: true, skipInitialSeek: false,
+                                                    startPosition: 15.9, isLive: false))
+        #expect(NativeAVPlayerHost.mountHoldsClock(inPlaceSwap: true, skipInitialSeek: false,
+                                                    startPosition: nil, isLive: true))
+        #expect(NativeAVPlayerHost.mountHoldsClock(inPlaceSwap: false, skipInitialSeek: false,
+                                                    startPosition: 15.9, isLive: false))
+        #expect(!NativeAVPlayerHost.mountHoldsClock(inPlaceSwap: false, skipInitialSeek: false,
+                                                     startPosition: 0, isLive: false))
+        #expect(!NativeAVPlayerHost.mountHoldsClock(inPlaceSwap: false, skipInitialSeek: false,
+                                                     startPosition: nil, isLive: false))
+        #expect(!NativeAVPlayerHost.mountHoldsClock(inPlaceSwap: false, skipInitialSeek: false,
+                                                     startPosition: 15.9, isLive: true))
+        #expect(!NativeAVPlayerHost.mountHoldsClock(inPlaceSwap: true, skipInitialSeek: true,
+                                                     startPosition: nil, isLive: true))
+    }
+
+    @Test("A fresh VOD mount past the head reads its mount position before the item answers")
+    @MainActor
+    func freshMountStatesItsPosition() {
+        let host = NativeAVPlayerHost()
+        host.load(url: URL(string: "http://127.0.0.1:1/vod/media.m3u8")!, startPosition: 15.9,
+                  contract: .init())
+        #expect(host.currentTime == 15.9)
+        #expect(host.renderedTime == 15.9)
+        // What the escalation rung resumes at once the host's load has returned.
+        #expect(AetherEngine.rebuildPosition(state: .playing, clock: host.currentTime,
+                                             underReconstruction: 15.9) == 15.9)
+    }
+
+    @Test("A mount at the head and a live mount publish nothing ahead of the item")
+    @MainActor
+    func otherMountsWaitForTheItem() {
+        let host = NativeAVPlayerHost()
+        host.load(url: URL(string: "http://127.0.0.1:1/vod/media.m3u8")!, startPosition: 0,
+                  contract: .init())
+        #expect(host.currentTime == 0)
+        host.load(url: URL(string: "http://127.0.0.1:1/live/media.m3u8")!, startPosition: 30,
+                  contract: .init(isLive: true))
+        #expect(host.currentTime == 0)
+    }
+}

From 9ea595ba20b1b0b14e1aa0a0369dd65fca0f23e6 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sat, 3 Oct 2026 06:00:53 +0200
Subject: [PATCH 302/359] chore(release): prep 7.26.1 - a VOD mount past the
 head holds its clock until the mount seek lands

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                    | 4 ++++
 Examples/README.md                              | 2 +-
 README.md                                       | 6 +++---
 Sources/AetherEngine/AetherEngine+Version.swift | 2 +-
 4 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3af50f97d..095f43b4d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,10 @@ the public-API contract.
 
 ## [Unreleased]
 
+_Nothing yet._
+
+## [7.26.1] - 2026-10-03
+
 ### Fixed
 
 - **A software-path rescue replayed the gap a host `load()` had skipped (#629).** A native VOD item mounted past the head reads, until its mount seek lands, the start of the segment AVPlayer decodes up from (12.00 s under 15.90 s on the reporter's Apple TV), and the session published that reading. Once the host's `load()` had returned nothing else remembered 15.90 s, so an item AVPlayer refused in that window was rebuilt at 12.00 s and the film replayed 3.9 s after the rescue. The clock hold #646 gave the in-place swap now covers that mount as well: the session reads the position it was mounted at until the mount seek lands or the item plays, and the rescue resumes there. No API change.
diff --git a/Examples/README.md b/Examples/README.md
index a942fe222..753502c42 100644
--- a/Examples/README.md
+++ b/Examples/README.md
@@ -18,7 +18,7 @@ Three samples covering different audiences:
    ```
    https://github.com/superuser404notfound/AetherEngine
    ```
-   Dependency Rule: Up to Next Major Version, starting from `7.26.0`. Add the `AetherEngine` library product to your app target.
+   Dependency Rule: Up to Next Major Version, starting from `7.26.1`. Add the `AetherEngine` library product to your app target.
 
 3. **Drop the file in.** Replace the Xcode template's default `App.swift` (or whatever the generated `@main` file is called) with the contents of [`MinimalPlayerApp.swift`](MinimalPlayer/MinimalPlayerApp.swift). The file is self-contained: it defines both the `@main App` struct and the `ContentView`.
 
diff --git a/README.md b/README.md
index 120e15094..07aaa5c5b 100644
--- a/README.md
+++ b/README.md
@@ -384,7 +384,7 @@ Subtitle cues land in raw source PTS; render the overlay against `player.sourceT
 Install via Swift Package Manager:
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.26.0")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.26.1")
 ```
 
 Three samples ship in `Examples/`:
@@ -631,10 +631,10 @@ Browse all of this as a searchable site at **[aetherengine.superuser404.de](http
 AetherEngine uses [Semantic Versioning](https://semver.org). The public API surface, every `public` declaration in `Sources/AetherEngine/`, is the stability contract. **Major** removes / renames public symbols or breaks adopters; **Minor** adds public API or codec / format support; **Patch** fixes bugs with no public API change. `internal` types are not part of the contract.
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.26.0")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.26.1")
 ```
 
-Pin to `.upToNextMinor(from: "7.26.0")` for stricter teams that prefer to opt into minor bumps explicitly.
+Pin to `.upToNextMinor(from: "7.26.1")` for stricter teams that prefer to opt into minor bumps explicitly.
 
 ## Requirements
 
diff --git a/Sources/AetherEngine/AetherEngine+Version.swift b/Sources/AetherEngine/AetherEngine+Version.swift
index 6c6aeefd3..cc12fc047 100644
--- a/Sources/AetherEngine/AetherEngine+Version.swift
+++ b/Sources/AetherEngine/AetherEngine+Version.swift
@@ -11,5 +11,5 @@ extension AetherEngine {
     ///
     /// Between releases, and in a consumer that pins an unreleased commit for a device test, this
     /// names the last PUBLISHED version the checkout descends from, not every patch in it.
-    public nonisolated static let version = "7.26.0"
+    public nonisolated static let version = "7.26.1"
 }

From 5cf1f64edb460410a34e5c5521620aa3e0bf0e9d Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sat, 3 Oct 2026 06:33:38 +0200
Subject: [PATCH 303/359] fix(live): one frame more no longer buys a whole
 second of fastZap TARGETDURATION (#670)

The fastZap GOP headroom took ceil(1.5 x max EXTINF). On a 59.94 fps
source with 1.001 s GOPs a 79-frame segment (1.318 s) sealed 2 and an
80-frame one (1.335 s, 2.002 x 1.5) sealed 3, a 9 s holdback that a 6 s
rebuild backlog could not hold: bounded start, first frame 2.5 s later.

The term now asks what it is for: the smallest TARGETDURATION under which
a GOP 1.5 x the longest seen still lists (RFC 8216 rounds EXTINF to the
nearest integer) and finishes inside AVPlayer's 1.5 x TD patience with
0.5 s to spare. Segments up to 1.666 s seal 2, 1 s GOPs keep 2, and the
value is never above the old one.

Measured with aetherctl live --fast-zap --realtime --preroll 6 on a
59.94 fps seed with one 80-frame segment, two runs per arm: main sealed 3,
served bounded after 1.345 s and presented at 2.94 to 2.95 s; the branch
sealed 2 and presented at 0.37 to 0.39 s. No -12888 or stall in either.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                  |  4 +-
 README.md                                     |  2 +-
 .../Video/VideoSegmentProvider.swift          | 32 +++++++++-
 .../Issue670FastZapGOPHeadroomTests.swift     | 60 +++++++++++++++++++
 docs/api.md                                   | 12 ++--
 5 files changed, 103 insertions(+), 7 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 095f43b4d..9707e0d08 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,7 +10,9 @@ the public-API contract.
 
 ## [Unreleased]
 
-_Nothing yet._
+### Fixed
+
+- **One frame more bought a whole second of `.fastZap` TARGETDURATION (#670 round 2).** The GOP headroom term took `ceil(1.5 x max EXTINF)`, so on a 59.94 fps source with 1.001 s GOPs a 79-frame segment (1.318 s) sealed 2 and an 80-frame one (1.335 s) sealed 3: a 9 s holdback, and a 6 s rebuild backlog then started bounded and presented 2.5 s later. The term now asks what it means, whether a GOP 1.5 x the longest seen would list legally (RFC 8216 rounds EXTINF to the nearest integer) and finish inside AVPlayer's `1.5 x TD` patience with 0.5 s to spare, so segments up to 1.666 s seal 2. Never above the old value; 1 s GOPs keep TARGETDURATION 2. The seal line names what the term needs (`1.5 x max EXTINF 2.002s needs 2s`). No API change.
 
 ## [7.26.1] - 2026-10-03
 
diff --git a/README.md b/README.md
index 07aaa5c5b..30685d4ec 100644
--- a/README.md
+++ b/README.md
@@ -477,7 +477,7 @@ player.$recordingState            // .idle / .recording / .ended / .failed
 
 `startRecording(to:)` (AetherEngine#560) writes the live source to an MPEG-TS file fed from the connection the session already holds. That is the point of it rather than a detail: an IPTV plan commonly caps an account at 1 to 3 simultaneous connections, so a host that opens its own connection to record either fails outright or knocks the viewer off the channel. It is a stream copy of the source packets taken before any audio bridging, so a TrueHD or DTS channel records its original audio while playback listens to the bridged rendition, and a file cut short by a crash is still playable up to the cut. Recording follows the source rather than the playhead, so pausing or scrubbing back inside the DVR window does not interrupt it, and a `liveSourceReset` ends it cleanly rather than writing past a seam the codecs may not survive. The one route that cannot record is `nativeRemoteHLS` (`.remoteBypass`), where AVFoundation holds the source connection and the engine never sees a byte; `startRecording` throws `.unsupportedRoute` there instead of producing an empty file. Full contract in [docs/api.md](docs/api.md#recording-a-live-stream).
 
-`liveJoinProfile: .fastZap` (AetherEngine#195/#208) cuts live segments at every keyframe past 0.5 s instead of the standard ~4 s, so the served `TARGETDURATION` collapses to 1.5 x the source GOP length (1 s GOPs serve 2; the headroom covers a broadcast's irregular GOPs, AetherEngine#670) and its live-edge holdback (`HOLD-BACK` = 3 x `TARGETDURATION`, the RFC 8216bis floor; AetherEngine#189) shrinks with it. The first manifest still prefers the full holdback. After two finalized segments, a strict-realtime source gets one observed-segment grace clamped to 0.5...2.0 s, then a shallow first window may be served so startup stays bounded. This can produce one early `-16832` or a short rebuffer. `.standard` retains the full-holdback guarantee. The smaller `TARGETDURATION` also tightens AVPlayer's unchanged-playlist patience and live-edge buffer, so origins that stall or burst mid-stream rebuffer more readily; opt in for zapping UX, keep `.standard` for lean-back viewing.
+`liveJoinProfile: .fastZap` (AetherEngine#195/#208) cuts live segments at every keyframe past 0.5 s instead of the standard ~4 s, so the served `TARGETDURATION` collapses to 1.5 x the source GOP length (1 s GOPs serve 2, and so do segments up to 1.666 s; the headroom covers a broadcast's irregular GOPs, AetherEngine#670) and its live-edge holdback (`HOLD-BACK` = 3 x `TARGETDURATION`, the RFC 8216bis floor; AetherEngine#189) shrinks with it. The first manifest still prefers the full holdback. After two finalized segments, a strict-realtime source gets one observed-segment grace clamped to 0.5...2.0 s, then a shallow first window may be served so startup stays bounded. This can produce one early `-16832` or a short rebuffer. `.standard` retains the full-holdback guarantee. The smaller `TARGETDURATION` also tightens AVPlayer's unchanged-playlist patience and live-edge buffer, so origins that stall or burst mid-stream rebuffer more readily; opt in for zapping UX, keep `.standard` for lean-back viewing.
 
 `liveSourceReset` is live's counterpart to a terminal `state = .error`, and a host that plays live has to subscribe to it. It fires where the session cannot be revived from inside the engine and only a new URL can: a source that restarted from byte 0 (a Jellyfin transcode respawn), a playlist still frozen after the stall ladder's last reload rung (#65), or an in-engine reopen transport whose budget is spent (#199). Each of those halts production first, so a dead provider stops advertising blocking reloads behind the host's back. Answer it by negotiating a fresh URL and calling `load` again, and guard that answer (one retune in flight, a minimum spacing, a bounded count per session) or a permanently dead upstream turns into a retune loop. Spend that bound out loud: a retune ladder that ends on a silent `return` leaves the same dead channel behind a counter, so surface the exhaustion the way a terminal `.error` would be surfaced.
 
diff --git a/Sources/AetherEngine/Video/VideoSegmentProvider.swift b/Sources/AetherEngine/Video/VideoSegmentProvider.swift
index 01456ac5b..ea9943652 100644
--- a/Sources/AetherEngine/Video/VideoSegmentProvider.swift
+++ b/Sources/AetherEngine/Video/VideoSegmentProvider.swift
@@ -416,7 +416,7 @@ enum LiveEdgePolicy {
         var td = wholeSecondsCovering(max(1.0, maxSegmentDuration))
         if let cut = cutTargetSeconds { td = max(td, wholeSecondsCovering(cut * 1.5)) }
         if gopHeadroomApplies(cutTargetSeconds: cutTargetSeconds, segmentsAreCutHere: segmentsAreCutHere) {
-            td = max(td, wholeSecondsCovering(maxSegmentDuration * 1.5))
+            td = max(td, targetDurationForGOPHeadroom(maxSegmentDuration))
         }
         if let floor = cadenceFloorSeconds { td = max(td, targetDurationForCadence(floor)) }
         if let upstream = upstreamSegmentSeconds { td = max(td, targetDurationForUpstreamSegment(upstream)) }
@@ -438,6 +438,35 @@ enum LiveEdgePolicy {
         return cut < 1.0
     }
 
+    /// AE#670: the smallest TARGETDURATION under which a GOP 1.5 x the longest seen would still be
+    /// served without fault: listed legally (RFC 8216 4.3.3.1 compares the EXTINF ROUNDED TO THE NEAREST
+    /// integer with TD) and finalized inside AVPlayer's `1.5 x TD` patience with
+    /// `gopHeadroomDeliveryMarginSeconds` to spare.
+    ///
+    /// Round 2: the first version took `ceil(1.5 x max EXTINF)`, which asks the virtual GOP for more than
+    /// any real segment is asked for and puts a cliff a millisecond wide into the seal. Reported on a
+    /// 59.94 fps source with 1.001 s GOPs: a 79-frame segment (1.318 s) sealed 2, an 80-frame one
+    /// (1.335 s, 2.002 x 1.5) sealed 3, a 9 s holdback a 6.6 s rebuild backlog could not hold, and the
+    /// first frame came 2.5 s later. Under TD 2 a GOP of 2.499 s still lists and leaves 0.5 s of patience,
+    /// so segments up to 1.666 s now seal 2, and the reporter's TD 2 sessions that later met 1.485 s ones
+    /// ran without a stall or -12888. Never above the first version: `round <= ceil`, and the patience
+    /// term only binds where the GOP is too short for the rounding to (TD 1 leaves a listed 1.5 x GOP no
+    /// patience at all, so 1.0 s GOPs keep their TD 2).
+    static func targetDurationForGOPHeadroom(_ maxSegmentSeconds: Double) -> Int {
+        guard maxSegmentSeconds.isFinite else { return wholeSecondsCovering(maxSegmentSeconds) }
+        let longerGOP = servedSeconds(maxSegmentSeconds * 1.5)
+        guard longerGOP > 0 else { return 0 }
+        let listed = wholeSecondsCovering(longerGOP.rounded(.toNearestOrAwayFromZero))
+        let patient = wholeSecondsCovering((longerGOP + gopHeadroomDeliveryMarginSeconds)
+                                           / unchangedPlaylistPatienceMultiplier)
+        return max(listed, patient)
+    }
+
+    /// AE#670 round 2: how long before AVPlayer's patience runs out a GOP 1.5 x the longest seen must
+    /// have been finalized. Half a second is what the first version already accepted for the 2.4 s GOP
+    /// it was reported for (TD 2, patience 3.0 s), so the relaxation gives up nothing that one kept.
+    static let gopHeadroomDeliveryMarginSeconds: Double = 0.5
+
     /// AVPlayer's default (and our explicitly advertised) live-edge holdback: `3 x TARGETDURATION`, the
     /// RFC 8216bis floor for `EXT-X-SERVER-CONTROL:HOLD-BACK`.
     static func holdBackSeconds(targetDuration: Int) -> Double { Double(3 * targetDuration) }
@@ -643,6 +672,7 @@ struct LiveTargetDurationDerivation {
         }
         if gopHeadroomApplies {
             terms.append("1.5 x max EXTINF \(LiveEdgePolicy.seconds(maxSegmentDuration * 1.5))s "
+                + "needs \(LiveEdgePolicy.targetDurationForGOPHeadroom(maxSegmentDuration))s "
                 + "(each segment is one whole GOP)")
         }
         terms.append(cadenceFloor.account)
diff --git a/Tests/AetherEngineTests/Issue670FastZapGOPHeadroomTests.swift b/Tests/AetherEngineTests/Issue670FastZapGOPHeadroomTests.swift
index ccff08886..ab48f5db3 100644
--- a/Tests/AetherEngineTests/Issue670FastZapGOPHeadroomTests.swift
+++ b/Tests/AetherEngineTests/Issue670FastZapGOPHeadroomTests.swift
@@ -76,6 +76,66 @@ final class Issue670FastZapGOPHeadroomTests: XCTestCase {
                                                             segmentsAreCutHere: true), 6)
     }
 
+    /// Round 2, reported on a 59.94 fps source with 1.001 s GOPs: 79 frames sealed 2 and 80 frames
+    /// sealed 3, one millisecond of `1.5 x` apart (1.977 against 2.002), and the 9 s holdback cost a
+    /// 6.6 s rebuild backlog its immediate start.
+    func testOneMoreFrameDoesNotBuyAWholeSecond() {
+        let frame = 1001.0 / 60000.0
+        for frames in [79, 80, 89] {
+            XCTAssertEqual(fastZapSeal(Double(frames) * frame), 2, "\(frames) frames")
+        }
+    }
+
+    /// The reporter's TD 2 sessions later met segments up to 1.485 s and ran without a stall or -12888.
+    func testFieldMaximumUnderTheSealStaysAtTwo() {
+        XCTAssertEqual(fastZapSeal(1.485), 2)
+    }
+
+    /// The boundary is where a GOP 1.5 x the longest seen would no longer list under TD 2: 2.499 s
+    /// rounds to 2, 2.5 s to 3.
+    func testHeadroomBoundaryFollowsTheListingRule() {
+        XCTAssertEqual(fastZapSeal(1.666), 2)
+        XCTAssertEqual(fastZapSeal(1.667), 3)
+    }
+
+    /// Every value of the round-2 term satisfies what the first version promised for its 2.4 s GOP:
+    /// a GOP 1.5 x the longest seen lists under TD and is finalized inside AVPlayer's patience with the
+    /// delivery margin to spare. And it is never above `ceil(1.5 x max EXTINF)`.
+    func testHeadroomTermKeepsItsPromiseAndNeverRaisesTheSeal() {
+        var gop = 0.3
+        while gop < 12 {
+            let td = LiveEdgePolicy.targetDurationForGOPHeadroom(gop)
+            let longer = LiveEdgePolicy.servedSeconds(gop * 1.5)
+            XCTAssertLessThanOrEqual(Int(longer.rounded(.toNearestOrAwayFromZero)), td, "\(gop)")
+            XCTAssertLessThanOrEqual(longer + LiveEdgePolicy.gopHeadroomDeliveryMarginSeconds,
+                                     Double(td) * LiveEdgePolicy.unchangedPlaylistPatienceMultiplier, "\(gop)")
+            XCTAssertLessThanOrEqual(td, LiveEdgePolicy.wholeSecondsCovering(gop * 1.5), "\(gop)")
+            gop += 0.001
+        }
+    }
+
+    func testHeadroomTermIsTotal() {
+        XCTAssertEqual(LiveEdgePolicy.targetDurationForGOPHeadroom(.nan), 0)
+        XCTAssertEqual(LiveEdgePolicy.targetDurationForGOPHeadroom(-1), 0)
+        XCTAssertEqual(LiveEdgePolicy.targetDurationForGOPHeadroom(.infinity), LiveEdgePolicy.maxCoveredWholeSeconds)
+        XCTAssertEqual(LiveEdgePolicy.targetDurationForGOPHeadroom(.greatestFiniteMagnitude),
+                       LiveEdgePolicy.maxCoveredWholeSeconds)
+    }
+
+    func testSealAccountNamesWhatTheHeadroomTermNeeds() {
+        let derivation = LiveTargetDurationDerivation(
+            value: 2, maxSegmentDuration: 80 * 1001.0 / 60000.0, cutTargetFloor: fastZapCut,
+            gopHeadroomApplies: true, cadenceFloor: .unmeasurable, selfReported: nil)
+        XCTAssertTrue(derivation.account.contains("1.5 x max EXTINF 2.002s needs 2s"), derivation.account)
+    }
+
+    private func fastZapSeal(_ maxSegment: Double) -> Int {
+        LiveEdgePolicy.targetDurationSeconds(maxSegmentDuration: maxSegment,
+                                             cutTargetSeconds: fastZapCut,
+                                             cadenceFloorSeconds: nil,
+                                             segmentsAreCutHere: true)
+    }
+
     func testSealAccountNamesTheHeadroomTerm() {
         let derivation = LiveTargetDurationDerivation(
             value: 2, maxSegmentDuration: 1.0, cutTargetFloor: fastZapCut,
diff --git a/docs/api.md b/docs/api.md
index 0c1748f9b..f0d30c44f 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -706,9 +706,13 @@ measured against, whether it waited or was satisfied immediately.
 cadence and the holdback follows it down, so the win belongs to the source GOP rather than to the flag:
 `TARGETDURATION` can never fall below `ceil(max EXTINF)`, and a long-GOP source therefore keeps most of
 its runway under either profile. Where the engine cuts the segments itself, each one is a whole GOP and
-the value is sealed from the first few, so it carries `ceil(1.5 x max EXTINF)` of headroom: a broadcast
-whose GOPs run 1.0 to 2.4 s sealed TARGETDURATION 1 on its first three and then broke `EXTINF <= TD`
-on every longer one (AE#670). 1 s GOPs therefore serve TARGETDURATION 2 and a 6 s holdback.
+the value is sealed from the first few, so it carries headroom for a GOP 1.5 x the longest seen: a
+broadcast whose GOPs run 1.0 to 2.4 s sealed TARGETDURATION 1 on its first three and then broke
+`EXTINF <= TD` on every longer one (AE#670). The headroom is the smallest value under which that longer
+GOP still lists (RFC 8216 rounds EXTINF to the nearest integer) and finishes inside AVPlayer's
+`1.5 x TARGETDURATION` patience with 0.5 s to spare, so 1 s GOPs serve TARGETDURATION 2 and a 6 s
+holdback, and so does a 59.94 fps stream whose scene-cut keyframes merge GOPs into 80 to 89-frame
+segments (up to 1.666 s seal 2).
 
 **An ingested HLS upstream seals over the segment it is delivered in, as far as its join pays for it,
 under either profile (AE#684).** The engine re-cuts an upstream segment (at its GOPs under `.fastZap`,
@@ -1062,7 +1066,7 @@ All flags default to safe values; the table is the full set. Depth for the media
 | `httpHeaders` | empty | Extra headers on every probe, range and segment fetch. On `nativeRemoteHLS` they ride into the `AVURLAsset`, so header-enforcing IPTV origins work. Forwarded to sidecar subtitle fetches unless overridden. **Scoping differs by route.** On the plain `nativeRemoteHLS` bypass AVFoundation itself sends them to every host the playlists name (cross-host variants, segments and `EXT-X-KEY` URIs) and carries them across 302 redirects, so credential headers there reach every such host and the engine cannot narrow that. The per-origin credential scoping described for `HLSLiveIngestReader` applies only on the routes the engine fetches itself: the ingest, the disc reader, the origin relay, the subtitle proxy, the audio tap and the live subtitle renditions. A credential that must not reach every host a playlist names should not ride in `httpHeaders` on the bypass. |
 | `isLive` | false | Treat the source as live. Set it explicitly; duration-based auto-detection is too noisy. |
 | `dvrWindowSeconds` | nil | Timeshift window. nil means live-only and `seek` is a no-op. The window is a ceiling: the disk budget (a quarter of the free space, at most 2 GiB) bounds what is actually kept, so a long window on a high-bitrate channel or a small volume holds less than it asks for. With several engines running, each one's quarter is taken from the free space the others have not already claimed, so a tile added on a tight volume holds less history than the first one (AE#687). |
-| `liveJoinProfile` | `.standard` | A `LiveJoinProfile`. `.fastZap` collapses TARGETDURATION to 1.5 x the source GOP (AE#670) so an IPTV join costs seconds instead of a full holdback. |
+| `liveJoinProfile` | `.standard` | A `LiveJoinProfile`. `.fastZap` collapses TARGETDURATION to the source GOP plus headroom for one 1.5 x longer (AE#670) so an IPTV join costs seconds instead of a full holdback. |
 | `clampsLiveResumeToWindow` | true | Whether `play()` may move a behind-live playhead by itself (edge snap on a live-only source more than 45 s behind, or a landing above the retained floor when a DVR window has slid past it). `false` hands the whole decision to the host, which then also owns the eviction case. |
 | `liveJoinStartsImmediately` | true | Cuts AVPlayer's stall-avoidance wait short once at the live join, over a buffer that is non-empty and at least 1.5 s deep, on an item that has reached `readyToPlay` (AE#684). The join tail no host can otherwise reach; default since 6.55.0 on a device A/B, see the live-join section. |
 | `liveBlockingReload` | nil (auto) | LL-HLS blocking-reload override for loopback live sessions. Auto derives eligibility from observed upstream cadence, which is what keeps a bursty relay off a `-15410` loop. |

From f660fc154daa9aeb6453bf918827fba4568e2478 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sat, 3 Oct 2026 06:51:02 +0200
Subject: [PATCH 304/359] chore(release): prep 7.26.2 - one frame more no
 longer buys a whole second of fastZap TARGETDURATION

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                    | 4 ++++
 Examples/README.md                              | 2 +-
 README.md                                       | 6 +++---
 Sources/AetherEngine/AetherEngine+Version.swift | 2 +-
 4 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9707e0d08..8bc380374 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,10 @@ the public-API contract.
 
 ## [Unreleased]
 
+_Nothing yet._
+
+## [7.26.2] - 2026-10-03
+
 ### Fixed
 
 - **One frame more bought a whole second of `.fastZap` TARGETDURATION (#670 round 2).** The GOP headroom term took `ceil(1.5 x max EXTINF)`, so on a 59.94 fps source with 1.001 s GOPs a 79-frame segment (1.318 s) sealed 2 and an 80-frame one (1.335 s) sealed 3: a 9 s holdback, and a 6 s rebuild backlog then started bounded and presented 2.5 s later. The term now asks what it means, whether a GOP 1.5 x the longest seen would list legally (RFC 8216 rounds EXTINF to the nearest integer) and finish inside AVPlayer's `1.5 x TD` patience with 0.5 s to spare, so segments up to 1.666 s seal 2. Never above the old value; 1 s GOPs keep TARGETDURATION 2. The seal line names what the term needs (`1.5 x max EXTINF 2.002s needs 2s`). No API change.
diff --git a/Examples/README.md b/Examples/README.md
index 753502c42..0e51b62c2 100644
--- a/Examples/README.md
+++ b/Examples/README.md
@@ -18,7 +18,7 @@ Three samples covering different audiences:
    ```
    https://github.com/superuser404notfound/AetherEngine
    ```
-   Dependency Rule: Up to Next Major Version, starting from `7.26.1`. Add the `AetherEngine` library product to your app target.
+   Dependency Rule: Up to Next Major Version, starting from `7.26.2`. Add the `AetherEngine` library product to your app target.
 
 3. **Drop the file in.** Replace the Xcode template's default `App.swift` (or whatever the generated `@main` file is called) with the contents of [`MinimalPlayerApp.swift`](MinimalPlayer/MinimalPlayerApp.swift). The file is self-contained: it defines both the `@main App` struct and the `ContentView`.
 
diff --git a/README.md b/README.md
index 30685d4ec..e13518741 100644
--- a/README.md
+++ b/README.md
@@ -384,7 +384,7 @@ Subtitle cues land in raw source PTS; render the overlay against `player.sourceT
 Install via Swift Package Manager:
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.26.1")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.26.2")
 ```
 
 Three samples ship in `Examples/`:
@@ -631,10 +631,10 @@ Browse all of this as a searchable site at **[aetherengine.superuser404.de](http
 AetherEngine uses [Semantic Versioning](https://semver.org). The public API surface, every `public` declaration in `Sources/AetherEngine/`, is the stability contract. **Major** removes / renames public symbols or breaks adopters; **Minor** adds public API or codec / format support; **Patch** fixes bugs with no public API change. `internal` types are not part of the contract.
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.26.1")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.26.2")
 ```
 
-Pin to `.upToNextMinor(from: "7.26.1")` for stricter teams that prefer to opt into minor bumps explicitly.
+Pin to `.upToNextMinor(from: "7.26.2")` for stricter teams that prefer to opt into minor bumps explicitly.
 
 ## Requirements
 
diff --git a/Sources/AetherEngine/AetherEngine+Version.swift b/Sources/AetherEngine/AetherEngine+Version.swift
index cc12fc047..ac2cc5200 100644
--- a/Sources/AetherEngine/AetherEngine+Version.swift
+++ b/Sources/AetherEngine/AetherEngine+Version.swift
@@ -11,5 +11,5 @@ extension AetherEngine {
     ///
     /// Between releases, and in a consumer that pins an unreleased commit for a device test, this
     /// names the last PUBLISHED version the checkout descends from, not every patch in it.
-    public nonisolated static let version = "7.26.1"
+    public nonisolated static let version = "7.26.2"
 }

From 66b1da52c7f06a14bdd399e0cce17372f92554d3 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sat, 3 Oct 2026 08:02:40 +0200
Subject: [PATCH 305/359] feat(live): an env-gated arm for the first-serve
 latch on engine-cut sources (#686)

On a source the engine cuts itself (raw MPEG-TS under fastZap) a bounded
start holds AVPlayer's second plain /media.m3u8 request for a second
grace: 1.015 to 1.384 s on every bounded start on the reporter's Apple TV.
#684 latched the gate for ingest sessions only, because whether skipping
that wait costs a stall (the session sits closer to the producing edge)
was never measured on a device.

AETHER_FIRST_SERVE_LATCH_ALL=1 extends the latch to engine-cut sources,
read once and off by default, like AETHER_BOUNDED_START_FLOOR. Both arms
now log how long the second request waited, which the reporter noted
was silent.

On the Mac (live --fast-zap --realtime --preroll 0, two runs per arm):
the arm removes exactly the grace (2.003 s / 1.011 s), init.mp4 and the
sustained advance come that much sooner, the playhead ends 0.9 to 2.0 s
closer to the edge, and neither arm stalled.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../AetherEngine/Video/HLSVideoEngine.swift   |  1 +
 .../Video/VideoSegmentProvider.swift          | 38 +++++++-
 .../Issue686FirstServeLatchArmTests.swift     | 93 +++++++++++++++++++
 docs/cli.md                                   | 18 ++++
 4 files changed, 147 insertions(+), 3 deletions(-)
 create mode 100644 Tests/AetherEngineTests/Issue686FirstServeLatchArmTests.swift

diff --git a/Sources/AetherEngine/Video/HLSVideoEngine.swift b/Sources/AetherEngine/Video/HLSVideoEngine.swift
index 1fef0d550..e8eede9b2 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine.swift
@@ -1968,6 +1968,7 @@ public final class HLSVideoEngine: @unchecked Sendable {
             ),
             allowsBoundedDegradedStart: liveJoinProfile == .fastZap,
             boundedStartFloorsAtHoldback: LiveEdgePolicy.boundedStartFloorArmed,
+            firstServeLatchCoversEngineCut: LiveEdgePolicy.firstServeLatchAllArmed,
             blockingReloadOverride: blockingReloadOverride,
             liveCadencePolicy: liveCadencePolicy,
             restartHandler: isLiveSession ? nil : { [weak self] idx in
diff --git a/Sources/AetherEngine/Video/VideoSegmentProvider.swift b/Sources/AetherEngine/Video/VideoSegmentProvider.swift
index ea9943652..2975be9f8 100644
--- a/Sources/AetherEngine/Video/VideoSegmentProvider.swift
+++ b/Sources/AetherEngine/Video/VideoSegmentProvider.swift
@@ -112,6 +112,12 @@ enum LiveEdgePolicy {
     static let boundedStartFloorArmed =
         ProcessInfo.processInfo.environment["AETHER_BOUNDED_START_FLOOR"] == "1"
 
+    /// AE#686, env-gated (`AETHER_FIRST_SERVE_LATCH_ALL=1`) for the same reason: it extends #684's
+    /// first-serve latch from ingest sessions to sources the engine cuts itself, so the second plain
+    /// manifest request no longer waits out a second grace. Read once.
+    static let firstServeLatchAllArmed =
+        ProcessInfo.processInfo.environment["AETHER_FIRST_SERVE_LATCH_ALL"] == "1"
+
     /// AVPlayer's unchanged-playlist patience: it tolerates a playlist that has not changed for this
     /// multiple of the served TARGETDURATION before drawing `-12888`. The one number the cadence floor
     /// is answerable to.
@@ -725,9 +731,14 @@ final class VideoSegmentProvider: HLSSegmentProvider, @unchecked Sendable {
     /// AE#594 arm B: skip the bounded branch, so the wait ends at the full holdback cushion or at the
     /// outer wall-clock deadline. Measurement arm, off unless the environment asks for it.
     private let boundedStartFloorsAtHoldback: Bool
+    /// AE#686 arm: the first-serve latch also covers a source the engine cuts itself. Measurement arm,
+    /// off unless the environment asks for it.
+    private let firstServeLatchCoversEngineCut: Bool
     /// AE#374: whether the first-serve gate has already reported the interval it held. Read and written
     /// only under `firstSegmentCondition`, inside `waitForFirstLiveSegment` and its two account helpers.
     private var didAccountForFirstServe = false
+    /// AE#686: whether the first repeat pass through the gate has been reported. Same lock.
+    private var didAccountForRepeatServe = false
     /// AE#684: on an ingest the gate is a FIRST-serve gate. Every `/media.m3u8` request without an
     /// `_HLS_msn` re-enters it, and AVPlayer opens a session with two of them back to back, so a
     /// bounded start (served under the holdback, after its grace) held the second request for a
@@ -953,6 +964,7 @@ final class VideoSegmentProvider: HLSSegmentProvider, @unchecked Sendable {
         liveWindowSizing: LiveWindowSizing = LiveWindowSizing(targetSegmentDurationSeconds: 4.0, dvrWindowSeconds: nil),
         allowsBoundedDegradedStart: Bool = false,
         boundedStartFloorsAtHoldback: Bool = false,
+        firstServeLatchCoversEngineCut: Bool = false,
         blockingReloadOverride: Bool? = nil,
         liveCadencePolicy: LiveCadencePolicy? = nil,
         restartHandler: ((Int) -> Void)? = nil,
@@ -983,6 +995,7 @@ final class VideoSegmentProvider: HLSSegmentProvider, @unchecked Sendable {
         self.liveWindowSizing = liveWindowSizing
         self.allowsBoundedDegradedStart = allowsBoundedDegradedStart
         self.boundedStartFloorsAtHoldback = boundedStartFloorsAtHoldback
+        self.firstServeLatchCoversEngineCut = firstServeLatchCoversEngineCut
         self.blockingReloadOverride = blockingReloadOverride
         self.liveCadencePolicy = liveCadencePolicy
         self.codecsString = codecsString
@@ -2600,8 +2613,11 @@ final class VideoSegmentProvider: HLSSegmentProvider, @unchecked Sendable {
             if waitersCancelled { return false }
             // Ingest sessions only. A source the engine cuts itself keeps the gate it had: there the
             // second request's wait is part of where the session ends up behind the producing edge,
-            // which is AE#594's question and not this one's.
-            if firstManifestServed, liveCadencePolicy != nil { return true }
+            // which is AE#594's question and not this one's. AE#686 measures it behind an arm.
+            if firstManifestServed, liveCadencePolicy != nil || firstServeLatchCoversEngineCut {
+                accountForRepeatServe(since: enteredAt, note: "first-serve latch")
+                return true
+            }
             // Spent first, snapshot second (see `firstServeTargetDuration`).
             let spent = liveCadencePolicy?.joinIsSpent
             let snap = liveCushionSnapshot()
@@ -2696,7 +2712,10 @@ final class VideoSegmentProvider: HLSSegmentProvider, @unchecked Sendable {
         note: String? = nil
     ) {
         firstManifestServed = true
-        guard !didAccountForFirstServe else { return }
+        guard !didAccountForFirstServe else {
+            accountForRepeatServe(since: entered, note: note)
+            return
+        }
         didAccountForFirstServe = true
         let account = LiveEdgePolicy.firstServeAccount(
             waitedSeconds: Self.secondsSince(entered),
@@ -2711,6 +2730,19 @@ final class VideoSegmentProvider: HLSSegmentProvider, @unchecked Sendable {
         )
     }
 
+    /// AE#686: AVPlayer opens with two plain manifest requests, and how long the second one waited is
+    /// the measurement the latch arm is about. Reported once, from whichever exit let it through.
+    private func accountForRepeatServe(since entered: DispatchTime, note: String?) {
+        guard !didAccountForRepeatServe else { return }
+        didAccountForRepeatServe = true
+        EngineLog.emit(
+            "[HLSVideoEngine] repeat live manifest request held "
+            + "\(LiveEdgePolicy.seconds(Self.secondsSince(entered)))s"
+            + (note.map { ", \($0)" } ?? ""),
+            category: .session
+        )
+    }
+
     /// The gate's other ending: the deadline passed and not one segment was ever cut, so there is no
     /// window to describe and the manifest cannot be served at all.
     private func accountForUnservedFirstManifest(since entered: DispatchTime) {
diff --git a/Tests/AetherEngineTests/Issue686FirstServeLatchArmTests.swift b/Tests/AetherEngineTests/Issue686FirstServeLatchArmTests.swift
new file mode 100644
index 000000000..24ad4a5a5
--- /dev/null
+++ b/Tests/AetherEngineTests/Issue686FirstServeLatchArmTests.swift
@@ -0,0 +1,93 @@
+// AE#686: on a source the engine cuts itself (raw MPEG-TS under fastZap) a bounded start holds
+// AVPlayer's second plain `/media.m3u8` request for a second grace, measured on an Apple TV as
+// 1.015 to 1.384 s on every bounded start. #684 latched the gate for ingest sessions only, because
+// whether the engine-cut path pays for skipping that wait (a session closer to the producing edge)
+// was never measured. `AETHER_FIRST_SERVE_LATCH_ALL=1` is the arm that measures it; off by default.
+import XCTest
+@testable import AetherEngine
+
+final class Issue686FirstServeLatchArmTests: XCTestCase {
+
+    private func makeProvider(latchArm: Bool) -> (VideoSegmentProvider, SegmentCache) {
+        let cache = SegmentCache(forwardWindow: 10, backwardWindow: 10)
+        let provider = VideoSegmentProvider(
+            cache: cache,
+            segments: [],
+            codecsString: "avc1.4D001E,mp4a.40.2",
+            supplementalCodecs: nil,
+            resolution: (720, 576),
+            videoRange: .sdr,
+            frameRate: 25,
+            hdcpLevel: nil,
+            sourceBitrate: 1_500_000,
+            isLive: true,
+            liveWindowSizing: LiveWindowSizing(targetSegmentDurationSeconds: 0.5, dvrWindowSeconds: nil),
+            allowsBoundedDegradedStart: true,
+            firstServeLatchCoversEngineCut: latchArm
+        )
+        return (provider, cache)
+    }
+
+    private func seconds(_ body: () -> Void) -> Double {
+        let start = DispatchTime.now()
+        body()
+        return Double(DispatchTime.now().uptimeNanoseconds - start.uptimeNanoseconds) / 1_000_000_000
+    }
+
+    func testTheArmIsOffWithoutTheEnvironment() {
+        XCTAssertEqual(LiveEdgePolicy.firstServeLatchAllArmed,
+                       ProcessInfo.processInfo.environment["AETHER_FIRST_SERVE_LATCH_ALL"] == "1")
+    }
+
+    /// Two 0.2 s segments against a 3 s holdback: the bounded start, grace 0.5 s.
+    func testArmedASelfCutSourceLetsTheSecondRequestThrough() {
+        let (provider, cache) = makeProvider(latchArm: true)
+        defer { cache.close() }
+        provider.appendLiveSegment(index: 0, startSeconds: 0, durationSeconds: 0.2)
+        provider.appendLiveSegment(index: 1, startSeconds: 0.2, durationSeconds: 0.2)
+
+        var served = false
+        let first = seconds { served = provider.waitForFirstLiveSegment(timeout: 3) }
+        XCTAssertTrue(served)
+        XCTAssertGreaterThanOrEqual(first, 0.45, "the first request still pays the grace")
+
+        let second = seconds { served = provider.waitForFirstLiveSegment(timeout: 3) }
+        XCTAssertTrue(served)
+        XCTAssertLessThan(second, 0.2, "the arm latches the gate once a manifest has gone out")
+    }
+
+    func testArmedAnUnservedGateStaysAGate() {
+        let (provider, cache) = makeProvider(latchArm: true)
+        defer { cache.close() }
+        XCTAssertFalse(provider.waitForFirstLiveSegment(timeout: 0.1))
+        XCTAssertFalse(provider.waitForFirstLiveSegment(timeout: 0.1))
+    }
+
+    /// The repeat line is the measurement both arms are compared on, so it must appear in the
+    /// unarmed one too, once, with the held interval.
+    func testTheRepeatRequestIsAccountedOnceInEitherArm() {
+        for armed in [false, true] {
+            let (provider, cache) = makeProvider(latchArm: armed)
+            defer { cache.close() }
+            provider.appendLiveSegment(index: 0, startSeconds: 0, durationSeconds: 0.2)
+            provider.appendLiveSegment(index: 1, startSeconds: 0.2, durationSeconds: 0.2)
+
+            let capture = EngineLogCapture()
+            defer { capture.end() }
+
+            XCTAssertTrue(provider.waitForFirstLiveSegment(timeout: 3))
+            XCTAssertTrue(provider.waitForFirstLiveSegment(timeout: 3))
+            let afterSecond = capture.matching("repeat live manifest request held").count
+            XCTAssertTrue(provider.waitForFirstLiveSegment(timeout: 3))
+
+            let repeats = capture.matching("repeat live manifest request held")
+            XCTAssertGreaterThanOrEqual(afterSecond, 1, "armed=\(armed)")
+            XCTAssertEqual(repeats.count, afterSecond, "armed=\(armed): a third request adds no line")
+            if armed {
+                XCTAssertTrue(repeats.contains { $0.contains("first-serve latch") })
+            } else {
+                XCTAssertTrue(repeats.contains { $0.contains("fastZap bounded start") })
+            }
+        }
+    }
+}
diff --git a/docs/cli.md b/docs/cli.md
index 7664439d7..2823793cc 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -769,6 +769,24 @@ No run stalled in either arm. The extra segment on 6,4 is the short one, and the
 
 **The gate held the second playlist request too.** AVPlayer opens with two `/media.m3u8` requests, each re-enters `waitForFirstLiveSegment`, and on a bounded start each waited its own grace (`GET /media.m3u8` at 2.81 s, `GET /init.mp4` at 4.83 s). On an ingest the gate now opens for good once a manifest has gone out. On a source the engine cuts itself it does not: that second grace is the "+2.07 s at the picture" of the AE#594 table above, and removing it there also leaves the session up to 2 s closer to the producing edge, which is that issue's open question. The raw-TS control (`live --fast-zap --realtime --preroll 0`, two seeds, two runs per arm) reads the same in both arms: first manifest at 3.84 to 3.96 s, `init.mp4` at 6.11 to 6.33 s, first picture at 6.20 to 6.58 s, playhead 6.3 to 6.8 s behind the wall clock. The AE#594 table stands as printed.
 
+**AE#686 measures that second grace behind an arm.** `AETHER_FIRST_SERVE_LATCH_ALL=1` applies the same latch to a source the engine cuts itself. It is a measurement arm like `AETHER_BOUNDED_START_FLOOR`, read once per process and off by default, because what it may cost (a session closer to the producing edge for its whole life) needs a device that seeks to edge-minus-holdback, which this harness does not. Both arms now print how long AVPlayer's second plain request waited, once per session:
+
+```
+[HLSVideoEngine] repeat live manifest request held 2.003s, fastZap bounded start after 2.000s grace
+[HLSVideoEngine] repeat live manifest request held 0.000s, first-serve latch
+```
+
+`live --fast-zap --realtime --preroll 0 --seconds 40`, two runs per arm, interleaved:
+
+| seed | arm | first manifest | second request held | `GET /init.mp4` | sustained advance | `item=` at the end | stalls |
+|---|---|---|---|---|---|---|---|
+| `h264-ts-sample.ts` (2 s cuts) | off | 3.76 to 3.94 s, 2 segments | 2.003 s | 6.10 to 6.14 s | 7.4 to 7.7 s | 34.78 to 34.95 s | 0 |
+| `h264-ts-sample.ts` | on | 3.94 s, 2 segments | 0.000 s | 4.08 s | 5.2 to 5.3 s | 36.57 to 37.20 s | 0 |
+| 1080p59.94, 1 s GOP | off | 1.22 to 1.23 s, 3 segments | 1.011 s | 2.43 s | 3.2 s | 38.30 to 38.40 s | 0 |
+| 1080p59.94, 1 s GOP | on | 1.24 s, 3 segments | 0.000 s | 1.41 to 1.44 s | 1.1 s | 39.19 to 39.30 s | 0 |
+
+The arm removes exactly the grace, and the session ends that much closer to the edge. Whether that costs a stall is the device half.
+
 The full matrix (6 s and 10 s segments, 3, 4 and 8 listed, both profiles, three runs per arm) is in `api.md` under the live join; `.standard` drops `--fast-zap` from the `play` line.
 
 **The same fixture measures sound against picture, in the bytes.** `play --served-url` hands over the init segment, the cache holds the rest, and decoding their concatenation gives the presentation time of every flash and every beep onset: 147 of 148 seconds of a served session read **-0.3 ms** (the very first beep reads +19.7 ms, the decoder starting), across a 12 s outage, with no audio frame of any duration but 1024 samples and no gap at any segment seam. A fresh item re-fetches the same cached segments, so a rebuild cannot change that. What a rebuild does change is which segment the item starts on and where in it, and a segment's sound does not begin where its picture does: the cut is taken on the video keyframe and a transport stream interleaves audio behind video, so on this fixture the sound opens between 11 ms after and 208 ms before the picture, segment by segment. Each item now says what it started on,

From 7ac28fa409601d12ec68eeb2e9468a240d5d90cd Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sat, 3 Oct 2026 08:44:38 +0200
Subject: [PATCH 306/359] chore(release): prep 7.26.3 - an env-gated arm for
 the first-serve latch on engine-cut sources

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                    | 6 ++++++
 Examples/README.md                              | 2 +-
 README.md                                       | 6 +++---
 Sources/AetherEngine/AetherEngine+Version.swift | 2 +-
 4 files changed, 11 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8bc380374..053bb715a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,12 @@ the public-API contract.
 
 _Nothing yet._
 
+## [7.26.3] - 2026-10-03
+
+### Added
+
+- **A measurement arm for the first-serve latch on engine-cut sources (#686).** On raw MPEG-TS under `.fastZap` a bounded start held AVPlayer's second plain `/media.m3u8` request for a second grace (1.0 to 1.4 s on the reporter's Apple TV). `AETHER_FIRST_SERVE_LATCH_ALL=1` applies #684's latch to those sources too; read once per process, off by default, so default behaviour is unchanged. Both arms now log how long that second request waited (`repeat live manifest request held Xs`), which was silent before. No API change.
+
 ## [7.26.2] - 2026-10-03
 
 ### Fixed
diff --git a/Examples/README.md b/Examples/README.md
index 0e51b62c2..4467fb107 100644
--- a/Examples/README.md
+++ b/Examples/README.md
@@ -18,7 +18,7 @@ Three samples covering different audiences:
    ```
    https://github.com/superuser404notfound/AetherEngine
    ```
-   Dependency Rule: Up to Next Major Version, starting from `7.26.2`. Add the `AetherEngine` library product to your app target.
+   Dependency Rule: Up to Next Major Version, starting from `7.26.3`. Add the `AetherEngine` library product to your app target.
 
 3. **Drop the file in.** Replace the Xcode template's default `App.swift` (or whatever the generated `@main` file is called) with the contents of [`MinimalPlayerApp.swift`](MinimalPlayer/MinimalPlayerApp.swift). The file is self-contained: it defines both the `@main App` struct and the `ContentView`.
 
diff --git a/README.md b/README.md
index e13518741..a75e164f0 100644
--- a/README.md
+++ b/README.md
@@ -384,7 +384,7 @@ Subtitle cues land in raw source PTS; render the overlay against `player.sourceT
 Install via Swift Package Manager:
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.26.2")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.26.3")
 ```
 
 Three samples ship in `Examples/`:
@@ -631,10 +631,10 @@ Browse all of this as a searchable site at **[aetherengine.superuser404.de](http
 AetherEngine uses [Semantic Versioning](https://semver.org). The public API surface, every `public` declaration in `Sources/AetherEngine/`, is the stability contract. **Major** removes / renames public symbols or breaks adopters; **Minor** adds public API or codec / format support; **Patch** fixes bugs with no public API change. `internal` types are not part of the contract.
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.26.2")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.26.3")
 ```
 
-Pin to `.upToNextMinor(from: "7.26.2")` for stricter teams that prefer to opt into minor bumps explicitly.
+Pin to `.upToNextMinor(from: "7.26.3")` for stricter teams that prefer to opt into minor bumps explicitly.
 
 ## Requirements
 
diff --git a/Sources/AetherEngine/AetherEngine+Version.swift b/Sources/AetherEngine/AetherEngine+Version.swift
index ac2cc5200..365d2fbd2 100644
--- a/Sources/AetherEngine/AetherEngine+Version.swift
+++ b/Sources/AetherEngine/AetherEngine+Version.swift
@@ -11,5 +11,5 @@ extension AetherEngine {
     ///
     /// Between releases, and in a consumer that pins an unreleased commit for a device test, this
     /// names the last PUBLISHED version the checkout descends from, not every patch in it.
-    public nonisolated static let version = "7.26.2"
+    public nonisolated static let version = "7.26.3"
 }

From e8d8c2fe1c600815b13421421fd8a30e71e60c9c Mon Sep 17 00:00:00 2001
From: superuser404notfound
 <264232962+superuser404notfound@users.noreply.github.com>
Date: Sun, 4 Oct 2026 09:23:15 +0000
Subject: [PATCH 307/359] docs(used-by): add WUW IPTV Player

---
 README.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/README.md b/README.md
index a75e164f0..18465fa71 100644
--- a/README.md
+++ b/README.md
@@ -49,6 +49,7 @@ You provide the transport bar. You provide the dropdowns. You provide the pretty
 - [stashy](https://stashy.shelf.am/): iOS/tvOS native player for stash.
 - [Gflix](https://gflixhub.app/): A flawless media app for your media.
 - [Melon Video](https://apps.apple.com/ca/app/melon-video/id6811750997): Video Player for Vision Pro.
+- [WUW IPTV Player](https://apps.apple.com/tr/app/wuw-iptv-player-smart-m3u-tv/id6759220800): Watch U Want — or simply WUW — your IPTV player for iPhone, iPad, Mac, Apple TV and Apple Vision Pro.
 <!-- used-by:end -->
 
 Shipping something on AetherEngine? [Submit it](https://github.com/superuser404notfound/AetherEngine/issues/new?template=used-by-submission.yml) to get listed here and on [aetherengine.superuser404.de](https://aetherengine.superuser404.de).

From 7fad6bf091af2aeb0491f8a382b282bfa4601eb5 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sun, 4 Oct 2026 17:32:34 +0200
Subject: [PATCH 308/359] fix(demux): one refusal at byte 0 no longer settles a
 range-capable VOD forward-only (#693)

An Xtream origin answered the ranged open of an episode with a 403 and the
unranged GET right after it with a 200. Since #378 every 401/403/404/410 at
byte 0 was read as the answer to the resource, so the source was served as
a sequential origin for the whole session: startPosition dropped, every seek
past the downloaded window snapped back. Ranged requests to the same origin
worked again later.

The open now asks the same range once more before it settles. Served, the
source stays seekable. Refused again, the #378 path runs unchanged (probe
skip, one unranged GET, typed failure if that is refused too).

Adds the published isSequentialOrigin, so a host can see a session that does
settle sequential (startPosition not honoured, seeks only inside
$residentRanges) instead of reading log lines.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                  |   8 +-
 Sources/AetherEngine/AetherEngine.swift       |  11 ++
 Sources/AetherEngine/Demuxer/AVIOReader.swift |  34 +++++-
 .../Issue693TransientRefusalTests.swift       | 108 ++++++++++++++++++
 docs/api.md                                   |   1 +
 5 files changed, 158 insertions(+), 4 deletions(-)
 create mode 100644 Tests/AetherEngineTests/Issue693TransientRefusalTests.swift

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 053bb715a..4253f3d7a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,7 +10,13 @@ the public-API contract.
 
 ## [Unreleased]
 
-_Nothing yet._
+### Fixed
+
+- **One refusal at byte 0 no longer settles a range-capable VOD forward-only for the whole session (#693).** An Xtream origin answered the ranged open of an episode with a 403 and the unranged GET right after it with a 200. Since #378 every 401/403/404/410 at byte 0 was read as the answer to the resource, so the source was served as a sequential origin: `startPosition` dropped and every seek past the downloaded window snapped back. The open now asks the same range once more before it settles: served, the source stays seekable; refused again, the #378 path runs unchanged. A source that refuses everything costs one request more and still fails typed with its status.
+
+### Added
+
+- **`isSequentialOrigin` (#693).** Published, true while a VOD session is served as a sequential origin, declared or found by the reader. Such a session plays from the start (a `startPosition` was not honoured) and a seek lands only inside `$residentRanges`, so a host can reopen the source itself or tell the user instead of reading log lines.
 
 ## [7.26.3] - 2026-10-03
 
diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index e7cef3c6d..3ae52d5aa 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -1371,6 +1371,14 @@ public final class AetherEngine: ObservableObject {
     /// True for a live session (`LoadOptions.isLive`). Cleared in stopInternal so it can't bleed into the next VOD load.
     @Published public internal(set) var isLive: Bool = false
 
+    /// True while a VOD session is served as a sequential origin: the source can only be read front to
+    /// back, either because `LoadOptions.sequentialOrigin` declared it or because the origin refused the
+    /// range form at open (twice, AE#693) and served a plain GET. Such a session plays from the start,
+    /// so a `startPosition` passed to `load()` is not honoured, and a seek lands only inside what the
+    /// session has already read. A host that needs the position reopens the source itself, or tells the
+    /// user. Set during `load()`, before `state` leaves `.loading`; cleared on stop.
+    @Published public internal(set) var isSequentialOrigin: Bool = false
+
     /// What the session's live recording is doing (AE#560). `.idle` when nothing is recording.
     /// See `startRecording(to:)`.
     @Published public internal(set) var recordingState: RecordingState = .idle
@@ -3985,6 +3993,7 @@ public final class AetherEngine: ObservableObject {
         // host-initiated reload would resurrect a stale session snapshot.
         loadedOptions.subtitleSessionCarryover = nil
         isLive = options.isLive
+        isSequentialOrigin = !options.isLive && options.sequentialOrigin
         // nativeRemoteHLS: DVR window is unbounded (AVPlayer clamps seeks to its real seekable range);
         // an over-wide published bound only affects range width, not seek landing.
         liveWindow = options.isLive
@@ -4899,6 +4908,7 @@ public final class AetherEngine: ObservableObject {
             options.declaredDurationSeconds = probe.duration
             loadedOptions.sequentialOrigin = true
             loadedOptions.declaredDurationSeconds = probe.duration
+            isSequentialOrigin = true
             EngineLog.emit(
                 "[AetherEngine] forward-only source with a container duration of "
                 + "\(String(format: "%.1f", probe.duration))s: serving it as a sequential origin",
@@ -7360,6 +7370,7 @@ public final class AetherEngine: ObservableObject {
         activeDiscTitleID = nil
         sourceStartSeconds = 0
         isLive = false
+        isSequentialOrigin = false
         liveWindow = nil
         liveBehindWhenLastAdvancing = 0
         lastPublishedLivePlayhead = nil
diff --git a/Sources/AetherEngine/Demuxer/AVIOReader.swift b/Sources/AetherEngine/Demuxer/AVIOReader.swift
index fa73cb5fb..ea837a9a7 100644
--- a/Sources/AetherEngine/Demuxer/AVIOReader.swift
+++ b/Sources/AetherEngine/Demuxer/AVIOReader.swift
@@ -1233,7 +1233,26 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
                 rangeVerdictPending = !isLive
                 winCond.unlock()
                 startPersistentConnection(at: 0, boundedTo: boundedInitialFetch)
-                gotData = awaitFirstPersistentData()
+                var opened = awaitFirstPersistentData()
+                // AE#693: one refusal is the origin's answer to that request, not yet to the
+                // resource. The #378 path below takes a 401/403/404/410 here as final and settles
+                // the session forward-only, which costs it every seek and the resume position. An
+                // IPTV panel answered a ranged open 403 and the unranged GET right after it 200, and
+                // ranged requests worked again later. Asking the same range once more decides it:
+                // served, the source stays seekable; refused again, the #378 path runs as before.
+                if !opened, !isLive, let refusal = refusalOfOpenConnection() {
+                    EngineLog.emit(
+                        "[AVIOReader] \(label) ranged open refused status=\(refusal) at offset 0; "
+                        + "asking once more before settling the source forward-only (AE#693)",
+                        category: .demux)
+                    try probeControl?.check()
+                    winCond.lock()
+                    rangeVerdictPending = true
+                    winCond.unlock()
+                    startPersistentConnection(at: 0, boundedTo: boundedInitialFetch)
+                    opened = awaitFirstPersistentData()
+                }
+                gotData = opened
                 openPrefix = firstWindowPrefix()
             }
             // AE#140: an HLS playlist URL misrouted onto the raw-byte live path. A live origin serves the
@@ -1281,8 +1300,9 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
                     try failIfStreamingRefused(fallbackStatus: 0)
                 } else if !haveSize {
                     tookFallback = true
-                    // A 401/403/404/410 at byte 0 is the origin's answer to the RESOURCE, not to
-                    // the range form: a HEAD or a `bytes=0-1` from the same client is answered
+                    // A 401/403/404/410 at byte 0, given twice (AE#693: once can be the moment's),
+                    // is the origin's answer to the RESOURCE, not to the range form: a HEAD or a
+                    // `bytes=0-1` from the same client is answered
                     // alike, and a size learned from either would only re-issue the refused range
                     // on the persistent path (which then dies after one retry with the status
                     // lost). Skip the ladder. The one request still worth making is the unranged
@@ -1410,6 +1430,14 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
         return gotData
     }
 
+    /// The refusal status the current persistent connection ended on, nil when it did not end on one
+    /// of the `isResolvedExpiryStatus` refusals. Demux thread, open-time only.
+    private func refusalOfOpenConnection() -> Int? {
+        winCond.lock()
+        defer { winCond.unlock() }
+        return (connEnded && Self.isResolvedExpiryStatus(connStatus)) ? connStatus : nil
+    }
+
     /// The streaming GET was answered with a status instead of a body, or the ranged open was
     /// already refused with one and the unranged GET then delivered nothing either. Either way the
     /// demuxer would be handed an empty stream (or an error page) and report it as invalid data;
diff --git a/Tests/AetherEngineTests/Issue693TransientRefusalTests.swift b/Tests/AetherEngineTests/Issue693TransientRefusalTests.swift
new file mode 100644
index 000000000..5db50ede2
--- /dev/null
+++ b/Tests/AetherEngineTests/Issue693TransientRefusalTests.swift
@@ -0,0 +1,108 @@
+// #693: a transient refusal at byte 0. KIPTV's Xtream origin answered the ranged open of a series
+// episode with a 403, and the unranged GET the reader sent right after it, to the same resource, was
+// answered 200. #378 had read every 401/403/404/410 at byte 0 as "the origin's answer to the
+// RESOURCE", so that one 403 decided the whole session: the reader streamed forward-only, the load
+// promoted the source to a sequential origin, the saved position was dropped and every seek past
+// the downloaded window snapped back. Ten hours later the same origin answered every ranged request
+// with a 206.
+//
+// A refusal that the next request does not repeat says nothing about the resource. The open now asks
+// the same range once more before it settles, and only a second refusal sends it down the #378 path.
+import Foundation
+import Testing
+@testable import AetherEngine
+
+@Suite("#693 a refusal at byte 0 that is not repeated keeps the source seekable", .serialized)
+struct Issue693TransientRefusalTests {
+
+    private static let fileSize = 8 * 1024 * 1024
+
+    private final class Counter: @unchecked Sendable {
+        private let lock = NSLock()
+        private var value = 0
+        func next() -> Int {
+            lock.lock(); defer { lock.unlock() }
+            value += 1
+            return value
+        }
+    }
+
+    /// A range-capable origin. `refuseByteZero` decides, per ranged request at byte 0 (1-based), whether
+    /// that one is answered 403.
+    private static func origin(refuseByteZero: @escaping @Sendable (Int) -> Bool) throws -> ScriptedOriginServer {
+        let byteZero = Counter()
+        return try #require(ScriptedOriginServer { request in
+            let total = Int64(fileSize)
+            guard let range = request.range else {
+                return .init(status: 200, declaredLength: total, bodyBytes: fileSize)
+            }
+            if range.hasPrefix("bytes=-") {
+                return .init(status: 206, declaredLength: 65_536,
+                             contentRange: "bytes \(total - 65_536)-\(total - 1)/\(total)", bodyBytes: 65_536)
+            }
+            let bounds = range.dropFirst("bytes=".count).split(separator: "-", omittingEmptySubsequences: false)
+            let start = Int64(bounds.first ?? "") ?? 0
+            let end = min(Int64(bounds.count > 1 ? bounds[1] : "") ?? (total - 1), total - 1)
+            if start == 0, refuseByteZero(byteZero.next()) {
+                return .init(status: 403, declaredLength: 0)
+            }
+            let length = Int(end - start + 1)
+            return .init(status: 206, declaredLength: Int64(length),
+                         contentRange: "bytes \(start)-\(end)/\(total)", bodyBytes: length)
+        })
+    }
+
+    @Test("a 403 that the second ranged open does not repeat leaves the source seekable, without an unranged GET")
+    func transientRefusalKeepsSeekability() throws {
+        let server = try Self.origin { $0 == 1 }
+        defer { server.stop() }
+        let url = URL(string: "http://127.0.0.1:\(server.port)/series/episode.mp4")!
+
+        let reader = AVIOReader(url: url)
+        defer { reader.markClosed(); reader.close() }
+        try reader.open()
+        #expect(reader.isSeekable, "one 403 at byte 0 turned a range-capable origin forward-only")
+
+        var buffer = [UInt8](repeating: 0, count: 64 * 1024)
+        let read = buffer.withUnsafeMutableBufferPointer { reader.read(into: $0.baseAddress!, size: Int32($0.count)) }
+        #expect(read > 0, "the second ranged open delivered nothing: \(read)")
+
+        let requests = server.requests
+        #expect(!requests.contains { $0.method == "GET" && $0.range == nil },
+                "settled on the unranged GET although the range form was served: \(requests)")
+        #expect(!requests.contains { $0.method == "HEAD" })
+        #expect(requests.filter { $0.range?.hasPrefix("bytes=0-") == true }.count == 2,
+                "expected the refused ranged open and exactly one more: \(requests)")
+    }
+
+    @Test("a 403 that the second ranged open repeats settles forward-only on one unranged GET, as #378 does")
+    func repeatedRefusalSettlesForwardOnly() throws {
+        let server = try Self.origin { _ in true }
+        defer { server.stop() }
+        let url = URL(string: "http://127.0.0.1:\(server.port)/series/episode.mp4")!
+
+        let reader = AVIOReader(url: url)
+        defer { reader.markClosed(); reader.close() }
+        try reader.open()
+        #expect(!reader.isSeekable)
+
+        let requests = server.requests
+        #expect(requests.filter { $0.range?.hasPrefix("bytes=0-") == true }.count == 2,
+                "the range form was not asked a second time, or more than that: \(requests)")
+        #expect(requests.filter { $0.method == "GET" && $0.range == nil }.count == 1, "\(requests)")
+        #expect(!requests.contains { $0.method == "HEAD" })
+        #expect(!requests.contains { $0.range == "bytes=0-1" })
+    }
+
+    // MARK: - What the host sees when the session does settle
+
+    @MainActor
+    @Test("isSequentialOrigin does not outlive the session it described")
+    func sequentialFlagClearsOnStop() throws {
+        let engine = try AetherEngine()
+        #expect(!engine.isSequentialOrigin)
+        engine.isSequentialOrigin = true
+        engine.stop()
+        #expect(!engine.isSequentialOrigin, "the next load would start out reporting a sequential origin")
+    }
+}
diff --git a/docs/api.md b/docs/api.md
index f0d30c44f..9c594edd8 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -678,6 +678,7 @@ suppressing `AVPlayerItemLegibleOutput` to keep the measurement running.
 | Symbol | Notes |
 | --- | --- |
 | `$isLive` | Mirrors `LoadOptions.isLive` for the session. |
+| `$isSequentialOrigin` | True while a VOD session is served as a sequential origin, declared (`LoadOptions.sequentialOrigin`) or found by the reader (the origin ignores `Range`, or refused the ranged open twice and served a plain GET, AE#693). The session plays from the start, so a `startPosition` given to `load()` was not honoured, and a seek lands only inside what `$residentRanges` already holds. A host that needs the position reopens the source or tells the user. Set during `load()`, cleared on stop. |
 | `seekToLiveEdge()` | `async`. |
 | `liveSourceReset` | The retune contract above. |
 | `liveResumeClamped`, `LiveResumeClamp` | A resume that found the playhead outside the window and moved it; see above. |

From 6f427d217001528befaf90b16a4bc20ae43f82c1 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sun, 4 Oct 2026 18:37:35 +0200
Subject: [PATCH 309/359] chore(release): prep 7.27.0 - one refusal at byte 0
 no longer settles a VOD forward-only

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                    | 4 ++++
 Examples/README.md                              | 2 +-
 README.md                                       | 6 +++---
 Sources/AetherEngine/AetherEngine+Version.swift | 2 +-
 4 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4253f3d7a..9c4cb51bf 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,10 @@ the public-API contract.
 
 ## [Unreleased]
 
+_Nothing yet._
+
+## [7.27.0] - 2026-10-04
+
 ### Fixed
 
 - **One refusal at byte 0 no longer settles a range-capable VOD forward-only for the whole session (#693).** An Xtream origin answered the ranged open of an episode with a 403 and the unranged GET right after it with a 200. Since #378 every 401/403/404/410 at byte 0 was read as the answer to the resource, so the source was served as a sequential origin: `startPosition` dropped and every seek past the downloaded window snapped back. The open now asks the same range once more before it settles: served, the source stays seekable; refused again, the #378 path runs unchanged. A source that refuses everything costs one request more and still fails typed with its status.
diff --git a/Examples/README.md b/Examples/README.md
index 4467fb107..d71acbf02 100644
--- a/Examples/README.md
+++ b/Examples/README.md
@@ -18,7 +18,7 @@ Three samples covering different audiences:
    ```
    https://github.com/superuser404notfound/AetherEngine
    ```
-   Dependency Rule: Up to Next Major Version, starting from `7.26.3`. Add the `AetherEngine` library product to your app target.
+   Dependency Rule: Up to Next Major Version, starting from `7.27.0`. Add the `AetherEngine` library product to your app target.
 
 3. **Drop the file in.** Replace the Xcode template's default `App.swift` (or whatever the generated `@main` file is called) with the contents of [`MinimalPlayerApp.swift`](MinimalPlayer/MinimalPlayerApp.swift). The file is self-contained: it defines both the `@main App` struct and the `ContentView`.
 
diff --git a/README.md b/README.md
index 18465fa71..7f9d90888 100644
--- a/README.md
+++ b/README.md
@@ -385,7 +385,7 @@ Subtitle cues land in raw source PTS; render the overlay against `player.sourceT
 Install via Swift Package Manager:
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.26.3")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.27.0")
 ```
 
 Three samples ship in `Examples/`:
@@ -632,10 +632,10 @@ Browse all of this as a searchable site at **[aetherengine.superuser404.de](http
 AetherEngine uses [Semantic Versioning](https://semver.org). The public API surface, every `public` declaration in `Sources/AetherEngine/`, is the stability contract. **Major** removes / renames public symbols or breaks adopters; **Minor** adds public API or codec / format support; **Patch** fixes bugs with no public API change. `internal` types are not part of the contract.
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.26.3")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.27.0")
 ```
 
-Pin to `.upToNextMinor(from: "7.26.3")` for stricter teams that prefer to opt into minor bumps explicitly.
+Pin to `.upToNextMinor(from: "7.27.0")` for stricter teams that prefer to opt into minor bumps explicitly.
 
 ## Requirements
 
diff --git a/Sources/AetherEngine/AetherEngine+Version.swift b/Sources/AetherEngine/AetherEngine+Version.swift
index 365d2fbd2..4576cf0f1 100644
--- a/Sources/AetherEngine/AetherEngine+Version.swift
+++ b/Sources/AetherEngine/AetherEngine+Version.swift
@@ -11,5 +11,5 @@ extension AetherEngine {
     ///
     /// Between releases, and in a consumer that pins an unreleased commit for a device test, this
     /// names the last PUBLISHED version the checkout descends from, not every patch in it.
-    public nonisolated static let version = "7.26.3"
+    public nonisolated static let version = "7.27.0"
 }

From 37b6901b5c95bea42817cbbccea9eb2204617369 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sun, 4 Oct 2026 19:13:15 +0200
Subject: [PATCH 310/359] test(network): a dropped exchange on a loaded runner
 no longer fails the token test

The 7.27.0 push run failed one request of four in the unprefixed-404 test with status 0
(no answer at all) while the requests around it on the same server were answered, and the
rerun passed. The socket helper now retries a 0 twice before it counts; 0 is never the
status under test.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../HLSLocalServerSessionTokenTests.swift           | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/Tests/AetherEngineTests/HLSLocalServerSessionTokenTests.swift b/Tests/AetherEngineTests/HLSLocalServerSessionTokenTests.swift
index 5c7072d7e..e01c39837 100644
--- a/Tests/AetherEngineTests/HLSLocalServerSessionTokenTests.swift
+++ b/Tests/AetherEngineTests/HLSLocalServerSessionTokenTests.swift
@@ -155,8 +155,19 @@ struct HLSLocalServerSessionTokenTests {
 
     // MARK: - Helpers
 
-    /// Status line of a plain GET, or 0 when the request could not be completed.
+    /// Status line of a plain GET, or 0 when the request could not be completed. A 0 is never the
+    /// answer under test, and a loaded CI runner has dropped one exchange mid-suite while the
+    /// requests around it on the same server were answered, so it is retried before it counts.
     private static func status(port: UInt16, path: String, extraHeaders: [String] = []) -> Int {
+        for attempt in 0..<3 {
+            if attempt > 0 { usleep(100_000) }
+            let code = singleStatus(port: port, path: path, extraHeaders: extraHeaders)
+            if code != 0 { return code }
+        }
+        return 0
+    }
+
+    private static func singleStatus(port: UInt16, path: String, extraHeaders: [String]) -> Int {
         let fd = socket(AF_INET, SOCK_STREAM, IPPROTO_TCP)
         guard fd >= 0 else { return 0 }
         defer { close(fd) }

From 04343a6a58efb39a80b05778fcf99fc85218c458 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sun, 4 Oct 2026 19:45:44 +0200
Subject: [PATCH 311/359] fix(audio): the audio-only host parks its clock at
 end of media (#694)

AudioPlaybackHost reported end of media while its synchronizer kept
rate 1, so currentTime grew past duration for as long as the session
stood. AE#374 closed the same defect on the software host; this host
never got it.

The end-of-media callback now carries the generation and the last
enqueued sample end. The park defers by the audio still queued (the
playthrough wait releases up to 0.25 s early, and pausing the
synchronizer stops the renderer too), then pauses the clock and
publishes rate 0. play() treats the park like the software host does
instead of restarting it as a stalled clock, and a seek clears it.

Covered end to end by Issue694AudioHostEndOfMediaParkTests: a 1 s WAV
decoded through the real host, clock rate 0 after the end and the
position standing still within 10 ms over 0.5 s.

Reported by ijuniorfu.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                  |  4 +-
 .../Audio/AudioPlaybackHost.swift             | 53 +++++++++++++++---
 ...Issue694AudioHostEndOfMediaParkTests.swift | 54 +++++++++++++++++++
 docs/api.md                                   |  2 +-
 4 files changed, 104 insertions(+), 9 deletions(-)
 create mode 100644 Tests/AetherEngineTests/Issue694AudioHostEndOfMediaParkTests.swift

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9c4cb51bf..f7018a0aa 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,7 +10,9 @@ the public-API contract.
 
 ## [Unreleased]
 
-_Nothing yet._
+### Fixed
+
+- **The audio-only path's clock parks at end of media instead of free-running past it (#694).** `AudioPlaybackHost` reported `.ended` while its synchronizer kept rate 1, so `currentTime` grew past `duration` for as long as the session stood. It now gets the AE#374 park the software host has: the queued tail plays out, then the clock stops on the last sample, and `play()` no longer restarts a clock the source stopped. Reported by ijuniorfu.
 
 ## [7.27.0] - 2026-10-04
 
diff --git a/Sources/AetherEngine/Audio/AudioPlaybackHost.swift b/Sources/AetherEngine/Audio/AudioPlaybackHost.swift
index e3c898017..c94a9ea76 100644
--- a/Sources/AetherEngine/Audio/AudioPlaybackHost.swift
+++ b/Sources/AetherEngine/Audio/AudioPlaybackHost.swift
@@ -96,6 +96,10 @@ final class AudioPlaybackHost {
     /// True between pause() and next play() so play() resumes the synchronizer rate (mirrors SoftwarePlaybackHost.pausedByHost).
     private var pausedByHost: Bool = false
 
+    /// #694: latched when end of media parks the clock (AE#374 on this host). Keeps `play()` from
+    /// restarting a clock the source stopped; a seek clears it.
+    private var didParkClockAtEnd = false
+
     /// Shared clock-armed latch (mirrors SoftwarePlaybackHost._clockArmed): demux loop arms once on first decoded
     /// packet; seek() anchors directly and sets this so the loop doesn't snap back to the stale initial anchor.
     nonisolated(unsafe) private var _clockArmed = false
@@ -205,9 +209,9 @@ final class AudioPlaybackHost {
             hostPaused: pausedByHost,
             clockArmed: clockArmed && demuxLoopStarted,
             synchronizerRate: audioOutput?.rate ?? 0,
-            // This host has neither a rebuffer that stops the clock nor an end-of-media park.
+            // This host has no rebuffer that stops the clock.
             rebuffering: false,
-            parkedAtEndOfMedia: false
+            parkedAtEndOfMedia: didParkClockAtEnd
         ) {
         case .resumeHostPause:
             pausedByHost = false
@@ -291,6 +295,7 @@ final class AudioPlaybackHost {
         // and it invalidates in-flight packets from the moment the seek starts rather than after it.
         bumpSeekGeneration()
         let generation = seekGeneration
+        didParkClockAtEnd = false
         // #292: inside another seek's window `isPlaying` is that seek's parked flag, not the transport's
         // intent. Inherit what it captured, and hand the same value on to whoever supersedes this one.
         let wasPlaying = SeekResumeIntent.resolve(isPlaying: isPlaying,
@@ -387,10 +392,12 @@ final class AudioPlaybackHost {
                 self?.failure = PlaybackErrorInfo(kind: .audioSessionFailed, message: msg)
             }
         }
-        let onEnd: @Sendable () -> Void = { [weak self] in
+        let onEnd: @Sendable (UInt64, Double) -> Void = { [weak self] generation, lastEnqueuedEnd in
             Task { @MainActor [weak self] in
-                self?.didReachEnd = true
-                self?.isPlaying = false
+                guard let self, self.seekGeneration == generation else { return }
+                self.parkClockAtEndOfMedia(lastEnqueuedEnd: lastEnqueuedEnd)
+                self.didReachEnd = true
+                self.isPlaying = false
             }
         }
 
@@ -432,7 +439,7 @@ final class AudioPlaybackHost {
         onClockAnchored: @Sendable (Double) -> Void,
         seekGeneration: @Sendable () -> UInt64,
         onError: @Sendable (String) -> Void,
-        onEnd: @Sendable () -> Void
+        onEnd: @Sendable (UInt64, Double) -> Void
     ) {
         // Clock-armed latch is SHARED with the host: anchor the clock exactly once on the first decoded packet.
         // seekClock is NOT idempotent (re-sets rate+time), so per-packet calls would snap the clock back ~47x/sec
@@ -537,7 +544,7 @@ final class AudioPlaybackHost {
                 }
                 if seekedAway { return true }
                 if seekGeneration() != seenSeekGeneration { return true }
-                onEnd()
+                onEnd(seenSeekGeneration, lastEnqueuedEnd)
                 return false
             }
 
@@ -604,6 +611,38 @@ final class AudioPlaybackHost {
         }
     }
 
+    /// #694: stop the master clock on the last sample instead of letting it free-run past the end
+    /// (AE#374 on the software host). The playthrough wait in the demux loop releases up to 0.25 s
+    /// before the last enqueued sample, so the park is deferred by what is still queued: parking stops
+    /// the renderer too and an immediate park would cut that tail.
+    private func parkClockAtEndOfMedia(lastEnqueuedEnd: Double) {
+        guard !didParkClockAtEnd else { return }
+        didParkClockAtEnd = true
+        guard clockArmed, let aOut = audioOutput else { return }
+        let tail = SoftwareEndOfMediaClock.tailPlayoutSeconds(
+            clockSeconds: aOut.currentTimeSeconds,
+            lastAudioPts: lastEnqueuedEnd
+        )
+        guard tail > 0 else { return parkClockNow() }
+        let generation = seekGeneration
+        Task { @MainActor [weak self] in
+            try? await Task.sleep(nanoseconds: UInt64(tail * 1_000_000_000))
+            guard let self, self.seekGeneration == generation, self.didParkClockAtEnd else { return }
+            self.parkClockNow()
+        }
+    }
+
+    private func parkClockNow() {
+        guard !stopRequested, let aOut = audioOutput else { return }
+        aOut.pause()
+        rate = 0
+        EngineLog.emit(
+            "[AudioHost] end of media: clock parked at "
+            + "\(String(format: "%.3f", aOut.currentTimeSeconds))s",
+            category: .swPlayback
+        )
+    }
+
     // MARK: - Time updates
 
     private func startTimeUpdates() {
diff --git a/Tests/AetherEngineTests/Issue694AudioHostEndOfMediaParkTests.swift b/Tests/AetherEngineTests/Issue694AudioHostEndOfMediaParkTests.swift
new file mode 100644
index 000000000..7714cf65b
--- /dev/null
+++ b/Tests/AetherEngineTests/Issue694AudioHostEndOfMediaParkTests.swift
@@ -0,0 +1,54 @@
+import Testing
+import Foundation
+@testable import AetherEngine
+
+/// #694: the audio-only host reported end of media while its synchronizer kept rate 1, so
+/// `currentTime` walked past `duration` without bound. AE#374 closed the same defect on the software
+/// host; this pins it on the audio-only one, end to end against a real decode.
+@Suite("Audio host parks its clock at end of media (#694)")
+struct Issue694AudioHostEndOfMediaParkTests {
+
+    @MainActor
+    @Test("after end of media the clock stands still on the last sample")
+    func clockParksOnTheLastSample() async throws {
+        let host = AudioPlaybackHost()
+        let demuxer = Demuxer()
+        try demuxer.open(reader: DataIOReader(data: makeWAV(seconds: 1)))
+        try await host.load(demuxer: demuxer, startPosition: nil, audioSourceStreamIndex: nil)
+        defer { host.stop() }
+        host.play()
+
+        let deadline = Date().addingTimeInterval(8)
+        while !host.didReachEnd, Date() < deadline {
+            try await Task.sleep(nanoseconds: 50_000_000)
+        }
+        #expect(host.didReachEnd)
+
+        let parkDeadline = Date().addingTimeInterval(2)
+        while host.clockRateForTesting != 0, Date() < parkDeadline {
+            try await Task.sleep(nanoseconds: 20_000_000)
+        }
+        #expect(host.clockRateForTesting == 0)
+        #expect(host.rate == 0)
+
+        let first = try #require(host.clockSecondsForTesting)
+        try await Task.sleep(nanoseconds: 500_000_000)
+        let second = try #require(host.clockSecondsForTesting)
+        #expect(abs(second - first) < 0.01)
+        #expect(abs(first - 1.0) < 0.1)
+    }
+
+    private func makeWAV(seconds: Double) -> Data {
+        let sampleRate = 48_000, channels = 2
+        let pcm = Data(count: Int(Double(sampleRate) * seconds) * channels * 2)
+        var d = Data()
+        func str(_ s: String) { d.append(s.data(using: .ascii)!) }
+        func u32(_ v: UInt32) { withUnsafeBytes(of: v.littleEndian) { d.append(contentsOf: $0) } }
+        func u16(_ v: UInt16) { withUnsafeBytes(of: v.littleEndian) { d.append(contentsOf: $0) } }
+        str("RIFF"); u32(UInt32(36 + pcm.count)); str("WAVE")
+        str("fmt "); u32(16); u16(1); u16(UInt16(channels)); u32(UInt32(sampleRate))
+        u32(UInt32(sampleRate * channels * 2)); u16(UInt16(channels * 2)); u16(16)
+        str("data"); u32(UInt32(pcm.count)); d.append(pcm)
+        return d
+    }
+}
diff --git a/docs/api.md b/docs/api.md
index 9c594edd8..e184183b7 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -77,7 +77,7 @@ It is assigned before `state`, so a `$state` sink reads this failure's own info
 
 To replay, call `load(...)` again. The engine keeps `.ended` terminal deliberately: a play press racing a host's end card must not silently restart a finished session (#63/#164). A VOD **parked at its final frame** without having ended (scrubbed there, paused there) is the other case and does resume: `play()` rewinds to the start first.
 
-The clock stops with it, on both backends: `clock.currentTime` and `clock.sourceTime` settle on the last sample and stay there, so a progress bar bound to them holds at the end instead of walking past `duration`. Through 6.28.0 the software path was the exception: its master clock kept its rate past end of media, so a session left standing published a position that grew without bound (20.13 s on a 12.0 s source after 20 s, against 11.97 s from a native session on the same file). A host reading the clock after `.ended` on one of those builds is reading that, not a drifting session (AE#374).
+The clock stops with it, on both backends: `clock.currentTime` and `clock.sourceTime` settle on the last sample and stay there, so a progress bar bound to them holds at the end instead of walking past `duration`. Through 6.28.0 the software path was the exception: its master clock kept its rate past end of media, so a session left standing published a position that grew without bound (20.13 s on a 12.0 s source after 20 s, against 11.97 s from a native session on the same file). A host reading the clock after `.ended` on one of those builds is reading that, not a drifting session (AE#374). The audio-only path (a source without a video track decoded through FFmpeg) had the same defect through 7.27.0 and parks the same way since (AE#694).
 
 ### Live: the retune request
 

From d9a0ce87e72ac90e5b07c96cc85b4f63f5b6bed2 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sun, 4 Oct 2026 19:56:10 +0200
Subject: [PATCH 312/359] chore(release): prep 7.27.1 - the audio-only clock
 parks at end of media

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                    | 4 ++++
 Examples/README.md                              | 2 +-
 README.md                                       | 6 +++---
 Sources/AetherEngine/AetherEngine+Version.swift | 2 +-
 4 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f7018a0aa..86df725ae 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,10 @@ the public-API contract.
 
 ## [Unreleased]
 
+_Nothing yet._
+
+## [7.27.1] - 2026-10-04
+
 ### Fixed
 
 - **The audio-only path's clock parks at end of media instead of free-running past it (#694).** `AudioPlaybackHost` reported `.ended` while its synchronizer kept rate 1, so `currentTime` grew past `duration` for as long as the session stood. It now gets the AE#374 park the software host has: the queued tail plays out, then the clock stops on the last sample, and `play()` no longer restarts a clock the source stopped. Reported by ijuniorfu.
diff --git a/Examples/README.md b/Examples/README.md
index d71acbf02..4060b5751 100644
--- a/Examples/README.md
+++ b/Examples/README.md
@@ -18,7 +18,7 @@ Three samples covering different audiences:
    ```
    https://github.com/superuser404notfound/AetherEngine
    ```
-   Dependency Rule: Up to Next Major Version, starting from `7.27.0`. Add the `AetherEngine` library product to your app target.
+   Dependency Rule: Up to Next Major Version, starting from `7.27.1`. Add the `AetherEngine` library product to your app target.
 
 3. **Drop the file in.** Replace the Xcode template's default `App.swift` (or whatever the generated `@main` file is called) with the contents of [`MinimalPlayerApp.swift`](MinimalPlayer/MinimalPlayerApp.swift). The file is self-contained: it defines both the `@main App` struct and the `ContentView`.
 
diff --git a/README.md b/README.md
index 7f9d90888..64c5b0cb2 100644
--- a/README.md
+++ b/README.md
@@ -385,7 +385,7 @@ Subtitle cues land in raw source PTS; render the overlay against `player.sourceT
 Install via Swift Package Manager:
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.27.0")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.27.1")
 ```
 
 Three samples ship in `Examples/`:
@@ -632,10 +632,10 @@ Browse all of this as a searchable site at **[aetherengine.superuser404.de](http
 AetherEngine uses [Semantic Versioning](https://semver.org). The public API surface, every `public` declaration in `Sources/AetherEngine/`, is the stability contract. **Major** removes / renames public symbols or breaks adopters; **Minor** adds public API or codec / format support; **Patch** fixes bugs with no public API change. `internal` types are not part of the contract.
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.27.0")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.27.1")
 ```
 
-Pin to `.upToNextMinor(from: "7.27.0")` for stricter teams that prefer to opt into minor bumps explicitly.
+Pin to `.upToNextMinor(from: "7.27.1")` for stricter teams that prefer to opt into minor bumps explicitly.
 
 ## Requirements
 
diff --git a/Sources/AetherEngine/AetherEngine+Version.swift b/Sources/AetherEngine/AetherEngine+Version.swift
index 4576cf0f1..616e1698e 100644
--- a/Sources/AetherEngine/AetherEngine+Version.swift
+++ b/Sources/AetherEngine/AetherEngine+Version.swift
@@ -11,5 +11,5 @@ extension AetherEngine {
     ///
     /// Between releases, and in a consumer that pins an unreleased commit for a device test, this
     /// names the last PUBLISHED version the checkout descends from, not every patch in it.
-    public nonisolated static let version = "7.27.0"
+    public nonisolated static let version = "7.27.1"
 }

From 38b9eb71176ad6819b0d76742c1946a7930e0903 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sun, 4 Oct 2026 20:59:52 +0200
Subject: [PATCH 313/359] test(load): the cancelled-load ceiling is derived
 from the timeout it guards against

The 7.27.1 push run failed the live-ingest cancel test at 1.99 s against a
1.5 s bound, with the outcome already .cancelled. 1.5 s was a guess at the
quiet-machine time. What the bound has to separate is "the cancel ended
the load" from "a timeout ended it", and the shortest timeout a silent
origin can end on at open is 5 s, so the ceiling is now 4 s. The wait
runs to 30 s, so a slow end reports its real duration.

Counter-check: with the task cancellation handler disabled the test
fails at 9.8 s (the ingest's 10 s request timeout), and the outcome
still reads .cancelled, so the ceiling is the only assertion that
catches that regression.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../CancellableLoadTests.swift                | 23 ++++++++++++-------
 1 file changed, 15 insertions(+), 8 deletions(-)

diff --git a/Tests/AetherEngineTests/CancellableLoadTests.swift b/Tests/AetherEngineTests/CancellableLoadTests.swift
index d081a50bc..83f583f6f 100644
--- a/Tests/AetherEngineTests/CancellableLoadTests.swift
+++ b/Tests/AetherEngineTests/CancellableLoadTests.swift
@@ -62,9 +62,16 @@ struct CancellableLoadTests {
         return (task, box)
     }
 
-    /// Cancels after the load has been held a moment, and reports whether it ended within `budget`.
+    /// How long a cancelled load may take to end. What it guards is the wait it replaced: a silent
+    /// origin is only given up on by a timeout, the shortest at open being the 5 s HEAD probe and
+    /// the ingest's 10 s request timeout, so any ceiling below 5 s tells "the cancel ended it" from
+    /// "a timeout ended it". 1.5 s was a guess at the quiet-machine time and a loaded runner took 2 s.
+    static let ceiling: Duration = .seconds(4)
+
+    /// Cancels after the load has been held a moment and reports how long it took to end. The wait
+    /// runs well past `ceiling`, so a slow end reports its real duration instead of the poll's.
     private static func cancelAndTime(_ task: Task<Void, Never>, _ box: OutcomeBox,
-                                      budget: Duration = .milliseconds(1500)) async throws -> Duration {
+                                      budget: Duration = .seconds(30)) async throws -> Duration {
         try await Task.sleep(for: .milliseconds(200))
         let clock = ContinuousClock()
         let cancelledAt = clock.now
@@ -85,7 +92,7 @@ struct CancellableLoadTests {
 
         let elapsed = try await Self.cancelAndTime(task, box)
         #expect(box.outcome == .cancelled, "ended \(String(describing: box.outcome)) after \(elapsed)")
-        #expect(elapsed < .milliseconds(1500))
+        #expect(elapsed < Self.ceiling)
         #expect(reader.wasReleasedByEngine)
         await task.value
         #expect(engine.state == .idle)
@@ -105,7 +112,7 @@ struct CancellableLoadTests {
 
         let elapsed = try await Self.cancelAndTime(task, box)
         #expect(box.outcome == .cancelled, "ended \(String(describing: box.outcome)) after \(elapsed)")
-        #expect(elapsed < .milliseconds(1500))
+        #expect(elapsed < Self.ceiling)
         origin.stop()
         await task.value
         #expect(engine.state == .idle)
@@ -126,7 +133,7 @@ struct CancellableLoadTests {
 
         let elapsed = try await Self.cancelAndTime(task, box)
         #expect(box.outcome == .cancelled, "ended \(String(describing: box.outcome)) after \(elapsed)")
-        #expect(elapsed < .milliseconds(1500))
+        #expect(elapsed < Self.ceiling)
         origin.stop()
         await task.value
         #expect(engine.state == .idle)
@@ -147,7 +154,7 @@ struct CancellableLoadTests {
 
         let elapsed = try await Self.cancelAndTime(task, box)
         #expect(box.outcome == .cancelled, "ended \(String(describing: box.outcome)) after \(elapsed)")
-        #expect(elapsed < .milliseconds(1500))
+        #expect(elapsed < Self.ceiling)
         origin.stop()
         await task.value
         #expect(engine.state == .idle)
@@ -377,7 +384,7 @@ struct CancellableLoadTests {
 
         let elapsed = try await Self.cancelAndTime(hostLoad, hostBox)
         #expect(hostBox.outcome == .cancelled, "ended \(String(describing: hostBox.outcome)) after \(elapsed)")
-        #expect(elapsed < .milliseconds(1500))
+        #expect(elapsed < Self.ceiling)
         #expect(reader.isClosed)
         await #expect(throws: CancellationError.self) { try await rebuild.value }
         await hostLoad.value
@@ -409,7 +416,7 @@ struct CancellableLoadTests {
 
         let elapsed = try await Self.cancelAndTime(hostLoad, hostBox)
         #expect(hostBox.outcome == .cancelled, "ended \(String(describing: hostBox.outcome)) after \(elapsed)")
-        #expect(elapsed < .milliseconds(1500))
+        #expect(elapsed < Self.ceiling)
         await #expect(throws: CancellationError.self) { try await rebuild.value }
         origin.stop()
         await hostLoad.value

From fb3b6327aed2446e8ff7850e673439daeff56efa Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sun, 4 Oct 2026 20:59:52 +0200
Subject: [PATCH 314/359] fix(audio): an end-of-media park that runs late still
 stops on the last sample (#694)

The park is deferred by the queued audio tail, then paused the clock
wherever it stood when the task got the main actor. On a busy main actor
that is past the end: the 7.27.1 CI rerun parked a 1.0 s source at
1.149 s. Both the audio-only and the software host now pause no later
than the point the deferral aimed at (the last enqueued sample, or
clock + tail on the software host).

The #694 end-to-end test now holds the main actor for 0.5 s after the
end, which parks at 1.29 s without the clamp and on 1.0 s with it.
The clamp itself is a pure function, pinned separately.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                        |  4 +++-
 Sources/AetherEngine/Audio/AudioOutput.swift        | 11 +++++++++++
 Sources/AetherEngine/Audio/AudioPlaybackHost.swift  | 11 ++++++-----
 .../Native/SoftwareEndOfMediaClock.swift            |  7 +++++++
 .../AetherEngine/Native/SoftwarePlaybackHost.swift  |  8 +++++---
 .../Issue694AudioHostEndOfMediaParkTests.swift      | 13 ++++++++++++-
 6 files changed, 44 insertions(+), 10 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 86df725ae..89ff5e398 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,7 +10,9 @@ the public-API contract.
 
 ## [Unreleased]
 
-_Nothing yet._
+### Fixed
+
+- **An end-of-media park that runs late still stops the clock on the last sample (#694).** The park is deferred by the queued audio tail and ran wherever the clock stood when its task got the main actor, so a busy main actor parked it past the end (measured: 1.149 s on a 1.0 s source). Both the audio-only and the software host now put the clock back on the point the deferral aimed at.
 
 ## [7.27.1] - 2026-10-04
 
diff --git a/Sources/AetherEngine/Audio/AudioOutput.swift b/Sources/AetherEngine/Audio/AudioOutput.swift
index 9ec1debab..d6057603b 100644
--- a/Sources/AetherEngine/Audio/AudioOutput.swift
+++ b/Sources/AetherEngine/Audio/AudioOutput.swift
@@ -158,6 +158,17 @@ final class AudioOutput: @unchecked Sendable {
         synchronizer.setRate(0.0, time: at)
     }
 
+    /// Pause the master clock, at `latest` if it has already run past it. A park deferred to the last
+    /// sample runs whenever its task is scheduled, and on a starved main actor that is after the clock
+    /// has walked on (#694: 1.149 s on a 1.0 s source on a CI runner).
+    func pause(notAfter latest: Double) {
+        let now = synchronizer.currentTime()
+        let seconds = SoftwareEndOfMediaClock.parkSeconds(clockSeconds: CMTimeGetSeconds(now), notAfter: latest)
+        let at = seconds.map { CMTime(seconds: $0, preferredTimescale: 90000) } ?? now
+        EngineLog.emit("[AudioOutput] pause at t=\(String(format: "%.3f", at.seconds))", category: .swPlayback)
+        synchronizer.setRate(0.0, time: at)
+    }
+
     /// AE#464: set the audio presentation offset. Positive presents audio later than video, which on
     /// this path means stamping its samples further ahead on the synchronizer's timeline: at clock
     /// time t the renderer then plays what was recorded at t minus the offset, while the video layer
diff --git a/Sources/AetherEngine/Audio/AudioPlaybackHost.swift b/Sources/AetherEngine/Audio/AudioPlaybackHost.swift
index c94a9ea76..c07adeb47 100644
--- a/Sources/AetherEngine/Audio/AudioPlaybackHost.swift
+++ b/Sources/AetherEngine/Audio/AudioPlaybackHost.swift
@@ -614,7 +614,8 @@ final class AudioPlaybackHost {
     /// #694: stop the master clock on the last sample instead of letting it free-run past the end
     /// (AE#374 on the software host). The playthrough wait in the demux loop releases up to 0.25 s
     /// before the last enqueued sample, so the park is deferred by what is still queued: parking stops
-    /// the renderer too and an immediate park would cut that tail.
+    /// the renderer too and an immediate park would cut that tail. Either way the clock stops on the
+    /// last sample, not where it stands when the park runs.
     private func parkClockAtEndOfMedia(lastEnqueuedEnd: Double) {
         guard !didParkClockAtEnd else { return }
         didParkClockAtEnd = true
@@ -623,18 +624,18 @@ final class AudioPlaybackHost {
             clockSeconds: aOut.currentTimeSeconds,
             lastAudioPts: lastEnqueuedEnd
         )
-        guard tail > 0 else { return parkClockNow() }
+        guard tail > 0 else { return parkClockNow(notAfter: lastEnqueuedEnd) }
         let generation = seekGeneration
         Task { @MainActor [weak self] in
             try? await Task.sleep(nanoseconds: UInt64(tail * 1_000_000_000))
             guard let self, self.seekGeneration == generation, self.didParkClockAtEnd else { return }
-            self.parkClockNow()
+            self.parkClockNow(notAfter: lastEnqueuedEnd)
         }
     }
 
-    private func parkClockNow() {
+    private func parkClockNow(notAfter latest: Double) {
         guard !stopRequested, let aOut = audioOutput else { return }
-        aOut.pause()
+        aOut.pause(notAfter: latest)
         rate = 0
         EngineLog.emit(
             "[AudioHost] end of media: clock parked at "
diff --git a/Sources/AetherEngine/Native/SoftwareEndOfMediaClock.swift b/Sources/AetherEngine/Native/SoftwareEndOfMediaClock.swift
index 596ea77cf..bb0b1670f 100644
--- a/Sources/AetherEngine/Native/SoftwareEndOfMediaClock.swift
+++ b/Sources/AetherEngine/Native/SoftwareEndOfMediaClock.swift
@@ -26,4 +26,11 @@ enum SoftwareEndOfMediaClock {
         guard remaining > 0 else { return 0 }
         return min(remaining, maxTailPlayoutSeconds)
     }
+
+    /// Where a late park puts the clock: back on `latest` when the clock has run past it, nil (park
+    /// where it stands) otherwise or when either value is unusable.
+    static func parkSeconds(clockSeconds: Double, notAfter latest: Double) -> Double? {
+        guard clockSeconds.isFinite, latest.isFinite, clockSeconds > latest else { return nil }
+        return latest
+    }
 }
diff --git a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
index aae095d69..f1e07941d 100644
--- a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
+++ b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
@@ -1231,17 +1231,19 @@ final class SoftwarePlaybackHost {
             lastAudioPts: demuxDiag.snapshot.lastAudioPts
         )
         guard tail > 0 else { return parkClockNow() }
+        // The deferral aims at the end of the queued tail; a task that runs late must not park past it.
+        let target = aOut.currentTimeSeconds + tail
         let generation = seekGeneration
         Task { @MainActor [weak self] in
             try? await Task.sleep(nanoseconds: UInt64(tail * 1_000_000_000))
             guard let self, self.admitsRead(generation: generation) else { return }
-            self.parkClockNow()
+            self.parkClockNow(notAfter: target)
         }
     }
 
-    private func parkClockNow() {
+    private func parkClockNow(notAfter latest: Double = .infinity) {
         guard !stopRequested, let aOut = audioOutput else { return }
-        aOut.pause()
+        aOut.pause(notAfter: latest)
         rate = 0
         EngineLog.emit(
             "[SWHost] end of media: clock parked at "
diff --git a/Tests/AetherEngineTests/Issue694AudioHostEndOfMediaParkTests.swift b/Tests/AetherEngineTests/Issue694AudioHostEndOfMediaParkTests.swift
index 7714cf65b..d73d833df 100644
--- a/Tests/AetherEngineTests/Issue694AudioHostEndOfMediaParkTests.swift
+++ b/Tests/AetherEngineTests/Issue694AudioHostEndOfMediaParkTests.swift
@@ -9,7 +9,7 @@ import Foundation
 struct Issue694AudioHostEndOfMediaParkTests {
 
     @MainActor
-    @Test("after end of media the clock stands still on the last sample")
+    @Test("after end of media the clock stands still on the last sample, even when the park runs late")
     func clockParksOnTheLastSample() async throws {
         let host = AudioPlaybackHost()
         let demuxer = Demuxer()
@@ -23,6 +23,9 @@ struct Issue694AudioHostEndOfMediaParkTests {
             try await Task.sleep(nanoseconds: 50_000_000)
         }
         #expect(host.didReachEnd)
+        // What a loaded runner does to the deferred park (CI: parked at 1.149 s): hold the main actor
+        // past the queued tail, so the park runs after the clock has walked on.
+        usleep(500_000)
 
         let parkDeadline = Date().addingTimeInterval(2)
         while host.clockRateForTesting != 0, Date() < parkDeadline {
@@ -38,6 +41,14 @@ struct Issue694AudioHostEndOfMediaParkTests {
         #expect(abs(first - 1.0) < 0.1)
     }
 
+    @Test("a park that runs after the clock passed its target puts it back on the target")
+    func lateParkLandsOnTheTarget() {
+        #expect(SoftwareEndOfMediaClock.parkSeconds(clockSeconds: 1.149, notAfter: 1.0) == 1.0)
+        #expect(SoftwareEndOfMediaClock.parkSeconds(clockSeconds: 0.98, notAfter: 1.0) == nil)
+        #expect(SoftwareEndOfMediaClock.parkSeconds(clockSeconds: 1.149, notAfter: .infinity) == nil)
+        #expect(SoftwareEndOfMediaClock.parkSeconds(clockSeconds: .nan, notAfter: 1.0) == nil)
+    }
+
     private func makeWAV(seconds: Double) -> Data {
         let sampleRate = 48_000, channels = 2
         let pcm = Data(count: Int(Double(sampleRate) * seconds) * channels * 2)

From 663e4ef0d2f03c6ba90cc63b13daf97388429841 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Sun, 4 Oct 2026 23:04:04 +0200
Subject: [PATCH 315/359] diag(audio): the software path names its route, its
 audio lead on live, and its renderer state (#395)

A live MPEG-1 Layer II channel on the software route was silent over an AirPlay 2
receiver and audible over HDMI, and the two logs read the same. Three gaps made that so:

- The software host never wrote the audio route. It now writes one at session start,
  with the route's output latency, through the formatter the native host's line uses
  (AudioRouteDescription). A process-wide line follows every route change, since a
  mid-session switch leaves the start line describing a route that is gone.
- `aLead` read `-` on every live line, because its marker was the pacing input and only
  existed where audio is decoupled. The diagnostic line now has its own marker, written
  on every route under the generation the buffer was produced under (AE#479). Pacing is
  unchanged.
- The audio renderer's status and error were only ever logged in DEBUG builds. `[SWDiag]`
  carries `aRend=status/sufficient/error` now.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 Sources/AetherEngine/AetherEngine.swift       |  4 ++
 Sources/AetherEngine/Audio/AudioOutput.swift  | 17 ++++++++
 .../Audio/AudioRouteDescription.swift         | 43 +++++++++++++++++++
 .../Native/NativeAVPlayerHost.swift           | 24 ++---------
 .../Native/SoftwarePlaybackHost.swift         | 33 +++++++++++---
 5 files changed, 94 insertions(+), 27 deletions(-)
 create mode 100644 Sources/AetherEngine/Audio/AudioRouteDescription.swift

diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index 3ae52d5aa..e72181896 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -7451,6 +7451,10 @@ public final class AetherEngine: ObservableObject {
             lifecycleObservers.append(observer)
         }
 
+        #if os(iOS) || os(tvOS)
+        AudioRouteDescription.changeLogger
+        #endif
+
         #if os(iOS)
         let routeObserver = nc.addObserver(
             forName: AVAudioSession.routeChangeNotification,
diff --git a/Sources/AetherEngine/Audio/AudioOutput.swift b/Sources/AetherEngine/Audio/AudioOutput.swift
index d6057603b..43fa2915b 100644
--- a/Sources/AetherEngine/Audio/AudioOutput.swift
+++ b/Sources/AetherEngine/Audio/AudioOutput.swift
@@ -56,6 +56,23 @@ final class AudioOutput: @unchecked Sendable {
         synchronizer.rate
     }
 
+    /// AE#395: the renderer's own view of its queue, for the diagnostic line: `status/sufficient/error`.
+    /// A session that is silent on one route while its clock runs at 1.00 has nothing else that could
+    /// say whether the renderer is playing what it was given, and the renderer error was only ever
+    /// logged in DEBUG builds.
+    var diagRendererState: String {
+        let status: String
+        switch renderer.status {
+        case .rendering: status = "rendering"
+        case .failed: status = "failed"
+        case .unknown: status = "unknown"
+        @unknown default: status = "?"
+        }
+        let sufficient = renderer.hasSufficientMediaDataForReliablePlaybackStart ? "y" : "n"
+        let error = (renderer.error as NSError?).map { "\($0.domain)/\($0.code)" } ?? "-"
+        return "\(status)/\(sufficient)/\(error)"
+    }
+
     /// AE#549: how often this renderer has flushed itself, for the diagnostic line.
     var automaticFlushCount: Int {
         lock.lock()
diff --git a/Sources/AetherEngine/Audio/AudioRouteDescription.swift b/Sources/AetherEngine/Audio/AudioRouteDescription.swift
new file mode 100644
index 000000000..b1307a20c
--- /dev/null
+++ b/Sources/AetherEngine/Audio/AudioRouteDescription.swift
@@ -0,0 +1,43 @@
+import Foundation
+import AVFoundation
+
+/// The audio route as one log fragment, shared by every host that writes a route line, so the native and
+/// the software path describe the same route in the same words and a diff between their logs is a diff
+/// of routes, not of formats.
+enum AudioRouteDescription {
+
+    /// `output=… preferred=… max=… ports=[name[type, ch=n], …] latency=…ms io=…ms`, or nil where there is
+    /// no `AVAudioSession`. The output latency is the field AE#395 needs: a buffered AirPlay route delays
+    /// sound by seconds where HDMI delays it by milliseconds, and a feed that is fine on one is late on
+    /// the other.
+    static func current() -> String? {
+        #if os(iOS) || os(tvOS)
+        let session = AVAudioSession.sharedInstance()
+        let ports = session.currentRoute.outputs.map { port in
+            "\(port.portName)[\(port.portType.rawValue), ch=\(port.channels?.count ?? -1)]"
+        }.joined(separator: ", ")
+        return "output=\(session.outputNumberOfChannels) preferred=\(session.preferredOutputNumberOfChannels) "
+            + "max=\(session.maximumOutputNumberOfChannels) ports=[\(ports)] "
+            + "latency=\(String(format: "%.0f", session.outputLatency * 1000))ms "
+            + "io=\(String(format: "%.1f", session.ioBufferDuration * 1000))ms"
+        #else
+        return nil
+        #endif
+    }
+
+    #if os(iOS) || os(tvOS)
+    /// AE#395: one line per route change, for the process rather than per engine (a multiview runs several).
+    /// A change mid-session leaves the session's start line describing a route that is gone, and a user
+    /// switching output to test a theory is exactly that case. Installed on first touch, never removed.
+    static let changeLogger: Void = {
+        _ = NotificationCenter.default.addObserver(
+            forName: AVAudioSession.routeChangeNotification,
+            object: AVAudioSession.sharedInstance(), queue: nil
+        ) { note in
+            let reason = (note.userInfo?[AVAudioSessionRouteChangeReasonKey] as? UInt).map(String.init) ?? "?"
+            guard let route = current() else { return }
+            EngineLog.emit("[AetherEngine] audioRoute changed reason=\(reason) \(route)", category: .engine)
+        }
+    }()
+    #endif
+}
diff --git a/Sources/AetherEngine/Native/NativeAVPlayerHost.swift b/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
index 18c8417cf..cc00d31d8 100644
--- a/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
+++ b/Sources/AetherEngine/Native/NativeAVPlayerHost.swift
@@ -2742,27 +2742,9 @@ final class NativeAVPlayerHost {
 
     /// Dump audio route channel capability post-load (route renegotiates on asset load; pre-load poll is stale). outputNumberOfChannels is the actual LPCM limit; EAC3/Atmos bypasses it via bitstream tunnel.
     nonisolated private static func dumpAudioRoute(sid: Int, phase: String) {
-        #if os(iOS) || os(tvOS)
-        let session = AVAudioSession.sharedInstance()
-        let out = session.outputNumberOfChannels
-        let pref = session.preferredOutputNumberOfChannels
-        let maxCh = session.maximumOutputNumberOfChannels
-        let route = session.currentRoute
-        let outputDescs = route.outputs.map { port in
-            let portName = port.portName
-            let portType = port.portType.rawValue
-            let nChannels = port.channels?.count ?? -1
-            return "\(portName)[\(portType), ch=\(nChannels)]"
-        }.joined(separator: ", ")
-        EngineLog.emit(
-            "[NativeAVPlayerHost] #\(sid) audioRoute output=\(out) preferred=\(pref) max=\(maxCh) "
-            + "ports=[\(outputDescs)] "
-            // AE#684: what the route says it delays sound by, per item, beside the item's start.
-            + "latency=\(String(format: "%.0f", session.outputLatency * 1000))ms "
-            + "io=\(String(format: "%.1f", session.ioBufferDuration * 1000))ms (\(phase))",
-            category: .engine
-        )
-        #endif
+        // AE#684: the route's own latency rides on the line, per item, beside the item's start.
+        guard let route = AudioRouteDescription.current() else { return }
+        EngineLog.emit("[NativeAVPlayerHost] #\(sid) audioRoute \(route) (\(phase))", category: .engine)
     }
 
     /// Read sr/ch/bits/layoutTag from CMAudioFormatDescription. Layout tag diagnoses where downmix occurs: unknown/stereo tag = AVPlayer parse layer; correct 7.1 tag = route/soundbar layer.
diff --git a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
index f1e07941d..47c9dd64a 100644
--- a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
+++ b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
@@ -982,6 +982,12 @@ final class SoftwarePlaybackHost {
         self.audioOutput = AudioOutput()
         self.audioOutput?.volume = volume
         self.audioOutput?.setPresentationOffset(seconds: audioDelaySeconds)   // AE#464
+        // AE#395: the route this session plays into, the counterpart of the native host's line. Without
+        // it a silent software session on a long-latency route and an audible one on HDMI log the same.
+        if let route = AudioRouteDescription.current() {
+            EngineLog.emit("[SoftwarePlaybackHost] audioRoute \(route) (session start, live=\(isLive))",
+                           category: .swPlayback)
+        }
 
         // Reset the live feeder state for the new session.
         resetFeederState()
@@ -2490,6 +2496,12 @@ final class SoftwarePlaybackHost {
         var everHadLead = false
         var parkedSeekGeneration = seekGeneration()
         let decoupleAudio = !isLive && audioDecoder != nil && audioOutput != nil
+        // AE#395: the diagnostic line's audio marker, written on every route. `lastEnqueuedAudioPtsSec`
+        // is the pacing input and only exists where audio is decoupled, so a live session's line read
+        // `aLead=-` throughout, on exactly the sessions where the lead decides whether a long-latency
+        // route plays anything. The generation is the one the buffer was produced under (AE#479).
+        var diagAudioPtsSec = Double.nan
+        var diagAudioPtsGeneration = parkedSeekGeneration
 
         func freeParkedVideo() {
             for p in parkedVideo {
@@ -2596,9 +2608,9 @@ final class SoftwarePlaybackHost {
                 releaseRebufferHold("the renderer needs a running clock to take parked video")
                 armFromParkedVideoIfStuck()
                 drainParkedVideoNonblocking()
-                diag?.update(lastAudioPts: lastEnqueuedAudioPtsSec,
+                diag?.update(lastAudioPts: diagAudioPtsSec,
                              parked: parkedVideo.count, rebuffering: rebuffering,
-                             generation: parkedSeekGeneration)
+                             generation: diagAudioPtsGeneration)
                 if stillWaiting() {
                     // The condition is broadcast on play, stop, background, seek-settled and feed-cursor
                     // changes, so those cut the wait short where the sleep used to ride them out.
@@ -2708,6 +2720,8 @@ final class SoftwarePlaybackHost {
                     parkedSeekGeneration = gen
                     freeParkedVideo()
                     lastEnqueuedAudioPtsSec = .nan
+                    diagAudioPtsSec = .nan
+                    diagAudioPtsGeneration = gen
                     rebuffering = false
                     // The lead is zero again after a seek, so the latch has to earn itself back:
                     // keeping it set pauses the clock for a rebuffer on the first post-seek check.
@@ -3010,9 +3024,13 @@ final class SoftwarePlaybackHost {
                     }
                     tapSink?(buf)   // #95: mirrored behind the accept, so a refused buffer is not transcribed
                 }
-                if decoupleAudio, let last = buffers.last {
+                if let last = buffers.last {
                     let pts = CMSampleBufferGetPresentationTimeStamp(last)
-                    if pts.isValid { lastEnqueuedAudioPtsSec = pts.seconds }
+                    if pts.isValid {
+                        if decoupleAudio { lastEnqueuedAudioPtsSec = pts.seconds }
+                        diagAudioPtsSec = pts.seconds
+                        diagAudioPtsGeneration = genBeforeRead
+                    }
                 }
                 // Arm clock on first decoded audio buffer; latch so subsequent packets don't snap clock back.
                 if !clockArmed(), !buffers.isEmpty {
@@ -3044,10 +3062,10 @@ final class SoftwarePlaybackHost {
             let keepGoing: Bool = autoreleasepool {
                 demuxIteration()
             }
-            diag?.update(lastAudioPts: lastEnqueuedAudioPtsSec,
+            diag?.update(lastAudioPts: diagAudioPtsSec,
                          parked: parkedVideo.count,
                          rebuffering: rebuffering,
-                         generation: parkedSeekGeneration)
+                         generation: diagAudioPtsGeneration)
             if !keepGoing { break }
         }
         freeParkedVideo()
@@ -3194,6 +3212,9 @@ final class SoftwarePlaybackHost {
                 // deactivated audio session are the same "dclk=0.00" and different defects.
                 + "rate=\(String(format: "%.2f", self.audioOutput?.rate ?? 0)) "
                 + "aLead=\(lead.isFinite ? String(format: "%.2f", lead) : "-") "
+                // AE#395: status/sufficient/error of the audio renderer, the one stage after the feed
+                // that nothing on this line described.
+                + "aRend=\(self.audioOutput?.diagRendererState ?? "-") "
                 + "vLead=\(videoLead.map { String(format: "%.2f", $0) } ?? "-") "
                 + "parkedPkts=\(d.parked) rebuf=\(d.rebuffering ? "y" : "n") "
                 + (d.sourceExhausted ? "eof=y " : "")

From ffbd54a778937f3c9c4587a51b24a58f4c1ba5d3 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Mon, 5 Oct 2026 05:27:09 +0200
Subject: [PATCH 316/359] chore(release): prep 7.27.2 - the software path names
 its audio route, live audio lead and renderer state

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                    | 8 ++++++++
 Examples/README.md                              | 2 +-
 README.md                                       | 6 +++---
 Sources/AetherEngine/AetherEngine+Version.swift | 2 +-
 4 files changed, 13 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 89ff5e398..8050fde91 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,14 @@ the public-API contract.
 
 ## [Unreleased]
 
+_Nothing yet._
+
+## [7.27.2] - 2026-10-05
+
+### Added
+
+- **The software path names its audio route, its audio lead on live, and its renderer state (#395).** A live software session that was silent on an AirPlay 2 receiver and audible over HDMI logged the same on both. The software host now writes `[SoftwarePlaybackHost] audioRoute ...` at session start with the route's output latency (same fields as the native host's line), the engine writes `[AetherEngine] audioRoute changed reason=N ...` on every route change once per process, `[SWDiag]` reports `aLead` on live sessions too (diagnostic marker only, pacing unchanged), and it carries `aRend=status/sufficient/error` for the audio renderer, whose error was only logged in DEBUG builds before. No API change.
+
 ### Fixed
 
 - **An end-of-media park that runs late still stops the clock on the last sample (#694).** The park is deferred by the queued audio tail and ran wherever the clock stood when its task got the main actor, so a busy main actor parked it past the end (measured: 1.149 s on a 1.0 s source). Both the audio-only and the software host now put the clock back on the point the deferral aimed at.
diff --git a/Examples/README.md b/Examples/README.md
index 4060b5751..eb3ecd1a0 100644
--- a/Examples/README.md
+++ b/Examples/README.md
@@ -18,7 +18,7 @@ Three samples covering different audiences:
    ```
    https://github.com/superuser404notfound/AetherEngine
    ```
-   Dependency Rule: Up to Next Major Version, starting from `7.27.1`. Add the `AetherEngine` library product to your app target.
+   Dependency Rule: Up to Next Major Version, starting from `7.27.2`. Add the `AetherEngine` library product to your app target.
 
 3. **Drop the file in.** Replace the Xcode template's default `App.swift` (or whatever the generated `@main` file is called) with the contents of [`MinimalPlayerApp.swift`](MinimalPlayer/MinimalPlayerApp.swift). The file is self-contained: it defines both the `@main App` struct and the `ContentView`.
 
diff --git a/README.md b/README.md
index 64c5b0cb2..9d5e78d28 100644
--- a/README.md
+++ b/README.md
@@ -385,7 +385,7 @@ Subtitle cues land in raw source PTS; render the overlay against `player.sourceT
 Install via Swift Package Manager:
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.27.1")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.27.2")
 ```
 
 Three samples ship in `Examples/`:
@@ -632,10 +632,10 @@ Browse all of this as a searchable site at **[aetherengine.superuser404.de](http
 AetherEngine uses [Semantic Versioning](https://semver.org). The public API surface, every `public` declaration in `Sources/AetherEngine/`, is the stability contract. **Major** removes / renames public symbols or breaks adopters; **Minor** adds public API or codec / format support; **Patch** fixes bugs with no public API change. `internal` types are not part of the contract.
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.27.1")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.27.2")
 ```
 
-Pin to `.upToNextMinor(from: "7.27.1")` for stricter teams that prefer to opt into minor bumps explicitly.
+Pin to `.upToNextMinor(from: "7.27.2")` for stricter teams that prefer to opt into minor bumps explicitly.
 
 ## Requirements
 
diff --git a/Sources/AetherEngine/AetherEngine+Version.swift b/Sources/AetherEngine/AetherEngine+Version.swift
index 616e1698e..5c1058490 100644
--- a/Sources/AetherEngine/AetherEngine+Version.swift
+++ b/Sources/AetherEngine/AetherEngine+Version.swift
@@ -11,5 +11,5 @@ extension AetherEngine {
     ///
     /// Between releases, and in a consumer that pins an unreleased commit for a device test, this
     /// names the last PUBLISHED version the checkout descends from, not every patch in it.
-    public nonisolated static let version = "7.27.1"
+    public nonisolated static let version = "7.27.2"
 }

From adb80da8ff7ffe46eee51abbe396c6b6e9bd158a Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Mon, 5 Oct 2026 19:12:23 +0200
Subject: [PATCH 317/359] fix(demux): repair HEVC MP4s without composition
 offsets (#699)

The #409 repair only armed on H.264, so an HEVC MP4 whose writer dropped
ctts while the bitstream reorders pictures reached AVPlayer and the
software decoder in decode order, which shows as flicker. The picture
order reader now takes the HEVC parser as well, and the window self-check
also accepts a decode-order prefix of at least nine pictures that fills
its own range exactly, which covers a hierarchical mini-GOP longer than
the reorder delay (five pictures at delay 2 on the reporting asset). The
partial-region repair stays H.264-only.

Reporting asset (CUVA conformance B.1-04, 4K50 HEVC Main 10): 0 backward
steps across all 1500 served frames, 35 of 88 before. New HEVC twin pair
reproduces the healthy twin's timestamps packet for packet.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                  |   4 +-
 .../Video/H264CompositionOffsetRepair.swift   |  54 +++-
 .../HEVCCompositionOffsetRepairTests.swift    | 236 ++++++++++++++++++
 docs/architecture.md                          |   2 +-
 docs/formats.md                               |  12 +-
 5 files changed, 288 insertions(+), 20 deletions(-)
 create mode 100644 Tests/AetherEngineTests/HEVCCompositionOffsetRepairTests.swift

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8050fde91..d55d8313b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,7 +10,9 @@ the public-API contract.
 
 ## [Unreleased]
 
-_Nothing yet._
+### Fixed
+
+- **An HEVC MP4 without composition offsets is presented in display order (#699).** The #409 repair only armed on H.264, so an HEVC file whose writer dropped `ctts` while the bitstream reorders pictures went to AVPlayer and the software decoder in decode order, which shows as flicker and back-and-forth motion. The repair now reads the picture order count with libavcodec's HEVC parser as well, and its window check also accepts a hierarchical mini-GOP longer than the reorder delay (five pictures at delay 2 on the reporting asset). Measured on that asset (4K50 Main 10, 1500 frames): 0 backward steps in the served stream, against 35 of 88 in the first frames before. The partial-region repair stays H.264-only. Reported by ijuniorfu.
 
 ## [7.27.2] - 2026-10-05
 
diff --git a/Sources/AetherEngine/Video/H264CompositionOffsetRepair.swift b/Sources/AetherEngine/Video/H264CompositionOffsetRepair.swift
index 5a3ba7aa8..f47dac467 100644
--- a/Sources/AetherEngine/Video/H264CompositionOffsetRepair.swift
+++ b/Sources/AetherEngine/Video/H264CompositionOffsetRepair.swift
@@ -291,8 +291,13 @@ enum H264CompositionOffsetRepair {
         // are then spread over twice the ladder while still being distinct. Ranks have to FILL the
         // window they came from: the span may exceed the sample only by the pictures still in flight
         // at its ragged edge, which is the reorder delay.
+        // A hierarchical mini-GOP longer than the reorder delay sends its anchor further ahead than
+        // that allowance (#699's HEVC stream: POC 15 decoded while 11 to 14 are still to come, at
+        // delay 2), so the window may instead prove itself by a decode-order prefix of at least
+        // `minimumSamples` pictures that fills its display range exactly, which is the stricter test.
         guard let maxIndex = displayIndices.max(), let minIndex = displayIndices.min(),
-              maxIndex - minIndex + 1 <= Int64(samples.count + videoDelay + 1) else {
+              maxIndex - minIndex + 1 <= Int64(samples.count + videoDelay + 1)
+                || hasContiguousPrefix(samples.map { $0.pictureOrderCount / pocStep }) else {
             return .inconclusive("display indices do not fill the sampled window")
         }
 
@@ -354,6 +359,19 @@ enum H264CompositionOffsetRepair {
         )
     }
 
+    /// True when some decode-order prefix of at least `minimumSamples` display indices covers its
+    /// own range without a gap, i.e. a whole number of mini-GOPs closed inside the window.
+    static func hasContiguousPrefix(_ indices: [Int64]) -> Bool {
+        guard var low = indices.first else { return false }
+        var high = low
+        for (offset, index) in indices.enumerated() {
+            low = min(low, index)
+            high = max(high, index)
+            if offset + 1 >= minimumSamples, high - low == Int64(offset) { return true }
+        }
+        return false
+    }
+
     /// Which phase of the cadence the sampled ladder starts on, and where that puts lattice ordinal
     /// zero. Every sampled picture has to land exactly, and the answer has to be the only phase in
     /// the period that does, or the ladder is not evidence of a lattice at all. This is what lets a
@@ -509,22 +527,25 @@ enum H264CompositionOffsetRepair {
     }
 }
 
-/// Reads a picture order count per packet with libavcodec's H.264 parser. No decoder is opened and
-/// no picture is reconstructed: the parser walks the slice header, which is where display order
-/// lives. It takes MP4's length-prefixed AVCC payload directly as long as the codec context carries
-/// the `avcC` extradata, so no Annex-B conversion sits in the packet path.
+/// Reads a picture order count per packet with libavcodec's H.264 or HEVC parser. No decoder is
+/// opened and no picture is reconstructed: the parser walks the slice header, which is where display
+/// order lives. It takes MP4's length-prefixed AVCC / HVCC payload directly as long as the codec
+/// context carries the `avcC` / `hvcC` extradata, so no Annex-B conversion sits in the packet path.
 final class H264PictureOrderReader {
     private var parser: UnsafeMutablePointer<AVCodecParserContext>?
     private var context: UnsafeMutablePointer<AVCodecContext>?
+    private let codecID: AVCodecID
     var isFramePicture: Bool { parser?.pointee.picture_structure == AV_PICTURE_STRUCTURE_FRAME }
 
     init?(codecParameters: UnsafePointer<AVCodecParameters>, timeBase: AVRational) {
-        guard let codec = avcodec_find_decoder(AV_CODEC_ID_H264),
+        codecID = codecParameters.pointee.codec_id
+        guard codecID == AV_CODEC_ID_H264 || codecID == AV_CODEC_ID_HEVC,
+              let codec = avcodec_find_decoder(codecID),
               let context = avcodec_alloc_context3(codec) else { return nil }
         self.context = context
         guard avcodec_parameters_to_context(context, codecParameters) >= 0 else { return nil }
         context.pointee.pkt_timebase = timeBase
-        guard let parser = av_parser_init(Int32(AV_CODEC_ID_H264.rawValue)) else { return nil }
+        guard let parser = av_parser_init(Int32(codecID.rawValue)) else { return nil }
         self.parser = parser
         // MP4 samples are whole access units; without this the parser hunts for start codes that
         // length-prefixed payloads do not contain.
@@ -543,7 +564,7 @@ final class H264PictureOrderReader {
     func reset() {
         guard let parser else { return }
         av_parser_close(parser)
-        self.parser = av_parser_init(Int32(AV_CODEC_ID_H264.rawValue))
+        self.parser = av_parser_init(Int32(codecID.rawValue))
         self.parser?.pointee.flags |= Int32(PARSER_FLAG_COMPLETE_FRAMES)
     }
 
@@ -582,6 +603,7 @@ final class H264CompositionOffsetRepairSession {
     private let videoDelay: Int
     private let streamStartTime: Int64
     private let ladderStart: Int64
+    private let codecName: String
     private var reader: H264PictureOrderReader?
     private var rewriter: H264CompositionOffsetRepair.Rewriter?
     private let partialRepairCandidate: H264PartialCompositionRepairSession?
@@ -591,8 +613,10 @@ final class H264CompositionOffsetRepairSession {
     private var heldBytes = 0
     private var verdictDescription = "sampling"
 
-    /// nil unless this stream is the exact shape the defect needs: ISO-BMFF, H.264, and a bitstream
-    /// that declares reordered pictures. Everything else never sees a parser or a held packet.
+    /// nil unless this stream is the exact shape the defect needs: ISO-BMFF, H.264 or HEVC, and a
+    /// bitstream that declares reordered pictures. Everything else never sees a parser or a held
+    /// packet. HEVC carries the same loss (#699: a CUVA conformance stream with B pictures and no
+    /// `ctts`), and its slice header carries the same picture order count.
     init?(
         containerFormatName: String?,
         stream: UnsafeMutablePointer<AVStream>,
@@ -602,7 +626,7 @@ final class H264CompositionOffsetRepairSession {
         let containers = containerFormatName?.split(separator: ",") ?? []
         guard containers.contains("mov") || containers.contains("mp4") else { return nil }
         guard let codecpar = stream.pointee.codecpar,
-              codecpar.pointee.codec_id == AV_CODEC_ID_H264,
+              codecpar.pointee.codec_id == AV_CODEC_ID_H264 || codecpar.pointee.codec_id == AV_CODEC_ID_HEVC,
               codecpar.pointee.video_delay > 0,
               let reader = H264PictureOrderReader(
                 codecParameters: codecpar, timeBase: stream.pointee.time_base)
@@ -613,7 +637,11 @@ final class H264CompositionOffsetRepairSession {
         self.ladderStart = ladderStart
         self.reader = reader
         let (lead, overflow) = stream.pointee.start_time.subtractingReportingOverflow(ladderStart)
-        partialRepairCandidate = !overflow && stream.pointee.start_time != Int64.min && ladderStart != Int64.min
+        // The partial-region repair reads H.264 NAL types to find its IDRs, so HEVC gets the
+        // all-missing repair only.
+        self.codecName = codecpar.pointee.codec_id == AV_CODEC_ID_HEVC ? "HEVC" : "H.264"
+        partialRepairCandidate = codecpar.pointee.codec_id == AV_CODEC_ID_H264
+            && !overflow && stream.pointee.start_time != Int64.min && ladderStart != Int64.min
             ? H264PartialCompositionRepairSession(stream: stream, streamIndex: streamIndex, presentationLead: lead)
             : nil
     }
@@ -767,7 +795,7 @@ final class H264CompositionOffsetRepairSession {
             }
             self.rewriter = rewriter
             EngineLog.emit(
-                "[Demuxer] #409 missing H.264 composition offsets confirmed on stream \(streamIndex): "
+                "[Demuxer] #409 missing \(codecName) composition offsets confirmed on stream \(streamIndex): "
                 + "\(verdictDescription) samples=\(samples.count)",
                 category: .demux
             )
diff --git a/Tests/AetherEngineTests/HEVCCompositionOffsetRepairTests.swift b/Tests/AetherEngineTests/HEVCCompositionOffsetRepairTests.swift
new file mode 100644
index 000000000..4f85989ee
--- /dev/null
+++ b/Tests/AetherEngineTests/HEVCCompositionOffsetRepairTests.swift
@@ -0,0 +1,236 @@
+import Foundation
+import AetherLibavcodec
+import Testing
+@testable import AetherEngine
+
+/// #699: the #409 defect on HEVC. The reporting asset (a CUVA HDR Vivid conformance stream, 4K50 Main
+/// 10) carries B pictures and no `ctts`, so every sample reports `PTS == DTS` and the picture was
+/// presented in decode order. Its mini-GOP is five pictures at a reorder delay of 2, which is also what
+/// the twin below encodes: the next anchor is decoded four pictures ahead of the last one displayed.
+@Suite("HEVC missing composition offsets (#699)")
+struct HEVCCompositionOffsetRepairTests {
+
+    /// The reporting asset's head, read with libavcodec's HEVC parser: picture order 0, 5, 3, 1, 2, 4,
+    /// then the same mini-GOP again, and the third anchor at 15 while 11 to 14 are still to come.
+    private func reportedSamples() -> [H264CompositionOffsetRepair.Sample] {
+        let pocs: [Int64] = [0, 5, 3, 1, 2, 4, 10, 8, 6, 7, 9, 15]
+        return pocs.enumerated().map { index, poc in
+            H264CompositionOffsetRepair.Sample(
+                dts: Int64(index - 2) * 24000,
+                pts: Int64(index - 2) * 24000,
+                pictureOrderCount: poc,
+                isKeyframe: index == 0
+            )
+        }
+    }
+
+    @Test("a mini-GOP longer than the reorder delay is repaired, not refused at its ragged edge")
+    func longMiniGOPIsRepaired() {
+        let verdict = H264CompositionOffsetRepair.classify(
+            samples: reportedSamples(), videoDelay: 2, streamStartTime: 0, ladderStart: -48000)
+        #expect(verdict == .repair(.init(step: 24000, decodeLead: 48000, shift: 48000, pocStep: 1)))
+    }
+
+    @Test("the contiguous prefix has to be at least the minimum sample long")
+    func contiguousPrefixNeedsTheMinimum() {
+        #expect(H264CompositionOffsetRepair.hasContiguousPrefix([0, 5, 3, 1, 2, 4, 10, 8, 6, 7, 9, 15]))
+        // Closes at 6 pictures only, and the next mini-GOP never closes inside the window.
+        #expect(!H264CompositionOffsetRepair.hasContiguousPrefix([0, 5, 3, 1, 2, 4, 12, 9, 7, 6, 8, 11]))
+        // A stray rank spread over twice the ladder never fills its range.
+        #expect(!H264CompositionOffsetRepair.hasContiguousPrefix([0, 10, 6, 2, 4, 8, 20, 16, 12, 14, 18, 30]))
+    }
+
+    // MARK: - end to end, against the twin
+
+    private struct Timestamps: Equatable, CustomStringConvertible {
+        var pts: Int64
+        var dts: Int64
+        var description: String { "pts=\(pts) dts=\(dts)" }
+    }
+
+    private static func videoTimestamps(base64: String) throws -> [Timestamps] {
+        let data = try #require(Data(base64Encoded: base64, options: .ignoreUnknownCharacters))
+        let demuxer = Demuxer()
+        try demuxer.open(reader: DataIOReader(data: data), formatHint: "mp4")
+        defer { demuxer.close() }
+        let videoIndex = demuxer.videoStreamIndex
+        var result: [Timestamps] = []
+        while let packet = try? demuxer.readPacket() {
+            if packet.pointee.stream_index == videoIndex {
+                result.append(Timestamps(pts: packet.pointee.pts, dts: packet.pointee.dts))
+            }
+            var owned: UnsafeMutablePointer<AVPacket>? = packet
+            trackedPacketFree(&owned)
+        }
+        return result
+    }
+
+    @Test("the repaired HEVC twin carries the healthy twin's timestamps, packet for packet")
+    func repairedTwinMatchesHealthyTwin() throws {
+        let healthy = try Self.videoTimestamps(base64: Self.healthyFixtureBase64)
+        let repaired = try Self.videoTimestamps(base64: Self.missingFixtureBase64)
+        #expect(healthy.count == 30)
+        #expect(healthy.first == Timestamps(pts: 0, dts: -512))
+        #expect(repaired == healthy)
+    }
+
+    @Test("the healthy HEVC twin is delivered exactly as the container wrote it")
+    func healthyTwinIsUntouched() throws {
+        let healthy = try Self.videoTimestamps(base64: Self.healthyFixtureBase64)
+        #expect(healthy.contains { $0.pts != $0.dts })
+        #expect(zip(healthy, healthy.dropFirst()).allSatisfy { $1.dts - $0.dts == 256 })
+    }
+
+    /// 64x64 HEVC Main 10, 50 fps, 30 frames, four B pictures per hierarchical mini-GOP.
+    ///
+    ///     ffmpeg -f lavfi -i 'testsrc=s=64x64:r=50:d=0.6' -frames:v 30 -c:v libx265 -preset ultrafast \
+    ///       -pix_fmt yuv420p10le -x265-params \
+    ///       'bframes=4:b-pyramid=1:b-adapt=0:keyint=30:min-keyint=30:scenecut=0' \
+    ///       -tag:v hvc1 -movflags +faststart healthy.mp4
+    ///     ffmpeg -i healthy.mp4 -map 0:v:0 -c:v copy -bsf:v 'setts=pts=DTS' \
+    ///       -movflags +faststart missing.mp4
+    private static let healthyFixtureBase64 = """
+        AAAAHGZ0eXBpc29tAAACAGlzb21pc28ybXA0MQAADf5tb292AAAAbG12aGQAAAAAAAAAAAAAAAAAAAPoAAACWAABAAABAAAAAAAA
+        AAAAAAAAAQAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACAAANKHRy
+        YWsAAABcdGtoZAAAAAMAAAAAAAAAAAAAAAEAAAAAAAACWAAAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAEAAAAAAAAA
+        AAAAAAAAAEAAAAAAQAAAAEAAAAAAACRlZHRzAAAAHGVsc3QAAAAAAAAAAQAAAlgAAAIAAAEAAAAADKBtZGlhAAAAIG1kaGQAAAAA
+        AAAAAAAAAAAAADIAAAAeAFXEAAAAAAAtaGRscgAAAAAAAAAAdmlkZQAAAAAAAAAAAAAAAFZpZGVvSGFuZGxlcgAAAAxLbWluZgAA
+        ABR2bWhkAAAAAQAAAAAAAAAAAAAAJGRpbmYAAAAcZHJlZgAAAAAAAAABAAAADHVybCAAAAABAAAMC3N0YmwAAAoZc3RzZAAAAAAA
+        AAABAAAKCWh2YzEAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAQABAAEgAAABIAAAAAAAAAAEVTGF2YzYyLjI4LjEwMSBsaWJ4MjY1
+        AAAAAAAAAAAAAAAY//8AAAmFaHZjQwECIAAAAJAAAAAAAB7wAPz9+voAAA8EoAABABhAAQwB//8CIAAAAwCQAAADAAADAB6VmAmh
+        AAEAKkIBAQIgAAADAJAAAAMAAAMAHqAggQTZZWZKTC8BaAgAAAMACAAAAwGQQKIAAQAGRAHAc8CJJwABCQpOAQX///////////8F
+        LKLeCbUXR9u7VaT+f8L8TngyNjUgKGJ1aWxkIDIxNikgLSA0LjIrMS1lNDQ0NzQ0OltNYWMgT1MgWF1bY2xhbmcgMjEuMC4wXVs2
+        NCBiaXRdIDEwYml0IC0gSC4yNjUvSEVWQyBjb2RlYyAtIENvcHlyaWdodCAyMDEzLTIwMTggKGMpIE11bHRpY29yZXdhcmUsIElu
+        YyAtIGh0dHA6Ly94MjY1Lm9yZyAtIG9wdGlvbnM6IGNwdWlkPTM0IGZyYW1lLXRocmVhZHM9MSBuby13cHAgbm8tcG1vZGUgbm8t
+        cG1lIG5vLXBzbnIgbm8tc3NpbSBsb2ctbGV2ZWw9MCBiaXRkZXB0aD0xMCBpbnB1dC1jc3A9MSBmcHM9NTAvMSBpbnB1dC1yZXM9
+        NjR4NjQgaW50ZXJsYWNlPTAgdG90YWwtZnJhbWVzPTAgbGV2ZWwtaWRjPTAgaGlnaC10aWVyPTEgdWhkLWJkPTAgcmVmPTEgbm8t
+        YWxsb3ctbm9uLWNvbmZvcm1hbmNlIG5vLXJlcGVhdC1oZWFkZXJzIGFubmV4YiBuby1hdWQgbm8tZW9iIG5vLWVvcyBuby1ocmQg
+        aW5mbyBoYXNoPTAgdGVtcG9yYWwtbGF5ZXJzPTAgb3Blbi1nb3AgbWluLWtleWludD0zMCBrZXlpbnQ9MzAgZ29wLWxvb2thaGVh
+        ZD0wIGJmcmFtZXM9NCBiLWFkYXB0PTAgYi1weXJhbWlkIGJmcmFtZS1iaWFzPTAgcmMtbG9va2FoZWFkPTUgbG9va2FoZWFkLXNs
+        aWNlcz0wIHNjZW5lY3V0PTAgbm8taGlzdC1zY2VuZWN1dCByYWRsPTAgbm8tc3BsaWNlIG5vLWludHJhLXJlZnJlc2ggY3R1PTMy
+        IG1pbi1jdS1zaXplPTE2IG5vLXJlY3Qgbm8tYW1wIG1heC10dS1zaXplPTMyIHR1LWludGVyLWRlcHRoPTEgdHUtaW50cmEtZGVw
+        dGg9MSBsaW1pdC10dT0wIHJkb3EtbGV2ZWw9MCBkeW5hbWljLXJkPTAuMDAgbm8tc3NpbS1yZCBuby1zaWduaGlkZSBuby10c2tp
+        cCBuci1pbnRyYT0wIG5yLWludGVyPTAgbm8tY29uc3RyYWluZWQtaW50cmEgc3Ryb25nLWludHJhLXNtb290aGluZyBtYXgtbWVy
+        Z2U9MiBsaW1pdC1yZWZzPTAgbm8tbGltaXQtbW9kZXMgbWU9MCBzdWJtZT0wIG1lcmFuZ2U9NTcgdGVtcG9yYWwtbXZwIG5vLWZy
+        YW1lLWR1cCBuby1obWUgbm8td2VpZ2h0cCBuby13ZWlnaHRiIG5vLWFuYWx5emUtc3JjLXBpY3MgZGVibG9jaz0wOjAgbm8tc2Fv
+        IG5vLXNhby1ub24tZGVibG9jayByZD0yIHNlbGVjdGl2ZS1zYW89MCBlYXJseS1za2lwIHJza2lwIGZhc3QtaW50cmEgbm8tdHNr
+        aXAtZmFzdCBuby1jdS1sb3NzbGVzcyBuby1iLWludHJhIG5vLXNwbGl0cmQtc2tpcCByZHBlbmFsdHk9MCBwc3ktcmQ9Mi4wMCBw
+        c3ktcmRvcT0wLjAwIG5vLXJkLXJlZmluZSBuby1sb3NzbGVzcyBjYnFwb2Zmcz0wIGNycXBvZmZzPTAgcmM9Y3JmIGNyZj0yOC4w
+        IHFjb21wPTAuNjAgcXBzdGVwPTQgc3RhdHMtd3JpdGU9MCBzdGF0cy1yZWFkPTAgaXByYXRpbz0xLjQwIHBicmF0aW89MS4zMCBh
+        cS1tb2RlPTEgYXEtc3RyZW5ndGg9MC4wMCBjdXRyZWUgem9uZS1jb3VudD0wIG5vLXN0cmljdC1jYnIgcWctc2l6ZT0zMiBuby1y
+        Yy1ncmFpbiBxcG1heD02OSBxcG1pbj0wIG5vLWNvbnN0LXZidiBzYXI9MSBvdmVyc2Nhbj0wIHZpZGVvZm9ybWF0PTUgcmFuZ2U9
+        MCBjb2xvcnByaW09MiB0cmFuc2Zlcj0yIGNvbG9ybWF0cml4PTIgY2hyb21hbG9jPTAgZGlzcGxheS13aW5kb3c9MCBjbGw9MCww
+        IG1pbi1sdW1hPTAgbWF4LWx1bWE9MTAyMyBsb2cyLW1heC1wb2MtbHNiPTggdnVpLXRpbWluZy1pbmZvIHZ1aS1ocmQtaW5mbyBz
+        bGljZXM9MSBuby1vcHQtcXAtcHBzIG5vLW9wdC1yZWYtbGlzdC1sZW5ndGgtcHBzIG5vLW11bHRpLXBhc3Mtb3B0LXJwcyBzY2Vu
+        ZWN1dC1iaWFzPTAuMDUgbm8tb3B0LWN1LWRlbHRhLXFwIG5vLWFxLW1vdGlvbiBuby1oZHIxMCBuby1oZHIxMC1vcHQgbm8tZGhk
+        cjEwLW9wdCBuby1pZHItcmVjb3Zlcnktc2VpIGFuYWx5c2lzLXJldXNlLWxldmVsPTAgYW5hbHlzaXMtc2F2ZS1yZXVzZS1sZXZl
+        bD0wIGFuYWx5c2lzLWxvYWQtcmV1c2UtbGV2ZWw9MCBzY2FsZS1mYWN0b3I9MCByZWZpbmUtaW50cmE9MCByZWZpbmUtaW50ZXI9
+        MCByZWZpbmUtbXY9MSByZWZpbmUtY3R1LWRpc3RvcnRpb249MCBuby1saW1pdC1zYW8gY3R1LWluZm89MCBuby1sb3dwYXNzLWRj
+        dCByZWZpbmUtYW5hbHlzaXMtdHlwZT0wIGNvcHktcGljPTEgbWF4LWF1c2l6ZS1mYWN0b3I9MS4wIG5vLWR5bmFtaWMtcmVmaW5l
+        IG5vLXNpbmdsZS1zZWkgbm8taGV2Yy1hcSBuby1zdnQgbm8tZmllbGQgcXAtYWRhcHRhdGlvbi1yYW5nZT0xLjAwIHNjZW5lY3V0
+        LWF3YXJlLXFwPTBjb25mb3JtYW5jZS13aW5kb3ctb2Zmc2V0cyByaWdodD0wIGJvdHRvbT0wIGRlY29kZXItbWF4LXJhdGU9MCBu
+        by12YnYtbGl2ZS1tdWx0aS1wYXNzIG5vLW1jc3RmIG5vLXNicmMgbm8tZnJhbWUtcmOAAAAACmZpZWwBAAAAABBwYXNwAAAAAQAA
+        AAEAAAAUYnRydAAAAAAAAFZoAAAAAAAAABhzdHRzAAAAAAAAAAEAAAAeAAABAAAAABRzdHNzAAAAAAAAAAEAAAABAAAAKnNkdHAA
+        AAAAIBAQGBgYEBAYGBgQEBgYGBAQGBgYEBAYGBgQEBgYAAAA2GN0dHMAAAAAAAAAGQAAAAEAAAIAAAAAAQAABgAAAAABAAADAAAA
+        AAIAAAAAAAAAAQAAAQAAAAABAAAGAAAAAAEAAAMAAAAAAgAAAAAAAAABAAABAAAAAAEAAAYAAAAAAQAAAwAAAAACAAAAAAAAAAEA
+        AAEAAAAAAQAABgAAAAABAAADAAAAAAIAAAAAAAAAAQAAAQAAAAABAAAGAAAAAAEAAAMAAAAAAgAAAAAAAAABAAABAAAAAAEAAAUA
+        AAAAAQAAAgAAAAABAAAAAAAAAAEAAAEAAAAAHHN0c2MAAAAAAAAAAQAAAAEAAAAeAAAAAQAAAIxzdHN6AAAAAAAAAAAAAAAeAAAE
+        FQAAABUAAAAOAAAADwAAAA8AAAAOAAAALAAAAA8AAAAQAAAAEAAAAA8AAAAsAAAAEAAAABAAAAAQAAAADwAAADoAAAAQAAAAEAAA
+        ABAAAAAPAAAALgAAABAAAAAQAAAAEAAAAA8AAAAuAAAAEAAAAA8AAAAPAAAAFHN0Y28AAAAAAAAAAQAADioAAABidWR0YQAAAFpt
+        ZXRhAAAAAAAAACFoZGxyAAAAAAAAAABtZGlyYXBwbAAAAAAAAAAAAAAAAC1pbHN0AAAAJal0b28AAAAdZGF0YQAAAAEAAAAATGF2
+        ZjYyLjEyLjEwMQAAAAhmcmVlAAAGg21kYXQAAAQRKAGsKYCoC2PeLG++3GQqYwPd5f4iYh0irT8tB7IqSXHt9aYS3pMd85e6qfFP
+        LmPrzOtW5kKQFnIBbc1MydWMNZHnyNpet0rgxNXjNkPiSCdRctOJmNboZXO3x//WaYP3Aq3x+xuQhmV0stHPZdcmt5Jbna/QezfT
+        DUUKoJwPS+5DmWJq9yw6gPeCyy1Rli+B4Uaxa0tsVKRIN5YnsFwCI3/P3LFhWQ1aulZViQoT/4lpsoXQXXUKsqQ1G/jmT98sRqYV
+        9OoAjm8GpBUioTmj3bkTXiDhlAX6da2TWpoxFZOqcNETPTflTcnZRJjTcqAyvaoYMPHFMywXDq05X6Klw+5LUC0m/IRo1LpwAEX6
+        dQqd6AMic6AKZUI9Znm7vmJQUJlPMTBWdxUiVdl5FhUt+Aukxa3ZF8pAQW5ql0lJa7DCNvwtqZKJviO6bfAN+tV0zaPRskCedm8M
+        7ojLfJp4/boaEq///9trlDjx6oCNe2I8TiPY/CgD6qXDF/1Ns/Pjv2jYMkPN+buRIG1PElW37KjK5VLSI8fBS/IwNmfWzMlJIfMP
+        oQm3zMBouaAJCeUOYHTE9xl2KRPwOcs6TCcSW0VCQhefFSlomBwBIgI3UnQQz1HyVVmMr6tMSVFPe2zKSCztBKkO3sx/RLk88SA0
+        dTCYwwefoazaTXOldBEPrQO1yAxZ+iqmsAslyNmichJ397ob6lWVj4HKIoH5dM3hA8rrhOqTQ5tqehE2pajPeVnrYlxmlH81gtpi
+        9MT6bA16aeJ9eY2gdP3A+QLrPLMTgHsgqa3k6rkOOpyrF15SswW9JNzerZOCRpfqw5AXp6y1aKyNhsYUJsDfwWkRRGgWlC5zzB1j
+        y5gOFuMIIM07Ew6eKOwU2teliFSzdk1MDHXcAwI+F3vaFsNEYJmk7zRnh873ftuThZQx28rwlmuf4+Ab8qv6amuMd/sC8/zxhfF0
+        UbCQSENNgeDzCZVTj8B8T0BZUoKHPn//KdmxoyikLbd2e3sEJyR/0HOhkOZnEKzLIqflcKN10SX5bgj9Q7at1ZCOMhQ5AzS+F+iL
+        b4qsLQJQeIApndqD3H7Llw14c3T0vZL1cAAsiSs5yFCuCwHYC8T8A7WdBrQM7As8BpBZgSAlXnJN7TxLfvXv3wwHVKsXaNTzxIiV
+        4s0Xtyhve/TUT6JuZtAZMJ3cWxXsJluym+z1c6poBR/aMnWSyhTuqOLa/5vU443t7Y4MwVpe6gBypmgX9uCJmCBkme8et61FbpkZ
+        +Mgc4AQJVenBce5b8yAQWHWd5zBk4zRu2L0VK9vuSu7ZgHYo51UxzwMQCNJQ7a92ZThKFLyDmFT5gqeltYfIjka3uHJDxujXGscw
+        FPTQRj4LKfyFRuPy3xCSsS8YMYm+AAAAEQIB0ClLiBRAs1pEo6u+ZSuXAAAACgIB4GSdYIFkkngAAAALAAHgJPVeiQMYkPAAAAAL
+        AAHgRNdeiQMIkPAAAAAKAAHghrfggYyQ8AAAACgCAdBQktXiBRCzWkFey1+VMBHdPUlsBUhuilioNQ9hOPghYTzWH99wAAAACwIB
+        4QInV1ggWZJ4AAAADAAB4Mb1VeiQMYCQ8AAAAAwAAeDm1XXokDCAkPAAAAALAAHhIi3XggYwkPAAAAAoAgHQeLLV1iBRs1fdRSLN
+        r7qLgw9k6qz4+0LjUk+0NRRyL70QOwEQgAAAAAwCAeGiJ1LWCBZAkngAAAAMAAHhZvVV6JAxgJDwAAAADAAB4YbVdeiQMICQ8AAA
+        AAsAAeHCLdeCBjCQ8AAAADYCAdCgstXWIFGzWkXwn0I9zhHfu+OUlQywM4hhFO/Rgmzzdyv0TypArT007GQJ1LjPL7Vu2TAAAAAM
+        AgHiQidS1ggWwJJ4AAAADAAB4gb1VeiQMICQ8AAAAAwAAeIm1XXokDGAkPAAAAALAAHiYi3XggYwkPAAAAAqAgHQyLLV1iBTs1pF
+        2UwP6z4eiZizCiXuyD+VkAZ8PmIohoKUP1a5rFLYAAAADAIB4uInUtYIFkCSeAAAAAwAAeKm9VXokDCAkPAAAAAMAAHixtV16JAx
+        gJDwAAAACwAB4wIt14IGMJDwAAAAKgIB0OiyVdYgUbNX33n2/kixaxBTSBJOYLe+rSsDXZK4kET9EzPm7DExEgAAAAwCAeNiJVLW
+        CBbAkngAAAALAAHjRvXXokDGkPAAAAALAAHjgi1XggYwkPA=
+        """
+
+    private static let missingFixtureBase64 = """
+        AAAAHGZ0eXBpc29tAAACAGlzb21pc28ybXA0MQAADSZtb292AAAAbG12aGQAAAAAAAAAAAAAAAAAAAPoAAACMAABAAABAAAAAAAA
+        AAAAAAAAAQAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACAAAMUHRy
+        YWsAAABcdGtoZAAAAAMAAAAAAAAAAAAAAAEAAAAAAAACMAAAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAEAAAAAAAAA
+        AAAAAAAAAEAAAAAAQAAAAEAAAAAAACRlZHRzAAAAHGVsc3QAAAAAAAAAAQAAAjAAAAIAAAEAAAAAC8htZGlhAAAAIG1kaGQAAAAA
+        AAAAAAAAAAAAADIAAAAeAFXEAAAAAAAtaGRscgAAAAAAAAAAdmlkZQAAAAAAAAAAAAAAAFZpZGVvSGFuZGxlcgAAAAtzbWluZgAA
+        ABR2bWhkAAAAAQAAAAAAAAAAAAAAJGRpbmYAAAAcZHJlZgAAAAAAAAABAAAADHVybCAAAAABAAALM3N0YmwAAAoZc3RzZAAAAAAA
+        AAABAAAKCWh2YzEAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAQABAAEgAAABIAAAAAAAAAAEVTGF2YzYyLjI4LjEwMSBsaWJ4MjY1
+        AAAAAAAAAAAAAAAY//8AAAmFaHZjQwECIAAAAJAAAAAAAB7wAPz9+voAAA8EoAABABhAAQwB//8CIAAAAwCQAAADAAADAB6VmAmh
+        AAEAKkIBAQIgAAADAJAAAAMAAAMAHqAggQTZZWZKTC8BaAgAAAMACAAAAwGQQKIAAQAGRAHAc8CJJwABCQpOAQX///////////8F
+        LKLeCbUXR9u7VaT+f8L8TngyNjUgKGJ1aWxkIDIxNikgLSA0LjIrMS1lNDQ0NzQ0OltNYWMgT1MgWF1bY2xhbmcgMjEuMC4wXVs2
+        NCBiaXRdIDEwYml0IC0gSC4yNjUvSEVWQyBjb2RlYyAtIENvcHlyaWdodCAyMDEzLTIwMTggKGMpIE11bHRpY29yZXdhcmUsIElu
+        YyAtIGh0dHA6Ly94MjY1Lm9yZyAtIG9wdGlvbnM6IGNwdWlkPTM0IGZyYW1lLXRocmVhZHM9MSBuby13cHAgbm8tcG1vZGUgbm8t
+        cG1lIG5vLXBzbnIgbm8tc3NpbSBsb2ctbGV2ZWw9MCBiaXRkZXB0aD0xMCBpbnB1dC1jc3A9MSBmcHM9NTAvMSBpbnB1dC1yZXM9
+        NjR4NjQgaW50ZXJsYWNlPTAgdG90YWwtZnJhbWVzPTAgbGV2ZWwtaWRjPTAgaGlnaC10aWVyPTEgdWhkLWJkPTAgcmVmPTEgbm8t
+        YWxsb3ctbm9uLWNvbmZvcm1hbmNlIG5vLXJlcGVhdC1oZWFkZXJzIGFubmV4YiBuby1hdWQgbm8tZW9iIG5vLWVvcyBuby1ocmQg
+        aW5mbyBoYXNoPTAgdGVtcG9yYWwtbGF5ZXJzPTAgb3Blbi1nb3AgbWluLWtleWludD0zMCBrZXlpbnQ9MzAgZ29wLWxvb2thaGVh
+        ZD0wIGJmcmFtZXM9NCBiLWFkYXB0PTAgYi1weXJhbWlkIGJmcmFtZS1iaWFzPTAgcmMtbG9va2FoZWFkPTUgbG9va2FoZWFkLXNs
+        aWNlcz0wIHNjZW5lY3V0PTAgbm8taGlzdC1zY2VuZWN1dCByYWRsPTAgbm8tc3BsaWNlIG5vLWludHJhLXJlZnJlc2ggY3R1PTMy
+        IG1pbi1jdS1zaXplPTE2IG5vLXJlY3Qgbm8tYW1wIG1heC10dS1zaXplPTMyIHR1LWludGVyLWRlcHRoPTEgdHUtaW50cmEtZGVw
+        dGg9MSBsaW1pdC10dT0wIHJkb3EtbGV2ZWw9MCBkeW5hbWljLXJkPTAuMDAgbm8tc3NpbS1yZCBuby1zaWduaGlkZSBuby10c2tp
+        cCBuci1pbnRyYT0wIG5yLWludGVyPTAgbm8tY29uc3RyYWluZWQtaW50cmEgc3Ryb25nLWludHJhLXNtb290aGluZyBtYXgtbWVy
+        Z2U9MiBsaW1pdC1yZWZzPTAgbm8tbGltaXQtbW9kZXMgbWU9MCBzdWJtZT0wIG1lcmFuZ2U9NTcgdGVtcG9yYWwtbXZwIG5vLWZy
+        YW1lLWR1cCBuby1obWUgbm8td2VpZ2h0cCBuby13ZWlnaHRiIG5vLWFuYWx5emUtc3JjLXBpY3MgZGVibG9jaz0wOjAgbm8tc2Fv
+        IG5vLXNhby1ub24tZGVibG9jayByZD0yIHNlbGVjdGl2ZS1zYW89MCBlYXJseS1za2lwIHJza2lwIGZhc3QtaW50cmEgbm8tdHNr
+        aXAtZmFzdCBuby1jdS1sb3NzbGVzcyBuby1iLWludHJhIG5vLXNwbGl0cmQtc2tpcCByZHBlbmFsdHk9MCBwc3ktcmQ9Mi4wMCBw
+        c3ktcmRvcT0wLjAwIG5vLXJkLXJlZmluZSBuby1sb3NzbGVzcyBjYnFwb2Zmcz0wIGNycXBvZmZzPTAgcmM9Y3JmIGNyZj0yOC4w
+        IHFjb21wPTAuNjAgcXBzdGVwPTQgc3RhdHMtd3JpdGU9MCBzdGF0cy1yZWFkPTAgaXByYXRpbz0xLjQwIHBicmF0aW89MS4zMCBh
+        cS1tb2RlPTEgYXEtc3RyZW5ndGg9MC4wMCBjdXRyZWUgem9uZS1jb3VudD0wIG5vLXN0cmljdC1jYnIgcWctc2l6ZT0zMiBuby1y
+        Yy1ncmFpbiBxcG1heD02OSBxcG1pbj0wIG5vLWNvbnN0LXZidiBzYXI9MSBvdmVyc2Nhbj0wIHZpZGVvZm9ybWF0PTUgcmFuZ2U9
+        MCBjb2xvcnByaW09MiB0cmFuc2Zlcj0yIGNvbG9ybWF0cml4PTIgY2hyb21hbG9jPTAgZGlzcGxheS13aW5kb3c9MCBjbGw9MCww
+        IG1pbi1sdW1hPTAgbWF4LWx1bWE9MTAyMyBsb2cyLW1heC1wb2MtbHNiPTggdnVpLXRpbWluZy1pbmZvIHZ1aS1ocmQtaW5mbyBz
+        bGljZXM9MSBuby1vcHQtcXAtcHBzIG5vLW9wdC1yZWYtbGlzdC1sZW5ndGgtcHBzIG5vLW11bHRpLXBhc3Mtb3B0LXJwcyBzY2Vu
+        ZWN1dC1iaWFzPTAuMDUgbm8tb3B0LWN1LWRlbHRhLXFwIG5vLWFxLW1vdGlvbiBuby1oZHIxMCBuby1oZHIxMC1vcHQgbm8tZGhk
+        cjEwLW9wdCBuby1pZHItcmVjb3Zlcnktc2VpIGFuYWx5c2lzLXJldXNlLWxldmVsPTAgYW5hbHlzaXMtc2F2ZS1yZXVzZS1sZXZl
+        bD0wIGFuYWx5c2lzLWxvYWQtcmV1c2UtbGV2ZWw9MCBzY2FsZS1mYWN0b3I9MCByZWZpbmUtaW50cmE9MCByZWZpbmUtaW50ZXI9
+        MCByZWZpbmUtbXY9MSByZWZpbmUtY3R1LWRpc3RvcnRpb249MCBuby1saW1pdC1zYW8gY3R1LWluZm89MCBuby1sb3dwYXNzLWRj
+        dCByZWZpbmUtYW5hbHlzaXMtdHlwZT0wIGNvcHktcGljPTEgbWF4LWF1c2l6ZS1mYWN0b3I9MS4wIG5vLWR5bmFtaWMtcmVmaW5l
+        IG5vLXNpbmdsZS1zZWkgbm8taGV2Yy1hcSBuby1zdnQgbm8tZmllbGQgcXAtYWRhcHRhdGlvbi1yYW5nZT0xLjAwIHNjZW5lY3V0
+        LWF3YXJlLXFwPTBjb25mb3JtYW5jZS13aW5kb3ctb2Zmc2V0cyByaWdodD0wIGJvdHRvbT0wIGRlY29kZXItbWF4LXJhdGU9MCBu
+        by12YnYtbGl2ZS1tdWx0aS1wYXNzIG5vLW1jc3RmIG5vLXNicmMgbm8tZnJhbWUtcmOAAAAACmZpZWwBAAAAABBwYXNwAAAAAQAA
+        AAEAAAAUYnRydAAAAAAAAFZoAABWaAAAABhzdHRzAAAAAAAAAAEAAAAeAAABAAAAABRzdHNzAAAAAAAAAAEAAAABAAAAKnNkdHAA
+        AAAAIBAQGBgYEBAYGBgQEBgYGBAQGBgYEBAYGBgQEBgYAAAAHHN0c2MAAAAAAAAAAQAAAAEAAAAeAAAAAQAAAIxzdHN6AAAAAAAA
+        AAAAAAAeAAAEFQAAABUAAAAOAAAADwAAAA8AAAAOAAAALAAAAA8AAAAQAAAAEAAAAA8AAAAsAAAAEAAAABAAAAAQAAAADwAAADoA
+        AAAQAAAAEAAAABAAAAAPAAAALgAAABAAAAAQAAAAEAAAAA8AAAAuAAAAEAAAAA8AAAAPAAAAFHN0Y28AAAAAAAAAAQAADVIAAABi
+        dWR0YQAAAFptZXRhAAAAAAAAACFoZGxyAAAAAAAAAABtZGlyYXBwbAAAAAAAAAAAAAAAAC1pbHN0AAAAJal0b28AAAAdZGF0YQAA
+        AAEAAAAATGF2ZjYyLjEyLjEwMQAAAAhmcmVlAAAGg21kYXQAAAQRKAGsKYCoC2PeLG++3GQqYwPd5f4iYh0irT8tB7IqSXHt9aYS
+        3pMd85e6qfFPLmPrzOtW5kKQFnIBbc1MydWMNZHnyNpet0rgxNXjNkPiSCdRctOJmNboZXO3x//WaYP3Aq3x+xuQhmV0stHPZdcm
+        t5Jbna/QezfTDUUKoJwPS+5DmWJq9yw6gPeCyy1Rli+B4Uaxa0tsVKRIN5YnsFwCI3/P3LFhWQ1aulZViQoT/4lpsoXQXXUKsqQ1
+        G/jmT98sRqYV9OoAjm8GpBUioTmj3bkTXiDhlAX6da2TWpoxFZOqcNETPTflTcnZRJjTcqAyvaoYMPHFMywXDq05X6Klw+5LUC0m
+        /IRo1LpwAEX6dQqd6AMic6AKZUI9Znm7vmJQUJlPMTBWdxUiVdl5FhUt+Aukxa3ZF8pAQW5ql0lJa7DCNvwtqZKJviO6bfAN+tV0
+        zaPRskCedm8M7ojLfJp4/boaEq///9trlDjx6oCNe2I8TiPY/CgD6qXDF/1Ns/Pjv2jYMkPN+buRIG1PElW37KjK5VLSI8fBS/Iw
+        NmfWzMlJIfMPoQm3zMBouaAJCeUOYHTE9xl2KRPwOcs6TCcSW0VCQhefFSlomBwBIgI3UnQQz1HyVVmMr6tMSVFPe2zKSCztBKkO
+        3sx/RLk88SA0dTCYwwefoazaTXOldBEPrQO1yAxZ+iqmsAslyNmichJ397ob6lWVj4HKIoH5dM3hA8rrhOqTQ5tqehE2pajPeVnr
+        YlxmlH81gtpi9MT6bA16aeJ9eY2gdP3A+QLrPLMTgHsgqa3k6rkOOpyrF15SswW9JNzerZOCRpfqw5AXp6y1aKyNhsYUJsDfwWkR
+        RGgWlC5zzB1jy5gOFuMIIM07Ew6eKOwU2teliFSzdk1MDHXcAwI+F3vaFsNEYJmk7zRnh873ftuThZQx28rwlmuf4+Ab8qv6amuM
+        d/sC8/zxhfF0UbCQSENNgeDzCZVTj8B8T0BZUoKHPn//KdmxoyikLbd2e3sEJyR/0HOhkOZnEKzLIqflcKN10SX5bgj9Q7at1ZCO
+        MhQ5AzS+F+iLb4qsLQJQeIApndqD3H7Llw14c3T0vZL1cAAsiSs5yFCuCwHYC8T8A7WdBrQM7As8BpBZgSAlXnJN7TxLfvXv3wwH
+        VKsXaNTzxIiV4s0Xtyhve/TUT6JuZtAZMJ3cWxXsJluym+z1c6poBR/aMnWSyhTuqOLa/5vU443t7Y4MwVpe6gBypmgX9uCJmCBk
+        me8et61FbpkZ+Mgc4AQJVenBce5b8yAQWHWd5zBk4zRu2L0VK9vuSu7ZgHYo51UxzwMQCNJQ7a92ZThKFLyDmFT5gqeltYfIjka3
+        uHJDxujXGscwFPTQRj4LKfyFRuPy3xCSsS8YMYm+AAAAEQIB0ClLiBRAs1pEo6u+ZSuXAAAACgIB4GSdYIFkkngAAAALAAHgJPVe
+        iQMYkPAAAAALAAHgRNdeiQMIkPAAAAAKAAHghrfggYyQ8AAAACgCAdBQktXiBRCzWkFey1+VMBHdPUlsBUhuilioNQ9hOPghYTzW
+        H99wAAAACwIB4QInV1ggWZJ4AAAADAAB4Mb1VeiQMYCQ8AAAAAwAAeDm1XXokDCAkPAAAAALAAHhIi3XggYwkPAAAAAoAgHQeLLV
+        1iBRs1fdRSLNr7qLgw9k6qz4+0LjUk+0NRRyL70QOwEQgAAAAAwCAeGiJ1LWCBZAkngAAAAMAAHhZvVV6JAxgJDwAAAADAAB4YbV
+        deiQMICQ8AAAAAsAAeHCLdeCBjCQ8AAAADYCAdCgstXWIFGzWkXwn0I9zhHfu+OUlQywM4hhFO/Rgmzzdyv0TypArT007GQJ1LjP
+        L7Vu2TAAAAAMAgHiQidS1ggWwJJ4AAAADAAB4gb1VeiQMICQ8AAAAAwAAeIm1XXokDGAkPAAAAALAAHiYi3XggYwkPAAAAAqAgHQ
+        yLLV1iBTs1pF2UwP6z4eiZizCiXuyD+VkAZ8PmIohoKUP1a5rFLYAAAADAIB4uInUtYIFkCSeAAAAAwAAeKm9VXokDCAkPAAAAAM
+        AAHixtV16JAxgJDwAAAACwAB4wIt14IGMJDwAAAAKgIB0OiyVdYgUbNX33n2/kixaxBTSBJOYLe+rSsDXZK4kET9EzPm7DExEgAA
+        AAwCAeNiJVLWCBbAkngAAAALAAHjRvXXokDGkPAAAAALAAHjgi1XggYwkPA=
+        """
+}
diff --git a/docs/architecture.md b/docs/architecture.md
index 57c7f23f2..ec48d9057 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -483,7 +483,7 @@ Sources/AetherEngine/
 │   ├── PlanBoundaryAxis.swift               Which axis a container stamps its index entries on, and therefore which packet timestamp the cutter gate may compare against a plan boundary: decode for a mov/mp4 sample table, presentation for a Matroska Cue (#358, AE#561)
 │   ├── VideoConfigRecord.swift              The `hvcC` / `avcC` config record and the framing question hanging off it (#365): movenc decides whether to Annex-B-convert every sample from the EXTRADATA rather than the packet, so a source carrying Annex-B parameter sets while muxing length-prefixed NALs has each sample rewritten by a converter that finds no start codes. Mirrors movenc's own two tests instead of an equivalent-looking predicate, since predicting that decision wrong is the whole defect
 │   ├── H264SPS.swift                        Hand-rolled H.264 SPS parser (SSAI ad-creative coded dimensions / codec config)
-│   ├── H264CompositionOffsetRepair.swift    Rebuilds the presentation axis of an MP4 whose writer dropped `ctts` while the bitstream still reorders pictures: libavcodec's H.264 parser supplies each access unit's picture order count without decoding, a fail-closed head sample settles the ladder and the shift, and packets are rewritten to the timeline a correct muxer would have written, so the native path and hardware decode are kept (#409)
+│   ├── H264CompositionOffsetRepair.swift    Rebuilds the presentation axis of an MP4 whose writer dropped `ctts` while the bitstream still reorders pictures: libavcodec's H.264 or HEVC parser supplies each access unit's picture order count without decoding, a fail-closed head sample settles the ladder and the shift, and packets are rewritten to the timeline a correct muxer would have written, so the native path and hardware decode are kept (#409, HEVC #699)
 │   ├── OutputTimestampSanitizer.swift       Final-stage DTS/PTS monotonicity guard before the fMP4 mux (SSAI splices, program restarts)
 │   ├── RestartCoalescer.swift               Coalesces a burst of producer-restart requests into one in-flight + one settled target (rapid-seek, AetherEngine#35)
 │   ├── LiveWindow.swift                     Live path: session-relative DVR timeline (seconds since first frame), shared by the native and SW live paths
diff --git a/docs/formats.md b/docs/formats.md
index c5f7bf50c..14e4117ef 100644
--- a/docs/formats.md
+++ b/docs/formats.md
@@ -26,7 +26,7 @@ Interlaced sources (DVD-rip MPEG-2, SD / HD broadcast H.264) are deinterlaced th
 
 ### MP4 without composition offsets
 
-Some writers emit a sample table with no `ctts` while the H.264 bitstream still reorders pictures.
+Some writers emit a sample table with no `ctts` while the H.264 or HEVC bitstream still reorders pictures.
 Every sample then reports `PTS == DTS`, and since the native route stream-copies those timestamps
 into fMP4, AVPlayer is handed decode order as presentation order: each future reference picture is
 shown before the B pictures that precede it. Measured through AVFoundation's own decoder on a twin
@@ -34,8 +34,8 @@ pair (one encode muxed twice, composition offsets removed from one), 45 of 66 pi
 time belonging to a different picture, with the content order stepping backwards 30 times (#409).
 
 The container lost the information, but the bitstream did not: every slice header carries a picture
-order count, which is display order, and libavcodec's H.264 parser reads it without decoding a pixel
-and takes MP4's length-prefixed payload directly. `H264CompositionOffsetRepair` samples the head
+order count, which is display order, and libavcodec's H.264 and HEVC parsers read it without decoding
+a pixel and take MP4's length-prefixed payload directly. `H264CompositionOffsetRepair` samples the head
 (twelve pictures at most, held rather than re-read, so no rewind and no second fetch) and repairs a
 confirmed source at the demuxer boundary:
 
@@ -54,10 +54,12 @@ built from index entries and then filled with these packets.
 Detection is fail-closed and costs a healthy file almost nothing: the first real PTS-DTS offset ends
 the sample (usually on the first packet, since a reordered file's head sample sits one delay below
 zero). A source is only repaired when every sampled pair is equal, the decode ladder is uniform, the
-picture order regresses, and the ranks it produces are distinct and fill the sampled window. Anything
+picture order regresses, and the ranks it produces are distinct and fill the sampled window (or a
+decode-order prefix of at least nine pictures fills its own range exactly, which covers a
+hierarchical mini-GOP longer than the reorder delay, #699). Anything
 short of that (variable frame timing, a picture order that does not advance one rank per picture, a
 sample that starts nowhere it can be anchored) is delivered exactly as the container wrote it.
-Reported by @orut34iop.
+Reported by @orut34iop; the HEVC case (#699) by @ijuniorfu.
 
 ### Matroska with presentation slots in coding order
 

From b27f29713778c8465b5b13f022ef9ea08940736d Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Mon, 5 Oct 2026 21:21:10 +0200
Subject: [PATCH 318/359] chore(release): prep 7.27.3 - HEVC MP4s without
 composition offsets present in display order

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                    | 4 ++++
 Examples/README.md                              | 2 +-
 README.md                                       | 6 +++---
 Sources/AetherEngine/AetherEngine+Version.swift | 2 +-
 4 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d55d8313b..284e48575 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,10 @@ the public-API contract.
 
 ## [Unreleased]
 
+_Nothing yet._
+
+## [7.27.3] - 2026-10-05
+
 ### Fixed
 
 - **An HEVC MP4 without composition offsets is presented in display order (#699).** The #409 repair only armed on H.264, so an HEVC file whose writer dropped `ctts` while the bitstream reorders pictures went to AVPlayer and the software decoder in decode order, which shows as flicker and back-and-forth motion. The repair now reads the picture order count with libavcodec's HEVC parser as well, and its window check also accepts a hierarchical mini-GOP longer than the reorder delay (five pictures at delay 2 on the reporting asset). Measured on that asset (4K50 Main 10, 1500 frames): 0 backward steps in the served stream, against 35 of 88 in the first frames before. The partial-region repair stays H.264-only. Reported by ijuniorfu.
diff --git a/Examples/README.md b/Examples/README.md
index eb3ecd1a0..82f21af50 100644
--- a/Examples/README.md
+++ b/Examples/README.md
@@ -18,7 +18,7 @@ Three samples covering different audiences:
    ```
    https://github.com/superuser404notfound/AetherEngine
    ```
-   Dependency Rule: Up to Next Major Version, starting from `7.27.2`. Add the `AetherEngine` library product to your app target.
+   Dependency Rule: Up to Next Major Version, starting from `7.27.3`. Add the `AetherEngine` library product to your app target.
 
 3. **Drop the file in.** Replace the Xcode template's default `App.swift` (or whatever the generated `@main` file is called) with the contents of [`MinimalPlayerApp.swift`](MinimalPlayer/MinimalPlayerApp.swift). The file is self-contained: it defines both the `@main App` struct and the `ContentView`.
 
diff --git a/README.md b/README.md
index 9d5e78d28..57adfa9f3 100644
--- a/README.md
+++ b/README.md
@@ -385,7 +385,7 @@ Subtitle cues land in raw source PTS; render the overlay against `player.sourceT
 Install via Swift Package Manager:
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.27.2")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.27.3")
 ```
 
 Three samples ship in `Examples/`:
@@ -632,10 +632,10 @@ Browse all of this as a searchable site at **[aetherengine.superuser404.de](http
 AetherEngine uses [Semantic Versioning](https://semver.org). The public API surface, every `public` declaration in `Sources/AetherEngine/`, is the stability contract. **Major** removes / renames public symbols or breaks adopters; **Minor** adds public API or codec / format support; **Patch** fixes bugs with no public API change. `internal` types are not part of the contract.
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.27.2")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.27.3")
 ```
 
-Pin to `.upToNextMinor(from: "7.27.2")` for stricter teams that prefer to opt into minor bumps explicitly.
+Pin to `.upToNextMinor(from: "7.27.3")` for stricter teams that prefer to opt into minor bumps explicitly.
 
 ## Requirements
 
diff --git a/Sources/AetherEngine/AetherEngine+Version.swift b/Sources/AetherEngine/AetherEngine+Version.swift
index 5c1058490..a008c6f22 100644
--- a/Sources/AetherEngine/AetherEngine+Version.swift
+++ b/Sources/AetherEngine/AetherEngine+Version.swift
@@ -11,5 +11,5 @@ extension AetherEngine {
     ///
     /// Between releases, and in a consumer that pins an unreleased commit for a device test, this
     /// names the last PUBLISHED version the checkout descends from, not every patch in it.
-    public nonisolated static let version = "7.27.2"
+    public nonisolated static let version = "7.27.3"
 }

From bbdb254f08726d1893651db36bd82b169fc6eab4 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Mon, 5 Oct 2026 21:58:21 +0200
Subject: [PATCH 319/359] feat(probe): detect HDR Vivid (CUVA) carriage (#699)

ProbeDetail.hdrVivid scans HEVC packets for the CUVA T/UWA 005.1 T.35 SEI
and sets SourceProbe.carriesHDRVividMetadata. It shares the HDR10+ packet
pass and its HDR10PlusDetectionOptions budget, so asking for both opens
one connection, and a cap after one confirmation keeps it.

libavcodec's CUVA parser is internal, so HDRVividMetadataScan walks the
body with the same field widths over the shared NAL/SEI walk and counts
only a complete message with a defined system_start_code and zero bits
after its last field. videoFormat does not move: Vivid rides an HLG or PQ
base, which stays the label. Playback is unchanged.

aetherctl probe gains --detect-hdr-vivid; make-hdr10plus-fixture.py gains
--vivid, verified against ffprobe's CUVA side data. Measured: the CUVA
conformance stream B.1-04 and the new fixture report Vivid, the HDR10+
fixture reports HDR10+ only, a plain HEVC file neither.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                  |   4 +-
 README.md                                     |   2 +-
 Scripts/make-hdr10plus-fixture.py             |  47 ++++++-
 Sources/AetherEngine/AetherEngine+Probe.swift |  17 ++-
 Sources/AetherEngine/PlayerState.swift        |  10 ++
 .../Video/HDR10PlusDetectionProbe.swift       |  67 ++++++---
 .../Video/HDR10PlusMetadataScan.swift         |  20 +--
 .../Video/HDRVividMetadataScan.swift          | 112 +++++++++++++++
 Sources/aetherctl/Probe.swift                 |   4 +
 Sources/aetherctl/main.swift                  |   3 +-
 .../HDRVividProbeTests.swift                  | 128 ++++++++++++++++++
 docs/api.md                                   |   8 +-
 docs/cli.md                                   |   4 +-
 docs/formats.md                               |  16 +++
 14 files changed, 392 insertions(+), 50 deletions(-)
 create mode 100644 Sources/AetherEngine/Video/HDRVividMetadataScan.swift
 create mode 100644 Tests/AetherEngineTests/HDRVividProbeTests.swift

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 284e48575..6fb4f9626 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,7 +10,9 @@ the public-API contract.
 
 ## [Unreleased]
 
-_Nothing yet._
+### Added
+
+- **HDR Vivid (CUVA) detection in the opt-in probe (#699).** `ProbeDetail.hdrVivid` scans HEVC packets for the CUVA T/UWA 005.1 T.35 SEI and sets the new `SourceProbe.carriesHDRVividMetadata`. It runs in the same packet pass as `.hdr10Plus` and under the same `HDR10PlusDetectionOptions` budget; asking for both still opens one connection, and a cap that ends the pass after one of the two was confirmed keeps that confirmation. libavcodec's CUVA parser is internal, so `HDRVividMetadataScan` walks the body with the same field widths and only counts a complete message with a defined `system_start_code` and zero bits after its last field. `videoFormat` does not move (Vivid rides an HLG or PQ base, which stays the label), and playback is unchanged: the SEI is stream-copied as before and no Apple platform applies it. `aetherctl probe --detect-hdr-vivid` prints the finding, and `Scripts/make-hdr10plus-fixture.py --vivid` builds a fixture ffprobe parses as Vivid. Requested by ijuniorfu.
 
 ## [7.27.3] - 2026-10-05
 
diff --git a/README.md b/README.md
index 57adfa9f3..3f51159fc 100644
--- a/README.md
+++ b/README.md
@@ -64,7 +64,7 @@ A scannable summary; the depth for each row lives in **[docs/formats.md](docs/fo
 | Disc | DVD-Video and Blu-ray ISO (decrypted): selectable titles and chapters, demuxed through the normal path |
 | Video (HW) | H.264, HEVC, HEVC Main10 via VideoToolbox; AV1 Main profile where HW AV1 exists |
 | Video (SW) | AV1 (dav1d) without HW, and AV1 High / Professional (4:4:4, 4:2:2, 12-bit) everywhere, VP9 / VP8, MPEG-4 Part 2 / MPEG-2 / VC-1, QuickTime RLE, the Flash tail (Sorenson Spark, On2 VP6) and anything else the FFmpeg build carries a decoder for (software is the default route; only HEVC, H.264 and HW-decodable AV1 go native), H.264 High 4:2:2 / 4:4:4 / 10 and HEVC Rext where VideoToolbox has no HW decoder (Intel Macs, older chips), interlaced H.264 (AVPlayer does not deinterlace; on VOD the declared field order is verified against decoded frames, so progressive-in-interlaced-carriage keeps hardware decode); GPU deinterlace (yadif_videotoolbox, Metal, field-rate by default) with a CPU bwdif fallback |
-| HDR | HDR10, HDR10+ (per-frame ST 2094-40), Dolby Vision (P5, P7 as single-layer 8.1, P8.1, P8.4, AV1 P10.x), HLG |
+| HDR | HDR10, HDR10+ (per-frame ST 2094-40), Dolby Vision (P5, P7 as single-layer 8.1, P8.1, P8.4, AV1 P10.x), HLG, HDR Vivid (played on its HLG / PQ base, CUVA metadata reported by `probe`) |
 | Audio | AAC, AC3, EAC3, FLAC, ALAC stream-copy lossless; TrueHD / MLP / DTS / DTS-HD MA / MP3 / MP2 / Opus / Vorbis / LPCM (incl. Blu-ray, G.711) / WMA (Standard, Pro, Lossless, Voice) / Nellymoser / ADPCM-SWF / Speex bridge to EAC3 5.1 (default) or lossless FLAC |
 | Dolby Atmos | EAC3+JOC stream-copied on every route (HDMI MAT 2.0, AirPods spatial, BT downmix). No container reliably declares JOC pre-decode, so an honest `TrackInfo.isAtmos` needs a bounded decode: `AetherEngine.probeDetectingAtmos(url:/source:)` answers for a details screen without starting playback, and `LoadOptions.confirmAtmos` has the running session confirm its own tracks in the background and republish `audioTracks`. Both are opt-in and neither sits on the playback-start path |
 | Surround | 5.1 / 7.1 with correct `AudioChannelLayout` |
diff --git a/Scripts/make-hdr10plus-fixture.py b/Scripts/make-hdr10plus-fixture.py
index 9dd4f33da..015ceaaa5 100755
--- a/Scripts/make-hdr10plus-fixture.py
+++ b/Scripts/make-hdr10plus-fixture.py
@@ -1,6 +1,9 @@
 #!/usr/bin/env python3
 """Build a tiny HEVC/PQ MP4 that carries a real ST 2094-40 (HDR10+) T.35 SEI.
 
+With `--vivid` it builds an HEVC/HLG MP4 carrying a CUVA HDR Vivid T.35 SEI instead, laid out as
+libavcodec/dynamic_hdr_vivid.c parses it, and verified by ffprobe reporting "CUVA" (#699).
+
 Layout of the payload follows libavutil/hdr_dynamic_metadata.c's parser exactly, so
 `ffprobe -show_frames` reporting "HDR Dynamic Metadata SMPTE2094-40" is the proof the
 fixture is genuine rather than a byte pattern that merely looks like one.
@@ -57,6 +60,31 @@ def hdr10plus_payload():
     return header + body
 
 
+def hdr_vivid_payload():
+    w = BitWriter()
+    w.u(8, 1)            # system_start_code
+    for value in (0, 3046, 1535, 4095):
+        w.u(12, value)   # minimum / average / variance / maximum maxrgb
+    w.u(1, 1)            # tone_mapping_mode_flag
+    w.u(1, 0)            # tone_mapping_param_num - 1
+    w.u(12, 2770)        # targeted_system_display_maximum_luminance
+    w.u(1, 1)            # base_enable_flag
+    for bits, value in ((14, 5734), (6, 24), (10, 510), (10, 0), (6, 10), (2, 1), (2, 1), (4, 1), (3, 0), (7, 0)):
+        w.u(bits, value)
+    w.u(1, 1)            # 3Spline_enable_flag
+    w.u(1, 0)            # 3Spline_num - 1
+    w.u(2, 0)            # 3Spline_TH_mode
+    w.u(8, 224)          # 3Spline_TH_enable_MB
+    for bits, value in ((12, 0), (10, 511), (10, 511), (8, 127)):
+        w.u(bits, value)
+    w.u(1, 1)            # color_saturation_mapping_flag
+    w.u(3, 2)            # color_saturation_num
+    w.u(8, 38)
+    w.u(8, 25)
+    header = bytes([0x26, 0x00, 0x04, 0x00, 0x05])
+    return header + w.bytes()
+
+
 def emulation_prevent(rbsp):
     out = bytearray()
     zeros = 0
@@ -111,18 +139,20 @@ def nal_type(nal):
 
 
 def main():
-    out_dir = sys.argv[1]
+    vivid = "--vivid" in sys.argv[1:]
+    out_dir = [a for a in sys.argv[1:] if a != "--vivid"][0]
+    transfer = ("18", "arib-std-b67") if vivid else ("16", "smpte2084")
     plain = os.path.join(out_dir, "plain.mp4")
     annexb = os.path.join(out_dir, "plain.hevc")
     injected = os.path.join(out_dir, "injected.hevc")
-    fixture = os.path.join(out_dir, "hdr10plus-hevc.mp4")
+    fixture = os.path.join(out_dir, "hdr-vivid-hevc.mp4" if vivid else "hdr10plus-hevc.mp4")
 
     subprocess.run([
         "ffmpeg", "-y", "-v", "error",
         "-f", "lavfi", "-i", "color=c=black:s=64x64:r=10:d=0.2",
         "-c:v", "libx265", "-pix_fmt", "yuv420p10le",
-        "-x265-params", "log-level=none:info=0:keyint=1:min-keyint=1:colorprim=9:transfer=16:colormatrix=9",
-        "-color_primaries", "bt2020", "-color_trc", "smpte2084", "-colorspace", "bt2020nc",
+        "-x265-params", "log-level=none:info=0:keyint=1:min-keyint=1:colorprim=9:transfer=" + transfer[0] + ":colormatrix=9",
+        "-color_primaries", "bt2020", "-color_trc", transfer[1], "-colorspace", "bt2020nc",
         "-frames:v", "2", plain,
     ], check=True)
 
@@ -132,7 +162,7 @@ def main():
     ], check=True)
 
     data = open(annexb, "rb").read()
-    payload = hdr10plus_payload()
+    payload = hdr_vivid_payload() if vivid else hdr10plus_payload()
     sei = sei_nal(payload)
     out = bytearray()
     for nal in split_annexb(data):
@@ -150,10 +180,13 @@ def main():
         "ffprobe", "-v", "error", "-select_streams", "v:0", "-show_frames",
         "-show_entries", "frame=side_data_list", fixture,
     ], capture_output=True, text=True)
-    ok = "SMPTE2094-40" in probe.stdout or "HDR10+" in probe.stdout
+    if vivid:
+        ok = "CUVA" in probe.stdout
+    else:
+        ok = "SMPTE2094-40" in probe.stdout or "HDR10+" in probe.stdout
     print(probe.stdout[:600])
     print("SIZE:", os.path.getsize(fixture), "bytes")
-    print("HDR10+ PARSED BY FFMPEG:", ok)
+    print("HDR VIVID" if vivid else "HDR10+", "PARSED BY FFMPEG:", ok)
     if ok:
         print("BASE64_START")
         print(base64.b64encode(open(fixture, "rb").read()).decode())
diff --git a/Sources/AetherEngine/AetherEngine+Probe.swift b/Sources/AetherEngine/AetherEngine+Probe.swift
index 73db43b4e..49d4c9aec 100644
--- a/Sources/AetherEngine/AetherEngine+Probe.swift
+++ b/Sources/AetherEngine/AetherEngine+Probe.swift
@@ -109,7 +109,9 @@ extension AetherEngine {
     /// - **Dolby Atmos**, which for E-AC-3 means the JOC flag in the dependent substream and only exists
     ///   post-decode (`.atmos`, see `AtmosDetectionOptions`), and
     /// - **HDR10+**, whose ST 2094-40 metadata rides an in-band ITU-T T.35 SEI that no demuxer parses
-    ///   (`.hdr10Plus`, see `HDR10PlusDetectionOptions`).
+    ///   (`.hdr10Plus`, see `HDR10PlusDetectionOptions`), and
+    /// - **HDR Vivid**, whose CUVA metadata rides the same kind of SEI in HEVC (`.hdrVivid`, scanned in
+    ///   the same pass and under the same `HDR10PlusDetectionOptions` budget).
     ///
     /// Both cost reads past `avformat_find_stream_info`, which is why `probe(url:)` does neither.
     /// Neither is for the playback-start critical path. Asking for both runs both
@@ -117,7 +119,7 @@ extension AetherEngine {
     /// queued, then the queue-flushing seek the Atmos decode pass needs.
     ///
     /// Both passes are additive and one-directional. They can only ever SET `isAtmos` /
-    /// `carriesHDR10PlusMetadata`, never clear what the container already declared, and a pass that hits a cap
+    /// `carriesHDR10PlusMetadata` / `carriesHDRVividMetadata`, never clear what the container already declared, and a pass that hits a cap
     /// leaves the base probe's answer exactly where it was.
     ///
     /// - Parameters:
@@ -125,7 +127,7 @@ extension AetherEngine {
     ///   - options: Forwarded verbatim to `probe(url:)` (`httpHeaders` only).
     ///   - detecting: Which extra passes to run. Empty is the header probe with the same controls.
     ///   - atmosDetection: Bounds + optional track override for the Atmos decode pass. Ignored without `.atmos`.
-    ///   - hdr10PlusDetection: Bounds for the HDR10+ scan. Ignored without `.hdr10Plus`.
+    ///   - hdr10PlusDetection: Bounds for the HDR10+ / HDR Vivid scan. Ignored without either.
     ///   - limits: Whole-probe limits, shared across open, stream analysis, seeks and both passes.
     ///   - cancellation: Cancellation reaches HTTP I/O or the custom reader's `cancel()`.
     /// - Throws: Open errors, `ProbeError` for whole-probe stops, or `CancellationError`. Ordinary
@@ -216,13 +218,18 @@ extension AetherEngine {
         // HDR10+ first, and before any seek: `avformat_find_stream_info` leaves its packets queued and
         // `av_read_frame` hands those back first, so at the head of a container the scan gets video packets
         // that have already been paid for. Running it after the Atmos pass would mean re-reading them.
-        if detecting.contains(.hdr10Plus) {
+        let dynamicTargets = detecting.intersection([.hdr10Plus, .hdrVivid])
+        if !dynamicTargets.isEmpty {
             let outcome = Self.detectHDR10Plus(
-                demuxer: demuxer, videoIndex: demuxer.videoStreamIndex, options: hdr10PlusDetection)
+                demuxer: demuxer, videoIndex: demuxer.videoStreamIndex, options: hdr10PlusDetection,
+                targets: dynamicTargets)
             try control?.check()
             if outcome.carriesHDR10Plus {
                 probe = Self.enrichHDR10Plus(base: probe)
             }
+            if outcome.carriesHDRVivid {
+                probe.carriesHDRVividMetadata = true
+            }
         }
 
         let targetIndex = Self.atmosDecodeTargetIndex(
diff --git a/Sources/AetherEngine/PlayerState.swift b/Sources/AetherEngine/PlayerState.swift
index 228a33a95..7f56260db 100644
--- a/Sources/AetherEngine/PlayerState.swift
+++ b/Sources/AetherEngine/PlayerState.swift
@@ -1019,6 +1019,14 @@ public struct SourceProbe: Sendable {
     /// Separate from `videoFormat == .hdr10Plus` because a Dolby Vision source can carry an HDR10+ layer too
     /// (Blu-ray Profile 7 and the 8.1 remuxes of it), and that source keeps reading `.dolbyVision`.
     public internal(set) var carriesHDR10PlusMetadata: Bool
+    /// HDR Vivid (CUVA T/UWA 005.1) dynamic metadata was SEEN in this source's HEVC video (#699).
+    ///
+    /// Same contract as `carriesHDR10PlusMetadata`: always `false` unless the probe was asked for
+    /// `.hdrVivid`, and `false` never means "proven absent". `videoFormat` does not move: HDR Vivid rides
+    /// an HLG or PQ base layer, the display is switched for that base, and the label keeps saying
+    /// `.hlg` / `.hdr10`. Apple platforms do not apply the dynamic metadata; the flag exists so a host can
+    /// label the source.
+    public internal(set) var carriesHDRVividMetadata: Bool
     /// Settable inside the module so `probeDetectingAtmos` can enrich one track without rebuilding the struct field by field.
     public internal(set) var audioTracks: [TrackInfo]
     /// Includes both text and bitmap (PGS / DVB) variants.
@@ -1039,6 +1047,7 @@ public struct SourceProbe: Sendable {
         isDolbyVision: Bool,
         dvProfile: Int? = nil,
         carriesHDR10PlusMetadata: Bool = false,
+        carriesHDRVividMetadata: Bool = false,
         audioTracks: [TrackInfo],
         subtitleTracks: [TrackInfo],
         metadata: MediaMetadata = MediaMetadata(title: nil, artist: nil, album: nil, artworkData: nil),
@@ -1057,6 +1066,7 @@ public struct SourceProbe: Sendable {
         self.isDolbyVision = isDolbyVision
         self.dvProfile = dvProfile
         self.carriesHDR10PlusMetadata = carriesHDR10PlusMetadata
+        self.carriesHDRVividMetadata = carriesHDRVividMetadata
         self.audioTracks = audioTracks
         self.subtitleTracks = subtitleTracks
         self.metadata = metadata
diff --git a/Sources/AetherEngine/Video/HDR10PlusDetectionProbe.swift b/Sources/AetherEngine/Video/HDR10PlusDetectionProbe.swift
index 87ea1fb94..29f2e810c 100644
--- a/Sources/AetherEngine/Video/HDR10PlusDetectionProbe.swift
+++ b/Sources/AetherEngine/Video/HDR10PlusDetectionProbe.swift
@@ -3,8 +3,9 @@ import AetherLibavformat
 import AetherLibavcodec
 import AetherLibavutil
 
-/// Bounds for the pre-playback HDR10+ (ST 2094-40) carriage scan, `AetherEngine.probe(url:detecting:)` with
-/// `.hdr10Plus`.
+/// Bounds for the pre-playback dynamic HDR metadata scan, `AetherEngine.probe(url:detecting:)` with
+/// `.hdr10Plus` (ST 2094-40) and/or `.hdrVivid` (CUVA). Both run in one pass over the same packets and
+/// share these bounds.
 ///
 /// Separate from `LoadOptions` and from the lightweight `probe(url:)` path, exactly like
 /// `AtmosDetectionOptions`: a host opts into reading real video packets without the default probe changing
@@ -69,11 +70,22 @@ struct HDR10PlusDetectionOutcome: Sendable, Equatable {
     let stopReason: StopReason
     let packetsRead: Int
     let bytesRead: Int64
+    /// What the pass confirmed. `.found` means every requested format was; a cap can still end a pass
+    /// that confirmed one of two, and that confirmation stands. Defaults to the single-target reading.
+    let found: ProbeDetail
 
-    /// A negative is never authoritative and is never published as one: only `.found` sets the flag, and the
-    /// flag is only ever set, never cleared. Every other reason means "not seen inside this budget", which
-    /// for a cap is genuinely inconclusive and for EOF is only as conclusive as the source is short.
-    var carriesHDR10Plus: Bool { stopReason == .found }
+    init(stopReason: StopReason, packetsRead: Int, bytesRead: Int64, found: ProbeDetail? = nil) {
+        self.stopReason = stopReason
+        self.packetsRead = packetsRead
+        self.bytesRead = bytesRead
+        self.found = found ?? (stopReason == .found ? .hdr10Plus : [])
+    }
+
+    /// A negative is never authoritative and is never published as one: only a validated payload sets a
+    /// flag, and a flag is only ever set, never cleared. Not found means "not seen inside this budget",
+    /// which for a cap is genuinely inconclusive and for EOF is only as conclusive as the source is short.
+    var carriesHDR10Plus: Bool { found.contains(.hdr10Plus) }
+    var carriesHDRVivid: Bool { found.contains(.hdrVivid) }
 }
 
 /// Which extra, strictly more expensive detail a probe should resolve on top of the container metadata.
@@ -90,6 +102,10 @@ public struct ProbeDetail: OptionSet, Sendable {
 
     /// HDR10+ (ST 2094-40) carriage via a bounded packet scan. See `HDR10PlusDetectionOptions`.
     public static let hdr10Plus = ProbeDetail(rawValue: 1 << 1)
+
+    /// HDR Vivid (CUVA T/UWA 005.1) carriage in HEVC via the same bounded packet scan as `.hdr10Plus`,
+    /// sharing its `HDR10PlusDetectionOptions` budget. See `SourceProbe.carriesHDRVividMetadata`.
+    public static let hdrVivid = ProbeDetail(rawValue: 1 << 2)
 }
 
 extension AetherEngine {
@@ -135,8 +151,9 @@ extension AetherEngine {
         detected == .hdr10 ? .hdr10Plus : detected
     }
 
-    /// Bounded scan for HDR10+ carriage on `videoIndex`. Opens no decoder: it reads demuxed packets and asks
-    /// `HDR10PlusMetadataScan` about each one, stopping at the first hit or the first cap.
+    /// Bounded scan for HDR10+ and/or HDR Vivid carriage on `videoIndex` (`targets`). Opens no decoder: it
+    /// reads demuxed packets and asks `HDR10PlusMetadataScan` / `HDRVividMetadataScan` about each one,
+    /// stopping once every target is confirmed or at the first cap.
     ///
     /// Deliberately runs BEFORE any queue-flushing seek, unlike `detectAtmos`. `avformat_find_stream_info`
     /// leaves the packets it read queued, `av_read_frame` hands those back first, and at the head of a
@@ -150,8 +167,10 @@ extension AetherEngine {
         demuxer: Demuxer,
         videoIndex: Int32,
         options: HDR10PlusDetectionOptions,
+        targets: ProbeDetail = .hdr10Plus,
         now: () -> UInt64 = { DispatchTime.now().uptimeNanoseconds }
     ) -> HDR10PlusDetectionOutcome {
+        let targets = targets.intersection([.hdr10Plus, .hdrVivid])
         guard videoIndex >= 0, let stream = demuxer.stream(at: videoIndex),
               let codecpar = stream.pointee.codecpar,
               codecpar.pointee.codec_type == AVMEDIA_TYPE_VIDEO else {
@@ -175,13 +194,15 @@ extension AetherEngine {
         var packetsRead = 0
         var bytesRead: Int64 = 0
         var packetsSeen = 0
+        var found: ProbeDetail = []
         let fuse = Self.hdr10PlusForeignPacketFuse(maxPackets: options.maxPackets)
 
         while true {
             if let cap = Self.hdr10PlusScanCapReached(
                 packetsRead: packetsRead, bytesRead: bytesRead, elapsed: elapsed(), options: options
             ) {
-                return HDR10PlusDetectionOutcome(stopReason: cap, packetsRead: packetsRead, bytesRead: bytesRead)
+                return HDR10PlusDetectionOutcome(
+                    stopReason: cap, packetsRead: packetsRead, bytesRead: bytesRead, found: found)
             }
 
             let packet: UnsafeMutablePointer<AVPacket>?
@@ -189,7 +210,7 @@ extension AetherEngine {
                 packet = try demuxer.readPacket()
             } catch {
                 return HDR10PlusDetectionOutcome(
-                    stopReason: readEnded(.demuxError), packetsRead: packetsRead, bytesRead: bytesRead)
+                    stopReason: readEnded(.demuxError), packetsRead: packetsRead, bytesRead: bytesRead, found: found)
             }
             defer {
                 if let packet {
@@ -199,46 +220,52 @@ extension AetherEngine {
             }
             guard elapsed() < options.timeBudget else {
                 return HDR10PlusDetectionOutcome(
-                    stopReason: .timeCap, packetsRead: packetsRead, bytesRead: bytesRead)
+                    stopReason: .timeCap, packetsRead: packetsRead, bytesRead: bytesRead, found: found)
             }
             guard let pkt = packet else {
                 return HDR10PlusDetectionOutcome(
-                    stopReason: readEnded(.demuxEOF), packetsRead: packetsRead, bytesRead: bytesRead)
+                    stopReason: readEnded(.demuxEOF), packetsRead: packetsRead, bytesRead: bytesRead, found: found)
             }
 
-            var found = false
             packetsSeen += 1
             if pkt.pointee.stream_index == videoIndex {
                 let packetBytes = Int64(pkt.pointee.size)
                 guard packetBytes >= 0 else {
                     return HDR10PlusDetectionOutcome(
-                        stopReason: .demuxError, packetsRead: packetsRead, bytesRead: bytesRead)
+                    stopReason: .demuxError, packetsRead: packetsRead, bytesRead: bytesRead, found: found)
                 }
                 guard packetBytes <= options.maxBytes - bytesRead else {
                     return HDR10PlusDetectionOutcome(
-                        stopReason: .byteCap, packetsRead: packetsRead, bytesRead: bytesRead)
+                    stopReason: .byteCap, packetsRead: packetsRead, bytesRead: bytesRead, found: found)
                 }
                 packetsRead += 1
                 bytesRead += packetBytes
-                found = HDR10PlusMetadataScan.packetCarriesHDR10Plus(pkt, codecParameters: codecpar)
+                if targets.contains(.hdr10Plus), !found.contains(.hdr10Plus),
+                   HDR10PlusMetadataScan.packetCarriesHDR10Plus(pkt, codecParameters: codecpar) {
+                    found.insert(.hdr10Plus)
+                }
+                if targets.contains(.hdrVivid), !found.contains(.hdrVivid),
+                   HDRVividMetadataScan.packetCarriesHDRVivid(pkt, codecParameters: codecpar) {
+                    found.insert(.hdrVivid)
+                }
             }
             // Evidence in hand outranks the soft budget. The caps exist to bound what this pass SPENDS,
             // and a confirmation is already paid for; dropping it would turn an overrun into a false
             // negative on a slow origin, which the caller cannot tell apart from "this source has none".
-            if found {
+            if !targets.isEmpty, found.isSuperset(of: targets) {
                 return HDR10PlusDetectionOutcome(
-                    stopReason: .found, packetsRead: packetsRead, bytesRead: bytesRead)
+                    stopReason: .found, packetsRead: packetsRead, bytesRead: bytesRead, found: found)
             }
 
             guard elapsed() < options.timeBudget else {
                 return HDR10PlusDetectionOutcome(
-                    stopReason: .timeCap, packetsRead: packetsRead, bytesRead: bytesRead)
+                    stopReason: .timeCap, packetsRead: packetsRead, bytesRead: bytesRead, found: found)
             }
 
             // AVDISCARD_ALL is advisory, so a container that keeps handing back foreign packets still ends.
             if packetsSeen >= fuse {
                 return HDR10PlusDetectionOutcome(
-                    stopReason: .packetCap, packetsRead: packetsRead, bytesRead: bytesRead)
+                    stopReason: .packetCap, packetsRead: packetsRead, bytesRead: bytesRead, found: found)
             }
         }
     }
diff --git a/Sources/AetherEngine/Video/HDR10PlusMetadataScan.swift b/Sources/AetherEngine/Video/HDR10PlusMetadataScan.swift
index 4f7d7f817..4dd233c18 100644
--- a/Sources/AetherEngine/Video/HDR10PlusMetadataScan.swift
+++ b/Sources/AetherEngine/Video/HDR10PlusMetadataScan.swift
@@ -49,7 +49,7 @@ enum HDR10PlusMetadataScan {
         let bytes = UnsafeBufferPointer(start: data, count: size)
         switch codecID {
         case AV_CODEC_ID_H264, AV_CODEC_ID_HEVC:
-            return scanNALs(bytes, codecID: codecID, framing: framing)
+            return scanNALs(bytes, codecID: codecID, framing: framing, payload: validT35)
         case AV_CODEC_ID_AV1:
             return scanOBUs(bytes)
         default:
@@ -71,9 +71,11 @@ enum HDR10PlusMetadataScan {
     /// A walk that runs into malformed framing stops and reports what it had already VALIDATED, rather
     /// than discarding it. Only `validT35` ever sets the answer, so an aborted walk cannot invent one;
     /// abandoning a confirmed payload because a later NAL in the same packet is malformed would be a
-    /// false negative on the one carriage this scan exists to find.
-    private static func scanNALs(
-        _ bytes: UnsafeBufferPointer<UInt8>, codecID: AVCodecID, framing: VideoNALFraming
+    /// false negative on the one carriage this scan exists to find. `payload` validates one registered
+    /// T.35 message (its bytes start at the country code), so HDR Vivid shares this walk.
+    static func scanNALs(
+        _ bytes: UnsafeBufferPointer<UInt8>, codecID: AVCodecID, framing: VideoNALFraming,
+        payload: (UnsafePointer<UInt8>, Int) -> Bool
     ) -> Bool {
         var found = false
         func visit(_ start: Int, _ end: Int) -> Bool {
@@ -90,7 +92,7 @@ enum HDR10PlusMetadataScan {
             }
             guard isSEI else { return true }
             guard let rbsp = unescape(bytes, start: start + headerSize, end: end),
-                  let carriesMetadata = scanSEI(rbsp) else { return false }
+                  let carriesMetadata = scanSEI(rbsp, payload: payload) else { return false }
             found = found || carriesMetadata
             return true
         }
@@ -155,7 +157,7 @@ enum HDR10PlusMetadataScan {
     /// Nil denotes malformed SEI framing; false is a well-formed SEI without HDR10+. A message this
     /// walk has already VALIDATED outranks framing it cannot finish reading, so nil is only ever the
     /// answer when nothing was confirmed.
-    private static func scanSEI(_ bytes: [UInt8]) -> Bool? {
+    private static func scanSEI(_ bytes: [UInt8], payload: (UnsafePointer<UInt8>, Int) -> Bool) -> Bool? {
         var offset = 0
         var found = false
         func extendedValue() -> Int? {
@@ -176,7 +178,7 @@ enum HDR10PlusMetadataScan {
                   size <= bytes.count - offset else { return found ? true : nil }
             if type == 4 {
                 let valid = bytes.withUnsafeBufferPointer {
-                    validT35($0.baseAddress! + offset, size: size)
+                    payload($0.baseAddress! + offset, size)
                 }
                 found = found || valid
             }
@@ -217,7 +219,7 @@ enum HDR10PlusMetadataScan {
                     var trailing = end
                     while trailing > offset, bytes[trailing - 1] == 0 { trailing -= 1 }
                     guard trailing > offset, bytes[trailing - 1] == 0x80 else { return found }
-                    found = validT35(bytes.baseAddress! + offset, size: trailing - offset - 1) || found
+                    found = validT35(bytes.baseAddress! + offset, trailing - offset - 1) || found
                 }
             }
             offset = end
@@ -244,7 +246,7 @@ enum HDR10PlusMetadataScan {
 
     // MARK: - Complete ST 2094-40 validation
 
-    private static func validT35(_ bytes: UnsafePointer<UInt8>, size: Int) -> Bool {
+    private static func validT35(_ bytes: UnsafePointer<UInt8>, _ size: Int) -> Bool {
         guard size > t35Header.count, size - t35Header.count <= Int(AV_HDR_PLUS_MAX_PAYLOAD_SIZE),
               t35Header.indices.allSatisfy({ bytes[$0] == t35Header[$0] }),
               let metadata = av_dynamic_hdr_plus_alloc(nil) else { return false }
diff --git a/Sources/AetherEngine/Video/HDRVividMetadataScan.swift b/Sources/AetherEngine/Video/HDRVividMetadataScan.swift
new file mode 100644
index 000000000..77c78af1f
--- /dev/null
+++ b/Sources/AetherEngine/Video/HDRVividMetadataScan.swift
@@ -0,0 +1,112 @@
+import Foundation
+import AetherLibavcodec
+import AetherLibavutil
+
+/// Decoder-free HDR Vivid (CUVA T/UWA 005.1) confirmation for the detail probe (#699).
+///
+/// HDR Vivid's dynamic metadata rides a registered ITU-T T.35 SEI in HEVC: country code 0x26 (China),
+/// terminal provider code 0x0004, provider oriented code 0x0005, then the CUVA body. No container
+/// declares it and no demuxer lifts it into packet side data, so like HDR10+ it is only visible in the
+/// packet payload. FFmpeg's own body parser is internal (`ff_parse_itu_t_t35_to_dynamic_hdr_vivid`),
+/// so the body is walked here with the same field widths, and a message only counts when it is
+/// complete and every bit after its last field is zero. A marker alone is not proof.
+///
+/// HEVC only, matching libavcodec, which ignores this payload on every other codec.
+enum HDRVividMetadataScan {
+    private static let t35Header: [UInt8] = [0x26, 0x00, 0x04, 0x00, 0x05]
+
+    static func packetCarriesHDRVivid(
+        _ packet: UnsafePointer<AVPacket>,
+        codecParameters: UnsafePointer<AVCodecParameters>
+    ) -> Bool {
+        let parameters = codecParameters.pointee
+        guard parameters.codec_id == AV_CODEC_ID_HEVC else { return false }
+        let framing: VideoNALFraming = NALUnitChain.lengthPrefixSize(
+            codecID: parameters.codec_id,
+            extradata: parameters.extradata,
+            extradataSize: Int(parameters.extradata_size)
+        ).map { .lengthPrefixed(size: $0) } ?? .annexB
+        return bytesCarryHDRVivid(packet.pointee.data, size: Int(packet.pointee.size), framing: framing)
+    }
+
+    static func bytesCarryHDRVivid(
+        _ data: UnsafePointer<UInt8>?, size: Int, framing: VideoNALFraming = .annexB
+    ) -> Bool {
+        guard let data, size >= t35Header.count,
+              t35Header.withUnsafeBufferPointer({ memmem(data, size, $0.baseAddress, $0.count) != nil })
+        else { return false }
+        return HDR10PlusMetadataScan.scanNALs(
+            UnsafeBufferPointer(start: data, count: size),
+            codecID: AV_CODEC_ID_HEVC, framing: framing, payload: validT35)
+    }
+
+    private static func validT35(_ bytes: UnsafePointer<UInt8>, _ size: Int) -> Bool {
+        guard size > t35Header.count,
+              t35Header.indices.allSatisfy({ bytes[$0] == t35Header[$0] }) else { return false }
+        return bodyIsComplete(UnsafeBufferPointer(start: bytes + t35Header.count, count: size - t35Header.count))
+    }
+
+    /// The CUVA body, field for field as libavcodec's `dynamic_hdr_vivid.c` reads it. Only
+    /// `system_start_code` 1 to 7 has a defined syntax (T/UWA 005.1-2022, table 11), so any other value
+    /// is not evidence of this format.
+    static func bodyIsComplete(_ body: UnsafeBufferPointer<UInt8>) -> Bool {
+        var reader = BitReader(body)
+        guard let startCode = reader.read(8), (1...7).contains(startCode),
+              reader.skip(4 * 12),
+              let toneMapping = reader.read(1) else { return false }
+        if toneMapping == 1 {
+            guard let extraParams = reader.read(1) else { return false }
+            for _ in 0...extraParams {
+                guard reader.skip(12), let baseEnable = reader.read(1) else { return false }
+                if baseEnable == 1, !reader.skip(14 + 6 + 10 + 10 + 6 + 2 + 2 + 4 + 3 + 7) { return false }
+                guard let splineEnable = reader.read(1) else { return false }
+                if splineEnable == 1 {
+                    guard let extraSplines = reader.read(1) else { return false }
+                    for _ in 0...extraSplines {
+                        guard let mode = reader.read(2) else { return false }
+                        if mode == 0 || mode == 2, !reader.skip(8) { return false }
+                        guard reader.skip(12 + 10 + 10 + 8) else { return false }
+                    }
+                }
+            }
+        }
+        guard let saturationMapping = reader.read(1) else { return false }
+        if saturationMapping == 1 {
+            guard let gains = reader.read(3), reader.skip(gains * 8) else { return false }
+        }
+        return reader.remainderIsZero
+    }
+
+    private struct BitReader {
+        let bytes: UnsafeBufferPointer<UInt8>
+        private(set) var position = 0
+
+        init(_ bytes: UnsafeBufferPointer<UInt8>) { self.bytes = bytes }
+
+        mutating func read(_ count: Int) -> Int? {
+            guard count <= bytes.count * 8 - position else { return nil }
+            var value = 0
+            for _ in 0..<count {
+                let bit = (bytes[position >> 3] >> (7 - UInt8(position & 7))) & 1
+                value = (value << 1) | Int(bit)
+                position += 1
+            }
+            return value
+        }
+
+        mutating func skip(_ count: Int) -> Bool {
+            guard count <= bytes.count * 8 - position else { return false }
+            position += count
+            return true
+        }
+
+        var remainderIsZero: Bool {
+            var index = position
+            while index < bytes.count * 8 {
+                if (bytes[index >> 3] >> (7 - UInt8(index & 7))) & 1 != 0 { return false }
+                index += 1
+            }
+            return true
+        }
+    }
+}
diff --git a/Sources/aetherctl/Probe.swift b/Sources/aetherctl/Probe.swift
index 05727c79f..079a3a347 100644
--- a/Sources/aetherctl/Probe.swift
+++ b/Sources/aetherctl/Probe.swift
@@ -9,6 +9,7 @@ func runProbe(url: URL, detecting: ProbeDetail = []) -> Int32 {
     if !detecting.isEmpty {
         var passes: [String] = []
         if detecting.contains(.hdr10Plus) { passes.append("hdr10plus (packet scan)") }
+        if detecting.contains(.hdrVivid) { passes.append("hdr-vivid (packet scan)") }
         if detecting.contains(.atmos) { passes.append("atmos (bounded decode)") }
         print("detail passes: \(passes.joined(separator: ", "))")
     }
@@ -41,6 +42,9 @@ func runProbe(url: URL, detecting: ProbeDetail = []) -> Int32 {
         // A negative here means "not seen inside the scan budget", never "proven absent".
         print("  HDR10+:    \(probe.carriesHDR10PlusMetadata ? "ST 2094-40 metadata seen" : "not seen")")
     }
+    if detecting.contains(.hdrVivid) {
+        print("  HDR Vivid: \(probe.carriesHDRVividMetadata ? "CUVA metadata seen" : "not seen")")
+    }
     print("")
 
     if probe.audioTracks.isEmpty {
diff --git a/Sources/aetherctl/main.swift b/Sources/aetherctl/main.swift
index 92666af33..9433b0939 100644
--- a/Sources/aetherctl/main.swift
+++ b/Sources/aetherctl/main.swift
@@ -66,7 +66,7 @@ func printUsage() {
     aetherctl: standalone AetherEngine repro harness
 
     Usage:
-      aetherctl probe [--detect-hdr10plus] [--detect-atmos] <url>
+      aetherctl probe [--detect-hdr10plus] [--detect-hdr-vivid] [--detect-atmos] <url>
       aetherctl serve [--no-dv] [--force-dv] [--dv-base-layer] [--start-position S] [--iframes] <url>
       aetherctl validate [--no-dv] [--force-dv] [--dv-base-layer] <url>
       aetherctl swdecode [--frames N] <url>
@@ -913,6 +913,7 @@ if ["probe", "serve", "validate", "swdecode", "extract", "audio", "customio"].co
     // instead of only through a host. Each costs reads past find_stream_info; the bare `probe` does neither.
     var probeDetail: ProbeDetail = []
     if takeFlag("--detect-hdr10plus", from: &rest) { probeDetail.insert(.hdr10Plus) }
+    if takeFlag("--detect-hdr-vivid", from: &rest) { probeDetail.insert(.hdrVivid) }
     if takeFlag("--detect-atmos", from: &rest) { probeDetail.insert(.atmos) }
     let inMemory = takeFlag("--memory", from: &rest)
     let forwardOnly = takeFlag("--forward-only", from: &rest)
diff --git a/Tests/AetherEngineTests/HDRVividProbeTests.swift b/Tests/AetherEngineTests/HDRVividProbeTests.swift
new file mode 100644
index 000000000..5eba7b856
--- /dev/null
+++ b/Tests/AetherEngineTests/HDRVividProbeTests.swift
@@ -0,0 +1,128 @@
+import Foundation
+import Testing
+@testable import AetherEngine
+
+/// #699: HDR Vivid (CUVA T/UWA 005.1) detection in the opt-in probe pass. The fixture is a two-frame
+/// 64x64 HEVC/HLG MP4 with a CUVA T.35 SEI that ffprobe reports as "HDR Dynamic Metadata CUVA 005.1
+/// 2021 (Vivid)", built by `Scripts/make-hdr10plus-fixture.py --vivid`.
+@Suite("HDR Vivid probe detection (#699)")
+struct HDRVividProbeTests {
+
+    // MARK: - the body validator
+
+    /// The fixture's CUVA body: one tone-mapping parameter set with base curve and one 3-spline, two
+    /// saturation gains, 207 bits and one zero padding bit.
+    private static let body: [UInt8] = [
+        0x01, 0x00, 0x0B, 0xE6, 0x5F, 0xFF, 0xFF, 0xAB, 0x4A, 0xB3, 0x33, 0x0F, 0xF0,
+        0x00, 0x52, 0x88, 0x01, 0x1C, 0x00, 0x00, 0xFF, 0xBF, 0xEF, 0xF4, 0x4C, 0x32,
+    ]
+
+    private func complete(_ bytes: [UInt8]) -> Bool {
+        bytes.withUnsafeBufferPointer { HDRVividMetadataScan.bodyIsComplete($0) }
+    }
+
+    @Test("a complete CUVA body validates, with or without trailing zero bytes")
+    func completeBody() {
+        #expect(complete(Self.body))
+        #expect(complete(Self.body + [0, 0]))
+    }
+
+    @Test("a body cut short of its last field is not evidence")
+    func truncatedBody() {
+        #expect(!complete(Array(Self.body.dropLast())))
+    }
+
+    @Test("a set bit after the last field is not evidence")
+    func nonZeroPadding() {
+        var bytes = Self.body
+        bytes[bytes.count - 1] |= 1
+        #expect(!complete(bytes))
+        #expect(!complete(Self.body + [0x80]))
+    }
+
+    @Test("only system_start_code 1 to 7 has a defined syntax")
+    func startCodeRange() {
+        for code: UInt8 in [0, 8, 0xFF] {
+            var bytes = Self.body
+            bytes[0] = code
+            #expect(!complete(bytes), "start code \(code)")
+        }
+        var seven = Self.body
+        seven[0] = 7
+        #expect(complete(seven))
+    }
+
+    @Test("a cap keeps what the pass already confirmed, and the default reads as the HDR10+ target")
+    func outcomeKeepsPartialFindings() {
+        let partial = HDR10PlusDetectionOutcome(
+            stopReason: .packetCap, packetsRead: 32, bytesRead: 1000, found: .hdr10Plus)
+        #expect(partial.carriesHDR10Plus)
+        #expect(!partial.carriesHDRVivid)
+        #expect(HDR10PlusDetectionOutcome(stopReason: .found, packetsRead: 1, bytesRead: 1).carriesHDR10Plus)
+        #expect(!HDR10PlusDetectionOutcome(stopReason: .found, packetsRead: 1, bytesRead: 1).carriesHDRVivid)
+    }
+
+    // MARK: - end to end
+
+    private static func writeFixture(_ base64: String, name: String) throws -> URL {
+        let data = try #require(Data(base64Encoded: base64, options: .ignoreUnknownCharacters))
+        let url = FileManager.default.temporaryDirectory
+            .appendingPathComponent("aether-hdr-vivid-\(name)-\(UUID().uuidString).mp4")
+        try data.write(to: url)
+        return url
+    }
+
+    @Test("the base probe does not read packets, so it does not report HDR Vivid")
+    func baseProbeIsOptIn() throws {
+        let url = try Self.writeFixture(Self.vividBase64, name: "base")
+        defer { try? FileManager.default.removeItem(at: url) }
+        let probe = try AetherEngine.probe(url: url)
+        #expect(probe.videoFormat == .hlg)
+        #expect(!probe.carriesHDRVividMetadata)
+    }
+
+    @Test("asking for .hdrVivid finds the CUVA payload and leaves the HLG label alone")
+    func detectingFindsVivid() throws {
+        let url = try Self.writeFixture(Self.vividBase64, name: "vivid")
+        defer { try? FileManager.default.removeItem(at: url) }
+        let probe = try AetherEngine.probe(url: url, detecting: .hdrVivid)
+        #expect(probe.carriesHDRVividMetadata)
+        #expect(!probe.carriesHDR10PlusMetadata)
+        #expect(probe.videoFormat == .hlg)
+    }
+
+    @Test("asking for both reports each format only on the source that carries it")
+    func bothTargetsStaySeparate() throws {
+        let vivid = try Self.writeFixture(Self.vividBase64, name: "both-vivid")
+        let plus = try Self.writeFixture(HDR10PlusProbeIntegrationTests.hdr10PlusBase64, name: "both-plus")
+        defer {
+            try? FileManager.default.removeItem(at: vivid)
+            try? FileManager.default.removeItem(at: plus)
+        }
+        let vividProbe = try AetherEngine.probe(url: vivid, detecting: [.hdr10Plus, .hdrVivid])
+        #expect(vividProbe.carriesHDRVividMetadata)
+        #expect(!vividProbe.carriesHDR10PlusMetadata)
+        let plusProbe = try AetherEngine.probe(url: plus, detecting: [.hdr10Plus, .hdrVivid])
+        #expect(plusProbe.carriesHDR10PlusMetadata)
+        #expect(plusProbe.videoFormat == .hdr10Plus)
+        #expect(!plusProbe.carriesHDRVividMetadata)
+    }
+
+    static let vividBase64 = """
+        AAAAHGZ0eXBpc29tAAACAGlzb21pc28ybXA0MQAAAAhmcmVlAAAAfm1kYXQAAAAkTgEEHyYABAAFAQAL5l///6tKszMP8ABSiAEc
+        AAD/v+/0TDKAAAAADigBr3jrrvv//FtlXy08AAAAJE4BBB8mAAQABQEAC+Zf//+rSrMzD/AAUogBHAAA/7/v9EwygAAAABAoAa8J
+        4CQEyH//J2Eew0j8AAADw21vb3YAAABsbXZoZAAAAAAAAAAAAAAAAAAAA+gAAADIAAEAAAEAAAAAAAAAAAAAAAABAAAAAAAAAAAA
+        AAAAAAAAAQAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAIAAALtdHJhawAAAFx0a2hkAAAAAwAA
+        AAAAAAAAAAAAAQAAAAAAAADIAAAAAAAAAAAAAAAAAAAAAAABAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAQAAAAABAAAAA
+        QAAAAAAAJGVkdHMAAAAcZWxzdAAAAAAAAAABAAAAyAAAAAAAAQAAAAACZW1kaWEAAAAgbWRoZAAAAAAAAAAAAAAAAAAST4AAA6mA
+        VcQAAAAAAC1oZGxyAAAAAAAAAAB2aWRlAAAAAAAAAAAAAAAAVmlkZW9IYW5kbGVyAAAAAhBtaW5mAAAAFHZtaGQAAAABAAAAAAAA
+        AAAAAAAkZGluZgAAABxkcmVmAAAAAAAAAAEAAAAMdXJsIAAAAAEAAAHQc3RibAAAAWRzdHNkAAAAAAAAAAEAAAFUaHZjMQAAAAAA
+        AAABAAAAAAAAAAAAAAAAAAAAAABAAEAASAAAAEgAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABj//wAA
+        AMdodmNDAQQIAAAAnagAAAAAHvAA/P36+gAADwOgAAIAF0ABDAH//wQIAAADAJ2oAAADAAAeugJAABdAAQwB//8ECAAAAwCdqAAA
+        AwAAHroCQKEAAgArQgEBBAgAAAMAnagAAAMAAB6gIIEE2W6kkyvAWoSJBIIAAAMAAgAAAwAUEAArQgEBBAgAAAMAnagAAAMAAB6g
+        IIEE2W6kkyvAWoSJBIIAAAMAAgAAAwAUEKIAAgAHRAHBcrAiQAAIRAHBcrAiQAAAAAATY29scm5jbHgACQASAAkAAAAAEHBhc3AA
+        AAABAAAAAQAAABRidHJ0AAAAAAAAEnAAABJwAAAAGHN0dHMAAAAAAAAAAQAAAAIAAdTAAAAAHHN0c2MAAAAAAAAAAQAAAAEAAAAC
+        AAAAAQAAABxzdHN6AAAAAAAAAAAAAAACAAAAOgAAADwAAAAUc3RjbwAAAAAAAAABAAAALAAAAGJ1ZHRhAAAAWm1ldGEAAAAAAAAA
+        IWhkbHIAAAAAAAAAAG1kaXJhcHBsAAAAAAAAAAAAAAAALWlsc3QAAAAlqXRvbwAAAB1kYXRhAAAAAQAAAABMYXZmNjIuMTIuMTAx
+        """
+}
diff --git a/docs/api.md b/docs/api.md
index e184183b7..05c4c691e 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -447,9 +447,9 @@ try await player.reloadAtCurrentPosition()
 | `stop(resetDisplayCriteria:finalTeardown:)` | Ends the session, `state` becomes `.idle`, `startupProgress` becomes nil. `resetDisplayCriteria: false` keeps the panel in its current mode across an item handoff. |
 | `AetherEngine.probe(url:options:)` / `probe(source:options:)` | `nonisolated static throws -> SourceProbe`. Container/stream metadata read, no detail-pass decoder or session. `options` is read for `httpHeaders` only. Optional trailing `limits` and `cancellation` control the whole operation (below). For a custom reader the caller keeps ownership, `close()` is not called, and the cursor is left unspecified. |
 | `AetherEngine.probeDetectingAtmos(url:options:atmosDetection:)` | `probe` plus a bounded decode pass that authoritatively resolves E-AC-3 JOC for an Atmos badge. Strictly more expensive; never on the playback-start path. Decode-side failures degrade to "not confirmed" rather than throwing. Same thing as `probe(url:detecting: .atmos)`. |
-| `AetherEngine.probe(url:options:detecting:atmosDetection:hdr10PlusDetection:)` / `probe(source:...)` | `probe` plus the opt-in passes named in `ProbeDetail`, over one demuxer: `.atmos` (the bounded JOC decode above) and `.hdr10Plus` (structurally validated ST 2094-40 carriage). Both passes share the optional trailing `limits` and `cancellation`. Empty set is the header probe with the same controls. Both passes only ever SET `isAtmos` / `carriesHDR10PlusMetadata`; ordinary pass failures and per-pass caps leave the detail unconfirmed. A whole-probe stop throws, with no partial result. |
-| `ProbeDetail` | `OptionSet`: `.atmos`, `.hdr10Plus`. |
-| `HDR10PlusDetectionOptions` | Bounds for the HDR10+ scan: `maxPackets` (32), `maxBytes` (16 MiB), `timeBudget` (2 s). The byte cap is the one that binds on UHD remuxes, where a single keyframe runs to several MB. It also bounds the total source read to four times `maxBytes` (at least 4 MiB), below the demuxer, so blocks of dropped streams count. |
+| `AetherEngine.probe(url:options:detecting:atmosDetection:hdr10PlusDetection:)` / `probe(source:...)` | `probe` plus the opt-in passes named in `ProbeDetail`, over one demuxer: `.atmos` (the bounded JOC decode above), `.hdr10Plus` (structurally validated ST 2094-40 carriage) and `.hdrVivid` (structurally validated CUVA HDR Vivid carriage in HEVC, scanned in the same packet pass as `.hdr10Plus`). Both passes share the optional trailing `limits` and `cancellation`. Empty set is the header probe with the same controls. The passes only ever SET `isAtmos` / `carriesHDR10PlusMetadata` / `carriesHDRVividMetadata`; ordinary pass failures and per-pass caps leave the detail unconfirmed. A whole-probe stop throws, with no partial result. |
+| `ProbeDetail` | `OptionSet`: `.atmos`, `.hdr10Plus`, `.hdrVivid`. |
+| `HDR10PlusDetectionOptions` | Bounds for the HDR10+ / HDR Vivid packet scan (one pass for both): `maxPackets` (32), `maxBytes` (16 MiB), `timeBudget` (2 s). The byte cap is the one that binds on UHD remuxes, where a single keyframe runs to several MB. It also bounds the total source read to four times `maxBytes` (at least 4 MiB), below the demuxer, so blocks of dropped streams count. |
 | `ProbeLimits` | Optional whole-probe controls: `maxInputBytes` (8 MiB), `maxPackets` (128), `maxPacketBytes` (2 MiB), `timeBudget` (5 s). Nonnegative values required; the time budget must be finite. |
 | `ProbeCancellation` | Thread-safe, one-shot token: `init()`, `isCancelled`, `cancel()`. Available on every URL/custom header, detail and `probeDetectingAtmos` overload. Cancellation is a request, not a completion notification. |
 | `ProbeError` | `invalidLimits`, `inputLimit`, `packetLimit`, `packetSizeLimit`, `timedOut`, `invalidReaderResult`, `unsupportedURL`, `sourceBusy`; `errorDescription` describes the stop. Explicit caller cancellation throws `CancellationError` instead. |
@@ -1112,7 +1112,7 @@ All flags default to safe values; the table is the full set. Depth for the media
 
 | Type | Carries |
 | --- | --- |
-| `SourceProbe` | `url`, `durationSeconds`, `videoFormat`, `videoCodecID` / `videoCodecName`, `videoWidth` / `videoHeight`, `videoFrameRate`, `isDolbyVision`, `dvProfile`, `carriesHDR10PlusMetadata`, `audioTracks`, `subtitleTracks`, `metadata`, `isLive`, `videoStreamFormat` (the same `VideoStreamFormat` a session publishes as `$sourceVideoStreamFormat`). `carriesHDR10PlusMetadata` is `false` unless the probe was asked for `.hdr10Plus`, and a `false` means "not asked, or not seen inside the budget", never "proven absent". When it is true and the container said HDR10, `videoFormat` reads `.hdr10Plus`; a Dolby Vision source keeps `.dolbyVision` and carries the flag alongside. |
+| `SourceProbe` | `url`, `durationSeconds`, `videoFormat`, `videoCodecID` / `videoCodecName`, `videoWidth` / `videoHeight`, `videoFrameRate`, `isDolbyVision`, `dvProfile`, `carriesHDR10PlusMetadata`, `carriesHDRVividMetadata`, `audioTracks`, `subtitleTracks`, `metadata`, `isLive`, `videoStreamFormat` (the same `VideoStreamFormat` a session publishes as `$sourceVideoStreamFormat`). `carriesHDR10PlusMetadata` is `false` unless the probe was asked for `.hdr10Plus`, and a `false` means "not asked, or not seen inside the budget", never "proven absent". When it is true and the container said HDR10, `videoFormat` reads `.hdr10Plus`; a Dolby Vision source keeps `.dolbyVision` and carries the flag alongside. `carriesHDRVividMetadata` follows the same contract for `.hdrVivid` (#699) and never moves `videoFormat`: HDR Vivid rides an HLG or PQ base, which stays the label. |
 | `TrackInfo` | `id`, `name`, `codec`, `language`, `channels`, `bitrate`, `isDefault`, `isForced`, `isHearingImpaired`, `isCommentary`, `isAtmos`, `assHeader`, `isExternal`, `isNativelyRenderedSubtitle`, and for audio `sampleRate`, `bitsPerSample`, `sampleFormat`, `channelLayout`, plus `profile` for every track (AE#658). `bitsPerSample` is 0 where the codec has no fixed depth (AAC, AC-3, E-AC-3 and Opus decode to float); `sampleFormat` is the probe decoder's output in libav's names ("fltp", "s32"); `profile` is libavcodec's profile name and the place DTS:X ("DTS-HD MA + DTS:X") and TrueHD Atmos ("Dolby TrueHD + Dolby Atmos") show up, where `isAtmos` covers E-AC-3 JOC only. `isNativelyRenderedSubtitle` marks a subtitle the playback backend draws itself (a remote-HLS rendition AVFoundation renders), so no cue reaches `subtitleCues` and an overlay control (position, delay, styling) has nothing to act on. |
 | `MediaMetadata` | `title`, `artist`, `album`, `artworkData`, `hasDisplayMetadata`. There is no separate album-artist field: a container's album artist is a fallback the parser folds into `artist`. |
 | `SubtitleCue` | `id`, `startTime`, `endTime`, `body` (a `SubtitleCue.Body`: `.text`, `.richText`, `.image`), `placement`, plus `text` and `isForced` conveniences. |
diff --git a/docs/cli.md b/docs/cli.md
index 2823793cc..2e042b122 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -33,13 +33,13 @@ Twenty-one subcommands plus the bare-URL `serve` alias.
 
 Opens the demuxer, prints the codec / resolution / frame rate of the video track, the audio track list (codec, channels, language, Atmos flag), the subtitle track list, the parsed container metadata (`MediaMetadata`: title / artist / album / albumArtist + embedded cover art presence), then exits. No HLS server is started.
 
-`--detect-hdr10plus` and `--detect-atmos` add the opt-in detail passes of `AetherEngine.probe(url:detecting:)`, and both can be given at once (one open, one connection). HDR10+ is the interesting one to watch: the bare `probe` reads only what the container declares, and ST 2094-40 is declared nowhere, so a carrying source prints `format: hdr10` without the flag and `format: hdr10Plus` plus `HDR10+: ST 2094-40 metadata seen` with it. `not seen` means "not inside the scan budget", not "proven absent".
+`--detect-hdr10plus` and `--detect-atmos` add the opt-in detail passes of `AetherEngine.probe(url:detecting:)`, and both can be given at once (one open, one connection). HDR10+ is the interesting one to watch: the bare `probe` reads only what the container declares, and ST 2094-40 is declared nowhere, so a carrying source prints `format: hdr10` without the flag and `format: hdr10Plus` plus `HDR10+: ST 2094-40 metadata seen` with it. `not seen` means "not inside the scan budget", not "proven absent". `--detect-hdr-vivid` adds the HDR Vivid (CUVA) check to the same packet pass and prints `HDR Vivid: CUVA metadata seen`; `format:` stays `hlg` / `hdr10`, since Vivid rides that base (#699).
 
 ```bash
 swift run aetherctl probe --detect-hdr10plus /path/to/hdr10plus.mkv
 ```
 
-`Scripts/make-hdr10plus-fixture.py <dir>` builds a ~1 KB HEVC/PQ fixture that carries a real ST 2094-40 T.35 SEI (and prints it base64, which is how the two fixtures embedded in `HDR10PlusProbeIntegrationTests` were made). It verifies itself: it only emits the file when `ffprobe -show_frames` reports `HDR Dynamic Metadata SMPTE2094-40` on it, so the payload is one FFmpeg's own parser accepts rather than a byte pattern that resembles one.
+`Scripts/make-hdr10plus-fixture.py <dir>` builds a ~1 KB HEVC/PQ fixture that carries a real ST 2094-40 T.35 SEI (and prints it base64, which is how the two fixtures embedded in `HDR10PlusProbeIntegrationTests` were made). It verifies itself: it only emits the file when `ffprobe -show_frames` reports `HDR Dynamic Metadata SMPTE2094-40` on it, so the payload is one FFmpeg's own parser accepts rather than a byte pattern that resembles one. With `--vivid` it builds an HEVC/HLG fixture carrying a CUVA HDR Vivid SEI instead, verified the same way against ffprobe's `CUVA` side data (the fixture in `HDRVividProbeTests`).
 
 ## serve
 
diff --git a/docs/formats.md b/docs/formats.md
index 14e4117ef..5234d8bb2 100644
--- a/docs/formats.md
+++ b/docs/formats.md
@@ -216,6 +216,22 @@ sets `SourceProbe.carriesHDR10PlusMetadata` independently of the primary format,
 See [whole-probe limits and cancellation](api.md#whole-probe-limits-and-cancellation) for bounded source
 reads; absence of confirmation is not proof of absence or a statement about the connected display.
 
+### HDR Vivid (CUVA) dynamic metadata
+
+HDR Vivid (CUVA T/UWA 005.1) is built to be backward compatible: the base layer is plain HLG or PQ in
+BT.2020, and its dynamic metadata is an optional registered T.35 SEI on top (country 0x26, provider
+0x0004, oriented code 0x0005). The engine plays that base exactly like any HLG or HDR10 source and the
+SEI is stream-copied with the rest of the bitstream; no Apple platform applies it, and a display
+without Vivid support shows the static base, which is the format's intended fallback. There is no
+host-side tone mapping: the native route has no pixel stage, tvOS gives an app no EDR or panel-peak
+reading to map against, and the TV maps the HDR signal itself (#699).
+
+`probe(url:detecting: .hdrVivid)` reports carriage as `SourceProbe.carriesHDRVividMetadata`, in the
+same packet pass and budget as `.hdr10Plus`. libavcodec's CUVA parser is internal, so
+`HDRVividMetadataScan` walks the body with the same field widths and only counts a message whose
+`system_start_code` is one of the defined 1 to 7, whose fields are all present, and whose bits after
+the last field are zero. HEVC only, as in libavcodec. `videoFormat` stays `.hlg` / `.hdr10`.
+
 The label can also be taken back from the item itself, where the platform has no capability table to clamp it against (AE#515). A Dolby Vision source on macOS resolves to `.hdr10`, because `supportsDolbyVision` is unclaimable there without a host assertion, while AVFoundation goes on playing the `dvh1` sample entry the engine served. Measured with the assertion off on a 16" XDR, a Profile 5 and a Profile 8.1 grade of Dolby's reference content both strobe, so the RPU reaches the pixels with no claim set anywhere and the clamp was moving nothing but the label. When the item's sample entry reads `dvh1` / `dvhe` and the probe agrees the source is Dolby Vision, the label is upgraded from `.hdr10` to `.dolbyVision` at `readyToPlay`. It is an upgrade and not a mirror of what AVFoundation parsed, for two reasons that both matter: an `.sdr` label is the clamp being right about a display presenting no HDR at all, and on tvOS and iOS the per-mode table answers the capability question, so the label follows it rather than a sample entry that a Profile 5 master carries on every panel. Profile 8.1 keeps `.hdr10` on macOS: it reports `hvc1` with the DV configuration alongside it, it composes on that display all the same, and nothing in the stack reports that.
 
 ## Audio

From 7de2d5a0dbb8bc60c09be5620a71f8904d7ab60f Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Tue, 6 Oct 2026 05:19:22 +0200
Subject: [PATCH 320/359] chore(release): prep 7.28.0 - HDR Vivid (CUVA)
 detection in the opt-in probe

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                    | 4 ++++
 Examples/README.md                              | 2 +-
 README.md                                       | 6 +++---
 Sources/AetherEngine/AetherEngine+Version.swift | 2 +-
 4 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6fb4f9626..b482eeb27 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,10 @@ the public-API contract.
 
 ## [Unreleased]
 
+_Nothing yet._
+
+## [7.28.0] - 2026-10-06
+
 ### Added
 
 - **HDR Vivid (CUVA) detection in the opt-in probe (#699).** `ProbeDetail.hdrVivid` scans HEVC packets for the CUVA T/UWA 005.1 T.35 SEI and sets the new `SourceProbe.carriesHDRVividMetadata`. It runs in the same packet pass as `.hdr10Plus` and under the same `HDR10PlusDetectionOptions` budget; asking for both still opens one connection, and a cap that ends the pass after one of the two was confirmed keeps that confirmation. libavcodec's CUVA parser is internal, so `HDRVividMetadataScan` walks the body with the same field widths and only counts a complete message with a defined `system_start_code` and zero bits after its last field. `videoFormat` does not move (Vivid rides an HLG or PQ base, which stays the label), and playback is unchanged: the SEI is stream-copied as before and no Apple platform applies it. `aetherctl probe --detect-hdr-vivid` prints the finding, and `Scripts/make-hdr10plus-fixture.py --vivid` builds a fixture ffprobe parses as Vivid. Requested by ijuniorfu.
diff --git a/Examples/README.md b/Examples/README.md
index 82f21af50..e93f0cea0 100644
--- a/Examples/README.md
+++ b/Examples/README.md
@@ -18,7 +18,7 @@ Three samples covering different audiences:
    ```
    https://github.com/superuser404notfound/AetherEngine
    ```
-   Dependency Rule: Up to Next Major Version, starting from `7.27.3`. Add the `AetherEngine` library product to your app target.
+   Dependency Rule: Up to Next Major Version, starting from `7.28.0`. Add the `AetherEngine` library product to your app target.
 
 3. **Drop the file in.** Replace the Xcode template's default `App.swift` (or whatever the generated `@main` file is called) with the contents of [`MinimalPlayerApp.swift`](MinimalPlayer/MinimalPlayerApp.swift). The file is self-contained: it defines both the `@main App` struct and the `ContentView`.
 
diff --git a/README.md b/README.md
index 3f51159fc..8b6e8ab7f 100644
--- a/README.md
+++ b/README.md
@@ -385,7 +385,7 @@ Subtitle cues land in raw source PTS; render the overlay against `player.sourceT
 Install via Swift Package Manager:
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.27.3")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.28.0")
 ```
 
 Three samples ship in `Examples/`:
@@ -632,10 +632,10 @@ Browse all of this as a searchable site at **[aetherengine.superuser404.de](http
 AetherEngine uses [Semantic Versioning](https://semver.org). The public API surface, every `public` declaration in `Sources/AetherEngine/`, is the stability contract. **Major** removes / renames public symbols or breaks adopters; **Minor** adds public API or codec / format support; **Patch** fixes bugs with no public API change. `internal` types are not part of the contract.
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.27.3")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.28.0")
 ```
 
-Pin to `.upToNextMinor(from: "7.27.3")` for stricter teams that prefer to opt into minor bumps explicitly.
+Pin to `.upToNextMinor(from: "7.28.0")` for stricter teams that prefer to opt into minor bumps explicitly.
 
 ## Requirements
 
diff --git a/Sources/AetherEngine/AetherEngine+Version.swift b/Sources/AetherEngine/AetherEngine+Version.swift
index a008c6f22..b6c42008d 100644
--- a/Sources/AetherEngine/AetherEngine+Version.swift
+++ b/Sources/AetherEngine/AetherEngine+Version.swift
@@ -11,5 +11,5 @@ extension AetherEngine {
     ///
     /// Between releases, and in a consumer that pins an unreleased commit for a device test, this
     /// names the last PUBLISHED version the checkout descends from, not every patch in it.
-    public nonisolated static let version = "7.27.3"
+    public nonisolated static let version = "7.28.0"
 }

From e29182daa5d697dbf2de8aafd89531ebc34f9e5a Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Tue, 6 Oct 2026 16:34:44 +0200
Subject: [PATCH 321/359] fix(native): stop trusting a keyframe index that ends
 minutes before EOF

A partial keyframe scan passed both existing witnesses: its gaps are
small and its coverage exceeds one segment. An MKV whose Cues are
missing or point past EOF leaves exactly that after the capped prewarm,
and the keyframe planner then cut its final segment from the last
scanned keyframe to the end of the title (205 s to 5933 s on a device),
a segment the producer can never finish while AVPlayer waits on it.

keyframeIndexIsTrustworthy gains a third witness: the indexed span must
reach within 60 s of the source duration, otherwise the session takes
the uniform plan. 60 s leaves room for a long final GOP and for a
container duration padded by a trailing audio or subtitle track.

The old "trailing gap is not counted" test asserted the defect, so it
is inverted, and the gap and coverage boundary tests lift the new
witness so each still pins only its own threshold.

Diagnosed by yipengfei329 in PR #703 (MovieClaw patch P18).

Co-authored-by: yipengfei329 <1396975+yipengfei329@users.noreply.github.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                  |  4 +-
 .../HLSVideoEngine+SegmentPlanning.swift      | 18 ++++--
 .../SegmentPlanSparseIndexTests.swift         | 59 ++++++++++++++-----
 docs/architecture.md                          |  2 +-
 4 files changed, 62 insertions(+), 21 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b482eeb27..710a06a43 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,7 +10,9 @@ the public-API contract.
 
 ## [Unreleased]
 
-_Nothing yet._
+### Fixed
+
+- **A keyframe index that stops minutes before the end is no longer trusted.** A partial scan (an MKV whose Cues are missing or point past EOF) passed both the gap and the coverage check, and the keyframe planner then cut a final segment from the last scanned keyframe to the end of the title, which the producer can never finish. The index now also has to reach within 60 s of the source duration, otherwise the session takes the uniform plan. Diagnosed by yipengfei329 (#703).
 
 ## [7.28.0] - 2026-10-06
 
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine+SegmentPlanning.swift b/Sources/AetherEngine/Video/HLSVideoEngine+SegmentPlanning.swift
index 54883b154..0a2191e05 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine+SegmentPlanning.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine+SegmentPlanning.swift
@@ -49,7 +49,7 @@ extension HLSVideoEngine {
     /// interleaver before its first flush, which on a 110 min Blu-ray climbed to ~13 GB of RAM and
     /// swapped until the device disk filled.
     ///
-    /// Two witnesses, both required:
+    /// Three witnesses, all required:
     ///
     /// - **Gap (#64)**: the largest gap between consecutive keyframes. A real index never gaps more than
     ///   a few GOPs (well under the cap); a clustered TS index gaps by thousands of seconds.
@@ -61,15 +61,22 @@ extension HLSVideoEngine {
     ///   whole-file segment, from which AVPlayer loads zero tracks. Below one segment of coverage the
     ///   keyframe planner cannot make even the first cut, so such an index is rejected here.
     ///
-    /// Coverage is the span between keyframes, never reaching to EOF, so a dense index that stops early
-    /// (the trailing-gap-not-counted case) is unaffected: its span already exceeds one segment.
-    /// An index failing either witness is routed to the uniform-stride fallback.
+    /// - **Tail (PR #703)**: the span must also reach to within `maxTrailingGapSeconds` of the source
+    ///   duration. An index that stops minutes short is not dense-but-short, it is a partial scan: an
+    ///   MKV whose Cues are missing or point past EOF (an incomplete download) leaves only what the
+    ///   capped prewarm walked, and the keyframe planner then cuts its last segment from the final
+    ///   scanned keyframe to the end of the title (measured on a device: 205 s to 5933 s), which the
+    ///   producer can never finish and AVPlayer waits on forever. The 60 s default leaves room for a
+    ///   long final GOP and for a container duration padded by a trailing audio or subtitle track.
+    ///
+    /// An index failing any witness is routed to the uniform-stride fallback.
     static func keyframeIndexIsTrustworthy(
         keyframes: [Int64],
         videoTimeBase: AVRational,
         sourceDurationSeconds: Double,
         maxTrustedGapSeconds: Double = Swift.max(HLSVideoEngine.targetSegmentDuration * 4, 30),
-        minCoverageSeconds: Double = HLSVideoEngine.targetSegmentDuration
+        minCoverageSeconds: Double = HLSVideoEngine.targetSegmentDuration,
+        maxTrailingGapSeconds: Double = 60
     ) -> Bool {
         guard keyframes.count >= 2,
               sourceDurationSeconds > 0,
@@ -79,6 +86,7 @@ extension HLSVideoEngine {
         // In Double: an index spanning both Int64 extremes overflows the integer difference (audit HLS-102).
         let coverageSeconds = (Double(sorted[sorted.count - 1]) - Double(sorted[0])) * tb
         guard coverageSeconds >= minCoverageSeconds else { return false }
+        guard sourceDurationSeconds - coverageSeconds <= maxTrailingGapSeconds else { return false }
         var largestGapSeconds = 0.0
         for i in 1..<sorted.count {
             let gapSeconds = (Double(sorted[i]) - Double(sorted[i - 1])) * tb
diff --git a/Tests/AetherEngineTests/SegmentPlanSparseIndexTests.swift b/Tests/AetherEngineTests/SegmentPlanSparseIndexTests.swift
index 1a43011bd..84a4cfd2c 100644
--- a/Tests/AetherEngineTests/SegmentPlanSparseIndexTests.swift
+++ b/Tests/AetherEngineTests/SegmentPlanSparseIndexTests.swift
@@ -88,14 +88,17 @@ struct SegmentPlanSparseIndexTests {
     @Test("The minimum-coverage threshold is one targetSegmentDuration (boundary)")
     func minimumCoverageBoundary() {
         // Span exactly one segment is trustworthy (seg 0 can be cut); span just under is not (seg 0
-        // degenerates to the whole file). Both have a single sub-cap inter-keyframe gap, so only the
-        // coverage check decides. Pins the threshold to targetSegmentDuration (4.0 s).
+        // degenerates to the whole file). Both have a single sub-cap inter-keyframe gap and the tail
+        // witness is lifted, so only the coverage check decides. Pins the threshold to
+        // targetSegmentDuration (4.0 s).
         let exactlyOneSegment: [Int64] = [0, 4_000]   // ms: 4.000 s span
         let justUnderOneSegment: [Int64] = [0, 3_999] // ms: 3.999 s span
         #expect(HLSVideoEngine.keyframeIndexIsTrustworthy(
-            keyframes: exactlyOneSegment, videoTimeBase: mkvMs, sourceDurationSeconds: 6843.872) == true)
+            keyframes: exactlyOneSegment, videoTimeBase: mkvMs, sourceDurationSeconds: 6843.872,
+            maxTrailingGapSeconds: .infinity) == true)
         #expect(HLSVideoEngine.keyframeIndexIsTrustworthy(
-            keyframes: justUnderOneSegment, videoTimeBase: mkvMs, sourceDurationSeconds: 6843.872) == false)
+            keyframes: justUnderOneSegment, videoTimeBase: mkvMs, sourceDurationSeconds: 6843.872,
+            maxTrailingGapSeconds: .infinity) == false)
     }
 
     @Test("A dense 4 s-GOP index across the whole title is trustworthy")
@@ -114,26 +117,54 @@ struct SegmentPlanSparseIndexTests {
     @Test("The trusted-gap cap is pinned at 30 s (boundary)")
     func gapCapBoundary() {
         // 30.000 s gap is trusted, 30.001 s is not. Pins the cap so a future targetSegmentDuration
-        // change becomes a visible test break.
+        // change becomes a visible test break. The tail witness is lifted so only the gap decides.
         let exactly30: [Int64] = [0, Int64(30.0 * 90_000)]
         let justOver30: [Int64] = [0, Int64(30.001 * 90_000)]
         #expect(HLSVideoEngine.keyframeIndexIsTrustworthy(
-            keyframes: exactly30, videoTimeBase: ts90k, sourceDurationSeconds: 6599) == true)
+            keyframes: exactly30, videoTimeBase: ts90k, sourceDurationSeconds: 6599,
+            maxTrailingGapSeconds: .infinity) == true)
         #expect(HLSVideoEngine.keyframeIndexIsTrustworthy(
-            keyframes: justOver30, videoTimeBase: ts90k, sourceDurationSeconds: 6599) == false)
+            keyframes: justOver30, videoTimeBase: ts90k, sourceDurationSeconds: 6599,
+            maxTrailingGapSeconds: .infinity) == false)
     }
 
-    @Test("A trailing gap from the last keyframe to EOF is not counted")
-    func tailGapNotCounted() {
-        // Keyframes spaced 4 s up to 60% of the duration, then nothing. The last-keyframe-to-EOF span
-        // is not an inter-keyframe gap and must not demote an otherwise-dense index.
+    /// A dense 4 s index from 0 up to `lastIndexedSeconds`, then nothing.
+    private func denseIndex(upTo lastIndexedSeconds: Double) -> [Int64] {
         let stride: Int64 = 4 * 90_000
         var kfs: [Int64] = []
         var t: Int64 = 0
-        let lastIndexed = Int64(0.6 * 6599 * 90_000)
-        while t <= lastIndexed { kfs.append(t); t += stride }
+        while t <= Int64(lastIndexedSeconds * 90_000) { kfs.append(t); t += stride }
+        return kfs
+    }
+
+    @Test("A dense index that stops minutes before EOF is a partial scan, not trustworthy (PR #703)")
+    func partialScanRejected() {
+        // Keyframes spaced 4 s up to 60% of the duration, then nothing: what a capped prewarm leaves
+        // on an MKV whose Cues are missing or point past EOF. Every inter-keyframe gap is fine; the
+        // index still cannot plan the last 40% of the title.
+        #expect(HLSVideoEngine.keyframeIndexIsTrustworthy(
+            keyframes: denseIndex(upTo: 0.6 * 6599), videoTimeBase: ts90k,
+            sourceDurationSeconds: 6599) == false)
+    }
+
+    @Test("Trusting the partial scan would have produced a final segment reaching to EOF (PR #703)")
+    func partialScanProducesGiantFinalSegment() {
+        // The device report: the last planned segment ran from the final scanned keyframe at 205 s to
+        // the end of the title at 5933 s, a segment the producer can never finish.
+        let plan = HLSVideoEngine.buildKeyframeSegmentPlan(
+            keyframes: denseIndex(upTo: 205), videoTimeBase: ts90k, sourceDurationSeconds: 5933)
+        #expect((plan.last?.durationSeconds ?? 0) > 5700)
+    }
+
+    @Test("The trailing-gap tolerance is pinned at 60 s (boundary)")
+    func trailingGapBoundary() {
+        // Coverage 0 to 1200 s: a duration 60 s past it is trusted (a long final GOP, a padded audio
+        // or subtitle tail), 60.5 s past it is not.
+        let kfs = denseIndex(upTo: 1200)
+        #expect(HLSVideoEngine.keyframeIndexIsTrustworthy(
+            keyframes: kfs, videoTimeBase: ts90k, sourceDurationSeconds: 1260) == true)
         #expect(HLSVideoEngine.keyframeIndexIsTrustworthy(
-            keyframes: kfs, videoTimeBase: ts90k, sourceDurationSeconds: 6599) == true)
+            keyframes: kfs, videoTimeBase: ts90k, sourceDurationSeconds: 1260.5) == false)
     }
 
     @Test("Degenerate inputs are never trustworthy")
diff --git a/docs/architecture.md b/docs/architecture.md
index ec48d9057..cd92e6a1d 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -50,7 +50,7 @@ read is discarded: its observed totals remain, but final totals are incomplete,
 session rather than fabricated. A new playback session (including an episode handover on the same
 player) clears those totals and rejects any old reconciliation.
 
-The playlist's segment boundaries come from a keyframe-aligned plan that mirrors the `hls` muxer's cut algorithm (segment N ends at the first IRAP at-or-after `(N+1) * targetSegmentDuration`), built in `HLSVideoEngine+SegmentPlanning.swift`. It needs the source's keyframe positions, which for MKV / MP4 come from a brief cue prewarm (a bounded seek that loads the Cues / `stss` index) and for MPEG-TS / M2TS come only from whatever `avformat_find_stream_info` plus that seek happened to scan. `keyframeIndexIsTrustworthy` gates the plan on two witnesses before trusting that index, falling back to a uniform-stride plan otherwise: the largest **gap** between consecutive keyframes must stay under a cap (a clustered TS index gaps by thousands of seconds; trusting it builds a multi-thousand-second first segment the `frag_custom` muxer buffers whole in RAM, #64), and the **coverage** from first to last indexed keyframe must span at least one `targetSegmentDuration`. The coverage check catches a remote MKV whose Cues tail read fails: the prewarm loads nothing, only the open-time keyframes survive bunched in the first few seconds, their gaps are tiny so the gap check passes, yet no keyframe reaches the first segment boundary, so the keyframe planner would degenerate to a single whole-file segment AVPlayer loads zero tracks from (`kFigAssetError_TrackNotFound`, #91). The uniform fallback anchors segment 0 at the content start so a late-starting title doesn't advertise empty leading segments.
+The playlist's segment boundaries come from a keyframe-aligned plan that mirrors the `hls` muxer's cut algorithm (segment N ends at the first IRAP at-or-after `(N+1) * targetSegmentDuration`), built in `HLSVideoEngine+SegmentPlanning.swift`. It needs the source's keyframe positions, which for MKV / MP4 come from a brief cue prewarm (a bounded seek that loads the Cues / `stss` index) and for MPEG-TS / M2TS come only from whatever `avformat_find_stream_info` plus that seek happened to scan. `keyframeIndexIsTrustworthy` gates the plan on three witnesses before trusting that index, falling back to a uniform-stride plan otherwise: the largest **gap** between consecutive keyframes must stay under a cap (a clustered TS index gaps by thousands of seconds; trusting it builds a multi-thousand-second first segment the `frag_custom` muxer buffers whole in RAM, #64), and the **coverage** from first to last indexed keyframe must span at least one `targetSegmentDuration`. The coverage check catches a remote MKV whose Cues tail read fails: the prewarm loads nothing, only the open-time keyframes survive bunched in the first few seconds, their gaps are tiny so the gap check passes, yet no keyframe reaches the first segment boundary, so the keyframe planner would degenerate to a single whole-file segment AVPlayer loads zero tracks from (`kFigAssetError_TrackNotFound`, #91). The **tail** check requires that coverage to reach within 60 s of the source duration: a dense index that stops minutes short is a partial scan (an MKV whose Cues are missing or point past EOF leaves only what the capped prewarm walked), and trusting it cuts a last segment from the final scanned keyframe to the end of the title that the producer can never finish (PR #703). The uniform fallback anchors segment 0 at the content start so a late-starting title doesn't advertise empty leading segments.
 
 At runtime the producer honors those boundaries with a keyframe-gated, decode-order cut (`VODSegmentCutter`): a segment opens only at the IRAP that reaches the next boundary, so the IRAP is the segment's first sample and its open-GOP leading pictures stay with it, matching the live path and the `hls` muxer. The earlier routing keyed each packet to a segment by its DTS against the PTS-valued boundaries, so under B-frame reorder a keyframe whose DTS trailed its PTS fell into the previous segment and the next one started mid-GOP, decode-dependent on its predecessor; a fresh decode at that boundary (rebuffer recovery) surfaced it as transient blocky corruption (#92).
 

From 68e898e2f0ec0e0ab7665b857535433d7fe08079 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Tue, 6 Oct 2026 16:34:45 +0200
Subject: [PATCH 322/359] fix(native): keep in-band HEVC parameter sets on
 Annex-B sources

On an Annex-B HEVC source (Blu-ray M2TS, broadcast TS) the session
muxer handed movenc an Annex-B record, so movenc converted every sample
itself, and under the hvc1 sample entry ff_hevc_annexb2mp4 runs with
filter_ps and drops every in-band VPS/SPS/PPS. A stream that sends a
new PPS mid-title then has every later slice decoded against the stale
one: sound continues over a frozen picture.

When the packets are conclusively Annex B, the muxer now gets the
length-prefixed record movenc would have built (from the canonical
record, so no SEI array, AE#187) and converts each sample itself with
every NAL kept, before the AE#561 sanitizer walks it. That is the shape
a Matroska remux of the same stream already reached the muxer in.
init.mp4 and CODECS are byte-identical to before. The conversion writes
a new packet buffer, never the possibly shared source one.

The flag travels on the stream config to all three muxer builds,
including the AE#682 I-frame rendition, which would otherwise have
received Annex-B samples under a length-prefixed record.

Measured with aetherctl on an HEVC TS whose PPS changes at 20 s (same
SPS, WPP and sign hiding toggled): play --present-times 463 frames in
42 s with none after the change before, 936 after; segverify decodes
0 frames of the post-change segment before, 117 after; the post-change
I-frame fragment fails to decode before and decodes after.

Diagnosed by yipengfei329 in PR #703 (MovieClaw patch P38).

Co-authored-by: yipengfei329 <1396975+yipengfei329@users.noreply.github.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                  |  1 +
 .../Video/AnnexBSampleConverter.swift         | 88 +++++++++++++++++++
 .../Video/HLSSegmentProducer.swift            |  6 ++
 .../Video/HLSVideoEngine+AudioRoute.swift     |  3 +-
 .../HLSVideoEngine+SegmentPlanning.swift      | 26 +++++-
 .../AetherEngine/Video/HLSVideoEngine.swift   |  2 +
 .../AetherEngine/Video/MP4SegmentMuxer.swift  | 15 ++++
 .../AnnexBSampleConverterTests.swift          | 73 +++++++++++++++
 docs/architecture.md                          |  1 +
 9 files changed, 212 insertions(+), 3 deletions(-)
 create mode 100644 Sources/AetherEngine/Video/AnnexBSampleConverter.swift
 create mode 100644 Tests/AetherEngineTests/AnnexBSampleConverterTests.swift

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 710a06a43..98f484c24 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,7 @@ the public-API contract.
 
 ### Fixed
 
+- **HEVC with a parameter-set change mid-title keeps its picture.** On an Annex-B HEVC source (Blu-ray M2TS, broadcast TS) movenc converted the samples itself and, under the `hvc1` sample entry, dropped every in-band VPS/SPS/PPS, so a stream that sends a new PPS mid-title had every later slice decoded against the stale one: sound continued over a frozen or black picture. The session muxer now gets a length-prefixed record and converts the samples itself with their parameter sets kept, the shape a Matroska remux of the same stream already had; `init.mp4` and `CODECS` are unchanged. The I-frame rendition muxer takes the same path. Measured on a fixture whose PPS changes at 20 s: 463 presented frames in 42 s before (none after the change), 936 after. Diagnosed by yipengfei329 (#703).
 - **A keyframe index that stops minutes before the end is no longer trusted.** A partial scan (an MKV whose Cues are missing or point past EOF) passed both the gap and the coverage check, and the keyframe planner then cut a final segment from the last scanned keyframe to the end of the title, which the producer can never finish. The index now also has to reach within 60 s of the source duration, otherwise the session takes the uniform plan. Diagnosed by yipengfei329 (#703).
 
 ## [7.28.0] - 2026-10-06
diff --git a/Sources/AetherEngine/Video/AnnexBSampleConverter.swift b/Sources/AetherEngine/Video/AnnexBSampleConverter.swift
new file mode 100644
index 000000000..b78667459
--- /dev/null
+++ b/Sources/AetherEngine/Video/AnnexBSampleConverter.swift
@@ -0,0 +1,88 @@
+import Foundation
+import AetherLibavcodec
+import AetherLibavutil
+
+/// Rewrites an Annex-B video sample to 4-byte length-prefixed NALs, keeping every NAL.
+///
+/// movenc does this conversion itself whenever the extradata is Annex B, but for an `hvc1` sample
+/// entry it runs `ff_hevc_annexb2mp4` with `filter_ps` set and drops every in-band VPS, SPS and PPS.
+/// The decoder is then left with the parameter sets in `hvcC` alone. A Blu-ray or broadcast HEVC
+/// stream that sends a new PPS mid-title (seen at 118 s and 345.7 s on one UHD disc) has every later
+/// slice decoded against the stale one: macOS reports "Cannot Decode", a device plays sound over a
+/// black picture. Converting here, and handing movenc a length-prefixed record so it does not convert
+/// again, keeps the parameter sets in the samples. That is the shape a Matroska remux of the same
+/// stream already reaches the muxer in (its samples carry their in-band parameter sets and movenc
+/// copies them as they are).
+///
+/// Diagnosed and first implemented by yipengfei329 for MovieClaw (AetherEngine PR #703, patch P38).
+enum AnnexBSampleConverter {
+    /// The NAL payload ranges of an Annex-B buffer, 3-byte and 4-byte start codes alike, with the
+    /// zero bytes in front of the next start code trimmed off, as `ff_nal_parse_units` does. Empty when
+    /// the buffer holds no start code.
+    static func nalRanges(_ bytes: UnsafeRawBufferPointer) -> [Range<Int>] {
+        guard let base = bytes.baseAddress?.assumingMemoryBound(to: UInt8.self), bytes.count >= 4 else {
+            return []
+        }
+        let n = bytes.count
+        var starts: [Int] = []
+        var i = 0
+        while i + 2 < n {
+            // The third byte of a start code is 1 and the two before it are 0, so any byte above 1 at
+            // i + 2 rules out a start code beginning at i, i + 1 or i + 2.
+            if base[i + 2] > 1 { i += 3; continue }
+            if base[i] == 0, base[i + 1] == 0, base[i + 2] == 1 {
+                starts.append(i + 3)
+                i += 3
+            } else {
+                i += 1
+            }
+        }
+        var ranges: [Range<Int>] = []
+        ranges.reserveCapacity(starts.count)
+        for (k, start) in starts.enumerated() {
+            var end = k + 1 < starts.count ? starts[k + 1] - 3 : n
+            while end > start, base[end - 1] == 0 { end -= 1 }
+            if end > start { ranges.append(start..<end) }
+        }
+        return ranges
+    }
+
+    /// Replace the packet's payload with its length-prefixed form. False when the payload holds no
+    /// start code (the packet is left untouched) or the new buffer could not be allocated.
+    ///
+    /// The payload goes into a new buffer rather than being rewritten in place: a demuxed packet's
+    /// buffer can be shared with another reference.
+    static func convertToLengthPrefixed(_ packet: UnsafeMutablePointer<AVPacket>) -> Bool {
+        guard let data = packet.pointee.data, packet.pointee.size > 0 else { return false }
+        let source = UnsafeRawBufferPointer(start: data, count: Int(packet.pointee.size))
+        let ranges = nalRanges(source)
+        guard !ranges.isEmpty else { return false }
+        let total = ranges.reduce(0) { $0 + 4 + $1.count }
+        guard total <= Int(Int32.max) else { return false }
+
+        let pad = Int(AV_INPUT_BUFFER_PADDING_SIZE)
+        guard let newRef = av_buffer_alloc(total + pad) else { return false }
+        guard let dst = newRef.pointee.data else {
+            var ref: UnsafeMutablePointer<AVBufferRef>? = newRef
+            av_buffer_unref(&ref)
+            return false
+        }
+        var w = 0
+        for range in ranges {
+            let len = range.count
+            dst[w + 0] = UInt8((len >> 24) & 0xFF)
+            dst[w + 1] = UInt8((len >> 16) & 0xFF)
+            dst[w + 2] = UInt8((len >> 8) & 0xFF)
+            dst[w + 3] = UInt8(len & 0xFF)
+            w += 4
+            memcpy(dst + w, data + range.lowerBound, len)
+            w += len
+        }
+        memset(dst + total, 0, pad)
+        av_buffer_unref(&packet.pointee.buf)
+        packet.pointee.buf = newRef
+        packet.pointee.data = newRef.pointee.data
+        packet.pointee.size = Int32(total)
+        return true
+    }
+}
diff --git a/Sources/AetherEngine/Video/HLSSegmentProducer.swift b/Sources/AetherEngine/Video/HLSSegmentProducer.swift
index a1a5dfc80..7431f833d 100644
--- a/Sources/AetherEngine/Video/HLSSegmentProducer.swift
+++ b/Sources/AetherEngine/Video/HLSSegmentProducer.swift
@@ -50,6 +50,9 @@ final class HLSSegmentProducer: @unchecked Sendable {
         /// which is only correct while the two agree; on a source where they do not, every walker
         /// downstream (A53 captions, the DV P7 RPU rewrite) reads the packet at the wrong offsets.
         let nalFramingOverride: VideoNALFraming?
+        /// Forwarded to `MP4SegmentMuxer.VideoConfig.convertsAnnexBSamples`. The packets stay Annex B
+        /// up to the muxer, so `nalFramingOverride` keeps describing them.
+        let convertsAnnexBSamples: Bool
         /// The session's BIT-1 framing verdict, handed to every muxer this producer builds for the
         /// program's own track (audit BIT-104).
         let nalFramingLatch: NALFramingLatch?
@@ -63,6 +66,7 @@ final class HLSSegmentProducer: @unchecked Sendable {
             colorOverride: MP4SegmentMuxer.ColorOverride? = nil,
             extradataOverride: [UInt8]? = nil,
             nalFramingOverride: VideoNALFraming? = nil,
+            convertsAnnexBSamples: Bool = false,
             nalFramingLatch: NALFramingLatch? = nil
         ) {
             self.codecpar = codecpar
@@ -73,6 +77,7 @@ final class HLSSegmentProducer: @unchecked Sendable {
             self.colorOverride = colorOverride
             self.extradataOverride = extradataOverride
             self.nalFramingOverride = nalFramingOverride
+            self.convertsAnnexBSamples = convertsAnnexBSamples
             self.nalFramingLatch = nalFramingLatch
         }
     }
@@ -2113,6 +2118,7 @@ final class HLSSegmentProducer: @unchecked Sendable {
             doviConfig: isAdCreative ? .keep : videoConfig.doviConfig,
             colorOverride: isAdCreative ? nil : videoConfig.colorOverride,
             extradataOverride: isAdCreative ? nil : videoConfig.extradataOverride,
+            convertsAnnexBSamples: isAdCreative ? false : videoConfig.convertsAnnexBSamples,
             nalFramingLatch: isAdCreative ? nil : videoConfig.nalFramingLatch
         )
         let muxerAudio: MP4SegmentMuxer.AudioConfig? = audioConfig.map { a in
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine+AudioRoute.swift b/Sources/AetherEngine/Video/HLSVideoEngine+AudioRoute.swift
index 7b9aa310d..b5d6089ce 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine+AudioRoute.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine+AudioRoute.swift
@@ -219,7 +219,8 @@ extension HLSVideoEngine {
                 codecTagOverride: vcfg.codecTagOverride,
                 doviConfig: vcfg.doviConfig,
                 colorOverride: vcfg.colorOverride,
-                extradataOverride: vcfg.extradataOverride
+                extradataOverride: vcfg.extradataOverride,
+                convertsAnnexBSamples: vcfg.convertsAnnexBSamples
             )
             let probeAudio = MP4SegmentMuxer.AudioConfig(
                 codecpar: cfg.codecpar,
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine+SegmentPlanning.swift b/Sources/AetherEngine/Video/HLSVideoEngine+SegmentPlanning.swift
index 0a2191e05..1218db350 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine+SegmentPlanning.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine+SegmentPlanning.swift
@@ -599,6 +599,9 @@ extension HLSVideoEngine {
         /// never going to reformat this track anyway). Callers fall back to deriving it from the
         /// extradata, which is only safe while the two agree.
         let measuredFraming: VideoNALFraming?
+        /// The packets are Annex B and `extradataOverride` is a length-prefixed record: the muxer
+        /// converts every sample itself and keeps its in-band parameter sets (`AnnexBSampleConverter`).
+        var convertsAnnexBSamples = false
     }
 
     /// Measure the video NAL framing on packets, then decide what config record the muxer gets.
@@ -635,8 +638,8 @@ extension HLSVideoEngine {
 
         let framing = probeVideoNALFraming(demuxer: demuxer, videoStreamIndex: videoStreamIndex)
         guard case .lengthPrefixed = framing else {
-            // The record stays Annex B here: movenc reads it to decide whether to convert the samples,
-            // and these samples do need converting. What it must not keep is a prefix SEI, because the
+            // Except for HEVC on Annex-B packets (below) the record stays Annex B: movenc reads it to
+            // decide whether to convert the samples, and these samples do need converting. What it must not keep is a prefix SEI, because the
             // hvcC movenc then builds carries it as a fourth array (`ff_isom_write_hvcc` collects five
             // NAL types) and Apple TV's HEVC track builder rejects such a record (AE#187). That defense
             // sits on the record path and cannot see this one, so the SEI goes before the muxer runs.
@@ -645,6 +648,25 @@ extension HLSVideoEngine {
             } ?? []
             let canonical = codecID == AV_CODEC_ID_HEVC
                 ? VideoConfigRecord.canonicalizeAnnexBHEVCConfigRecord(source) : nil
+            // HEVC on conclusively Annex-B packets: movenc's own conversion drops every in-band
+            // parameter set under `hvc1`, which breaks a stream that sends a new PPS mid-title. Give
+            // it a length-prefixed record so it copies the samples, and convert them in the muxer
+            // instead, parameter sets kept. Built from the canonical record so the hvcC carries no
+            // SEI array (AE#187).
+            if codecID == AV_CODEC_ID_HEVC, case .annexB? = framing,
+               let record = VideoConfigRecord.fromAnnexB(
+                   canonical ?? source, codecID: codecID,
+                   width: codecpar.pointee.width, height: codecpar.pointee.height) {
+                EngineLog.emit(
+                    "[HLSVideoEngine] #365 HEVC on Annex-B packets: the muxer gets a length-prefixed "
+                    + "record (\(source.count) B → \(record.count) B) and converts the samples itself, "
+                    + "keeping their in-band parameter sets",
+                    category: .session
+                )
+                var result = VideoFramingNormalization(extradataOverride: record, measuredFraming: framing)
+                result.convertsAnnexBSamples = true
+                return result
+            }
             EngineLog.emit(
                 "[HLSVideoEngine] #365 the muxer will reformat this track's samples and the packets "
                 + "are \(framing == nil ? "not conclusively framed" : "Annex B"); the muxer builds the "
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine.swift b/Sources/AetherEngine/Video/HLSVideoEngine.swift
index e8eede9b2..3f56816df 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine.swift
@@ -1594,6 +1594,7 @@ public final class HLSVideoEngine: @unchecked Sendable {
             colorOverride: p5ColorOverride,
             extradataOverride: hevcExtradataOverride,
             nalFramingOverride: measuredVideoNALFraming,
+            convertsAnnexBSamples: framingNormalization.convertsAnnexBSamples,
             nalFramingLatch: NALFramingLatch(confirmed: framingMeasuredLengthPrefixed)
         )
         self.videoStreamIndex = videoIndex
@@ -2633,6 +2634,7 @@ public final class HLSVideoEngine: @unchecked Sendable {
                 codecpar: cfg.codecpar, timeBase: cfg.timeBase,
                 codecTagOverride: cfg.codecTagOverride, doviConfig: cfg.doviConfig,
                 colorOverride: cfg.colorOverride, extradataOverride: cfg.extradataOverride,
+                convertsAnnexBSamples: cfg.convertsAnnexBSamples,
                 nalFramingLatch: cfg.nalFramingLatch),
             stagingDir: staging)
         let framing = cfg.nalFramingOverride ?? A53SEIParser.nalFraming(
diff --git a/Sources/AetherEngine/Video/MP4SegmentMuxer.swift b/Sources/AetherEngine/Video/MP4SegmentMuxer.swift
index 1c59008e6..f204a5c24 100644
--- a/Sources/AetherEngine/Video/MP4SegmentMuxer.swift
+++ b/Sources/AetherEngine/Video/MP4SegmentMuxer.swift
@@ -72,6 +72,10 @@ final class MP4SegmentMuxer {
         /// has numOfArrays=0 (in-band parameter sets) and the engine rebuilt a proper hvcC with
         /// VPS/SPS/PPS arrays; the mp4 muxer writes extradata directly into the hvcC/avcC box.
         let extradataOverride: [UInt8]?
+        /// The video samples are Annex B while `extradataOverride` is a length-prefixed record: the
+        /// muxer converts each sample itself and keeps its in-band parameter sets, which movenc's own
+        /// `hvc1` conversion would drop. See `AnnexBSampleConverter`.
+        let convertsAnnexBSamples: Bool
         /// The session's framing verdict for this track (audit BIT-104); nil gives the muxer its own.
         let nalFramingLatch: NALFramingLatch?
 
@@ -82,6 +86,7 @@ final class MP4SegmentMuxer {
             doviConfig: DoviConfigPolicy = .keep,
             colorOverride: ColorOverride? = nil,
             extradataOverride: [UInt8]? = nil,
+            convertsAnnexBSamples: Bool = false,
             nalFramingLatch: NALFramingLatch? = nil
         ) {
             self.codecpar = codecpar
@@ -90,6 +95,7 @@ final class MP4SegmentMuxer {
             self.doviConfig = doviConfig
             self.colorOverride = colorOverride
             self.extradataOverride = extradataOverride
+            self.convertsAnnexBSamples = convertsAnnexBSamples
             self.nalFramingLatch = nalFramingLatch
         }
     }
@@ -171,6 +177,8 @@ final class MP4SegmentMuxer {
     /// length-prefixed at all. Latched at init: it is a property of the configuration record that
     /// lands in the sample entry, and the AE#561 sanitizer walks every video sample with it.
     private let videoNALLengthPrefixSize: Int?
+    /// Latched from `VideoConfig.convertsAnnexBSamples`.
+    private let convertsAnnexBVideoSamples: Bool
     /// AE#561 harness switch: the sanitizer removes the only shape that reproduces a segment Apple's
     /// parser refuses, so the rung underneath it (the software-path escalation) would have nothing to
     /// be measured against. Read once from the environment, never set in a shipped configuration.
@@ -284,6 +292,7 @@ final class MP4SegmentMuxer {
         self.audioNeedsParsedPacketForMoov =
             audio.map { Self.audioNeedsParsedPacketForMoov($0.codecpar.pointee.codec_id) } ?? false
         self.videoNALFraming = video.nalFramingLatch ?? NALFramingLatch()
+        self.convertsAnnexBVideoSamples = video.convertsAnnexBSamples
         // AE#561: the override, when there is one, is the record that reaches the sample entry. Both
         // carry the same width (the #19 rebuild keeps the source header's first 22 bytes), so this
         // only matters for a source whose own extradata is missing or Annex B.
@@ -633,6 +642,12 @@ final class MP4SegmentMuxer {
 
         let streamIndex = packet.pointee.stream_index
 
+        // Before the AE#561 sanitizer, which walks the sample as the length-prefixed chain the
+        // record declares. A packet with no start code is written as it came.
+        if convertsAnnexBVideoSamples, streamIndex == videoOutputStreamIndex {
+            _ = AnnexBSampleConverter.convertToLengthPrefixed(packet)
+        }
+
         // #64 mid-segment flush bound: cap libavformat's interleaver RAM on a very long segment
         // (degenerate sparse-keyframe plan, or an audio stream that decodes to nothing) by emitting a
         // moof+mdat into the current staging file before the buffered span grows without bound. Tracked
diff --git a/Tests/AetherEngineTests/AnnexBSampleConverterTests.swift b/Tests/AetherEngineTests/AnnexBSampleConverterTests.swift
new file mode 100644
index 000000000..19df958c1
--- /dev/null
+++ b/Tests/AetherEngineTests/AnnexBSampleConverterTests.swift
@@ -0,0 +1,73 @@
+// Annex-B HEVC samples converted by the session muxer instead of movenc (PR #703, MovieClaw P38).
+//
+// movenc's own conversion under `hvc1` drops every in-band VPS/SPS/PPS, so a stream that sends a new
+// PPS mid-title has its later slices decoded against the stale one. The converter must keep every NAL.
+import Foundation
+import Testing
+import AetherLibavcodec
+@testable import AetherEngine
+
+@Suite("Annex-B samples keep their in-band parameter sets (PR #703)")
+struct AnnexBSampleConverterTests {
+
+    private let aud: [UInt8] = [0x46, 0x01, 0x50]
+    private let vps: [UInt8] = [0x40, 0x01, 0x0C]
+    private let pps: [UInt8] = [0x44, 0x01, 0xC0, 0x72]
+    /// An IDR slice carrying an emulation-prevention byte, which must pass through untouched.
+    private let idr: [UInt8] = [0x28, 0x01, 0xAF, 0x00, 0x00, 0x03, 0x01, 0x80]
+
+    private func lengthPrefixed(_ nals: [[UInt8]]) -> [UInt8] {
+        nals.flatMap { nal -> [UInt8] in
+            let n = nal.count
+            return [UInt8(n >> 24 & 0xFF), UInt8(n >> 16 & 0xFF), UInt8(n >> 8 & 0xFF), UInt8(n & 0xFF)] + nal
+        }
+    }
+
+    /// Run the packet-level conversion on a fresh packet holding `bytes`; nil when it declined.
+    private func convert(_ bytes: [UInt8]) -> [UInt8]? {
+        var packet: UnsafeMutablePointer<AVPacket>? = av_packet_alloc()
+        defer { av_packet_free(&packet) }
+        guard let pkt = packet, av_new_packet(pkt, Int32(bytes.count)) == 0 else { return nil }
+        bytes.withUnsafeBytes { _ = memcpy(pkt.pointee.data, $0.baseAddress, bytes.count) }
+        guard AnnexBSampleConverter.convertToLengthPrefixed(pkt) else { return nil }
+        return Array(UnsafeBufferPointer(start: pkt.pointee.data, count: Int(pkt.pointee.size)))
+    }
+
+    @Test("Every NAL survives, parameter sets included, and start-code zero padding is dropped")
+    func keepsParameterSets() {
+        let annexB: [UInt8] = [0, 0, 0, 1] + aud + [0, 0, 1] + vps + [0, 0, 0, 1] + pps
+            + [0, 0, 1] + idr + [0, 0]
+        #expect(convert(annexB) == lengthPrefixed([aud, vps, pps, idr]))
+    }
+
+    @Test("A sample with no start code is declined and left as it was")
+    func lengthPrefixedInputDeclined() {
+        #expect(convert(lengthPrefixed([idr])) == nil)
+    }
+
+    @Test("A NAL in the 256 to 511 byte band is converted once, not split at its own length bytes")
+    func midSizedNAL() {
+        // Its length prefix would read 00 00 01 xx, but the input here is Annex B, so the only start
+        // codes are the real ones and the payload contains none.
+        let slice: [UInt8] = [0x02, 0x01] + [UInt8](repeating: 0x55, count: 300)
+        let annexB: [UInt8] = [0, 0, 0, 1] + pps + [0, 0, 0, 1] + slice
+        #expect(convert(annexB) == lengthPrefixed([pps, slice]))
+    }
+
+    @Test("The converted packet's buffer is a new one, the source buffer is not written")
+    func sourceBufferUntouched() {
+        let annexB: [UInt8] = [0, 0, 1] + pps + [0, 0, 1] + idr
+        var source: UnsafeMutablePointer<AVPacket>? = av_packet_alloc()
+        var shared: UnsafeMutablePointer<AVPacket>? = av_packet_alloc()
+        defer { av_packet_free(&source); av_packet_free(&shared) }
+        guard let src = source, let ref = shared, av_new_packet(src, Int32(annexB.count)) == 0 else {
+            Issue.record("packet allocation failed"); return
+        }
+        annexB.withUnsafeBytes { _ = memcpy(src.pointee.data, $0.baseAddress, annexB.count) }
+        #expect(av_packet_ref(ref, src) == 0)
+        #expect(AnnexBSampleConverter.convertToLengthPrefixed(ref))
+        #expect(Array(UnsafeBufferPointer(start: src.pointee.data, count: Int(src.pointee.size))) == annexB)
+        #expect(Array(UnsafeBufferPointer(start: ref.pointee.data, count: Int(ref.pointee.size)))
+            == lengthPrefixed([pps, idr]))
+    }
+}
diff --git a/docs/architecture.md b/docs/architecture.md
index cd92e6a1d..a57ba7cf6 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -472,6 +472,7 @@ Sources/AetherEngine/
 │   ├── HLSVideoEngine+SegmentPlanning.swift Native path: keyframe / uniform segment plans, extradata + AAC fixups
 │   ├── HLSVideoEngine+LiveReopen.swift      Native path: live source-loss recovery (capped-backoff reopen on the same timeline); VOD backpressure-wedge re-anchor + consumer re-engage nudge, which re-reads the rendered position at nudge time so the zero-tolerance seek never lands behind the on-screen frame (#115)
 │   ├── CodecRoutePolicy.swift               Native path: DV / HDR / codec routing decisions (track types, CODECS strings, VIDEO-RANGE)
+│   ├── AnnexBSampleConverter.swift          Native path: Annex-B HEVC samples rewritten to length-prefixed NALs by the session muxer, in-band VPS/SPS/PPS kept. movenc's own conversion under `hvc1` drops them, so a stream that sends a new PPS mid-title stopped decoding at the change (PR #703)
 │   ├── DoviRpuConverter.swift               Native path: per-packet DV Profile 7 → 8.1 RPU conversion via libdovi (NAL surgery: convert type-62 RPU, drop type-63 EL)
 │   ├── DoviRpuConverter+Probe.swift         Diagnostic DV-conversion probe (`doviConvertProbe` / `DoviConvertProbeResult`), backs `aetherctl dovitest`
 │   ├── Issue65LivelockBreakers.swift        Pure backpressure-wedge detection (`BackpressureWedgeDetector`) breaking the VOD HLS scrub-burst livelock (#65); `seekIsWedged` starvation check + `SeekResumeGuard` single-resume latch for the deadline-bounded seek

From 3cc2cf29107d7c829a2f80939d597b4da8cf2096 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Tue, 6 Oct 2026 22:28:34 +0200
Subject: [PATCH 323/359] diag(audio): the software path's aLead covers live
 DVR sessions too (#395)

7.27.2 wrote the new `[SWDiag]` audio marker in the combined demux loop only. A live
session loaded with `dvrWindowSeconds` runs the ring feeder instead, whose audio pump
never wrote it, so the line kept reading `aLead=-` on exactly the sessions a timeshift
host such as NowSeen runs. The line now reads the pump's own fed PTS there, the value the
pump paces on and a DVR seek clears.

Measured with `aetherctl dvr --path sw`: `aLead=-` on main, `aLead=4.00/3.12/2.12` here.
Diagnostic only, pacing unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                  |  1 +
 .../Native/SoftwarePlaybackHost.swift         | 15 ++++++++++++++-
 .../SWPlaybackDiagStateTests.swift            | 19 +++++++++++++++++++
 3 files changed, 34 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 98f484c24..51bec5f18 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,7 @@ the public-API contract.
 
 ### Fixed
 
+- **`[SWDiag]` reports `aLead` on live DVR sessions as well (#395).** 7.27.2 added the marker to the combined demux loop only. A live session loaded with `dvrWindowSeconds` feeds its audio from the ring pump, which never wrote it, so its line still read `aLead=-` throughout. The line now reads the pump's own fed PTS there, the value the pump paces on. Measured with `aetherctl dvr --path sw`: `aLead=-` before, `aLead=4.00`, `3.12`, `2.12` after. Diagnostic only, pacing unchanged, no API change.
 - **HEVC with a parameter-set change mid-title keeps its picture.** On an Annex-B HEVC source (Blu-ray M2TS, broadcast TS) movenc converted the samples itself and, under the `hvc1` sample entry, dropped every in-band VPS/SPS/PPS, so a stream that sends a new PPS mid-title had every later slice decoded against the stale one: sound continued over a frozen or black picture. The session muxer now gets a length-prefixed record and converts the samples itself with their parameter sets kept, the shape a Matroska remux of the same stream already had; `init.mp4` and `CODECS` are unchanged. The I-frame rendition muxer takes the same path. Measured on a fixture whose PPS changes at 20 s: 463 presented frames in 42 s before (none after the change), 936 after. Diagnosed by yipengfei329 (#703).
 - **A keyframe index that stops minutes before the end is no longer trusted.** A partial scan (an MKV whose Cues are missing or point past EOF) passed both the gap and the coverage check, and the keyframe planner then cut a final segment from the last scanned keyframe to the end of the title, which the producer can never finish. The index now also has to reach within 60 s of the source duration, otherwise the session takes the uniform plan. Diagnosed by yipengfei329 (#703).
 
diff --git a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
index 47c9dd64a..7e0e6f3a5 100644
--- a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
+++ b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
@@ -3132,6 +3132,15 @@ final class SoftwarePlaybackHost {
     /// the line stops rather than repeating itself at 1 Hz for as long as the host holds the engine.
     private var didEmitParkedDiag = false
 
+    /// AE#395: a DVR session feeds audio from the ring pump, which never writes `demuxDiag`, so its
+    /// line read `aLead=-` throughout. The pump's own fed PTS is the marker it paces on, and a DVR
+    /// seek clears it, so it carries no pre-seek value.
+    nonisolated static func diagAudioMarker(
+        demuxLoopPts: Double, dvrPumpPts: Double, isDVRSession: Bool
+    ) -> Double {
+        isDVRSession ? dvrPumpPts : demuxLoopPts
+    }
+
     /// 1 Hz [SWDiag] line: clock + clock delta, decoded-audio and video lead over the clock, parked
     /// video PACKET FIFO depth, rebuffer state, frames produced vs frames handed to the layer with
     /// the spacing of the timestamps they carried, and the display layer's OWN drop counter with its
@@ -3161,7 +3170,11 @@ final class SoftwarePlaybackHost {
             if prevClock.isFinite, clock == prevClock { didEmitParkedDiag = true }
         }
         diagPrevClock = clock
-        let lead = d.lastAudioPts.isFinite && clock.isFinite ? d.lastAudioPts - clock : Double.nan
+        let audioMarker = Self.diagAudioMarker(
+            demuxLoopPts: d.lastAudioPts,
+            dvrPumpPts: audioLookahead.lastFedAudioPTS,
+            isDVRSession: isLive && dvrRing != nil)
+        let lead = audioMarker.isFinite && clock.isFinite ? audioMarker - clock : Double.nan
         let enqueued = framesEnqueued
         let dEnq = enqueued - diagPrevEnqueued
         diagPrevEnqueued = enqueued
diff --git a/Tests/AetherEngineTests/SWPlaybackDiagStateTests.swift b/Tests/AetherEngineTests/SWPlaybackDiagStateTests.swift
index 0eaac5b16..21d4b782c 100644
--- a/Tests/AetherEngineTests/SWPlaybackDiagStateTests.swift
+++ b/Tests/AetherEngineTests/SWPlaybackDiagStateTests.swift
@@ -64,3 +64,22 @@ struct SWPlaybackDiagStateTests {
         #expect(diag.snapshot.lastAudioPts == 4.0)
     }
 }
+
+/// AE#395: the DVR feeder arm delivers audio through the ring pump and never writes `demuxDiag`.
+@Suite("SWDiag audio marker source")
+struct SWDiagAudioMarkerSourceTests {
+
+    @Test("A DVR session reads the pump's fed PTS, not the demux loop's empty marker")
+    func dvrSessionReadsThePump() {
+        let marker = SoftwarePlaybackHost.diagAudioMarker(
+            demuxLoopPts: .nan, dvrPumpPts: 1234.5, isDVRSession: true)
+        #expect(marker == 1234.5)
+    }
+
+    @Test("Every other session keeps the demux loop's marker")
+    func otherSessionsKeepTheDemuxMarker() {
+        let marker = SoftwarePlaybackHost.diagAudioMarker(
+            demuxLoopPts: 16.11, dvrPumpPts: .nan, isDVRSession: false)
+        #expect(marker == 16.11)
+    }
+}

From 92994eff436a92e7617e8619a3abc2807381f71b Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Tue, 6 Oct 2026 22:30:21 +0200
Subject: [PATCH 324/359] chore(release): prep 7.28.1 - aLead on live DVR
 sessions, HEVC in-band parameter sets, partial keyframe index

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                    | 4 ++++
 Examples/README.md                              | 2 +-
 README.md                                       | 6 +++---
 Sources/AetherEngine/AetherEngine+Version.swift | 2 +-
 4 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 51bec5f18..b9b51ec5b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,10 @@ the public-API contract.
 
 ## [Unreleased]
 
+_Nothing yet._
+
+## [7.28.1] - 2026-10-06
+
 ### Fixed
 
 - **`[SWDiag]` reports `aLead` on live DVR sessions as well (#395).** 7.27.2 added the marker to the combined demux loop only. A live session loaded with `dvrWindowSeconds` feeds its audio from the ring pump, which never wrote it, so its line still read `aLead=-` throughout. The line now reads the pump's own fed PTS there, the value the pump paces on. Measured with `aetherctl dvr --path sw`: `aLead=-` before, `aLead=4.00`, `3.12`, `2.12` after. Diagnostic only, pacing unchanged, no API change.
diff --git a/Examples/README.md b/Examples/README.md
index e93f0cea0..0f3766e4f 100644
--- a/Examples/README.md
+++ b/Examples/README.md
@@ -18,7 +18,7 @@ Three samples covering different audiences:
    ```
    https://github.com/superuser404notfound/AetherEngine
    ```
-   Dependency Rule: Up to Next Major Version, starting from `7.28.0`. Add the `AetherEngine` library product to your app target.
+   Dependency Rule: Up to Next Major Version, starting from `7.28.1`. Add the `AetherEngine` library product to your app target.
 
 3. **Drop the file in.** Replace the Xcode template's default `App.swift` (or whatever the generated `@main` file is called) with the contents of [`MinimalPlayerApp.swift`](MinimalPlayer/MinimalPlayerApp.swift). The file is self-contained: it defines both the `@main App` struct and the `ContentView`.
 
diff --git a/README.md b/README.md
index 8b6e8ab7f..6120b0a43 100644
--- a/README.md
+++ b/README.md
@@ -385,7 +385,7 @@ Subtitle cues land in raw source PTS; render the overlay against `player.sourceT
 Install via Swift Package Manager:
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.28.0")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.28.1")
 ```
 
 Three samples ship in `Examples/`:
@@ -632,10 +632,10 @@ Browse all of this as a searchable site at **[aetherengine.superuser404.de](http
 AetherEngine uses [Semantic Versioning](https://semver.org). The public API surface, every `public` declaration in `Sources/AetherEngine/`, is the stability contract. **Major** removes / renames public symbols or breaks adopters; **Minor** adds public API or codec / format support; **Patch** fixes bugs with no public API change. `internal` types are not part of the contract.
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.28.0")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.28.1")
 ```
 
-Pin to `.upToNextMinor(from: "7.28.0")` for stricter teams that prefer to opt into minor bumps explicitly.
+Pin to `.upToNextMinor(from: "7.28.1")` for stricter teams that prefer to opt into minor bumps explicitly.
 
 ## Requirements
 
diff --git a/Sources/AetherEngine/AetherEngine+Version.swift b/Sources/AetherEngine/AetherEngine+Version.swift
index b6c42008d..948d3c405 100644
--- a/Sources/AetherEngine/AetherEngine+Version.swift
+++ b/Sources/AetherEngine/AetherEngine+Version.swift
@@ -11,5 +11,5 @@ extension AetherEngine {
     ///
     /// Between releases, and in a consumer that pins an unreleased commit for a device test, this
     /// names the last PUBLISHED version the checkout descends from, not every patch in it.
-    public nonisolated static let version = "7.28.0"
+    public nonisolated static let version = "7.28.1"
 }

From efdd6e8a7f01a4ffd87ac9b72309892f44bff42a Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Tue, 6 Oct 2026 22:43:32 +0200
Subject: [PATCH 325/359] fix(live): the first-serve latch covers engine-cut
 sources by default (#686)

AVPlayer's second plain /media.m3u8 request on a bounded fastZap start
waited out a second grace on raw MPEG-TS. The reporter's Apple TV A/B
(1080p59.94, 1.001 s segments, three runs per cell) found the latch
reaching the picture 1.003 to 1.039 s sooner on every bounded start,
0.5 to 1.5 s nearer the edge after 60 s, and no stall, -16832 or -12888
in 18 latched launches. Rebuilds from a backlog served a full cushion
in both arms. AETHER_FIRST_SERVE_LATCH_ALL=0 restores the old gate.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../Video/VideoSegmentProvider.swift           | 18 +++++++++---------
 .../Issue686FirstServeLatchArmTests.swift      |  7 ++++---
 docs/cli.md                                    |  6 +++---
 3 files changed, 16 insertions(+), 15 deletions(-)

diff --git a/Sources/AetherEngine/Video/VideoSegmentProvider.swift b/Sources/AetherEngine/Video/VideoSegmentProvider.swift
index 2975be9f8..f4d4e5463 100644
--- a/Sources/AetherEngine/Video/VideoSegmentProvider.swift
+++ b/Sources/AetherEngine/Video/VideoSegmentProvider.swift
@@ -112,11 +112,12 @@ enum LiveEdgePolicy {
     static let boundedStartFloorArmed =
         ProcessInfo.processInfo.environment["AETHER_BOUNDED_START_FLOOR"] == "1"
 
-    /// AE#686, env-gated (`AETHER_FIRST_SERVE_LATCH_ALL=1`) for the same reason: it extends #684's
-    /// first-serve latch from ingest sessions to sources the engine cuts itself, so the second plain
-    /// manifest request no longer waits out a second grace. Read once.
+    /// AE#686: #684's first-serve latch covers sources the engine cuts itself too, so AVPlayer's second
+    /// plain manifest request no longer waits out a second grace. On by default since the Apple TV A/B
+    /// (first picture 1.003 to 1.039 s sooner on every bounded start, no stall in 18 launches);
+    /// `AETHER_FIRST_SERVE_LATCH_ALL=0` restores the old gate for a comparison run. Read once.
     static let firstServeLatchAllArmed =
-        ProcessInfo.processInfo.environment["AETHER_FIRST_SERVE_LATCH_ALL"] == "1"
+        ProcessInfo.processInfo.environment["AETHER_FIRST_SERVE_LATCH_ALL"] != "0"
 
     /// AVPlayer's unchanged-playlist patience: it tolerates a playlist that has not changed for this
     /// multiple of the served TARGETDURATION before drawing `-12888`. The one number the cadence floor
@@ -731,8 +732,8 @@ final class VideoSegmentProvider: HLSSegmentProvider, @unchecked Sendable {
     /// AE#594 arm B: skip the bounded branch, so the wait ends at the full holdback cushion or at the
     /// outer wall-clock deadline. Measurement arm, off unless the environment asks for it.
     private let boundedStartFloorsAtHoldback: Bool
-    /// AE#686 arm: the first-serve latch also covers a source the engine cuts itself. Measurement arm,
-    /// off unless the environment asks for it.
+    /// AE#686: the first-serve latch also covers a source the engine cuts itself. The engine passes
+    /// `LiveEdgePolicy.firstServeLatchAllArmed`, on unless the environment opts out.
     private let firstServeLatchCoversEngineCut: Bool
     /// AE#374: whether the first-serve gate has already reported the interval it held. Read and written
     /// only under `firstSegmentCondition`, inside `waitForFirstLiveSegment` and its two account helpers.
@@ -2611,9 +2612,8 @@ final class VideoSegmentProvider: HLSSegmentProvider, @unchecked Sendable {
         defer { parkedWaiters -= 1 }
         while true {
             if waitersCancelled { return false }
-            // Ingest sessions only. A source the engine cuts itself keeps the gate it had: there the
-            // second request's wait is part of where the session ends up behind the producing edge,
-            // which is AE#594's question and not this one's. AE#686 measures it behind an arm.
+            // AE#684 latched ingest sessions; AE#686 extends it to a source the engine cuts itself,
+            // where the second grace bought nothing on device but a session 1 s further from the edge.
             if firstManifestServed, liveCadencePolicy != nil || firstServeLatchCoversEngineCut {
                 accountForRepeatServe(since: enteredAt, note: "first-serve latch")
                 return true
diff --git a/Tests/AetherEngineTests/Issue686FirstServeLatchArmTests.swift b/Tests/AetherEngineTests/Issue686FirstServeLatchArmTests.swift
index 24ad4a5a5..35d2a8bc4 100644
--- a/Tests/AetherEngineTests/Issue686FirstServeLatchArmTests.swift
+++ b/Tests/AetherEngineTests/Issue686FirstServeLatchArmTests.swift
@@ -2,7 +2,8 @@
 // AVPlayer's second plain `/media.m3u8` request for a second grace, measured on an Apple TV as
 // 1.015 to 1.384 s on every bounded start. #684 latched the gate for ingest sessions only, because
 // whether the engine-cut path pays for skipping that wait (a session closer to the producing edge)
-// was never measured. `AETHER_FIRST_SERVE_LATCH_ALL=1` is the arm that measures it; off by default.
+// was never measured. The Apple TV A/B showed it does not, so the latch is now on by default and
+// `AETHER_FIRST_SERVE_LATCH_ALL=0` is the opt-out.
 import XCTest
 @testable import AetherEngine
 
@@ -34,9 +35,9 @@ final class Issue686FirstServeLatchArmTests: XCTestCase {
         return Double(DispatchTime.now().uptimeNanoseconds - start.uptimeNanoseconds) / 1_000_000_000
     }
 
-    func testTheArmIsOffWithoutTheEnvironment() {
+    func testTheLatchIsOnUnlessTheEnvironmentOptsOut() {
         XCTAssertEqual(LiveEdgePolicy.firstServeLatchAllArmed,
-                       ProcessInfo.processInfo.environment["AETHER_FIRST_SERVE_LATCH_ALL"] == "1")
+                       ProcessInfo.processInfo.environment["AETHER_FIRST_SERVE_LATCH_ALL"] != "0")
     }
 
     /// Two 0.2 s segments against a 3 s holdback: the bounded start, grace 0.5 s.
diff --git a/docs/cli.md b/docs/cli.md
index 2e042b122..f7927e5d1 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -767,9 +767,9 @@ No run stalled in either arm. The extra segment on 6,4 is the short one, and the
 
 **Whether a join is spent is a fact, not arithmetic.** The seal may only be taken short once the join has nothing more to give, and "cut content plus one segment reaches the summed EXTINF" is not that fact: `--dur 6.3` over 6 s of media never adds up, and a first version built on the sum sealed the full value there and took the bounded start (2.23 s to first picture against 0.20 s). The reader states it instead: the whole join batch is committed, its FIFO is empty, and the cutter is parked waiting for the next delivery. Three runs per arm on each inflated shape with three segments listed: served at once in all six (0.000 to 0.034 s of hold), TD 5 on 6 s media and TD 9 on 10 s. Two more shapes belong to the same fact. A demuxed audio rendition (run the origin twice, video-only and audio-only segments behind a master) makes the cutter park on the AUDIO reader when the audio ends a little before the video, so the fact is stated for the cutter and not for the video reader: both join batches committed and either reader dry. Read off the video reader alone it never became true, 2.2 s to first picture under `.fastZap` and 10.4 s under `.standard`; now 0.18 to 0.21 s in all six cells (6 s and 10 s `.fastZap`, 10 s `.standard`, audio aligned and 0.2 s short, three runs each), as on 7.25.1. And a join slower than the `.fastZap` grace (`play --max-concurrent-requests 1` behind `--rate-kbps 4000`) is served by the bounded start before it is spent, seals the full 6 or 10 over a window under its holdback and draws a `-16832` warning at the start: first picture 5.05 to 6.08 s against 7.05 to 8.26 s on 7.25.1, which still pays the second grace there, and no `-12888` against 1 to 3.
 
-**The gate held the second playlist request too.** AVPlayer opens with two `/media.m3u8` requests, each re-enters `waitForFirstLiveSegment`, and on a bounded start each waited its own grace (`GET /media.m3u8` at 2.81 s, `GET /init.mp4` at 4.83 s). On an ingest the gate now opens for good once a manifest has gone out. On a source the engine cuts itself it does not: that second grace is the "+2.07 s at the picture" of the AE#594 table above, and removing it there also leaves the session up to 2 s closer to the producing edge, which is that issue's open question. The raw-TS control (`live --fast-zap --realtime --preroll 0`, two seeds, two runs per arm) reads the same in both arms: first manifest at 3.84 to 3.96 s, `init.mp4` at 6.11 to 6.33 s, first picture at 6.20 to 6.58 s, playhead 6.3 to 6.8 s behind the wall clock. The AE#594 table stands as printed.
+**The gate held the second playlist request too.** AVPlayer opens with two `/media.m3u8` requests, each re-enters `waitForFirstLiveSegment`, and on a bounded start each waited its own grace (`GET /media.m3u8` at 2.81 s, `GET /init.mp4` at 4.83 s). On an ingest the gate now opens for good once a manifest has gone out. On a source the engine cuts itself it did not until 7.28.2 (next paragraph): that second grace is the "+2.07 s at the picture" of the AE#594 table above, and removing it there also leaves the session up to 2 s closer to the producing edge, which is that issue's open question. The raw-TS control (`live --fast-zap --realtime --preroll 0`, two seeds, two runs per arm) reads the same in both arms: first manifest at 3.84 to 3.96 s, `init.mp4` at 6.11 to 6.33 s, first picture at 6.20 to 6.58 s, playhead 6.3 to 6.8 s behind the wall clock. The AE#594 table stands as printed.
 
-**AE#686 measures that second grace behind an arm.** `AETHER_FIRST_SERVE_LATCH_ALL=1` applies the same latch to a source the engine cuts itself. It is a measurement arm like `AETHER_BOUNDED_START_FLOOR`, read once per process and off by default, because what it may cost (a session closer to the producing edge for its whole life) needs a device that seeks to edge-minus-holdback, which this harness does not. Both arms now print how long AVPlayer's second plain request waited, once per session:
+**AE#686 applies the same latch to a source the engine cuts itself, by default since 7.28.2.** It started as a measurement arm (`AETHER_FIRST_SERVE_LATCH_ALL=1`, 7.26.3), because what it may cost (a session closer to the producing edge for its whole life) needs a device that seeks to edge-minus-holdback, which this harness does not. The reporter's Apple TV A/B answered that: on 1080p59.94 raw TS with 1.001 s segments, every bounded start reached its picture 1.003 to 1.039 s sooner with the latch, the session sat 0.5 to 1.5 s nearer the edge after 60 s, and 18 latched launches logged no stall, `-16832` or `-12888`. A rebuild from a backlog served a full cushion in both arms, so the latch had nothing to skip there. `AETHER_FIRST_SERVE_LATCH_ALL=0` restores the old gate, read once per process. Both arms print how long AVPlayer's second plain request waited, once per session:
 
 ```
 [HLSVideoEngine] repeat live manifest request held 2.003s, fastZap bounded start after 2.000s grace
@@ -785,7 +785,7 @@ No run stalled in either arm. The extra segment on 6,4 is the short one, and the
 | 1080p59.94, 1 s GOP | off | 1.22 to 1.23 s, 3 segments | 1.011 s | 2.43 s | 3.2 s | 38.30 to 38.40 s | 0 |
 | 1080p59.94, 1 s GOP | on | 1.24 s, 3 segments | 0.000 s | 1.41 to 1.44 s | 1.1 s | 39.19 to 39.30 s | 0 |
 
-The arm removes exactly the grace, and the session ends that much closer to the edge. Whether that costs a stall is the device half.
+The latch removes exactly the grace, and the session ends that much closer to the edge; on the device that cost no stall.
 
 The full matrix (6 s and 10 s segments, 3, 4 and 8 listed, both profiles, three runs per arm) is in `api.md` under the live join; `.standard` drops `--fast-zap` from the `play` line.
 

From 637466fa8fb1a474bbb6689d896d42e2aa5a7c34 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Tue, 6 Oct 2026 22:44:14 +0200
Subject: [PATCH 326/359] chore(release): prep 7.28.2 - first-serve latch
 covers engine-cut live sources by default

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                    | 6 ++++++
 Examples/README.md                              | 2 +-
 README.md                                       | 6 +++---
 Sources/AetherEngine/AetherEngine+Version.swift | 2 +-
 4 files changed, 11 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b9b51ec5b..565962af2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,12 @@ the public-API contract.
 
 _Nothing yet._
 
+## [7.28.2] - 2026-10-06
+
+### Changed
+
+- **A bounded live start on a source the engine cuts itself no longer waits a second grace (#686).** AVPlayer opens with two plain `/media.m3u8` requests, and on raw MPEG-TS under `.fastZap` each one waited out the bounded-start grace; #684's first-serve latch spared only ingest sessions. It now covers engine-cut sources too, the behaviour 7.26.3 put behind `AETHER_FIRST_SERVE_LATCH_ALL=1`. Measured by cmcpherson274 on an Apple TV 4K (1080p59.94 H.264 + AAC, 1.001 s segments, three runs per cell): every bounded start reached its picture 1.003 to 1.039 s sooner, the session sat 0.5 to 1.5 s nearer the edge after 60 s, and 18 latched launches logged no stall, `-16832` or `-12888`. Rebuilds from a backlog served a full cushion either way. `AETHER_FIRST_SERVE_LATCH_ALL=0` restores the old gate. No API change.
+
 ## [7.28.1] - 2026-10-06
 
 ### Fixed
diff --git a/Examples/README.md b/Examples/README.md
index 0f3766e4f..bf1d67b09 100644
--- a/Examples/README.md
+++ b/Examples/README.md
@@ -18,7 +18,7 @@ Three samples covering different audiences:
    ```
    https://github.com/superuser404notfound/AetherEngine
    ```
-   Dependency Rule: Up to Next Major Version, starting from `7.28.1`. Add the `AetherEngine` library product to your app target.
+   Dependency Rule: Up to Next Major Version, starting from `7.28.2`. Add the `AetherEngine` library product to your app target.
 
 3. **Drop the file in.** Replace the Xcode template's default `App.swift` (or whatever the generated `@main` file is called) with the contents of [`MinimalPlayerApp.swift`](MinimalPlayer/MinimalPlayerApp.swift). The file is self-contained: it defines both the `@main App` struct and the `ContentView`.
 
diff --git a/README.md b/README.md
index 6120b0a43..27f78cc85 100644
--- a/README.md
+++ b/README.md
@@ -385,7 +385,7 @@ Subtitle cues land in raw source PTS; render the overlay against `player.sourceT
 Install via Swift Package Manager:
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.28.1")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.28.2")
 ```
 
 Three samples ship in `Examples/`:
@@ -632,10 +632,10 @@ Browse all of this as a searchable site at **[aetherengine.superuser404.de](http
 AetherEngine uses [Semantic Versioning](https://semver.org). The public API surface, every `public` declaration in `Sources/AetherEngine/`, is the stability contract. **Major** removes / renames public symbols or breaks adopters; **Minor** adds public API or codec / format support; **Patch** fixes bugs with no public API change. `internal` types are not part of the contract.
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.28.1")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.28.2")
 ```
 
-Pin to `.upToNextMinor(from: "7.28.1")` for stricter teams that prefer to opt into minor bumps explicitly.
+Pin to `.upToNextMinor(from: "7.28.2")` for stricter teams that prefer to opt into minor bumps explicitly.
 
 ## Requirements
 
diff --git a/Sources/AetherEngine/AetherEngine+Version.swift b/Sources/AetherEngine/AetherEngine+Version.swift
index 948d3c405..cc4756768 100644
--- a/Sources/AetherEngine/AetherEngine+Version.swift
+++ b/Sources/AetherEngine/AetherEngine+Version.swift
@@ -11,5 +11,5 @@ extension AetherEngine {
     ///
     /// Between releases, and in a consumer that pins an unreleased commit for a device test, this
     /// names the last PUBLISHED version the checkout descends from, not every patch in it.
-    public nonisolated static let version = "7.28.1"
+    public nonisolated static let version = "7.28.2"
 }

From 8f2d2bf387ae4d0e4bd339234e91e275af1ee716 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Tue, 6 Oct 2026 22:52:45 +0200
Subject: [PATCH 327/359] test(core): read the stacked rebuild's transport
 without polling for .loading (LIF-102)

The custom-source rebuild can enter and leave `.loading` between two 20 ms polls, so
`waitFor { state == .loading }` waited for a state that was already gone until the
two-minute `.timeLimit` failed the run (CI red on 7.28.1 and on b27f2971). The read is
now a main-actor job enqueued as `.loading` is published, which runs at the rebuild's
first suspension, where a second rebuild stacked behind it reads. Still fails with the
`transportIntentUnderReconstruction` park removed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../Issue464ReloadPreservesSessionTests.swift | 25 ++++++++++++++-----
 1 file changed, 19 insertions(+), 6 deletions(-)

diff --git a/Tests/AetherEngineTests/Issue464ReloadPreservesSessionTests.swift b/Tests/AetherEngineTests/Issue464ReloadPreservesSessionTests.swift
index b4fce693e..a11b2c6e6 100644
--- a/Tests/AetherEngineTests/Issue464ReloadPreservesSessionTests.swift
+++ b/Tests/AetherEngineTests/Issue464ReloadPreservesSessionTests.swift
@@ -1,3 +1,4 @@
+import Combine
 import Foundation
 import Testing
 @testable import AetherEngine
@@ -177,13 +178,25 @@ struct Issue464RebuildCallSiteTransportTests {
         engine.pause()
         let url = try #require(engine.loadedURL)
 
-        let rebuild = Task { @MainActor in
-            await engine.reloadWithAudioOverride(
-                url: url, audioStreamIndex: nil, expectedGeneration: engine.loadGeneration)
+        // Stack the read behind the rebuild instead of polling for `.loading`: a custom-source
+        // rebuild can enter and leave `.loading` between two polls, and the poll then waits for a
+        // state that is already gone until `.timeLimit` ends the run (red CI on 2026-10-05 and
+        // 2026-10-06). A main-actor job enqueued as `.loading` is published runs at the rebuild's
+        // first suspension, which is exactly where a second rebuild raised behind it would read.
+        var stacked: Task<(PlaybackState, Bool), Never>?
+        let observer = engine.$state.sink { next in
+            MainActor.assumeIsolated {
+                guard stacked == nil, next == .loading else { return }
+                stacked = Task { @MainActor in (engine.state, engine.sessionRebuildResumesPlaying) }
+            }
         }
-        try await waitFor { engine.state == .loading }
-        #expect(!engine.sessionRebuildResumesPlaying)
-        _ = await rebuild.value
+        defer { observer.cancel() }
+
+        _ = await engine.reloadWithAudioOverride(
+            url: url, audioStreamIndex: nil, expectedGeneration: engine.loadGeneration)
+        let (stateThen, resumes) = try #require(await stacked?.value)
+        #expect(stateThen == .loading)
+        #expect(!resumes)
     }
 
     @Test("a mount with autoplay off stays paused across a custom-source reload")

From 4a86b522dbeb6906b421f170fe18530da7a76132 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Tue, 6 Oct 2026 23:08:06 +0200
Subject: [PATCH 328/359] fix(demux): repair missing composition offsets across
 a seek onto an open GOP (#699)

Two defects behind the software host's resume reading decode order on HEVC
MP4s without ctts (reported on #699 after 7.27.3):

- The repair verdict was reached at the first read. The software host seeks
  to its resume position before that read, so the sample started on the
  landing CRA, whose picture order is not 0, and the classifier refused. A
  seek before the first read now settles the verdict at the head first.

- After any seek the rewriter anchored the landing keyframe as the first
  picture displayed. An open GOP's CRA is displayed after the leading
  pictures decoded behind it, so the axis sat one slot early per leading
  picture and B pictures fell below their decode time and went out
  untouched. The session now holds from the landing to the first trailing
  picture, counts the leading pictures, and anchors with that count.

Twin fixture with a CRA and four RASL pictures at frame 30; each half fails
the new tests without the other.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 Sources/AetherEngine/Demuxer/Demuxer.swift    |  18 +-
 .../Video/H264CompositionOffsetRepair.swift   |  79 +++++-
 ...ompositionOffsetRepairFirstSeekTests.swift | 268 ++++++++++++++++++
 3 files changed, 358 insertions(+), 7 deletions(-)
 create mode 100644 Tests/AetherEngineTests/CompositionOffsetRepairFirstSeekTests.swift

diff --git a/Sources/AetherEngine/Demuxer/Demuxer.swift b/Sources/AetherEngine/Demuxer/Demuxer.swift
index 6466a7e35..fde9b153f 100644
--- a/Sources/AetherEngine/Demuxer/Demuxer.swift
+++ b/Sources/AetherEngine/Demuxer/Demuxer.swift
@@ -1887,6 +1887,16 @@ public final class Demuxer: @unchecked Sendable {
         decideCompositionRepairLocked()
     }
 
+    /// #409: a seek moves the read position, so the repair drops its picture-order anchor and
+    /// re-anchors on the landing keyframe. A seek that comes before the first read (the software
+    /// host's resume, #699) settles the verdict at the head first: sampled at the landing, the
+    /// stream would start on an open-GOP keyframe whose picture order is not 0, and the classifier
+    /// refuses that, so the whole session played in decode order. Caller holds `accessLock`.
+    private func noteCompositionRepairSeekLocked() {
+        if !compositionRepairEvaluated { decideCompositionRepairLocked() }
+        compositionRepair?.noteSeek()
+    }
+
     /// #409: reads far enough into the source for the verdict, holding every
     /// packet it consumed so nothing is lost. Called before anything reads a timestamp axis off this
     /// demuxer: the container index and the packets must describe the same ladder, and only the
@@ -2139,7 +2149,7 @@ public final class Demuxer: @unchecked Sendable {
               let timestamp = Self.ticks(forSeconds: seconds, timeBase: Self.avTimeBase) else { return false }
         // #409: the read position moves, so the repair drops its picture-order anchor and
         // re-anchors on the next keyframe (a seek always lands on one).
-        compositionRepair?.noteSeek()
+        noteCompositionRepairSeekLocked()
         if let reader = timeSeekableReader {
             dropPeekedPacketsLocked()
             guard repositionTimeSeekable(reader, toSourceSeconds: seconds, streamIndex: -1) else { return false }
@@ -2173,7 +2183,7 @@ public final class Demuxer: @unchecked Sendable {
               streamIndex < Int32(ctx.pointee.nb_streams) else { return false }
         // #409: the read position moves, so the repair drops its picture-order anchor and
         // re-anchors on the next keyframe (a seek always lands on one).
-        compositionRepair?.noteSeek()
+        noteCompositionRepairSeekLocked()
         if let reader = timeSeekableReader,
            let stream = ctx.pointee.streams[Int(streamIndex)] {
             let timeBase = stream.pointee.time_base
@@ -2313,7 +2323,7 @@ public final class Demuxer: @unchecked Sendable {
         guard let timestamp = Self.ticks(forSeconds: seconds, timeBase: timeBase) else { return false }
         // #409: the read position moves, so the repair drops its picture-order anchor and
         // re-anchors on the next keyframe (a seek always lands on one).
-        compositionRepair?.noteSeek()
+        noteCompositionRepairSeekLocked()
         // #268: a time-seekable source repositions itself instead of paying libavformat's byte-space
         // binary search, which on an index-less MPEG-TS is either wedged or broken (round 10 below) and
         // over HTTP would additionally be a request storm. No read deadline is armed: the reader's
@@ -2529,7 +2539,7 @@ public final class Demuxer: @unchecked Sendable {
         accessLock.lock()
         defer { accessLock.unlock() }
         guard let ctx = formatContext else { return false }
-        compositionRepair?.noteSeek()  // #409: re-anchor on the next keyframe
+        noteCompositionRepairSeekLocked()  // #409: re-anchor on the next keyframe
         guard isSourceSeekable else { return false }  // audit HLS-103, see `seek(to:)`
         dropPeekedPacketsLocked()
         let ret = avformat_seek_file(ctx, -1, Int64.min, byteTarget, Int64.max, AVSEEK_FLAG_BYTE)
diff --git a/Sources/AetherEngine/Video/H264CompositionOffsetRepair.swift b/Sources/AetherEngine/Video/H264CompositionOffsetRepair.swift
index f47dac467..f718bd9d2 100644
--- a/Sources/AetherEngine/Video/H264CompositionOffsetRepair.swift
+++ b/Sources/AetherEngine/Video/H264CompositionOffsetRepair.swift
@@ -444,6 +444,10 @@ enum H264CompositionOffsetRepair {
         private(set) var sequenceBaseOrdinal: Int64?
         /// A seek leaves the parser and the sequence anchor behind; the next keyframe re-anchors.
         private var awaitingReanchor = true
+        /// Pictures that follow the landing keyframe in decode order but precede it in display
+        /// order (an open GOP's leading pictures). The landing is displayed that many slots after
+        /// the one it is decoded in, so the re-anchor has to know the count.
+        private var landingLeadingPictures: Int64 = 0
         /// Pictures emitted untouched because no anchor was available or the arithmetic did not
         /// close. Surfaced so a stream this repair does not describe is visible as a number.
         private(set) var unrepairedPictures = 0
@@ -455,6 +459,11 @@ enum H264CompositionOffsetRepair {
             awaitingReanchor = true
             sequenceAnchorDTS = nil
             sequenceBaseOrdinal = nil
+            landingLeadingPictures = 0
+        }
+
+        mutating func noteLanding(leadingPictures: Int64) {
+            landingLeadingPictures = max(0, leadingPictures)
         }
 
         /// nil when the picture cannot be placed; the caller then emits it untouched.
@@ -482,8 +491,12 @@ enum H264CompositionOffsetRepair {
                     return nil
                 }
                 let landingIndex = pictureOrderCount / plan.pocStep
+                // The landing is decoded in slot k and displayed in slot k + leading, so the
+                // sequence origin sits `landingIndex - leading` slots before its decode time.
+                let (anchorSlots, slotsOverflow) = landingIndex.subtractingReportingOverflow(landingLeadingPictures)
                 // Audit BIT-101: a 64-bit `tfdt` step and a landing order near -2^31 leave Int64.
-                let (landingTicks, productOverflow) = landingIndex.multipliedReportingOverflow(by: plan.step)
+                let (landingTicks, productOverflow) = slotsOverflow
+                    ? (0, true) : anchorSlots.multipliedReportingOverflow(by: plan.step)
                 let (anchor, anchorOverflow) = dts.subtractingReportingOverflow(landingTicks)
                 guard !productOverflow, !anchorOverflow else {
                     unrepairedPictures += 1
@@ -492,7 +505,7 @@ enum H264CompositionOffsetRepair {
                 sequenceAnchorDTS = anchor
                 sequenceBaseOrdinal = plan.presentationOrdinal(ladderTimestamp: dts)
                     .flatMap { ordinal -> Int64? in
-                        let (base, overflow) = ordinal.subtractingReportingOverflow(landingIndex)
+                        let (base, overflow) = ordinal.subtractingReportingOverflow(anchorSlots)
                         return overflow ? nil : base
                     }
                 awaitingReanchor = false
@@ -612,6 +625,10 @@ final class H264CompositionOffsetRepairSession {
     private var held: [(packet: UnsafeMutablePointer<AVPacket>, pictureOrderCount: Int64?)] = []
     private var heldBytes = 0
     private var verdictDescription = "sampling"
+    /// After a seek on a repaired stream: nil until the landing keyframe arrives, then its picture
+    /// order while the packets behind it are held to count its leading pictures.
+    private var relanding = false
+    private var landingPictureOrder: Int64?
 
     /// nil unless this stream is the exact shape the defect needs: ISO-BMFF, H.264 or HEVC, and a
     /// bitstream that declares reordered pictures. Everything else never sees a parser or a held
@@ -676,6 +693,7 @@ final class H264CompositionOffsetRepairSession {
         case .off:
             return monitorsPartialOffsets ? partialRepairCandidate?.ingest(packet) ?? false : false
         case .repairing:
+            if relanding { return ingestAfterSeek(packet) }
             guard packet.pointee.stream_index == streamIndex else { return false }
             applyRepair(to: packet, pictureOrderCount: reader?.pictureOrderCount(for: packet))
             return false
@@ -704,6 +722,58 @@ final class H264CompositionOffsetRepairSession {
         }
     }
 
+    /// A seek lands on a keyframe that may be an open GOP's entry point, displayed after the leading
+    /// pictures decoded behind it. Their number is only known at the first picture that follows the
+    /// landing in display order (leading pictures all precede the trailing ones in decode order), so
+    /// everything from the landing up to that picture is held, every stream, and then repaired with
+    /// the count. Without it the post-seek axis sat that many slots early, which put B pictures
+    /// below their own decode time and left them in decode order (#699, resume onto a CRA).
+    private func ingestAfterSeek(_ packet: UnsafeMutablePointer<AVPacket>) -> Bool {
+        var pictureOrderCount: Int64?
+        if packet.pointee.stream_index == streamIndex {
+            pictureOrderCount = reader?.pictureOrderCount(for: packet)
+            if landingPictureOrder == nil {
+                // Pictures before the landing keyframe cannot be placed; the rewriter passes them
+                // through untouched, as it did before.
+                guard (packet.pointee.flags & AV_PKT_FLAG_KEY) != 0, let pictureOrderCount else {
+                    applyRepair(to: packet, pictureOrderCount: pictureOrderCount)
+                    return false
+                }
+                landingPictureOrder = pictureOrderCount
+            } else if let landing = landingPictureOrder, let pictureOrderCount, pictureOrderCount > landing {
+                held.append((packet, pictureOrderCount))
+                finishLanding()
+                return true
+            }
+        } else if landingPictureOrder == nil {
+            return false
+        }
+        held.append((packet, pictureOrderCount))
+        heldBytes += Int(max(0, packet.pointee.size))
+        if heldBytes >= H264CompositionOffsetRepair.sampleByteBudget
+            || held.count >= H264CompositionOffsetRepair.heldPacketCeiling {
+            finishLanding()
+        }
+        return true
+    }
+
+    private func finishLanding() {
+        relanding = false
+        guard var rewriter else { return }
+        if let landing = landingPictureOrder {
+            let leading = held.filter {
+                $0.packet.pointee.stream_index == streamIndex
+                    && ($0.pictureOrderCount.map { $0 < landing } ?? false)
+            }.count
+            rewriter.noteLanding(leadingPictures: Int64(leading))
+        }
+        for entry in held where entry.packet.pointee.stream_index == streamIndex {
+            applyRepair(to: entry.packet, pictureOrderCount: entry.pictureOrderCount, using: &rewriter)
+        }
+        self.rewriter = rewriter
+        landingPictureOrder = nil
+    }
+
     /// A healthy file usually proves itself on its first packet, and paying twelve packets of hold
     /// for it would tax every well-formed MP4 with B-frames on the platform.
     private var earlyHealthyVerdict: Bool {
@@ -714,6 +784,7 @@ final class H264CompositionOffsetRepairSession {
     /// EOF during sampling. Decides on what is there, so the held packets are still delivered.
     func endOfStream() {
         if phase == .sampling { decide() }
+        if relanding { finishLanding() }
         if monitorsPartialOffsets { partialRepairCandidate?.endOfStream() }
     }
 
@@ -733,6 +804,8 @@ final class H264CompositionOffsetRepairSession {
         case .repairing:
             rewriter?.noteSeek()
             reader?.reset()
+            relanding = true
+            landingPictureOrder = nil
         case .off:
             break
         }
@@ -754,7 +827,7 @@ final class H264CompositionOffsetRepairSession {
     }
 
     func dequeue() -> UnsafeMutablePointer<AVPacket>? {
-        guard phase != .sampling else { return nil }
+        guard phase != .sampling, !relanding else { return nil }
         if !held.isEmpty { return held.removeFirst().packet }
         return monitorsPartialOffsets ? partialRepairCandidate?.dequeue() : nil
     }
diff --git a/Tests/AetherEngineTests/CompositionOffsetRepairFirstSeekTests.swift b/Tests/AetherEngineTests/CompositionOffsetRepairFirstSeekTests.swift
new file mode 100644
index 000000000..122a11542
--- /dev/null
+++ b/Tests/AetherEngineTests/CompositionOffsetRepairFirstSeekTests.swift
@@ -0,0 +1,268 @@
+import Foundation
+import AetherLibavcodec
+import Testing
+@testable import AetherEngine
+
+/// #699 follow-up: the software host seeks to a resume position before its first read. The repair
+/// verdict used to be reached at that first read, so it sampled the landing instead of the head, met
+/// an open-GOP keyframe whose picture order is not 0, refused, and the session played in decode
+/// order. A seek before the first read now settles the verdict at the head first.
+@Suite("Composition-offset repair when the first move is a seek (#699)")
+struct CompositionOffsetRepairFirstSeekTests {
+
+    private struct Timestamps: Equatable, CustomStringConvertible {
+        var pts: Int64
+        var dts: Int64
+        var description: String { "pts=\(pts) dts=\(dts)" }
+    }
+
+    /// Opens the fixture, seeks before reading anything (the resume shape), and returns the video
+    /// timestamps from the landing on.
+    private static func videoTimestamps(
+        base64: String, seekingTo seconds: Double, afterReading readFirst: Int = 0
+    ) throws -> [Timestamps] {
+        let data = try #require(Data(base64Encoded: base64, options: .ignoreUnknownCharacters))
+        let demuxer = Demuxer()
+        try demuxer.open(reader: DataIOReader(data: data), formatHint: "mp4")
+        defer { demuxer.close() }
+        for _ in 0..<readFirst {
+            var owned = try demuxer.readPacket()
+            trackedPacketFree(&owned)
+        }
+        #expect(demuxer.seek(to: seconds))
+        let videoIndex = demuxer.videoStreamIndex
+        var result: [Timestamps] = []
+        while let packet = try? demuxer.readPacket() {
+            if packet.pointee.stream_index == videoIndex {
+                result.append(Timestamps(pts: packet.pointee.pts, dts: packet.pointee.dts))
+            }
+            var owned: UnsafeMutablePointer<AVPacket>? = packet
+            trackedPacketFree(&owned)
+        }
+        return result
+    }
+
+    @Test("a resume onto the CRA carries the healthy twin's timestamps")
+    func resumeOntoCRAIsRepaired() throws {
+        let healthy = try Self.videoTimestamps(base64: Self.healthyFixtureBase64, seekingTo: 0.6)
+        let repaired = try Self.videoTimestamps(base64: Self.missingFixtureBase64, seekingTo: 0.6)
+        // The landing is the CRA at 0.6 s (7680 ticks), decoded ahead of its leading pictures.
+        #expect(healthy.first == Timestamps(pts: 7680, dts: 6144))
+        #expect(healthy.contains { $0.pts != $0.dts })
+        #expect(repaired == healthy)
+    }
+
+    /// The native path decides at the head and seeks later. Its landing used to be anchored as if
+    /// the CRA were the first picture displayed, so the axis sat one slot early per leading picture.
+    @Test("a seek after playback started counts the landing's leading pictures")
+    func seekAfterReadingCountsLeadingPictures() throws {
+        let healthy = try Self.videoTimestamps(base64: Self.healthyFixtureBase64, seekingTo: 0.6, afterReading: 8)
+        let repaired = try Self.videoTimestamps(base64: Self.missingFixtureBase64, seekingTo: 0.6, afterReading: 8)
+        #expect(healthy.first == Timestamps(pts: 7680, dts: 6144))
+        #expect(repaired == healthy)
+    }
+
+    @Test("the healthy twin is untouched by the head sample a first seek now takes")
+    func healthyTwinSurvivesTheHeadSample() throws {
+        let fromHead = try Self.videoTimestamps(base64: Self.healthyFixtureBase64, seekingTo: 0)
+        #expect(fromHead.count == 60)
+        #expect(fromHead.first == Timestamps(pts: 0, dts: -512))
+    }
+
+    /// 64x64 HEVC Main 10, 50 fps, 60 frames, four B pictures per hierarchical mini-GOP, and an
+    /// open-GOP CRA with leading pictures at frame 30.
+    ///
+    ///     ffmpeg -f lavfi -i 'testsrc=s=64x64:r=50:d=1.2' -frames:v 60 -c:v libx265 -preset ultrafast \
+    ///       -pix_fmt yuv420p10le -x265-params \
+    ///       'bframes=4:b-pyramid=1:b-adapt=0:keyint=30:min-keyint=30:scenecut=0:open-gop=1' \
+    ///       -tag:v hvc1 -movflags +faststart healthy.mp4
+    ///     ffmpeg -i healthy.mp4 -map 0:v:0 -c:v copy -bsf:v 'setts=pts=DTS' \
+    ///       -movflags +faststart missing.mp4
+    private static let healthyFixtureBase64 = """
+        AAAAHGZ0eXBpc29tAAACAGlzb21pc28ybXA0MQAAD1htb292AAAAbG12aGQAAAAAAAAAAAAAAAAAAAPoAAAEsAABAAABAAAAAAAA
+        AAAAAAAAAQAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACAAAOgnRy
+        YWsAAABcdGtoZAAAAAMAAAAAAAAAAAAAAAEAAAAAAAAEsAAAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAEAAAAAAAAA
+        AAAAAAAAAEAAAAAAQAAAAEAAAAAAACRlZHRzAAAAHGVsc3QAAAAAAAAAAQAABLAAAAIAAAEAAAAADfptZGlhAAAAIG1kaGQAAAAA
+        AAAAAAAAAAAAADIAAAA8AFXEAAAAAAAtaGRscgAAAAAAAAAAdmlkZQAAAAAAAAAAAAAAAFZpZGVvSGFuZGxlcgAAAA2lbWluZgAA
+        ABR2bWhkAAAAAQAAAAAAAAAAAAAAJGRpbmYAAAAcZHJlZgAAAAAAAAABAAAADHVybCAAAAABAAANZXN0YmwAAAoZc3RzZAAAAAAA
+        AAABAAAKCWh2YzEAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAQABAAEgAAABIAAAAAAAAAAEVTGF2YzYyLjI4LjEwMSBsaWJ4MjY1
+        AAAAAAAAAAAAAAAY//8AAAmFaHZjQwECIAAAAJAAAAAAAB7wAPz9+voAAA8EoAABABhAAQwB//8CIAAAAwCQAAADAAADAB6VmAmh
+        AAEAKkIBAQIgAAADAJAAAAMAAAMAHqAggQTZZWZKTC8BaAgAAAMACAAAAwGQQKIAAQAGRAHAc8CJJwABCQpOAQX///////////8F
+        LKLeCbUXR9u7VaT+f8L8TngyNjUgKGJ1aWxkIDIxNikgLSA0LjIrMS1lNDQ0NzQ0OltNYWMgT1MgWF1bY2xhbmcgMjEuMC4wXVs2
+        NCBiaXRdIDEwYml0IC0gSC4yNjUvSEVWQyBjb2RlYyAtIENvcHlyaWdodCAyMDEzLTIwMTggKGMpIE11bHRpY29yZXdhcmUsIElu
+        YyAtIGh0dHA6Ly94MjY1Lm9yZyAtIG9wdGlvbnM6IGNwdWlkPTM0IGZyYW1lLXRocmVhZHM9MSBuby13cHAgbm8tcG1vZGUgbm8t
+        cG1lIG5vLXBzbnIgbm8tc3NpbSBsb2ctbGV2ZWw9MCBiaXRkZXB0aD0xMCBpbnB1dC1jc3A9MSBmcHM9NTAvMSBpbnB1dC1yZXM9
+        NjR4NjQgaW50ZXJsYWNlPTAgdG90YWwtZnJhbWVzPTAgbGV2ZWwtaWRjPTAgaGlnaC10aWVyPTEgdWhkLWJkPTAgcmVmPTEgbm8t
+        YWxsb3ctbm9uLWNvbmZvcm1hbmNlIG5vLXJlcGVhdC1oZWFkZXJzIGFubmV4YiBuby1hdWQgbm8tZW9iIG5vLWVvcyBuby1ocmQg
+        aW5mbyBoYXNoPTAgdGVtcG9yYWwtbGF5ZXJzPTAgb3Blbi1nb3AgbWluLWtleWludD0zMCBrZXlpbnQ9MzAgZ29wLWxvb2thaGVh
+        ZD0wIGJmcmFtZXM9NCBiLWFkYXB0PTAgYi1weXJhbWlkIGJmcmFtZS1iaWFzPTAgcmMtbG9va2FoZWFkPTUgbG9va2FoZWFkLXNs
+        aWNlcz0wIHNjZW5lY3V0PTAgbm8taGlzdC1zY2VuZWN1dCByYWRsPTAgbm8tc3BsaWNlIG5vLWludHJhLXJlZnJlc2ggY3R1PTMy
+        IG1pbi1jdS1zaXplPTE2IG5vLXJlY3Qgbm8tYW1wIG1heC10dS1zaXplPTMyIHR1LWludGVyLWRlcHRoPTEgdHUtaW50cmEtZGVw
+        dGg9MSBsaW1pdC10dT0wIHJkb3EtbGV2ZWw9MCBkeW5hbWljLXJkPTAuMDAgbm8tc3NpbS1yZCBuby1zaWduaGlkZSBuby10c2tp
+        cCBuci1pbnRyYT0wIG5yLWludGVyPTAgbm8tY29uc3RyYWluZWQtaW50cmEgc3Ryb25nLWludHJhLXNtb290aGluZyBtYXgtbWVy
+        Z2U9MiBsaW1pdC1yZWZzPTAgbm8tbGltaXQtbW9kZXMgbWU9MCBzdWJtZT0wIG1lcmFuZ2U9NTcgdGVtcG9yYWwtbXZwIG5vLWZy
+        YW1lLWR1cCBuby1obWUgbm8td2VpZ2h0cCBuby13ZWlnaHRiIG5vLWFuYWx5emUtc3JjLXBpY3MgZGVibG9jaz0wOjAgbm8tc2Fv
+        IG5vLXNhby1ub24tZGVibG9jayByZD0yIHNlbGVjdGl2ZS1zYW89MCBlYXJseS1za2lwIHJza2lwIGZhc3QtaW50cmEgbm8tdHNr
+        aXAtZmFzdCBuby1jdS1sb3NzbGVzcyBuby1iLWludHJhIG5vLXNwbGl0cmQtc2tpcCByZHBlbmFsdHk9MCBwc3ktcmQ9Mi4wMCBw
+        c3ktcmRvcT0wLjAwIG5vLXJkLXJlZmluZSBuby1sb3NzbGVzcyBjYnFwb2Zmcz0wIGNycXBvZmZzPTAgcmM9Y3JmIGNyZj0yOC4w
+        IHFjb21wPTAuNjAgcXBzdGVwPTQgc3RhdHMtd3JpdGU9MCBzdGF0cy1yZWFkPTAgaXByYXRpbz0xLjQwIHBicmF0aW89MS4zMCBh
+        cS1tb2RlPTEgYXEtc3RyZW5ndGg9MC4wMCBjdXRyZWUgem9uZS1jb3VudD0wIG5vLXN0cmljdC1jYnIgcWctc2l6ZT0zMiBuby1y
+        Yy1ncmFpbiBxcG1heD02OSBxcG1pbj0wIG5vLWNvbnN0LXZidiBzYXI9MSBvdmVyc2Nhbj0wIHZpZGVvZm9ybWF0PTUgcmFuZ2U9
+        MCBjb2xvcnByaW09MiB0cmFuc2Zlcj0yIGNvbG9ybWF0cml4PTIgY2hyb21hbG9jPTAgZGlzcGxheS13aW5kb3c9MCBjbGw9MCww
+        IG1pbi1sdW1hPTAgbWF4LWx1bWE9MTAyMyBsb2cyLW1heC1wb2MtbHNiPTggdnVpLXRpbWluZy1pbmZvIHZ1aS1ocmQtaW5mbyBz
+        bGljZXM9MSBuby1vcHQtcXAtcHBzIG5vLW9wdC1yZWYtbGlzdC1sZW5ndGgtcHBzIG5vLW11bHRpLXBhc3Mtb3B0LXJwcyBzY2Vu
+        ZWN1dC1iaWFzPTAuMDUgbm8tb3B0LWN1LWRlbHRhLXFwIG5vLWFxLW1vdGlvbiBuby1oZHIxMCBuby1oZHIxMC1vcHQgbm8tZGhk
+        cjEwLW9wdCBuby1pZHItcmVjb3Zlcnktc2VpIGFuYWx5c2lzLXJldXNlLWxldmVsPTAgYW5hbHlzaXMtc2F2ZS1yZXVzZS1sZXZl
+        bD0wIGFuYWx5c2lzLWxvYWQtcmV1c2UtbGV2ZWw9MCBzY2FsZS1mYWN0b3I9MCByZWZpbmUtaW50cmE9MCByZWZpbmUtaW50ZXI9
+        MCByZWZpbmUtbXY9MSByZWZpbmUtY3R1LWRpc3RvcnRpb249MCBuby1saW1pdC1zYW8gY3R1LWluZm89MCBuby1sb3dwYXNzLWRj
+        dCByZWZpbmUtYW5hbHlzaXMtdHlwZT0wIGNvcHktcGljPTEgbWF4LWF1c2l6ZS1mYWN0b3I9MS4wIG5vLWR5bmFtaWMtcmVmaW5l
+        IG5vLXNpbmdsZS1zZWkgbm8taGV2Yy1hcSBuby1zdnQgbm8tZmllbGQgcXAtYWRhcHRhdGlvbi1yYW5nZT0xLjAwIHNjZW5lY3V0
+        LWF3YXJlLXFwPTBjb25mb3JtYW5jZS13aW5kb3ctb2Zmc2V0cyByaWdodD0wIGJvdHRvbT0wIGRlY29kZXItbWF4LXJhdGU9MCBu
+        by12YnYtbGl2ZS1tdWx0aS1wYXNzIG5vLW1jc3RmIG5vLXNicmMgbm8tZnJhbWUtcmOAAAAACmZpZWwBAAAAABBwYXNwAAAAAQAA
+        AAEAAAAUYnRydAAAAAAAAE6eAAAAAAAAABhzdHRzAAAAAAAAAAEAAAA8AAABAAAAABhzdHNzAAAAAAAAAAIAAAABAAAAGwAAAEhz
+        ZHRwAAAAACAQEBgYGBAQGBgYEBAYGBgQEBgYGBAQGBgYIBAYGBgQEBgYGBAQGBgYEBAYGBgQEBgYGBAQGBgYEBAYGAAAAZhjdHRz
+        AAAAAAAAADEAAAABAAACAAAAAAEAAAYAAAAAAQAAAwAAAAACAAAAAAAAAAEAAAEAAAAAAQAABgAAAAABAAADAAAAAAIAAAAAAAAA
+        AQAAAQAAAAABAAAGAAAAAAEAAAMAAAAAAgAAAAAAAAABAAABAAAAAAEAAAYAAAAAAQAAAwAAAAACAAAAAAAAAAEAAAEAAAAAAQAA
+        BgAAAAABAAADAAAAAAIAAAAAAAAAAQAAAQAAAAABAAAGAAAAAAEAAAMAAAAAAgAAAAAAAAABAAABAAAAAAEAAAYAAAAAAQAAAwAA
+        AAACAAAAAAAAAAEAAAEAAAAAAQAABgAAAAABAAADAAAAAAIAAAAAAAAAAQAAAQAAAAABAAAGAAAAAAEAAAMAAAAAAgAAAAAAAAAB
+        AAABAAAAAAEAAAYAAAAAAQAAAwAAAAACAAAAAAAAAAEAAAEAAAAAAQAABgAAAAABAAADAAAAAAIAAAAAAAAAAQAAAQAAAAABAAAF
+        AAAAAAEAAAIAAAAAAQAAAAAAAAABAAABAAAAABxzdHNjAAAAAAAAAAEAAAABAAAAPAAAAAEAAAEEc3RzegAAAAAAAAAAAAAAPAAA
+        BBUAAAAVAAAADgAAAA8AAAAPAAAADgAAACwAAAAPAAAAEAAAABAAAAAPAAAALAAAABAAAAAQAAAAEAAAAA8AAAA6AAAAEAAAABAA
+        AAAQAAAADwAAAC4AAAAQAAAAEAAAABAAAAAPAAADAwAAABAAAAAQAAAAEAAAAA8AAAAZAAAADgAAAA8AAAAPAAAADgAAAC4AAAAP
+        AAAAEAAAABAAAAAPAAAAMAAAABAAAAAQAAAAEAAAAA8AAAA1AAAAEAAAABAAAAAQAAAADwAAACwAAAAQAAAAEAAAABAAAAAPAAAA
+        LwAAABAAAAAPAAAADwAAABRzdGNvAAAAAAAAAAEAAA+EAAAAYnVkdGEAAABabWV0YQAAAAAAAAAhaGRscgAAAAAAAAAAbWRpcmFw
+        cGwAAAAAAAAAAAAAAAAtaWxzdAAAACWpdG9vAAAAHWRhdGEAAAABAAAAAExhdmY2Mi4xMi4xMDEAAAAIZnJlZQAAC9NtZGF0AAAE
+        ESgBrCmAqAtj3ixvvtxkKmMD3eX+ImIdIq0/LQeyKklx7fWmEt6THfOXuqnxTy5j68zrVuZCkBZyAW3NTMnVjDWR58jaXrdK4MTV
+        4zZD4kgnUXLTiZjW6GVzt8f/1mmD9wKt8fsbkIZldLLRz2XXJreSW52v0Hs30w1FCqCcD0vuQ5liavcsOoD3gsstUZYvgeFGsWtL
+        bFSkSDeWJ7BcAiN/z9yxYVkNWrpWVYkKE/+JabKF0F11CrKkNRv45k/fLEamFfTqAI5vBqQVIqE5o925E14g4ZQF+nWtk1qaMRWT
+        qnDREz035U3J2USY03KgMr2qGDDxxTMsFw6tOV+ipcPuS1AtJvyEaNS6cABF+nUKnegDInOgCmVCPWZ5u75iUFCZTzEwVncVIlXZ
+        eRYVLfgLpMWt2RfKQEFuapdJSWuwwjb8LamSib4jum3wDfrVdM2j0bJAnnZvDO6Iy3yaeP26GhKv///ba5Q48eqAjXtiPE4j2Pwo
+        A+qlwxf9TbPz479o2DJDzfm7kSBtTxJVt+yoyuVS0iPHwUvyMDZn1szJSSHzD6EJt8zAaLmgCQnlDmB0xPcZdikT8DnLOkwnEltF
+        QkIXnxUpaJgcASICN1J0EM9R8lVZjK+rTElRT3tsykgs7QSpDt7Mf0S5PPEgNHUwmMMHn6Gs2k1zpXQRD60DtcgMWfoqprALJcjZ
+        onISd/e6G+pVlY+ByiKB+XTN4QPK64Tqk0ObanoRNqWoz3lZ62JcZpR/NYLaYvTE+mwNemnifXmNoHT9wPkC6zyzE4B7IKmt5Oq5
+        DjqcqxdeUrMFvSTc3q2TgkaX6sOQF6estWisjYbGFCbA38FpEURoFpQuc8wdY8uYDhbjCCDNOxMOnijsFNrXpYhUs3ZNTAx13AMC
+        Phd72hbDRGCZpO80Z4fO937bk4WUMdvK8JZrn+PgG/Kr+mprjHf7AvP88YXxdFGwkEhDTYHg8wmVU4/AfE9AWVKChz5//ynZsaMo
+        pC23dnt7BCckf9BzoZDmZxCsyyKn5XCjddEl+W4I/UO2rdWQjjIUOQM0vhfoi2+KrC0CUHiAKZ3ag9x+y5cNeHN09L2S9XAALIkr
+        OchQrgsB2AvE/AO1nQa0DOwLPAaQWYEgJV5yTe08S371798MB1SrF2jU88SIleLNF7cob3v01E+ibmbQGTCd3FsV7CZbspvs9XOq
+        aAUf2jJ1ksoU7qji2v+b1OON7e2ODMFaXuoAcqZoF/bgiZggZJnvHretRW6ZGfjIHOAECVXpwXHuW/MgEFh1necwZOM0bti9FSvb
+        7kru2YB2KOdVMc8DEAjSUO2vdmU4ShS8g5hU+YKnpbWHyI5Gt7hyQ8bo1xrHMBT00EY+Cyn8hUbj8t8QkrEvGDGJvgAAABECAdAp
+        S4gUQLNaRKOrvmUrlwAAAAoCAeBknWCBZJJ4AAAACwAB4CT1XokDGJDwAAAACwAB4ETXXokDCJDwAAAACgAB4Ia34IGMkPAAAAAo
+        AgHQUJLV4gUQs1pBXstflTAR3T1JbAVIbopYqDUPYTj4IWE81h/fcAAAAAsCAeECJ1dYIFmSeAAAAAwAAeDG9VXokDGAkPAAAAAM
+        AAHg5tV16JAwgJDwAAAACwAB4SIt14IGMJDwAAAAKAIB0Hiy1dYgUbNX3UUiza+6i4MPZOqs+PtC41JPtDUUci+9EDsBEIAAAAAM
+        AgHhoidS1ggWQJJ4AAAADAAB4Wb1VeiQMYCQ8AAAAAwAAeGG1XXokDCAkPAAAAALAAHhwi3XggYwkPAAAAA2AgHQoLLV1iBRs1pF
+        8J9CPc4R37vjlJUMsDOIYRTv0YJs83cr9E8qQK09NOxkCdS4zy+1btkwAAAADAIB4kInUtYIFsCSeAAAAAwAAeIG9VXokDCAkPAA
+        AAAMAAHiJtV16JAxgJDwAAAACwAB4mIt14IGMJDwAAAAKgIB0Miy1dYgU7NaRdlMD+s+HomYswol7sg/lZAGfD5iKIaClD9WuaxS
+        2AAAAAwCAeLiJ1LWCBZAkngAAAAMAAHipvVV6JAwgJDwAAAADAAB4sbVdeiQMYCQ8AAAAAsAAeMCLdeCBjCQ8AAAAv8qAax4WUjJ
+        CWCjD2eNFYBL9VgaG1nDmWYZT44HnoNrRoPGSdWf2Hq+kAVp0AETi8bXaTSzsF+JUlDhD3/F6v4RJdJ0nr//gzctK9Kf0HYjnaTZ
+        QMpnbQiyS3n232faVg21N8KsG1ZNqscyqiiIt+wc12DDVvXwz86qXsby+oe0oXOGHLAA6ze7alSy/+qrwwd7NVYDo6yNBZR23bKp
+        M5r65RAYpV46uGId2xk+8hFx+DOKF9516y9z2Sc00Ri24Iq8OdCVWNvHWKPB635A0pBuAawUdfGgyCjIPQh1+ZsBXLhT41eJcSlV
+        UWuNOqZIyerG7zNStDP2dylZqCW9Ul3XmIVPSEc2f//1fOq+gXwDQffb0/SFIXZLPKzHdWYD8RUI1pDR0l5ExhcvZ/zMdpZ4t8Rb
+        3QIVCbN0yjPy1vJ4jjIoHM1NcKMLIDnBVOh+zt3QM3leO+4ZFjjf8r6ocDE3KoN2gNvpPm5L7CIhQ2ifdpvoTgBmjVh6cTm/Wf49
+        1E5/q/5y8gPCFZxtlbEBQZkn2j7DPTns4UYiJ1uD4UzOKIMq4i+rfpo8hTFNA8HtVN5lJ6Tv0c9CPeh5uAdwwKVrbaPtiazzMXZ8
+        jOAfZ6hngSyJI4nhYaAOHW/sy5dm1McbDzOwuZ1T0nPhGqyWqtEvQ69uxZZZNkWS55TB8snliUp4sKy1/uLfA8tGJUBuumU7yJbO
+        xPgOpaR06JWocWRaho4OonanCAUCSTLLif+PF4HqU6crLSctC7oafi+qctoINabIeRpCshIeTFlTDX7bdZIBUWd74n7FdxIpmLzt
+        JCcvZyMLQNpn1zHi6WV4IBFALtCCOBSJ2P/TcS9/Z0C/BRexcGZFe88yAbVa+15bZQ44+t92JW+PlM3cDHMdP+cGWxf7QdajToUs
+        mR17uo1Y6BteMHVLrjVz37Mu4OZtaIqp1LwfD/Gl0BAF8ph1b9l6rYoUppu2nj1CrHd/+0kJgooDopxHesfYiVHVpsapV0t6aHAr
+        jyCdhMCBL/e4CAAAAAwSAeOCJ1LWCBbAkngAAAAMEAHjRvVV6JAxgJDwAAAADBAB42bVdeiQMYCQ8AAAAAsQAeOiLdeCBhCQ8AAA
+        ABUCAdEZS4gUwKWUARtgIeLbo2Dsm4AAAAAKAgHkJJ1ggWSSeAAAAAsAAePk9V6JAxiQ8AAAAAsAAeQE116JAxiQ8AAAAAoAAeRG
+        t+CBhJDwAAAAKgIB0UCS1eIFMLNaRZJaHzbJq9zDac6CVeR4Ose49AXhreJ5h3CAkxnAgAAAAAsCAeTCJ1dYIFmSeAAAAAwAAeSG
+        9VXokDCAkPAAAAAMAAHkptV16JAxgJDwAAAACwAB5OIt14IGEJDwAAAALAIB0Wiy1dYgU7NX0oxEpyVXkd0PlmoD4UCzwOy1Kn4H
+        M30P7lZDezVWpePWAAAADAIB5WInUtYIFkCSeAAAAAwAAeUm9VXokDCAkPAAAAAMAAHlRtV16JAxgJDwAAAACwAB5YIt14IGEJDw
+        AAAAMQIB0ZCy1dYgU7NaQVA7FgvGoiPkdZiJRmkpLH4HCwR/7s/PnTGo0asEbqN5ii4n+OAAAAAMAgHmAidS1ggWwJJ4AAAADAAB
+        5cb1VeiQMICQ8AAAAAwAAeXm1XXokDCAkPAAAAALAAHmIi3XggYwkPAAAAAoAgHRuLLV1iBTs1pIU6hYy2wO0STGAgb99r9Labtc
+        ybfbnmQ6/OsmvgAAAAwCAeaiJ1LWCBbAkngAAAAMAAHmZvVV6JAwgJDwAAAADAAB5obVdeiQMICQ8AAAAAsAAebCLdeCBhCQ8AAA
+        ACsCAdHYslXWIFOtmAzX0NRed3pQXw+62wWHkLbUGOmJJygg3cAOzHxoBHGAAAAADAIB5yIlUtYIFsCSeAAAAAsAAecG9deiQMaQ
+        8AAAAAsAAedCLVeCBjCQ8A==
+        """
+
+    private static let missingFixtureBase64 = """
+        AAAAHGZ0eXBpc29tAAACAGlzb21pc28ybXA0MQAADcBtb292AAAAbG12aGQAAAAAAAAAAAAAAAAAAAPoAAAEiAABAAABAAAAAAAA
+        AAAAAAAAAQAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACAAAM6nRy
+        YWsAAABcdGtoZAAAAAMAAAAAAAAAAAAAAAEAAAAAAAAEiAAAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAEAAAAAAAAA
+        AAAAAAAAAEAAAAAAQAAAAEAAAAAAACRlZHRzAAAAHGVsc3QAAAAAAAAAAQAABIgAAAIAAAEAAAAADGJtZGlhAAAAIG1kaGQAAAAA
+        AAAAAAAAAAAAADIAAAA8AFXEAAAAAAAtaGRscgAAAAAAAAAAdmlkZQAAAAAAAAAAAAAAAFZpZGVvSGFuZGxlcgAAAAwNbWluZgAA
+        ABR2bWhkAAAAAQAAAAAAAAAAAAAAJGRpbmYAAAAcZHJlZgAAAAAAAAABAAAADHVybCAAAAABAAALzXN0YmwAAAoZc3RzZAAAAAAA
+        AAABAAAKCWh2YzEAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAQABAAEgAAABIAAAAAAAAAAEVTGF2YzYyLjI4LjEwMSBsaWJ4MjY1
+        AAAAAAAAAAAAAAAY//8AAAmFaHZjQwECIAAAAJAAAAAAAB7wAPz9+voAAA8EoAABABhAAQwB//8CIAAAAwCQAAADAAADAB6VmAmh
+        AAEAKkIBAQIgAAADAJAAAAMAAAMAHqAggQTZZWZKTC8BaAgAAAMACAAAAwGQQKIAAQAGRAHAc8CJJwABCQpOAQX///////////8F
+        LKLeCbUXR9u7VaT+f8L8TngyNjUgKGJ1aWxkIDIxNikgLSA0LjIrMS1lNDQ0NzQ0OltNYWMgT1MgWF1bY2xhbmcgMjEuMC4wXVs2
+        NCBiaXRdIDEwYml0IC0gSC4yNjUvSEVWQyBjb2RlYyAtIENvcHlyaWdodCAyMDEzLTIwMTggKGMpIE11bHRpY29yZXdhcmUsIElu
+        YyAtIGh0dHA6Ly94MjY1Lm9yZyAtIG9wdGlvbnM6IGNwdWlkPTM0IGZyYW1lLXRocmVhZHM9MSBuby13cHAgbm8tcG1vZGUgbm8t
+        cG1lIG5vLXBzbnIgbm8tc3NpbSBsb2ctbGV2ZWw9MCBiaXRkZXB0aD0xMCBpbnB1dC1jc3A9MSBmcHM9NTAvMSBpbnB1dC1yZXM9
+        NjR4NjQgaW50ZXJsYWNlPTAgdG90YWwtZnJhbWVzPTAgbGV2ZWwtaWRjPTAgaGlnaC10aWVyPTEgdWhkLWJkPTAgcmVmPTEgbm8t
+        YWxsb3ctbm9uLWNvbmZvcm1hbmNlIG5vLXJlcGVhdC1oZWFkZXJzIGFubmV4YiBuby1hdWQgbm8tZW9iIG5vLWVvcyBuby1ocmQg
+        aW5mbyBoYXNoPTAgdGVtcG9yYWwtbGF5ZXJzPTAgb3Blbi1nb3AgbWluLWtleWludD0zMCBrZXlpbnQ9MzAgZ29wLWxvb2thaGVh
+        ZD0wIGJmcmFtZXM9NCBiLWFkYXB0PTAgYi1weXJhbWlkIGJmcmFtZS1iaWFzPTAgcmMtbG9va2FoZWFkPTUgbG9va2FoZWFkLXNs
+        aWNlcz0wIHNjZW5lY3V0PTAgbm8taGlzdC1zY2VuZWN1dCByYWRsPTAgbm8tc3BsaWNlIG5vLWludHJhLXJlZnJlc2ggY3R1PTMy
+        IG1pbi1jdS1zaXplPTE2IG5vLXJlY3Qgbm8tYW1wIG1heC10dS1zaXplPTMyIHR1LWludGVyLWRlcHRoPTEgdHUtaW50cmEtZGVw
+        dGg9MSBsaW1pdC10dT0wIHJkb3EtbGV2ZWw9MCBkeW5hbWljLXJkPTAuMDAgbm8tc3NpbS1yZCBuby1zaWduaGlkZSBuby10c2tp
+        cCBuci1pbnRyYT0wIG5yLWludGVyPTAgbm8tY29uc3RyYWluZWQtaW50cmEgc3Ryb25nLWludHJhLXNtb290aGluZyBtYXgtbWVy
+        Z2U9MiBsaW1pdC1yZWZzPTAgbm8tbGltaXQtbW9kZXMgbWU9MCBzdWJtZT0wIG1lcmFuZ2U9NTcgdGVtcG9yYWwtbXZwIG5vLWZy
+        YW1lLWR1cCBuby1obWUgbm8td2VpZ2h0cCBuby13ZWlnaHRiIG5vLWFuYWx5emUtc3JjLXBpY3MgZGVibG9jaz0wOjAgbm8tc2Fv
+        IG5vLXNhby1ub24tZGVibG9jayByZD0yIHNlbGVjdGl2ZS1zYW89MCBlYXJseS1za2lwIHJza2lwIGZhc3QtaW50cmEgbm8tdHNr
+        aXAtZmFzdCBuby1jdS1sb3NzbGVzcyBuby1iLWludHJhIG5vLXNwbGl0cmQtc2tpcCByZHBlbmFsdHk9MCBwc3ktcmQ9Mi4wMCBw
+        c3ktcmRvcT0wLjAwIG5vLXJkLXJlZmluZSBuby1sb3NzbGVzcyBjYnFwb2Zmcz0wIGNycXBvZmZzPTAgcmM9Y3JmIGNyZj0yOC4w
+        IHFjb21wPTAuNjAgcXBzdGVwPTQgc3RhdHMtd3JpdGU9MCBzdGF0cy1yZWFkPTAgaXByYXRpbz0xLjQwIHBicmF0aW89MS4zMCBh
+        cS1tb2RlPTEgYXEtc3RyZW5ndGg9MC4wMCBjdXRyZWUgem9uZS1jb3VudD0wIG5vLXN0cmljdC1jYnIgcWctc2l6ZT0zMiBuby1y
+        Yy1ncmFpbiBxcG1heD02OSBxcG1pbj0wIG5vLWNvbnN0LXZidiBzYXI9MSBvdmVyc2Nhbj0wIHZpZGVvZm9ybWF0PTUgcmFuZ2U9
+        MCBjb2xvcnByaW09MiB0cmFuc2Zlcj0yIGNvbG9ybWF0cml4PTIgY2hyb21hbG9jPTAgZGlzcGxheS13aW5kb3c9MCBjbGw9MCww
+        IG1pbi1sdW1hPTAgbWF4LWx1bWE9MTAyMyBsb2cyLW1heC1wb2MtbHNiPTggdnVpLXRpbWluZy1pbmZvIHZ1aS1ocmQtaW5mbyBz
+        bGljZXM9MSBuby1vcHQtcXAtcHBzIG5vLW9wdC1yZWYtbGlzdC1sZW5ndGgtcHBzIG5vLW11bHRpLXBhc3Mtb3B0LXJwcyBzY2Vu
+        ZWN1dC1iaWFzPTAuMDUgbm8tb3B0LWN1LWRlbHRhLXFwIG5vLWFxLW1vdGlvbiBuby1oZHIxMCBuby1oZHIxMC1vcHQgbm8tZGhk
+        cjEwLW9wdCBuby1pZHItcmVjb3Zlcnktc2VpIGFuYWx5c2lzLXJldXNlLWxldmVsPTAgYW5hbHlzaXMtc2F2ZS1yZXVzZS1sZXZl
+        bD0wIGFuYWx5c2lzLWxvYWQtcmV1c2UtbGV2ZWw9MCBzY2FsZS1mYWN0b3I9MCByZWZpbmUtaW50cmE9MCByZWZpbmUtaW50ZXI9
+        MCByZWZpbmUtbXY9MSByZWZpbmUtY3R1LWRpc3RvcnRpb249MCBuby1saW1pdC1zYW8gY3R1LWluZm89MCBuby1sb3dwYXNzLWRj
+        dCByZWZpbmUtYW5hbHlzaXMtdHlwZT0wIGNvcHktcGljPTEgbWF4LWF1c2l6ZS1mYWN0b3I9MS4wIG5vLWR5bmFtaWMtcmVmaW5l
+        IG5vLXNpbmdsZS1zZWkgbm8taGV2Yy1hcSBuby1zdnQgbm8tZmllbGQgcXAtYWRhcHRhdGlvbi1yYW5nZT0xLjAwIHNjZW5lY3V0
+        LWF3YXJlLXFwPTBjb25mb3JtYW5jZS13aW5kb3ctb2Zmc2V0cyByaWdodD0wIGJvdHRvbT0wIGRlY29kZXItbWF4LXJhdGU9MCBu
+        by12YnYtbGl2ZS1tdWx0aS1wYXNzIG5vLW1jc3RmIG5vLXNicmMgbm8tZnJhbWUtcmOAAAAACmZpZWwBAAAAABBwYXNwAAAAAQAA
+        AAEAAAAUYnRydAAAAAAAAE6eAABOngAAABhzdHRzAAAAAAAAAAEAAAA8AAABAAAAABhzdHNzAAAAAAAAAAIAAAABAAAAGwAAAEhz
+        ZHRwAAAAACAQEBgYGBAQGBgYEBAYGBgQEBgYGBAQGBgYIBAYGBgQEBgYGBAQGBgYEBAYGBgQEBgYGBAQGBgYEBAYGAAAABxzdHNj
+        AAAAAAAAAAEAAAABAAAAPAAAAAEAAAEEc3RzegAAAAAAAAAAAAAAPAAABBUAAAAVAAAADgAAAA8AAAAPAAAADgAAACwAAAAPAAAA
+        EAAAABAAAAAPAAAALAAAABAAAAAQAAAAEAAAAA8AAAA6AAAAEAAAABAAAAAQAAAADwAAAC4AAAAQAAAAEAAAABAAAAAPAAADAwAA
+        ABAAAAAQAAAAEAAAAA8AAAAZAAAADgAAAA8AAAAPAAAADgAAAC4AAAAPAAAAEAAAABAAAAAPAAAAMAAAABAAAAAQAAAAEAAAAA8A
+        AAA1AAAAEAAAABAAAAAQAAAADwAAACwAAAAQAAAAEAAAABAAAAAPAAAALwAAABAAAAAPAAAADwAAABRzdGNvAAAAAAAAAAEAAA3s
+        AAAAYnVkdGEAAABabWV0YQAAAAAAAAAhaGRscgAAAAAAAAAAbWRpcmFwcGwAAAAAAAAAAAAAAAAtaWxzdAAAACWpdG9vAAAAHWRh
+        dGEAAAABAAAAAExhdmY2Mi4xMi4xMDEAAAAIZnJlZQAAC9NtZGF0AAAEESgBrCmAqAtj3ixvvtxkKmMD3eX+ImIdIq0/LQeyKklx
+        7fWmEt6THfOXuqnxTy5j68zrVuZCkBZyAW3NTMnVjDWR58jaXrdK4MTV4zZD4kgnUXLTiZjW6GVzt8f/1mmD9wKt8fsbkIZldLLR
+        z2XXJreSW52v0Hs30w1FCqCcD0vuQ5liavcsOoD3gsstUZYvgeFGsWtLbFSkSDeWJ7BcAiN/z9yxYVkNWrpWVYkKE/+JabKF0F11
+        CrKkNRv45k/fLEamFfTqAI5vBqQVIqE5o925E14g4ZQF+nWtk1qaMRWTqnDREz035U3J2USY03KgMr2qGDDxxTMsFw6tOV+ipcPu
+        S1AtJvyEaNS6cABF+nUKnegDInOgCmVCPWZ5u75iUFCZTzEwVncVIlXZeRYVLfgLpMWt2RfKQEFuapdJSWuwwjb8LamSib4jum3w
+        DfrVdM2j0bJAnnZvDO6Iy3yaeP26GhKv///ba5Q48eqAjXtiPE4j2PwoA+qlwxf9TbPz479o2DJDzfm7kSBtTxJVt+yoyuVS0iPH
+        wUvyMDZn1szJSSHzD6EJt8zAaLmgCQnlDmB0xPcZdikT8DnLOkwnEltFQkIXnxUpaJgcASICN1J0EM9R8lVZjK+rTElRT3tsykgs
+        7QSpDt7Mf0S5PPEgNHUwmMMHn6Gs2k1zpXQRD60DtcgMWfoqprALJcjZonISd/e6G+pVlY+ByiKB+XTN4QPK64Tqk0ObanoRNqWo
+        z3lZ62JcZpR/NYLaYvTE+mwNemnifXmNoHT9wPkC6zyzE4B7IKmt5Oq5DjqcqxdeUrMFvSTc3q2TgkaX6sOQF6estWisjYbGFCbA
+        38FpEURoFpQuc8wdY8uYDhbjCCDNOxMOnijsFNrXpYhUs3ZNTAx13AMCPhd72hbDRGCZpO80Z4fO937bk4WUMdvK8JZrn+PgG/Kr
+        +mprjHf7AvP88YXxdFGwkEhDTYHg8wmVU4/AfE9AWVKChz5//ynZsaMopC23dnt7BCckf9BzoZDmZxCsyyKn5XCjddEl+W4I/UO2
+        rdWQjjIUOQM0vhfoi2+KrC0CUHiAKZ3ag9x+y5cNeHN09L2S9XAALIkrOchQrgsB2AvE/AO1nQa0DOwLPAaQWYEgJV5yTe08S371
+        798MB1SrF2jU88SIleLNF7cob3v01E+ibmbQGTCd3FsV7CZbspvs9XOqaAUf2jJ1ksoU7qji2v+b1OON7e2ODMFaXuoAcqZoF/bg
+        iZggZJnvHretRW6ZGfjIHOAECVXpwXHuW/MgEFh1necwZOM0bti9FSvb7kru2YB2KOdVMc8DEAjSUO2vdmU4ShS8g5hU+YKnpbWH
+        yI5Gt7hyQ8bo1xrHMBT00EY+Cyn8hUbj8t8QkrEvGDGJvgAAABECAdApS4gUQLNaRKOrvmUrlwAAAAoCAeBknWCBZJJ4AAAACwAB
+        4CT1XokDGJDwAAAACwAB4ETXXokDCJDwAAAACgAB4Ia34IGMkPAAAAAoAgHQUJLV4gUQs1pBXstflTAR3T1JbAVIbopYqDUPYTj4
+        IWE81h/fcAAAAAsCAeECJ1dYIFmSeAAAAAwAAeDG9VXokDGAkPAAAAAMAAHg5tV16JAwgJDwAAAACwAB4SIt14IGMJDwAAAAKAIB
+        0Hiy1dYgUbNX3UUiza+6i4MPZOqs+PtC41JPtDUUci+9EDsBEIAAAAAMAgHhoidS1ggWQJJ4AAAADAAB4Wb1VeiQMYCQ8AAAAAwA
+        AeGG1XXokDCAkPAAAAALAAHhwi3XggYwkPAAAAA2AgHQoLLV1iBRs1pF8J9CPc4R37vjlJUMsDOIYRTv0YJs83cr9E8qQK09NOxk
+        CdS4zy+1btkwAAAADAIB4kInUtYIFsCSeAAAAAwAAeIG9VXokDCAkPAAAAAMAAHiJtV16JAxgJDwAAAACwAB4mIt14IGMJDwAAAA
+        KgIB0Miy1dYgU7NaRdlMD+s+HomYswol7sg/lZAGfD5iKIaClD9WuaxS2AAAAAwCAeLiJ1LWCBZAkngAAAAMAAHipvVV6JAwgJDw
+        AAAADAAB4sbVdeiQMYCQ8AAAAAsAAeMCLdeCBjCQ8AAAAv8qAax4WUjJCWCjD2eNFYBL9VgaG1nDmWYZT44HnoNrRoPGSdWf2Hq+
+        kAVp0AETi8bXaTSzsF+JUlDhD3/F6v4RJdJ0nr//gzctK9Kf0HYjnaTZQMpnbQiyS3n232faVg21N8KsG1ZNqscyqiiIt+wc12DD
+        VvXwz86qXsby+oe0oXOGHLAA6ze7alSy/+qrwwd7NVYDo6yNBZR23bKpM5r65RAYpV46uGId2xk+8hFx+DOKF9516y9z2Sc00Ri2
+        4Iq8OdCVWNvHWKPB635A0pBuAawUdfGgyCjIPQh1+ZsBXLhT41eJcSlVUWuNOqZIyerG7zNStDP2dylZqCW9Ul3XmIVPSEc2f//1
+        fOq+gXwDQffb0/SFIXZLPKzHdWYD8RUI1pDR0l5ExhcvZ/zMdpZ4t8Rb3QIVCbN0yjPy1vJ4jjIoHM1NcKMLIDnBVOh+zt3QM3le
+        O+4ZFjjf8r6ocDE3KoN2gNvpPm5L7CIhQ2ifdpvoTgBmjVh6cTm/Wf491E5/q/5y8gPCFZxtlbEBQZkn2j7DPTns4UYiJ1uD4UzO
+        KIMq4i+rfpo8hTFNA8HtVN5lJ6Tv0c9CPeh5uAdwwKVrbaPtiazzMXZ8jOAfZ6hngSyJI4nhYaAOHW/sy5dm1McbDzOwuZ1T0nPh
+        GqyWqtEvQ69uxZZZNkWS55TB8snliUp4sKy1/uLfA8tGJUBuumU7yJbOxPgOpaR06JWocWRaho4OonanCAUCSTLLif+PF4HqU6cr
+        LSctC7oafi+qctoINabIeRpCshIeTFlTDX7bdZIBUWd74n7FdxIpmLztJCcvZyMLQNpn1zHi6WV4IBFALtCCOBSJ2P/TcS9/Z0C/
+        BRexcGZFe88yAbVa+15bZQ44+t92JW+PlM3cDHMdP+cGWxf7QdajToUsmR17uo1Y6BteMHVLrjVz37Mu4OZtaIqp1LwfD/Gl0BAF
+        8ph1b9l6rYoUppu2nj1CrHd/+0kJgooDopxHesfYiVHVpsapV0t6aHArjyCdhMCBL/e4CAAAAAwSAeOCJ1LWCBbAkngAAAAMEAHj
+        RvVV6JAxgJDwAAAADBAB42bVdeiQMYCQ8AAAAAsQAeOiLdeCBhCQ8AAAABUCAdEZS4gUwKWUARtgIeLbo2Dsm4AAAAAKAgHkJJ1g
+        gWSSeAAAAAsAAePk9V6JAxiQ8AAAAAsAAeQE116JAxiQ8AAAAAoAAeRGt+CBhJDwAAAAKgIB0UCS1eIFMLNaRZJaHzbJq9zDac6C
+        VeR4Ose49AXhreJ5h3CAkxnAgAAAAAsCAeTCJ1dYIFmSeAAAAAwAAeSG9VXokDCAkPAAAAAMAAHkptV16JAxgJDwAAAACwAB5OIt
+        14IGEJDwAAAALAIB0Wiy1dYgU7NX0oxEpyVXkd0PlmoD4UCzwOy1Kn4HM30P7lZDezVWpePWAAAADAIB5WInUtYIFkCSeAAAAAwA
+        AeUm9VXokDCAkPAAAAAMAAHlRtV16JAxgJDwAAAACwAB5YIt14IGEJDwAAAAMQIB0ZCy1dYgU7NaQVA7FgvGoiPkdZiJRmkpLH4H
+        CwR/7s/PnTGo0asEbqN5ii4n+OAAAAAMAgHmAidS1ggWwJJ4AAAADAAB5cb1VeiQMICQ8AAAAAwAAeXm1XXokDCAkPAAAAALAAHm
+        Ii3XggYwkPAAAAAoAgHRuLLV1iBTs1pIU6hYy2wO0STGAgb99r9LabtcybfbnmQ6/OsmvgAAAAwCAeaiJ1LWCBbAkngAAAAMAAHm
+        ZvVV6JAwgJDwAAAADAAB5obVdeiQMICQ8AAAAAsAAebCLdeCBhCQ8AAAACsCAdHYslXWIFOtmAzX0NRed3pQXw+62wWHkLbUGOmJ
+        Jygg3cAOzHxoBHGAAAAADAIB5yIlUtYIFsCSeAAAAAsAAecG9deiQMaQ8AAAAAsAAedCLVeCBjCQ8A==
+        """
+}

From 3cc256a0c1b9d9ec5302fac3f48b3c04cb9ab3e5 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 7 Oct 2026 05:18:48 +0200
Subject: [PATCH 329/359] chore(release): prep 7.28.3 - #409 repair survives a
 resume or seek onto an open-GOP keyframe

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                    | 6 ++++++
 Examples/README.md                              | 2 +-
 README.md                                       | 6 +++---
 Sources/AetherEngine/AetherEngine+Version.swift | 2 +-
 4 files changed, 11 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 565962af2..2b353f2b2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,12 @@ the public-API contract.
 
 _Nothing yet._
 
+## [7.28.3] - 2026-10-07
+
+### Fixed
+
+- **A resume or seek onto an open-GOP keyframe keeps the #409 repair (#699).** Two defects on H.264/HEVC MP4s without composition offsets. The repair verdict was reached at the first read, and the software host seeks to its resume position before reading, so the sample started on a CRA (picture order not 0) and was declined: the whole session played in decode order. A seek before the first read now settles the verdict at the head first. Separately, every post-seek re-anchor treated the landing keyframe as the first picture displayed; a CRA with leading pictures is displayed that many slots later, so the axis sat early and B pictures that fell below their decode time went out untouched. The session now holds from the landing to the first trailing picture and anchors with the leading-picture count. Covered by an x265 open-GOP twin (CRA plus four RASL pictures) for a resume-shaped seek and a seek during playback. Reported by cmcpherson274. No API change.
+
 ## [7.28.2] - 2026-10-06
 
 ### Changed
diff --git a/Examples/README.md b/Examples/README.md
index bf1d67b09..78c7c9545 100644
--- a/Examples/README.md
+++ b/Examples/README.md
@@ -18,7 +18,7 @@ Three samples covering different audiences:
    ```
    https://github.com/superuser404notfound/AetherEngine
    ```
-   Dependency Rule: Up to Next Major Version, starting from `7.28.2`. Add the `AetherEngine` library product to your app target.
+   Dependency Rule: Up to Next Major Version, starting from `7.28.3`. Add the `AetherEngine` library product to your app target.
 
 3. **Drop the file in.** Replace the Xcode template's default `App.swift` (or whatever the generated `@main` file is called) with the contents of [`MinimalPlayerApp.swift`](MinimalPlayer/MinimalPlayerApp.swift). The file is self-contained: it defines both the `@main App` struct and the `ContentView`.
 
diff --git a/README.md b/README.md
index 27f78cc85..7fd3b8b0a 100644
--- a/README.md
+++ b/README.md
@@ -385,7 +385,7 @@ Subtitle cues land in raw source PTS; render the overlay against `player.sourceT
 Install via Swift Package Manager:
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.28.2")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.28.3")
 ```
 
 Three samples ship in `Examples/`:
@@ -632,10 +632,10 @@ Browse all of this as a searchable site at **[aetherengine.superuser404.de](http
 AetherEngine uses [Semantic Versioning](https://semver.org). The public API surface, every `public` declaration in `Sources/AetherEngine/`, is the stability contract. **Major** removes / renames public symbols or breaks adopters; **Minor** adds public API or codec / format support; **Patch** fixes bugs with no public API change. `internal` types are not part of the contract.
 
 ```swift
-.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.28.2")
+.package(url: "https://github.com/superuser404notfound/AetherEngine", from: "7.28.3")
 ```
 
-Pin to `.upToNextMinor(from: "7.28.2")` for stricter teams that prefer to opt into minor bumps explicitly.
+Pin to `.upToNextMinor(from: "7.28.3")` for stricter teams that prefer to opt into minor bumps explicitly.
 
 ## Requirements
 
diff --git a/Sources/AetherEngine/AetherEngine+Version.swift b/Sources/AetherEngine/AetherEngine+Version.swift
index cc4756768..fdf3e4f9f 100644
--- a/Sources/AetherEngine/AetherEngine+Version.swift
+++ b/Sources/AetherEngine/AetherEngine+Version.swift
@@ -11,5 +11,5 @@ extension AetherEngine {
     ///
     /// Between releases, and in a consumer that pins an unreleased commit for a device test, this
     /// names the last PUBLISHED version the checkout descends from, not every patch in it.
-    public nonisolated static let version = "7.28.2"
+    public nonisolated static let version = "7.28.3"
 }

From 3eb20011372a849aa1f4cfa07c07ab627745f95f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Okan=20Yu=CC=88cel?= <okan.yucel95@gmail.com>
Date: Wed, 7 Oct 2026 12:44:43 +0300
Subject: [PATCH 330/359] perf(routing): defer AV1 capability probing until
 needed

---
 CHANGELOG.md                                      |  4 +++-
 .../AetherEngine/Decoder/VideoRoutingPolicy.swift |  5 +++--
 .../VideoRoutingPolicyTests.swift                 | 15 +++++++++++++++
 docs/architecture.md                              |  2 +-
 4 files changed, 22 insertions(+), 4 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2b353f2b2..28a3b4176 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,7 +10,9 @@ the public-API contract.
 
 ## [Unreleased]
 
-_Nothing yet._
+### Fixed
+
+- Video routing consults the AV1 hardware decoder only for AV1 sources, avoiding supplemental decoder registration on unrelated playback starts.
 
 ## [7.28.3] - 2026-10-07
 
diff --git a/Sources/AetherEngine/Decoder/VideoRoutingPolicy.swift b/Sources/AetherEngine/Decoder/VideoRoutingPolicy.swift
index b2453b87e..e8b9b9b0a 100644
--- a/Sources/AetherEngine/Decoder/VideoRoutingPolicy.swift
+++ b/Sources/AetherEngine/Decoder/VideoRoutingPolicy.swift
@@ -14,6 +14,7 @@ enum VideoRoutingPolicy {
 
     /// True when a video codec must use the software decode path (SoftwarePlaybackHost) instead of
     /// native AVPlayer. `av1Available` is `VTCapabilityProbe.av1Available` (HW AV1 decode support).
+    /// Evaluated only for AV1; registering its decoder must not delay unrelated formats.
     /// #150: `spsIndicatesInterlaced` (SPS frame_mbs_only_flag == 0) breaks the tie when the demuxer's
     /// field_order probe stays UNKNOWN; a concrete PROGRESSIVE probe analyzed actual frames and wins.
     /// A false positive costs an unnecessary SW decode (deint=interlaced passes progressive frames
@@ -30,7 +31,7 @@ enum VideoRoutingPolicy {
     static func requiresSoftwarePath(
         codecID: AVCodecID,
         fieldOrder: AVFieldOrder,
-        av1Available: Bool,
+        av1Available: @autoclosure () -> Bool,
         spsIndicatesInterlaced: Bool = false,
         stereo3DType: AVStereo3DType? = nil
     ) -> Bool {
@@ -38,7 +39,7 @@ enum VideoRoutingPolicy {
         case AV_CODEC_ID_NONE, AV_CODEC_ID_HEVC:
             return false
         case AV_CODEC_ID_AV1:
-            return !av1Available
+            return !av1Available()
         case AV_CODEC_ID_H264:
             if routesSoftwareForMultiviewCarriage(codecID: codecID, stereo3DType: stereo3DType) {
                 return true
diff --git a/Tests/AetherEngineTests/VideoRoutingPolicyTests.swift b/Tests/AetherEngineTests/VideoRoutingPolicyTests.swift
index 0f32d1b4b..770f28135 100644
--- a/Tests/AetherEngineTests/VideoRoutingPolicyTests.swift
+++ b/Tests/AetherEngineTests/VideoRoutingPolicyTests.swift
@@ -67,6 +67,21 @@ struct VideoRoutingPolicyTests {
             codecID: AV_CODEC_ID_AV1, fieldOrder: AV_FIELD_PROGRESSIVE, av1Available: true))
     }
 
+    @Test("Only AV1 routing evaluates the hardware capability probe")
+    func hardwareProbeIsLazy() {
+        var calls = 0
+        func probe() -> Bool { calls += 1; return true }
+        for codec in [AV_CODEC_ID_H264, AV_CODEC_ID_HEVC, AV_CODEC_ID_NONE,
+                      AV_CODEC_ID_VP9, AV_CODEC_ID_MPEG2VIDEO] {
+            _ = VideoRoutingPolicy.requiresSoftwarePath(
+                codecID: codec, fieldOrder: AV_FIELD_PROGRESSIVE, av1Available: probe())
+        }
+        #expect(calls == 0)
+        #expect(!VideoRoutingPolicy.requiresSoftwarePath(
+            codecID: AV_CODEC_ID_AV1, fieldOrder: AV_FIELD_PROGRESSIVE, av1Available: probe()))
+        #expect(calls == 1)
+    }
+
     // MARK: - #150 SPS frame_mbs_only fallback for UNKNOWN field order
 
     @Test("UNKNOWN field order + SPS frame_mbs_only=0 routes to software")
diff --git a/docs/architecture.md b/docs/architecture.md
index a57ba7cf6..e626e706c 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -90,7 +90,7 @@ A seek holds the last frame on screen rather than blanking it. `SampleBufferRend
 
 `AudioDecoder` stamps each `CMSampleBuffer` from a running sample count anchored to the first frame (`AudioClockAnchor`), not from the container-quantized per-packet PTS. Container timebases are coarse (1 ms in MKV), so when a frame's duration is not an integer number of ticks (a 1536-sample AC-3 frame is 34.83 ms at 44.1 kHz but exactly 32 ms at 48 kHz) the quantized PTS leave a sub-millisecond gap or overlap at every buffer boundary, and `AVSampleBufferAudioRenderer` reconciles a discontinuity at each one (~29 clicks/sec, a continuous crackle). Anchoring to the sample clock makes consecutive buffers abut exactly; a real source discontinuity (> 100 ms off the predicted clock, i.e. a seek or edit) re-anchors so genuine gaps are not papered over, and `flush()` drops the anchor. The clock advances only on a successfully emitted buffer, so a dropped buffer injects no phantom samples.
 
-AV1+DV (Profile 10.0 / 10.1 / 10.4) routes through the native path on hardware-AV1 hosts via the `dav1` / `av01` track type plus the source's `dvvC` box. AV1+Atmos is genuinely rare in the wild (mastering still runs in HEVC overwhelmingly), so the SW pipeline's lack of Atmos passthrough is a theoretical limitation rather than a real one. The dispatch happens once at load time; hosts see a unified `@Published` state surface either way.
+AV1+DV (Profile 10.0 / 10.1 / 10.4) routes through the native path on hardware-AV1 hosts via the `dav1` / `av01` track type plus the source's `dvvC` box. AV1+Atmos is genuinely rare in the wild (mastering still runs in HEVC overwhelmingly), so the SW pipeline's lack of Atmos passthrough is a theoretical limitation rather than a real one. AV1 capability registration is lazy and runs only when routing an AV1 source; loading H.264, HEVC or audio-only content does not consult it. The dispatch happens once at load time; hosts see a unified `@Published` state surface either way.
 
 **Background audio (iOS).** When the app backgrounds while playing, the engine keeps audio going rather than tearing the pipeline down. The decision is a pure, unit-tested policy, `backgroundAction(isAudioBackend:hasSoftwareHost:keepVideoAlive:state:)`, driven from the `UIApplication` lifecycle observers; `keepVideoAlive` comes from `shouldKeepVideoAlive(enabled:pipActive:state:)` and is gated to iOS (tvOS always tears down, wedge-safe: a frozen decode session crossing a multi-hour suspension wedged `mediaserverd`). On the native path "keep audio alive" is just declining to tear down: `AVPlayer` under the `.playback` session keeps decoding. The software path has no `AVPlayer`, and its combined demux loop normally paces the whole loop (audio and video) on the video renderer's `isReadyForMoreMediaData`; once `AVSampleBufferDisplayLayer` stops draining in the background that gate never reopens and audio would starve. So the host enters `backgroundAudioOnly`: the loop drops video packets and paces on the audio renderer (`AudioOutput.isReadyForMoreMediaData`) instead, keeping `AVSampleBufferAudioRenderer` fed and the synchronizer advancing. On foreground return the flag clears, the video decoder and renderer flush, and video resyncs at the next keyframe with audio uninterrupted. Scope is the combined VOD loop (and live-without-DVR, which shares it); the DVR feeder loop is unchanged. Exercise it headless with `aetherctl bgaudio` (see [cli.md](cli.md)).
 

From 43cbb17be4481b42f5fecf7f5b17f5a21c1bb3a6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Okan=20Yu=CC=88cel?= <okan.yucel95@gmail.com>
Date: Wed, 7 Oct 2026 12:47:12 +0300
Subject: [PATCH 331/359] feat(subtitles): apply timing offsets to software PiP
 captions

---
 CHANGELOG.md                                  |  4 +-
 .../AetherEngine/AetherEngine+Loading.swift   |  3 +-
 Sources/AetherEngine/AetherEngine.swift       | 18 +++++++-
 .../Native/SoftwarePlaybackHost.swift         |  4 +-
 .../Renderer/SubtitleFrameCompositor.swift    | 17 +++++---
 .../SubtitleFrameCompositorTests.swift        | 41 +++++++++++++++++++
 docs/api.md                                   | 12 ++++++
 7 files changed, 89 insertions(+), 10 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2b353f2b2..732944dbc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,7 +10,9 @@ the public-API contract.
 
 ## [Unreleased]
 
-_Nothing yet._
+### Added
+
+- `setSoftwareSubtitleDelay(_:)` applies a persistent, caller-selected subtitle offset to both channels in software PiP without changing the playback clock. Native renditions remain unchanged.
 
 ## [7.28.3] - 2026-10-07
 
diff --git a/Sources/AetherEngine/AetherEngine+Loading.swift b/Sources/AetherEngine/AetherEngine+Loading.swift
index 2f1d2eb2a..817db474a 100644
--- a/Sources/AetherEngine/AetherEngine+Loading.swift
+++ b/Sources/AetherEngine/AetherEngine+Loading.swift
@@ -1933,7 +1933,8 @@ extension AetherEngine {
         Publishers.CombineLatest($subtitleCues, $secondarySubtitleCues)
             .sink { [weak self, weak host] primary, secondary in
                 guard let self, let host else { return }
-                host.updateSubtitleCompositor(cues: primary + secondary, enabled: self.pictureInPictureActive)
+                host.updateSubtitleCompositor(cues: primary + secondary, enabled: self.pictureInPictureActive,
+                                              delaySeconds: self.softwareSubtitleDelaySeconds)
             }
             .store(in: &softwareCancellables)
         // #131: no demuxable CC track on the SW path either: arm an A53 tap fed by decoded-frame
diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index e72181896..d66dde067 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -736,6 +736,22 @@ public final class AetherEngine: ObservableObject {
         }
     }
 
+    /// Timing adjustment for subtitles composited into software PiP frames, in media seconds.
+    /// Positive values delay subtitles; negative values advance them. Host overlays must apply
+    /// the same value against `clock.sourceTime`. Native AVPlayer renditions are not affected.
+    /// Persists across loads on this engine, like a host presentation preference.
+    public private(set) var softwareSubtitleDelaySeconds: Double = 0
+
+    /// Updates software subtitle composition without reopening media or shifting the A/V clock.
+    /// Non-finite values are ignored. Takes effect on the next composited video frame.
+    public func setSoftwareSubtitleDelay(_ seconds: Double) {
+        guard seconds.isFinite, seconds != softwareSubtitleDelaySeconds else { return }
+        softwareSubtitleDelaySeconds = seconds
+        softwareHost?.updateSubtitleCompositor(cues: subtitleCues + secondarySubtitleCues,
+            enabled: pictureInPictureActive, delaySeconds: seconds)
+        EngineLog.emit("[AetherEngine] software subtitle delay=\(seconds)s", category: .engine)
+    }
+
     /// Master enable for background playback (iOS: PiP + background audio; tvOS: PiP keepalive). Default on.
     public var backgroundPlaybackEnabled = true
     /// Set by the host from its PiP delegate (iOS: AVKit; tvOS: host-built AVPictureInPictureController);
@@ -744,7 +760,7 @@ public final class AetherEngine: ObservableObject {
         didSet {
             // SW-PiP Phase C: flip the frame compositor with the PiP state so subtitles appear in the
             // window and never double-draw under the fullscreen host overlay.
-            softwareHost?.updateSubtitleCompositor(cues: subtitleCues + secondarySubtitleCues, enabled: pictureInPictureActive)
+            softwareHost?.updateSubtitleCompositor(cues: subtitleCues + secondarySubtitleCues, enabled: pictureInPictureActive, delaySeconds: softwareSubtitleDelaySeconds)
             #if os(tvOS)
             // PiP window closed while backgrounded: nothing keeps the app running anymore, so the
             // wedge-safe teardown is due before idle suspension (mirrors the iOS pause-while-backgrounded path).
diff --git a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
index 7e0e6f3a5..568e17dc8 100644
--- a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
+++ b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
@@ -112,8 +112,8 @@ final class SoftwarePlaybackHost {
     var displayLayer: AVSampleBufferDisplayLayer { renderer.displayLayer }
 
     /// SW-PiP Phase C: engine-fed cue mirror + PiP gate for the renderer's frame compositor.
-    func updateSubtitleCompositor(cues: [SubtitleCue], enabled: Bool) {
-        renderer.subtitleCompositor.update(cues: cues, enabled: enabled)
+    func updateSubtitleCompositor(cues: [SubtitleCue], enabled: Bool, delaySeconds: Double = 0) {
+        renderer.subtitleCompositor.update(cues: cues, enabled: enabled, delaySeconds: delaySeconds)
     }
 
     // MARK: - Internals
diff --git a/Sources/AetherEngine/Renderer/SubtitleFrameCompositor.swift b/Sources/AetherEngine/Renderer/SubtitleFrameCompositor.swift
index 9cfe59087..a49dd5dc5 100644
--- a/Sources/AetherEngine/Renderer/SubtitleFrameCompositor.swift
+++ b/Sources/AetherEngine/Renderer/SubtitleFrameCompositor.swift
@@ -16,9 +16,13 @@ final class SubtitleFrameCompositor: @unchecked Sendable {
         let maxTextWidth: CGFloat
     }
 
-    /// Plain window check; cue times and SW frame PTS share the source axis.
-    nonisolated static func activeCues(in cues: [SubtitleCue], at seconds: Double) -> [SubtitleCue] {
-        cues.filter { $0.startTime <= seconds && seconds < $0.endTime }
+    /// Cue times and frame PTS share the source axis. Shift subtitle presentation only;
+    /// playback rate already advances the frame clock in media seconds.
+    nonisolated static func activeCues(in cues: [SubtitleCue], at seconds: Double,
+                                       delaySeconds: Double = 0) -> [SubtitleCue] {
+        let subtitleTime = seconds - delaySeconds
+        guard seconds.isFinite, delaySeconds.isFinite, subtitleTime.isFinite else { return [] }
+        return cues.filter { $0.startTime <= subtitleTime && subtitleTime < $0.endTime }
     }
 
     /// Default look: readable in a small window, resolution-independent.
@@ -61,6 +65,7 @@ final class SubtitleFrameCompositor: @unchecked Sendable {
     private let lock = NSLock()
     private var cues: [SubtitleCue] = []
     private var enabled = false
+    private var delaySeconds: Double = 0
     /// Cache key of the overlay currently rendered (active cue ids); nil = no overlay cached.
     private var cachedCueIDs: [Int]?
     private var cachedOverlay: CIImage?
@@ -71,10 +76,11 @@ final class SubtitleFrameCompositor: @unchecked Sendable {
     private var poolFormat: (width: Int, height: Int, pixelFormat: OSType)?
 
     /// Any thread; called by the engine when its published cues or the PiP flag change.
-    func update(cues: [SubtitleCue], enabled: Bool) {
+    func update(cues: [SubtitleCue], enabled: Bool, delaySeconds: Double = 0) {
         lock.lock()
         self.cues = cues
         self.enabled = enabled
+        if delaySeconds.isFinite { self.delaySeconds = delaySeconds }
         lock.unlock()
     }
 
@@ -83,10 +89,11 @@ final class SubtitleFrameCompositor: @unchecked Sendable {
         lock.lock()
         let enabled = self.enabled
         let cues = self.cues
+        let delay = self.delaySeconds
         lock.unlock()
         guard enabled else { return buffer }
 
-        let active = Self.activeCues(in: cues, at: ptsSeconds)
+        let active = Self.activeCues(in: cues, at: ptsSeconds, delaySeconds: delay)
         guard !active.isEmpty else {
             lock.lock(); cachedCueIDs = nil; cachedOverlay = nil; lock.unlock()
             return buffer
diff --git a/Tests/AetherEngineTests/SubtitleFrameCompositorTests.swift b/Tests/AetherEngineTests/SubtitleFrameCompositorTests.swift
index 17ce5e7f8..c59139a91 100644
--- a/Tests/AetherEngineTests/SubtitleFrameCompositorTests.swift
+++ b/Tests/AetherEngineTests/SubtitleFrameCompositorTests.swift
@@ -18,6 +18,32 @@ struct SubtitleFrameCompositorTests {
         #expect(SubtitleFrameCompositor.activeCues(in: cues, at: 12.0).isEmpty)
     }
 
+    @Test("software PiP delay and advance use media time for both subtitle channels")
+    func adjustedCueWindow() {
+        let cues = [cue(1, 10, 12), cue(2, 10, 11), cue(3, 12, 14)]
+        #expect(SubtitleFrameCompositor.activeCues(in: cues, at: 10.5, delaySeconds: 1.5).isEmpty)
+        #expect(SubtitleFrameCompositor.activeCues(in: cues, at: 11.5, delaySeconds: 1.5).map(\.id) == [1, 2])
+        #expect(SubtitleFrameCompositor.activeCues(in: cues, at: 13.5, delaySeconds: 1.5).map(\.id) == [3])
+        #expect(SubtitleFrameCompositor.activeCues(in: cues, at: 8.5, delaySeconds: -1.5).map(\.id) == [1, 2])
+        #expect(SubtitleFrameCompositor.activeCues(in: cues, at: .nan).isEmpty)
+        #expect(SubtitleFrameCompositor.activeCues(in: cues, at: 11, delaySeconds: .infinity).isEmpty)
+    }
+
+    @MainActor
+    @Test("software subtitle preference survives PiP transitions and rejects invalid values")
+    func delayPreference() throws {
+        let engine = try AetherEngine()
+        engine.setSoftwareSubtitleDelay(1.5)
+        engine.pictureInPictureActive = true
+        engine.pictureInPictureActive = false
+        engine.setSoftwareSubtitleDelay(.nan)
+        #expect(engine.softwareSubtitleDelaySeconds == 1.5)
+        engine.setSoftwareSubtitleDelay(-0.5)
+        #expect(engine.softwareSubtitleDelaySeconds == -0.5)
+        engine.stop()
+        #expect(engine.softwareSubtitleDelaySeconds == -0.5)
+    }
+
     @Test("text layout scales with frame height and keeps a safe bottom margin")
     func textLayoutScales() {
         let layout = SubtitleFrameCompositor.textLayout(frameWidth: 1920, frameHeight: 1080)
@@ -95,6 +121,21 @@ struct SubtitleFrameCompositorTests {
         #expect(compositor.composite(buffer, ptsSeconds: 20) === buffer)
     }
 
+    @Test("rendered PiP frames apply timing changes without a cue or transport update")
+    func compositeAppliesDelay() throws {
+        let compositor = SubtitleFrameCompositor()
+        let buffer = try blackFrame(kCVPixelFormatType_420YpCbCr8BiPlanarVideoRange)
+        let cues = [cue(1, 10, 12)]
+        compositor.update(cues: cues, enabled: true, delaySeconds: 1.5)
+        #expect(compositor.composite(buffer, ptsSeconds: 10.5) === buffer)
+        #expect(compositor.composite(buffer, ptsSeconds: 11.5) !== buffer)
+        #expect(compositor.composite(buffer, ptsSeconds: 13.5) === buffer)
+        compositor.update(cues: cues, enabled: true, delaySeconds: -1.5)
+        #expect(compositor.composite(buffer, ptsSeconds: 8.5) !== buffer)
+        compositor.update(cues: cues, enabled: false, delaySeconds: -1.5)
+        #expect(compositor.composite(buffer, ptsSeconds: 8.5) === buffer)
+    }
+
     private func blackFrame(_ format: OSType) throws -> CVPixelBuffer {
         var pb: CVPixelBuffer?
         let attrs: [CFString: Any] = [kCVPixelBufferIOSurfacePropertiesKey: [:] as CFDictionary]
diff --git a/docs/api.md b/docs/api.md
index 05c4c691e..7968ebfa6 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -1144,3 +1144,15 @@ Public for the CLI, the test suite, or a diagnostic overlay, and outside the sha
 - **`DiscInspector` / `DiscInspection`**, `DoviRpuConverter` and its probe, `AudioTapProbe`, `SoftwareDecodeProbeResult`, `A53SEIParser`: repro and inspection surfaces behind `aetherctl` subcommands.
 - **`HLSLiveIngestReader`'s internals** (`terminalError`, `upstreamTargetDuration`, `observedLiveCadenceSeconds`, `closedLiveCadenceSeconds`, `upstreamSegmentDurationSeconds`, `companionAudioReader`): fixture and diagnostic reads. The last two are the closed evidence the served TARGETDURATION is sealed from (AE#447); `upstreamTargetDuration` is the upstream's own claim, reported in the seal line and derived from nowhere.
 - **`SubtitleChannel`**: the primary / secondary selector on the engine's internal subtitle routing. No public signature takes one; a host picks the channel by calling the primary or the secondary method.
+
+### Software PiP subtitle timing
+
+`setSoftwareSubtitleDelay(_:)` applies an engine-wide media-time offset to both subtitle
+channels composited into software PiP frames. Positive values delay cues; negative values
+advance them. `softwareSubtitleDelaySeconds` reports the current preference. Non-finite
+values are ignored; the default is zero and the value survives subsequent loads on the same
+engine. It takes effect on the next composited frame without a seek, source reopen or A/V
+clock change. An inline overlay can use the same value with `clock.sourceTime - delay`.
+
+This setting does not shift AVPlayer-owned native subtitle renditions, native PiP or AirPlay.
+Hosts should expose that renderer limit when offering subtitle timing controls.

From 193959421020fc9e139077456ab0788f16b9a394 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Okan=20Yu=CC=88cel?= <okan.yucel95@gmail.com>
Date: Wed, 7 Oct 2026 12:48:53 +0300
Subject: [PATCH 332/359] feat(lifecycle): expose pending foreground video
 restoration

---
 CHANGELOG.md                                   |  4 +++-
 Sources/AetherEngine/AetherEngine.swift        |  4 ++++
 ...ue357BackgroundTeardownSelectionTests.swift | 18 ++++++++++++++++++
 docs/api.md                                    |  1 +
 4 files changed, 26 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2b353f2b2..8040c34d9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,7 +10,9 @@ the public-API contract.
 
 ## [Unreleased]
 
-_Nothing yet._
+### Added
+
+- `needsForegroundVideoRestore` exposes actual background video teardown so a host can rebuild through the existing reload API before resuming.
 
 ## [7.28.3] - 2026-10-07
 
diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index e72181896..d00ccb17f 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -3470,6 +3470,10 @@ public final class AetherEngine: ObservableObject {
     /// itself. Claimed by `consumeReloadSelection`, dropped by any other `load()` and by `stop()`.
     var backgroundTeardownSelection: BackgroundTeardownSelection?
 
+    /// The background policy released the video item while retaining the source, playhead,
+    /// selection and native host. A foreground host must rebuild before sending play().
+    public var needsForegroundVideoRestore: Bool { backgroundTeardownSelection != nil }
+
     /// Detached reader that decodes ALL embedded text subtitle streams in one side-demuxer pass into their
     /// ordinal's NativeSubtitleCueStore (#55, all-tracks). Parallel to the packet-store drainer (which drives
     /// subtitleCues for the active track with full styling). Cancelled on stop/clear/load.
diff --git a/Tests/AetherEngineTests/Issue357BackgroundTeardownSelectionTests.swift b/Tests/AetherEngineTests/Issue357BackgroundTeardownSelectionTests.swift
index 9c7523542..535a754c5 100644
--- a/Tests/AetherEngineTests/Issue357BackgroundTeardownSelectionTests.swift
+++ b/Tests/AetherEngineTests/Issue357BackgroundTeardownSelectionTests.swift
@@ -27,6 +27,16 @@ struct Issue357BackgroundTeardownSelectionTests {
         engine.stopInternal(resetDisplayCriteria: false, keepNativeHost: true, keepCustomReader: true)
     }
 
+    @Test("foreground restore is owed only after video teardown")
+    func restoreRequiresTeardown() throws {
+        let engine = try AetherEngine()
+        #expect(!engine.needsForegroundVideoRestore)
+        backgroundTeardown(engine)
+        #expect(engine.needsForegroundVideoRestore)
+        _ = engine.consumeReloadSelection()
+        #expect(!engine.needsForegroundVideoRestore)
+    }
+
     @Test("the selection stopInternal wipes is still there for the reload that follows minutes later")
     func teardownHandsSelectionToReload() throws {
         let engine = try AetherEngine()
@@ -168,12 +178,20 @@ struct Issue357BackgroundTeardownSelectionTests {
         let engine = try AetherEngine()
         engine.nativeHost = NativeAVPlayerHost()
         engine.playbackBackend = .native
+        let surface = AetherPlayerView(frame: .zero)
+        engine.bind(view: surface)
+        let layer = engine.nativePlayerLayer
+        #expect(layer?.superlayer != nil)
 
         backgroundTeardown(engine)
 
         // The teardown preserves the host on purpose: AVKit registers its Now-Playing client once
         // per AVPlayer instance (issue #15), so the instance has to outlive the suspension.
         #expect(engine.nativeHost != nil)
+        #expect(engine.nativePlayerLayer === layer)
+        #expect(layer?.superlayer != nil)
+        #expect(!engine.isSessionReady)
+        #expect(!engine.hasFirstFrameReadyForDisplay)
         // And it resets the backend, which is the state the foreground reload's load() reads.
         #expect(engine.playbackBackend == .none)
         // Reading the backend alone answered "nothing native here" and threw the kept host away.
diff --git a/docs/api.md b/docs/api.md
index 05c4c691e..b39a8fec8 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -983,6 +983,7 @@ say so on the tracker rather than working around it.
 | `$softwareDisplaySize` | The rectangle the software path's picture presents at: coded size under the decoder's pixel aspect. Mirrored, not latched, so a mid-stream resolution change re-shapes it. nil on every other path. |
 | `sourceVideoWidth`, `sourceVideoHeight`, `sourceVideoPixelAspectRatio` | The source's CODED size and the multiplier that turns it into the presented one (`width * ratio`), read once from the probe (on `.remoteBypass`, from AVPlayer's item video track once it resolves: the delivered size). The ratio is 1 on square pixels and on a declared ratio the engine refuses (#290), never a guess; on the paths that draw, prefer what is on screen (`softwareDisplaySize`, `AVPlayerLayer.videoRect`) over recomputing it here. |
 | `pictureInPictureActive` | Host-set. Keeps the pipeline and the loopback server alive across a background transition, and keeps the software path decoding video for the window. |
+| `needsForegroundVideoRestore` | True after background policy actually releases the video item. Restore with `reloadAtCurrentPosition(applying:)` before play, choosing the desired transport intent. False when video was retained or after stop/load. |
 | `backgroundPlaybackEnabled`, `backgroundTeardownGraceSeconds` | Background audio policy; the grace window (15 s default) is what lets a paused session survive a quick app switch. |
 | `presentationAxisMap` | `PresentationAxisMap`: `sourceSeconds(forItemSeconds:)`, `itemSeconds(forSourceSeconds:)`, `shiftSeconds(atItemSeconds:)`, `seams` (each a `PresentationAxisMap.Seam` of `itemSeconds` and `shiftSeconds`), `isEmpty`. Readable off the main actor. Cue times and `sourceTime` live on the source axis; `AVPlayerItem.currentTime()` lives on the item axis, and they differ by the producer shift. Returns nil rather than a guess where no axis is established. |
 | `setNativeVideoFrameTimeObserver(_:)` | Takes a `NativeVideoFrameTimeObserver`, called per muxed frame on both axes (`NativeVideoFrameTime`: `source`, `item`, `segmentIndex`, `isKeyframe`, `epoch`). Called on the producer pump thread in **decode** order, so `source` is not monotonic under B-frames. `epoch` rises process-wide. |

From 37314935f42e9477a0559860b0be150fe0e96909 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Okan=20Yu=CC=88cel?= <okan.yucel95@gmail.com>
Date: Wed, 7 Oct 2026 12:51:17 +0300
Subject: [PATCH 333/359] fix(audio): serialize track rebuilds and preserve
 transport intent

---
 CHANGELOG.md                                  |  4 +-
 .../AetherEngine/AetherEngine+Loading.swift   | 29 ++++++---
 Sources/AetherEngine/AetherEngine.swift       | 56 ++++++++++++----
 .../AudioSelectionOwnershipTests.swift        | 65 +++++++++++++++++++
 docs/api.md                                   | 11 ++++
 5 files changed, 143 insertions(+), 22 deletions(-)
 create mode 100644 Tests/AetherEngineTests/AudioSelectionOwnershipTests.swift

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2b353f2b2..4ee6a28df 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,7 +10,9 @@ the public-API contract.
 
 ## [Unreleased]
 
-_Nothing yet._
+### Fixed
+
+- Rapid audio-track selections coalesce into serialized rebuilds. Stop/load invalidate queued work, and play/pause commands received during a rebuild supply its final transport intent. Native handover retains the old item until replacement unless media services were reset.
 
 ## [7.28.3] - 2026-10-07
 
diff --git a/Sources/AetherEngine/AetherEngine+Loading.swift b/Sources/AetherEngine/AetherEngine+Loading.swift
index 2f1d2eb2a..89148b529 100644
--- a/Sources/AetherEngine/AetherEngine+Loading.swift
+++ b/Sources/AetherEngine/AetherEngine+Loading.swift
@@ -2345,9 +2345,15 @@ extension AetherEngine {
         // or the first rebuild after a reset mounts its item on the invalidated AVPlayer.
         let mediaServicesWereReset = consumeMediaServicesReset()
         claimSoftwarePathTakeover()   // AE#629
+        // Keep the current native item through an ordinary audio switch, but never reuse a host
+        // invalidated by a media-services reset (audit LIF-104).
+        let keepAudioSwitchItem = audioStreamIndex != nil && discTitleIDOverride == nil
+            && !targetSoftwarePath && !mediaServicesWereReset && nativeHost?.avPlayer.currentItem != nil
+        if keepAudioSwitchItem { nativeHost?.pause() }
         stopInternal(resetDisplayCriteria: false,
                      keepNativeHost: !targetSoftwarePath && !mediaServicesWereReset,
-                     keepCustomReader: true)
+                     keepCustomReader: true, keepCurrentItem: keepAudioSwitchItem)
+        pendingInPlaceItemHandover = keepAudioSwitchItem
         if mediaServicesWereReset { dropAudioPlayerHostAfterMediaServicesReset() }
         EngineLog.emit("[AetherEngine] reload: stopInternal done (\(elapsedMs(since: reloadStart))ms)", category: .engine)
         let gen = loadGeneration
@@ -2377,8 +2383,8 @@ extension AetherEngine {
                     return d
                 }.value
             } catch {
-                // Sodalite#173: a reopen a stop() or a cancelled load aborted is not a failed reload.
-                if loadGeneration != gen {
+                // A superseded or caller-cancelled reopen is not a reload failure.
+                if loadGeneration != gen || Task.isCancelled {
                     EngineLog.emit("[AetherEngine] reload superseded during custom reader reopen; unwinding", category: .engine)
                     return nil
                 }
@@ -2407,8 +2413,8 @@ extension AetherEngine {
                     return d
                 }.value
             } catch {
-                // Sodalite#173: a reopen a stop() or a cancelled load aborted is not a failed reload.
-                if loadGeneration != gen {
+                // A superseded or caller-cancelled reopen is not a reload failure.
+                if loadGeneration != gen || Task.isCancelled {
                     EngineLog.emit("[AetherEngine] reload superseded during disc URL reopen; unwinding", category: .engine)
                     return nil
                 }
@@ -2477,8 +2483,9 @@ extension AetherEngine {
                     audioTracks: audioTracks, activeIndex: softwareHost?.audioStreamIndex ?? -1
                 )
                 presentCurrentLayer()
-                // #124: not resuming leaves the host paused; its readiness settles `.loading -> .paused`.
-                if resumesPlaying { softwareHost?.play() }
+                // Keep the latest transport intent if play/pause changed while the rebuild awaited I/O.
+                if audioSelectionTransportIntent ?? resumesPlaying { softwareHost?.play() }
+                else { softwareHost?.pause() }
             } else {
                 EngineLog.emit("[AetherEngine] reload: loadNative enter audio=\(audioStreamIndex.map(String.init) ?? "nil") resumeAt=\(String(format: "%.2f", resumeAt))s", category: .engine)
                 // #339: the only write this reload can still produce is a sole-writer host's re-write on the
@@ -2568,10 +2575,11 @@ extension AetherEngine {
                     settleCap: loadedOptions.isLive ? .standard : .awaitObservedEnd,
                     isCurrent: { self.loadGeneration == gen })
                 try checkLoadCurrent(gen)
-                if resumesPlaying { nativeHost?.play() }
+                if audioSelectionTransportIntent ?? resumesPlaying { nativeHost?.play() }
+                else { nativeHost?.pause() }
             }
             try checkLoadCurrent(gen)
-            if resumesPlaying { state = .playing }
+            state = (audioSelectionTransportIntent ?? resumesPlaying) ? .playing : .paused
             // Re-arm samplers: stopInternal nilled them, and the reload path bypasses public load() that normally restarts them. Without this, liveTelemetry stays nil and the stats overlay shows "-" after every audio switch.
             startMemoryProbe()
             startLiveTelemetrySampler()
@@ -2583,11 +2591,12 @@ extension AetherEngine {
             if loadedOptions.isLive, !targetSoftwarePath {
                 armLiveReloadWatchdog(generation: gen)
             }
-            EngineLog.emit("[AetherEngine] reload: state=\(resumesPlaying ? ".playing" : "paused on readiness") total=\(elapsedMs(since: reloadStart))ms", category: .engine)
+            EngineLog.emit("[AetherEngine] reload: state=\(state == .playing ? ".playing" : ".paused") total=\(elapsedMs(since: reloadStart))ms", category: .engine)
         } catch is CancellationError {
             // Superseded by a newer load/stop: it owns the engine state.
             return nil
         } catch {
+            guard loadGeneration == gen, !Task.isCancelled else { return nil }
             EngineLog.emit(
                 "[AetherEngine] selectAudioTrack reload failed: \(error), playback stopped",
                 category: .engine
diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index e72181896..e13fedf57 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -3443,6 +3443,19 @@ public final class AetherEngine: ObservableObject {
     /// window as `positionUnderReconstruction` and for the same reason. Read only through
     /// `sessionRebuildResumesPlaying`. See `rebuildResumesPlaying`.
     var transportIntentUnderReconstruction: Bool?
+    private(set) var audioSelectionTask: Task<Void, Never>?
+    private var pendingAudioSelection: Int?
+    private var audioSelectionEpoch = UUID()
+    // Non-nil only during an audio rebuild. Transport received across awaits wins.
+    var audioSelectionTransportIntent: Bool?
+
+    private func cancelPendingAudioSelection() {
+        audioSelectionEpoch = UUID()
+        audioSelectionTask?.cancel()
+        audioSelectionTask = nil
+        pendingAudioSelection = nil
+        audioSelectionTransportIntent = nil
+    }
 
     /// AE#464 round 3: true while a re-anchor raised by `setAudioDelay` is running, so the presses
     /// that arrive during it are folded into it instead of stacking re-anchors of their own. The
@@ -3933,6 +3946,7 @@ public final class AetherEngine: ObservableObject {
         // RUNNING session is the right question here, unlike the host above: a background teardown
         // has already unloaded the item, so there is nothing left to hand over in place.
         let handOverInPlace = consumeInPlaceItemHandoverRequest(priorBackendWasNative: priorBackendWasNative)
+        cancelPendingAudioSelection()
         pendingInPlaceItemHandover = handOverInPlace
         // #128 follow-up: preserve the previous session's display criteria across the load seam. Nil-ing it
         // here bounces the panel through SDR before apply() re-negotiates the same mode on video->video
@@ -5220,6 +5234,7 @@ public final class AetherEngine: ObservableObject {
     }
 
     public func play() {
+        if audioSelectionTransportIntent != nil { audioSelectionTransportIntent = true }
         // AetherEngine#164: a VOD parked at its final frame (scrubbed to the end, or paused there)
         // cannot advance; AVPlayer.play() would no-op and leave the button frozen. Rewind to the start
         // first, then resume. `.ended` is excluded (see shouldRewindBeforePlay): it stays terminal so a
@@ -5241,6 +5256,7 @@ public final class AetherEngine: ObservableObject {
     }
 
     public func pause() {
+        if audioSelectionTransportIntent != nil { audioSelectionTransportIntent = false }
         resumeAfterInterruption = false
         activeTransportHost?.pause()
         isBuffering = false
@@ -6171,6 +6187,7 @@ public final class AetherEngine: ObservableObject {
     }
 
     public func stop(resetDisplayCriteria: Bool = true, finalTeardown: Bool? = nil) {
+        cancelPendingAudioSelection()
         nextLoadRequestsInPlaceItemHandover = false
         stopInternal(resetDisplayCriteria: resetDisplayCriteria,
                      finalTeardown: finalTeardown ?? resetDisplayCriteria)
@@ -6852,8 +6869,9 @@ public final class AetherEngine: ObservableObject {
 
     // MARK: - Audio / subtitle track selection
 
-    /// Switch the active audio track mid-playback. Restarts the HLS pipeline with the new audio stream;
-    /// expects ~0.5-1 s black frame (AVPlayer.replaceCurrentItem tears the surface). Display-criteria handshake
+    /// Switch the active audio track mid-playback. Rebuilds the pipeline at the current position;
+    /// native audio handover retains the old item until replacement, but decoder readiness can still
+    /// interrupt presentation. Software/forward-only sources cannot promise a seamless switch. Display-criteria handshake
     /// is suppressed (video unchanged). `index` is the container stream index (TrackInfo.id). No-op if
     /// out-of-range, pointing at a non-audio stream, or already active.
     ///
@@ -6889,21 +6907,37 @@ public final class AetherEngine: ObservableObject {
             )
             return
         }
-        if activeAudioTrackIndex == index { return }
+        if activeAudioTrackIndex == index && audioSelectionTask == nil { return }
 
         EngineLog.emit(
             "[AetherEngine] selectAudioTrack: scheduling switch to stream \(index)",
             category: .engine
         )
 
-        let gen = loadGeneration
-        Task { @MainActor [weak self] in
-            guard let self = self else { return }
-            await self.reloadWithAudioOverride(
-                url: url,
-                audioStreamIndex: Int32(index),
-                expectedGeneration: gen
-            )
+        pendingAudioSelection = index
+        guard audioSelectionTask == nil else { return }
+        let epoch = audioSelectionEpoch
+        audioSelectionTask = Task { @MainActor [weak self] in
+            guard let self, self.audioSelectionEpoch == epoch else { return }
+            defer {
+                if self.audioSelectionEpoch == epoch {
+                    self.audioSelectionTask = nil
+                    self.audioSelectionTransportIntent = nil
+                }
+            }
+            while let selected = self.pendingAudioSelection {
+                self.pendingAudioSelection = nil
+                guard !Task.isCancelled, self.audioSelectionEpoch == epoch else { return }
+                if self.activeAudioTrackIndex == selected { continue }
+                self.audioSelectionTransportIntent = self.sessionRebuildResumesPlaying
+                let beforeReload = self.loadGeneration
+                let failure = await self.reloadWithAudioOverride(
+                    url: url, audioStreamIndex: Int32(selected), expectedGeneration: beforeReload)
+                // This rebuild owns one stopInternal generation. Background teardown or
+                // another SDK recovery cannot lend its successor to queued audio work.
+                guard !Task.isCancelled, self.audioSelectionEpoch == epoch, failure == nil,
+                      self.loadGeneration == beforeReload &+ 1 else { return }
+            }
         }
     }
 
diff --git a/Tests/AetherEngineTests/AudioSelectionOwnershipTests.swift b/Tests/AetherEngineTests/AudioSelectionOwnershipTests.swift
new file mode 100644
index 000000000..3701fd9c2
--- /dev/null
+++ b/Tests/AetherEngineTests/AudioSelectionOwnershipTests.swift
@@ -0,0 +1,65 @@
+import XCTest
+@testable import AetherEngine
+
+@MainActor
+final class AudioSelectionOwnershipTests: XCTestCase {
+    private func fixture() throws -> AetherEngine {
+        let engine = try AetherEngine()
+        engine.loadedURL = URL(string: "https://example.invalid/controlled.ts")!
+        engine.audioTracks = [1, 2].map {
+            TrackInfo(id: $0, name: "Track \($0)", codec: "aac", language: nil, isDefault: $0 == 1)
+        }
+        engine.activeAudioTrackIndex = 1
+        return engine
+    }
+
+    func testSameAudioDoesNotScheduleRebuild() throws {
+        let engine = try fixture()
+        defer { engine.stop() }
+        engine.selectAudioTrack(index: 1)
+        XCTAssertNil(engine.audioSelectionTask)
+    }
+
+    func testRapidSelectionReturningToCurrentAudioCoalescesBeforeIO() async throws {
+        let engine = try fixture()
+        defer { engine.stop() }
+        let generation = engine.loadGeneration
+        engine.selectAudioTrack(index: 2)
+        engine.selectAudioTrack(index: 1)
+        await engine.audioSelectionTask?.value
+        XCTAssertEqual(engine.loadGeneration, generation)
+        XCTAssertEqual(engine.activeAudioTrackIndex, 1)
+        XCTAssertNil(engine.audioSelectionTask)
+    }
+
+    func testStopInvalidatesQueuedAudioWorkBeforeItCanReopenSource() async throws {
+        let engine = try fixture()
+        engine.selectAudioTrack(index: 2)
+        let task = try XCTUnwrap(engine.audioSelectionTask)
+        engine.stop()
+        let stoppedGeneration = engine.loadGeneration
+        await task.value
+        XCTAssertEqual(engine.loadGeneration, stoppedGeneration)
+        XCTAssertNil(engine.loadedURL)
+        XCTAssertEqual(engine.state, .idle)
+    }
+
+    func testTransportCommandsDuringAudioRebuildKeepLatestIntent() throws {
+        let engine = try fixture()
+        defer { engine.stop() }
+        engine.audioSelectionTransportIntent = true
+        engine.pause()
+        XCTAssertEqual(engine.audioSelectionTransportIntent, false)
+        engine.play()
+        XCTAssertEqual(engine.audioSelectionTransportIntent, true)
+        engine.stop()
+        XCTAssertNil(engine.audioSelectionTransportIntent)
+    }
+
+    func testLiveURLDoesNotRequireHostReload() throws {
+        let engine = try fixture()
+        defer { engine.stop() }
+        engine.isLive = true
+        XCTAssertNil(engine.sessionReloadRefusal)
+    }
+}
diff --git a/docs/api.md b/docs/api.md
index 05c4c691e..d43bd79cc 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -1144,3 +1144,14 @@ Public for the CLI, the test suite, or a diagnostic overlay, and outside the sha
 - **`DiscInspector` / `DiscInspection`**, `DoviRpuConverter` and its probe, `AudioTapProbe`, `SoftwareDecodeProbeResult`, `A53SEIParser`: repro and inspection surfaces behind `aetherctl` subcommands.
 - **`HLSLiveIngestReader`'s internals** (`terminalError`, `upstreamTargetDuration`, `observedLiveCadenceSeconds`, `closedLiveCadenceSeconds`, `upstreamSegmentDurationSeconds`, `companionAudioReader`): fixture and diagnostic reads. The last two are the closed evidence the served TARGETDURATION is sealed from (AE#447); `upstreamTargetDuration` is the upstream's own claim, reported in the seal line and derived from nowhere.
 - **`SubtitleChannel`**: the primary / secondary selector on the engine's internal subtitle routing. No public signature takes one; a host picks the channel by calling the primary or the secondary method.
+
+### Audio selection while rebuilding
+
+`selectAudioTrack(index:)` coalesces rapid choices and runs one rebuild at a time.
+A queued choice for the already-active track requires no source reopen. Stop or a
+new load invalidates pending audio selections; a superseded or cancelled rebuild
+cannot publish a stale error. Play/pause commands received while a rebuild awaits
+I/O determine the final transport state.
+
+An ordinary native audio handover retains the old item until replacement, but does
+not promise a gapless switch. A media-services reset still discards the old host.

From 7c85a3f7f32b2d28e04ea1cd31c5bc002cbeaa0b Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 7 Oct 2026 18:40:31 +0200
Subject: [PATCH 334/359] refactor(subtitles): require the PiP subtitle delay
 at every compositor update

The compositor stores whatever delay an update carries, so a default of 0 on
SoftwarePlaybackHost.updateSubtitleCompositor and SubtitleFrameCompositor.update
would let a future caller that omits it silently reset the host's offset. Both
now take it explicitly. The API reference lists setSoftwareSubtitleDelay(_:)
in the Subtitles table instead of under "Public but not host API".

Follow-up to #709.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 .../AetherEngine/Native/SoftwarePlaybackHost.swift  |  2 +-
 .../Renderer/SubtitleFrameCompositor.swift          |  2 +-
 .../SubtitleFrameCompositorTests.swift              |  8 ++++----
 docs/api.md                                         | 13 +------------
 4 files changed, 7 insertions(+), 18 deletions(-)

diff --git a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
index 568e17dc8..57a7810b2 100644
--- a/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
+++ b/Sources/AetherEngine/Native/SoftwarePlaybackHost.swift
@@ -112,7 +112,7 @@ final class SoftwarePlaybackHost {
     var displayLayer: AVSampleBufferDisplayLayer { renderer.displayLayer }
 
     /// SW-PiP Phase C: engine-fed cue mirror + PiP gate for the renderer's frame compositor.
-    func updateSubtitleCompositor(cues: [SubtitleCue], enabled: Bool, delaySeconds: Double = 0) {
+    func updateSubtitleCompositor(cues: [SubtitleCue], enabled: Bool, delaySeconds: Double) {
         renderer.subtitleCompositor.update(cues: cues, enabled: enabled, delaySeconds: delaySeconds)
     }
 
diff --git a/Sources/AetherEngine/Renderer/SubtitleFrameCompositor.swift b/Sources/AetherEngine/Renderer/SubtitleFrameCompositor.swift
index a49dd5dc5..bdeeb7ae1 100644
--- a/Sources/AetherEngine/Renderer/SubtitleFrameCompositor.swift
+++ b/Sources/AetherEngine/Renderer/SubtitleFrameCompositor.swift
@@ -76,7 +76,7 @@ final class SubtitleFrameCompositor: @unchecked Sendable {
     private var poolFormat: (width: Int, height: Int, pixelFormat: OSType)?
 
     /// Any thread; called by the engine when its published cues or the PiP flag change.
-    func update(cues: [SubtitleCue], enabled: Bool, delaySeconds: Double = 0) {
+    func update(cues: [SubtitleCue], enabled: Bool, delaySeconds: Double) {
         lock.lock()
         self.cues = cues
         self.enabled = enabled
diff --git a/Tests/AetherEngineTests/SubtitleFrameCompositorTests.swift b/Tests/AetherEngineTests/SubtitleFrameCompositorTests.swift
index c59139a91..ac6bf6a8e 100644
--- a/Tests/AetherEngineTests/SubtitleFrameCompositorTests.swift
+++ b/Tests/AetherEngineTests/SubtitleFrameCompositorTests.swift
@@ -96,11 +96,11 @@ struct SubtitleFrameCompositorTests {
         CVPixelBufferUnlockBaseAddress(buffer, [])
 
         // Disabled: passthrough must be the same instance.
-        compositor.update(cues: [SubtitleCue(id: 1, startTime: 0, endTime: 10, body: .text("HELLO"))], enabled: false)
+        compositor.update(cues: [SubtitleCue(id: 1, startTime: 0, endTime: 10, body: .text("HELLO"))], enabled: false, delaySeconds: 0)
         #expect(compositor.composite(buffer, ptsSeconds: 5) === buffer)
 
         // Enabled with an active cue: output keeps the format and the bottom region gains bright pixels.
-        compositor.update(cues: [SubtitleCue(id: 1, startTime: 0, endTime: 10, body: .text("HELLO"))], enabled: true)
+        compositor.update(cues: [SubtitleCue(id: 1, startTime: 0, endTime: 10, body: .text("HELLO"))], enabled: true, delaySeconds: 0)
         let out = compositor.composite(buffer, ptsSeconds: 5)
         #expect(CVPixelBufferGetPixelFormatType(out) == kCVPixelFormatType_420YpCbCr8BiPlanarVideoRange)
         #expect(out !== buffer)
@@ -153,7 +153,7 @@ struct SubtitleFrameCompositorTests {
     @Test("a composited frame keeps the source's pixel aspect ratio and colour tags")
     func compositedFrameKeepsSourceAttachments() throws {
         let compositor = SubtitleFrameCompositor()
-        compositor.update(cues: [SubtitleCue(id: 1, startTime: 0, endTime: 10, body: .text("HELLO"))], enabled: true)
+        compositor.update(cues: [SubtitleCue(id: 1, startTime: 0, endTime: 10, body: .text("HELLO"))], enabled: true, delaySeconds: 0)
 
         let hdr = try blackFrame(kCVPixelFormatType_420YpCbCr10BiPlanarVideoRange)
         let aspect: NSDictionary = [
@@ -184,7 +184,7 @@ struct SubtitleFrameCompositorTests {
     @Test("a recycled output buffer does not keep an earlier source's pixel aspect ratio")
     func recycledBufferDropsStaleAspect() throws {
         let compositor = SubtitleFrameCompositor()
-        compositor.update(cues: [SubtitleCue(id: 1, startTime: 0, endTime: 10, body: .text("HELLO"))], enabled: true)
+        compositor.update(cues: [SubtitleCue(id: 1, startTime: 0, endTime: 10, body: .text("HELLO"))], enabled: true, delaySeconds: 0)
         let format = kCVPixelFormatType_420YpCbCr8BiPlanarVideoRange
 
         let anamorphic = try blackFrame(format)
diff --git a/docs/api.md b/docs/api.md
index 7968ebfa6..c4331b77f 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -671,6 +671,7 @@ suppressing `AVPlayerItemLegibleOutput` to keep the measurement running.
 | `$nativeSubtitleRenditionAvailable` | At least one cue exists for the native track. Gate the AVMediaSelection picker on it. |
 | `$nativeSubtitleRenditionsServed` | Whether the served playlist is the master. A reload signal and a diagnostic, nothing more: whether a legible rendition reaches a wired external display is AVKit's business and is not observable from here. |
 | `setNativeSubtitleRendering(_:)` | Hand subtitle drawing to AVKit while the video leaves the host's view hierarchy (PiP, AirPlay, wired external display) and take it back on return. No-op when the active subtitle has no native text equivalent (bitmap, or a track added after load). |
+| `setSoftwareSubtitleDelay(_:)`, `softwareSubtitleDelaySeconds` | Media-time offset for both channels composited into software PiP frames: positive delays cues, negative advances them. Non-finite values are ignored; the default is 0 and the value survives later loads on the same engine. Takes effect on the next composited frame, without a seek, reopen or A/V clock change. A host overlay applies the same value as `clock.sourceTime - delay`. AVPlayer-owned native renditions, native PiP and AirPlay are not shifted; a host offering a timing control should say so. |
 | `teletextPage`, `setTeletextPage(_:)` | The DVB teletext caption page, at load and while the channel plays. |
 
 ## Live and DVR
@@ -1144,15 +1145,3 @@ Public for the CLI, the test suite, or a diagnostic overlay, and outside the sha
 - **`DiscInspector` / `DiscInspection`**, `DoviRpuConverter` and its probe, `AudioTapProbe`, `SoftwareDecodeProbeResult`, `A53SEIParser`: repro and inspection surfaces behind `aetherctl` subcommands.
 - **`HLSLiveIngestReader`'s internals** (`terminalError`, `upstreamTargetDuration`, `observedLiveCadenceSeconds`, `closedLiveCadenceSeconds`, `upstreamSegmentDurationSeconds`, `companionAudioReader`): fixture and diagnostic reads. The last two are the closed evidence the served TARGETDURATION is sealed from (AE#447); `upstreamTargetDuration` is the upstream's own claim, reported in the seal line and derived from nowhere.
 - **`SubtitleChannel`**: the primary / secondary selector on the engine's internal subtitle routing. No public signature takes one; a host picks the channel by calling the primary or the secondary method.
-
-### Software PiP subtitle timing
-
-`setSoftwareSubtitleDelay(_:)` applies an engine-wide media-time offset to both subtitle
-channels composited into software PiP frames. Positive values delay cues; negative values
-advance them. `softwareSubtitleDelaySeconds` reports the current preference. Non-finite
-values are ignored; the default is zero and the value survives subsequent loads on the same
-engine. It takes effect on the next composited frame without a seek, source reopen or A/V
-clock change. An inline overlay can use the same value with `clock.sourceTime - delay`.
-
-This setting does not shift AVPlayer-owned native subtitle renditions, native PiP or AirPlay.
-Hosts should expose that renderer limit when offering subtitle timing controls.

From 2ef8aae02661fd9784a2c0644529833512c45e30 Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 7 Oct 2026 18:52:07 +0200
Subject: [PATCH 335/359] fix(test): the #243 fetch-tally test tolerates a
 parallel session start

startMemoryProbe zeroes HTTPDiscIOReader's process-wide tally at every
session start, so an engine test loading in parallel could reset it between
the test's baseline and its read, and the delta came up short (CI on 6c2ec706:
786432 of the expected 1048577). The comment's premise that concurrent work
can only add was wrong. A reset count now tells a reset in between apart from
a missed range, and the delta is asserted only when none happened.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 Sources/AetherEngine/IO/HTTPDiscIOReader.swift           | 9 +++++++++
 .../AetherEngineTests/Issue243ReaderRetentionTests.swift | 9 +++++++--
 2 files changed, 16 insertions(+), 2 deletions(-)

diff --git a/Sources/AetherEngine/IO/HTTPDiscIOReader.swift b/Sources/AetherEngine/IO/HTTPDiscIOReader.swift
index e6dfab66e..1e805efa4 100644
--- a/Sources/AetherEngine/IO/HTTPDiscIOReader.swift
+++ b/Sources/AetherEngine/IO/HTTPDiscIOReader.swift
@@ -397,6 +397,7 @@ final class HTTPDiscIOReader: IOReader, @unchecked Sendable {
     /// counter. Reset per session by the memory probe.
     private static let fetchedLock = NSLock()
     nonisolated(unsafe) private static var fetchedBytesTotal: Int64 = 0
+    nonisolated(unsafe) private static var fetchedResetCount: Int = 0
 
     private static func recordFetched(bytes: Int) {
         guard bytes > 0 else { return }
@@ -410,9 +411,17 @@ final class HTTPDiscIOReader: IOReader, @unchecked Sendable {
         return fetchedBytesTotal
     }
 
+    /// Bumped by every reset, so a reader of `lifetimeFetchedBytes` deltas can tell that a session
+    /// start in between (`startMemoryProbe`) zeroed the tally under it.
+    static var lifetimeFetchedResetCount: Int {
+        fetchedLock.lock(); defer { fetchedLock.unlock() }
+        return fetchedResetCount
+    }
+
     static func resetLifetimeFetchedBytes() {
         fetchedLock.lock()
         fetchedBytesTotal = 0
+        fetchedResetCount &+= 1
         fetchedLock.unlock()
     }
 }
diff --git a/Tests/AetherEngineTests/Issue243ReaderRetentionTests.swift b/Tests/AetherEngineTests/Issue243ReaderRetentionTests.swift
index bc08553e0..82a2c0c3f 100644
--- a/Tests/AetherEngineTests/Issue243ReaderRetentionTests.swift
+++ b/Tests/AetherEngineTests/Issue243ReaderRetentionTests.swift
@@ -152,7 +152,9 @@ struct Issue243ReaderRetentionTests {
         config.protocolClasses = [RetentionRangeURLProtocol.self]
         HTTPDiscIOReader.resetLifetimeFetchedBytes()
         // Deltas, not absolutes: the tally is process-wide, and a reader in another suite may be
-        // fetching in parallel. Concurrent fetches can only add to it.
+        // fetching in parallel. A parallel engine session start also zeroes it (`startMemoryProbe`),
+        // which only the reset count can tell apart from a missed range.
+        let resetsAtStart = HTTPDiscIOReader.lifetimeFetchedResetCount
         let atStart = HTTPDiscIOReader.lifetimeFetchedBytes
         let reader = try #require(HTTPDiscIOReader(
             url: url, baseChunkSize: 256 * 1024, maxChunkSize: 256 * 1024,
@@ -170,7 +172,10 @@ struct Issue243ReaderRetentionTests {
         }
         #expect(read == 1024 * 1024)
         // Four 256 KB refills plus the one-byte size probe from init.
-        #expect(HTTPDiscIOReader.lifetimeFetchedBytes - atStart >= Int64(1024 * 1024 + 1))
+        let fetched = HTTPDiscIOReader.lifetimeFetchedBytes - atStart
+        if HTTPDiscIOReader.lifetimeFetchedResetCount == resetsAtStart {
+            #expect(fetched >= Int64(1024 * 1024 + 1))
+        }
 
         HTTPDiscIOReader.resetLifetimeFetchedBytes()
         #expect(HTTPDiscIOReader.lifetimeFetchedBytes < Int64(1024 * 1024))

From b64ff7e274eff3c08b5e1b3d852b3c136c2bb08f Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 7 Oct 2026 19:04:58 +0200
Subject: [PATCH 336/359] docs(api): selectAudioTrack describes the serialized,
 item-retaining rebuild

#711 documented the new contract under "Public but not host API" while the
Audio table still promised 0.5 to 1 s of black on every switch. The row now
carries the contract itself: native handover keeps the old item mounted,
rapid picks coalesce, stop/load drop queued work, and a play/pause during the
rebuild decides its final transport.

Follow-up to #711.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 docs/api.md | 13 +------------
 1 file changed, 1 insertion(+), 12 deletions(-)

diff --git a/docs/api.md b/docs/api.md
index b38d391fb..462c2b11d 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -650,7 +650,7 @@ suppressing `AVPlayerItemLegibleOutput` to keep the measurement running.
 | --- | --- |
 | `$audioTracks` | `[TrackInfo]`. Republished when `LoadOptions.confirmAtmos` confirms a track. On `.remoteBypass` it lists the audio tracks AVPlayer built for the item (normally just the one playing), read from their format descriptions: `codec` in libavcodec's spelling (`eac3`, `ac3`, `aac`), `channels`, `sampleRate`, `profile` (AAC's object type; "Dolby Digital Plus + Dolby Atmos" with `isAtmos` when the E-AC-3 dec3 record announces JOC) and `language` from the track or the selected audible option. The ids are synthetic (from 400000 up) because there is no stream index on that route; compare them only with `activeAudioTrackIndex`. |
 | `$activeAudioTrackIndex` | The selected track's id. On `.remoteBypass`, the enabled item track's. |
-| `selectAudioTrack(index:)` | Session-preserving reload, roughly 0.5 to 1 s of black. It comes back in the session's transport like `reloadAtCurrentPosition()`: a paused session stays paused. `index` is `TrackInfo.id`. A no-op when out of range, already active, or on a forward-only custom source (live ingest included), which cannot rebuild its pipeline: there a track change is a fresh `load` naming the stream. Every refusal is logged, so a picker that does nothing is explainable. Also a no-op on `.remoteBypass`, where AVPlayer owns the audio selection and the list above is informational; a different language there is a different URL. |
+| `selectAudioTrack(index:)` | Session-preserving reload. On the native path the old item stays mounted until its replacement is ready (not gapless; a media-services reset still discards it); elsewhere expect roughly 0.5 to 1 s of black. Rapid picks coalesce into one rebuild at a time, a pick back to the active track costs nothing, and `stop()` or a new `load` drops what is queued. It comes back in the session's transport like `reloadAtCurrentPosition()`: a paused session stays paused, and a `play()` or `pause()` that arrives while the rebuild awaits I/O decides the final state. `index` is `TrackInfo.id`. A no-op when out of range, already active, or on a forward-only custom source (live ingest included), which cannot rebuild its pipeline: there a track change is a fresh `load` naming the stream. Every refusal is logged, so a picker that does nothing is explainable. Also a no-op on `.remoteBypass`, where AVPlayer owns the audio selection and the list above is informational; a different language there is a different URL. |
 | `installAudioTap()`, `removeAudioTap()`, `audioTapHasDeliverySource`, `AetherEngine.audioTapFormat` | Opt-in decoded PCM, mono Float32 48 kHz with source-PTS stamps, off the render path. See the contract above. |
 
 ## Subtitles
@@ -1146,14 +1146,3 @@ Public for the CLI, the test suite, or a diagnostic overlay, and outside the sha
 - **`DiscInspector` / `DiscInspection`**, `DoviRpuConverter` and its probe, `AudioTapProbe`, `SoftwareDecodeProbeResult`, `A53SEIParser`: repro and inspection surfaces behind `aetherctl` subcommands.
 - **`HLSLiveIngestReader`'s internals** (`terminalError`, `upstreamTargetDuration`, `observedLiveCadenceSeconds`, `closedLiveCadenceSeconds`, `upstreamSegmentDurationSeconds`, `companionAudioReader`): fixture and diagnostic reads. The last two are the closed evidence the served TARGETDURATION is sealed from (AE#447); `upstreamTargetDuration` is the upstream's own claim, reported in the seal line and derived from nowhere.
 - **`SubtitleChannel`**: the primary / secondary selector on the engine's internal subtitle routing. No public signature takes one; a host picks the channel by calling the primary or the secondary method.
-
-### Audio selection while rebuilding
-
-`selectAudioTrack(index:)` coalesces rapid choices and runs one rebuild at a time.
-A queued choice for the already-active track requires no source reopen. Stop or a
-new load invalidates pending audio selections; a superseded or cancelled rebuild
-cannot publish a stale error. Play/pause commands received while a rebuild awaits
-I/O determine the final transport state.
-
-An ordinary native audio handover retains the old item until replacement, but does
-not promise a gapless switch. A media-services reset still discards the old host.

From dd1d5f885cd5da65a6641e42f5cd6ba341c6a05c Mon Sep 17 00:00:00 2001
From: Vincent Herbst <superuser404@tuta.com>
Date: Wed, 7 Oct 2026 19:41:29 +0200
Subject: [PATCH 337/359] fix(transport): a play/pause during any session
 rebuild decides how it comes back

#711 parked the transport for an audio pick in a field of its own, beside
transportIntentUnderReconstruction (AE#464 round 3), so a press during a
disc-title switch, reloadAtCurrentPosition or an engine-raised rebuild was
still lost: the rebuild came back in the state it started from. play() and
pause() now write the existing field while sessionPreservingReloadInFlight
holds (not while .loading, which play() itself leaves), reloadWithAudioOverride
settles from it, and the URL branch of reloadAtCurrentPosition replays it after
load() returns. audioSelectionTransportIntent is gone.

Covered end to end on both branches: a pause during an audio rebuild and during
a URL reload holds, a play during a custom-source reload holds, and a press
outside a rebuild parks nothing. All four fail without the change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WJcXkGQrMiBPixVEFTSBJS
---
 CHANGELOG.md                                  |  1 +
 .../AetherEngine/AetherEngine+Loading.swift   |  6 +-
 Sources/AetherEngine/AetherEngine.swift       | 23 +++--
 .../AudioSelectionOwnershipTests.swift        | 12 ---
 .../Issue464ReloadPreservesSessionTests.swift | 86 +++++++++++++++++++
 docs/api.md                                   |  2 +-
 6 files changed, 107 insertions(+), 23 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 632a2d8f1..448469c46 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -19,6 +19,7 @@ the public-API contract.
 
 - Video routing consults the AV1 hardware decoder only for AV1 sources, avoiding supplemental decoder registration on unrelated playback starts.
 - Rapid audio-track selections coalesce into serialized rebuilds. Stop/load invalidate queued work, and play/pause commands received during a rebuild supply its final transport intent. Native handover retains the old item until replacement unless media services were reset.
+- A `play()` or `pause()` that arrives while any session-preserving rebuild runs (an audio or disc-title switch, `reloadAtCurrentPosition()`, an engine-raised rebuild) now decides the transport it comes back in; before, only an audio pick honoured it and the others came back in the state they started from.
 
 ## [7.28.3] - 2026-10-07
 
diff --git a/Sources/AetherEngine/AetherEngine+Loading.swift b/Sources/AetherEngine/AetherEngine+Loading.swift
index 2bad353b9..b205f5da2 100644
--- a/Sources/AetherEngine/AetherEngine+Loading.swift
+++ b/Sources/AetherEngine/AetherEngine+Loading.swift
@@ -2485,7 +2485,7 @@ extension AetherEngine {
                 )
                 presentCurrentLayer()
                 // Keep the latest transport intent if play/pause changed while the rebuild awaited I/O.
-                if audioSelectionTransportIntent ?? resumesPlaying { softwareHost?.play() }
+                if transportIntentUnderReconstruction ?? resumesPlaying { softwareHost?.play() }
                 else { softwareHost?.pause() }
             } else {
                 EngineLog.emit("[AetherEngine] reload: loadNative enter audio=\(audioStreamIndex.map(String.init) ?? "nil") resumeAt=\(String(format: "%.2f", resumeAt))s", category: .engine)
@@ -2576,11 +2576,11 @@ extension AetherEngine {
                     settleCap: loadedOptions.isLive ? .standard : .awaitObservedEnd,
                     isCurrent: { self.loadGeneration == gen })
                 try checkLoadCurrent(gen)
-                if audioSelectionTransportIntent ?? resumesPlaying { nativeHost?.play() }
+                if transportIntentUnderReconstruction ?? resumesPlaying { nativeHost?.play() }
                 else { nativeHost?.pause() }
             }
             try checkLoadCurrent(gen)
-            state = (audioSelectionTransportIntent ?? resumesPlaying) ? .playing : .paused
+            state = (transportIntentUnderReconstruction ?? resumesPlaying) ? .playing : .paused
             // Re-arm samplers: stopInternal nilled them, and the reload path bypasses public load() that normally restarts them. Without this, liveTelemetry stays nil and the stats overlay shows "-" after every audio switch.
             startMemoryProbe()
             startLiveTelemetrySampler()
diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index 05d4e9572..044f90c29 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -3462,15 +3462,12 @@ public final class AetherEngine: ObservableObject {
     private(set) var audioSelectionTask: Task<Void, Never>?
     private var pendingAudioSelection: Int?
     private var audioSelectionEpoch = UUID()
-    // Non-nil only during an audio rebuild. Transport received across awaits wins.
-    var audioSelectionTransportIntent: Bool?
 
     private func cancelPendingAudioSelection() {
         audioSelectionEpoch = UUID()
         audioSelectionTask?.cancel()
         audioSelectionTask = nil
         pendingAudioSelection = nil
-        audioSelectionTransportIntent = nil
     }
 
     /// AE#464 round 3: true while a re-anchor raised by `setAudioDelay` is running, so the presses
@@ -3487,6 +3484,15 @@ public final class AetherEngine: ObservableObject {
     /// The transport state a rebuild of this session has to come back in (#464 round 2). Asks the
     /// native host for its durable intent where there is one to ask, exactly as `togglePlayPause`
     /// does, and falls back to `state` on the routes that have no competing transport owner.
+    /// AE#711 follow-up: a play/pause that arrives while a session-preserving rebuild runs is the
+    /// transport that rebuild has to come back in. Recorded on the flag both rebuild routes raise
+    /// rather than on `.loading`, because `play()` itself moves `.loading` to `.playing` and a pause
+    /// after it would otherwise go unrecorded. Read back where each rebuild settles its transport.
+    func recordTransportDuringRebuild(playing: Bool) {
+        guard sessionPreservingReloadInFlight else { return }
+        transportIntentUnderReconstruction = playing
+    }
+
     var sessionRebuildResumesPlaying: Bool {
         let nativeIntent = (nativeHost != nil && !audioAVPlayerActive && audioHost == nil && softwareHost == nil)
             ? nativeHost?.transportIntentIsPlaying
@@ -5254,7 +5260,7 @@ public final class AetherEngine: ObservableObject {
     }
 
     public func play() {
-        if audioSelectionTransportIntent != nil { audioSelectionTransportIntent = true }
+        recordTransportDuringRebuild(playing: true)
         // AetherEngine#164: a VOD parked at its final frame (scrubbed to the end, or paused there)
         // cannot advance; AVPlayer.play() would no-op and leave the button frozen. Rewind to the start
         // first, then resume. `.ended` is excluded (see shouldRewindBeforePlay): it stays terminal so a
@@ -5276,7 +5282,7 @@ public final class AetherEngine: ObservableObject {
     }
 
     public func pause() {
-        if audioSelectionTransportIntent != nil { audioSelectionTransportIntent = false }
+        recordTransportDuringRebuild(playing: false)
         resumeAfterInterruption = false
         activeTransportHost?.pause()
         isBuffering = false
@@ -5422,6 +5428,11 @@ public final class AetherEngine: ObservableObject {
         options.subtitleSessionCarryover = carryover
         try await load(url: url, startPosition: resume, options: options,
                        audioSourceStreamIndex: audioToRestore.map { Int32($0) }, discTitleID: titleID)
+        // AE#711 follow-up: `load` autostarts from the flag it was handed; a play/pause that arrived
+        // while it ran is the newer word.
+        if let intent = transportIntentUnderReconstruction, intent != options.autoplay {
+            if intent { play() } else { pause() }
+        }
         restoreSubtitleSelection(from: carryover, resumeAnchor: resume)
         // Arm the watchdog so a live reopen whose AVPlayer never becomes ready fails visibly instead of freezing.
         if options.isLive, !options.nativeRemoteHLS, playbackBackend == .native {
@@ -6942,14 +6953,12 @@ public final class AetherEngine: ObservableObject {
             defer {
                 if self.audioSelectionEpoch == epoch {
                     self.audioSelectionTask = nil
-                    self.audioSelectionTransportIntent = nil
                 }
             }
             while let selected = self.pendingAudioSelection {
                 self.pendingAudioSelection = nil
                 guard !Task.isCancelled, self.audioSelectionEpoch == epoch else { return }
                 if self.activeAudioTrackIndex == selected { continue }
-                self.audioSelectionTransportIntent = self.sessionRebuildResumesPlaying
                 let beforeReload = self.loadGeneration
                 let failure = await self.reloadWithAudioOverride(
                     url: url, audioStreamIndex: Int32(selected), expectedGeneration: beforeReload)
diff --git a/Tests/AetherEngineTests/AudioSelectionOwnershipTests.swift b/Tests/AetherEngineTests/AudioSelectionOwnershipTests.swift
index 3701fd9c2..83e837e1c 100644
--- a/Tests/AetherEngineTests/AudioSelectionOwnershipTests.swift
+++ b/Tests/AetherEngineTests/AudioSelectionOwnershipTests.swift
@@ -44,18 +44,6 @@ final class AudioSelectionOwnershipTests: XCTestCase {
         XCTAssertEqual(engine.state, .idle)
     }
 
-    func testTransportCommandsDuringAudioRebuildKeepLatestIntent() throws {
-        let engine = try fixture()
-        defer { engine.stop() }
-        engine.audioSelectionTransportIntent = true
-        engine.pause()
-        XCTAssertEqual(engine.audioSelectionTransportIntent, false)
-        engine.play()
-        XCTAssertEqual(engine.audioSelectionTransportIntent, true)
-        engine.stop()
-        XCTAssertNil(engine.audioSelectionTransportIntent)
-    }
-
     func testLiveURLDoesNotRequireHostReload() throws {
         let engine = try fixture()
         defer { engine.stop() }
diff --git a/Tests/AetherEngineTests/Issue464ReloadPreservesSessionTests.swift b/Tests/AetherEngineTests/Issue464ReloadPreservesSessionTests.swift
index a11b2c6e6..62c312727 100644
--- a/Tests/AetherEngineTests/Issue464ReloadPreservesSessionTests.swift
+++ b/Tests/AetherEngineTests/Issue464ReloadPreservesSessionTests.swift
@@ -213,6 +213,92 @@ struct Issue464RebuildCallSiteTransportTests {
         try await waitFor { engine.state == .paused }
     }
 
+    /// AE#711 follow-up: a press that lands while the rebuild runs is the newer word. `body` runs at
+    /// the rebuild's first suspension after `.loading` is published, where a host's button would.
+    private static func duringRebuild(
+        of engine: AetherEngine, _ body: @escaping @MainActor () -> Void,
+        rebuild: () async throws -> Void
+    ) async throws {
+        var fired: Task<Void, Never>?
+        let observer = engine.$state.sink { next in
+            MainActor.assumeIsolated {
+                guard fired == nil, next == .loading else { return }
+                fired = Task { @MainActor in body() }
+            }
+        }
+        defer { observer.cancel() }
+        try await rebuild()
+        await fired?.value
+        #expect(fired != nil)
+    }
+
+    @Test("a pause pressed during an audio rebuild of a playing session holds")
+    func pauseDuringAudioRebuildHolds() async throws {
+        let engine = try AetherEngine()
+        defer { engine.stop() }
+        _ = try await engine.load(source: Self.customSource())
+        #expect(engine.state == .playing)
+        let url = try #require(engine.loadedURL)
+
+        try await Self.duringRebuild(of: engine, { engine.pause() }) {
+            _ = await engine.reloadWithAudioOverride(
+                url: url, audioStreamIndex: nil, expectedGeneration: engine.loadGeneration)
+        }
+
+        #expect(engine.state != .playing)
+        #expect(engine.nativeHost?.transportIntentIsPlaying == false)
+    }
+
+    @Test("a play pressed during a reload of a paused session holds")
+    func playDuringReloadHolds() async throws {
+        let engine = try AetherEngine()
+        defer { engine.stop() }
+        _ = try await engine.load(source: Self.customSource())
+        engine.pause()
+        try await waitFor { engine.state == .paused }
+
+        try await Self.duringRebuild(of: engine, { engine.play() }) {
+            try await engine.reloadAtCurrentPosition()
+        }
+
+        #expect(engine.state == .playing)
+        #expect(engine.nativeHost?.transportIntentIsPlaying == true)
+    }
+
+    @Test("a pause pressed during a URL reload of a playing session holds")
+    func pauseDuringURLReloadHolds() async throws {
+        let file = FileManager.default.temporaryDirectory
+            .appendingPathComponent("ae711-intent-\(UUID().uuidString).mp4")
+        try ProbeTestFixtures.hdr10Plus().write(to: file)
+        defer { try? FileManager.default.removeItem(at: file) }
+        let engine = try AetherEngine()
+        defer { engine.stop() }
+        _ = try await engine.load(url: file)
+        #expect(engine.state == .playing)
+        #expect(!engine.isCustomSource)
+
+        try await Self.duringRebuild(of: engine, { engine.pause() }) {
+            try await engine.reloadAtCurrentPosition()
+        }
+
+        #expect(engine.state != .playing)
+        #expect(engine.nativeHost?.transportIntentIsPlaying == false)
+    }
+
+    @Test("outside a rebuild a press parks nothing for the next one")
+    func pressOutsideARebuildParksNothing() throws {
+        let engine = try AetherEngine()
+        defer { engine.stop() }
+        engine.transportIntentUnderReconstruction = nil
+        engine.pause()
+        engine.play()
+        #expect(engine.transportIntentUnderReconstruction == nil)
+        engine.sessionPreservingReloadInFlight = true
+        engine.pause()
+        #expect(engine.transportIntentUnderReconstruction == false)
+        engine.sessionPreservingReloadInFlight = false
+    }
+
     @Test("a playing session still comes back playing")
     func playingSessionComesBackPlaying() async throws {
         let engine = try AetherEngine()
diff --git a/docs/api.md b/docs/api.md
index 462c2b11d..65cd91c7f 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -442,7 +442,7 @@ try await player.reloadAtCurrentPosition()
 | --- | --- |
 | `load(url:startPosition:options:audioSourceStreamIndex:discTitleID:)` | `async throws -> SourceProbe?`. Discardable. Tears down any running session first. |
 | `load(source:startPosition:options:audioSourceStreamIndex:discTitleID:)` | Same, for `MediaSource.url` or `.custom(IOReader, formatHint:)`. A custom source whose initial probe fails throws, since it cannot be reopened by URL. |
-| `reloadAtCurrentPosition()` | `async throws`. Background reopen at the current position, preserving options. Session-preserving: it finishes an installed audio tap and keeps the native host where it can. It also preserves the session's TRANSPORT rather than replaying `autoplay`, so a session that was playing comes back playing and one that was paused comes back paused, whatever the mount was given (AE#464 round 2). The one exception is the resume after a background teardown, which has no transport left to read and is the host's call, so there the mount flag still decides. |
+| `reloadAtCurrentPosition()` | `async throws`. Background reopen at the current position, preserving options. Session-preserving: it finishes an installed audio tap and keeps the native host where it can. It also preserves the session's TRANSPORT rather than replaying `autoplay`, so a session that was playing comes back playing and one that was paused comes back paused, whatever the mount was given (AE#464 round 2). A `play()` or `pause()` that arrives while it runs is the newer word and decides how it comes back. The one exception is the resume after a background teardown, which has no transport left to read and is the host's call, so there the mount flag still decides. |
 | `prepareForItemReplacement()` | One-shot. Keeps the current native `AVPlayerItem` attached until the next `load()` replaces it atomically, for a host that mounts the engine's own player layer and would otherwise show a black layer across the nil-item gap of a foreground episode or playlist change. Consumed by the next `load()`, cancelled by `stop()`, no effect when the outgoing session is not native. PiP hosts do not need it: an active PiP window already forces the handover (AE#158). |
 | `stop(resetDisplayCriteria:finalTeardown:)` | Ends the session, `state` becomes `.idle`, `startupProgress` becomes nil. `resetDisplayCriteria: false` keeps the panel in its current mode across an item handoff. |
 | `AetherEngine.probe(url:options:)` / `probe(source:options:)` | `nonisolated static throws -> SourceProbe`. Container/stream metadata read, no detail-pass decoder or session. `options` is read for `httpHeaders` only. Optional trailing `limits` and `cancellation` control the whole operation (below). For a custom reader the caller keeps ownership, `close()` is not called, and the cursor is left unspecified. |

From dc4d5433a140bede2d47bb3e9ab2f98c20e0e1d7 Mon Sep 17 00:00:00 2001
From: Quick104 <31828688+Quick104@users.noreply.github.com>
Date: Wed, 7 Oct 2026 16:14:59 -0400
Subject: [PATCH 338/359] test(audio): decode the APAC click test off the
 cooperative pool

CI moved the macOS test job from macos-15 to the xcode-27 runner (macOS 27),
so the fork's APAC tests, which return early below OS 26, ran in CI for the
first time. The click test called AVAssetReader.copyNextSampleBuffer() from
the cooperative pool. That call blocks until AVFoundation has decoded the
next buffer, so it held one of a three-core runner's pool threads while the
decode waited. One run stalled for 70 s and timed out 38 deadline tests; the
rerun hung until the job limit.

The decode now runs on a thread of its own and resumes the test through a
continuation, as PythonOrigin does with its blocking read. The suite gets a
two-minute time limit so a hang reports as a failure, not a stalled job.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .../SpatialAudioBridgeTests.swift             | 28 ++++++++++++++-----
 1 file changed, 21 insertions(+), 7 deletions(-)

diff --git a/Tests/AetherEngineTests/SpatialAudioBridgeTests.swift b/Tests/AetherEngineTests/SpatialAudioBridgeTests.swift
index 8d6a15885..b553ab377 100644
--- a/Tests/AetherEngineTests/SpatialAudioBridgeTests.swift
+++ b/Tests/AetherEngineTests/SpatialAudioBridgeTests.swift
@@ -13,7 +13,7 @@ import AetherLibavutil
 /// with the encoder's 2048 frames of priming counted in, so the first packet takes the anchor and
 /// the first content frame plays there. These drive the bridge with a synthetic decoder that
 /// behaves like the real one on exactly those points.
-@Suite("TrueHD Atmos spatial bridge")
+@Suite("TrueHD Atmos spatial bridge", .timeLimit(.minutes(2)))
 struct SpatialAudioBridgeTests {
 
     /// Stand-in object decoder: one pushed byte is one 40-frame access unit (TrueHD's 1/1200 s),
@@ -357,15 +357,30 @@ struct SpatialAudioBridgeTests {
 
         let asset = AVURLAsset(url: file)
         let track = try #require(try await asset.loadTracks(withMediaType: .audio).first)
+        // copyNextSampleBuffer blocks until AVFoundation has decoded the next buffer. Called from the
+        // cooperative pool it held one of a three-core CI runner's threads while that decode waited
+        // for one, and the whole test process stalled. A thread of its own cannot starve the pool.
+        let decoded = await withCheckedContinuation {
+            (continuation: CheckedContinuation<Result<Double?, Error>, Never>) in
+            Thread.detachNewThread {
+                continuation.resume(returning: Result { try Self.clickOnset(asset: asset, track: track) })
+            }
+        }
+        let heard = try #require(try decoded.get(), "the click reaches the left channel")
+        #expect(abs(heard - 0.25) < 0.001, "the click decodes at \(heard) s, not at its source position 0.25 s")
+    }
+
+    /// Decodes the track to PCM and returns when the left channel first rises above the click
+    /// threshold, or nil when it never does. Blocks until AVFoundation has decoded that far.
+    private static func clickOnset(asset: AVURLAsset, track: AVAssetTrack) throws -> Double? {
         let reader = try AVAssetReader(asset: asset)
         let output = AVAssetReaderTrackOutput(track: track, outputSettings: [
             AVFormatIDKey: kAudioFormatLinearPCM, AVLinearPCMBitDepthKey: 32,
             AVLinearPCMIsFloatKey: true, AVLinearPCMIsNonInterleaved: false,
         ])
         reader.add(output)
-        #expect(reader.startReading())
-        var onset: Double?
-        while onset == nil, let buffer = output.copyNextSampleBuffer() {
+        guard reader.startReading() else { throw reader.error ?? CocoaError(.fileReadUnknown) }
+        while let buffer = output.copyNextSampleBuffer() {
             guard let format = CMSampleBufferGetFormatDescription(buffer),
                   let asbd = CMAudioFormatDescriptionGetStreamBasicDescription(format)?.pointee else { continue }
             let channels = Int(asbd.mChannelsPerFrame)
@@ -379,10 +394,9 @@ struct SpatialAudioBridgeTests {
                 blockBufferMemoryAllocator: nil, flags: 0, blockBufferOut: &block)
             guard let samples = list.mBuffers.mData?.assumingMemoryBound(to: Float.self) else { continue }
             if let i = (0..<frames).first(where: { abs(samples[$0 * channels]) > 0.2 }) {
-                onset = start + Double(i) / 48_000
+                return start + Double(i) / 48_000
             }
         }
-        let heard = try #require(onset, "the click reaches the left channel")
-        #expect(abs(heard - 0.25) < 0.001, "the click decodes at \(heard) s, not at its source position 0.25 s")
+        return nil
     }
 }

From e773c6614fa998beb78b47216e109f18769914cc Mon Sep 17 00:00:00 2001
From: Quick104 <31828688+Quick104@users.noreply.github.com>
Date: Wed, 7 Oct 2026 16:21:02 -0400
Subject: [PATCH 339/359] fix(subtitles): select a hidden ASS rendition only
 once it is extracted

Keeping an overlay-drawn ASS sidecar's rendition selected for AE#616 made
AVPlayer fetch and buffer it. The whole-program .vtt is served only once
extraction finishes, so a rendition selected while that ran could hold
playback up for a subtitle nobody sees. Turning subtitles off went through
the pinned deselect, which loads the legible group first, so a host that
turned them off and started playback straight away still had the rendition
selected. Silo's authorization playback tests start playback with waiting
disabled; there the late deselect stopped the player at rate 0.

The hidden rendition is now selected only after the provider's fill has
finished, which is also the first moment AE#616 can measure. Subtitles off
and a switch to an overlay track take the engine's rendition down at once,
from the group the selection recorded, before the pin runs.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md                                  |  2 +-
 .../AetherEngine/AetherEngine+Subtitles.swift | 27 ++++++++++
 Sources/AetherEngine/AetherEngine.swift       |  4 ++
 ...InjectedASSRenditionSuppressionTests.swift | 51 +++++++++++++++++--
 4 files changed, 79 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 16ba5a2f9..1d925d8e1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -35,7 +35,7 @@ the public-API contract.
 - Session option corrections recognize `httpRequestAuthorization` and external subtitle provider replacements by identity.
 - Sidecar decoding runs on a dispatch worker instead of a cooperative-pool thread, so concurrent authorized decodes cannot starve the async resolvers their requests wait on.
 - A pause made through the engine while the premature-end recovery re-seeks (AE#287) is kept. The recovery called `play()` after its seek whatever the play intent said, so the title started again.
-- An external ASS sidecar the host draws itself (`preserveASSMarkup`) on the `nativeRemoteHLS` bypass keeps its plain rendition selected behind a suppressing legible output instead of deselecting it. AE#616 measures `sourceTime` off the selected injected rendition, so the deselect left the clock a styled-ASS overlay draws from on item time, 1 to 8 s ahead of the picture after a seek on a transcode restarted at an earlier keyframe.
+- An external ASS sidecar the host draws itself (`preserveASSMarkup`) on the `nativeRemoteHLS` bypass keeps its plain rendition selected behind a suppressing legible output instead of deselecting it. AE#616 measures `sourceTime` off the selected injected rendition, so the deselect left the clock a styled-ASS overlay draws from on item time, 1 to 8 s ahead of the picture after a seek on a transcode restarted at an earlier keyframe. The hidden rendition is selected only once its whole-program WebVTT has been extracted, because AVPlayer fetches and buffers a selected rendition, and turning subtitles off takes it down immediately.
 - TrueHD Atmos rendered to APAC reports a decoder that produces nothing (`.audioBridgeProducedNoOutput` on VOD), as the channel bridges do since AE#641, instead of playing the picture over silence.
 - Playlist preflight through a refreshable `HTTPRequestAuthorization` keeps the 2 MB playlist cap the static-header preflight has (audit NAT-5), and relayed fetches use upstream's per-fetch pending cap (audit NET-107) in place of the fork's high-water wait.
 - Native subtitle renditions wait for complete extraction instead of caching a partial whole-track response. While extraction is pending, the local server returns a retryable HTTP 503.
diff --git a/Sources/AetherEngine/AetherEngine+Subtitles.swift b/Sources/AetherEngine/AetherEngine+Subtitles.swift
index 57a1e28c1..21065aa31 100644
--- a/Sources/AetherEngine/AetherEngine+Subtitles.swift
+++ b/Sources/AetherEngine/AetherEngine+Subtitles.swift
@@ -1674,6 +1674,7 @@ extension AetherEngine {
         // it off until the host selects again; the pin is a no-op while a reapply ordinal stands.
         if let active = activeSubtitleTrackIndex, injectedSubtitleRenditionNames[active] != nil,
            nativeSubtitleReapplyOrdinal == nil {
+            deselectInjectedRenditionNow()
             forceNativeLegibleDeselectedUntilHostSelects()
         } else if let active = activeSubtitleTrackIndex,
            nativeSubtitleRenderingRequested
@@ -2724,6 +2725,7 @@ extension AetherEngine {
         guard let id = activeSubtitleTrackIndex, injectedSubtitleRenditionNames[id] != nil else { return }
         injectedSubtitleSelectionTask?.cancel()
         injectedSubtitleSelectionTask = nil
+        deselectInjectedRenditionNow()
         forceNativeLegibleDeselectedUntilHostSelects()
     }
 
@@ -2786,11 +2788,19 @@ extension AetherEngine {
                 // The reporter's order: take the rendition down, let a frame or two pass, then hide
                 // it and select it again.
                 item.select(nil, in: group)
+                // AVPlayer fetches and buffers a selected rendition, and the whole-program .vtt is only
+                // served once extraction finishes, so a hidden one selected early can hold playback up.
+                // It is there only for AE#616, which reads nothing before the fill is done either.
+                while let provider = self.remoteHLSSubtitleProxy?.provider, !provider.isFillFinished {
+                    try? await Task.sleep(nanoseconds: 200_000_000)
+                    guard stillWanted() else { return }
+                }
                 try? await Task.sleep(nanoseconds: 100_000_000)
                 guard stillWanted() else { return }
                 self.suppressInjectedRenditionDrawing(on: item)
             }
             item.select(group.options[index], in: group)
+            self.injectedRenditionSelection = InjectedRenditionSelection(item: item, group: group)
             EngineLog.emit("[AetherEngine] #316: selected injected rendition \"\(name)\" for external id=\(id)"
                            + (nativeRendering ? "" : ", drawn by the host overlay (rendition suppressed)"),
                            category: .engine)
@@ -2806,6 +2816,16 @@ extension AetherEngine {
         injectedRenditionSuppression = InjectedRenditionSuppression(output: output, item: item)
     }
 
+    /// Takes the injected rendition the engine selected down on the spot. The pinned deselect that
+    /// follows has to load the legible group first, and a rendition still selected when playback
+    /// starts is one AVPlayer goes on fetching.
+    private func deselectInjectedRenditionNow() {
+        guard let selection = injectedRenditionSelection else { return }
+        injectedRenditionSelection = nil
+        guard let item = selection.item, item === currentAVPlayer?.currentItem else { return }
+        item.select(nil, in: selection.group)
+    }
+
     /// Lets AVPlayer draw legible media again. Called right before a selection AVPlayer is meant to
     /// draw, and at teardown. A deselect keeps the output: nothing selected draws nothing, and a switch
     /// between styled tracks must not uncover the old rendition while the next selection resolves.
@@ -2835,6 +2855,7 @@ extension AetherEngine {
                   ordinal < group.options.count else { return }
             // The origin's own rendition is AVPlayer's to draw.
             self.releaseInjectedRenditionSuppression()
+            self.injectedRenditionSelection = nil
             item.select(group.options[ordinal], in: group)
             EngineLog.emit(
                 "[AetherEngine] AE#154: remote-HLS legible select ordinal=\(ordinal) (\(group.options[ordinal].displayName))",
@@ -2849,6 +2870,12 @@ struct InjectedRenditionSuppression {
     weak var item: AVPlayerItem?
 }
 
+/// The injected rendition the engine selected and the group it belongs to.
+struct InjectedRenditionSelection {
+    weak var item: AVPlayerItem?
+    let group: AVMediaSelectionGroup
+}
+
 /// AE#628: one channel's share of a drain tick, everything the decode needs and everything the
 /// apply half reads back. Built and consumed on the MainActor; only `decodeHandoff` leaves it.
 struct SubtitleDrainChannelWork {
diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index 58fd7c775..aff9c63be 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -2356,6 +2356,8 @@ public final class AetherEngine: ObservableObject {
     /// The suppressing legible output behind which an overlay-drawn ASS track keeps its injected
     /// rendition selected, so AE#616 goes on measuring. Nil whenever AVPlayer may draw legible media.
     var injectedRenditionSuppression: InjectedRenditionSuppression?
+    /// What `deselectInjectedRenditionNow` takes down. Nil once anything else owns the selection.
+    var injectedRenditionSelection: InjectedRenditionSelection?
 
     /// Deferred lazy-reader start while a producer restart is in flight (#93 residual): the
     /// readers' side demuxer competed with the restart for the starved link. Cancelled by
@@ -4098,6 +4100,7 @@ public final class AetherEngine: ObservableObject {
         injectedSubtitleSelectionTask?.cancel()
         injectedSubtitleSelectionTask = nil
         releaseInjectedRenditionSuppression()
+        injectedRenditionSelection = nil
         detachRemoteHLSCueClock()   // AE#616
         stallRecoveryWindowUntil = .distantPast
         stallRecoveryReasserts = 0
@@ -6278,6 +6281,7 @@ public final class AetherEngine: ObservableObject {
         injectedSubtitleSelectionTask?.cancel()
         injectedSubtitleSelectionTask = nil
         releaseInjectedRenditionSuppression()
+        injectedRenditionSelection = nil
         detachRemoteHLSCueClock()   // AE#616
         // Font attachments are session-scoped but must survive stopInternal (audio-track-switch skips the probe;
         // clearing in stopInternal would leave the session with an empty font list after any audio switch).
diff --git a/Tests/AetherEngineTests/InjectedASSRenditionSuppressionTests.swift b/Tests/AetherEngineTests/InjectedASSRenditionSuppressionTests.swift
index 91d3029a3..3639e50bc 100644
--- a/Tests/AetherEngineTests/InjectedASSRenditionSuppressionTests.swift
+++ b/Tests/AetherEngineTests/InjectedASSRenditionSuppressionTests.swift
@@ -17,11 +17,20 @@ import AVFoundation
 struct InjectedASSRenditionSuppressionTests {
 
     private static let script = #"""
-    import http.server
+    import http.server, time
     class Handler(http.server.BaseHTTPRequestHandler):
         protocol_version = "HTTP/1.1"
         def log_message(self, *args): pass
         def do_GET(self):
+            if self.path == "/slow.ass":
+                time.sleep(2)
+                body = open("sub.ass", "rb").read()
+                self.send_response(200)
+                self.send_header("Content-Type", "text/x-ssa")
+                self.send_header("Content-Length", str(len(body)))
+                self.end_headers()
+                self.wfile.write(body)
+                return
             if self.path == "/master.m3u8":
                 body = b"#EXTM3U\n#EXT-X-STREAM-INF:BANDWIDTH=800000\nmedia.m3u8\n"
             elif self.path == "/media.m3u8":
@@ -101,16 +110,50 @@ struct InjectedASSRenditionSuppressionTests {
         engine.setNativeSubtitleRendering(false)
         try await waitFor { Self.selectedName(item, in: group) == name && Self.suppressed(item) }
 
-        // Off takes the rendition down and leaves the output: nothing selected draws nothing, and
-        // the next styled pick must not uncover a line while it resolves.
+        // Off takes the rendition down at once and leaves the output: nothing selected draws
+        // nothing, and the next styled pick must not uncover a line while it resolves.
         engine.clearSubtitle()
-        try await waitFor { Self.selectedName(item, in: group) == nil }
+        #expect(Self.selectedName(item, in: group) == nil)
         #expect(Self.suppressed(item))
 
         engine.selectSubtitleTrack(index: id)
         try await waitFor { Self.selectedName(item, in: group) == name }
         #expect(Self.suppressed(item))
     }
+
+    /// AVPlayer fetches and buffers a selected rendition, and the whole-program .vtt is served only
+    /// once extraction finishes. A hidden rendition selected before that holds playback up for a
+    /// subtitle nobody sees, and one still selected when the host turns subtitles off and plays is
+    /// fetched on into playback. Seen as a stalled start in Silo's authorization playback tests.
+    @Test("The hidden rendition waits for its extraction, and Off takes it down at once")
+    func hiddenRenditionWaitsForExtraction() async throws {
+        let origin = try #require(await PythonOrigin.launch(
+            prefix: "aether-ass-slow", script: Self.script, files: ["sub.ass": Self.assScript]))
+        defer { origin.stop() }
+        let engine = try AetherEngine()
+        defer { engine.stop(finalTeardown: true) }
+        let master = try #require(URL(string: "http://127.0.0.1:\(origin.port)/master.m3u8"))
+        let sidecar = try #require(URL(string: "http://127.0.0.1:\(origin.port)/slow.ass"))
+        _ = try await engine.load(url: master, options: LoadOptions(
+            nativeRemoteHLS: true, preserveASSMarkup: true,
+            externalSubtitles: [ExternalSubtitleTrack(url: sidecar, name: "Styled ASS")], autoplay: false))
+        let id = AetherEngine.externalSubtitleTrackIDBase
+        let name = try #require(engine.injectedSubtitleRenditionNames[id])
+        let item = try #require(engine.currentAVPlayer?.currentItem)
+        let group = try #require(try await item.asset.loadMediaSelectionGroup(for: .legible))
+        let provider = try #require(engine.remoteHLSSubtitleProxy?.provider)
+
+        engine.selectSubtitleTrack(index: id)
+        try await Task.sleep(for: .milliseconds(800))
+        #expect(!provider.isFillFinished, "the origin holds the sidecar for two seconds")
+        #expect(Self.selectedName(item, in: group) == nil)
+
+        try await waitFor { provider.isFillFinished }
+        try await waitFor { Self.selectedName(item, in: group) == name && Self.suppressed(item) }
+
+        engine.clearSubtitle()
+        #expect(Self.selectedName(item, in: group) == nil)
+    }
 }
 
 #endif

From 2d221aaa089ed58a5a1a4cb96b4804c5b4612354 Mon Sep 17 00:00:00 2001
From: Quick104 <31828688+Quick104@users.noreply.github.com>
Date: Wed, 7 Oct 2026 16:59:16 -0400
Subject: [PATCH 340/359] fix(subtitles): select the hidden ASS rendition once
 playback runs

e773c661 waited only for the WebVTT extraction. A sidecar that extracts in
milliseconds was still selected while the item sat paused before its first
play, so AVPlayer had the rendition in its startup buffer. Silo's
authorization playback tests start with stall waiting off, and in CI they
stopped at rate 0 on iOS and tvOS.

AE#616 measures lines AVPlayer presents, so a paused item gains nothing from
the rendition. It now joins once the fill is done and playback is running,
and never touches the startup buffer. A DEBUG flag lets the engine tests
select it on fixture media that cannot play.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md                                  |  2 +-
 .../AetherEngine/AetherEngine+Subtitles.swift | 18 ++++++++---
 Sources/AetherEngine/AetherEngine.swift       |  2 ++
 ...InjectedASSRenditionSuppressionTests.swift | 32 +++++++++++++++++++
 4 files changed, 49 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1d925d8e1..31f949c01 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -35,7 +35,7 @@ the public-API contract.
 - Session option corrections recognize `httpRequestAuthorization` and external subtitle provider replacements by identity.
 - Sidecar decoding runs on a dispatch worker instead of a cooperative-pool thread, so concurrent authorized decodes cannot starve the async resolvers their requests wait on.
 - A pause made through the engine while the premature-end recovery re-seeks (AE#287) is kept. The recovery called `play()` after its seek whatever the play intent said, so the title started again.
-- An external ASS sidecar the host draws itself (`preserveASSMarkup`) on the `nativeRemoteHLS` bypass keeps its plain rendition selected behind a suppressing legible output instead of deselecting it. AE#616 measures `sourceTime` off the selected injected rendition, so the deselect left the clock a styled-ASS overlay draws from on item time, 1 to 8 s ahead of the picture after a seek on a transcode restarted at an earlier keyframe. The hidden rendition is selected only once its whole-program WebVTT has been extracted, because AVPlayer fetches and buffers a selected rendition, and turning subtitles off takes it down immediately.
+- An external ASS sidecar the host draws itself (`preserveASSMarkup`) on the `nativeRemoteHLS` bypass keeps its plain rendition selected behind a suppressing legible output instead of deselecting it. AE#616 measures `sourceTime` off the selected injected rendition, so the deselect left the clock a styled-ASS overlay draws from on item time, 1 to 8 s ahead of the picture after a seek on a transcode restarted at an earlier keyframe. The hidden rendition is selected only once its whole-program WebVTT has been extracted and playback is running, because AVPlayer fetches and buffers a selected rendition and AE#616 measures only presented lines. Turning subtitles off takes it down immediately.
 - TrueHD Atmos rendered to APAC reports a decoder that produces nothing (`.audioBridgeProducedNoOutput` on VOD), as the channel bridges do since AE#641, instead of playing the picture over silence.
 - Playlist preflight through a refreshable `HTTPRequestAuthorization` keeps the 2 MB playlist cap the static-header preflight has (audit NAT-5), and relayed fetches use upstream's per-fetch pending cap (audit NET-107) in place of the fork's high-water wait.
 - Native subtitle renditions wait for complete extraction instead of caching a partial whole-track response. While extraction is pending, the local server returns a retryable HTTP 503.
diff --git a/Sources/AetherEngine/AetherEngine+Subtitles.swift b/Sources/AetherEngine/AetherEngine+Subtitles.swift
index 21065aa31..e98727893 100644
--- a/Sources/AetherEngine/AetherEngine+Subtitles.swift
+++ b/Sources/AetherEngine/AetherEngine+Subtitles.swift
@@ -2788,10 +2788,10 @@ extension AetherEngine {
                 // The reporter's order: take the rendition down, let a frame or two pass, then hide
                 // it and select it again.
                 item.select(nil, in: group)
-                // AVPlayer fetches and buffers a selected rendition, and the whole-program .vtt is only
-                // served once extraction finishes, so a hidden one selected early can hold playback up.
-                // It is there only for AE#616, which reads nothing before the fill is done either.
-                while let provider = self.remoteHLSSubtitleProxy?.provider, !provider.isFillFinished {
+                // AVPlayer fetches and buffers a selected rendition, so a hidden one selected before
+                // playback runs joins the startup buffer for a subtitle nobody sees. It is there only
+                // for AE#616, which measures presented lines and reads nothing before the fill is done.
+                while !self.hiddenRenditionMayJoin() {
                     try? await Task.sleep(nanoseconds: 200_000_000)
                     guard stillWanted() else { return }
                 }
@@ -2816,6 +2816,16 @@ extension AetherEngine {
         injectedRenditionSuppression = InjectedRenditionSuppression(output: output, item: item)
     }
 
+    /// When a hidden ASS rendition may be selected: its whole-program .vtt is extracted, and playback
+    /// is running, so AE#616 has presented lines to measure.
+    private func hiddenRenditionMayJoin() -> Bool {
+        if let provider = remoteHLSSubtitleProxy?.provider, !provider.isFillFinished { return false }
+        #if DEBUG
+        if hiddenRenditionIgnoresPlaybackForTesting { return true }
+        #endif
+        return currentAVPlayer?.timeControlStatus == .playing
+    }
+
     /// Takes the injected rendition the engine selected down on the spot. The pinned deselect that
     /// follows has to load the legible group first, and a rendition still selected when playback
     /// starts is one AVPlayer goes on fetching.
diff --git a/Sources/AetherEngine/AetherEngine.swift b/Sources/AetherEngine/AetherEngine.swift
index aff9c63be..2ed1bb446 100644
--- a/Sources/AetherEngine/AetherEngine.swift
+++ b/Sources/AetherEngine/AetherEngine.swift
@@ -1243,6 +1243,8 @@ public final class AetherEngine: ObservableObject {
     #if DEBUG
     /// AE#628: lets a test drive the drain tick with a real decoder but no playback session.
     var subtitleDrainDecoderFactoryForTesting: ((Int32) -> EmbeddedSubtitleDecoder?)?
+    /// Lets a test select the hidden ASS rendition on an item whose fixture media never plays.
+    var hiddenRenditionIgnoresPlaybackForTesting = false
     #endif
     /// SW-host sessions have no HLSVideoEngine; their tap fills this store instead.
     var softwareSubtitlePacketStore: SubtitlePacketStore?
diff --git a/Tests/AetherEngineTests/InjectedASSRenditionSuppressionTests.swift b/Tests/AetherEngineTests/InjectedASSRenditionSuppressionTests.swift
index 3639e50bc..a9ae15559 100644
--- a/Tests/AetherEngineTests/InjectedASSRenditionSuppressionTests.swift
+++ b/Tests/AetherEngineTests/InjectedASSRenditionSuppressionTests.swift
@@ -83,6 +83,7 @@ struct InjectedASSRenditionSuppressionTests {
 
         let engine = try AetherEngine()
         defer { engine.stop(finalTeardown: true) }
+        engine.hiddenRenditionIgnoresPlaybackForTesting = true
         let master = try #require(URL(string: "http://127.0.0.1:\(origin.port)/master.m3u8"))
         _ = try await engine.load(url: master, options: LoadOptions(
             nativeRemoteHLS: true, preserveASSMarkup: true,
@@ -121,6 +122,36 @@ struct InjectedASSRenditionSuppressionTests {
         #expect(Self.suppressed(item))
     }
 
+    /// AE#616 measures presented lines, so a paused item has nothing to gain from the hidden rendition,
+    /// and selected before playback starts it would join the startup buffer. Silo's authorization
+    /// playback tests start with stall waiting off and stopped at rate 0 when it did.
+    @Test("A paused item gets no hidden rendition, and the overlay still gets its cues")
+    func pausedItemGetsNoHiddenRendition() async throws {
+        let origin = try #require(await PythonOrigin.launch(prefix: "aether-ass-paused", script: Self.script))
+        defer { origin.stop() }
+        let ass = FileManager.default.temporaryDirectory
+            .appendingPathComponent("paused-\(UUID().uuidString).ass")
+        try Self.assScript.write(to: ass, atomically: true, encoding: .utf8)
+        defer { try? FileManager.default.removeItem(at: ass) }
+        let engine = try AetherEngine()
+        defer { engine.stop(finalTeardown: true) }
+        let master = try #require(URL(string: "http://127.0.0.1:\(origin.port)/master.m3u8"))
+        _ = try await engine.load(url: master, options: LoadOptions(
+            nativeRemoteHLS: true, preserveASSMarkup: true,
+            externalSubtitles: [ExternalSubtitleTrack(url: ass, name: "Styled ASS")], autoplay: false))
+        let id = AetherEngine.externalSubtitleTrackIDBase
+        let item = try #require(engine.currentAVPlayer?.currentItem)
+        let group = try #require(try await item.asset.loadMediaSelectionGroup(for: .legible))
+        let provider = try #require(engine.remoteHLSSubtitleProxy?.provider)
+
+        engine.selectSubtitleTrack(index: id)
+        try await waitFor { provider.isFillFinished && !engine.subtitleCues.isEmpty }
+        try await Task.sleep(for: .milliseconds(500))
+        #expect(engine.currentAVPlayer?.timeControlStatus != .playing)
+        #expect(Self.selectedName(item, in: group) == nil)
+        #expect(!Self.suppressed(item))
+    }
+
     /// AVPlayer fetches and buffers a selected rendition, and the whole-program .vtt is served only
     /// once extraction finishes. A hidden rendition selected before that holds playback up for a
     /// subtitle nobody sees, and one still selected when the host turns subtitles off and plays is
@@ -132,6 +163,7 @@ struct InjectedASSRenditionSuppressionTests {
         defer { origin.stop() }
         let engine = try AetherEngine()
         defer { engine.stop(finalTeardown: true) }
+        engine.hiddenRenditionIgnoresPlaybackForTesting = true
         let master = try #require(URL(string: "http://127.0.0.1:\(origin.port)/master.m3u8"))
         let sidecar = try #require(URL(string: "http://127.0.0.1:\(origin.port)/slow.ass"))
         _ = try await engine.load(url: master, options: LoadOptions(

From afff51c608e50861229c0fa5ec26155a28f9005b Mon Sep 17 00:00:00 2001
From: Quick104 <31828688+Quick104@users.noreply.github.com>
Date: Wed, 7 Oct 2026 17:11:12 -0400
Subject: [PATCH 341/359] test(subtitles): hold the sidecar until the test
 releases it

The extraction test assumed a two-second origin delay would outlast the
load and the selection. The fill starts at load, so on a loaded CI runner
it had already finished by the time the test looked. The origin now holds
the sidecar until the test drops a release file in its work directory.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .../InjectedASSRenditionSuppressionTests.swift  | 17 +++++++++++------
 1 file changed, 11 insertions(+), 6 deletions(-)

diff --git a/Tests/AetherEngineTests/InjectedASSRenditionSuppressionTests.swift b/Tests/AetherEngineTests/InjectedASSRenditionSuppressionTests.swift
index a9ae15559..33be97ad4 100644
--- a/Tests/AetherEngineTests/InjectedASSRenditionSuppressionTests.swift
+++ b/Tests/AetherEngineTests/InjectedASSRenditionSuppressionTests.swift
@@ -17,13 +17,15 @@ import AVFoundation
 struct InjectedASSRenditionSuppressionTests {
 
     private static let script = #"""
-    import http.server, time
+    import http.server, os, time
     class Handler(http.server.BaseHTTPRequestHandler):
         protocol_version = "HTTP/1.1"
         def log_message(self, *args): pass
         def do_GET(self):
-            if self.path == "/slow.ass":
-                time.sleep(2)
+            if self.path == "/held.ass":
+                deadline = time.time() + 60
+                while not os.path.exists("release") and time.time() < deadline:
+                    time.sleep(0.05)
                 body = open("sub.ass", "rb").read()
                 self.send_response(200)
                 self.send_header("Content-Type", "text/x-ssa")
@@ -159,13 +161,13 @@ struct InjectedASSRenditionSuppressionTests {
     @Test("The hidden rendition waits for its extraction, and Off takes it down at once")
     func hiddenRenditionWaitsForExtraction() async throws {
         let origin = try #require(await PythonOrigin.launch(
-            prefix: "aether-ass-slow", script: Self.script, files: ["sub.ass": Self.assScript]))
+            prefix: "aether-ass-held", script: Self.script, files: ["sub.ass": Self.assScript]))
         defer { origin.stop() }
         let engine = try AetherEngine()
         defer { engine.stop(finalTeardown: true) }
         engine.hiddenRenditionIgnoresPlaybackForTesting = true
         let master = try #require(URL(string: "http://127.0.0.1:\(origin.port)/master.m3u8"))
-        let sidecar = try #require(URL(string: "http://127.0.0.1:\(origin.port)/slow.ass"))
+        let sidecar = try #require(URL(string: "http://127.0.0.1:\(origin.port)/held.ass"))
         _ = try await engine.load(url: master, options: LoadOptions(
             nativeRemoteHLS: true, preserveASSMarkup: true,
             externalSubtitles: [ExternalSubtitleTrack(url: sidecar, name: "Styled ASS")], autoplay: false))
@@ -175,11 +177,14 @@ struct InjectedASSRenditionSuppressionTests {
         let group = try #require(try await item.asset.loadMediaSelectionGroup(for: .legible))
         let provider = try #require(engine.remoteHLSSubtitleProxy?.provider)
 
+        // The origin holds the sidecar until the test lets it go, so the extraction is still running.
         engine.selectSubtitleTrack(index: id)
         try await Task.sleep(for: .milliseconds(800))
-        #expect(!provider.isFillFinished, "the origin holds the sidecar for two seconds")
+        try #require(!provider.isFillFinished)
         #expect(Self.selectedName(item, in: group) == nil)
 
+        FileManager.default.createFile(
+            atPath: origin.workDir.appendingPathComponent("release").path, contents: Data())
         try await waitFor { provider.isFillFinished }
         try await waitFor { Self.selectedName(item, in: group) == name && Self.suppressed(item) }
 

From 1fda333afa16369a09189a87d655c103ea87ad3d Mon Sep 17 00:00:00 2001
From: Quick104 <31828688+Quick104@users.noreply.github.com>
Date: Wed, 7 Oct 2026 17:14:22 -0400
Subject: [PATCH 342/359] fix(subtitles): a stale origin-rendition pick leaves
 a newer selection alone

selectRemoteHLSSubtitleTrack loads the legible group in an unstructured task
and then selects the origin's rendition and drops the hidden ASS
suppression. A pick made while the group loaded, such as a styled ASS track,
could have its suppression removed and the origin's rendition drawn over the
overlay. The task now re-checks the item and the active track after the
await, as the injected-rendition task already does. Reported by Kody on #16.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 Sources/AetherEngine/AetherEngine+Subtitles.swift | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/Sources/AetherEngine/AetherEngine+Subtitles.swift b/Sources/AetherEngine/AetherEngine+Subtitles.swift
index e98727893..9c2b22841 100644
--- a/Sources/AetherEngine/AetherEngine+Subtitles.swift
+++ b/Sources/AetherEngine/AetherEngine+Subtitles.swift
@@ -2861,8 +2861,12 @@ extension AetherEngine {
         isLoadingSubtitles = false
         Task { @MainActor in
             self.currentAVPlayer?.appliesMediaSelectionCriteriaAutomatically = false
+            // A pick made while the group loaded owns the selection, and may be a hidden ASS
+            // rendition whose suppression this must not take down.
             guard let group = try? await item.asset.loadMediaSelectionGroup(for: .legible),
-                  ordinal < group.options.count else { return }
+                  ordinal < group.options.count,
+                  self.currentAVPlayer?.currentItem === item,
+                  self.activeSubtitleTrackIndex == id else { return }
             // The origin's own rendition is AVPlayer's to draw.
             self.releaseInjectedRenditionSuppression()
             self.injectedRenditionSelection = nil

From 9c50e0d6811ec23c40a8315d29e43963eb9f0239 Mon Sep 17 00:00:00 2001
From: Quick104 <31828688+Quick104@users.noreply.github.com>
Date: Wed, 7 Oct 2026 21:59:36 -0400
Subject: [PATCH 343/359] fix(network): refuse a non-positive Content-Range
 total before subtracting from it

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 Sources/AetherEngine/Demuxer/AVIOReader.swift |  6 +++++-
 .../Issue281ColdStartRoundTripTests.swift     | 20 +++++++++++++++++++
 2 files changed, 25 insertions(+), 1 deletion(-)

diff --git a/Sources/AetherEngine/Demuxer/AVIOReader.swift b/Sources/AetherEngine/Demuxer/AVIOReader.swift
index ea837a9a7..45f5e80a9 100644
--- a/Sources/AetherEngine/Demuxer/AVIOReader.swift
+++ b/Sources/AetherEngine/Demuxer/AVIOReader.swift
@@ -3004,12 +3004,16 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
     /// Audit DMX-8: a suffix is the END of the source, so the span has to end on the byte before a
     /// numeric total. Without that, `bytes <2^63-65536>-<Int64.max>/*` installed a span whose `end`
     /// overflows on the first read that reaches it.
+    ///
+    /// The total has to be positive before `total - 1` is taken: `Int64` parses a signed string, so
+    /// `bytes 0-0/-9223372036854775808` reached the subtraction with `Int64.min` and trapped.
     static func suffixRangeStart(_ http: HTTPURLResponse, expectedLength: Int) -> Int64? {
         guard let value = http.value(forHTTPHeaderField: "Content-Range") else { return nil }
         let scanner = value.replacingOccurrences(of: "bytes ", with: "")
         let parts = scanner.split(separator: "/", maxSplits: 1)
         guard parts.count == 2,
-              let total = Int64(parts[1].trimmingCharacters(in: .whitespaces)) else { return nil }
+              let total = Int64(parts[1].trimmingCharacters(in: .whitespaces)),
+              total > 0 else { return nil }
         let bounds = parts[0].split(separator: "-", maxSplits: 1)
         guard bounds.count == 2,
               let start = Int64(bounds[0].trimmingCharacters(in: .whitespaces)),
diff --git a/Tests/AetherEngineTests/Issue281ColdStartRoundTripTests.swift b/Tests/AetherEngineTests/Issue281ColdStartRoundTripTests.swift
index 44d5c677a..76f1b29ad 100644
--- a/Tests/AetherEngineTests/Issue281ColdStartRoundTripTests.swift
+++ b/Tests/AetherEngineTests/Issue281ColdStartRoundTripTests.swift
@@ -403,6 +403,26 @@ struct Issue281ColdStartRoundTripTests {
             expectedLength: 100) == nil)
     }
 
+    /// `Int64` parses a sign, so a total of `Int64.min` reached `total - 1` and trapped the process
+    /// from a single response header.
+    @Test("a suffix 206 with a total that is not positive is refused, not trapped on")
+    func suffixStartRefusesANonPositiveTotal() {
+        let url = URL(string: "http://example.invalid/movie.bin")!
+        func response(_ contentRange: String) -> HTTPURLResponse {
+            HTTPURLResponse(url: url, statusCode: 206, httpVersion: "HTTP/1.1",
+                            headerFields: ["Content-Range": contentRange])!
+        }
+
+        #expect(AVIOReader.suffixRangeStart(response("bytes 0-0/-9223372036854775808"),
+                                            expectedLength: 1) == nil)
+        #expect(AVIOReader.suffixRangeStart(response("bytes 0-0/-1"), expectedLength: 1) == nil)
+        #expect(AVIOReader.suffixRangeStart(response("bytes 0-0/0"), expectedLength: 1) == nil)
+        #expect(AVIOReader.suffixRangeStart(response("bytes 0-0/1"), expectedLength: 1) == 0)
+        #expect(AVIOReader.suffixRangeStart(
+            response("bytes 9223372036854775707-9223372036854775806/9223372036854775807"),
+            expectedLength: 100) == 9223372036854775707)
+    }
+
     /// The calibration the in-flight test above no longer carries, checked where it costs no socket
     /// and no wall clock: two measured round trips, floored so a cache-warm first connection still
     /// buys a wait, capped so a hung fetch cannot own the open.

From d261d7472028962a679d938829ef015811f81c7e Mon Sep 17 00:00:00 2001
From: Quick104 <31828688+Quick104@users.noreply.github.com>
Date: Wed, 7 Oct 2026 21:59:36 -0400
Subject: [PATCH 344/359] fix(logging): redact Xtream passwords holding , ' or
 ) and values behind a registered name

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .../Diagnostics/LogRedaction.swift            | 34 ++++++++++++++-----
 .../AetherEngineTests/LogRedactionTests.swift | 33 ++++++++++++++++++
 2 files changed, 58 insertions(+), 9 deletions(-)

diff --git a/Sources/AetherEngine/Diagnostics/LogRedaction.swift b/Sources/AetherEngine/Diagnostics/LogRedaction.swift
index dfb1ea3d1..469d491d0 100644
--- a/Sources/AetherEngine/Diagnostics/LogRedaction.swift
+++ b/Sources/AetherEngine/Diagnostics/LogRedaction.swift
@@ -140,15 +140,26 @@ enum LogRedaction {
     private static func match(in bytes: [UInt8], at index: Int, secrets: [[UInt8]], keys: Bool)
         -> Range<Int>?
     {
-        if let secret = registeredSecretRange(in: bytes, at: index, secrets: secrets) { return secret }
-        if keys, let value = matchedKeyLength(in: bytes, at: index)
-            .flatMap({ valueRange(in: bytes, keyStart: index, keyEnd: index + $0) }) {
-            return value
-        }
-        return authorizationSchemeRange(in: bytes, at: index)
+        let keyed = keys ? matchedKeyLength(in: bytes, at: index)
+            .flatMap({ valueRange(in: bytes, keyStart: index, keyEnd: index + $0) }) : nil
+        guard var span = keyed
+            ?? authorizationSchemeRange(in: bytes, at: index)
             ?? encodedPayloadRange(in: bytes, at: index)
             ?? userInfoSecretRange(in: bytes, at: index)
-            ?? xtreamPathSecretRange(in: bytes, at: index)
+            ?? xtreamPathSecretRange(in: bytes, at: index) else {
+            return registeredSecretRange(in: bytes, at: index, secrets: secrets)
+        }
+        // The scan resumes past the span, so a registered secret starting before its end goes unseen
+        // unless it is folded in, and returning that secret alone hides the value instead (`token`
+        // registered, `token=abc` logged). One span covers both.
+        var k = index
+        while !secrets.isEmpty, k < span.upperBound {
+            if let secret = registeredSecretRange(in: bytes, at: k, secrets: secrets) {
+                span = min(span.lowerBound, k) ..< max(span.upperBound, secret.upperBound)
+            }
+            k += 1
+        }
+        return span
     }
 
     /// Every logical character of a line once, escapes followed through `%25` layers by
@@ -497,10 +508,15 @@ enum LogRedaction {
     }
 
     /// Ends a URL path: the query, the fragment, or whatever the log line puts after the URL.
+    ///
+    /// `'` `,` and `)` are absent: they are legal raw in a path segment and a password holds them, so
+    /// `/live/u/pa,ss/1.ts` read as too few segments and kept its password. Where prose puts one after
+    /// the URL it lands in the last segment, which the layout never redacts, and the blank after it
+    /// still ends the path.
     private static func isPathTerminator(_ b: UInt8) -> Bool {
         switch b {
-        case UInt8(ascii: "?"), UInt8(ascii: "#"), UInt8(ascii: "\""), UInt8(ascii: "'"),
-             UInt8(ascii: ","), UInt8(ascii: ")"), UInt8(ascii: ">"), UInt8(ascii: " "), 0x09, 0x0A, 0x0D:
+        case UInt8(ascii: "?"), UInt8(ascii: "#"), UInt8(ascii: "\""), UInt8(ascii: ">"),
+             UInt8(ascii: " "), 0x09, 0x0A, 0x0D:
             return true
         default:
             return false
diff --git a/Tests/AetherEngineTests/LogRedactionTests.swift b/Tests/AetherEngineTests/LogRedactionTests.swift
index 5f370172d..b59eb5134 100644
--- a/Tests/AetherEngineTests/LogRedactionTests.swift
+++ b/Tests/AetherEngineTests/LogRedactionTests.swift
@@ -194,6 +194,21 @@ struct LogRedactionTests {
         #expect(LogRedaction.redact("[x] url=\(url) ok") == "[x] url=\(url) ok")
     }
 
+    /// `'` `,` and `)` are legal raw in a URL path, so a password holding one read as too few segments
+    /// for the layout and went out whole. The same mark after the URL is prose and still ends it.
+    @Test("an Xtream password holding ' , or ) goes whole, and the mark after the URL stays prose",
+          arguments: ["'", ",", ")"])
+    func xtreamPasswordWithPathPunctuation(mark: String) {
+        #expect(LogRedaction.redact("[x] url=http://h:8080/live/john/pa\(mark)ss/12345.ts ok")
+                == "[x] url=http://h:8080/live/john/<redacted>/12345.ts ok")
+        #expect(LogRedaction.redact("[x] url=http://h:8080/hlsr/a1b2\(mark)c3/john/pa\(mark)ss/12345/1/7.ts ok")
+                == "[x] url=http://h:8080/hlsr/<redacted>/12345/1/7.ts ok")
+        #expect(LogRedaction.redact("[x] (http://h:8080/live/john/S3cretPass/12345.ts\(mark)) retrying")
+                == "[x] (http://h:8080/live/john/<redacted>/12345.ts\(mark)) retrying")
+        let ordinary = "[x] (see https://origin.example/live/channel1/index.m3u8\(mark)), ok"
+        #expect(LogRedaction.redact(ordinary) == ordinary)
+    }
+
     @Test("a URL logged percent-encoded inside another URL's query loses its token (audit NET-1)")
     func percentEncodedNestedURL() {
         // The exact shape the pre-NET-1 origin relay logged on every request.
@@ -268,6 +283,24 @@ struct LogRedactionTests {
         #expect(LogRedaction.redact("[x] v=\(secret)x") == "[x] v=\(secret)x")
     }
 
+    /// A registered literal that is also a credential name hid the value behind it, because the scan
+    /// resumed past the literal; the value's span must not hide a registered literal either.
+    /// `passwd` rather than `token`: the registry is process-global and parallel suites log `token`.
+    @Test("a registered secret and a named credential value both go where they meet")
+    func registeredSecretMeetsACredentialName() {
+        #expect(EngineLog.registerSecret("passwd"))
+        #expect(EngineLog.registerSecret("w0rd tail"))
+        defer {
+            EngineLog.unregisterSecret("passwd")
+            EngineLog.unregisterSecret("w0rd tail")
+        }
+        #expect(LogRedaction.redact("[x] passwd=abcdef123456&keep=1") == "[x] <redacted>&keep=1")
+        #expect(LogRedaction.redact("[x] password=w0rd tail ok") == "[x] password=<redacted> ok")
+        // An escape anywhere in the line takes the decoded-view pass instead of the streaming one.
+        #expect(LogRedaction.redact("[x] %20 passwd=abcdef123456&keep=1") == "[x] %20 <redacted>&keep=1")
+        #expect(LogRedaction.redact("[x] passwd alone") == "[x] <redacted> alone")
+    }
+
     // MARK: - Nameless shapes inside a percent-encoded URL (audit SUB-104)
 
     /// An IPTV proxy or a debrid wrapper carries the upstream URL percent-encoded in its own query.

From 4ec5ac92cf4e584028833198c6b390190233c5a3 Mon Sep 17 00:00:00 2001
From: Quick104 <31828688+Quick104@users.noreply.github.com>
Date: Wed, 7 Oct 2026 21:59:36 -0400
Subject: [PATCH 345/359] fix(audio): park the audio-only clock when it reaches
 the last sample, at any rate

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .../Audio/AudioPlaybackHost.swift             | 19 +++--
 .../Native/SoftwareEndOfMediaClock.swift      | 12 ++++
 ...Issue694AudioHostEndOfMediaParkTests.swift | 72 ++++++++++++++++++-
 3 files changed, 98 insertions(+), 5 deletions(-)

diff --git a/Sources/AetherEngine/Audio/AudioPlaybackHost.swift b/Sources/AetherEngine/Audio/AudioPlaybackHost.swift
index c07adeb47..d804ecd9d 100644
--- a/Sources/AetherEngine/Audio/AudioPlaybackHost.swift
+++ b/Sources/AetherEngine/Audio/AudioPlaybackHost.swift
@@ -620,16 +620,27 @@ final class AudioPlaybackHost {
         guard !didParkClockAtEnd else { return }
         didParkClockAtEnd = true
         guard clockArmed, let aOut = audioOutput else { return }
+        let clock = aOut.currentTimeSeconds
         let tail = SoftwareEndOfMediaClock.tailPlayoutSeconds(
-            clockSeconds: aOut.currentTimeSeconds,
+            clockSeconds: clock,
             lastAudioPts: lastEnqueuedEnd
         )
         guard tail > 0 else { return parkClockNow(notAfter: lastEnqueuedEnd) }
+        // The tail is source time: below 1x, or across a pause, it outlasts as many wall seconds, so
+        // the park waits for the clock to get there. `target` keeps the clamp on a broken PTS.
+        let target = clock + tail
         let generation = seekGeneration
         Task { @MainActor [weak self] in
-            try? await Task.sleep(nanoseconds: UInt64(tail * 1_000_000_000))
-            guard let self, self.seekGeneration == generation, self.didParkClockAtEnd else { return }
-            self.parkClockNow(notAfter: lastEnqueuedEnd)
+            var wait = tail
+            while true {
+                try? await Task.sleep(nanoseconds: UInt64(wait * 1_000_000_000))
+                guard let self, self.seekGeneration == generation, self.didParkClockAtEnd,
+                      let aOut = self.audioOutput else { return }
+                guard let next = SoftwareEndOfMediaClock.parkWaitSeconds(
+                    clockSeconds: aOut.currentTimeSeconds, rate: aOut.rate, target: target
+                ) else { return self.parkClockNow(notAfter: lastEnqueuedEnd) }
+                wait = next
+            }
         }
     }
 
diff --git a/Sources/AetherEngine/Native/SoftwareEndOfMediaClock.swift b/Sources/AetherEngine/Native/SoftwareEndOfMediaClock.swift
index bb0b1670f..7ac1a6f4f 100644
--- a/Sources/AetherEngine/Native/SoftwareEndOfMediaClock.swift
+++ b/Sources/AetherEngine/Native/SoftwareEndOfMediaClock.swift
@@ -33,4 +33,16 @@ enum SoftwareEndOfMediaClock {
         guard clockSeconds.isFinite, latest.isFinite, clockSeconds > latest else { return nil }
         return latest
     }
+
+    /// How often a deferred park re-reads a clock that is not running (paused during the tail).
+    static let stoppedClockPollSeconds: TimeInterval = 0.1
+
+    /// Wall seconds before a deferred park looks again, nil once the clock has reached `target` or
+    /// either value is unusable. The tail is source time, so it plays out over `remaining / rate`
+    /// wall seconds; a stopped clock is polled, since parking it where it stands cuts the tail.
+    static func parkWaitSeconds(clockSeconds: Double, rate: Float, target: Double) -> TimeInterval? {
+        guard clockSeconds.isFinite, target.isFinite, clockSeconds < target else { return nil }
+        guard rate > 0 else { return stoppedClockPollSeconds }
+        return (target - clockSeconds) / Double(rate)
+    }
 }
diff --git a/Tests/AetherEngineTests/Issue694AudioHostEndOfMediaParkTests.swift b/Tests/AetherEngineTests/Issue694AudioHostEndOfMediaParkTests.swift
index d73d833df..6eb88c7f4 100644
--- a/Tests/AetherEngineTests/Issue694AudioHostEndOfMediaParkTests.swift
+++ b/Tests/AetherEngineTests/Issue694AudioHostEndOfMediaParkTests.swift
@@ -5,7 +5,7 @@ import Foundation
 /// #694: the audio-only host reported end of media while its synchronizer kept rate 1, so
 /// `currentTime` walked past `duration` without bound. AE#374 closed the same defect on the software
 /// host; this pins it on the audio-only one, end to end against a real decode.
-@Suite("Audio host parks its clock at end of media (#694)")
+@Suite("Audio host parks its clock at end of media (#694)", .serialized)
 struct Issue694AudioHostEndOfMediaParkTests {
 
     @MainActor
@@ -49,6 +49,76 @@ struct Issue694AudioHostEndOfMediaParkTests {
         #expect(SoftwareEndOfMediaClock.parkSeconds(clockSeconds: .nan, notAfter: 1.0) == nil)
     }
 
+    @Test("the deferred park waits out the tail in source time, and polls a stopped clock")
+    func parkWaitIsSourceTime() {
+        // 0.25 s of tail at 0.5x is half a second of wall time, not a quarter.
+        #expect(SoftwareEndOfMediaClock.parkWaitSeconds(clockSeconds: 0.75, rate: 0.5, target: 1.0) == 0.5)
+        #expect(SoftwareEndOfMediaClock.parkWaitSeconds(clockSeconds: 0.75, rate: 1, target: 1.0) == 0.25)
+        #expect(SoftwareEndOfMediaClock.parkWaitSeconds(clockSeconds: 0.75, rate: 0, target: 1.0)
+                == SoftwareEndOfMediaClock.stoppedClockPollSeconds)
+        #expect(SoftwareEndOfMediaClock.parkWaitSeconds(clockSeconds: 1.0, rate: 0.5, target: 1.0) == nil)
+        #expect(SoftwareEndOfMediaClock.parkWaitSeconds(clockSeconds: .nan, rate: 1, target: 1.0) == nil)
+    }
+
+    @MainActor
+    @Test("below 1x the clock still parks on the last sample, not short of it")
+    func halfSpeedParksOnTheLastSample() async throws {
+        let host = AudioPlaybackHost()
+        let demuxer = Demuxer()
+        try demuxer.open(reader: DataIOReader(data: makeWAV(seconds: 1)))
+        try await host.load(demuxer: demuxer, startPosition: nil, audioSourceStreamIndex: nil)
+        defer { host.stop() }
+        host.setResumeRate(0.5)
+        host.play()
+
+        try await waitForParkedClock(host, within: 8)
+        let first = try #require(host.clockSecondsForTesting)
+        // Parked on wall time, the clock stopped about 0.11 s short of the end at 0.5x.
+        #expect(abs(first - 1.0) < 0.02)
+    }
+
+    @MainActor
+    @Test("a pause during the tail holds the park until the clock reaches the last sample")
+    func pauseDuringTheTailDefersThePark() async throws {
+        let host = AudioPlaybackHost()
+        let demuxer = Demuxer()
+        try demuxer.open(reader: DataIOReader(data: makeWAV(seconds: 1)))
+        try await host.load(demuxer: demuxer, startPosition: nil, audioSourceStreamIndex: nil)
+        defer { host.stop() }
+        host.play()
+
+        let deadline = Date().addingTimeInterval(8)
+        while !host.didReachEnd, Date() < deadline {
+            try await Task.sleep(nanoseconds: 10_000_000)
+        }
+        #expect(host.didReachEnd)
+        // The playthrough wait releases up to 0.25 s before the end; pause inside that tail and
+        // hold the pause past it.
+        host.pause()
+        try await Task.sleep(nanoseconds: 400_000_000)
+        host.play()
+
+        // A park that fired during the pause left nothing to stop the resumed clock.
+        try await waitForParkedClock(host, within: 2)
+        let first = try #require(host.clockSecondsForTesting)
+        #expect(abs(first - 1.0) < 0.02)
+    }
+
+    @MainActor
+    private func waitForParkedClock(_ host: AudioPlaybackHost, within seconds: TimeInterval) async throws {
+        let deadline = Date().addingTimeInterval(seconds)
+        while !(host.didReachEnd && host.clockRateForTesting == 0), Date() < deadline {
+            try await Task.sleep(nanoseconds: 20_000_000)
+        }
+        #expect(host.didReachEnd)
+        #expect(host.clockRateForTesting == 0)
+        #expect(host.rate == 0)
+        let first = try #require(host.clockSecondsForTesting)
+        try await Task.sleep(nanoseconds: 300_000_000)
+        let second = try #require(host.clockSecondsForTesting)
+        #expect(abs(second - first) < 0.01)
+    }
+
     private func makeWAV(seconds: Double) -> Data {
         let sampleRate = 48_000, channels = 2
         let pcm = Data(count: Int(Double(sampleRate) * seconds) * channels * 2)

From 8fc0a12f14f2aa1ce4387572fcf07a1c2a8a186d Mon Sep 17 00:00:00 2001
From: Quick104 <31828688+Quick104@users.noreply.github.com>
Date: Wed, 7 Oct 2026 21:59:36 -0400
Subject: [PATCH 346/359] fix(live): check a delayed revive again when its
 restart is admitted

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .../Video/HLSVideoEngine+LiveReopen.swift     |  2 +-
 .../AetherEngine/Video/HLSVideoEngine.swift   | 18 ++++++++-
 .../SupersededProducerReportTests.swift       | 37 +++++++++++++++++++
 3 files changed, 55 insertions(+), 2 deletions(-)

diff --git a/Sources/AetherEngine/Video/HLSVideoEngine+LiveReopen.swift b/Sources/AetherEngine/Video/HLSVideoEngine+LiveReopen.swift
index c8ed5580b..3bbb10274 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine+LiveReopen.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine+LiveReopen.swift
@@ -543,7 +543,7 @@ extension HLSVideoEngine {
                 category: .session)
             return
         }
-        requestRestart(at: idx, authoritative: true)
+        requestRestart(at: idx, authoritative: true, reviving: (deadProducer, sessionEpoch))
     }
 
     /// #377: how long a refusal keeps classifying a read error as metering. The reader's give-up
diff --git a/Sources/AetherEngine/Video/HLSVideoEngine.swift b/Sources/AetherEngine/Video/HLSVideoEngine.swift
index 86347e740..84c126870 100644
--- a/Sources/AetherEngine/Video/HLSVideoEngine.swift
+++ b/Sources/AetherEngine/Video/HLSVideoEngine.swift
@@ -4039,7 +4039,12 @@ public final class HLSVideoEngine: @unchecked Sendable {
         restartLock.unlock()
     }
 
-    func requestRestart(at idx: Int, authoritative: Bool = false) {
+    /// `reviving` names the dead producer and session a delayed revive was scheduled for (audit
+    /// HLS-104). They are checked again in the same `restartLock` hold as the admission: a seek
+    /// restart that began after the caller's own check would otherwise get the stale target queued
+    /// behind it. A restart already in flight is about to replace the dead producer, so it counts.
+    func requestRestart(at idx: Int, authoritative: Bool = false,
+                        reviving revive: (deadProducer: HLSSegmentProducer?, sessionEpoch: UInt64)? = nil) {
         // A sequential origin has no restart. performRestart's demuxer seek has nowhere to land
         // on a non-seekable pb, and it ignores that failure: the new producer would keep reading
         // wherever the stream stands (or from byte 0 after a fresh reopen) and label those bytes
@@ -4056,6 +4061,17 @@ public final class HLSVideoEngine: @unchecked Sendable {
             return
         }
         restartLock.lock()
+        if let revive, !Self.meteredReviveStillOwed(
+            sessionUnchanged: sessionEpoch == revive.sessionEpoch,
+            deadProducerInstalled: producer === revive.deadProducer && !restartCoalescer.isInFlight) {
+            restartLock.unlock()
+            EngineLog.emit(
+                "[HLSVideoEngine] revive at idx=\(idx) dropped at admission: a restart began or the "
+                + "dead producer was replaced after it was scheduled",
+                category: .session
+            )
+            return
+        }
         let shouldRun = restartCoalescer.begin(idx, authoritative: authoritative)
         let seekTime = segmentStartSecondsLocked(idx) // under lock; segmentPlan guarded by restartLock (#38)
         restartLock.unlock()
diff --git a/Tests/AetherEngineTests/SupersededProducerReportTests.swift b/Tests/AetherEngineTests/SupersededProducerReportTests.swift
index 8abe27041..982880e6c 100644
--- a/Tests/AetherEngineTests/SupersededProducerReportTests.swift
+++ b/Tests/AetherEngineTests/SupersededProducerReportTests.swift
@@ -177,4 +177,41 @@ struct SupersededProducerReportTests {
         engine.fireMeteredRevive(at: 2, deadProducer: dead, sessionEpoch: epoch)
         #expect(restarts.began == 1)
     }
+
+    @Test("a revive that wakes as a seek restart starts does not queue its stale target behind it",
+          .timeLimit(.minutes(1)))
+    func meteredReviveYieldsToAStartingRestart() async throws {
+        let session = try Session()
+        let engine = session.engine
+        let restarts = Restarts()
+        let dead = try engine.makeProducer(baseIndex: 2)
+        engine.producer = dead
+        dead.start()
+        try await waitFor { dead.didFinish }
+        let epoch = engine.sessionEpochSnapshot()
+
+        // The seek restart is admitted and held before it takes the dead producer out, so the
+        // revive's own producer and session checks still pass.
+        let admitted = DispatchSemaphore(value: 0)
+        let proceed = DispatchSemaphore(value: 0)
+        engine.onSeekStateChanged = { began, _ in
+            restarts.note(began)
+            if began, restarts.began == 1 {
+                admitted.signal()
+                proceed.wait()
+            }
+        }
+        let began: Int = await withCheckedContinuation { continuation in
+            DispatchQueue.global().async {
+                let seek = DispatchGroup()
+                DispatchQueue.global().async(group: seek) { engine.requestRestart(at: 6) }
+                admitted.wait()
+                engine.fireMeteredRevive(at: 2, deadProducer: dead, sessionEpoch: epoch)
+                proceed.signal()
+                seek.wait()
+                continuation.resume(returning: restarts.began)
+            }
+        }
+        #expect(began == 1, "the revive's stale target ran after the seek restart")
+    }
 }

From 3e2e4a16005c5f69d6dd10ee2cd1c5e023a7c023 Mon Sep 17 00:00:00 2001
From: Quick104 <31828688+Quick104@users.noreply.github.com>
Date: Wed, 7 Oct 2026 21:59:37 -0400
Subject: [PATCH 347/359] fix(cache): keep the I-frame cache under its cap and
 release the ring's tail on close

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .../Video/IFramePayloadCache.swift            |  4 +-
 .../AetherEngine/Video/PacketRingBuffer.swift |  7 ++
 .../IFramePayloadCacheTests.swift             | 13 ++-
 .../IFrameRenditionTests.swift                | 14 ++-
 .../PacketRingBufferChunkSpoolTests.swift     | 91 +++++++++++++++++++
 5 files changed, 123 insertions(+), 6 deletions(-)

diff --git a/Sources/AetherEngine/Video/IFramePayloadCache.swift b/Sources/AetherEngine/Video/IFramePayloadCache.swift
index 71a230ad7..b5cdd02be 100644
--- a/Sources/AetherEngine/Video/IFramePayloadCache.swift
+++ b/Sources/AetherEngine/Video/IFramePayloadCache.swift
@@ -41,7 +41,9 @@ final class IFramePayloadCache: @unchecked Sendable {
     }
 
     func store(_ data: Data, for index: Int) {
-        guard !data.isEmpty else { return }
+        // Eviction never takes the entry it makes room for, so one larger than the cap would stay
+        // over it. The caller serves such a payload uncached.
+        guard !data.isEmpty, data.count <= byteLimit else { return }
         lock.lock(); defer { lock.unlock() }
         forgetLocked(index)
         do {
diff --git a/Sources/AetherEngine/Video/PacketRingBuffer.swift b/Sources/AetherEngine/Video/PacketRingBuffer.swift
index 1d752d3e3..89946d7bd 100644
--- a/Sources/AetherEngine/Video/PacketRingBuffer.swift
+++ b/Sources/AetherEngine/Video/PacketRingBuffer.swift
@@ -153,6 +153,13 @@ final class PacketRingBuffer: @unchecked Sendable {
         markerFD = -1
         lock.unlock()
 
+        // The writer's chunk would otherwise stay open, blocks and all, until the next append. An
+        // append in flight is waited out here, after the index is cleared, so readers never wait on it.
+        writeLock.lock()
+        tail = nil
+        tailOffset = 0
+        writeLock.unlock()
+
         DispatchQueue.global(qos: .userInitiated).async { [scratch] in
             try? FileManager.default.removeItem(at: scratch)
             // Released after the removal, so the directory reads live until it is gone.
diff --git a/Tests/AetherEngineTests/IFramePayloadCacheTests.swift b/Tests/AetherEngineTests/IFramePayloadCacheTests.swift
index 06aeac336..62bed54ad 100644
--- a/Tests/AetherEngineTests/IFramePayloadCacheTests.swift
+++ b/Tests/AetherEngineTests/IFramePayloadCacheTests.swift
@@ -32,13 +32,20 @@ struct IFramePayloadCacheTests {
         #expect(cache.payload(for: 2) != nil)
     }
 
-    @Test("a payload larger than the cap is kept alone rather than evicted into a miss")
-    func oversizedPayloadIsKeptAlone() throws {
+    @Test("a payload larger than the cap is not kept and evicts nothing; one exactly at the cap is kept")
+    func oversizedPayloadIsNotKept() throws {
         let (cache, dir) = try makeCache(limit: 100)
         defer { try? FileManager.default.removeItem(at: dir) }
         cache.store(Data(count: 60), for: 0)
         cache.store(Data(count: 500), for: 1)
-        #expect(cache.payload(for: 1)?.count == 500)
+        #expect(cache.payload(for: 1) == nil)
+        #expect(cache.payload(for: 0)?.count == 60)
+        #expect(cache.nearestIndex(to: 1) == 0)
+        let files = try FileManager.default.contentsOfDirectory(atPath: dir.path)
+        #expect(files == ["payload-0.bin"], "the oversized payload left a file over the cap")
+
+        cache.store(Data(count: 100), for: 2)
+        #expect(cache.payload(for: 2)?.count == 100)
         #expect(cache.payload(for: 0) == nil)
     }
 
diff --git a/Tests/AetherEngineTests/IFrameRenditionTests.swift b/Tests/AetherEngineTests/IFrameRenditionTests.swift
index f9a7559a5..127218d11 100644
--- a/Tests/AetherEngineTests/IFrameRenditionTests.swift
+++ b/Tests/AetherEngineTests/IFrameRenditionTests.swift
@@ -28,7 +28,7 @@ private final class Recorder: @unchecked Sendable {
 }
 
 struct IFrameRenditionTests {
-    private func make(_ rec: Recorder, count: Int = 5) -> (IFrameRendition, URL) {
+    private func make(_ rec: Recorder, count: Int = 5, cacheLimit: Int = 1 << 20) -> (IFrameRendition, URL) {
         let dir = FileManager.default.temporaryDirectory
             .appendingPathComponent("iframe-rendition-\(UUID().uuidString)", isDirectory: true)
         let entries = (0..<count).map {
@@ -36,7 +36,7 @@ struct IFrameRenditionTests {
         }
         let rendition = IFrameRendition(
             entries: entries,
-            cache: IFramePayloadCache(directory: dir, byteLimit: 1 << 20),
+            cache: IFramePayloadCache(directory: dir, byteLimit: cacheLimit),
             readPayload: rec.read,
             buildFragment: { payload, index, entry in
                 // The fragment names the payload it was built from and the time it was stamped with.
@@ -86,6 +86,16 @@ struct IFrameRenditionTests {
         #expect(r.fragment(at: 3) == Data("key1000@3:12.0".utf8))
     }
 
+    @Test("a keyframe larger than the cache's cap is served from the read and read again next time")
+    func oversizedPayloadIsServedUncached() {
+        let rec = Recorder()
+        // "key2000" is 7 bytes.
+        let (r, dir) = make(rec, cacheLimit: 4); defer { r.shutdown(); try? FileManager.default.removeItem(at: dir) }
+        #expect(r.fragment(at: 2) == Data("key2000@2:8.0".utf8))
+        #expect(r.fragment(at: 2) == Data("key2000@2:8.0".utf8))
+        #expect(rec.reads == [2000, 2000])
+    }
+
     @Test("a failed read with nothing cached is nil")
     func nothingToSubstitute() {
         let rec = Recorder()
diff --git a/Tests/AetherEngineTests/PacketRingBufferChunkSpoolTests.swift b/Tests/AetherEngineTests/PacketRingBufferChunkSpoolTests.swift
index 96ef5fae0..6b7ded536 100644
--- a/Tests/AetherEngineTests/PacketRingBufferChunkSpoolTests.swift
+++ b/Tests/AetherEngineTests/PacketRingBufferChunkSpoolTests.swift
@@ -424,6 +424,97 @@ struct PacketRingBufferChunkSpoolTests {
         #expect(ring.packet(atSeq: 0) == nil)
         #expect(ring.packet(atSeq: 59)?.bytes.count == 30 << 10)
     }
+
+    // MARK: - Teardown
+
+    /// Which file a descriptor refers to, or nil once it is closed. A closed number that something
+    /// else reopened reads as a different file, so this cannot mistake reuse for the chunk.
+    private struct OpenFile: Equatable {
+        let device: dev_t
+        let inode: ino_t
+        init?(_ fd: Int32) {
+            var info = stat()
+            guard fstat(fd, &info) == 0 else { return nil }
+            device = info.st_dev
+            inode = info.st_ino
+        }
+    }
+
+    /// Records the descriptor the writer writes through, and can park one write until released.
+    private final class WriteSpy: @unchecked Sendable {
+        private let lock = NSLock()
+        private var _fd: Int32?
+        private var parkWith: Int32?
+        private var _parked = false
+        private let gate = DispatchSemaphore(value: 0)
+        var fd: Int32? { lock.lock(); defer { lock.unlock() }; return _fd }
+        var parked: Bool { lock.lock(); defer { lock.unlock() }; return _parked }
+        /// The next write waits for `release()`, then fails with `code`.
+        func parkNextWrite(failingWith code: Int32) { lock.lock(); parkWith = code; lock.unlock() }
+        func release() { gate.signal() }
+
+        var writer: PacketRingBuffer.WriteAll {
+            { [self] fd, bytes, offset in
+                lock.lock()
+                _fd = fd
+                let code = parkWith
+                parkWith = nil
+                if code != nil { _parked = true }
+                lock.unlock()
+                if let code {
+                    gate.wait()
+                    throw NSError(domain: NSPOSIXErrorDomain, code: Int(code))
+                }
+                try PacketRingBuffer.pwriteAll(fd, bytes, offset)
+            }
+        }
+    }
+
+    @Test("close() releases the chunk the writer appends to rather than leaving it to the next append")
+    func closeReleasesWriterChunk() throws {
+        let dirs = ScratchDirs()
+        let spy = WriteSpy()
+        let ring = try PacketRingBuffer(windowSeconds: .infinity, scratch: makeScratch(dirs), writeAll: spy.writer)
+        try ring.append(pts: 0, isKeyframe: true, isVideo: true, bytes: Data([1, 2, 3]))
+        let fd = try #require(spy.fd)
+        let chunk = try #require(OpenFile(fd))
+
+        ring.close()
+        #expect(OpenFile(fd) != chunk, "the closed ring still holds its tail chunk open")
+        withExtendedLifetime(ring) {}
+    }
+
+    @Test("close() during an append clears the index at once, then releases the chunk once the append ends",
+          .timeLimit(.minutes(1)))
+    func closeDuringAppendReleasesWriterChunk() async throws {
+        let dirs = ScratchDirs()
+        let spy = WriteSpy()
+        let ring = try PacketRingBuffer(windowSeconds: .infinity, scratch: makeScratch(dirs), writeAll: spy.writer)
+        try ring.append(pts: 0, isKeyframe: true, isVideo: true, bytes: Data([1]))
+        let fd = try #require(spy.fd)
+        let chunk = try #require(OpenFile(fd))
+
+        // An append that fails after close() has begun leaves the tail behind if close() does not
+        // wait it out.
+        spy.parkNextWrite(failingWith: EIO)
+        let appended = Counter()
+        let closed = Counter()
+        Thread {
+            try? ring.append(pts: 1, isKeyframe: false, isVideo: true, bytes: Data([2]))
+            appended.add(1)
+        }.start()
+        try await waitFor { spy.parked }
+        Thread {
+            ring.close()
+            closed.add(1)
+        }.start()
+        try await waitFor { ring.oldestPts == nil }
+        spy.release()
+        try await waitFor { appended.value == 1 && closed.value == 1 }
+
+        #expect(OpenFile(fd) != chunk, "the closed ring still holds its tail chunk open")
+        withExtendedLifetime(ring) {}
+    }
 }
 
 private final class Counter: @unchecked Sendable {

From e63a2d96a965f4e75351ecacdb69bed75bfb0048 Mon Sep 17 00:00:00 2001
From: Quick104 <31828688+Quick104@users.noreply.github.com>
Date: Wed, 7 Oct 2026 21:59:37 -0400
Subject: [PATCH 348/359] perf(subtitles): strip cue markup in one pass

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .../Native/RemoteHLSCueClock.swift            |  13 +-
 .../RemoteHLSCueClockTests.swift              | 114 ++++++++++++++++++
 2 files changed, 124 insertions(+), 3 deletions(-)

diff --git a/Sources/AetherEngine/Native/RemoteHLSCueClock.swift b/Sources/AetherEngine/Native/RemoteHLSCueClock.swift
index af423f917..beae55f62 100644
--- a/Sources/AetherEngine/Native/RemoteHLSCueClock.swift
+++ b/Sources/AetherEngine/Native/RemoteHLSCueClock.swift
@@ -88,10 +88,17 @@ struct RemoteHLSCueClock {
     /// text went through `MovTextSampleBuilder.sanitize`, and AVPlayer drops the WebVTT markup and may
     /// re-break lines.
     static func normalize(_ text: String) -> String {
-        var s = MovTextSampleBuilder.sanitize(text)
-        while let open = s.firstIndex(of: "<"), let close = s[open...].firstIndex(of: ">") {
-            s.removeSubrange(open...close)
+        let sanitized = MovTextSampleBuilder.sanitize(text)
+        // One forward pass: removing a tag at a time and searching again from the start cost tags x
+        // length, seconds for a crafted 64 KiB cue. Once a `<` finds no `>`, no later one can either.
+        // Scanned by Character, as before, so a `<` carrying a combining mark is still text.
+        var s = ""
+        var rest = sanitized[...]
+        while let open = rest.firstIndex(of: "<"), let close = rest[open...].firstIndex(of: ">") {
+            s.append(contentsOf: rest[..<open])
+            rest = rest[rest.index(after: close)...]
         }
+        s.append(contentsOf: rest)
         s = s.replacingOccurrences(of: "&lt;", with: "<")
             .replacingOccurrences(of: "&gt;", with: ">")
             .replacingOccurrences(of: "&nbsp;", with: " ")
diff --git a/Tests/AetherEngineTests/RemoteHLSCueClockTests.swift b/Tests/AetherEngineTests/RemoteHLSCueClockTests.swift
index 5cd5d1224..3505b149b 100644
--- a/Tests/AetherEngineTests/RemoteHLSCueClockTests.swift
+++ b/Tests/AetherEngineTests/RemoteHLSCueClockTests.swift
@@ -113,4 +113,118 @@ struct RemoteHLSCueClockTests {
         _ = c.observe(strings: ["Run."], itemTime: 1803.086)
         #expect(c.isMeasuredSinceJump)
     }
+
+    // MARK: - Markup stripping
+
+    /// The `normalize` that removed one tag at a time, searching again from the start, kept as the oracle.
+    private func legacyNormalize(_ text: String) -> String {
+        var s = MovTextSampleBuilder.sanitize(text)
+        while let open = s.firstIndex(of: "<"), let close = s[open...].firstIndex(of: ">") {
+            s.removeSubrange(open...close)
+        }
+        s = s.replacingOccurrences(of: "&lt;", with: "<")
+            .replacingOccurrences(of: "&gt;", with: ">")
+            .replacingOccurrences(of: "&nbsp;", with: " ")
+            .replacingOccurrences(of: "&amp;", with: "&")
+        return s.split(whereSeparator: { $0.isWhitespace || $0.isNewline }).joined(separator: " ")
+    }
+
+    private struct SplitMix64: RandomNumberGenerator {
+        var state: UInt64
+        mutating func next() -> UInt64 {
+            state &+= 0x9E37_79B9_7F4A_7C15
+            var z = state
+            z = (z ^ (z >> 30)) &* 0xBF58_476D_1CE4_E5B9
+            z = (z ^ (z >> 27)) &* 0x94D0_49BB_1331_11EB
+            return z ^ (z >> 31)
+        }
+    }
+
+    private static let trickyLines: [String] = [
+        "",
+        "plain",
+        "<i>Line one</i>\nline two",
+        "<>x",
+        "<><>",
+        "a<>b<>c",
+        "<a<b>c>",
+        "<<a>>",
+        "a<b",
+        "a>b",
+        "><",
+        "a<b>c<d",
+        "<b>x<",
+        "<",
+        ">",
+        "<i>open only",
+        "close only</i>",
+        "<c.yellow><i>nested</i></c>",
+        "&lt;i&gt;escaped&lt;/i&gt;",
+        "&lt;<b>&gt;",
+        "&amp;lt;",
+        "&<i>lt;</i>",
+        "a&nbsp;&nbsp;b",
+        "&nbsp<b>;</b>",
+        "<v Roger>Hi &amp; bye",
+        "{\\an8}<i>top</i>\\Nnext",
+        "{<b>}x",
+        "<{b}>x",
+        "<\u{0301}b>x",
+        "<b\u{0600}>x>",
+        "\u{0600}<b>x",
+        "e\u{0301}<b>\u{0301}x",
+        "x<b>\u{0301}y>",
+        "\u{1F1FA}<b>\u{1F1F8}\u{1F1EC}<i>\u{1F1E7}",
+        "\u{1F468}\u{200D}<b>\u{1F469}",
+        "\u{1100}<b>\u{1161}",
+        "\r<b>\nx",
+        "\u{226E}b>x",
+        "a<b>\u{00A0}<i>c",
+        "  <b> spaced </b>  ",
+    ]
+
+    @Test("The forward strip matches the old tag-at-a-time strip on tricky lines")
+    func stripMatchesLegacyOnTrickyLines() {
+        for line in Self.trickyLines {
+            let got = RemoteHLSCueClock.normalize(line)
+            let want = legacyNormalize(line)
+            #expect(got == want, "line: \(line.debugDescription)")
+            #expect(Array(got.unicodeScalars) == Array(want.unicodeScalars), "line: \(line.debugDescription)")
+        }
+    }
+
+    @Test("The forward strip matches the old tag-at-a-time strip on generated lines full of markup")
+    func stripMatchesLegacyOnGeneratedLines() {
+        let alphabet: [String] = ["<", ">", "<", ">", "<i>", "</i>", "<>", "&lt;", "&gt;", "&amp;", "&nbsp;",
+                                  "&", "lt;", "a", " ", "\n", "\r", "{", "}", "\\N", "\u{0301}", "\u{0600}",
+                                  "\u{200D}", "\u{1F468}", "\u{1F1FA}", "\u{1F1F8}", "\u{1100}", "\u{1161}",
+                                  "\u{226E}", "\u{00E9}"]
+        var rng = SplitMix64(state: 0x0616_C0E5)
+        for _ in 0..<6000 {
+            let length = Int.random(in: 0...30, using: &rng)
+            var line = ""
+            for _ in 0..<length { line += alphabet.randomElement(using: &rng)! }
+            let got = RemoteHLSCueClock.normalize(line)
+            let want = legacyNormalize(line)
+            #expect(got == want && Array(got.unicodeScalars) == Array(want.unicodeScalars),
+                    "line: \(line.debugDescription)")
+        }
+    }
+
+    @Test("A 64 KiB cue made of tags normalizes in linear time")
+    func tagHeavyCueIsLinear() {
+        let hostile = String(repeating: "<i>a</i>", count: 8 * 1024)
+        #expect(hostile.utf8.count == 64 * 1024)
+        // The fastest of a few runs, so one preemption on a loaded machine is not read as the cost.
+        // About 50 ms in a debug build here against 1.1 s for the rescanning strip; the bound leaves a
+        // loaded CI runner room without letting a quadratic strip back in.
+        var fastest = Duration.seconds(3600)
+        for _ in 0..<3 where fastest >= .milliseconds(400) {
+            let started = ContinuousClock.now
+            let normalized = RemoteHLSCueClock.normalize(hostile)
+            fastest = min(fastest, ContinuousClock.now - started)
+            #expect(normalized == String(repeating: "a", count: 8 * 1024))
+        }
+        #expect(fastest < .milliseconds(400), "took \(fastest)")
+    }
 }

From 9a92e8cfb8cff394b22c38f7bc8691541c15ac42 Mon Sep 17 00:00:00 2001
From: Quick104 <31828688+Quick104@users.noreply.github.com>
Date: Wed, 7 Oct 2026 21:59:37 -0400
Subject: [PATCH 349/359] docs(demuxer): say why a first seek's head sample
 runs outside its budget

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 Sources/AetherEngine/Demuxer/Demuxer.swift | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/Sources/AetherEngine/Demuxer/Demuxer.swift b/Sources/AetherEngine/Demuxer/Demuxer.swift
index fde9b153f..502205492 100644
--- a/Sources/AetherEngine/Demuxer/Demuxer.swift
+++ b/Sources/AetherEngine/Demuxer/Demuxer.swift
@@ -2323,6 +2323,11 @@ public final class Demuxer: @unchecked Sendable {
         guard let timestamp = Self.ticks(forSeconds: seconds, timeBase: timeBase) else { return false }
         // #409: the read position moves, so the repair drops its picture-order anchor and
         // re-anchors on the next keyframe (a seek always lands on one).
+        // A first seek's head sample runs outside `timeout` on purpose. Cut short, it either settles
+        // the verdict on a partial sample, and the session plays in decode order (#699), or leaves
+        // the seek unpositioned, and a resume that ignores the outcome then reads from the head. The
+        // sample has its own bounds instead: `sampleByteBudget`, `heldPacketCeiling` and the per-read
+        // stall timeout.
         noteCompositionRepairSeekLocked()
         // #268: a time-seekable source repositions itself instead of paying libavformat's byte-space
         // binary search, which on an index-less MPEG-TS is either wedged or broken (round 10 below) and

From 94fab68e2d8cfe3806c84b362a9dfb1c0efef57a Mon Sep 17 00:00:00 2001
From: Quick104 <31828688+Quick104@users.noreply.github.com>
Date: Wed, 7 Oct 2026 21:59:37 -0400
Subject: [PATCH 350/359] fix(aetherctl): redact origin URLs, resolve
 served-VTT URIs, linear smb-test pass

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 Scripts/hls-burst-origin.py            |  5 ++++
 Sources/aetherctl/PlaybackCmd.swift    | 37 +++++++++++++++++++-------
 Sources/aetherctl/SMBTestCommand.swift | 15 ++++++++++-
 docs/cli.md                            |  2 +-
 4 files changed, 47 insertions(+), 12 deletions(-)

diff --git a/Scripts/hls-burst-origin.py b/Scripts/hls-burst-origin.py
index 8cc0d439e..71d5ca245 100755
--- a/Scripts/hls-burst-origin.py
+++ b/Scripts/hls-burst-origin.py
@@ -47,6 +47,11 @@
 
 delays = [float(x) for x in args.delays.split(",")]
 count = len([f for f in os.listdir(args.dir) if f.startswith("seg") and f.endswith(".ts")])
+# Both index the segment list below, so a short folder would otherwise end in an IndexError.
+if not 0 <= args.prefill <= count:
+    ap.error("--prefill must be 0 to %d, the segments in %s (got %d)" % (count, args.dir, args.prefill))
+if args.freeze_at >= count:
+    ap.error("--freeze-at must be below %d, the segments in %s (got %d)" % (count, args.dir, args.freeze_at))
 durs = [float(x) for x in args.durs.split(",")] if args.durs else [args.dur]
 seg_dur = [durs[k % len(durs)] for k in range(count)]
 ends = []
diff --git a/Sources/aetherctl/PlaybackCmd.swift b/Sources/aetherctl/PlaybackCmd.swift
index fe5ec7c23..a3979a848 100644
--- a/Sources/aetherctl/PlaybackCmd.swift
+++ b/Sources/aetherctl/PlaybackCmd.swift
@@ -948,8 +948,9 @@ private func playSmokeTest(url: URL, seconds: Double, live: Bool, forceSoftware:
         if servedURL, let item = engine.currentAVPlayerItem, ObjectIdentifier(item) != servedURLItem,
            let asset = item.asset as? AVURLAsset {
             servedURLItem = ObjectIdentifier(item)
-            // Deliberately unredacted: the path token is the only way in, and this is a local harness.
-            FileHandle.standardOutput.write(Data("  SERVED \(asset.url.absoluteString)\n".utf8))
+            // The engine's loopback URL stays raw; on the remote route with no stand-in this is the
+            // origin URL itself, which is redacted like the banner.
+            FileHandle.standardOutput.write(Data("  SERVED \(printableURL(asset.url))\n".utf8))
         }
         // AE#441: the live rewind surfaces a host actually scales its strip on. Sampling them needed a
         // patched copy of this CLI before, which is how an over-promising lower bound stayed unseen.
@@ -1593,6 +1594,15 @@ extension AetherEngine {
     }
 }
 
+/// `url` for stdout. The engine's loopback address prints raw, because its path token is the only way
+/// in and this is a local harness; anything else is an origin that can carry a credential, so it is
+/// redacted the way the banner is.
+private func printableURL(_ url: URL) -> String {
+    let host = url.host?.lowercased()
+    let loopback = host == "127.0.0.1" || host == "localhost" || host == "::1"
+    return loopback ? url.absoluteString : EngineLog.redacted(url.absoluteString)
+}
+
 @MainActor
 private func reportServedVTT(_ engine: AetherEngine, _ label: String, around playhead: Double,
                              sessionStart: Double) async {
@@ -1607,7 +1617,7 @@ private func reportServedVTT(_ engine: AetherEngine, _ label: String, around pla
         return String(data: data, encoding: .utf8)
     }
     guard let masterBody = await get(master) else {
-        print("  VTT \(label): master unreachable at \(master.absoluteString)")
+        print("  VTT \(label): master unreachable at \(printableURL(master))")
         return
     }
     // The rendition AVPlayer is on, named by the legible selection so the harness follows the same
@@ -1633,22 +1643,29 @@ private func reportServedVTT(_ engine: AetherEngine, _ label: String, around pla
         print("  VTT \(label): no SUBTITLES rendition in the master")
         return
     }
-    guard let media = await get(master.deletingLastPathComponent().appendingPathComponent(pick.uri)) else {
-        print("  VTT \(label): \(pick.uri) unreachable")
+    // Each URI resolves against the playlist that names it: an origin rendition kept on the
+    // nativeRemoteHLS bypass is absolute, and its segments sit next to it rather than the master.
+    let mediaURL = URL(string: pick.uri, relativeTo: master)?.absoluteURL
+    guard let mediaURL, let media = await get(mediaURL) else {
+        print("  VTT \(label): \(mediaURL.map(printableURL) ?? EngineLog.redacted(pick.uri)) unreachable")
         return
     }
     // Walk EXTINF rather than assuming a uniform grid. A source with irregular keyframes (scene cuts,
     // which is most real content) has segments of unequal length, and the reporter's log shows exactly
     // that: `planSource` and `sourceStart` 1.96 s apart on every segment. Dividing the playhead by a
     // nominal 4 s picked nothing there, and a harness that checks zero segments reports a clean run.
-    var offsets: [(name: String, start: Double)] = []
+    var offsets: [(name: String, url: URL, start: Double)] = []
     var acc = 0.0
     var pending: Double?
     for line in media.split(separator: "\n", omittingEmptySubsequences: false) {
         if line.hasPrefix("#EXTINF:") {
             pending = Double(line.dropFirst(8).split(separator: ",").first ?? "") ?? 0
-        } else if line.hasSuffix(".vtt") {
-            offsets.append((String(line), acc))
+        } else if !line.isEmpty, !line.hasPrefix("#"),
+                  let url = URL(string: String(line), relativeTo: mediaURL)?.absoluteURL,
+                  url.pathExtension == "vtt" {
+            // The extension is read off the path so a query string does not hide it, and the name
+            // printed is the file name alone, so that query (which can carry a token) stays out.
+            offsets.append((url.lastPathComponent, url, acc))
             acc += pending ?? 0
             pending = nil
         }
@@ -1661,9 +1678,9 @@ private func reportServedVTT(_ engine: AetherEngine, _ label: String, around pla
     let startIndex = offsets.lastIndex(where: { $0.start <= relative }) ?? 0
     var checked = 0, nonEmpty = 0, cues = 0, misplaced = 0
     var firstMismatch: String?
-    for (name, start) in offsets[startIndex...] where checked < 8 {
+    for (name, url, start) in offsets[startIndex...] where checked < 8 {
         checked += 1
-        guard let body = await get(master.deletingLastPathComponent().appendingPathComponent(name)) else { continue }
+        guard let body = await get(url) else { continue }
         // A cue is a timestamp line plus text under it; counting "-->" counts cues without parsing.
         let c = body.components(separatedBy: "-->").count - 1
         cues += c
diff --git a/Sources/aetherctl/SMBTestCommand.swift b/Sources/aetherctl/SMBTestCommand.swift
index a54c0c0e5..1d8d8b748 100644
--- a/Sources/aetherctl/SMBTestCommand.swift
+++ b/Sources/aetherctl/SMBTestCommand.swift
@@ -37,6 +37,12 @@ private func smbTestRun(_ args: [String]) async -> Int32 {
             }
         }
 
+        // Probe indices by offset, walked with a cursor, so the timed pass below visits only the probes
+        // near each chunk instead of every probe per chunk. `probes` keeps its random order for the
+        // seek pass.
+        let byOffset = probes.indices.sorted { probes[$0].offset < probes[$1].offset }
+        var cursor = 0
+
         let chunk = 1 << 20 // 1 MiB sequential read
         var buf = [UInt8](repeating: 0, count: chunk)
         var readBytes: Int64 = 0
@@ -46,7 +52,14 @@ private func smbTestRun(_ args: [String]) async -> Int32 {
             let n = buf.withUnsafeMutableBufferPointer { reader.read($0.baseAddress, size: Int32(chunk)) }
             if n <= 0 { break }
             let chunkEnd = readBytes + Int64(n)
-            for i in probes.indices {
+            // Skip probes that ended before this chunk; one that crosses into it stays for its tail.
+            while cursor < byOffset.count {
+                let probe = probes[byOffset[cursor]]
+                guard probe.offset + Int64(probe.length) <= readBytes else { break }
+                cursor += 1
+            }
+            for i in byOffset[cursor...] {
+                if probes[i].offset >= chunkEnd { break }
                 let lo = max(probes[i].offset, readBytes)
                 let hi = min(probes[i].offset + Int64(probes[i].length), chunkEnd)
                 guard lo < hi else { continue }
diff --git a/docs/cli.md b/docs/cli.md
index f281dc9a2..0d8b96a5a 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -147,7 +147,7 @@ load and `playing` at the roll (AE#440).
 
 `--subs <codec-or-lang>` matches against the track's libavcodec name or language and logs every overlay cue and cue trim as it lands. `--host-calls` replays host post-load behavior against the fresh session: `play`, `extractor` (`makeFrameExtractor`), `setrate` (`setRate(1.0)`), `pausestart` (Sodalite#104 round 4: `pause()` the instant load returns, before any frame exists, and `play()` at t=8; the shape of a host that holds a fresh load paused, and a software session used to answer it with eight ticks of `enq=+0 status=unknown r4d=n`, a black picture under a paused clock; now the `[SWHost] #104` lines show the first frame presented at a stopped clock and `startup 8/8 presenting` arrives while paused), `ratehold` (set 1.5, pause at tick 3, resume at tick 5, then read the rate back off the transport itself: the #436 drill, and it fails the run if the resume came back at 1.0), `reloadlive` (reload the URL on the live path when the probe flags it live, the AetherPlayer Open URL flow), `reloadnext` (a host's episode seam: the same URL loaded again at t=4 on the still-playing engine with no `stop()` in between, so the native host is reused, and every published `state` printed as `STATE <state> t=<s>`; the second load must go `loading`, `playing` with no `paused` between them, which it did not while the reused host still carried the outgoing item's `.playing` status and every host raised its transport over the next episode), `seekback` (rewind 20 s into the DVR window at t=15, return to the live edge at t=30), `overlapseek` (the #292 seek-window drills below), `pausehold` (Sodalite#104: pause at t=10 and HOLD until ten seconds before the end, printing the playhead, the edge and the resident depth every second, which is how a session paused for longer than its own DVR window is measured without waiting out a real one: pair it with `--dvr-window 30` and `--seconds 90` and the ninety minute question becomes a ninety second run), `still` (#544: asks for a scrub still at three aims, 20 s behind the playhead at t=15, 5 s behind at t=20 and at the edge at t=25, writing each to `aetherctl-still-<tick>.png` in aetherctl's private per-user temporary directory (the path is printed) and reporting hit or MISS with the decode time; pair it with `--sw --dvr-window N`, where the picture comes out of the DVR packet ring rather than a segment cache, and read the FILE as well as the count, because the bundled seed burns its own second into the frame so a still asked for 14.85 s showing `14` is the verdict that it decoded the right moment and not merely an image; exit 6 when nothing hit, 5 when the session ended before the first aim; on a VOD session (AE#605) the three aims are 10.5 s behind the playhead, 4.5 s ahead of it and 600 s past it, through `scrubThumbnail`, and the third is EXPECTED to miss, because a frame the cache does not hold yet must not be answered with the one before it: `--sw` against an HTTP source is the software packet-cache case, and the testsrc fixture's counter in the PNG is the verdict that the still decoded to the target rather than snapping to its keyframe), `stallclock` (AE#549: stop the master clock at t=4 behind the host's back, the way an interrupted audio session does, then call a plain `play()` at t=7 and read whether the playhead moves again; the interruption itself cannot be staged on macOS, its outcome can, and without the `RendererClockResume` branch the run ends with the clock standing exactly where the stall left it, which is the field log's shape; the drill drives DEBUG-only engine hooks, so a Release `aetherctl` prints a notice and ends inconclusive, build it with `swift build --product aetherctl`), `pausereload`, `playreload` and `extplayreload` (#623: force the #93/#65 stage-2 item reload at t=10, on a session paused at t=6, on one left playing, and on one paused through the engine at t=6 and resumed at t=8 straight on the `AVPlayer` the way AVKit's transport does, which leaves the engine's intent reading paused while the player runs; the run fails with exit 4 if the clock moves after the paused reload or stands still after either playing one, and before #623 `pausereload` ended `+7.20 s, state=playing`), and `pauseseek` (pause at t=12, seek at t=15 while paused, resume at t=20; with `--sw` the five paused ticks between landing and resume show what the `[SWDiag]` line reports while the pump is parked and has not heard of the seek, the AE#479 shape); this is how the pre-arming `setRate` wedge was isolated.
 
-`--served-url` prints `SERVED <url>` whenever the session mounts a native item, with the loopback path token in clear. Every other line redacts it, which is right for a log and leaves no way to look at what was actually served. With the URL, `init.mp4` is one `curl` away, and the fMP4 segments are already on disk under `$TMPDIR/aether-segments/<session>/seg-N-M.m4s`: `cat init.mp4 seg-26-27.m4s > s.mp4` is a file `ffprobe -show_packets` reads, which is how AE#684 measured the sound against the picture in the bytes rather than in the log. Fetch the init segment only: a second client asking for the playlist or for segments is a consumer the session then accounts for.
+`--served-url` prints `SERVED <url>` whenever the session mounts a native item, with the loopback path token in clear. On the remote route with no loopback stand-in the item plays the origin URL itself, which is redacted like any other line. Every other line redacts the token, which is right for a log and leaves no way to look at what was actually served. With the URL, `init.mp4` is one `curl` away, and the fMP4 segments are already on disk under `$TMPDIR/aether-segments/<session>/seg-N-M.m4s`: `cat init.mp4 seg-26-27.m4s > s.mp4` is a file `ffprobe -show_packets` reads, which is how AE#684 measured the sound against the picture in the bytes rather than in the log. Fetch the init segment only: a second client asking for the playlist or for segments is a consumer the session then accounts for.
 
 `--seek-every N` seeks once every N ticks past tick 10, walking `--seek-pattern <abs,abs,...>` if one is given (a short backward hop otherwise), and `--seek-count K` stops after K seeks so a run can be a BURST and then play. Both halves are needed for anything about what a seek sequence leaves behind: the burst puts the store in the state under test, and only the playing half shows what the overlay carries through it. That pairing is what made AE#362's second mechanism reproducible (a hole between a restarted pump and the island the previous run left ahead of it, decoded across and then never re-read).
 

From d45af9e38ee79543a3c43e91e3ecaf48a5ae2441 Mon Sep 17 00:00:00 2001
From: Quick104 <31828688+Quick104@users.noreply.github.com>
Date: Wed, 7 Oct 2026 21:59:38 -0400
Subject: [PATCH 351/359] test: release parked readers on timeout, drop the
 Task.yield ordering, lock two fakes

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .../AbortedReadIsNotEndOfFileTests.swift      |  3 ++
 .../DemuxerStreamLifetimeTests.swift          |  6 ++++
 .../HLSLocalServerSlowPeerTests.swift         | 12 ++++----
 .../Issue684JoinBoundSealTests.swift          | 20 +++++++++++--
 .../LiveRecordingTeardownTests.swift          | 29 +++++++++++++++----
 .../StoppedPumpInFlightReadTests.swift        |  3 ++
 6 files changed, 60 insertions(+), 13 deletions(-)

diff --git a/Tests/AetherEngineTests/AbortedReadIsNotEndOfFileTests.swift b/Tests/AetherEngineTests/AbortedReadIsNotEndOfFileTests.swift
index af59ad4a3..c7f96a227 100644
--- a/Tests/AetherEngineTests/AbortedReadIsNotEndOfFileTests.swift
+++ b/Tests/AetherEngineTests/AbortedReadIsNotEndOfFileTests.swift
@@ -115,6 +115,9 @@ struct AbortedReadIsNotEndOfFileTests {
         let demuxer = Demuxer()
         try demuxer.open(reader: reader, formatHint: "matroska")
         defer { demuxer.close() }
+        // Runs before the close: a wait the time limit cancels must not leave the parked read
+        // holding the access lock that close() waits on.
+        defer { reader.release() }
         reader.arm(blockAt: Self.parkOffset)
 
         let outcome = ReadOutcome()
diff --git a/Tests/AetherEngineTests/DemuxerStreamLifetimeTests.swift b/Tests/AetherEngineTests/DemuxerStreamLifetimeTests.swift
index f1bb1ffb4..12659d5ae 100644
--- a/Tests/AetherEngineTests/DemuxerStreamLifetimeTests.swift
+++ b/Tests/AetherEngineTests/DemuxerStreamLifetimeTests.swift
@@ -49,6 +49,9 @@ struct DemuxerStreamLifetimeTests {
         let closed = Flag()
         let seenInsideTheBody = Seen()
         let release = DispatchSemaphore(value: 0)
+        // A wait the time limit cancels skips the signal below; this one lets the caller and the
+        // close behind it finish anyway. An extra signal is harmless: nothing waits twice.
+        defer { release.signal() }
         Thread.detachNewThread {
             _ = demuxer.withStream(at: MultiSubtitleContainerFixture.videoStreamIndex) { stream in
                 entered.set()
@@ -103,6 +106,9 @@ struct DemuxerStreamLifetimeTests {
         // parked on a slow origin leaves the lock in.
         let holding = Flag()
         let readReleased = DispatchSemaphore(value: 0)
+        // Runs before the close: a wait the time limit cancels must not leave the read holding the
+        // access lock that close() waits on.
+        defer { readReleased.signal() }
         let readFinished = Flag()
         Thread.detachNewThread {
             _ = try? demuxer.readPacket(isCurrent: {
diff --git a/Tests/AetherEngineTests/HLSLocalServerSlowPeerTests.swift b/Tests/AetherEngineTests/HLSLocalServerSlowPeerTests.swift
index d3602371b..06cdf8746 100644
--- a/Tests/AetherEngineTests/HLSLocalServerSlowPeerTests.swift
+++ b/Tests/AetherEngineTests/HLSLocalServerSlowPeerTests.swift
@@ -219,17 +219,19 @@ private final class Trickle: @unchecked Sendable {
         Thread.detachNewThread { [self] in
             let head = Array("GET / HTTP/1.1\r\nHost: x\r\nX-Pad: \(String(repeating: "a", count: 400))\r\n\r\n".utf8)
             for byte in head {
-                if isStopped { return }
-                var one = byte
-                if send(fd, &one, 1, 0) != 1 { return }
+                if !sendUnlessStopped(byte, fd: fd) { return }
                 Thread.sleep(forTimeInterval: 0.2)
             }
         }
     }
 
-    private var isStopped: Bool {
+    /// The check and the send hold the lock together, so once `stop()` returns no send is in flight
+    /// and the caller's `close(fd)` cannot let a reused descriptor receive a stray byte.
+    private func sendUnlessStopped(_ byte: UInt8, fd: Int32) -> Bool {
         lock.lock(); defer { lock.unlock() }
-        return stopped
+        if stopped { return false }
+        var one = byte
+        return send(fd, &one, 1, 0) == 1
     }
 
     func stop() {
diff --git a/Tests/AetherEngineTests/Issue684JoinBoundSealTests.swift b/Tests/AetherEngineTests/Issue684JoinBoundSealTests.swift
index ae925c4f8..882619122 100644
--- a/Tests/AetherEngineTests/Issue684JoinBoundSealTests.swift
+++ b/Tests/AetherEngineTests/Issue684JoinBoundSealTests.swift
@@ -14,10 +14,24 @@
 import XCTest
 @testable import AetherEngine
 
+/// Locked because a test flips `joinSpent` from another queue while the provider reads it.
 private final class JoinedUpstream: @unchecked Sendable {
-    var segmentDuration: Double?
-    var joinBacklog: Double?
-    var joinSpent: Bool?
+    private let lock = NSLock()
+    private var _segmentDuration: Double?
+    private var _joinBacklog: Double?
+    private var _joinSpent: Bool?
+    var segmentDuration: Double? {
+        get { lock.withLock { _segmentDuration } }
+        set { lock.withLock { _segmentDuration = newValue } }
+    }
+    var joinBacklog: Double? {
+        get { lock.withLock { _joinBacklog } }
+        set { lock.withLock { _joinBacklog = newValue } }
+    }
+    var joinSpent: Bool? {
+        get { lock.withLock { _joinSpent } }
+        set { lock.withLock { _joinSpent = newValue } }
+    }
 }
 
 final class Issue684JoinBoundSealTests: XCTestCase {
diff --git a/Tests/AetherEngineTests/LiveRecordingTeardownTests.swift b/Tests/AetherEngineTests/LiveRecordingTeardownTests.swift
index db1b01803..cb85a7042 100644
--- a/Tests/AetherEngineTests/LiveRecordingTeardownTests.swift
+++ b/Tests/AetherEngineTests/LiveRecordingTeardownTests.swift
@@ -53,6 +53,8 @@ struct LiveRecordingTeardownTests {
         try engine._testStartRecordingWithStubHost(to: url, host: host, ceilingBytes: 4096)
         let writer = try #require(engine.activeRecording)
         let gate = Latch()
+        // A cancelled wait below skips the open; the held writer must not outlive the test.
+        defer { gate.open() }
         writer.beforeWriteForTesting = { gate.wait() }
 
         // The first packet enters the held drain, the second breaks the ceiling: the demux thread's
@@ -96,6 +98,23 @@ struct LiveRecordingTeardownTests {
         return release
     }
 
+    @MainActor private final class Reached { var value = false }
+
+    /// Starts a recording and returns once the start is parked in its `recordingFinish` wait.
+    /// `startRecording` takes its snapshots and reaches that wait without suspending, so a task that
+    /// has entered it, seen from the main actor, is already waiting. `Task.yield()` would leave the
+    /// order to the executor.
+    private func startParkedInTheWait(_ engine: AetherEngine, to url: URL) async throws
+        -> Task<Void, any Error> {
+        let entered = Reached()
+        let starter = Task { @MainActor in
+            entered.value = true
+            try await engine.startRecording(to: url)
+        }
+        try await waitFor { entered.value }
+        return starter
+    }
+
     @Test("a start that a stop overtook while it waited does not begin recording")
     func stopDuringTheStartsWaitCancelsIt() async throws {
         let engine = try AetherEngine()
@@ -103,10 +122,11 @@ struct LiveRecordingTeardownTests {
         let release = holdPreviousFinish(engine)
 
         let url = tempURL()
-        let starter = Task { @MainActor in try await engine.startRecording(to: url) }
-        await Task.yield()
+        let starter = try await startParkedInTheWait(engine, to: url)
+        let serial = engine.recordingStopSerial
         let stopper = Task { @MainActor in await engine.stopRecording() }
-        await Task.yield()
+        // The stop has to be counted before the release lets the start look again.
+        try await waitFor { engine.recordingStopSerial != serial }
 
         release.yield(())
         release.finish()
@@ -126,8 +146,7 @@ struct LiveRecordingTeardownTests {
         let release = holdPreviousFinish(engine)
 
         let url = tempURL()
-        let starter = Task { @MainActor in try await engine.startRecording(to: url) }
-        await Task.yield()
+        let starter = try await startParkedInTheWait(engine, to: url)
         engine.loadGeneration &+= 1
 
         release.yield(())
diff --git a/Tests/AetherEngineTests/StoppedPumpInFlightReadTests.swift b/Tests/AetherEngineTests/StoppedPumpInFlightReadTests.swift
index b001b8c1e..096cdd124 100644
--- a/Tests/AetherEngineTests/StoppedPumpInFlightReadTests.swift
+++ b/Tests/AetherEngineTests/StoppedPumpInFlightReadTests.swift
@@ -85,6 +85,9 @@ struct StoppedPumpInFlightReadTests {
         let demuxer = Demuxer()
         try demuxer.open(reader: reader, formatHint: "matroska")
         defer { demuxer.close() }
+        // Runs before the close: a wait the time limit cancels must not leave the parked read
+        // holding the access lock that close() waits on.
+        defer { reader.release() }
         reader.arm(blockAt: Self.parkOffset)
 
         let videoIndex = demuxer.videoStreamIndex

From 580377004d3396cabed5f6743c27a7aaaa3eda49 Mon Sep 17 00:00:00 2001
From: Quick104 <31828688+Quick104@users.noreply.github.com>
Date: Wed, 7 Oct 2026 21:59:38 -0400
Subject: [PATCH 352/359] docs(changelog): fixes from the review of the
 upstream code

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 31f949c01..d763c3cef 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -38,6 +38,16 @@ the public-API contract.
 - An external ASS sidecar the host draws itself (`preserveASSMarkup`) on the `nativeRemoteHLS` bypass keeps its plain rendition selected behind a suppressing legible output instead of deselecting it. AE#616 measures `sourceTime` off the selected injected rendition, so the deselect left the clock a styled-ASS overlay draws from on item time, 1 to 8 s ahead of the picture after a seek on a transcode restarted at an earlier keyframe. The hidden rendition is selected only once its whole-program WebVTT has been extracted and playback is running, because AVPlayer fetches and buffers a selected rendition and AE#616 measures only presented lines. Turning subtitles off takes it down immediately.
 - TrueHD Atmos rendered to APAC reports a decoder that produces nothing (`.audioBridgeProducedNoOutput` on VOD), as the channel bridges do since AE#641, instead of playing the picture over silence.
 - Playlist preflight through a refreshable `HTTPRequestAuthorization` keeps the 2 MB playlist cap the static-header preflight has (audit NAT-5), and relayed fetches use upstream's per-fetch pending cap (audit NET-107) in place of the fork's high-water wait.
+- A 206 whose `Content-Range` total is zero or negative no longer crashes an HTTP source as it opens. `Int64` parses a signed total, so `bytes 0-0/-9223372036854775808` reached `total - 1` with `Int64.min` and trapped.
+- Below 1x, or after a pause in the last quarter second, the audio-only host parks its clock when it reaches the last sample. It parked after the tail's length in wall time, which cut up to 0.125 s at 0.5x.
+- A delayed revive of a dead live producer is checked again when its restart is admitted, so a seek restart that began in between no longer gets the stale position queued behind it.
+- The I-frame payload cache refuses a payload larger than its byte limit instead of holding it over the cap. The payload is still served.
+- Closing the DVR packet ring releases the writer's open chunk instead of keeping it until the ring is freed.
+- Remote-HLS cue normalization strips markup in one pass. Removing one tag at a time and searching again from the start took seconds on the main actor for a crafted 64 KiB cue.
+- Log redaction covers an Xtream password containing `,` `'` or `)`, which used to end the path segment early, and a registered secret that starts a credential name such as `token` no longer hides the value after it.
+- `aetherctl`: `--served-url` and the served-VTT readout redact origin URLs (loopback URLs still print in full), the readout resolves rendition and segment URIs against the playlist that lists them, and `smb-test`'s sequential pass no longer scans every probe for every chunk inside its timed window.
+- `Scripts/hls-burst-origin.py` rejects a `--prefill` or `--freeze-at` that the folder's segments cannot satisfy instead of failing with an `IndexError`.
+- Seven upstream tests no longer turn a timeout into a hang, rely on main-executor ordering after `Task.yield()`, race a closed socket, or write a fake's state from another queue without a lock.
 - Native subtitle renditions wait for complete extraction instead of caching a partial whole-track response. While extraction is pending, the local server returns a retryable HTTP 503.
 - External subtitles can declare `nativeTimelineOffsetSeconds` for media reanchored upstream. Native HLS/PiP/AirPlay renditions use the adjusted timeline while host overlay cues retain source timestamps.
 - Video routing consults the AV1 hardware decoder only for AV1 sources, avoiding supplemental decoder registration on unrelated playback starts.

From 4ebc8eb0d8bd98d1c7e7a820989ba318c874b3e7 Mon Sep 17 00:00:00 2001
From: Quick104 <31828688+Quick104@users.noreply.github.com>
Date: Wed, 7 Oct 2026 22:09:03 -0400
Subject: [PATCH 353/359] fix(reload): refuse a shared-output role change in a
 session correction

`sharedOutputRole` was listed in `loadIdentityFields`, but `refusedFields`
never compared it, so `reloadAtCurrentPosition(applying:)` rebuilt a running
multiview engine under the other role instead of throwing
`loadIdentityNotCorrectable`. A new test flips every identity field alone
and expects exactly that field refused, and fails when the list names a
field the comparison does not cover.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .../AetherEngine+ReloadWithOptions.swift      |  2 ++
 .../Issue460ReloadWithOptionsTests.swift      | 21 +++++++++++++++++++
 2 files changed, 23 insertions(+)

diff --git a/Sources/AetherEngine/AetherEngine+ReloadWithOptions.swift b/Sources/AetherEngine/AetherEngine+ReloadWithOptions.swift
index 51d82c368..9b8e1958e 100644
--- a/Sources/AetherEngine/AetherEngine+ReloadWithOptions.swift
+++ b/Sources/AetherEngine/AetherEngine+ReloadWithOptions.swift
@@ -315,6 +315,8 @@ enum SessionOptionCorrection {
         if proposed.heldSourceConnection != current.heldSourceConnection {
             refused.append("heldSourceConnection")
         }
+        // The role decides which engine drives the panel and owns Now Playing, joined once at load.
+        if proposed.sharedOutputRole != current.sharedOutputRole { refused.append("sharedOutputRole") }
         return refused
     }
 
diff --git a/Tests/AetherEngineTests/Issue460ReloadWithOptionsTests.swift b/Tests/AetherEngineTests/Issue460ReloadWithOptionsTests.swift
index 81403ecf4..cf0746688 100644
--- a/Tests/AetherEngineTests/Issue460ReloadWithOptionsTests.swift
+++ b/Tests/AetherEngineTests/Issue460ReloadWithOptionsTests.swift
@@ -17,6 +17,27 @@ struct Issue460SessionOptionCorrectionTests {
         }
     }
 
+    /// Listing a field as identity refuses nothing on its own: `refusedFields` compares each one by
+    /// hand, and `sharedOutputRole` was listed without a comparison.
+    @Test("every identity field, flipped alone, is refused by name")
+    func everyIdentityFieldIsRefused() {
+        let base = LoadOptions()
+        let flips: [String: (inout LoadOptions) -> Void] = [
+            "isLive": { $0.isLive.toggle() },
+            "audioOnly": { $0.audioOnly.toggle() },
+            "nativeRemoteHLS": { $0.nativeRemoteHLS.toggle() },
+            "sequentialOrigin": { $0.sequentialOrigin.toggle() },
+            "heldSourceConnection": { $0.heldSourceConnection.toggle() },
+            "sharedOutputRole": { $0.sharedOutputRole = $0.sharedOutputRole == .primary ? .secondary : .primary },
+        ]
+        #expect(Set(flips.keys) == Set(SessionOptionCorrection.loadIdentityFields))
+        for (field, flip) in flips {
+            var proposed = base
+            flip(&proposed)
+            #expect(SessionOptionCorrection.refusedFields(from: base, to: proposed) == [field])
+        }
+    }
+
     /// The inventory guard. A field added to `LoadOptions` is correctable by default (it falls
     /// through `refusedFields`), which is right for a tuning lever and wrong for one that names the
     /// session, so adding one has to be a decision. This fails until someone makes it.

From bf23457c14b33c1715aaae239bc714bc7e355466 Mon Sep 17 00:00:00 2001
From: Quick104 <31828688+Quick104@users.noreply.github.com>
Date: Wed, 7 Oct 2026 22:09:17 -0400
Subject: [PATCH 354/359] docs(changelog): shared-output role refusal

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d763c3cef..b0d895650 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -47,6 +47,7 @@ the public-API contract.
 - Log redaction covers an Xtream password containing `,` `'` or `)`, which used to end the path segment early, and a registered secret that starts a credential name such as `token` no longer hides the value after it.
 - `aetherctl`: `--served-url` and the served-VTT readout redact origin URLs (loopback URLs still print in full), the readout resolves rendition and segment URIs against the playlist that lists them, and `smb-test`'s sequential pass no longer scans every probe for every chunk inside its timed window.
 - `Scripts/hls-burst-origin.py` rejects a `--prefill` or `--freeze-at` that the folder's segments cannot satisfy instead of failing with an `IndexError`.
+- `reloadAtCurrentPosition(applying:)` refuses a `sharedOutputRole` change with `loadIdentityNotCorrectable`. The role was listed as load identity but never compared, so a correction rebuilt a multiview engine under the other role.
 - Seven upstream tests no longer turn a timeout into a hang, rely on main-executor ordering after `Task.yield()`, race a closed socket, or write a fake's state from another queue without a lock.
 - Native subtitle renditions wait for complete extraction instead of caching a partial whole-track response. While extraction is pending, the local server returns a retryable HTTP 503.
 - External subtitles can declare `nativeTimelineOffsetSeconds` for media reanchored upstream. Native HLS/PiP/AirPlay renditions use the adjusted timeline while host overlay cues retain source timestamps.

From 71234f57d2433d58ea9991227bcf1abd894c297d Mon Sep 17 00:00:00 2001
From: Quick104 <31828688+Quick104@users.noreply.github.com>
Date: Wed, 7 Oct 2026 22:16:46 -0400
Subject: [PATCH 355/359] fix(aetherctl): print only the engine's own loopback
 URLs in full

printableURL treated every loopback host as the engine, so a nativeRemoteHLS
origin on localhost printed its query credential in SERVED. An engine server
is a loopback address on a port the source does not use; the rest, a
localhost origin and its absolute renditions included, is redacted.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 Sources/aetherctl/PlaybackCmd.swift | 40 +++++++++++++++++++----------
 1 file changed, 27 insertions(+), 13 deletions(-)

diff --git a/Sources/aetherctl/PlaybackCmd.swift b/Sources/aetherctl/PlaybackCmd.swift
index a3979a848..aa7590fd6 100644
--- a/Sources/aetherctl/PlaybackCmd.swift
+++ b/Sources/aetherctl/PlaybackCmd.swift
@@ -950,7 +950,7 @@ private func playSmokeTest(url: URL, seconds: Double, live: Bool, forceSoftware:
             servedURLItem = ObjectIdentifier(item)
             // The engine's loopback URL stays raw; on the remote route with no stand-in this is the
             // origin URL itself, which is redacted like the banner.
-            FileHandle.standardOutput.write(Data("  SERVED \(printableURL(asset.url))\n".utf8))
+            FileHandle.standardOutput.write(Data("  SERVED \(printableURL(asset.url, source: url))\n".utf8))
         }
         // AE#441: the live rewind surfaces a host actually scales its strip on. Sampling them needed a
         // patched copy of this CLI before, which is how an over-promising lower bound stayed unseen.
@@ -1307,7 +1307,8 @@ private func playSmokeTest(url: URL, seconds: Double, live: Bool, forceSoftware:
         }
         if let t = nativeRenderTick, tick == t + 2 {
             await reportLegibleSelection(engine, "after render on")
-            await reportServedVTT(engine, "after render on", around: engine.currentTime, sessionStart: startPosition ?? 0)
+            await reportServedVTT(engine, "after render on", around: engine.currentTime, sessionStart: startPosition ?? 0,
+                                  source: url)
         }
         if let subsOffTick, tick == subsOffTick {
             print("  HOSTCALL subtitles off")
@@ -1328,7 +1329,8 @@ private func playSmokeTest(url: URL, seconds: Double, live: Bool, forceSoftware:
         if let t = subsOffTick, tick == t + 1 { await reportLegibleSelection(engine, "after off") }
         if let t = subsOnTick, tick == t + 4 {
             await reportLegibleSelection(engine, "after on")
-            await reportServedVTT(engine, "after on", around: engine.currentTime, sessionStart: startPosition ?? 0)
+            await reportServedVTT(engine, "after on", around: engine.currentTime, sessionStart: startPosition ?? 0,
+                                  source: url)
         }
     }
 
@@ -1594,18 +1596,30 @@ extension AetherEngine {
     }
 }
 
-/// `url` for stdout. The engine's loopback address prints raw, because its path token is the only way
-/// in and this is a local harness; anything else is an origin that can carry a credential, so it is
-/// redacted the way the banner is.
-private func printableURL(_ url: URL) -> String {
-    let host = url.host?.lowercased()
-    let loopback = host == "127.0.0.1" || host == "localhost" || host == "::1"
-    return loopback ? url.absoluteString : EngineLog.redacted(url.absoluteString)
+/// `url` for stdout. The engine's own loopback servers print raw, because their path token is the only
+/// way in and this is a local harness; anything else, an origin on localhost included, can carry a
+/// credential, so it is redacted the way the banner is. An engine server is a loopback address on a
+/// port the source does not use.
+private func printableURL(_ url: URL, source: URL) -> String {
+    func isLoopback(_ u: URL) -> Bool {
+        let host = u.host?.lowercased()
+        return host == "127.0.0.1" || host == "localhost" || host == "::1"
+    }
+    func port(_ u: URL) -> Int? {
+        if let port = u.port { return port }
+        switch u.scheme {
+        case "https": return 443
+        case "http": return 80
+        default: return nil
+        }
+    }
+    let engineServed = isLoopback(url) && !(isLoopback(source) && port(url) == port(source))
+    return engineServed ? url.absoluteString : EngineLog.redacted(url.absoluteString)
 }
 
 @MainActor
 private func reportServedVTT(_ engine: AetherEngine, _ label: String, around playhead: Double,
-                             sessionStart: Double) async {
+                             sessionStart: Double, source: URL) async {
     guard let item = engine.currentAVPlayerItem,
           let asset = item.asset as? AVURLAsset else {
         print("  VTT \(label): no item")
@@ -1617,7 +1631,7 @@ private func reportServedVTT(_ engine: AetherEngine, _ label: String, around pla
         return String(data: data, encoding: .utf8)
     }
     guard let masterBody = await get(master) else {
-        print("  VTT \(label): master unreachable at \(printableURL(master))")
+        print("  VTT \(label): master unreachable at \(printableURL(master, source: source))")
         return
     }
     // The rendition AVPlayer is on, named by the legible selection so the harness follows the same
@@ -1647,7 +1661,7 @@ private func reportServedVTT(_ engine: AetherEngine, _ label: String, around pla
     // nativeRemoteHLS bypass is absolute, and its segments sit next to it rather than the master.
     let mediaURL = URL(string: pick.uri, relativeTo: master)?.absoluteURL
     guard let mediaURL, let media = await get(mediaURL) else {
-        print("  VTT \(label): \(mediaURL.map(printableURL) ?? EngineLog.redacted(pick.uri)) unreachable")
+        print("  VTT \(label): \(mediaURL.map { printableURL($0, source: source) } ?? EngineLog.redacted(pick.uri)) unreachable")
         return
     }
     // Walk EXTINF rather than assuming a uniform grid. A source with irregular keyframes (scene cuts,

From 7f5af614d371aa153145a17de76a38bae5db58e9 Mon Sep 17 00:00:00 2001
From: Quick104 <31828688+Quick104@users.noreply.github.com>
Date: Wed, 7 Oct 2026 22:16:46 -0400
Subject: [PATCH 356/359] test(audio): land the pause inside the end-of-media
 tail on a loaded runner

CI paused after the park instead of inside the 0.25 s tail, and a resume
after a host pause restarts a parked clock, so the test read 3.5 s on a 1 s
file. The tail now plays at 0.25x, about a second of wall time, and a run
that still misses it starts over. Without the fix the test still fails.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 ...Issue694AudioHostEndOfMediaParkTests.swift | 48 +++++++++++--------
 1 file changed, 28 insertions(+), 20 deletions(-)

diff --git a/Tests/AetherEngineTests/Issue694AudioHostEndOfMediaParkTests.swift b/Tests/AetherEngineTests/Issue694AudioHostEndOfMediaParkTests.swift
index 6eb88c7f4..ef5571358 100644
--- a/Tests/AetherEngineTests/Issue694AudioHostEndOfMediaParkTests.swift
+++ b/Tests/AetherEngineTests/Issue694AudioHostEndOfMediaParkTests.swift
@@ -80,28 +80,36 @@ struct Issue694AudioHostEndOfMediaParkTests {
     @MainActor
     @Test("a pause during the tail holds the park until the clock reaches the last sample")
     func pauseDuringTheTailDefersThePark() async throws {
-        let host = AudioPlaybackHost()
-        let demuxer = Demuxer()
-        try demuxer.open(reader: DataIOReader(data: makeWAV(seconds: 1)))
-        try await host.load(demuxer: demuxer, startPosition: nil, audioSourceStreamIndex: nil)
-        defer { host.stop() }
-        host.play()
+        // The playthrough wait releases up to 0.25 s of source before the end, and the pause has to
+        // land in that tail, before the park. At 0.25x the tail lasts about a second of wall time;
+        // a run a loaded machine still delays past it (the clock already parked on the last
+        // sample, which a resume would carry on from) starts over.
+        for _ in 0..<4 {
+            let host = AudioPlaybackHost()
+            let demuxer = Demuxer()
+            try demuxer.open(reader: DataIOReader(data: makeWAV(seconds: 1)))
+            try await host.load(demuxer: demuxer, startPosition: nil, audioSourceStreamIndex: nil)
+            defer { host.stop() }
+            host.setResumeRate(0.25)
+            host.play()
 
-        let deadline = Date().addingTimeInterval(8)
-        while !host.didReachEnd, Date() < deadline {
-            try await Task.sleep(nanoseconds: 10_000_000)
-        }
-        #expect(host.didReachEnd)
-        // The playthrough wait releases up to 0.25 s before the end; pause inside that tail and
-        // hold the pause past it.
-        host.pause()
-        try await Task.sleep(nanoseconds: 400_000_000)
-        host.play()
+            let deadline = Date().addingTimeInterval(16)
+            while !host.didReachEnd, Date() < deadline {
+                try await Task.sleep(nanoseconds: 10_000_000)
+            }
+            try #require(host.didReachEnd)
+            host.pause()
+            guard try #require(host.clockSecondsForTesting) < 0.99 else { continue }
+            try await Task.sleep(nanoseconds: 600_000_000)
+            host.play()
 
-        // A park that fired during the pause left nothing to stop the resumed clock.
-        try await waitForParkedClock(host, within: 2)
-        let first = try #require(host.clockSecondsForTesting)
-        #expect(abs(first - 1.0) < 0.02)
+            // A park that fired during the pause left nothing to stop the resumed clock.
+            try await waitForParkedClock(host, within: 4)
+            let first = try #require(host.clockSecondsForTesting)
+            #expect(abs(first - 1.0) < 0.02)
+            return
+        }
+        Issue.record("the pause never landed inside the tail in four runs")
     }
 
     @MainActor

From a01a6a72f064bde09f020ae2cbc44de4769c5478 Mon Sep 17 00:00:00 2001
From: Quick104 <31828688+Quick104@users.noreply.github.com>
Date: Wed, 7 Oct 2026 22:16:46 -0400
Subject: [PATCH 357/359] test(ring): release a parked writer when a wait is
 cancelled

The same deferred release the other parked-reader tests have, so a time-limit
cancel cannot leave the append thread and close() blocked.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 Tests/AetherEngineTests/PacketRingBufferChunkSpoolTests.swift | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Tests/AetherEngineTests/PacketRingBufferChunkSpoolTests.swift b/Tests/AetherEngineTests/PacketRingBufferChunkSpoolTests.swift
index 6b7ded536..abf7de958 100644
--- a/Tests/AetherEngineTests/PacketRingBufferChunkSpoolTests.swift
+++ b/Tests/AetherEngineTests/PacketRingBufferChunkSpoolTests.swift
@@ -497,6 +497,9 @@ struct PacketRingBufferChunkSpoolTests {
         // An append that fails after close() has begun leaves the tail behind if close() does not
         // wait it out.
         spy.parkNextWrite(failingWith: EIO)
+        // A wait the time limit cancels skips the release below; the parked writer, and a close()
+        // waiting on it, must not outlive the test. A second signal is harmless: nothing parks again.
+        defer { spy.release() }
         let appended = Counter()
         let closed = Counter()
         Thread {

From 0cc3bd8c72f0c3c5840ac4723a1a9ad40f22db9f Mon Sep 17 00:00:00 2001
From: Quick104 <31828688+Quick104@users.noreply.github.com>
Date: Wed, 7 Oct 2026 22:17:11 -0400
Subject: [PATCH 358/359] docs(changelog): aetherctl redacts a localhost origin
 too

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b0d895650..7df7ea50d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -45,7 +45,7 @@ the public-API contract.
 - Closing the DVR packet ring releases the writer's open chunk instead of keeping it until the ring is freed.
 - Remote-HLS cue normalization strips markup in one pass. Removing one tag at a time and searching again from the start took seconds on the main actor for a crafted 64 KiB cue.
 - Log redaction covers an Xtream password containing `,` `'` or `)`, which used to end the path segment early, and a registered secret that starts a credential name such as `token` no longer hides the value after it.
-- `aetherctl`: `--served-url` and the served-VTT readout redact origin URLs (loopback URLs still print in full), the readout resolves rendition and segment URIs against the playlist that lists them, and `smb-test`'s sequential pass no longer scans every probe for every chunk inside its timed window.
+- `aetherctl`: `--served-url` and the served-VTT readout redact origin URLs, a localhost origin included (the engine's own loopback URLs still print in full), the readout resolves rendition and segment URIs against the playlist that lists them, and `smb-test`'s sequential pass no longer scans every probe for every chunk inside its timed window.
 - `Scripts/hls-burst-origin.py` rejects a `--prefill` or `--freeze-at` that the folder's segments cannot satisfy instead of failing with an `IndexError`.
 - `reloadAtCurrentPosition(applying:)` refuses a `sharedOutputRole` change with `loadIdentityNotCorrectable`. The role was listed as load identity but never compared, so a correction rebuilt a multiview engine under the other role.
 - Seven upstream tests no longer turn a timeout into a hang, rely on main-executor ordering after `Task.yield()`, race a closed socket, or write a fake's state from another queue without a lock.

From 31047b0503ba1be1423a0061c73c01a3d8cf33b9 Mon Sep 17 00:00:00 2001
From: Quick104 <31828688+Quick104@users.noreply.github.com>
Date: Wed, 7 Oct 2026 22:19:02 -0400
Subject: [PATCH 359/359] fix(aetherctl): print in full only URLs on the
 mounted item's engine server

A different loopback port did not make a URL the engine's: a localhost origin\ncan list an absolute rendition on another localhost port. The engine endpoint\nis now the mounted item's URL when it is a loopback URL other than the source\n(the no-stand-in route mounts the source itself), and only URLs on that\nscheme, host and port print raw.\n\nCo-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 Sources/aetherctl/PlaybackCmd.swift | 40 ++++++++++++++---------------
 1 file changed, 19 insertions(+), 21 deletions(-)

diff --git a/Sources/aetherctl/PlaybackCmd.swift b/Sources/aetherctl/PlaybackCmd.swift
index aa7590fd6..61e3f4823 100644
--- a/Sources/aetherctl/PlaybackCmd.swift
+++ b/Sources/aetherctl/PlaybackCmd.swift
@@ -950,7 +950,8 @@ private func playSmokeTest(url: URL, seconds: Double, live: Bool, forceSoftware:
             servedURLItem = ObjectIdentifier(item)
             // The engine's loopback URL stays raw; on the remote route with no stand-in this is the
             // origin URL itself, which is redacted like the banner.
-            FileHandle.standardOutput.write(Data("  SERVED \(printableURL(asset.url, source: url))\n".utf8))
+            let engine = engineEndpoint(mounted: asset.url, source: url)
+            FileHandle.standardOutput.write(Data("  SERVED \(printableURL(asset.url, engine: engine))\n".utf8))
         }
         // AE#441: the live rewind surfaces a host actually scales its strip on. Sampling them needed a
         // patched copy of this CLI before, which is how an over-promising lower bound stayed unseen.
@@ -1596,25 +1597,21 @@ extension AetherEngine {
     }
 }
 
-/// `url` for stdout. The engine's own loopback servers print raw, because their path token is the only
+/// The engine server behind a mounted item, or nil. An item's URL is either the source itself (the
+/// remote route with no stand-in) or the engine's loopback stand-in, so a loopback URL that is not
+/// the source is the engine's.
+private func engineEndpoint(mounted: URL, source: URL) -> URL? {
+    let host = mounted.host?.lowercased()
+    guard mounted != source, host == "127.0.0.1" || host == "localhost" || host == "::1" else { return nil }
+    return mounted
+}
+
+/// `url` for stdout. A URL on the engine's own server prints raw, because its path token is the only
 /// way in and this is a local harness; anything else, an origin on localhost included, can carry a
-/// credential, so it is redacted the way the banner is. An engine server is a loopback address on a
-/// port the source does not use.
-private func printableURL(_ url: URL, source: URL) -> String {
-    func isLoopback(_ u: URL) -> Bool {
-        let host = u.host?.lowercased()
-        return host == "127.0.0.1" || host == "localhost" || host == "::1"
-    }
-    func port(_ u: URL) -> Int? {
-        if let port = u.port { return port }
-        switch u.scheme {
-        case "https": return 443
-        case "http": return 80
-        default: return nil
-        }
-    }
-    let engineServed = isLoopback(url) && !(isLoopback(source) && port(url) == port(source))
-    return engineServed ? url.absoluteString : EngineLog.redacted(url.absoluteString)
+/// credential, so it is redacted the way the banner is.
+private func printableURL(_ url: URL, engine: URL?) -> String {
+    let onEngine = engine.map { url.scheme == $0.scheme && url.host == $0.host && url.port == $0.port } ?? false
+    return onEngine ? url.absoluteString : EngineLog.redacted(url.absoluteString)
 }
 
 @MainActor
@@ -1626,12 +1623,13 @@ private func reportServedVTT(_ engine: AetherEngine, _ label: String, around pla
         return
     }
     let master = asset.url
+    let engine = engineEndpoint(mounted: master, source: source)
     func get(_ url: URL) async -> String? {
         guard let (data, _) = try? await URLSession.shared.data(from: url) else { return nil }
         return String(data: data, encoding: .utf8)
     }
     guard let masterBody = await get(master) else {
-        print("  VTT \(label): master unreachable at \(printableURL(master, source: source))")
+        print("  VTT \(label): master unreachable at \(printableURL(master, engine: engine))")
         return
     }
     // The rendition AVPlayer is on, named by the legible selection so the harness follows the same
@@ -1661,7 +1659,7 @@ private func reportServedVTT(_ engine: AetherEngine, _ label: String, around pla
     // nativeRemoteHLS bypass is absolute, and its segments sit next to it rather than the master.
     let mediaURL = URL(string: pick.uri, relativeTo: master)?.absoluteURL
     guard let mediaURL, let media = await get(mediaURL) else {
-        print("  VTT \(label): \(mediaURL.map { printableURL($0, source: source) } ?? EngineLog.redacted(pick.uri)) unreachable")
+        print("  VTT \(label): \(mediaURL.map { printableURL($0, engine: engine) } ?? EngineLog.redacted(pick.uri)) unreachable")
         return
     }
     // Walk EXTINF rather than assuming a uniform grid. A source with irregular keyframes (scene cuts,